# dxaws-dns

## Overview

`dxaws-dns` is the DNS primitive module within the **dxaws** ecosystem.

It provides declarative, idempotent management of Route 53 DNS record sets
using the dxaws **planner → executor → provider** architecture.

The goal of this module is simple:

> Given a desired DNS record state, converge AWS Route 53 to match that state — safely and deterministically.

This module does **not** wrap the AWS CLI and it does not expose raw boto3
shapes. Instead, it exposes stable Python contracts designed for composition
with other dxaws modules.

---

## What This Module Manages

Currently supported record types:

- `TXT`
- `A`
- `CNAME`

The module supports:

- Record creation (`state="present"`)
- Record deletion (`state="absent"`)
- TTL drift detection and correction
- Idempotent convergence (`noop` when already correct)
- Automatic `zone_id` resolution from `zone_name`
- TXT quoting normalization (Route 53 returns TXT values quoted)

---

## Design Principles

`dxaws-dns` follows the dxaws primitive architecture:

- **Models define stable contracts** (`DnsRecordDesired`, `DnsRecordCurrent`)
- **Manager performs normalization + orchestration**
- **Planner computes diffs** (pure logic, no AWS calls)
- **Executor performs mutation**
- **Provider isolates AWS / boto3 specifics**

Key rules:

- Interfaces are immutable and extendable.
- Provider quirks (e.g., TXT quoting) are normalized.
- Manager canonicalizes desired input before diffing.
- Planner behavior is deterministic and side-effect free.

This ensures true *declarative convergence*:

- Apply once → `applied`
- Apply again → `noop`
- Introduce drift → `applied`
- Re-apply → `noop`

---

## Responsibilities

This module **owns**:

- DNS record-set lifecycle management
- Record normalization (type, quoting, canonical forms)
- Idempotent convergence behavior

This module explicitly does **not**:

- Manage hosted zone delegation
- Handle IAM policies
- Implement cross-account orchestration
- Expose raw boto3 interfaces

Those concerns belong in other dxaws modules.

---

## Related Modules

- **dxaws-core** – shared session, provider base classes, o11y
- **dxaws-dns** – DNS primitive (this module)
- **dxaws-edge** – higher-level DNS + CDN orchestration

---

```{toctree}
:maxdepth: 2
:caption: Contents

README
usage
design
api
```