Unify the routable-token grammar in one module

What does this MR do and why?

The routable-token grammar has no single source of truth. It is transcribed as a regex into each of the ten rules in config/ruleset/session_token.json that decode a token, again into nine fixtures, and now a twentieth time into the patterns decodeRoutableToken added in !1384 (merged), the MR this one is stacked on. The copies have already drifted:

config/ruleset/ test/fixtures/
version segment pinned \.01\. any [0-9a-z]{2}

Both spellings arrived in the same commit, bd49e7f (2025-04-22), and have sat apart since. A fixture that accepts tokens production rejects validates a grammar that does not ship, which is the slack that let this sit unnoticed.

src/routable_token.ts now owns the grammar: the charset, the {27,320} bounds, the pinned version and the two suffix sources every decoding rule ends with. decodeRoutableToken's own two patterns are rebuilt from those constants rather than spelled out, so the module cannot drift from itself either; the five fixtures and the two inline copies in test/rule.spec.ts are pinned to 01 to match production. test/helper.ts mints only v01, which is also why the drift was never exercised.

Version 01 is pinned rather than widened into the rules. Decoding an unrecognised version as v01 yields a wrong cell id or a throw, and a throw inside the rule engine is a fleet-wide 400 with no flag in front of it. Pinning costs a fall-through to the Legacy Cell, which is where every request the router cannot classify already goes. The day v02 is real it is one constant in one file.

Drift is enforced by test/routable_token.spec.ts, which asserts every decoding rule in config/ruleset/ and test/fixtures/ ends with the shared suffix: nineteen cases today, globbed so later additions are covered on arrival, with a canary so a glob resolving to nothing cannot make them all pass vacuously. Not codegen, because the rules legitimately differ ahead of the suffix by prefix (Bearer , glrtr?-, pat:<id>:) and by payload bound, and config/ruleset/ is human-edited operational config people open during incidents. The grammar constants are only worth the indirection because of this test: without something holding the copies together, tidier internals change nothing about whether the ten rules and the /jwt/auth handler agree.

No behaviour change to a shipping path. config/ruleset/ is untouched and the two patterns are .source-identical to the literals they replace; only fixtures and test-local copies tighten.

npm test 36 files / 445 tests → 36 / 465. tsc --noEmit, eslint ., prettier --check and npm run jsonnet-test clean.

References

How to set up and validate locally

  1. npm test covers all of it; nothing here needs a running stack.
  2. npx vitest run test/routable_token.spec.ts for the grammar unit tests plus the drift check.
  3. To see the drift check bite: set ROUTABLE_TOKEN_VERSION to '02' and re-run. Twelve of the nineteen cases fail, the routable-token-payload ones, six in the ruleset and six in the fixtures, each naming itself and saying to fix the rule. The seven routable-json cases carry no version segment and stay green.

MR acceptance checklist

Please evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Sangwoo Han

Merge request reports

Loading
Loading