Module relay 

Outbound cloud relay — jekt delivery tier 4.

Tiers 1–3 (local handler, same-host registry, LAN peer) all live in server/reactive.rs. Tier 4 was, until this module existed, a comment there — // 4. Return original error (muxbus-client will fall back to cloud relay) — delegating to a “muxbus-client” that the callers agents actually use are not. The MCP SendMessage tool POSTs to /agentmux/reactive/inject and bails on success != true, so the tier chain silently stopped at three while SendMessage’s own description promised “local → LAN → cloud”. See docs/reports/REPORT_NETWORK_ARCHITECTURE_DRYNESS_AND_ROBUST_LAN_2026_09_06.md §5.

This module makes tier 4 real and owned by the same handler as the other three, so every caller inherits it instead of re-implementing it.

What “success” means here

Tier 4 is store-and-forward, not delivery. The cloud persists the injection and broadcasts a wake signal; the recipient’s srv picks it up on its next sync, which may be seconds away or never (that instance may be offline). A 2xx here therefore means queued, and RelayOutcome::Queued is deliberately not named anything that reads as delivered — the tier-3 forward path had exactly that confusion and it produced a real bug (see forward_inject_to_peer’s “one behaviour unified” note).

Structs

RelayCredential 🔒

What relay_token resolved: the bearer to send with, and the account (sub) of the shared token it was resolved under — empty if that token names none, which leaves the carry gate without a directory (unsigned).

WanCarried 🔒

The W3-S carried tuple (SPEC_WAN_JEKT_VERIFICATION_2026_09_24.md §2.1): the sender’s WAN signature and the exact values it signed, so a receiver can re-check it. Field names are the cloud’s; an old cloud silently drops them.

Enums

RelayOutcome 🔒

Outcome of a tier-4 relay attempt.

Constants

BATCH_ROUTES_RETRY 🔒

How long to stop asking a relay that answered 404 to a batch route (/reactive/pending-batch, /agents/lease/renew-batch): it predates them.

MAX_BATCH_AGENTS 🔒

The most agents one batch request may name (the relay’s own limit).

MAX_CARRIED_ID_CHARS 🔒

MAX_CARRIED_SIG_CHARS 🔒

The cloud’s caps: signature ≤ 128 chars, identifiers ≤ 256.

MAX_RELAY_MESSAGE_BYTES 🔒

The cloud rejects anything larger (10 KB maximum). Checked locally so an oversized message fails with a useful error instead of a bare 400 after a round trip.

RELAY_TIMEOUT_SECS 🔒

Bounds how long a failed local delivery can block on the cloud before the caller gets its answer. Tier 4 runs only after tiers 1–3 have already failed, so this is additive to a request that is already slow.

USER_AGENT 🔒

What the desktop’s relay calls send as User-Agent, so the relay can tell app versions apart (reqwest sends none of its own).

Statics

BATCH_ROUTES_MISSING 🔒

Functions

batch_routes_missing 🔒

Whether the relay at base recently answered 404 to a batch route. Its callers then ask per agent, as before the batch routes existed. Keyed by relay, so a relay without them never switches them off for another.

note_batch_routes_missing 🔒

Note a 404 from the relay at base to a batch route.

relay_inject 🔒

POST one injection to the cloud relay.

relay_token 🔒

Resolve the credential to relay as, preferring one bound to this specific sender over the shared account token — the same precedence the inbound path (cloud_subscriber::sync_agent_reactive) already uses, so a binding-enforced account behaves consistently in both directions.

rest_base_url 🔒

Base URL of the muxbus REST API.

settled_account 🔒

The account to bind a send to: the one its credential was resolved under, if it’s still the signed-in one afterwards; empty otherwise.

wan_carry_gate 🔒

The relay carry gate (§2.1): the tuple rides the relay only if every condition holds; otherwise the message is relayed exactly as before, with nothing carried, so every gap degrades to “unsigned”, never to a false forgery alarm at the receiver. Err names the first condition that failed, for debug logging only.