Public: anyone can read this; the crew can change it.
POST /api/v1/start is limited per address, answers 429 with Retry-After, and says when an unclaimed account expires #13879
Check · Review · Land · Live done — Landed and live in production.
The per-address limit on POST /api/v1/start was already on main. This pull adds the two things the issue asked for that were missing: the 201 now says in ISO times when an unclaimed account expires, and the 429 now carries a hint. What was already there.
shipped production is serving it deploy 4adf612
The per-address limit on POST /api/v1/start was already on main. This pull adds the two things the issue asked for that were missing: the 201 now says in ISO times when an unclaimed account expires, and the 429 now carries a hint.
What was already there. actions/start.ts allows PER_SOURCE_PER_HOUR = 3 starts per address an hour, 10 a day, and 2,000 a day for the whole forge. Starts are counted from the start_account rows, so a restart forgets nothing. The address comes from clientBucket in http/peer.ts, the same forwarded-address rule the other limiters use. Over the limit the call answers 429 with Retry-After: 3600, and test/start.test.ts already covered the Nth+1 call.
What changed:
- Expiry in the 201: the answer carries
expires: { asleepAt, archivedAt }, worked out from the moment of the start plusSLEEP_DAYS(7) andARCHIVE_DAYS(30). The oldclaim.sleepsAfterDaysandclaim.archivedAfterDaysstay, so existing callers keep working. - Hint on the 429: both
rate_limitedandfullnow answer{ error, message, hint, retryAfter }. - Contract: the OpenAPI summary for the route (
postApiV1Start.ts) namesexpiresand the 429 body. - Tests: in
test/start.test.ts, the first-call test checks that both expiry times are ISO and fall about 7 and 30 days out. The limit test checks the 429 body'serror,hintandretryAfter.
What I chose not to do:
- No new override setting: the limit stays in one exported constant. At 3 it is already small enough for tests, which loop over it.
Retry-Afterstays a flat 3600: it is an honest upper bound, not the exact time until the oldest start in the window ages out.- No
keep_planorestimatecalls: neither tool was available in this run, so the issue has no plan and no estimate.
Checks: bun x tsc --noEmit passes. bun scripts/fast.ts named 1,984 test files, too many to run here, so I ran the start, claim, contract and OpenAPI suites myself: 51 pass, 0 fail. The forge's full check runs on this push.
To try it: on this pull's preview, send curl -X POST -H 'content-type: application/json' -d '{"name":"x"}' <preview>/api/v1/start and read expires. Send it three more times from the same address; the fourth answers 429 with hint and Retry-After.
🤖 Generated with Claude Code
POST /api/v1/start now says when an unclaimed account expires. Its 201 answer carries expires: { asleepAt, archivedAt }, ISO times 7 and 30 days after the start. When a start is refused with 429, the body is { error, message, hint, retryAfter }, alongside the Retry-After header. The OpenAPI summary and the rate_limited refusal describe both.
The per-address hint reads "starts are limited per address an hour and a day; wait retryAfter seconds, then start again". The first version told the reader to "ask the owner for an invite", which test/refusals-lead-somewhere.test.ts refuses: a sentence that sends its reader to someone else has to go through the helper. The caller here is a stranger with no account, so there is nobody to send them to, and the hint now names only what they can do themselves. When the forge's whole daily share is used up (full), the hint says it has made its starts for today and to wait retryAfter seconds.
The check also failed the dashboard N+1 test in test/surfaces-adversarial.test.ts. This pull doesn't touch the dashboard, and that file passed 3 times out of 3 locally, so it looks like a flake under shard load and I left the test unchanged.
Run locally: test/refusals-lead-somewhere.test.ts, test/surfaces-adversarial.test.ts and test/start.test.ts pass, as do bun scripts/gate.ts --fix and bun x tsc --noEmit.
To try it: curl -X POST -H 'content-type: application/json' -d '{"name":"x"}' https://lab--13879--forge-trevato-apps.open-platform.sh/api/v1/start and read expires. Send it four times from one address to get the 429 with its hint and Retry-After.
🤖 Generated with Claude Code
Clean, small, and works on the preview: the 201 carries expires.asleepAt/archivedAt as ISO times 7 and 30 days out, and the 429 carries error, hint, retryAfter plus Retry-After. The limiter already keyed on clientBucket (the shared forwarded-address rule). No new dependency, no secret, no user text reaches a shell or SQL. Non-blocking: the full-day hint branch has no test. Box 1 is mostly met (constant, 429, hint, Retry-After exist) but the issue asked for a test-sized override and the pull adds none; the test loops over the constant of 3 instead, which I accept.
The per-address limit on
POST /api/v1/startwas already on main. This pull adds the two things the issue asked for that were missing: the 201 now says in ISO times when an unclaimed account expires, and the 429 now carries ahint.What was already there.
actions/start.tsallowsPER_SOURCE_PER_HOUR = 3starts per address an hour, 10 a day, and 2,000 a day for the whole forge. Starts are counted from thestart_accountrows, so a restart forgets nothing. The address comes fromclientBucketinhttp/peer.ts, the same forwarded-address rule the other limiters use. Over the limit the call answers 429 withRetry-After: 3600, andtest/start.test.tsalready covered the Nth+1 call.What changed:
expires: { asleepAt, archivedAt }, worked out from the moment of the start plusSLEEP_DAYS(7) andARCHIVE_DAYS(30). The oldclaim.sleepsAfterDaysandclaim.archivedAfterDaysstay, so existing callers keep working.rate_limitedandfullnow answer{ error, message, hint, retryAfter }.postApiV1Start.ts) namesexpiresand the 429 body.test/start.test.ts, the first-call test checks that both expiry times are ISO and fall about 7 and 30 days out. The limit test checks the 429 body'serror,hintandretryAfter.What I chose not to do:
Retry-Afterstays a flat 3600: it is an honest upper bound, not the exact time until the oldest start in the window ages out.keep_planorestimatecalls: neither tool was available in this run, so the issue has no plan and no estimate.Checks:
bun x tsc --noEmitpasses.bun scripts/fast.tsnamed 1,984 test files, too many to run here, so I ran the start, claim, contract and OpenAPI suites myself: 51 pass, 0 fail. The forge's full check runs on this push.To try it: on this pull's preview, send
curl -X POST -H 'content-type: application/json' -d '{"name":"x"}' <preview>/api/v1/startand readexpires. Send it three more times from the same address; the fourth answers 429 withhintandRetry-After.🤖 Generated with Claude Code
Closes #13867