Module hostname 

Hostname helpers — typed FQDN formatting matching nix/lib/fleet- domains.nix’s mkHostname pattern.

The substrate move: every FQDN this codebase emits is computed here. Two functions (fmt_fqdn for the per-instance form + fmt_fqdn_stable for the unprefixed stable-claim form) and one deterministic ephemeral-id derivation (ephemeral_id_from_spec) are the single source of truth — no string format!() of DNS syntax anywhere else in the tree.

Forms:

  Per-instance: ${app}.${ephemeral_id}.${cluster}.${location}.${domain}
  Stable:       ${app}.${cluster}.${location}.${domain}

Where ${ephemeral_id} is:

• RoutingHostname.instance when set — a named slot like akeyless-prod or pr-1234.
• EPHEMERAL_ID_HASH_LEN (= 8) hex chars of BLAKE3(canonical_spec_json) when unset — a content-hash slot that changes only when the Process’s spec changes.

All four FQDN segments are validated as RFC 1123 DNS labels at the boundary — lowercase alphanumeric + hyphen, 1–63 chars, no leading/trailing hyphen. Validation errors surface as typed HostnameError variants so callers can render targeted operator messages.

Enums

HostnameError

Why a hostname can’t be formatted. Typed so callers can branch.

Constants

EPHEMERAL_ID_HASH_LEN

Number of hex chars from BLAKE3 to use as the content-hash form of ephemeral_id. 8 = 32 bits of entropy; collision probability at 1k concurrent Processes ≈ 1 in 8.5 million. Comfortable for any single cluster’s working set, room to grow.

Functions

ephemeral_id_from_spec

Compute the content-hash form of ephemeral_id for a given ProcessSpec. Stable across reconciles of the same spec; new spec content ⇒ new hash ⇒ new DNS slot.

fmt_fqdn

Format the per-instance FQDN.

fmt_fqdn_stable

Format the stable-claim FQDN (no ephemeral_id segment).

resolve_ephemeral_id

Resolve the ephemeral_id for a single RoutingHostname entry. Named slot wins if set; otherwise the content-hash form is computed from the surrounding ProcessSpec (caller passes in via fallback_hash).