Design Notes for dxaws-dns

This document captures the design intent and architectural rules for the dxaws-dns primitive.

The module is intentionally small: it exists to provide a stable, composable contract for managing DNS record sets in AWS Route 53 using declarative convergence.

Architectural Position in dxaws

dxaws-dns is a primitive module.

That means:

  • It exposes stable Python contracts.

  • Its public interfaces are immutable and only extendable.

  • It contains no orchestration beyond converging a single DNS record.

  • It is designed to be composed by higher-level modules (e.g., website/CDN orchestration).

In the dxaws stack, the rough layering looks like:

  • dxaws-core: shared session, provider base classes, o11y

  • dxaws-dns: DNS record primitives (this module)

  • higher-level modules: orchestration (CloudFront, websites, multi-account)

Core Pattern: Declarative Convergence

The core workflow is:

  1. Normalize desired (complete inputs; canonicalize)

  2. Read current (from provider)

  3. Plan (diff desired vs current)

  4. Apply (execute the plan)

  5. Return a result with an outcome:

    • noop if no changes were required

    • applied if AWS was mutated

The contract goal is deterministic behavior:

  • Apply once → applied

  • Apply again → noop

  • Introduce drift → applied

  • Re-apply → noop

This is validated via AWS-backed acceptance tests.

Layering

Models (contracts)

Models define the stable API surface and must not leak AWS/boto3 shapes.

  • DnsRecordDesired

  • DnsRecordCurrent

  • DnsRecordPlan

  • DnsManagerResult

Contract notes:

  • zone_name is the human-facing identifier and is always required.

  • zone_id is optional at call sites and may be resolved by the system.

Manager (orchestration + normalization)

The manager owns:

  • Input normalization (canonicalization)

  • Workflow orchestration (current → plan → apply)

  • Emitting o11y events (when enabled)

Normalization rules live here because:

  • It keeps the planner deterministic.

  • It prevents duplication across call sites (CLI, tests, orchestrators).

Planner (pure diff)

The planner:

  • Takes (desired, current)

  • Produces a plan

  • Must be side-effect free (no AWS calls)

Executor (mutation)

The executor:

  • Takes a plan

  • Calls provider write operations

  • Must not perform input enrichment (e.g., resolving zone_id)

Provider (AWS isolation)

The provider is the only layer that should:

  • Touch boto3

  • Encode AWS/Route 53 quirks

The provider surface should stay small and explicit.

Canonicalization Rules

These are the canonicalization rules that make diffs stable and idempotency real.

Hosted zone identity

Callers provide:

  • zone_name (e.g., dev.dxaws.com)

The system may resolve:

  • zone_id via provider.resolve_zone_id(zone_name=...)

This keeps AWS implementation details out of call sites.

Record names

Record names are normalized to a fully-qualified name based on zone_name.

Example:

  • record_name="_test" + zone_name="dev.dxaws.com"

  • becomes "_test.dev.dxaws.com."

Record types

Record types are normalized to uppercase.

TXT values (quoting)

Route 53 returns TXT values wrapped in double quotes.

To keep diffs stable:

  • Desired TXT values are normalized to quoted form.

  • Provider write operations also normalize to quoted form.

This ensures that a second apply becomes noop.

CNAME targets

Route 53 stores DNS names with a trailing dot.

Callers should prefer canonical targets (e.g., example.com.). The planner operates on the normalized values.

Acceptance Tests as Contract Tests

Acceptance tests in this module are treated as contract tests.

They validate:

  • Create / read / delete lifecycle

  • Idempotency (noop on second apply)

  • TTL drift detection + correction

  • Multiple record types (TXT, A, CNAME)

Safety features:

  • Tests are opt-in (DXAWS_AWS_TESTS=1).

  • Tests require explicit zone confirmation (DXAWS_ACCEPTANCE_CONFIRM).

  • Tests print AWS identity before mutation.

  • Tests clean up after themselves and verify deletion.

Tradeoffs and Intentional Limitations

  • This module focuses on record sets, not zone provisioning.

  • It avoids complex routing policies (weighted, latency, geo) until the core contracts are proven.

  • It intentionally prefers explicit, composable APIs over convenience wrappers.

If/when the module expands, it should do so by extending interfaces rather than changing existing fields or semantics.

Extensibility Guidelines

When extending this module:

  • Prefer adding new optional fields to DnsRecordDesired over changing meaning.

  • Keep planner logic deterministic and side-effect free.

  • Put AWS quirks in the provider and canonicalization in the manager.

  • Add acceptance coverage for any new record type or behavior.