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.
scout/forge:scout/13867-post-api-v1-start-is-limited-per-address → main 3 commits fork
4 files
changed +25
−3
src/actions/start.ts +6
| @@ -88,6 +88,8 @@ export interface Started { | ||
| 88 | 88 | readonly app: { readonly url: string | null }; |
| 89 | 89 | /** One-time link a person opens to take the account and its repositories. */ |
| 90 | 90 | readonly claim: { readonly url: string; readonly sleepsAfterDays: number; readonly archivedAfterDays: number }; |
| 91 | /** When the account, left unclaimed, goes to sleep and is archived: ISO times. */ | |
| 92 | readonly expires: { readonly asleepAt: string; readonly archivedAt: string }; | |
| 91 | 93 | } |
| 92 | 94 | |
| 93 | 95 | /** The name as a repository and account name: lowercase letters, digits, dashes. */ |
| @@ -196,6 +198,10 @@ export async function startBuilding( | ||
| 196 | 198 | git: { url, push: `git push ${url.replace("://", `://${user.username}:${token.token}@`)} HEAD:main` }, |
| 197 | 199 | app: { url: appsRuntime(app)?.urlFor(record, "production") ?? null }, |
| 198 | 200 | claim: { url: `${origin}/claim/start/${claimToken}`, sleepsAfterDays: SLEEP_DAYS, archivedAfterDays: ARCHIVE_DAYS }, |
| 201 | expires: { | |
| 202 | asleepAt: new Date(now.getTime() + SLEEP_DAYS * DAY_MS).toISOString(), | |
| 203 | archivedAt: new Date(now.getTime() + ARCHIVE_DAYS * DAY_MS).toISOString(), | |
| 204 | }, | |
| 199 | 205 | }); |
| 200 | 206 | } |
| 201 | 207 |
src/contract/openapi/routes/postApiV1Start.ts +2 −2
| @@ -4,7 +4,7 @@ export const route: Route = { | ||
| 4 | 4 | method: "post", |
| 5 | 5 | path: "/api/v1/start", |
| 6 | 6 | summary: |
| 7 | "Start building with no account (an agent holding only the forge's URL): answers 201 { user: { username }, token, repo: \"owner/name\", git: { url, push }, app: { url }, claim: { url, sleepsAfterDays, archivedAfterDays } }. It makes an agent account, a public repository from the app template and its app; the token (read and write, that account only) and the claim link are shown once; `git push` to main deploys; a person opens `claim.url` to take the account and its repositories. Unclaimed it has no crew and no credits, runs small with no outbound host but the package registries, sleeps after 7 days and is archived after 30. A few starts per source an hour and a cap per day; refused from another origin with 403 forbidden; the owner's setting can turn it off or ask for an invite `code`", | |
| 7 | "Start building with no account (an agent holding only the forge's URL): answers 201 { user: { username }, token, repo: \"owner/name\", git: { url, push }, app: { url }, claim: { url, sleepsAfterDays, archivedAfterDays }, expires: { asleepAt, archivedAt } (ISO times) }. It makes an agent account, a public repository from the app template and its app; the token (read and write, that account only) and the claim link are shown once; `git push` to main deploys; a person opens `claim.url` to take the account and its repositories. Unclaimed it has no crew and no credits, runs small with no outbound host but the package registries, sleeps after 7 days and is archived after 30. A few starts per source an hour and a cap per day; refused from another origin with 403 forbidden; the owner's setting can turn it off or ask for an invite `code`", | |
| 8 | 8 | auth: false, |
| 9 | 9 | role: "anonymous", |
| 10 | 10 | status: 201, |
| @@ -12,7 +12,7 @@ export const route: Route = { | ||
| 12 | 12 | refusals: { |
| 13 | 13 | off: "403, the owner turned the start call off", |
| 14 | 14 | code_needed: "403, this forge asks for an open invite link's token as `code`", |
| 15 | rate_limited: "429, too many starts from this source; retry-after says when", | |
| 15 | rate_limited: "429 { error, message, hint, retryAfter }, too many starts from this address; Retry-After says when", | |
| 16 | 16 | full: "429, the forge has started its share for today", |
| 17 | 17 | too_large: "413, the body is over the limit for a stranger's", |
| 18 | 18 | invalid_name: "422, name is 1-40 characters with a letter or digit", |
src/http/api/start.ts +6 −1
| @@ -26,7 +26,12 @@ export function startRoutes(router: Router<Handler>): void { | ||
| 26 | 26 | const refusal = started.error; |
| 27 | 27 | const said = START_WORDS[refusal.error]; |
| 28 | 28 | if (refusal.error === "rate_limited" || refusal.error === "full") |
| 29 | return tryAgain(refusal.error, 429, said, refusal.retryAfter ?? 3600); | |
| 29 | return tryAgain(refusal.error, 429, said, refusal.retryAfter ?? 3600, {}, { | |
| 30 | hint: | |
| 31 | refusal.error === "rate_limited" | |
| 32 | ? "starts are limited per address an hour and a day; wait retryAfter seconds, then start again" | |
| 33 | : "the forge has made its starts for today; wait retryAfter seconds", | |
| 34 | }); | |
| 30 | 35 | if (refusal.error === "off") return apiError("off", 403, said); |
| 31 | 36 | if (refusal.error === "code_needed") return apiError("code_needed", 403, said); |
| 32 | 37 | if (refusal.error === "failed") return apiError("failed", 500, said); |
test/start.test.ts +11
| @@ -54,6 +54,7 @@ interface StartAnswer { | ||
| 54 | 54 | git: { url: string; push: string }; |
| 55 | 55 | app: { url: string | null }; |
| 56 | 56 | claim: { url: string }; |
| 57 | expires: { asleepAt: string; archivedAt: string }; | |
| 57 | 58 | } |
| 58 | 59 | |
| 59 | 60 | describe("start, push, live, claim", () => { |
| @@ -67,6 +68,12 @@ describe("start, push, live, claim", () => { | ||
| 67 | 68 | expect(started.token).toStartWith("forge_"); |
| 68 | 69 | expect(started.repo).toMatch(/^glint-notes-[0-9a-f]+\/glint-notes$/); |
| 69 | 70 | expect(started.claim.url).toContain("/claim/start/claim_"); |
| 71 | const day = 86_400_000; | |
| 72 | const asleep = Date.parse(started.expires.asleepAt) - Date.now(); | |
| 73 | const archived = Date.parse(started.expires.archivedAt) - Date.now(); | |
| 74 | expect(started.expires.asleepAt).toMatch(/^\d{4}-\d\d-\d\dT.*Z$/); | |
| 75 | expect(Math.abs(asleep - 7 * day)).toBeLessThan(60_000); | |
| 76 | expect(Math.abs(archived - 30 * day)).toBeLessThan(60_000); | |
| 70 | 77 | const repo = getRepo(forge.app.db, started.user.username, "glint-notes")!; |
| 71 | 78 | expect(repo.visibility).toBe("public"); |
| 72 | 79 | // No crew, no password; held as a guest and unclaimed. |
| @@ -158,6 +165,10 @@ describe("the defenses", () => { | ||
| 158 | 165 | const held = await post("/api/v1/start", { name: "lim-x" }, {}, "198.51.100.30"); |
| 159 | 166 | expect(held.status).toBe(429); |
| 160 | 167 | expect(held.headers.get("retry-after")).toBe("3600"); |
| 168 | const body = (await held.json()) as { error: string; hint: string; retryAfter: number }; | |
| 169 | expect(body.error).toBe("rate_limited"); | |
| 170 | expect(body.hint).toContain("per address"); | |
| 171 | expect(body.retryAfter).toBe(3600); | |
| 161 | 172 | expect((await post("/api/v1/start", { name: "lim-y" }, {}, "198.51.100.31")).status).toBe(201); |
| 162 | 173 | }, 60_000); |
| 163 | 174 |
new above
offline