# Usage

This page shows common ways to use **dxaws-cloudfront**.

The primary entry point is `CloudFrontManager.execute(desired)`.

---

## Basic: Default certificate, no aliases

This creates (or updates) a distribution using the CloudFront default certificate.

```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-origin-bucket"),
)

out = mgr.execute(desired)
print("id=", out.result.id)
print("domain_name=", out.result.domain_name)
```

---

## Aliases + ACM certificate (CloudFront)

CloudFront requires ACM certificates in **us-east-1**.

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

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

cert_arn = "arn:aws:acm:us-east-1:123456789012:certificate/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

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

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

---

## SPA custom error responses

This is useful for single-page apps that want `index.html` for 403/404.

```python
from dxaws_cloudfront.manager import CloudFrontManager
from dxaws_cloudfront.models import (
    CustomErrorResponsesDesired,
    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-origin-bucket"),
    custom_errors=CustomErrorResponsesDesired(
        enabled=True,
        response_page_path="/index.html",
        error_codes=(403, 404),
        response_code=200,
    ),
)

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

---

## Destroy

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

Call `destroy()` with the same `desired` you used for creation so aliases can
locate the distribution deterministically.

```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-origin-bucket"),
    aliases=("cdn.example.com",),
)

mgr.destroy(desired)
```

Notes:

- CloudFront deletion is slow.
- Destroy performs: disable → wait (disabled + deployed) → delete.

---

## Running acceptance tests

Acceptance tests run against real AWS and are intentionally noisy/verbose.

Required environment variables:

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

Run:

```bash
DXAWS_AWS_TESTS=1 make accept-cloudfront
```

If you hit `ExpiredToken`, run:

```bash
dxaws whoami
```

---

## Outputs and DNS integration

`execute()` returns a `ManagerResult` with a `DistributionResult`:

- `id`
- `domain_name`
- `hosted_zone_id` (CloudFront constant)

These outputs are intended to feed DNS modules that create Route53 alias records.