# dxaws-cloudfront

Create and manage CloudFront distributions using the dxaws declarative convergence pattern.

---

## Overview

This repository contains the **dxaws-cloudfront** module.

Version: **0.1.0**

This module manages a single CloudFront distribution using:

- S3 origin (via Origin Access Control)
- Optional aliases (CNAMEs)
- Optional ACM certificate (must be in `us-east-1`)
- Deterministic convergence (create / update / wait / destroy)

It follows the dxaws architecture pattern:

- **Desired** → target state
- **Current** → observed state
- **Plan** → diff
- **Executor** → apply actions
- **Manager** → orchestration + lifecycle

---

## Installation

```bash
pip install dxaws-cloudfront
```

For development:

```bash
pip install -e ".[dev]"
```

---

## Quick Example

```python
from dxaws_cloudfront.manager import CloudFrontManager
from dxaws_cloudfront.models import DistributionDesired, S3OriginDesired
from dxaws_cloudfront.providers.aws import AwsProvider

provider = AwsProvider(aws=...)
mgr = CloudFrontManager(provider=provider)

desired = DistributionDesired(
    name="my-site",
    origin=S3OriginDesired(bucket_name="my-bucket"),
    aliases=("cdn.example.com",),
)

result = mgr.execute(desired)
print(result.domain_name)
```

Destroy:

```python
mgr.destroy(desired)
```

Destroy converges to `present=False` while preserving aliases for deterministic discovery.

---

## Acceptance Tests (Real AWS)

CloudFront acceptance tests run against real AWS.

### Required Environment Variables

```bash
DXAWS_TEST_REGION=ca-central-1
DXAWS_ACCEPTANCE_ZONE_NAME=test.dxaws.com
```

Run:

```bash
make accept-cloudfront
```

### Notes

- The origin bucket is **persistent** and will NOT be deleted.
- ACM wildcard certificate is reused if available.
- CloudFront certificates must be in **us-east-1**.
- If you see `ExpiredToken`, run:

```bash
dxaws whoami
```

---

## Lifecycle Behavior

### Create
- Creates OAC (if needed)
- Creates distribution
- Waits until deployed

### Update
- Updates config if diff detected
- Waits until deployed

### Wait
- If distribution exists but status != `Deployed`, manager waits

### Destroy
- Disable distribution
- Wait until disabled + deployed
- Delete distribution

CloudFront is eventually consistent. The provider ensures proper wait semantics before delete.

---

## Local Docs Preview (Sphinx)

```bash
python -m pip install ".[docs]"
cd docs
make html
open _build/html/index.html
```

Tip: use editable install during development:

```bash
python -m pip install -e ".[docs]"
```

---

## Current Scope (MVP)

Supported:

- Single distribution
- Single S3 origin
- Default cache behavior
- Aliases
- ACM certificate
- Custom SPA error responses

Not yet supported:

- Multiple origins
- Cache policies / origin request policies
- Logging
- WAF
- Real-time logs
- Advanced behaviors

---

## Design Philosophy

This module is intentionally:

- Deterministic
- Explicit
- Idempotent
- Contract-driven

The planner compares summarized state to avoid AWS response drift.

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

---

## License

MIT