verifier-service-socket

name	verifier-service-socket
description	Boot a vers domain service as a real process and drive its RPC endpoints over HTTP — for changes the in-process test client bypasses (serve entrypoint, env wiring, transport middleware, error serialization, trace propagation).

Verifying a domain service at its socket

When to reach for this

The bun test suites boot the real service factory against a real postgres and call procedures through buildRPCTestClient with real token verification, so procedure logic, auth, and declared errors are verified there. Socket verification covers what that in-process client never executes:

• the src/serve.ts entrypoint and its env wiring (DATABASE_URL, SERVICE_AUTH_JWKS, PORT) and GET /health
• wire-format contracts: the serialized error envelope, x-trace-id response headers, traceparent continuity
• per-request side effects of the central onError interceptor (Sentry reporting, pino output)
• connection-phase database behaviour

For procedure and business-logic changes, the test suite is the verification — skip this pass.

Database

Boot recipe that works with only the pg test container running (bun run pg:test-container:start; container publishes 5432 on a random port — find it with docker ps, credentials test:test, template database test_template).

Clone the migrated template instead of standing up the dev stack:

docker exec <container> psql -U test -d postgres -c "CREATE DATABASE verify_db TEMPLATE test_template"

Seed rows with docker exec <container> psql -U test -d verify_db -c "INSERT …". Drop the clone when done.

Gotcha: an unreachable database or a connection-phase failure (bad database name, wrong port) crashes the service process via a postgres@3.4.5 error-path bug (query.origin.replace on undefined) instead of rejecting the query — point the service at a database that accepts connections.

Credentials

Services validate s2s tokens against SERVICE_AUTH_JWKS — a JSON key set holding each minting issuer's public key under an issuer-named kid (app-web, service-activity, service-replay). Mint a throwaway keypair + tokens with a scratchpad script using jose: generateKeyPair('EdDSA') → exportJWK, wrap as {"keys":[{...jwk, kid: "app-web"}]}, then SignJWT with protected header { alg: 'EdDSA', kid: 'app-web' }, issuer equal to the kid, audience = service name (service-user), and sub for an acting user (omit sub for anonymous). The service rejects a token with a 401 when its iss isn't a registered issuer, doesn't equal its kid, or a different issuer's key signs it.

Boot and drive

cd services/<name>
DATABASE_URL="postgresql://test:test@127.0.0.1:<port>/verify_db" PORT=3399 \
  SERVICE_AUTH_JWKS="$(jq -r .jwks creds.json)" bun src/serve.ts &

Endpoints: GET /health (no token), POST /rpc/<procedure> with authorization: Bearer <token>, content-type: application/json, body {"json":<input>}. Responses carry x-trace-id; send a traceparent header to assert trace continuity. Error bodies are {"json":{"defined":…,"code":…,"status":…,…}}.