# Design

## Goals
1. Converge an S3 bucket to a desired spec for the supported features:
   - tags
   - versioning
   - public access block
2. Stay declarative: Desired → Current → Plan → Apply → Result
3. Keep the module primitive and composable: no “SDK wrapper” surface

Future scope (not implemented yet): encryption, lifecycle rules, bucket policy templates (e.g., TLS-only), CloudFront-origin/OAC policy convergence.

## Architecture

The purpose of this module is to provide a convergent management interface to Amazon S3 buckets.

We do **not** expose the full boto3 surface area. Instead, we converge a pragmatic subset of bucket features that are commonly needed by dxaws primitives. This keeps the public contract small, testable, and stable.

## Declarative Convergence

This module follows a **declarative convergence** model.

Instead of issuing imperative AWS calls directly, callers describe the
*desired state*. The module then:

1. **Plans** what needs to change to reach that state
2. **Applies** the plan using provider-backed AWS operations

This separation makes behavior predictable, testable, and idempotent,
while keeping AWS-specific logic isolated in providers and making plans easy to unit test.

## Key Concepts

### Providers

Providers encapsulate AWS SDK (boto3) calls. The rest of the module treats the provider as an interface so that planning/execution can be unit tested without AWS.

### Manager (public facade)

`manager.py` is the public entrypoint. It:

1. Validates the desired state
2. Reads the current state from the provider
3. Calls the planner to compute a plan
4. Applies the plan via the executor
5. Returns a result object

### Planner / Executor

- **planner.py** computes a deterministic plan (a list of actions) by comparing *desired* vs *current* state.
- **executor.py** applies the plan using provider-backed operations.

### planner.py

Planner rules are deterministic and include purpose-driven invariants:

1. If bucket doesn’t exist → `CREATE_BUCKET`
2. Tags drift → `PUT_TAGS`
3. Public access block drift → `PUT_PUBLIC_ACCESS_BLOCK`
4. Versioning drift → `PUT_VERSIONING`

These four rules define the current contract that higher-level modules can rely on.

#### Future planner rules (not implemented yet)

- Encryption drift → `PUT_ENCRYPTION`
- Bucket policy convergence:
  - TLS-only deny statement
  - CloudFront OAC allow-read statement
- Lifecycle rules / intelligent-tiering / replication templates

### executor.py

The executor applies actions in a safe order:

1. Create bucket (if needed)
2. Public access block
3. Versioning
4. Tags

Returns `S3BucketResult` from a provider read-back.

### providers/base.py (interface)

boto3 methods that will be encapsulated:

- `get_current(name) -> S3BucketCurrent`
- `create_bucket(desired)`
- `put_tags(name, tags)`
- `put_public_access_block(name, config)`
- `put_versioning(name, enabled: bool)`
- `destroy_bucket(name)`
- `get_outputs(name) -> S3BucketResult`

AWS implementation in `providers/aws.py` uses boto3 S3.

### constants.py / exceptions.py

Defaults:

- `DEFAULT_ENCRYPTION = "SSE-S3"`
- `DEFAULT_BLOCK_PUBLIC_ACCESS = True`
- `DEFAULT_ENFORCE_TLS = True`

Exceptions:

- `InvalidDesiredStateError`
- `BucketNameError`
- `MissingCloudFrontInfoError` (only if strict mode is enabled)


## CLI Surface

The CLI orchestration for S3 lives in **dxaws-cli**.

This module remains **Python-first** and focuses on providing a stable manager/provider contract that higher-level tooling can call.

## Tradeoffs

### Eventual Consistency

Some S3 operations (especially create/delete and feature reads immediately after) can be eventually consistent.

Acceptance tests intentionally include:

- a visibility wait after create
- drift + converge checks
- a delete waiter with small grace delays

This keeps the contract stable while acknowledging AWS propagation behavior.

### CloudFront / Policy Convergence

CloudFront-origin and policy convergence (TLS-only, OAC statements, etc.) are intentionally deferred. The current module stays focused on the primitive features we already rely on.