The testSpeed knob

Last updated Jun 14, 2026

Real Delaware filings take 1–3 business days. Real ACH transfers settle T+1 to T+3. Real EIN issuance can take a week. Test mode gives you a knob to compress these waits to seconds, fractions of a second, or skip them entirely — without changing the shape of any other request.

The header

Every async test-mode endpoint accepts X-Matter-Test-Speed:

Live-mode bearers passing this header receive 400 invalid_header_for_live_mode. The header has no effect on synchronous endpoints (e.g. POST /v1/entities returns 201 inline regardless of speed).

Which endpoints honour it

Every service that has an async pipeline implements the same knob. The pattern is intentional — once you know how submit-entity handles it, you know how bank-transfer handles it.

Endpoints not in this table either complete synchronously (no real-world wait to simulate) or aren't yet wired through the knob (tracked in the project's banking / board / mail rewrites).

How it works under the hood

Service-layer functions accept testSpeed as a request-body field (translated from the header by the HTTP shell). The default is instant for test-mode bearers; live-mode bearers ignore the field and always enqueue.

// inside @repo/banking-service/src/create-transfer.ts (excerpt)
const testSpeed = args.auth.livemode ? undefined : body.testSpeed ?? "instant";
const willSimulateInline = !args.auth.livemode;

if (willSimulateInline) {
  // Adjust balances atomically inside the same transaction as the
  // transfer row's status update. Source decrement, destination
  // increment — both balances are correct on the response.
  await tx.bankAccount.update({ … decrement … });
  await tx.bankAccount.update({ … increment … });
  return tx.bankTransfer.update({ … settled … });
}

// Live path: stop at `submitted`. The queue worker drives `settled`
// once the upstream provider confirms.

The three speeds aren't three completely separate code paths — they're the same path with a different executeAfter on the BackgroundJob row. instant skips the queue entirely; fast runs the queue handler inline with a 1s delay; real schedules the job with a delay that matches real-world turnaround for that resource type.

Adding the knob to a new resource service

When you add an async pipeline to a new resource, follow this checklist:

1. Add testSpeed: z.enum(["real", "fast", "instant"]).optional() to the create-request Zod schema.
2. In the service function:
   • Compute testSpeed = auth.livemode ? undefined : body.testSpeed ?? "instant".
   • Branch on willSimulateInline = !auth.livemode (which is true whenever testSpeed resolved to anything — only live mode hits the queue unconditionally).
   • Under instant, write the terminal state inline in the same transaction.
   • Under fast, wrap the same write in setTimeout(1000).
   • Under real, enqueue a BackgroundJob with executeAfter = now + <real-world delay>.
3. In the HTTP shell:
   • Read X-Matter-Test-Speed from the request header.
   • Reject with 400 invalid_header_for_live_mode when auth.livemode === true && header set.
   • Forward the header value as the request-body testSpeed field into the service call.
4. In the BackgroundJob handler:
   • The handler is the same code regardless of speed — it's just invoked at different cadences. The handler is mode-aware and calls the right provider (DemoFilingProvider / DemoBankingSimulator / LiveFilingProvider).

The pattern is in packages/entity-service/src/submit-entity.ts. Lift it for new services rather than re-inventing the dispatch logic.

See also

• Test, sandbox & live mode — the overall mode contract.
• Webhooks — how the speed knob interacts with the webhook fan-out (deliveries fire when the simulator settles, just like live).
• Idempotency — replaying the same key under different speeds is still a replay; the key is the source of truth for "have I processed this?", not the speed.