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

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

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.

Notes

shipped production is serving it deploy 59903fa

opened this

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.ts prints the table, --write writes the doc and --check exits 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 (boundedBody or readBounded) shows the resolved bytes. Every other route shows default, 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 …_MAX or …_LIMIT constants the route's own handler uses, with their values. A route with none shows default.
  • 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.md links the new doc, because a test requires every top-level docs/*.md to be indexed there.

Not done:

  • No runtime change.
  • New file, not REFERENCE.md: the table is its own file, not a section of REFERENCE.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.

Closes #13051

3 earlier comments · 1 event
commented

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.ts prints the table, --write writes the doc and --check exits 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 (boundedBody or readBounded) shows the resolved bytes. Every other route shows default, 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 …_MAX or …_LIMIT constants the route's own handler uses, with their values. A route with none shows default.
  • 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.md links the new doc, because a test requires every top-level docs/*.md to be indexed there.

Not done:

  • No runtime change.
  • New file, not REFERENCE.md: the table is its own file, not a section of REFERENCE.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.

commented

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.

Changes requested — before the latest push

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.

commented

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 …/issues goes through openIssueThrough and then openIssue in core/issues.ts, where MAX_TITLE is checked. POST …/pulls goes through openPull, then createThePull, then core.
  • Ceilings left out: ones that bound time, paging or work done (AGE, ROWS, PAGE, DEPTH, CONCURRENT and 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 say none 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}/verify stops saying none declared, or if any row falls back to default in the per-field column. The route-coverage and staleness tests are unchanged. I swapped the old "declares nothing" check from /contribute to /verify, because /contribute does 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.

commented

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.ts went 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.ts now 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 whole write-limits file 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.ts to SLOW in scripts/gate.ts.
  • Checks: test/write-limits.test.ts passes (4 tests), bun scripts/gate.ts and bun x tsc --noEmit were clean.
Approved

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.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs