Connections
The connection lifecycle state machine, hostname collisions, and tenancy.
A connection is one custom domain being onboarded. Its id doubles as the
jobId used by the widget and webhooks. A connection carries desired records,
observed records, an ownership challenge, and a certificate mirror.
The connection lifecycle (state machine)
created → pending_ownership → verifying → verified
→ dns_writing → propagating → issuing_cert → live
↘ drifted
(any) → stalled / failed / archived| State | Meaning |
|---|---|
created | Row exists; nothing proven yet. |
pending_ownership | Waiting for the ownership TXT to appear. |
verifying | An ownership check is in progress. |
verified | Ownership proven — the ask gate is now open for this host. |
dns_writing | A delegated auto-write is in progress. |
propagating | Desired records are being observed until they all resolve. |
issuing_cert | Cert issuance in progress. |
live | Records propagated, cert issued, edge is proxying. |
drifted | A live domain's records stopped resolving to their intended values. |
stalled | Progress paused (e.g. long propagation). |
failed | A terminal error occurred. |
archived | Soft-deleted / offboarded. |
Hostname collisions
Exactly one active claim per hostname exists globally (enforced by a partial
unique index over verified/issuing_cert/live). A second connection to a
hostname already held active is rejected with 409 HostnameConflict.
Tenancy
Every object belongs to a tenant. All tenant-scoped endpoints filter by the
caller's tenant; cross-tenant access returns 404, never another tenant's data.
See Security.
Propagation and drift
Propagation is confirmed by resolving each desired record and matching values
(see Ownership and setup types). After
go-live, a background worker periodically re-checks; if a live domain's records
stop resolving correctly it transitions to drifted and fires domain.drift so
you can alert the customer.