Struct RoutingHostname 

pub struct RoutingHostname {
    pub app: String,
    pub instance: Option<String>,
    pub cluster: Option<String>,
}

One entry in RoutingSpec.hostnames.

Emitted FQDN: ${app}.${ephemeral_id}.${cluster}.${location}.${domain} where:

• app and (optional) instance come from this struct;
• cluster falls back to reconciler-config when unset;
• location and domain are reconciler-config (from nix/lib/fleet-domains.nix).

Fields

app: String

Application slot — api, gateway, web, etc. Must be a valid DNS label (RFC 1123): lowercase alpha-num

• hyphen, 1–63 chars, no leading/trailing hyphen. The reconciler validates this at the boundary.

instance: Option<String>

Named instance segment. When Some("demo-prod") the FQDN reads ${app}.demo-prod.${cluster}.…. When None the reconciler substitutes blake3(canonical_spec)[:8] — deterministic per-spec, changes when the spec changes.

Must be a valid DNS label when set.

cluster: Option<String>

Cluster override. Empty/None ⇒ reconciler-config default (e.g., pleme-dev). Used for cross-cluster routing rules, rare in practice.

Implementations

impl RoutingHostname

pub fn is_named(&self) -> bool

True iff this entry resolves to a named slot (vs content-hash).

pub fn cluster_or<'a>(&'a self, fallback: &'a str) -> &'a str

Cluster override slice with a caller-supplied per-config fallback applied — the ONE-line collapse of the paired self.cluster.as_deref().unwrap_or(fallback) incantation the reconciler’s FQDN composer + stable-claim group-key composer both spelled by hand pre-lift.

Pre-lift the projection was hand-authored at TWO sites past the ★★ PRIME-DIRECTIVE ≥ 2 duplication threshold in tatara-reconciler, each walking the SAME borrow-form Option<String> slot × per-config-fallback shape:

• render::render_routing — per-instance FQDN composer seed for crate::hostname::fmt_fqdn, keyed on the cluster segment.
• table_controller::stable_name_group_key — claim-arbiter (cluster, app) group-key seed, keyed on the cluster segment.

Both sites walked the SAME projection: pull the borrow-form .cluster.as_deref() slot, sink an absent slot to the per-config fallback the caller threads in from Context.config.cluster. Post-lift both consumers read hostname.cluster_or(cfg_cluster) — the projection sits at ONE substrate owner, so a future normalization (a case-fold pass, an empty-string-to-fallback promotion, a cross-cluster alias resolver, a per-fleet cluster-name canonicalization) lands here exactly once and every consumer (FQDN composer, claim-arbiter group key, and any future edge whose downstream keys on the cluster segment) inherits the upgrade mechanically.

Peer to Self::is_named on the (Option slot × fallback shape) axis pair — both live on RoutingHostname and hide the missing-slot corner behind ONE substrate primitive; both preserve the borrow-form return, so downstream composers thread the slice without a .to_string() step.

Semantics: an explicit Some("") returns the empty string (matching the pre-lift .as_deref().unwrap_or(fallback) chain’s behavior). Callers whose downstream rejects an empty cluster segment must gate on that separately — crate::hostname::fmt_fqdn’s validator does so automatically via [crate::hostname::HostnameError:: InvalidLabel].

pub fn instanced(app: impl Into<String>, instance: impl Into<String>) -> Self

Compose a RoutingHostname pinned to the “named-slot, per-config cluster fallback” shape (instance: Some(<instance>), cluster: None) — the ONE substrate primitive owning the 3-slot RoutingHostname { app, instance: Some(<instance>), cluster: None } fixture literal every consumer restated by hand pre-lift.

Pre-lift the same 3-slot chain (app: <s>.into(), instance: Some(<s>.into()), cluster: None) was hand-authored at TEN workspace-wide sites past the ★★ PRIME-DIRECTIVE ≥ 2 duplication threshold, EVERY one of them the “named instance segment, cluster-inherits-from-config” shape:

• tatara-process::hostname — two sites: the resolve_named_slot_wins fixture plus the end_to_end_named_and_unnamed_for_same_process named-arm fixture.
• tatara-process::routing — four sites: the demo_routing seed (two hostnames), the hostname_is_named_when_instance_nonempty populated-instance pin, and the cluster_or_borrow_form_return_shape_matches_fmt_fqdn_arg_shape FQDN-composer parity pin.
• tatara-reconciler::edges — two sites: the api_hostname test fixture plus the routing_edge_labels_stamps_app_slot_from_hostname APP-slot pin (which stamps "gateway" instead of "api").
• tatara-reconciler::render — two sites: the two_hostname_routing seed’s api + gateway hostname pair.

Post-lift every callsite reads RoutingHostname::instanced(<app>, <instance>) and the three-slot struct’s cluster slot stays owned by the ONE substrate site — the per-config-cluster fallback resolved through Self::cluster_or at read time stays the ONLY axis a cluster override travels through, so a future normalization (a per-cluster canonicalization, a cross-cluster alias resolver, a claim-arbiter fallback swap) lands here exactly once and every consumer inherits the upgrade mechanically. The impl Into<String> bound on both positional args accepts every pre-lift caller shape verbatim — &'static str literals, owned String values, and .into()-terminated chains alike — without a per-site coercion.

Peer to Self::content_hashed on the (instance slot × cluster slot) axis pair: both live on RoutingHostname and hide the pair’s “per-config cluster fallback” corner behind ONE substrate primitive; Self::instanced fills the Some(<name>) arm of the instance slot, Self::content_hashed fills the None arm.

Theory anchor: THEORY.md §VI.1 (generation over composition — the RoutingHostname { app, instance: Some(<i>), cluster: None } fixture literal recurred at ten hand-authored sites past the ★★ PRIME-DIRECTIVE ≥ 2 duplication trigger, and is lifted to ONE owner here). THEORY.md §II.1 invariant 5 (composition preserves proofs — a regression that drifted the default- cluster sentinel from None to a hardcoded string, or reordered the three struct slots, surfaces at the instanced_composes_byte_identical_to_pre_lift_literal_across_every_app_instance_pair pin below rather than as silent skew at every downstream fixture).

pub fn content_hashed(app: impl Into<String>) -> Self

Compose a RoutingHostname pinned to the “content-hash anonymous, per-config cluster fallback” shape (instance: None, cluster: None) — the ONE substrate primitive owning the 3-slot RoutingHostname { app, instance: None, cluster: None } fixture literal every consumer restated by hand pre-lift.

The instance: None slot instructs the reconciler’s crate::hostname::resolve_ephemeral_id to substitute blake3(canonical_spec)[:8] — the content-hashed FQDN form documented on RoutingHostname. Pre-lift the same 3-slot chain (app: <s>.into(), instance: None, cluster: None) was hand-authored at NINE workspace-wide sites past the ★★ PRIME-DIRECTIVE ≥ 2 duplication threshold, EVERY one of them the “unnamed instance, cluster-inherits-from-config” shape:

• tatara-process::hostname — two sites: the resolve_unset_named_falls_back fixture plus the end_to_end_named_and_unnamed_for_same_process anon-arm fixture.
• tatara-process::routing — six sites: the h_anon pin, the cluster_or_falls_back_to_caller_string_when_cluster_is_none fallback pin, and four more cluster_or / round-trip fixtures.
• tatara-reconciler::render — one site: the anonymous_hostname_uses_content_hash FQDN composer pin.

Peer to Self::instanced on the (instance slot × cluster slot) axis pair — Self::content_hashed fills the None arm of the instance slot, Self::instanced fills the Some(<name>) arm.

Theory anchor: THEORY.md §VI.1 (generation over composition — the RoutingHostname { app, instance: None, cluster: None } fixture literal recurred at nine hand-authored sites past the ★★ PRIME-DIRECTIVE ≥ 2 duplication trigger, and is lifted to ONE owner here). THEORY.md §II.1 invariant 5.

Trait Implementations

impl Clone for RoutingHostname

fn clone(&self) -> RoutingHostname

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RoutingHostname

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for RoutingHostname

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for RoutingHostname

impl JsonSchema for RoutingHostname

fn schema_name() -> String

The name of the generated JSON Schema.

fn schema_id() -> Cow<'static, str>

Returns a string that uniquely identifies the schema produced by this type.

fn json_schema(generator: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

fn is_referenceable() -> bool

Whether JSON Schemas generated for this type should be re-used where possible using the $ref keyword.

impl PartialEq for RoutingHostname

fn eq(&self, other: &RoutingHostname) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for RoutingHostname

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for RoutingHostname