Module routing 

Distributed request routing: the gRPC-edge availability layer over the fence. Distributed request routing — the gRPC-edge availability layer over the epoch fence (DISTRIBUTED-ROUTING-DESIGN §2).

A node that is not the current owner of shard_for(workflow_id) cannot win the quorum CAS for that workflow’s writes: the owner’s promised ballot fences the proposal (surfaced as aion_store::StoreError::NotOwner, R-0). Routing turns that correctness backstop into an availability layer: at the edge we resolve the shard owner and either proceed locally, forward to the owner (R-3), or return the typed retryable NotOwner so the caller re-resolves.

This module only ever does anything for a distributed ([store.cluster]) boot. With no cluster store on crate::ServerState every entry point short-circuits to “proceed locally”, so the default single-node path is byte-identical — the fence is never even reachable there.

Staging

• R-1 (here): a shard_for-aware edge guard for signal/query/cancel on a non-owned shard (return NotOwner), plus an unsteered-start remint so a start whose default-minted id would land off-owner is re-minted onto a locally-owned shard and never fences (§2.4 stopgap).
• R-2: a ShardDirectory trait + static resolver so the edge knows the remote owner’s gRPC address, not just “not me”.
• R-3: a RequestForwarder trait + gRPC forwarder that relays a non-local request to the owner instead of rejecting it.

Structs

DirectoryPeer

One peer entry in the static directory: its name, the shards it statically declares ownership of, and its (optional) gRPC forward address.

GrpcRequestForwarder

gRPC forwarder: dials the owner’s grpc_address with a tonic WorkflowService client and re-issues the RPC.

NodeRef

A resolved remote shard owner.

StaticShardDirectory

The static directory: static peer config + live local-ownership, the SS-3 quorum-replicated shard-owner overlay, and a peer-liveness overlay, all read live from the cluster store.

Enums

ForwardReply

The owner’s reply, relayed back to the original caller unchanged.

ForwardRequest

The forwardable client RPCs. For signal/query/cancel the target workflow_id is known at the edge; start is forwardable once the caller supplies an R-4 routing_key so the edge can resolve the target shard’s owner before placing the start.

OwnerView

The directory’s view of a shard’s current owner.

RemintOutcome

The placement decision for an unsteered start whose id has not been minted yet (R-1 stopgap).

RouteDecision

The routing verdict for a mutation/read (signal/query/cancel) whose target workflow_id is known up front.

SteerDecision

The routing decision for a steered start whose target shard is derived from a caller-chosen routing key (R-4, §2.4).

Constants

FORWARD_HOPS_METADATA

The metadata key carrying the number of cluster hops a forwarded request has already taken. A request arriving with a value at or above the hop cap is NOT forwarded again (loop prevention) — the receiver returns NotOwner so the original caller re-resolves and retries with backoff.

MAX_FORWARD_HOPS

The maximum number of intra-cluster forward hops a single client request may take before the chain is broken with NotOwner (§2.5: “a hop counter caps forwards (e.g. 2)”).

Traits

RequestForwarder

Relays a client request to a remote shard owner and returns its reply.

ShardDirectory

Resolves the current owner of a distribution shard.

Functions

current_hops

Read the current hop count from request metadata (0 when absent/malformed).

not_owner_wire

The typed retryable wrong-owner refusal for shard.

owner_refusal

The owner’s own typed refusal, decoded out of a forwarded request’s failure status, or None when the status carries no authored detail.

route_mutation

Route a signal/query/cancel at the edge through the shard directory.

route_start

Decide an unsteered start’s placement at the edge (R-1, §2.4).

route_start_steered

Route a steered start at the edge through the shard directory (R-4, §2.4).