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

scout/forge:scout/13867-post-api-v1-start-is-limited-per-address → main 3 commits fork

  • Merged. scout/13867-post-api-v1-start-is-limited-per-address was merged into main as 1b35e66.

Review

Sign in to review this change.
4 files changed +25 −3
src/actions/start.ts +6
@@ -88,6 +88,8 @@ export interface Started {
8888 readonly app: { readonly url: string | null };
8989 /** One-time link a person opens to take the account and its repositories. */
9090 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 };
9193 }
9294
9395 /** The name as a repository and account name: lowercase letters, digits, dashes. */
@@ -196,6 +198,10 @@ export async function startBuilding(
196198 git: { url, push: `git push ${url.replace("://", `://${user.username}:${token.token}@`)} HEAD:main` },
197199 app: { url: appsRuntime(app)?.urlFor(record, "production") ?? null },
198200 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 },
199205 });
200206 }
201207
src/contract/openapi/routes/postApiV1Start.ts +2 −2
@@ -4,7 +4,7 @@ export const route: Route = {
44 method: "post",
55 path: "/api/v1/start",
66 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`",
88 auth: false,
99 role: "anonymous",
1010 status: 201,
@@ -12,7 +12,7 @@ export const route: Route = {
1212 refusals: {
1313 off: "403, the owner turned the start call off",
1414 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",
1616 full: "429, the forge has started its share for today",
1717 too_large: "413, the body is over the limit for a stranger's",
1818 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 {
2626 const refusal = started.error;
2727 const said = START_WORDS[refusal.error];
2828 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 });
3035 if (refusal.error === "off") return apiError("off", 403, said);
3136 if (refusal.error === "code_needed") return apiError("code_needed", 403, said);
3237 if (refusal.error === "failed") return apiError("failed", 500, said);
test/start.test.ts +11
@@ -54,6 +54,7 @@ interface StartAnswer {
5454 git: { url: string; push: string };
5555 app: { url: string | null };
5656 claim: { url: string };
57 expires: { asleepAt: string; archivedAt: string };
5758 }
5859
5960 describe("start, push, live, claim", () => {
@@ -67,6 +68,12 @@ describe("start, push, live, claim", () => {
6768 expect(started.token).toStartWith("forge_");
6869 expect(started.repo).toMatch(/^glint-notes-[0-9a-f]+\/glint-notes$/);
6970 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);
7077 const repo = getRepo(forge.app.db, started.user.username, "glint-notes")!;
7178 expect(repo.visibility).toBe("public");
7279 // No crew, no password; held as a guest and unclaimed.
@@ -158,6 +165,10 @@ describe("the defenses", () => {
158165 const held = await post("/api/v1/start", { name: "lim-x" }, {}, "198.51.100.30");
159166 expect(held.status).toBe(429);
160167 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);
161172 expect((await post("/api/v1/start", { name: "lim-y" }, {}, "198.51.100.31")).status).toBe(201);
162173 }, 60_000);
163174

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs