relay

const (
	ReconnectInitialDelay = 500 * time.Millisecond
	ReconnectFactor       = 2
	ReconnectCeiling      = 30 * time.Second
	ReconnectJitter       = 0.20
)

The reconnect backoff between relay dial attempts: ADR-007 section 6.0's numeric budget (initial delay, growth factor, ceiling, jitter fraction), and the D9 clause that binds it -- "Client reconnect backoff + jitter on BOTH hops".

A client that reconnects hard exhausts the relay's per-target quota, which is shared with the traffic it is trying to carry; the exponential growth is what keeps a stuck relay from being redialled at a fixed high rate for the life of the process, and the jitter keeps a fleet reconnecting after a relay restart from arriving as one herd. These are the committee's approved numbers, not tuning knobs: a change here is a change to the budget.

IT LIVES IN THIS PACKAGE BECAUSE BOTH HOPS DIAL THROUGH IT AND NOTHING ELSE IS COMMON TO THEM. The schedule shipped first as unexported constants inside mobile/relay.go, which made it the PHONE's schedule -- and when the gateway hop finally got a reconnect there was nowhere to take the numbers from but a second copy. A budget that exists twice is two budgets. relay is the one package both the handset facade and the machine sidecar already import (it is on mobile's PB-BIND-0 allowlist), so putting the schedule here costs the bound handset no new dependency edge and gives the clause one home.

Section 6.0's transcription of these values is asserted directly, against literals, in mobile/pbnet4_backoff_test.go.

const CapabilityMailboxRecovery = "mailbox_recovery"

serverCaps is the relay's capability set; r_hello negotiates the intersection.

"wait" is the bounded server-side mailbox_wait (ADR-007 B7, PB-NET-5). It is advertised HERE, in the handshake the protocol has had all along, because the alternative was measured and rejected by the final-audit committee (finding H1): a client that has to PROBE the op learns "unsupported" only from a timeout, and a pre-wait relay's dispatch answers the unknown op with an ordinary in-order MsgError the client's parked waiter cannot correlate -- a stray reply that shifts the connection's request/reply pairing. With the capability advertised, a client never sends the op to a relay that did not claim it, and a reconnect to an upgraded relay re-evaluates for free. CapabilityMailboxRecovery is advertised by a gateway connection only when that gateway understands the destructive-mailbox-recovery command and will replace the compacted backlog with a roster reseed. The relay uses the negotiated capability on the CURRENT paired gateway session as a deletion fence; an old or disconnected gateway therefore cannot authorize a new phone to discard data it would not replace.

const DefaultCallTimeout = 10 * time.Second

DefaultCallTimeout bounds one authenticated request/reply exchange.

IT EXISTS BECAUSE SILENCE IS THE RELAY'S CHEAPEST ATTACK. The relay is the declared adversary and it need not misbehave to wedge a client: it can complete the websocket handshake, accept every frame, and reply to none. roundtrip holds c.mu across write-then-read and readFrame waits on the socket, so ONE unanswered exchange used to park every producer on the connection -- with no error, no state change and nothing to retry. A half-open TCP after a WiFi -> cellular handoff presents identically, so this is reached benignly as well as adversarially.

THE SAME BOUND THE GATEWAY ALREADY APPLIES TO THIS CLIENT, and for the same argument: remotegw's defaultAppendTimeout ("an UNBOUNDED append against a hung relay would pin that lock forever and wedge every producer AND Err()", Blocker 2). What that fixed was one caller; this fixes the client, so a call site nobody audited -- and every call site the phone has, which all pass context.Background() -- inherits the bound rather than the wedge.

TEN SECONDS IS §6.0'S, NOT THIS AUTHOR'S. The budget table binds "Non-wait request timeout | 10 s" to PB-NET-7 under a preamble that reads "Changing any value requires committee agreement, not implementer discretion" (docs/specifications/remote-phaseB-requirements.md). This constant first shipped at five seconds on latency grounds -- generous against PB-NET-5's 150 ms p50 and against push_trigger's one-second verdict wait, and matching App.awaitConn's five-second patience. Every word of that argument may still be true and none of it is this file's to make: a budget an implementer may re-derive locally is not a budget, and the row was NOT MET while the two disagreed (ADR-007 B99).

The 10 s used to live only as transport.RequestTimeout, in a package the shipped phone does not use -- so the value bound to a requirement existed exclusively in code nothing ran, which is the same defect as the fence-guarding-a-dead-path this constant was written to close. That package has since been deleted (B98), so this is now the ONLY place the budget exists at all, and TestCallDeadline_TheNonWaitRequestTimeoutIsTheCommitteeBudget pins it here, on the live path, so the next divergence is a failing test rather than a review round.

const DefaultDialTimeout = 10 * time.Second

DefaultDialTimeout bounds the CONNECT phase of every dial: the TCP handshake, the TLS handshake, the HTTP response and the websocket upgrade -- every stage before the first frame.

IT EXISTS BECAUSE THE DIAL HAPPENS BEFORE EVERY OTHER BOUND. DefaultCallTimeout bounds an exchange on an open connection and the gateway bounds its own MailboxWait, and NEITHER IS EVER REACHED by a caller still inside the dial. A relay that accepts the TCP connection and then stalls -- no ServerHello, no response head, a half-written 101 -- costs itself one file descriptor and parks its caller for as long as it cares to hold the socket. A half-open TCP after a WiFi -> cellular handoff presents identically, so this is benign as well as adversarial.

WHAT IT COSTS EACH SHIPPED CALLER, differently, and NOT ONE OF THE THREE declares a deadline:

THE PHONE never enters backoff. mobile/app.go passes context.WithCancel(context.Background()),
and App.run's reconnect schedule runs BETWEEN dial attempts -- a dial that never returns is a
dial that never fails, so PB-NET-4's backoff never runs once.

THE GATEWAY, cmd/swarm-remote, passes signal.NotifyContext(context.Background(), ...) and
starts by dialling, so a stalled dial is a sidecar that never starts and never says why.

THE PAIRING RENDEZVOUS burns the owner connection's pairing SLOT. internal/skeleton's
relayRendezvousFactory dials inside the closure BeginPairing calls, on the owner connection's
lifetime context -- and BEFORE pairing.go builds pairCtx, so ADR-007 B64's window is not yet
in force. The slot is already claimed and is released only by `result` or by BeginPairing's
error return; a dial that never returns takes neither, there is no pair_cancel op, and
dropping the owner connection is the only exit.

THE BOUND IS HERE, at the one seam every dial passes, and not at the callers. THREE callers exist and all three got it wrong independently -- and only two of them were known when this was written, which is the argument rather than a prediction about it: a per-caller fix would have been applied to the set we happened to know, and that set was wrong. It is also the quantifier B115 left open at the sibling defect ("fixing the one instance does not close a quantifier").

AND THE THIRD SITE SHOWS WHY THE CALLER IS THE WRONG PLACE even when it is remembered. The ctx relayRendezvousFactory receives has DUAL DUTY -- it bounds the dial AND owns the connection's lifetime, via the `go func(){ <-ctx.Done(); _ = conn.Close() }()` watcher three lines down -- so a caller-side `defer cancel()` there closes the connection it just returned. Bounding at this seam has no such hazard at any of the three.

TEN SECONDS IS SECTION 6.0'S, REUSED RATHER THAN RE-DERIVED. The connect phase IS one non-wait request/reply -- an HTTP GET carrying the upgrade, answered by a 101 -- and the budget table binds "Non-wait request timeout | 10 s" to PB-NET-7. Minting a second, local dial budget is what ADR-007 B99 refused.

AND THE COMPOSITION LANDS EXACTLY ON THE RELAY'S OWN PRE-AUTH WINDOW, which is the corroboration TestDialDeadline_TheWholeDialFitsTheRelaysOwnPreAuthWindow pins. A whole dial is this connect phase plus two non-wait requests (auth_init, auth_resp, each bounded at the same 10 s by DefaultCallTimeout) = 30 s; the relay bounds the SAME window from its own side at Config.HandshakeTimeout -- 30 s, "CUMULATIVE time-to-authenticate, anchored at accept time" (preAuthDeadline), one of the Phase A constants section 6.0's preamble names as the values its table is chosen to be consistent with. Past that instant an honest peer has already hung up.

ONLY THAT NUMBER IS BORROWED FROM THE ADVERSARY, never its enforcement. B112 recorded that exact error -- "MailboxWait bypasses it by construction under the relay's own 25 s ceiling", measured 2.8x past that ceiling -- and the deadline below is declared and enforced on this side, whatever the peer does.

WHAT IS STILL THE COMMITTEE'S TO SAY, recorded rather than decided here: section 6.0 has no row for a dial or a connect, so "the upgrade is one non-wait request" is a READING of an existing row, not a row. It is the narrowest reading available -- it mints nothing and it composes onto a constant already in the table -- but a committee that wanted a distinct dial budget would be setting it, not confirming this.

const DiagnosticCapabilityTTL = 5 * time.Minute

DiagnosticCapabilityTTL is the hard ceiling on a minted diagnostic capability's lifetime (playbook 6.5: "capability TTL <= 5 min, single-use"). It is enforced server-side against the relay's OWN clock; a capability carries no TTL of its own to claim a longer one.

"SINGLE-USE" IS ENFORCED IN PROCESS MEMORY ONLY (spendDiagNonce's diagUsedNonces, server.go), not the durable store — the same shape and the same reasoning as rendezvous burns (see burnWindow's comment). A relay restart forgets every spent nonce, so a capability spent just before a restart and still inside its TTL could, in principle, be replayed just after one. The blast radius stays tiny even so: replaying it buys nothing but a fresh, empty, per-connection diagnostic route bounded by maxDiagItems and mailboxPageByteBudget — never real mailbox content, never a routing id.

const GenericPushAlert = "You have a new secure message."

GenericPushAlert is the fixed, content-free outer alert the relay attaches to every push. It never carries a routing id, session id, or command text — the real content is the opaque ciphertext the app decrypts on-device (R-REL.5).

const MaxFrame = 1 << 20 // 1 MiB

MaxFrame is the largest legal declared frame length L (payload+1 tag byte), the anti-DoS cap enforced before any body allocation or read.

const ProtocolVersion = 1

ProtocolVersion is the current relay wire protocol version. r_hello negotiates it; a client offering an incompatible version is refused, not downgraded.

const PushEnvelopeSize = 78

PushEnvelopeSize is the ONE ciphertext length the relay puts on the push channel.

It is a SCHEMA, not a bound, and that distinction is the requirement. PB-PUSH-3 concedes that the provider observes token, timing and SIZE — and a conceded disclosure is benign only while it is CONSTANT. That property is quantified over the CHANNEL, so it is a promise the RELAY keeps and not one the gateway can keep alone: every producer reaching the provider must agree on one number, or the provider separates WHAT happened from THAT something happened without touching crypto — the exact defeat the two-tier wake/content key split exists to prevent (PB-KEY-2, ADR-007 B87, residual 4.23). A bound would not do it: the disclosure is a DIFFERENCE, not a magnitude, so a cap leaves every shape below it separable.

WHY THE RELAY REFUSES RATHER THAN PADS. It forwards the opaque envelope BYTE FOR BYTE and has to keep doing so (TestPush_RelaySeesOnlyCiphertext): padding would make the relay a party that edits ciphertext, and truncating would silently destroy a wake the phone then cannot open — with the loss surfacing as an AEAD failure on the one background path the phone has. Refusal is the only normalisation available to a party that holds no key, and a refused push puts nothing on the channel and so discloses nothing.

THE NUMBER is crypto's 62-byte cleartext envelope header plus a 16-byte AEAD tag over an EMPTY plaintext — the same constant as remotegw.PushWakeEnvelopeSize, which is the PRODUCER's side of it. This package cannot import remotegw (remotegw imports this one), so the two are pinned to each other by test rather than by the compiler: the reachability arm of TestPBPUSH3_AnUnschemadTriggerEnvelopeIsTheSameSizeOnTheChannel drives a remotegw.PushWakeEnvelopeSize envelope through push_trigger and requires it DELIVERED, so a relay that disagreed with the gateway would refuse every real wake and fail there.