router: a stale-epoch client Request gets an error frame instead of silence

Merged
IC
3mo ago
+90-1

Closes the client half of #39. A Request dropped for a stale route epoch now tells the caller, using the stale_route_epoch code whose SDK handling you pre-landed in db91a7c.

The change

router.rs, the DataRoute::Client(DataRouteState::EpochMismatch) arm: emit an error frame for FrameType::Request, counter retained. New RouterError::StaleRouteEpoch, rendered exactly as its UnknownChannel neighbour ten lines down — which was the sibling that made this an oversight rather than a policy.

The retry-safety property is why the distinct code was worth it: an epoch mismatch means the daemon dropped the frame before delivery, so the request is provably not-forwarded and unambiguously safe to retry. That was computed at the drop site and discarded.

Verification

  • cargo test --workspace — 39 binaries ok; clippy and fmt clean.
  • Mutation proof: removing only the emission makes client_request_with_mismatched_route_epoch_emits_stale_route_epoch_without_forwarding fail by timeout — the test reproduces the defect exactly as a caller experiences it, rather than by assertion mismatch.
  • Round trip confirmed: the literal stale_route_epoch is byte-identical in router.rs, crates/subc-client-rs/src/consumer.rs, and clients/subc-client/src/client.ts. Both SDK sites go live the moment this merges.

Note on the test-binary count: an earlier run reported 38 against my stated ≥39 baseline. I re-ran on the committed branch and measured 39. Transient, not a lost binary — flagging since I raised it on the issue.

Scope — the module direction is deliberately not here

I originally wrote that the module-direction sibling was probably fine. That was wrong, and my implementer refuted it rather than following the instruction: reverse requests are a shipped path that awaits a response (clients/subc-client/src/provider.ts:462; subc-mcp's handle_reverse_request/send_reverse_response), so a module issuing one against a stale epoch hangs exactly as a client did. The module arm is also blunter — it drops every frame type with no FrameType::Request discrimination at all.

I've laid out three scope options on #39 (widen this PR / merge this and file the module half / emit-now-SDK-later) and lean on merging this half now, because the module fix needs module-side SDK classification that doesn't exist yet (provider.ts has no unknown_channel/stale_route_epoch handling) and deserves its own review. Happy to widen this PR instead if you'd rather have it in one piece — say which and I'll follow.


View with [code]smith Autofix with [code]smith
Need help on this PR? Tag @codesmith with what you need. Autofix is disabled.


Summary by cubic

Client requests sent with a stale route epoch no longer hang silently. The router now emits an Error frame with code stale_route_epoch for dropped Request frames, making them safe to re-bind and retry.

Review and rollout

  • Router: in DataRoute::Client(EpochMismatch), emit stale_route_epoch for FrameType::Request only; keep the drop counter behavior; module-direction handling is unchanged.
  • New error: RouterError::StaleRouteEpoch serializes identically to unknown_channel neighbors and uses code stale_route_epoch.
  • Tests: add an integration test that the request is not forwarded (no module event), the client receives the error promptly, and a live-epoch request still succeeds.
  • Docs: add stale_route_epoch to the protocol error code set with retry guidance.
  • Migration: none required. Clients should re-bind and retry the request once on stale_route_epoch. SDK handling is already present in crates/subc-client-rs and clients/subc-client.