refactor(drawbridge): extract the v1 router so it can be tested

[macterra]

Why

drawbridge-api.ts built its Express app inside main(), which the module calls at import time. Importing it booted the server — connecting to Gatekeeper and Redis and binding a port — so its 28 v1 routes were untestable and uncounted. Same shape #705/#706 fixed for gatekeeper and keymaster.

What

• New v1-router.ts exporting createV1Router(options)
• New v1-admin.ts (createRequireAdminKey) and v1-router-types.ts, mirroring the gatekeeper layout
• drawbridge-api.ts builds its dependencies and mounts the router

Behaviour-preserving — and verified, not assumed

The route block was moved programmatically rather than retyped, then diffed against the original. The only difference:

- res.json({ version: serviceVersion, commit: serviceCommit });
+ res.json({ version: getServiceVersion(), commit: serviceCommit });

That change is required, not cosmetic. serviceVersion is a module-scope let reassigned after an async readFile of package.json; capturing it by value when the factory runs would pin /version to "unknown" forever. The getter preserves the original late-binding.

Checks:

• route set diffed before/after → 28 routes, identical
• tsc -p tsconfig.json clean for the service
• ARCHON_ADMIN_HEADER is used by the admin middleware and by the herald proxy for upstream auth, so it is exported from v1-admin.ts rather than duplicated

Tests

18 for the extracted router — capabilities derived from configured URLs, DIDComm endpoint including the null case, admin gating across 401 / 403-when-unconfigured / pass-through, resolve options passed only when present, numeric-vs-hash blockId parsing, a table-driven 502 check across every proxy route, a mid-stream read failure, and the lightning proxy's 501 / 200 / 502 paths.

11 for lightning-mediator-client — the router test transitively pulled that module into the coverage denominator at 5.9%, so leaving it would have dragged the number down for nothing. Now covered: request shaping, admin header, error mapping to LightningUnavailableError, the 404-means-null case, and percent-encoding of payment hashes.

Result

file	coverage
v1-router.ts	98.1%
v1-admin.ts	100%
lightning-mediator-client.ts	5.9% → 100%
drawbridge/server	6 files instrumented → 10 at 99.0% (509/514)
repo total	96.47% → 96.52%

Total rose despite ~200 lines entering the denominator. Suite: 1,778 passing, 0 eslint errors (1 pre-existing warning in l402-auth.ts, present on main).

One thing worth a second opinion

Three one-line L402 delegation routes are deliberately left uncovered. Driving them with a stub l402Options leaves one handler never sending a response, which hangs Jest — and since CI runs without --forceExit, that is a silent workflow hang rather than a failed test. Their handlers are already at 100% via l402-auth.test.ts, and a comment in the test records why.

Separately: a handler that silently never responds is arguably a production issue too — a malformed-options request would hang the client instead of erroring. I have not chased which handler or whether it is reachable with real config; it may well be unreachable. Flagging rather than fixing, as it is outside this refactor.

Follow-up

services/herald/server/src/index.ts (1,490 lines) has the same module-scope-app problem and is the remaining blocker for covering herald. Worth its own PR.

🤖 Generated with Claude Code