# dxaws-cloudfront

CloudFront distribution management using the **dxaws declarative convergence** pattern.

---

## Overview

`dxaws-cloudfront` is a primitive dxaws module responsible for converging
**one CloudFront distribution** to a declared desired state.

It is designed to be:

- Deterministic
- Idempotent
- Provider-isolated
- Contract-driven

This module does not orchestrate other services. It focuses strictly on
CloudFront distribution lifecycle management and exposes a stable interface
for higher-level modules such as `dxaws-website`.

---

## What This Module Manages

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

---

## What This Module Does NOT Manage

- Multiple origins or origin groups
- Multiple cache behaviors
- Cache policies / origin request policies
- WAF / Shield configuration
- Logging / realtime logs
- Lambda@Edge / CloudFront Functions
- DNS records (Route53 handled elsewhere)

---

## Lifecycle Model

The module follows the dxaws convergence model:

1. Discover current state
2. Plan required actions
3. Execute actions
4. Wait for eventual consistency when necessary

Destroy is modeled as convergence to `present=False`.

CloudFront is eventually consistent, so wait semantics are explicit and enforced.

---

## Module Structure

```text
models.py      → stable contract
planner.py     → pure diff logic
executor.py    → action dispatcher
providers/aws  → AWS implementation
manager.py     → orchestration + lifecycle
```

See the full architecture documentation in **design.md**.

---

## Contents

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

README
usage
design
api
```

---

## Related dxaws Modules

- dxaws-core
- dxaws-dns
- dxaws-s3
- dxaws-acm
- dxaws-website

These modules compose together but remain independently testable primitives.