Design Notes for dxaws-cloudfront

#

This document is the architecture/design reference for dxaws-cloudfront.

The goal is to keep the module contract stable while allowing the internals (planner comparisons, provider implementations, config shapes) to evolve.

Purpose and Scope

#

dxaws-cloudfront converges a single CloudFront distribution to a desired state.

MVP scope:

• One CloudFront distribution
• One S3 origin
• Origin Access Control (OAC)
• Optional aliases (CNAMEs)
• Optional ACM certificate (must be in us-east-1 for CloudFront)
• Default cache behavior (MVP subset)
• Optional SPA-friendly custom error responses
• Deterministic create/update/wait/destroy lifecycle

Non-goals (for now):

• Multiple origins / origin groups
• Multiple cache behaviors
• Cache policies / origin request policies
• Logging / realtime logs
• WAF / Shield configuration
• Lambda@Edge / CloudFront Functions

How this fits into dxaws

#

dxaws modules are primitive building blocks that expose stable, testable interfaces. Higher-level orchestration (e.g., dxaws-website, Step Functions, runbooks) composes primitives but should not reach into their internals.

This module is intended to be used by:

• dxaws-website (CloudFront distribution fronting an S3 website origin)
• DNS modules (Route53 alias record creation using distribution domain + hosted zone id)
• Runbooks / automation flows (idempotent apply + explicit outputs)

Declarative Convergence

#

This module follows a declarative convergence model.

Callers provide a Desired state. The module:

1. Discovers the Current state (minimal normalized snapshot)
2. Plans a list of Actions required to converge
3. Executes those Actions via a Provider
4. Waits when necessary for eventual consistency

Key properties:

• Idempotent: repeat runs converge to the same result
• Deterministic: planning is pure and does not call AWS
• Provider-isolated: AWS API details live in providers
• Stable contracts: models + provider protocol change cautiously

Module Layers

#

Models (stable contract)

#

models.py defines the stable data model:

• DistributionDesired (target state)
  • present: bool is the lifecycle switch
    • present=True => ensure distribution exists
    • present=False => ensure distribution is deleted (destroy)
• DistributionCurrent (observed state)
• Plan and Action (what will be done)
• DistributionResult (outputs)

Rule: Keep these models small, explicit, and backwards-compatible.

Planner (pure)

#

planner.py converts:

• (desired, current, oac_id) → Plan(actions=[...])

Planner rules:

• No AWS calls
• Deterministic config synthesis
• Compare using summarized fields only (avoid AWS response drift)

Destroy planning (present=False):

• If absent already → noop
• Else → DISABLE → WAIT_DEPLOYED → DELETE

Executor (boring)

#

executor.py is a thin action dispatcher:

• Executes actions in order
• Calls provider methods
• Avoids any planning decisions

Provider

#

Providers implement the AWS (or mock) behavior behind a stable protocol.

providers/base.py defines the provider contract.

providers/aws.py implements it using boto3/botocore.

Provider rules:

• AWS-only logic lives here
• Handle strict AWS request shapes (CloudFront is strict)
• Handle eventual consistency where required
  • notably disable/delete sequencing

Manager

#

manager.py is the orchestrator:

• get_current() discovery (by alias)
• plan() emits plan events
• apply() executes and waits
• execute() is the primary entry point
• destroy(desired) is a convenience wrapper that preserves aliases

Discovery Strategy

#

Discovery is currently alias-driven:

• get_current() attempts provider.find_distribution_by_alias(aliases[0])
• If found, pulls config + etag and normalizes into DistributionCurrent

Implications:

• Callers should provide aliases for deterministic discovery.
• In future, we can optionally support tag/comment-based discovery.

Naming and Idempotency

#

Stable comment

#

We use a stable comment (dxaws-cloudfront:<name>) to support deterministic config synthesis and optional discovery.

OAC name length

#

CloudFront enforces strict resource name limits.

We use truncate_with_hash() to generate stable, bounded OAC names.

Waiting and Eventual Consistency

#

CloudFront is eventually consistent.

We model waiting explicitly:

• WAIT_DEPLOYED action (planned for create/update and optionally wait-only)
• Manager-level wait for current.status != Deployed

Destroy requires a stricter sequence:

1. Disable distribution
2. Wait until:
   • status is Deployed
   • config shows Enabled=False
3. Delete distribution

The AWS provider is responsible for waiting until CloudFront reflects the disabled state before proceeding.

Outputs

#

DistributionResult includes:

• distribution id
• distribution domain name
• hosted zone id (constant) for Route53 alias record creation

Observability (o11y)

#

Manager emits structured events via dxaws_core.o11y.O11y:

• manager.plan.start / manager.plan.done
• manager.apply.start / manager.apply.progress / manager.apply.done
• manager.execute.done (outcome: noop/applied/failed)

These events are designed to be stable enough for:

• CLI output shaping
• runbook audit trails
• eventual EventBridge integration

Tests

#

We aim for three layers:

• Unit tests: planner comparisons, config shape synthesis
• Integration tests: manager + stub provider behavior
• Acceptance tests: real AWS (slow) for lifecycle correctness

Acceptance tests intentionally reuse persistent resources (e.g., origin bucket) so repeated runs are cheap and predictable.

Extension Guidelines

#

When extending this module:

• Prefer adding new optional fields to DistributionDesired
• Keep planner comparisons summarized and stable
• Extend the provider protocol only when necessary, and add tests
• Maintain backwards compatibility whenever possible

If a change would break existing callers, introduce a new optional field or a new action type instead of changing semantics.