Deterministic reconnect routing: a transfer marker from RedirectFix

[Pixnop]

Follow-up to #57. The IP-keyed sticky being implemented there is the right compatible fix, but it is a heuristic, and the NAT corner cases are managed rather than eliminated. The durable answer is to make the reconnect itself carry the routing information, which is possible now that RedirectFix lives in this org.

The gap. After a redirect, the reconnecting client's first frame is LoginTokenQuery, which carries nothing. The proxy must pick the destination backend before any backend sees a byte (the token exchange binds the session to whichever backend answers, see #57), and at that moment it only knows the source address. Everything else is inference.

Option A, a transfer marker from RedirectFix. RedirectFix already patches the redirect path client-side. On ExitAndSwitchServer it can remember the transfer, and on the reconnect send one tiny frame before LoginTokenQuery: an unused packet id carrying the transfer correlation id. The proxy sniffs frame one, consumes the marker (never forwards it), routes deterministically, and proceeds. The natural payload already exists: ClientTransferId from the seamless handshake plumbing (#39), staged proxy-side at redirect time. Old RedirectFix clients simply fall back to the IP sticky, so the fleet can upgrade at its own pace.

Option B, routing by dialled address. Give each backend its own player-facing port (or subdomain) on the proxy, stamp it into the redirect packet via transfers.redirect_address (#38), and route reconnects by which listener they arrive on. No identity needed at all, NAT-proof by construction. Two costs: RedirectFix must start honouring the stamped address (today it ignores it and reconnects to the cached one), and operators must expose a port per backend, which is real friction on panels and firewalls.

Why A is the better first move. It needs no operator-side changes, it reuses an existing correlation id, and it degrades gracefully. B has one unique virtue though: it is exactly the path a future fixed vanilla client will take when it follows the stamped address literally (#18), so whatever we do for A should not paint over B. Concretely: keep redirect_address stamping correct and consider B again the day the vanilla fix ships.

Scope for A, roughly: pick an id for the marker that vanilla will never send (coordinate with the client mod work), stage the expected marker alongside the sticky at redirect time, teach the first-frame path to recognise and strip it, extend RedirectFix to emit it, and version the behaviour so mixed fleets stay coherent. The proxy-side sniffing already has everything it needs; the sensitive part is choosing the marker shape so it can never be confused with a real first frame.

[Pixnop]

Design for option A, for review before anything is built, same drill as #54 and #43. The issue's framing stands; this fills in the marker shape, the announcement channel, and the compatibility matrix, which are the places a mistake becomes a fleet-wide incident.

The problem inside the problem

The marker cannot be a frame a vanilla server ever sees. RedirectFix works standalone on non-proxied networks (that is its mod DB pitch), and its reconnect goes to whatever address it cached, which on those networks is a vanilla server that will not tolerate an unknown first frame. So the client may only emit the marker when it KNOWS the other end understands it, which means the redirect itself has to announce that. Choosing an "unused packet id" does not solve this; it just moves the crash from a parse error to an unknown-packet handler we do not control.

The announcement: a tag in the redirect's display name

Nimbus already forges the redirect packet (RedirectBuilder), and its displayName field is cosmetic to the client. The proxy appends a suffix after a delimiter no server name uses: <name>\u001Fnmbs1:<id>. RedirectFix strips everything from the delimiter on before any UI sees it, and remembers the id for the reconnect. A vanilla client on the same network never renders it today (it crashes on redirect before UI, which is why RedirectFix exists), and the day the vanilla fix ships (#18), option B's dialled-address routing is the plan anyway and the tag can retire. Old RedirectFix versions show a suffix in a screen nobody sees and reconnect exactly as before: degraded to today, never worse.

The marker frame

Sent only when a tag was seen, as the very first bytes of the reconnect, BEFORE any Vintage Story framing: magic 4E 4D 42 53 ("NMBS"), one version byte, one length byte, then the id (16 bytes). Twenty-two bytes, never forwarded. The proxy's first-frame reader already buffers before choosing a backend; it checks the magic, consumes the marker, and hands the REST of the stream (starting at the real LoginTokenQuery) to the existing path. By construction this can never be confused with a VS frame, and by the announcement rule it can never reach a server that does not speak it.

Staging and resolution

The id is the ClientTransferId already minted into the reservation at redirect time (#39 plumbing); the sticky route staged at redirect gains it as a third key next to uid and client address. Resolution order on a reconnect becomes: marker id (exact), then the existing uid and IP heuristics as fallback, untouched. Single use, same TTL as the uid sticky, and the existing Identification-time reconcile stays as the final check, so a marker that lands in the wrong hands routes to a backend whose auth gate the holder still cannot pass; the id is a routing hint, never a credential, 128 bits random, logged only as a prefix.

Compatibility matrix

New proxy + new RedirectFix: deterministic routing, NAT ambiguity gone. New proxy + old RedirectFix: no marker sent, today's heuristics, unchanged. Old proxy + new RedirectFix: no tag seen, no marker sent, unchanged. Standalone RedirectFix on a vanilla network: no tag ever, zero behavioral change, the standalone pitch stays true. Vanilla client anywhere: nothing changes anywhere.

Sequencing

Nimbus ships first (tag stamping plus marker consumption are harmless alone), RedirectFix 1.1.0 second, each with tests on its side: proxy tests drive a fake client sending tagged reconnects through the RecordingBackend harness; RedirectFix gets the strip-and-remember and the emit-only-when-tagged cases. Option B stays alive exactly as the issue says: transfers.redirect_address stamping remains correct so the #18 future keeps its path.

Open questions: the delimiter (\u001F unit separator is my pick, but anything provably absent from server display names works), whether the marker should also carry the target serverId as a cross-check against the staged route, and whether RedirectFix should expire its remembered id (I lean yes, 60 seconds, matching the IP sticky's TTL).