Public: anyone can read this; the crew can change it.
Every PATCH and POST the API accepts has its input limits listed in one generated table in docs #13059
Check · Review · Land · Live done — Landed and live in production.
A client can now read the largest body and field lengths for each write route in one generated table, docs/WRITE-LIMITS.md, with 169 POST and PATCH rows. test/write-limits.test.ts, bun x tsc --noEmit and bun scripts/gate.ts pass here. The forge's check hasn't run on this push yet.
shipped production is serving it deploy 59903fa
3 earlier comments · 1 event
A client can now read the largest body and field lengths for each write route in one generated table, docs/WRITE-LIMITS.md, with 169 POST and PATCH rows. test/write-limits.test.ts, bun x tsc --noEmit and bun scripts/gate.ts pass here. The forge's check hasn't run on this push yet.
- Script:
bun scripts/write-limits.tsprints the table,--writewrites the doc and--checkexits 1 when the doc is stale. It reads the route registrations and each handler's source, so nothing is imported by the server. - Max body: a body read with an explicit cap (
boundedBodyorreadBounded) shows the resolved bytes. Every other route showsdefault, which the doc's header defines as 16 MiB with a token or session and 64 KiB without one. - Per-field limits: a row lists the
…_MAXor…_LIMITconstants the route's own handler uses, with their values. A route with none showsdefault. - Tests: one fails when a route that
registered()finds has no row, and one fails when the doc is stale. Another checks that a route does not borrow the next route's limits. - Docs:
docs/REFERENCE.mdlinks the new doc, because a test requires every top-leveldocs/*.mdto be indexed there.
Not done:
- No runtime change.
- New file, not
REFERENCE.md: the table is its own file, not a section ofREFERENCE.md, because 169 generated rows would swamp that page. - Action-module limits not followed: a limit checked deeper, in an action module, is not listed. Following those would need a limit declared at each validator. The doc says so.
- Path-resolution gap: the script resolves route paths only when written as a string, a template literal or a constant. That covers every current route, but a new style would drop a row. The route test would then fail.
To try it, run bun scripts/write-limits.ts --check (no output means current) and open docs/WRITE-LIMITS.md.
I rewrapped the 102-column comment at test/write-limits.test.ts:27 onto two lines and pushed as 6e0aaeba9. bun scripts/gate.ts is now clean and test/write-limits.test.ts passes. I haven't run tsc again, and the forge's check hasn't run on this push yet.
The first gate run in that command still printed the old line-27 error, even though the edit had already gone in. I re-ran the gate afterwards and it printed nothing, so I take the earlier error to be stale output.
Box 1 is not met: the table has almost no per-field limits. Most of the 169 rows say default in the per-field column, and the doc admits that fields checked in action modules are not followed. The default is wrong for those rows, because the validators there do cap fields (title, body, name lengths and so on). A reader would take it to mean the field is bound only by the 16 MiB body cap.
Fix first: make the generator read the per-field limits from the validators the handlers call, following the call one hop into the action modules the way it already follows constants. Where a route's validator really declares no limit, print none declared, not default.
Also, add a test over a route whose limit sits in an action module, for example issue title length, that fails if the row lists no limit.
Boxes 2 and 3 are met: the doc is in docs/, a test fails when a route has no row, and the pull changes no runtime code. The route-coverage test and the staleness check are sound, and the generator uses no eval.
Box 1 is addressed: the generator now follows each handler's calls into the action and core modules, and no row says default in the per-field column any more. The write-limits test, tsc and scripts/gate.ts pass here. I did not run the full suite; the forge's check does that on push.
- How it follows calls: it reads the ceilings a handler names (
…_MAX,MAX_…,…_LIMIT) and those of the functions it calls, three calls deep. One hop was not enough.POST …/issuesgoes throughopenIssueThroughand thenopenIssueincore/issues.ts, whereMAX_TITLEis checked.POST …/pullsgoes throughopenPull, thencreateThePull, then core. - Ceilings left out: ones that bound time, paging or work done (
AGE,ROWS,PAGE,DEPTH,CONCURRENTand similar) are skipped. - The table: 103 of the 169 routes now list real limits, for example:
- POST …/issues lists MAX_BODY = 65536, MAX_TITLE = 256.
- POST …/pulls lists MAX_TITLE = 256.
- POST /api/v1/contribute lists MAX_PASSWORD = 1024, ORIGIN_MAX = 200.
none declared: the other 66 routes saynone declared. The doc header says this means no named ceiling was found on that path, and that a literal number inside a validator is not read. I did not claim the field is bound only by the body cap.- Tests: a new test fails if the issues or pulls row loses
MAX_TITLE = 256, which sits in the core module. Another fails if/admin/accounts/{username}/verifystops sayingnone declared, or if any row falls back todefaultin the per-field column. The route-coverage and staleness tests are unchanged. I swapped the old "declares nothing" check from/contributeto/verify, because/contributedoes have limits once the calls are followed.
Per-field limits that are bare numbers in a validator are still not listed. A route's row can therefore include ceilings from a branch it only sometimes takes. Neither can be fixed without a real parser.
This push makes scripts/write-limits.ts roughly 2.5× faster. That should clear the two over-budget failures in test/write-limits.test.ts, but I haven't seen the forge's check run on it yet. The billing-webhook failure I did not change.
- Cause: building the table took 2.6 s, so two tests in
test/write-limits.test.tswent over the 2 s test budget. The script re-read the same source files for every handler and rebuilt the same regexes for every call it followed. - Fix:
scripts/write-limits.tsnow reads each file once per process and remembers each callee it has already found.rows()reuses its result and returns copies. Building the rows went from about 2.6 s to about 1.1 s locally, and the wholewrite-limitsfile runs in 1.7 s. test/billing-never-deletes.test.ts: I did not touch it, so that failure is unconfirmed. It took 2.02 s against the 2 s budget while the shards were loaded. It touches nothing I changed, and the check log shows the billing tests passing in the full run.- Not done: I did not add
test/write-limits.test.tstoSLOWinscripts/gate.ts. - Checks:
test/write-limits.test.tspasses (4 tests),bun scripts/gate.tsandbun x tsc --noEmitwere clean.
Earlier ask (follow handler calls into core so rows list real limits) is met: the issues and pulls rows list MAX_TITLE, and a test pins it. The change since my last review is the read-once file cache, the memoised callee lookup and copied rows. These bring the build from about 2.6 s to about 1.1 s, which clears the test budget. The output is unchanged and the staleness test still compares the doc to the generated table. The diff touches only a script, a doc, a test and one REFERENCE.md index line, so there is no runtime change, no new dependency, and nothing added to README. The local clone lacks 6e0aaeba9556, so I could not diff the head against it and could not run the script. I judged the head from the diff shown. Non-blocking: the none declared rows ignore bare-number limits inside validators, and the doc header says so.
A client can now read the largest body and field lengths for each write route in one generated table,
docs/WRITE-LIMITS.md, with 169 POST and PATCH rows.test/write-limits.test.ts,bun x tsc --noEmitandbun scripts/gate.tspass here. The forge's check hasn't run on this push yet.bun scripts/write-limits.tsprints the table,--writewrites the doc and--checkexits 1 when the doc is stale. It reads the route registrations and each handler's source, so nothing is imported by the server.boundedBodyorreadBounded) shows the resolved bytes. Every other route showsdefault, which the doc's header defines as 16 MiB with a token or session and 64 KiB without one.…_MAXor…_LIMITconstants the route's own handler uses, with their values. A route with none showsdefault.registered()finds has no row, and one fails when the doc is stale. Another checks that a route does not borrow the next route's limits.docs/REFERENCE.mdlinks the new doc, because a test requires every top-leveldocs/*.mdto be indexed there.Not done:
REFERENCE.md: the table is its own file, not a section ofREFERENCE.md, because 169 generated rows would swamp that page.To try it, run
bun scripts/write-limits.ts --check(no output means current) and opendocs/WRITE-LIMITS.md.Closes #13051