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

A wake counts against the forge's owner once it is claimed and against the forge itself until then, never against whoever sent it #13903

Merged opened this

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

Merged

trevato/wake-budget-per-owner → main 3 commits

  • Merged. trevato/wake-budget-per-owner was merged into main as d73d768.

Review

Sign in to review this change.
6 files changed +197 −14
docs/features/forge-sleep.md +1 −1
@@ -3,7 +3,7 @@
33 A person (or their assistant, over the MCP `spawn` tool with their consent) makes a forge at `/forges/new`, the address `<name>--<this host>`. Free within the limits below; no payment path yet.
44
55 - **Sleep.** A forge with no request for `FORGE_CHILD_IDLE_S` (600) sleeps: a hosted child's App and apps close, a cell child's process stops. Data stays under `children/<bodyId>`. The next page load, `git push` or API call wakes it. A page for a sleeping cell forge answers a plain "waking up" page at once (git and API calls wait up to 4 s) (503, `retry-after`, reloads itself); a hosted one opens in-process.
6 - **Limits, each refused in words.** The admin limits `forges.per_person` (3) and `forges.storage_mb` (1000 MB), set at `/admin/limits` (the same list is on the terminal's limits screen), each refused in a sentence naming the limit and the person's use (site admins exempt), `FORGE_CHILD_AWAKE_MAX` (8 awake at once; sleeping forges do not count), `FORGE_CHILD_WAKES_PER_HOUR` (20 per forge), the admin limit `forges.wakes_per_person_hour` (30 wakes an hour across one person's forges, refused with "waking too often, try in N s"), plus the existing size/quota limits (`FORGE_CHILD_*_MIB`), and each cell's own disk cap.
6 - **Limits, each refused in words.** The admin limits `forges.per_person` (3) and `forges.storage_mb` (1000 MB), set at `/admin/limits` (the same list is on the terminal's limits screen), each refused in a sentence naming the limit and the person's use (site admins exempt), `FORGE_CHILD_AWAKE_MAX` (8 awake at once; sleeping forges do not count), `FORGE_CHILD_WAKES_PER_HOUR` (20 per forge), the admin limit `forges.wakes_per_person_hour` (30 wakes an hour, counted against the forge's owner once someone has claimed it and against the forge itself until then, never against whoever sent it; a site admin's own forge is counted like anyone's; refused in a sentence that says whose wakes are spent, in how long the forge can be woken again, and the limit's name and where an admin raises it), plus the existing size/quota limits (`FORGE_CHILD_*_MIB`), and each cell's own disk cap.
77 - **Owner.** `/forges` shows awake/asleep, size, last activity, with Stop (sleep now) and Remove (ledger and data).
88 - **Secrets.** A child starts from `childEnv` and never sees this forge's model credential; the person brings their own or its crew stays off.
99
src/settings/limits.ts +1 −1
@@ -248,7 +248,7 @@ export const LIMITS: Record<LimitKey, LimitDef> = {
248248 default: 30,
249249 min: 1,
250250 max: 10_000,
251 reason: "Waking a sleeping forge starts a process on this machine; a person who wakes theirs too often is asked to wait.",
251 reason: "Waking a sleeping forge starts a process on this machine. A wake counts against the forge's owner, the person who claimed it, and against the forge itself until it is claimed; never against whoever sent it.",
252252 },
253253 "forges.storage_mb": {
254254 label: "Storage a person can hold in hosted forges",
src/spawn/host.ts +13 −6
@@ -24,7 +24,7 @@ import {
2424 } from "./placement.ts";
2525 import { DEFAULT_SIZE, isSize, type Size } from "./sizes.ts";
2626 import { cellChildren, forward, forwardSocket, type CellChild } from "./cell.ts";
27 import { childNextRunDue } from "./child_db.ts";
27 import { childNextRunDue, childPerson } from "./child_db.ts";
2828 import { cellsAvailable } from "../apps/contain.ts";
2929 import { childNeedsOwnFilesystem } from "../core/capacity.ts";
3030 import { liveChildDisk, startRefusal } from "./disk_mount.ts";
@@ -32,7 +32,7 @@ import { floorRefusal } from "./disk_floor.ts";
3232 import { limitValue } from "../settings/limits.ts";
3333 import { cancelRestarts, clearStop, lastStop, noteStop, stopSentence, tryAgainAt, useRestart } from "./stopped.ts";
3434 import { readOwnCode } from "./own_code.ts";
35 import { awakeRefusal, idleAfterMs, WakeRate } from "./sleep.ts";
35 import { awakeRefusal, budgetRefusal, idleAfterMs, wakeBudget, WakeRate } from "./sleep.ts";
3636 import { rememberAwake, takeAwake } from "./awake_at_stop.ts";
3737 import { wakingResponse } from "../web/pages/waking.ts";
3838 import { lapsedResponse, payAgainRoute, PAY_AGAIN_PATH } from "../web/pages/lapsed.ts";
@@ -515,7 +515,8 @@ export function refusedResponse(why: string): Response {
515515 /**
516516 * Before a child's Host is answered: a child already awake is marked busy (by a
517517 * request whose session or token the child verifies, so a stranger cannot keep it awake); one
518 * asleep is woken within the limits (a stranger's address first, then this host's
518 * asleep is woken within the limits (a stranger's address first, then its owner's
519 * wakes an hour, or its own while nobody has claimed it (`wakeBudget`), then this host's
519520 * awake ceiling, then, for strangers, the child's wakes an hour), else a plain
520521 * refusal. The slot is reserved here. Undefined means carry on.
521522 */
@@ -548,6 +549,10 @@ export async function wakeGate(parent: App, request: Request): Promise<Response
548549 // Asked off this thread when the child is a cell's: its database is its own to write, and the
549550 // answer has a deadline.
550551 const known = await carriesCredentials(parent, ledger.bodyId, request);
552 // Whose wake this would be, read from the forge's own tables while it is asleep and no wake of
553 // it is already granted; asked here so nothing below waits between the checks and the grant.
554 const fresh = !isAwakeBody(parent, ledger.bodyId) && !(reservedCount(parent) > 0 && waking.get(parent)?.has(ledger.bodyId) === true);
555 const budget = wakeBudget(ledger.bodyId, fresh ? await childPerson(childDirOf(parent, ledger.bodyId)) : undefined);
551556 if (isAwakeBody(parent, ledger.bodyId)) {
552557 clearStop(parent, ledger.bodyId);
553558 if (known) {
@@ -572,15 +577,17 @@ export async function wakeGate(parent: App, request: Request): Promise<Response
572577 const at = gateClock.now();
573578 let people = personWakes.get(parent);
574579 if (!people) personWakes.set(parent, (people = new WakeRate()));
575 const wait = ledger.ownerId === undefined ? 0 : people.waitS(ledger.ownerId, limitValue(parent.db, "forges.wakes_per_person_hour"), at);
576 if (wait > 0) return wakingResponse(parent, request, name, `waking too often, try in ${wait} s`, wait);
580 const max = limitValue(parent.db, "forges.wakes_per_person_hour");
581 const wait = people.waitS(budget.key, max, at);
582 if (wait > 0)
583 return wakingResponse(parent, request, name, budgetRefusal({ name, budget, max, waitS: wait, limitsUrl: `${parentOrigin(parent.config)}/admin/limits` }), wait);
577584 const why = awakeRefusal(awakeCount(parent)) ?? (known ? undefined : rates.refusal(ledger.bodyId, at));
578585 if (why !== undefined) {
579586 const stop = lastStop(parent, ledger.bodyId);
580587 return wakingResponse(parent, request, name, stop === undefined ? why : stopSentence(stop));
581588 }
582589 if (!known) rates.note(ledger.bodyId, at);
583 if (ledger.ownerId !== undefined) people.note(ledger.ownerId, at);
590 people.note(budget.key, at);
584591 clearStop(parent, ledger.bodyId); // the wake is granted: the stop no longer explains anything
585592 reserved.set(ledger.bodyId, Date.now());
586593 touch(parent, ledger);
src/spawn/sleep.ts +49 −5
@@ -14,7 +14,7 @@
1414 import type { Database } from "bun:sqlite";
1515 import { readdirSync, readFileSync, statSync } from "node:fs";
1616 import { join } from "node:path";
17 import { limitValue } from "../settings/limits.ts";
17 import { LIMITS, limitValue } from "../settings/limits.ts";
1818
1919 type Env = Record<string, string | undefined>;
2020
@@ -27,7 +27,10 @@ function whole(env: Env, name: string, fallback: number): number {
2727
2828 /** A forge quiet for this long sleeps: FORGE_CHILD_IDLE_S, ten minutes by default. */
2929 export const idleAfterMs = (env: Env = process.env): number => whole(env, "FORGE_CHILD_IDLE_S", 600) * 1000;
30 /** Most hosted forges awake at once on this host: FORGE_CHILD_AWAKE_MAX. A sleeping forge does not count. */
30 /**
31 * Most hosted forges awake at once on this host: FORGE_CHILD_AWAKE_MAX. A sleeping forge does not
32 * count.
33 */
3134 export const awakeCeiling = (env: Env = process.env): number => whole(env, "FORGE_CHILD_AWAKE_MAX", 8);
3235 /** Most wakes of one forge in an hour: FORGE_CHILD_WAKES_PER_HOUR. */
3336 export const wakesPerHour = (env: Env = process.env): number => whole(env, "FORGE_CHILD_WAKES_PER_HOUR", 20);
@@ -50,7 +53,7 @@ export class WakeRate {
5053 : undefined;
5154 }
5255 /**
53 * Seconds until `key` (a person) may wake another forge, 0 when it may now:
56 * Seconds until `key` (a budget, `wakeBudget`) allows another wake, 0 when it does now:
5457 * `max` wakes in any hour; the oldest leaves the window at its time + 1 h.
5558 */
5659 waitS(key: string, max: number, now = Date.now()): number {
@@ -64,6 +67,42 @@ export class WakeRate {
6467 }
6568 }
6669
70 /**
71 * Whose budget of wakes an hour (`forges.wakes_per_person_hour`) a wake of one forge is counted
72 * against. `owner` is who claimed the forge, null while nobody has, undefined when its own
73 * tables could not be read just now.
74 */
75 export interface WakeBudget {
76 readonly key: string;
77 readonly owner: string | null | undefined;
78 }
79
80 /**
81 * A claimed forge's wakes count against its owner, the person who claimed it; an unclaimed
82 * forge's against the forge itself. Never against whoever sent it: one person sends forges to
83 * many, and a room of people each waking their own must not spend one budget (#13813). The
84 * owner is an account on the forge, not on this host, so the budget is theirs for that forge;
85 * a site admin's own forge is counted the same way, as anyone's is.
86 */
87 export function wakeBudget(bodyId: string, person: { readonly claimedBy: string | null } | undefined): WakeBudget {
88 const owner = person === undefined ? undefined : person.claimedBy;
89 return typeof owner === "string" ? { key: `${bodyId}\0${owner}`, owner } : { key: bodyId, owner };
90 }
91
92 /** A wait in plain words: seconds under two minutes, whole minutes from there, rounded up. */
93 export const waitWords = (s: number): string => (s < 120 ? `${s} ${s === 1 ? "second" : "seconds"}` : `${Math.ceil(s / 60)} minutes`);
94
95 /**
96 * The refusal when a budget of wakes is spent: whose it is, when the forge can be woken again,
97 * and the limit an admin of the host can raise, by the name it has on `limitsUrl`.
98 */
99 export function budgetRefusal(input: { readonly name: string; readonly budget: WakeBudget; readonly max: number; readonly waitS: number; readonly limitsUrl: string }): string {
100 const { name, budget, max } = input;
101 const whose = typeof budget.owner === "string" ? `its owner ${budget.owner} has` : budget.owner === null ? "a forge has until someone claims it" : "it has";
102 const label = LIMITS["forges.wakes_per_person_hour"].label;
103 return `${name} has been woken ${max} ${max === 1 ? "time" : "times"} in the last hour, which is all of the ${max} ${max === 1 ? "wake" : "wakes"} an hour ${whose}. It can be woken again in ${waitWords(input.waitS)}; an admin of this host can raise "${label}" at ${input.limitsUrl}.`;
104 }
105
67106 /** Why this host will not wake one more forge while `awake` are running, or undefined. */
68107 export function awakeRefusal(awake: number, env: Env = process.env): string | undefined {
69108 const max = awakeCeiling(env);
@@ -134,7 +173,9 @@ export function heldByPerson(dataDir: string, ownerId: string): number {
134173
135174 const MB = 1_000_000;
136175
137 /** How many forges this person holds on plan `key`; a ledger that names no plan is on the free one. */
176 /**
177 * How many forges this person holds on plan `key`; a ledger that names no plan is on the free one.
178 */
138179 export function ownedOnPlan(dataDir: string, ownerId: string, key: string, free: string): number {
139180 let n = 0;
140181 let files: string[] = [];
@@ -185,7 +226,10 @@ export function personRefusal(db: Database, dataDir: string, owner: { id: string
185226 return undefined;
186227 }
187228
188 /** The plain-text "waking up" or refusal answer: for a git client or an API call (a page is `web/pages/waking.ts`). */
229 /**
230 * The plain-text "waking up" or refusal answer: for a git client or an API call (a page is
231 * `web/pages/waking.ts`).
232 */
189233 export function wakingText(name: string, why?: string, retryS = 5): Response {
190234 const message = why ?? `${name} was asleep and is waking up; this takes a few seconds`;
191235 return new Response(message, {
test/forge-sleep.test.ts +1 −1
@@ -375,7 +375,7 @@ describe("a hosted forge scales to zero", () => {
375375 gateClock.now = () => t0 + 60_000;
376376 const refused = await gate({ accept: "text/html" });
377377 expect(refused?.status).toBe(429);
378 expect(await refused?.text()).toContain("waking too often, try in 3540 s");
378 expect(await refused?.text()).toContain("It can be woken again in 59 minutes");
379379 expect(refused?.headers.get("retry-after")).toBe("3540");
380380 gateClock.now = () => t0 + 3_600_000;
381381 expect(await gate()).toBeUndefined();
test/wake-budget.test.ts added +132
@@ -0,0 +1,132 @@
1 /**
2 * Whose budget a wake counts against (#13813): the forge's owner once someone has claimed it, the
3 * forge itself until then, never whoever sent it. One admin sends forges to a room of people; each
4 * of them waking their own must not spend one shared budget.
5 */
6 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
7 import { mkdtemp, rm } from "node:fs/promises";
8 import { tmpdir } from "node:os";
9 import { join } from "node:path";
10 import { spawnForge } from "../src/actions/spawn.ts";
11 import { createApp, type App } from "../src/app.ts";
12 import { createUser, type User } from "../src/core/users.ts";
13 import { serve, type Servers } from "../src/http/server.ts";
14 import { LIMITS, setLimit } from "../src/settings/limits.ts";
15 import { childAwake, gateClock, resolveHostedChild, sleepIdleChildren, wakeGate } from "../src/spawn/host.ts";
16 import { hostedPlacement } from "../src/spawn/placement.ts";
17 import { budgetRefusal, waitWords, wakeBudget } from "../src/spawn/sleep.ts";
18 import { quietLogs } from "./helpers/globals.ts";
19
20 quietLogs();
21
22 describe("whose budget a wake counts against", () => {
23 let dir = "";
24 let parent: App;
25 let servers: Servers;
26 const hostOf = (name: string) => `${name}--forge.test`;
27 const gate = (name: string, headers: Record<string, string> = {}) =>
28 wakeGate(parent, new Request("https://forge.test/", { headers: { host: hostOf(name), ...headers } }));
29 const visit = (name: string) => fetch(`${servers.url}/healthz`, { headers: { host: hostOf(name) } });
30 const allAsleep = async () => {
31 await sleepIdleChildren(parent, 600_000, Date.now() + 3_600_000);
32 for (const name of ["claimed", "unclaimed"]) expect(childAwake(parent, name)).toBe(false);
33 };
34
35 /** A forge the admin sends, as `/forges/new` does. */
36 async function send(admin: User, name: string): Promise<void> {
37 const spawned = await spawnForge(
38 parent,
39 admin,
40 { name, org: name, apps: [], carryBriefs: false, carrySubscriptions: false },
41 { catalog: [], briefs: [], subscriptions: [] },
42 {
43 placement: hostedPlacement({ host: "forge.test" }),
44 request: new Request("https://forge.test/spawn", { method: "POST", headers: { origin: "https://forge.test" } }),
45 url: new URL("https://forge.test/spawn"),
46 },
47 );
48 if (!spawned.ok) throw new Error(JSON.stringify(spawned.error));
49 }
50
51 beforeAll(async () => {
52 dir = await mkdtemp(join(tmpdir(), "wake-budget-"));
53 parent = createApp({ dataDir: dir, url: "https://forge.test", port: 0 });
54 const alice = await createUser(parent.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", isAdmin: true });
55 if (!alice.ok) throw new Error("user");
56 // One admin sends both forges; carol has claimed hers, nobody has claimed the other.
57 await send(alice.value, "claimed");
58 await send(alice.value, "unclaimed");
59 servers = await serve(parent);
60 const opened = await resolveHostedChild(parent, new Request("https://forge.test/healthz", { headers: { host: hostOf("claimed") } }));
61 if (opened === undefined || opened === "unknown" || opened === "cell") throw new Error("child not hosted");
62 const carol = await createUser(opened.db, { origin: "seed", trusted: true, username: "carol", email: "[email protected]", isAdmin: true });
63 if (!carol.ok) throw new Error("claimant");
64 await visit("unclaimed");
65 await allAsleep();
66 });
67
68 afterAll(async () => {
69 gateClock.now = () => Date.now();
70 servers?.stop();
71 parent?.close();
72 await rm(dir, { recursive: true, force: true });
73 });
74
75 test("the key: a claimed forge's owner, an unclaimed or unread forge itself", () => {
76 expect(wakeBudget("b1", { claimedBy: "carol" })).toEqual({ key: "b1\0carol", owner: "carol" });
77 expect(wakeBudget("b1", { claimedBy: null })).toEqual({ key: "b1", owner: null });
78 expect(wakeBudget("b1", undefined)).toEqual({ key: "b1", owner: undefined });
79 });
80
81 test("the wait is said in seconds, then in minutes rounded up", () => {
82 expect([1, 45, 119, 120, 121, 3_540].map(waitWords)).toEqual(["1 second", "45 seconds", "119 seconds", "2 minutes", "3 minutes", "59 minutes"]);
83 });
84
85 test("the refusal says whose wakes are spent, the wait, and the limit by its name and place", () => {
86 const say = (owner: string | null | undefined) =>
87 budgetRefusal({ name: "kiln", budget: { key: "k", owner }, max: 30, waitS: 700, limitsUrl: "https://forge.test/admin/limits" });
88 const tail = ` It can be woken again in 12 minutes; an admin of this host can raise "${LIMITS["forges.wakes_per_person_hour"].label}" at https://forge.test/admin/limits.`;
89 expect(say("carol")).toBe(`kiln has been woken 30 times in the last hour, which is all of the 30 wakes an hour its owner carol has.${tail}`);
90 expect(say(null)).toBe(`kiln has been woken 30 times in the last hour, which is all of the 30 wakes an hour a forge has until someone claims it.${tail}`);
91 expect(say(undefined)).toBe(`kiln has been woken 30 times in the last hour, which is all of the 30 wakes an hour it has.${tail}`);
92 expect(say("carol")).not.toContain("wakes_per_person_hour");
93 });
94
95 test("forges one admin sent do not share a budget: each is refused only for its own wakes", async () => {
96 const t0 = Date.now() + 10_000_000;
97 expect(setLimit(parent.db, "forges.wakes_per_person_hour", 1, "seed").ok).toBe(true);
98 try {
99 gateClock.now = () => t0;
100 // Carol wakes hers: the one wake her budget has this hour.
101 expect(await gate("claimed")).toBeUndefined();
102 // A visitor opens the other forge's claim link: its sender's other forge woke, and it is not
103 // refused.
104 expect(await gate("unclaimed")).toBeUndefined();
105 await visit("claimed");
106 await visit("unclaimed");
107 await allAsleep();
108
109 gateClock.now = () => t0 + 60_000;
110 const page = await gate("claimed", { accept: "text/html" });
111 const text = await gate("claimed");
112 const said = 'claimed has been woken 1 time in the last hour, which is all of the 1 wake an hour its owner carol has. It can be woken again in 59 minutes; an admin of this host can raise "Wakes per person per hour" at https://forge.test/admin/limits.';
113 expect(page?.status).toBe(429);
114 expect(page?.headers.get("retry-after")).toBe("3540");
115 // The page and the plain answer (a git client, an API call) say the same sentence.
116 expect((await page?.text())?.replaceAll("&quot;", '"')).toContain(said);
117 expect(text?.status).toBe(429);
118 expect(await text?.text()).toBe(said);
119 const other = await gate("unclaimed");
120 expect(other?.status).toBe(429);
121 expect(await other?.text()).toContain("unclaimed has been woken 1 time in the last hour, which is all of the 1 wake an hour a forge has until someone claims it. It can be woken again in 59 minutes");
122
123 // The hour passes: each has its wake again.
124 gateClock.now = () => t0 + 3_600_000;
125 expect(await gate("claimed")).toBeUndefined();
126 expect(await gate("unclaimed")).toBeUndefined();
127 } finally {
128 gateClock.now = () => Date.now();
129 setLimit(parent.db, "forges.wakes_per_person_hour", null, "seed");
130 }
131 });
132 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs