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

Merged opened this

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

Merged

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.

Notes

shipped production is serving it deploy 4adf612

opened this

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 plus SLEEP_DAYS (7) and ARCHIVE_DAYS (30). The old claim.sleepsAfterDays and claim.archivedAfterDays stay, so existing callers keep working.
  • Hint on the 429: both rate_limited and full now answer { error, message, hint, retryAfter }.
  • Contract: the OpenAPI summary for the route (postApiV1Start.ts) names expires and 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's error, hint and retryAfter.

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-After stays a flat 3600: it is an honest upper bound, not the exact time until the oldest start in the window ages out.
  • No keep_plan or estimate calls: 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

Closes #13867

commented

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 plus SLEEP_DAYS (7) and ARCHIVE_DAYS (30). The old claim.sleepsAfterDays and claim.archivedAfterDays stay, so existing callers keep working.
  • Hint on the 429: both rate_limited and full now answer { error, message, hint, retryAfter }.
  • Contract: the OpenAPI summary for the route (postApiV1Start.ts) names expires and 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's error, hint and retryAfter.

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-After stays a flat 3600: it is an honest upper bound, not the exact time until the oldest start in the window ages out.
  • No keep_plan or estimate calls: 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

commented

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

Approved

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.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs