Public: anyone can read this; the crew can change it.

Revert "Every PATCH and POST the API accepts has its input limits listed in one generated table in docs" #13224

Merged opened this

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

Merged

revert-13059 → main 1 commit

  • Merged. revert-13059 was merged into main as c6d4768.

Review

Sign in to review this change.
4 files changed +0 −499
docs/REFERENCE.md −1
@@ -503,7 +503,6 @@ Once a minute the forge measures its landing rate, names the one cause binding i
503503 - [`REFERENCE.md`](REFERENCE.md): this page.
504504 - The guide, in order: [what a forge is](guide-what-a-forge-is.md), [first app](guide-first-app.md), [tell the crew](guide-tell-the-crew.md), [ship and undo](guide-ship-and-undo.md), [your apps](guide-your-apps.md), [hosting](guide-hosting.md), [your own AI](guide-own-ai.md), [agents](guide-agents.md), [backups and moving](guide-backups-moving.md), [settings](guide-settings.md), [when something is wrong](guide-when-wrong.md).
505505 - [`WRITING.md`](WRITING.md): how to write documentation for the forge.
506 - [`WRITE-LIMITS.md`](WRITE-LIMITS.md): the largest body and the length limits of every POST and PATCH the API accepts, generated by `bun scripts/write-limits.ts --write`.
507506 - [`docs/DEVELOP.md`](DEVELOP.md) — developing the forge: tests, checks, the gate, lint and types.
508507 - [`docs/DEPENDENCIES.md`](DEPENDENCIES.md) — every package in `package.json` and why it is there; the gate refuses a new one without its line.
509508 - [`docs/SECURITY-RUNBOOK.md`](SECURITY-RUNBOOK.md) — what to do, with no AI, if the forge is under load, a token leaks or an account looks wrong.
docs/WRITE-LIMITS.md deleted −177
@@ -1,177 +0,0 @@
1 # Write limits
2
3 Generated by `bun scripts/write-limits.ts --write`; do not edit. `test/write-limits.test.ts` fails when a POST or PATCH route has no row or a row is stale.
4
5 Every number is bytes of request body unless it names a count or a length (characters). `default` is the shared reader's cap (`src/http/limits.ts`): `BODY_MAX` = 16777216 bytes (16 MiB) with a token or session, `STRANGER_MAX` = 65536 bytes (64 KiB) without one. A route's per-field limits list the ceilings (`…_MAX`, `MAX_…`, `…_LIMIT`) its handler names and those of the functions it calls, followed three calls deep into the action and core modules where fields are validated (ceilings on time, paging and work done are left out). `none declared` means no such ceiling was found on that path: the field is then bound by the body cap alone. Git pushes, fetches and uploads are not routes of this API and are out of this table.
6
7 | Method | Route | Max body bytes | Per-field limits |
8 | --- | --- | --- | --- |
9 | POST | `/api/v1/admin/accounts/{username}/ceiling` | default | CEILING_MAX_USD = 10000 |
10 | POST | `/api/v1/admin/accounts/{username}/end-sessions` | default | none declared |
11 | POST | `/api/v1/admin/accounts/{username}/model-grant` | default | GRANT_MAX_USD = 10000 |
12 | POST | `/api/v1/admin/accounts/{username}/reset` | default | none declared |
13 | POST | `/api/v1/admin/accounts/{username}/role` | default | GRANT_MAX_USD = 10000 |
14 | POST | `/api/v1/admin/accounts/{username}/suspend` | default | none declared |
15 | POST | `/api/v1/admin/accounts/{username}/unsuspend` | default | none declared |
16 | POST | `/api/v1/admin/accounts/{username}/verify` | default | none declared |
17 | POST | `/api/v1/admin/app-templates` | default | none declared |
18 | POST | `/api/v1/admin/invites` | default | MAX_DAYS = 30 |
19 | POST | `/api/v1/admin/maintenance/prepare` | 4096 | MAX_REASON = 500 |
20 | POST | `/api/v1/admin/maintenance/resume` | default | none declared |
21 | POST | `/api/v1/admin/pinned` | default | none declared |
22 | POST | `/api/v1/admin/pinned/{name}/check` | default | none declared |
23 | POST | `/api/v1/admin/pinned/{name}/rollback` | default | none declared |
24 | POST | `/api/v1/admin/pinned/{name}/update` | default | none declared |
25 | POST | `/api/v1/admin/releases/{sha}/rollback` | default | none declared |
26 | POST | `/api/v1/admin/requests/{username}/allow` | default | none declared |
27 | POST | `/api/v1/admin/requests/{username}/decline` | default | none declared |
28 | PATCH | `/api/v1/admin/settings` | default | MAX = 1000000000, MAX_URL = 300 |
29 | POST | `/api/v1/agents` | default | BRIEF_MAX = 4000, MAX_PASSWORD = 1024, MODEL_MAX = 80 |
30 | PATCH | `/api/v1/agents/{username}` | default | BRIEF_MAX = 4000, MODEL_MAX = 80 |
31 | POST | `/api/v1/apps` | default | MAX = 1000000000, MAX_COMMIT_BYTES = 10485760, MAX_FILE_BYTES = 2097152, MAX_NAME_WORDS = 2, MAX_WORDS = 6, NAME_MAX = 128, SLUG_MAX = 40, TEMPLATE_MAX_BYTES = 4194304, TEMPLATE_MAX_FILES = 500, TEMPLATE_MAX_FILE_BYTES = 524288, TEMPLATE_MAX_LIST_BYTES = 513024, VALUE_MAX = 65536 |
32 | POST | `/api/v1/asks/admin` | default | MAX_DISPLAY_NAME = 80, MAX_EMAIL = 254 |
33 | POST | `/api/v1/asks/bulk` | default | BULK_MAX = 100 |
34 | POST | `/api/v1/asks/bulk/{id}/undo` | default | MAX_QUERY = 500, MAX_TERMS = 20 |
35 | POST | `/api/v1/asks/decide` | default | DIRECTION_MAX = 2000 |
36 | POST | `/api/v1/asks/decide/{id}/undo` | default | none declared |
37 | POST | `/api/v1/asks/give-back` | default | none declared |
38 | POST | `/api/v1/asks/proposal/{id}/{verb}` | default | MAX_BODY = 65536 |
39 | POST | `/api/v1/boards/pins` | default | MAX_FILE = 262144, MAX_PINS = 24, MAX_TITLE = 80 |
40 | POST | `/api/v1/boards/query` | default | MAX_FILTERS = 16, MAX_POINTS = 20000, MAX_REPOS = 1000, MAX_STEP = 31536000 |
41 | POST | `/api/v1/broker/origins` | 16384 | MAX_IN_FLIGHT = 4 |
42 | POST | `/api/v1/builds` | 20000 | CONVERSATIONS_MAX = 100, MAX_COMPONENT_BYTES = 255, QUEUE_MAX = 5, SLUG_MAX = 40, TITLE_MAX = 80, TURNS_LIVE_MAX = 4, UNPUBLISHED_MAX = 10, VALUE_MAX = 65536 |
43 | POST | `/api/v1/codes` | default | MAX_NOTE = 80, MAX_USES = 1000 |
44 | POST | `/api/v1/contribute` | 65536 | MAX_PASSWORD = 1024, ORIGIN_MAX = 200 |
45 | POST | `/api/v1/conversation-confirms/{id}` | default | MAX_TURN_CHARS = 20000 |
46 | POST | `/api/v1/conversation-tokens` | 128000 | CONVERSATION_TOKENS_MAX = 30, WORDS_MAX = 20000 |
47 | POST | `/api/v1/conversation/files` | 5242880 | STORE_MAX = 52428800, TEXT_MAX = 102400 |
48 | POST | `/api/v1/conversation/messages` | 128000 | DECISIONS_MAX = 5, MAX_TURN_CHARS = 20000, QUEUE_MAX = 5, TURNS_LIVE_MAX = 4, WORDS_MAX = 20000 |
49 | POST | `/api/v1/conversation/stop` | default | none declared |
50 | POST | `/api/v1/conversations` | 4000 | CONVERSATIONS_MAX = 100, TITLE_MAX = 80 |
51 | PATCH | `/api/v1/conversations/{id}` | 4000 | TITLE_MAX = 80 |
52 | POST | `/api/v1/conversations/{id}/build/publish` | default | UNPUBLISHED_MAX = 10, WORDS_MAX = 20000 |
53 | POST | `/api/v1/conversations/{id}/build/restore` | 1000 | UNPUBLISHED_MAX = 10, WORDS_MAX = 20000 |
54 | POST | `/api/v1/devices/{id}/print` | default | MAX_SIDE = 40000, PDF_MAX_BYTES = 10485760, PWG_MAX_BYTES = 83886080 |
55 | POST | `/api/v1/drills` | 32000 | DRILL_SEEN_MAX = 8000 |
56 | PATCH | `/api/v1/features/{slug}/settings` | default | CHANGED_MAX = 500, DECLARED_MAX = 2000, INT_LIMIT = 1000000000, LIST_MAX = 50, STRING_MAX = 500 |
57 | POST | `/api/v1/feed/chips` | default | none declared |
58 | POST | `/api/v1/feed/interactions` | default | FEED_LIMIT_DEFAULT = 20, FEED_LIMIT_MAX = 50, FROM_MAX = 512, MAX_BODY = 65536, NOTE_MAX = 280, RECIPIENTS_MAX = 10, TELL_TEXT_MAX = 2000, TELL_TITLE_MAX = 80, VARIANTS_MAX = 4 |
59 | POST | `/api/v1/feed/tells` | default | FROM_MAX = 512, MAX_BODY = 65536, MAX_TITLE = 256, TELL_TEXT_MAX = 2000, TELL_TITLE_MAX = 80, VARIANTS_MAX = 4 |
60 | POST | `/api/v1/first-admin` | 65536 | MAX_PASSWORD = 1024 |
61 | POST | `/api/v1/first-admin/recover` | 65536 | none declared |
62 | POST | `/api/v1/fleet/ops` | default | MAX_QUERY = 500, MAX_TERMS = 20 |
63 | POST | `/api/v1/fleet/ops/{id}/undo` | default | MAX_QUERY = 500, MAX_TERMS = 20 |
64 | PATCH | `/api/v1/forge/following` | default | none declared |
65 | POST | `/api/v1/forges` | default | API_BASE_MAX = 200, BRIEF_MAX = 4000, MAX_APPS = 50, MAX_BRIEFS = 100, MAX_BRIEF_CHARS = 20000, MAX_BUDGET_USD = 1000, MAX_CHILDREN = 1000, MAX_CREW = 100, MAX_DIRECTION_CHARS = 2000, MAX_FOR_CHARS = 200, MAX_FRESH_CHARS = 200, MAX_SUBSCRIPTIONS = 200, MAX_WATCHERS = 20, TOKEN_MAX = 4096 |
66 | POST | `/api/v1/forges/{name}/claim-link` | default | none declared |
67 | POST | `/api/v1/forges/{name}/sandbox` | default | CONFIG_MAX = 1048576, REPOS_MAX = 10000 |
68 | POST | `/api/v1/heartbeat` | 1024 | COUNT_MAX = 1000000, USD_MAX = 1000000 |
69 | POST | `/api/v1/maintenance/duties/{name}` | 1024 | none declared |
70 | POST | `/api/v1/migrate` | default | MAX_BYTES = 262144, MAX_JOBS = 64 |
71 | POST | `/api/v1/orgs` | default | none declared |
72 | POST | `/api/v1/orgs/{org}/teams` | default | none declared |
73 | POST | `/api/v1/orgs/{org}/teams/{team}/members` | default | none declared |
74 | POST | `/api/v1/reach/asks` | default | WHY_MAX = 120 |
75 | POST | `/api/v1/release/heartbeat` | default | REASON_MAX = 300 |
76 | POST | `/api/v1/repos` | default | none declared |
77 | PATCH | `/api/v1/repos/{owner}/{name}` | default | MAX_PARENTS = 4, POLISH_SHARE_MAX = 50 |
78 | PATCH | `/api/v1/repos/{owner}/{name}/app` | default | none declared |
79 | POST | `/api/v1/repos/{owner}/{name}/app` | default | MAX = 1000000000, SLUG_MAX = 40 |
80 | POST | `/api/v1/repos/{owner}/{name}/app/{env}/redeploy` | default | none declared |
81 | POST | `/api/v1/repos/{owner}/{name}/app/{env}/stop` | default | none declared |
82 | POST | `/api/v1/repos/{owner}/{name}/app/domains` | default | MAX_OLD_RECORDS = 50 |
83 | POST | `/api/v1/repos/{owner}/{name}/app/domains/{host}/check` | default | none declared |
84 | POST | `/api/v1/repos/{owner}/{name}/app/notes/{id}/ban` | default | none declared |
85 | POST | `/api/v1/repos/{owner}/{name}/app/notes/{id}/hide` | default | none declared |
86 | POST | `/api/v1/repos/{owner}/{name}/app/notes/{id}/unban` | default | none declared |
87 | POST | `/api/v1/repos/{owner}/{name}/app/pull` | default | DECLARED_MAX = 256, PULL_BODY_MAX = 65536 |
88 | POST | `/api/v1/repos/{owner}/{name}/atlas` | 65536 | DESCRIPTION_MAX = 4000, EDGES_MAX = 60, GRAPH_MAX = 400, LINE_MAX = 300, MAX = 64, MAX_DIRECTION_CHARS = 2000, MAX_FRESH_CHARS = 200, MAX_TITLE = 256, PARTS_MAX = 12, SYSTEM_MAX = 60 |
89 | POST | `/api/v1/repos/{owner}/{name}/branches` | default | MAX_COMPONENT_BYTES = 255 |
90 | POST | `/api/v1/repos/{owner}/{name}/builds` | default | none declared |
91 | PATCH | `/api/v1/repos/{owner}/{name}/builds/{label}` | default | NOTES_MAX = 10240 |
92 | POST | `/api/v1/repos/{owner}/{name}/builds/{label}/cart` | default | none declared |
93 | POST | `/api/v1/repos/{owner}/{name}/builds/{label}/shots` | 3145728 | CAPTION_MAX = 140, SHOTS_LIMIT = 12, SHOT_MAX = 2097152 |
94 | POST | `/api/v1/repos/{owner}/{name}/builds/{label}/shots/{file}` | default | CAPTION_MAX = 140, SHOTS_LIMIT = 12, SHOT_MAX = 2097152, UPLOAD_MAX = 3145728 |
95 | POST | `/api/v1/repos/{owner}/{name}/builds/{label}/shots/looks` | default | SHOTS_LIMIT = 12, SHOT_MAX = 2097152, UPLOAD_MAX = 3145728 |
96 | POST | `/api/v1/repos/{owner}/{name}/builds/preview` | default | BUILD_ASKS_MAX = 20, MAX_READERS = 64 |
97 | POST | `/api/v1/repos/{owner}/{name}/chapters` | default | FROZEN_MAX = 200, MAX_MEANS = 300 |
98 | POST | `/api/v1/repos/{owner}/{name}/chapters/{chapter}/{verb}` | default | FROZEN_MAX = 200, MAX_MEANS = 300 |
99 | POST | `/api/v1/repos/{owner}/{name}/checks/recheck` | default | LIST_LIMIT_MAX = 200, RECHECK_MAX = 50, TEST_NAME_MAX = 300 |
100 | POST | `/api/v1/repos/{owner}/{name}/contents` | default | MAX_COMMIT_BYTES = 10485760, MAX_FILE_BYTES = 2097152 |
101 | POST | `/api/v1/repos/{owner}/{name}/contribute` | default | MAX_CACHED = 64, MAX_COMMIT_BYTES = 10485760, MAX_FILES = 1000, MAX_FILE_BYTES = 2097152 |
102 | POST | `/api/v1/repos/{owner}/{name}/data-import` | default | MAX_FILES = 10000, MAX_STATEMENTS = 1000000 |
103 | POST | `/api/v1/repos/{owner}/{name}/data/{env}/{file}/query` | default | none declared |
104 | POST | `/api/v1/repos/{owner}/{name}/desk` | default | DESK_MAX = 50, NOTE_MAX = 280 |
105 | POST | `/api/v1/repos/{owner}/{name}/edits` | default | MAX_COMMIT_BYTES = 10485760, MAX_FILES = 1000, MAX_FILE_BYTES = 2097152 |
106 | POST | `/api/v1/repos/{owner}/{name}/egress-grants` | default | READY_MAX = 600 |
107 | POST | `/api/v1/repos/{owner}/{name}/following/converge` | default | MAX_BODY = 65536, MAX_TITLE = 256, RELATION_CACHE_MAX = 500 |
108 | POST | `/api/v1/repos/{owner}/{name}/following/propose` | default | RELATION_CACHE_MAX = 500 |
109 | POST | `/api/v1/repos/{owner}/{name}/following/propose-parent` | default | none declared |
110 | POST | `/api/v1/repos/{owner}/{name}/following/sever` | default | none declared |
111 | POST | `/api/v1/repos/{owner}/{name}/following/take` | default | MAX_BODY = 65536, MAX_TITLE = 256 |
112 | POST | `/api/v1/repos/{owner}/{name}/forks` | default | none declared |
113 | POST | `/api/v1/repos/{owner}/{name}/hooks` | default | none declared |
114 | POST | `/api/v1/repos/{owner}/{name}/hooks/{id}/deliveries/{delivery}/redeliver` | default | none declared |
115 | POST | `/api/v1/repos/{owner}/{name}/hooks/{id}/pause` | default | none declared |
116 | POST | `/api/v1/repos/{owner}/{name}/hooks/{id}/ping` | default | PING_LIMIT = 3 |
117 | POST | `/api/v1/repos/{owner}/{name}/hooks/{id}/resume` | default | none declared |
118 | POST | `/api/v1/repos/{owner}/{name}/issues` | default | MAX_BODY = 65536, MAX_TITLE = 256 |
119 | PATCH | `/api/v1/repos/{owner}/{name}/issues/{number}` | default | MAX = 64, MAX_BODY = 65536, MAX_NOTE = 300, MAX_TITLE = 256 |
120 | POST | `/api/v1/repos/{owner}/{name}/issues/{number}/comments` | default | MAX_BODY = 65536, MAX_TITLE = 256 |
121 | POST | `/api/v1/repos/{owner}/{name}/issues/{number}/dependencies` | default | MAX = 64 |
122 | POST | `/api/v1/repos/{owner}/{name}/issues/{number}/dependencies/{blocker}/confirm` | default | none declared |
123 | POST | `/api/v1/repos/{owner}/{name}/issues/{number}/estimates` | default | BASIS_MAX = 300, PULLS_MAX = 600 |
124 | POST | `/api/v1/repos/{owner}/{name}/issues/{number}/private` | default | none declared |
125 | POST | `/api/v1/repos/{owner}/{name}/jobs/{id}/{action}` | default | none declared |
126 | POST | `/api/v1/repos/{owner}/{name}/labels` | default | none declared |
127 | PATCH | `/api/v1/repos/{owner}/{name}/labels/{id}` | default | none declared |
128 | POST | `/api/v1/repos/{owner}/{name}/make-it-yours` | default | MAX_DISPLAY_NAME = 80, MAX_EMAIL = 254, SLUG_MAX = 40 |
129 | POST | `/api/v1/repos/{owner}/{name}/milestones/{number}/limb` | default | MAX = 64 |
130 | POST | `/api/v1/repos/{owner}/{name}/offers` | 1261568 | MAX_PATCH_BYTES = 262144, OFFERS_WAITING_MAX = 20, OFFER_BODY_MAX = 8000, OFFER_PATCH_MAX = 204800, OFFER_TITLE_MAX = 200 |
131 | POST | `/api/v1/repos/{owner}/{name}/origin-hook` | 262144 | MAX_BODY = 65536, MAX_CACHED = 64, MAX_TITLE = 256 |
132 | POST | `/api/v1/repos/{owner}/{name}/origin/reconnect` | default | none declared |
133 | POST | `/api/v1/repos/{owner}/{name}/plan` | default | GRAPH_MAX = 400, MAX = 64, MAX_BODY = 65536, MAX_DISPLAY_NAME = 80, MAX_EMAIL = 254, MAX_TITLE = 256, PLAN_MAX = 12, WHY_MAX = 300 |
134 | POST | `/api/v1/repos/{owner}/{name}/prompts` | default | none declared |
135 | POST | `/api/v1/repos/{owner}/{name}/prompts/{id}/run` | default | none declared |
136 | POST | `/api/v1/repos/{owner}/{name}/proposal-tokens` | 65536 | none declared |
137 | POST | `/api/v1/repos/{owner}/{name}/pulls` | 65536 | MAX_TITLE = 256 |
138 | PATCH | `/api/v1/repos/{owner}/{name}/pulls/{number}` | default | MAX = 64, MAX_BODY = 65536, MAX_NOTE = 300, MAX_TITLE = 256 |
139 | POST | `/api/v1/repos/{owner}/{name}/pulls/{number}/approve-here` | default | none declared |
140 | POST | `/api/v1/repos/{owner}/{name}/pulls/{number}/checks` | default | none declared |
141 | POST | `/api/v1/repos/{owner}/{name}/pulls/{number}/comments` | default | MAX_BODY = 65536, MAX_TITLE = 256 |
142 | POST | `/api/v1/repos/{owner}/{name}/pulls/{number}/looks` | default | ATTACH_MAX_BYTES = 5242880, ATTACH_NOTE_MAX = 200, SIDE_MAX = 8192 |
143 | POST | `/api/v1/repos/{owner}/{name}/pulls/{number}/merge` | default | COAUTHORS_MAX = 20, MAX = 64, MAX_BODY = 65536 |
144 | POST | `/api/v1/repos/{owner}/{name}/pulls/{number}/review-states` | default | MAX = 64, MAX_BODY = 65536, MAX_PASS = 50, MAX_REVIEW_LINES = 50, MAX_TEXT = 300, MAX_TITLE = 256, MAX_WHY = 300, READINGS_MAX = 500 |
145 | POST | `/api/v1/repos/{owner}/{name}/pulls/{number}/reviews` | default | MAX_BODY = 65536 |
146 | POST | `/api/v1/repos/{owner}/{name}/pulls/{number}/slices` | default | MAX = 64, READINGS_MAX = 500 |
147 | POST | `/api/v1/repos/{owner}/{name}/pulls/{number}/take-back` | default | MAX_COMPONENT_BYTES = 255 |
148 | POST | `/api/v1/repos/{owner}/{name}/pulls/{number}/threads/{anchor}/resolve` | default | none declared |
149 | POST | `/api/v1/repos/{owner}/{name}/pulls/{number}/variant` | default | MAX = 64, MAX_NOTE = 300, REASON_MAX = 200 |
150 | POST | `/api/v1/repos/{owner}/{name}/reports` | 65536 | CLAIM_MAX = 64, TITLE_MAX = 200, WAITING_MAX = 100 |
151 | POST | `/api/v1/repos/{owner}/{name}/reports/{id}/accept` | default | MAX_BODY = 65536, MAX_TITLE = 256, TITLE_MAX = 200 |
152 | POST | `/api/v1/repos/{owner}/{name}/reports/{id}/dismiss` | default | none declared |
153 | POST | `/api/v1/repos/{owner}/{name}/runs/{id}/cancel` | default | none declared |
154 | POST | `/api/v1/repos/{owner}/{name}/runs/{id}/steer` | default | MAX_LINE = 16384 |
155 | POST | `/api/v1/repos/{owner}/{name}/schedules/{schedule}/{action}` | default | none declared |
156 | POST | `/api/v1/repos/{owner}/{name}/spend` | default | MAX_TOKENS = 10000000000, MAX_USD = 10000 |
157 | POST | `/api/v1/repos/{owner}/{name}/sync` | default | none declared |
158 | POST | `/api/v1/repos/{owner}/{name}/transfer` | default | none declared |
159 | POST | `/api/v1/repos/{owner}/{name}/upstream/check` | default | none declared |
160 | POST | `/api/v1/sessions` | 65536 | MAX_DISPLAY_NAME = 80, MAX_EMAIL = 254, MAX_PASSWORD = 1024 |
161 | POST | `/api/v1/share` | default | MAX_BODY = 65536, NOTE_MAX = 280, RECIPIENTS_MAX = 10, TELL_TITLE_MAX = 80, WEIGHT_MAX = 2 |
162 | POST | `/api/v1/start` | 65536 | DESCRIPTION_MAX = 2000, NAME_MAX = 40 |
163 | POST | `/api/v1/thoughts` | default | THOUGHT_MAX = 20000 |
164 | POST | `/api/v1/timers` | 69632 | ONCE_BODY_MAX = 65536 |
165 | POST | `/api/v1/tokens` | 65536 | MAX_DISPLAY_NAME = 80, MAX_EMAIL = 254, MAX_PASSWORD = 1024 |
166 | PATCH | `/api/v1/user` | default | MAX_DISPLAY_NAME = 80 |
167 | POST | `/api/v1/user/email/verify` | default | none declared |
168 | POST | `/api/v1/user/keys` | default | KEY_NAME_MAX = 64, MAX_LINE = 16384 |
169 | POST | `/api/v1/user/origin-apps` | default | none declared |
170 | POST | `/api/v1/user/origins` | default | MAX_CACHED = 64 |
171 | POST | `/api/v1/user/origins/{id}/browse/{owner}/{name}/contribute` | default | MAX_CACHED = 64, MAX_COMMIT_BYTES = 10485760, MAX_FILES = 1000, MAX_FILE_BYTES = 2097152 |
172 | POST | `/api/v1/user/origins/{id}/fork` | default | MAX_CACHED = 64 |
173 | POST | `/api/v1/user/origins/{id}/mirror` | default | none declared |
174 | POST | `/api/v1/user/origins/{id}/sync` | default | none declared |
175 | POST | `/api/v1/user/origins/oauth` | default | MAX_BYTES = 65536 |
176 | POST | `/api/v1/user/password` | default | MAX_PASSWORD = 1024 |
177 | POST | `/api/v1/users` | 65536 | MAX_PASSWORD = 1024, MAX_TOKEN = 2048, NOTE_MAX = 500, SOURCE_MAX = 80 |
scripts/write-limits.ts deleted −277
@@ -1,277 +0,0 @@
1 /**
2 * Writes `docs/WRITE-LIMITS.md` (#13051): every POST and PATCH the API
3 * accepts, with the most body it reads and the length limits its handler
4 * names. Read from the source, so the table cannot drift from the routes.
5 *
6 * bun scripts/write-limits.ts print the table
7 * bun scripts/write-limits.ts --write write docs/WRITE-LIMITS.md
8 * bun scripts/write-limits.ts --check exit 1 when the file is stale
9 *
10 * `test/write-limits.test.ts` runs the same comparison and fails when a write
11 * route has no row. A route's limits are the ceilings (`…_MAX`, `MAX_…`,
12 * `…_LIMIT`) its handler names and those of the functions it calls, two calls
13 * deep; a body read with the shared reader is `default`, a route with no
14 * ceiling on that path says `none declared`. No runtime change: nothing here is
15 * imported by the server.
16 *
17 * @tree-scan: reads src/http/ and src/http/api/.
18 */
19 import { readdirSync, readFileSync, writeFileSync } from "node:fs";
20 import { join } from "node:path";
21
22 const ROOT = join(import.meta.dir, "..");
23 const HTTP = join(ROOT, "src/http");
24 const OUT = join(ROOT, "docs/WRITE-LIMITS.md");
25
26 export interface Row {
27 readonly method: "POST" | "PATCH";
28 readonly path: string;
29 /** Bytes, or `default` for the shared readers' cap (`src/http/limits.ts`). */
30 readonly body: number | "default";
31 /** `NAME = value`, for each limit the handler, or an action it calls, names. */
32 readonly fields: readonly string[];
33 }
34
35 /** `TITLE_MAX`, `MAX_TITLE`, `PAGE_LIMIT`, `MAX_NOTE_CHARS`: a name that says it is a ceiling. */
36 const NAMED = /\b(?:[A-Z][A-Z0-9_]*_)?(?:MAX|LIMIT)(?:_[A-Z0-9_]+)?\b/g;
37 /** Ceilings that bound time, paging or work done, not what a caller may send. */
38 const NOT_INPUT = /(?:AGE|CONCURRENT|_MS\b|_S\b|ROWS|PAGE|DEPTH|ATTEMPTS|KEPT|SAFE_INTEGER|RETRIES|CLONES|SAMPLES)/;
39 /** How many calls deep a handler's limits are followed: handler, the action, what it hands on, the core call. */
40 const HOPS = 3;
41
42 const files = new Map<string, string | undefined>();
43 /** Each source file is read once per process: the walk revisits the same modules from many handlers. */
44 const read = (path: string): string | undefined => {
45 if (files.has(path)) return files.get(path);
46 let text: string | undefined;
47 try {
48 text = readFileSync(path, "utf8");
49 } catch {
50 text = undefined;
51 }
52 files.set(path, text);
53 return text;
54 };
55
56 /** A constant's source expression, in this file or in a module it imports (one hop). */
57 function declared(name: string, file: string, src: string): { expr: string; file: string; src: string } | undefined {
58 const own = new RegExp(`\\bconst ${name}\\s*(?::[^=]+)?=\\s*([^;]+);`).exec(src);
59 if (own) return { expr: own[1]!, file, src };
60 for (const m of src.matchAll(/import\s+(?:type\s+)?\{([^}]*)\}\s+from\s+"(\.[^"]+\.ts)"/g)) {
61 const names = m[1]!.split(",").map((n) => n.trim().replace(/^.*\sas\s/, ""));
62 if (!names.includes(name)) continue;
63 const there = join(file, "..", m[2]!);
64 const text = read(there);
65 const found = text === undefined ? undefined : new RegExp(`\\bconst ${name}\\s*(?::[^=]+)?=\\s*([^;]+);`).exec(text);
66 if (found) return { expr: found[1]!, file: there, src: text! };
67 }
68 return undefined;
69 }
70
71 /** A number from digits, `_`, `*`, `+`, parentheses and other constants; undefined for anything else. No eval. */
72 export function value(expr: string, file: string, src: string, depth = 0): number | undefined {
73 if (depth > 4) return undefined;
74 const tokens = expr.replace(/\/\/.*$/gm, "").match(/\d[\d_]*|[A-Za-z_][A-Za-z0-9_]*|[*+()-]/g);
75 if (tokens === null || tokens.join("").length < expr.replace(/\s|\/\/.*$/gm, "").length) return undefined;
76 let at = 0;
77 const atom = (): number | undefined => {
78 const t = tokens[at++];
79 if (t === undefined) return undefined;
80 if (t === "(") {
81 const v = sum();
82 return tokens[at++] === ")" ? v : undefined;
83 }
84 if (/^\d/.test(t)) return Number(t.replaceAll("_", ""));
85 if (/^[A-Z][A-Z0-9_]*$/.test(t)) {
86 const d = declared(t, file, src);
87 return d === undefined ? undefined : value(d.expr, d.file, d.src, depth + 1);
88 }
89 return undefined;
90 };
91 const product = (): number | undefined => {
92 let v = atom();
93 while (tokens[at] === "*") {
94 at++;
95 const r = atom();
96 v = v === undefined || r === undefined ? undefined : v * r;
97 }
98 return v;
99 };
100 const sum = (): number | undefined => {
101 let v = product();
102 while (tokens[at] === "+" || tokens[at] === "-") {
103 const op = tokens[at++];
104 const r = product();
105 v = v === undefined || r === undefined ? undefined : op === "+" ? v + r : v - r;
106 }
107 return v;
108 };
109 const v = sum();
110 return at === tokens.length ? v : undefined;
111 }
112
113 /** Text from `start` to the bracket that closes the first one at or after it; quotes and comments are skipped. */
114 export function balanced(src: string, start: number): string {
115 let depth = 0;
116 let i = start;
117 let opened = false;
118 while (i < src.length) {
119 const c = src[i]!;
120 if (c === "/" && src[i + 1] === "/") i = src.indexOf("\n", i) < 0 ? src.length : src.indexOf("\n", i);
121 else if (c === "/" && src[i + 1] === "*") i = src.indexOf("*/", i) < 0 ? src.length : src.indexOf("*/", i) + 2;
122 else if (c === '"' || c === "'" || c === "`") {
123 i++;
124 while (i < src.length && src[i] !== c) i += src[i] === "\\" ? 2 : 1;
125 i++;
126 } else {
127 if ("([{".includes(c)) {
128 depth++;
129 opened = true;
130 } else if (")]}".includes(c)) {
131 depth--;
132 if (opened && depth <= 0) return src.slice(start, i + 1);
133 }
134 i++;
135 }
136 }
137 return src.slice(start);
138 }
139
140 /** The text of a handler named in a registration: its definition here or in a module this one imports. */
141 function definition(name: string, file: string, src: string): { text: string; file: string; src: string } | undefined {
142 const own = new RegExp(`(?:function\\s+${name}\\b|\\bconst\\s+${name}\\b)`).exec(src);
143 if (own) return { text: balanced(src, src.indexOf("{", own.index)), file, src };
144 for (const m of src.matchAll(/import\s+(?:type\s+)?\{([^}]*)\}\s+from\s+"(\.[^"]+\.ts)"/g)) {
145 if (!m[1]!.split(",").some((n) => n.trim() === name)) continue;
146 const there = join(file, "..", m[2]!);
147 const text = read(there);
148 const found = text === undefined ? undefined : new RegExp(`(?:function\\s+${name}\\b|\\bconst\\s+${name}\\b)`).exec(text);
149 if (found) return { text: balanced(text!, text!.indexOf("{", found.index)), file: there, src: text! };
150 }
151 return undefined;
152 }
153
154 /** A called function's text: from its declaration to the next closing brace at column 0 (or its one line). */
155 const callees = new Map<string, ReturnType<typeof calleeOf>>();
156 function callee(name: string, file: string, src: string): ReturnType<typeof calleeOf> {
157 const key = `${file}\0${name}`;
158 if (!callees.has(key)) callees.set(key, calleeOf(name, file, src));
159 return callees.get(key);
160 }
161
162 function calleeOf(name: string, file: string, src: string): { text: string; file: string; src: string } | undefined {
163 const find = (text: string, at: string): { text: string; file: string; src: string } | undefined => {
164 const m = new RegExp(`^(?:export\\s+)?(?:async\\s+)?(?:function\\s+${name}\\b|const\\s+${name}\\b)`, "m").exec(text);
165 if (m === null) return undefined;
166 const lineEnd = text.indexOf("\n", m.index);
167 const first = text.slice(m.index, lineEnd < 0 ? text.length : lineEnd);
168 if (first.includes("=>") && first.endsWith(";")) return { text: first, file: at, src: text };
169 const close = text.indexOf("\n}", m.index);
170 return { text: text.slice(m.index, close < 0 ? text.length : close + 2), file: at, src: text };
171 };
172 const own = find(src, file);
173 if (own) return own;
174 for (const m of src.matchAll(/import\s+(?:type\s+)?\{([^}]*)\}\s+from\s+"(\.[^"]+\.ts)"/g)) {
175 if (!m[1]!.split(",").some((n) => n.trim().replace(/^.*\sas\s/, "") === name)) continue;
176 const there = join(file, "..", m[2]!);
177 const text = read(there);
178 const found = text === undefined ? undefined : find(text, there);
179 if (found) return found;
180 }
181 return undefined;
182 }
183
184 /** Every `NAME = value` ceiling the text names, and those of the functions it calls, `hops` deep. */
185 function limitsIn(text: string, file: string, src: string, hops: number, seen: Set<string>, into: Map<string, number>): void {
186 for (const name of new Set(text.match(NAMED) ?? [])) {
187 if (/^(?:BODY|STRANGER|REQUEST|PUSH|FETCH|GZIP|DRAIN)_MAX$/.test(name) || NOT_INPUT.test(name)) continue;
188 const d = declared(name, file, src);
189 const v = d === undefined ? undefined : value(d.expr, d.file, d.src);
190 if (v !== undefined) into.set(name, v);
191 }
192 if (hops === 0) return;
193 for (const m of text.matchAll(/(?<![.\w])([a-z]\w*)\(/g)) {
194 const key = `${file}:${m[1]}`;
195 if (seen.has(key)) continue;
196 seen.add(key);
197 const c = callee(m[1]!, file, src);
198 if (c !== undefined && c.text !== text) limitsIn(c.text, c.file, c.src, hops - 1, seen, into);
199 }
200 }
201
202 const routeFiles = (): string[] => [
203 ...readdirSync(HTTP).map((f) => join(HTTP, f)),
204 ...readdirSync(join(HTTP, "api")).map((f) => join(HTTP, "api", f)),
205 ].filter((f) => f.endsWith(".ts"));
206
207 /** The write routes with their limits, sorted by path then method. */
208 let memo: Row[] | undefined;
209 export function rows(): Row[] {
210 return (memo ??= compute()).map((r) => ({ ...r }));
211 }
212
213 function compute(): Row[] {
214 const out = new Map<string, Row>();
215 for (const file of routeFiles()) {
216 const src = read(file)!;
217 if (!src.includes("router.add(")) continue;
218 const consts = new Map([...src.matchAll(/\bconst ([A-Z_]+) = "([^"]*)"/g)].map((m) => [m[1]!, m[2]!]));
219 const parts = src.split("router.add(");
220 for (const part of parts.slice(1)) {
221 const head = /^\s*"(POST|PATCH)",\s*(?:"([^"]*)"|`([^`]*)`|([A-Z_]+)\b)/.exec(part);
222 if (head === null) continue;
223 const raw = (head[2] ?? head[3] ?? consts.get(head[4]!) ?? "").replace(/\$\{([A-Z_]+)\}/g, (_, n) => consts.get(n) ?? `\${${n}}`);
224 if (!raw.startsWith("/api/v1")) continue;
225 // The registration's own call, or the named handler it passes.
226 const call = balanced(`(${part}`, 0).slice(1);
227 const named = /,\s*([A-Za-z_]\w*)\s*\)?$/.exec(call.replace(/\s+/g, " "));
228 const handler = named !== null && !call.includes("=>") && !call.includes("function") ? definition(named[1]!, file, src) : undefined;
229 const region = handler?.text ?? call;
230 const at = handler ?? { file, src };
231 const cap = /(?:boundedBody|readBounded)\(\s*ctx\.request,\s*([^)]+)\)/.exec(region);
232 const capValue = cap === null ? undefined : value(cap[1]!, at.file, at.src);
233 const body: Row["body"] = capValue ?? "default";
234 const found = new Map<string, number>();
235 limitsIn(region, at.file, at.src, HOPS, new Set(), found);
236 const fields = new Set<string>();
237 for (const [name, v] of found) if (capValue !== v) fields.add(`${name} = ${v}`);
238 for (const v of raw.includes("${kind}") ? ["issues", "pulls"] : [""]) {
239 const path = raw.replace("${kind}", v).replace(/[:*]\w+/g, (p) => `{${p.slice(1)}}`);
240 const key = `${path} ${head[1]}`;
241 if (!out.has(key)) out.set(key, { method: head[1] as Row["method"], path, body, fields: [...fields].sort() });
242 }
243 }
244 }
245 return [...out.values()].sort((a, b) => (a.path === b.path ? a.method.localeCompare(b.method) : a.path.localeCompare(b.path)));
246 }
247
248 const cell = (s: string): string => s.replaceAll("|", "\\|");
249
250 /** The document: a header saying how to read it, then one row per write route. */
251 export function table(list: readonly Row[] = rows()): string {
252 return [
253 "# Write limits",
254 "",
255 "Generated by `bun scripts/write-limits.ts --write`; do not edit. `test/write-limits.test.ts` fails when a POST or PATCH route has no row or a row is stale.",
256 "",
257 "Every number is bytes of request body unless it names a count or a length (characters). `default` is the shared reader's cap (`src/http/limits.ts`): `BODY_MAX` = 16777216 bytes (16 MiB) with a token or session, `STRANGER_MAX` = 65536 bytes (64 KiB) without one. A route's per-field limits list the ceilings (`…_MAX`, `MAX_…`, `…_LIMIT`) its handler names and those of the functions it calls, followed three calls deep into the action and core modules where fields are validated (ceilings on time, paging and work done are left out). \`none declared\` means no such ceiling was found on that path: the field is then bound by the body cap alone. Git pushes, fetches and uploads are not routes of this API and are out of this table.",
258 "",
259 "| Method | Route | Max body bytes | Per-field limits |",
260 "| --- | --- | --- | --- |",
261 ...list.map((r) => `| ${r.method} | \`${cell(r.path)}\` | ${r.body} | ${r.fields.length === 0 ? "none declared" : cell(r.fields.join(", "))} |`),
262 "",
263 ].join("\n");
264 }
265
266 if (import.meta.main) {
267 const text = table();
268 if (process.argv.includes("--write")) {
269 writeFileSync(OUT, text);
270 console.log(`wrote docs/WRITE-LIMITS.md (${rows().length} routes)`);
271 } else if (process.argv.includes("--check")) {
272 if (read(OUT) !== text) {
273 console.error("stale: docs/WRITE-LIMITS.md; run `bun scripts/write-limits.ts --write`");
274 process.exit(1);
275 }
276 } else process.stdout.write(text);
277 }
test/write-limits.test.ts deleted −44
@@ -1,44 +0,0 @@
1 import { expect, test } from "bun:test";
2 import { readFileSync } from "node:fs";
3 import { join } from "node:path";
4 import { balanced, rows, table, value } from "../scripts/write-limits.ts";
5 import { registered } from "./helpers/registered_routes.ts";
6
7 const doc = readFileSync(join(import.meta.dir, "../docs/WRITE-LIMITS.md"), "utf8");
8
9 test("every POST and PATCH route the API registers has a row in docs/WRITE-LIMITS.md", () => {
10 const listed = new Set(
11 [...doc.matchAll(/^\| (POST|PATCH) \| `([^`]+)`/gm)].map((m) => `${m[1]} ${m[2]!.replace(/\{\w+\}/g, "{}")}`),
12 );
13 const missing = registered().filter((r) => /^(POST|PATCH) /.test(r) && !listed.has(r));
14 expect(missing, `no row; run \`bun scripts/write-limits.ts --write\`:\n${missing.join("\n")}`).toEqual([]);
15 });
16
17 test("the table is current: run `bun scripts/write-limits.ts --write`", () => {
18 expect(doc).toBe(table());
19 });
20
21 test("a declared body cap and a handler's field limit are read from the source", () => {
22 const all = rows();
23 const find = (m: string, p: string) => all.find((r) => r.method === m && r.path === p)!;
24 expect(find("POST", "/api/v1/heartbeat").body).toBe(1024);
25 expect(find("POST", "/api/v1/sessions").body).toBe(65536);
26 expect(find("POST", "/api/v1/thoughts").fields).toContain("THOUGHT_MAX = 20000");
27 // The title limit lives in core/issues.ts, three calls below the handler:
28 // a row that lists none has stopped following the call.
29 expect(find("POST", "/api/v1/repos/{owner}/{name}/issues").fields).toContain("MAX_TITLE = 256");
30 expect(find("POST", "/api/v1/repos/{owner}/{name}/pulls").fields).toContain("MAX_TITLE = 256");
31 expect(doc).toMatch(/\| POST \| `\/api\/v1\/repos\/\{owner\}\/\{name\}\/issues` \| [^|]+ \| [^|]*MAX_TITLE = 256/);
32 // A route that validates nothing says so, in those words, and never `default`.
33 // It does not borrow the next route's limits.
34 expect(find("POST", "/api/v1/admin/accounts/{username}/verify").fields).toEqual([]);
35 expect(doc).toMatch(/\| POST \| `\/api\/v1\/admin\/accounts\/\{username\}\/verify` \| [^|]+ \| none declared \|/);
36 expect(doc).not.toMatch(/\| (?:default|none declared) \| default \|$/m);
37 });
38
39 test("constants resolve by hand: products, sums and underscores, never eval", () => {
40 expect(value("2 * 1024 * 1024", "x.ts", "")).toBe(2097152);
41 expect(value("1_000 + 24", "x.ts", "")).toBe(1024);
42 expect(value("process.exit(1)", "x.ts", "")).toBeUndefined();
43 expect(balanced('f("a)", (b), `c)`) // )', 1)).toBe('("a)", (b), `c)`)');
44 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs