API Reference

This page documents the stable contracts exposed by dxaws-acm.

The goal of this module is to provide a small, durable surface area that higher-level orchestrators (e.g., dxaws-website) can depend on without coupling to AWS SDK details.

• API Modules
  • dxaws_acm.manager
  • dxaws_acm.planner
  • dxaws_acm.models
  • dxaws_acm.constants
  • dxaws_acm.exceptions
  • dxaws_acm.providers.base
  • dxaws_acm.providers.aws
  • dxaws_acm.providers.route53

---

Primary Entry Point

AcmManager

from dxaws_acm.manager import AcmManager

The manager coordinates planning and execution.

Primary method:

AcmManager.execute(desired: AcmDesired, *, options: ExecuteOptions | None = None) -> AcmManagerResult

This method:

1. Reads current state

2. Plans differences

3. Applies changes

4. Optionally waits for convergence

It is safe to call repeatedly (idempotent).

---

Desired Model

AcmDesired

from dxaws_acm.models import AcmDesired

Fields:

• domain_name: str

• subject_alternative_names: list[str]

• hosted_zone_id: str

• region: str

• tags: dict[str, str]

This describes the target certificate state.

---

Result Model

AcmManagerResult

Returned from execute().

Key fields:

• desired

• current

• plan

• outputs

• outcome ("noop" | "applied" | "failed")

AcmOutputs

Key fields:

• certificate_arn: str

• status: str

---

Execution Options

ExecuteOptions

from dxaws_acm.manager import ExecuteOptions, ApplyOptions

Fields:

• apply_options: ApplyOptions | None

• emit_events: bool

ApplyOptions

Controls polling and wait behavior.

Fields:

• max_wait_seconds: int

• poll_interval_seconds: int

• dns_ttl: int

• emit_events: bool

---

Providers

Providers encapsulate AWS-specific logic.

AwsProvider

from dxaws_acm.providers.aws import AwsProvider

Responsibilities:

• list_certificates()

• describe_certificate()

• request_dns_validated_certificate()

• delete_certificate()

• get_dns_validation_records()

All boto3 interaction lives here.

Route53RecordProvider

from dxaws_acm.providers.route53 import Route53RecordProvider

Responsibilities:

• resolve_zone_id(zone_name: str) -> str

• upsert_record(...)

• delete_record(...)

---

Stability Contract

The following are considered stable integration points:

• AcmManager.execute()

• AcmDesired

• AcmManagerResult

• AcmOutputs

Internal planner logic and AWS normalization details are intentionally hidden behind these contracts.

Higher-level modules should depend only on these surfaces.