# 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.