Field report: rebuilding a production API on Rockets v8 — findings and parity backlog
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 25/100
- Issue type
- Feature
- Clarity
- Needs clarification
- Activity status
- Active
- Tech stack
- firebase, typescript
- Domain
- backend-api-design
Research direction
Treat this as a tracking report rather than a single implementation task. Read the evidence for #43, #44, and #45, then choose one named backlog entry such as the zod input/output path, RocketsCoreExceptionsFilter, TransactionScope, or the JOB_DISPATCHER token. Done should be defined by a separately scoped issue with tests and reference behavior identified.
Written by the indexing model from the issue text.
Description
Field report: rebuilding a production API on Rockets v8 — findings and parity backlog
Tracking issue. We rebuilt a real production API (real-estate analytics: MLS proxying, valuation math, AI report generation, chat with tool calls, video rendering) on Rockets v8 twice, to separate two questions:
- A — frozen contract: reproduce the existing HTTP contract byte-for-byte, front end untouched. 47 routes, 225 e2e, router diff against a frozen
contract.jsonwith an empty allowlist, and the front end's own Zod.strict()schemas validating the new responses (18/18). - B — contract free: use the framework to its ceiling — generated CRUD, CQRS commands/events, zod everywhere, contract redesigned where the framework earns it. 52 routes, 249 e2e, front end adapted.
Headline results
| Measure | Legacy | A · frozen | B · max |
|---|---|---|---|
| Framework-generated routes | 0 | 5/47 (10.6%) | 19/52 (36.5%) |
| Server source LOC | 29,497 | 28,710 | 31,177 |
| Handwritten code deleted | — | — | 1,400 LOC (7 files) |
| e2e | — | 225 | 249 |
| Front-end change | — | none | 23 files, +735/−300 (≈1/6 of the API-side cost) |
Interpretation we would stand behind: Rockets pays clearly where the surface is owned-entity CRUD, and does not compress analysis/proxy/streaming surfaces — 2/3 of this product. Contract freedom tripled generated routes but did not change that shape; what limits it is the closed operation set, not the contract.
Filed from this study
- #43 — non-CRUD operations as first-class (the single highest-impact item; ~10 of our handwritten routes would convert). Commented with second-phase evidence.
- #44 —
rockets-repository-firestoreparity plan to become a production store of record. This decided our architecture: we chose TypeORM before writing a line, purely because the zod entity compiler is TypeORM-only and the Firestore adapter has no cross-entity transactions — the four transactional behaviors this product needs (fail-closed rate limiting, idempotent job enqueue, chat turn lock, render lease) had produced 9 raw-SDK bypasses in an earlier POC. - #45 —
ctxomission silently disables entity hooks and escapes the operation's transaction. Found via a real defect: an expired parent record still minted working public share links.
Backlog — not yet filed, evidence and reference implementations available
Each item below cost us handwritten code in both builds, i.e. contract freedom did not remove it. We have working, e2e-pinned implementations of all of them and are happy to extract any as a starting point.
-
input/outputon the zod path.ZodResourceDefinition extends Omit<…, 'entity' | 'dto' | 'operations'>, so the class path gets per-operation input/output DTOs and the zod path does not. Today you choose between controlled projection and automatic OpenAPI. (Small.) - Pluggable error envelope.
RocketsCoreExceptionsFilterhardcodes{statusCode, errorCode, message, timestamp}incatch()and both unwrap helpers areprivate, so an app with its own envelope re-implements the whole filter to change three keys — while needing to preserve thecontext.originalErrorunwrap chain (miss it and every hook 409 becomes a 500). Proposal: a serializer strategy +protectedunwrap helpers. (Small.) - Global rate limiting. The framework ships only an auth-route throttler. Every serious app writes a policy→route limiter; ours is a fail-closed fixed-window store over
@InjectDynamicRepository+TransactionScope. (Medium.) - Background job port. No dispatch abstraction (named tasks, dedupe, lease/heartbeat, at-least-once). Ours is a
JOB_DISPATCHERtoken with an in-process implementation for tests and Cloud Tasks in deploy. (Medium.) - Session-cookie auth + CSRF + ternary route policy, for apps whose identity is external (Firebase/Auth0/Clerk).
rockets-adapter-firebaseexposes onlyverifyIdToken— noverifySessionCookie, no cookie minting; there is no CSRF anywhere; and route policy is binary (@AuthPublic()vs protected) where we neededpublic | internal | session. With external identity, ~100% of auth is app code. (Medium; two ~100-LOC adapters is the whole recipe.) - Transport primitives: SSE and Range. Zero framework support; three domains (chat, video, PDF) stayed fully app-owned in both builds. Note SSE cannot be expressed in OpenAPI — the route and body DTO can, the framing cannot. (Large.)
- Discoverability of the non-CRUD transaction seam.
transactional: trueexists only on CRUD operations; custom guards/services must discover upstreamTransactionScope+ per-call{ ctx }. Cost us 45 min of source spelunking and is the root of #45. (Docs.) - Ecosystem pinning.
@nest-mcp/serversupports ≤ Nest 11, so an MCP surface on Nest 12 alpha requires reimplementing the streamable-HTTP transport. (Ecosystem.)
Notes on method
Friction, bypasses and gaps were logged at the moment they happened, not reconstructed: 40+ friction entries, 39 bypass rows (each with an "could Rockets absorb this?" verdict), 54 gaps. Both builds were audited by an adversarial reviewer that ran the gates itself and rejected reported results; both came back REVISE and both work orders were executed before these numbers were published.
Two findings we would highlight for the maintainers, because neither was visible in a green test suite:
- the
ctxchain in #45, and - a repository call inside a hook that appeared transactional (and was documented as such) while committing outside the operation.
Happy to open any backlog item as its own issue on request, or to hand over the reference implementations.
- Dominant language
- TypeScript
- Stars
- 1
- Forks
- 2
- PR merge metrics
- No merged PRs in 30d
Getting set up
Starts the project's dev container in your browser, under your own GitHub account.
- No Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from btwld/rockets
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
-
question
Difficulty 4/5 3-5 days Newbie friendliness 45/100
-
bug
Difficulty 4/5 3-5 days Newbie friendliness 52/100
-
question
Difficulty 5/5 Over a week Newbie friendliness 35/100
-
bug
Difficulty 5/5 Over a week Newbie friendliness 45/100
Similar issues
-
community first-timers-only good first issue hacktoberfest help wanted low hanging fruit up-for-grabs
Difficulty 1/5 Under an hour Newbie friendliness 92/100
lingdojo/kana-dojo#34449 · 1 comment · 5 reactions ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
drizzle-team/drizzle-orm#6726 ·
Maintainers usually reply within 2 days
-
bug platform-desktop platform-windows
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
Termix-SSH/Termix#1951 · 2 comments ·
Maintainers usually reply within 1 day
-
Grok provider voice list shows 5 of xAI's 28 built-in voicesPossibly taken @hkjarral claimed this today. Open
Difficulty 2/5 1-3 hours Newbie friendliness 80/100
hkjarral/AVA-AI-Voice-Agent-for-Asterisk#883 · 1 comment ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 70/100