@worker-protocol/hono 0.1.0

package/dist/mount.js

@@ -0,0 +1,432 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { EDITION, nudge } from "@worker-protocol/schemas";
+import { actions as actionsSurface, IN_MEMORY, jsonSchema } from "./actions.js";
+import { byCode } from "./codes.js";
+import { collection, serializeSince } from "./collection.js";
+import { metrics as metricsSurface } from "./metrics.js";
+import { performAction, pollHealth, readActivity, readAlerts, readDescriptor, readMetric, readTasks, SURFACES, takeNudge, } from "./surfaces.js";
+import { tasks as taskSurface } from "./tasks.js";
+/**
+ * Write the builder `mount()` takes, and have a mistake reported where you made it.
+ *
+ * It returns its argument and does nothing at all at runtime. What it does is at the type level: a
+ * builder declared apart from the `mount()` call has nothing to check its object literal against,
+ * so the first complaint arrives at `mount()`, about a type nested six levels deep, naming a
+ * property three files away. Through this, a missing `since` is reported on `since`. An `async`
+ * builder is the same call, because `Worker | Promise<Worker>` is written here once instead of at
+ * every Worker that happens to await something.
+ *
+ * ```ts
+ * export const fleetWorker = defineWorker<Env>((env) => ({ id: "…", health: () => … }))
+ * export default { fetch: mount(fleetWorker).fetch }
+ * ```
+ *
+ * **No rule id can be cited for this line, and that is worth saying rather than dressing up.**
+ * `packages/README.md` asks that of everything in this package, and an identity function that
+ * exists to please a compiler answers nothing. It stays because the alternative — knowing that
+ * `WorkerBuilder` exists before you can annotate with it — is friction paid by every author, and
+ * `defineConfig`, `defineComponent` and `defineStore` have made this shape one a reader does not
+ * have to be taught. The type above is exported too, for a builder that was already written.
+ */
+export const defineWorker = (build) => build;
+const JSON_UTF8 = { "content-type": "application/json; charset=utf-8" };
+/** ENDP-25, ENDP-26: the envelope, with the status and class the code fixes and nothing chosen. */
+const envelope = ({ code, message }) => {
+    const row = byCode.get(code);
+    return new Response(JSON.stringify({ code, message, class: row?.class ?? "reject" }), {
+        status: row?.status ?? 400,
+        headers: JSON_UTF8,
+    });
+};
+const refused = (answer) => "code" in answer;
+/** What a write answered, as a response: a refusal enveloped, a body as JSON, or no body at all. */
+const reply = (c, answer) => {
+    if (refused(answer))
+        return envelope(answer);
+    if (answer.body === null)
+        return c.body(null, answer.status);
+    return c.json(answer.body, answer.status);
+};
+/** What a read answered: a refusal enveloped, or the page as `200`. */
+const page = (c, answer) => refused(answer) ? envelope(answer) : c.json(answer, 200);
+const query = (c) => new URL(c.req.url).searchParams;
+const bearer = (c) => {
+    const presented = c.req.header("authorization");
+    return presented?.startsWith("Bearer ") ? presented.slice("Bearer ".length) : undefined;
+};
+/** A parameter the route's declaration refuses is a parameter fault, and nothing was done. */
+const defaultHook = (result) => result.success
+    ? undefined
+    : envelope({ code: "invalid_parameter", message: "A parameter is missing or malformed." });
+// ENDP-24: an unrecognized filter parameter is `400` and is never ignored. A filter dropped in
+// silence answers with MORE than the caller asked for, in a shape it will happily parse. The
+// surfaces with parameters of their own check them where they know what they mean; the rest take
+// none, so anything at all is a parameter they cannot know.
+const noParameters = async (c, next) => {
+    const [first] = Object.keys(c.req.query());
+    if (first !== undefined) {
+        return envelope({
+            code: "unknown_filter",
+            message: `This address takes no parameter named ${first}.`,
+        });
+    }
+    await next();
+};
+/**
+ * One Worker's surfaces.
+ *
+ * **Nothing here holds state across requests any more, and that is deliberate.** Everything a rule
+ * needs to outlive one call — which today is ENDP-16's recorded outcomes and nothing else — is a
+ * store the Worker names, because `mount()` may answer a different `Worker` object on every
+ * request and a copy held here would start again with each one. That was the shape of three
+ * separate bugs before it was a principle.
+ */
+function surfacesOf(worker) {
+    return {
+        tasks: worker.tasks ? taskSurface(worker.tasks.raises, worker.tasks) : undefined,
+        actions: worker.actions ? actionsSurface(worker.actions) : undefined,
+        metrics: worker.metrics ? metricsSurface(worker.metrics) : undefined,
+    };
+}
+/**
+ * Two ways a Worker fails ENDP-16 without a single request going wrong.
+ *
+ * Neither is a conformance failure anything could find: a verifier sees two `200`s and has no way
+ * to know the Action ran twice. So they are found here, and said where somebody can act on them —
+ * thrown before a request exists where that is possible, and written to the log where it is not.
+ */
+const complainer = () => {
+    let complained = false;
+    return (fault) => {
+        if (fault === null || complained)
+            return;
+        complained = true;
+        console.error(fault);
+    };
+};
+/**
+ * A Worker that declares an idempotency key and names nowhere to record the outcome.
+ *
+ * It cannot keep the promise the key is for: every repeat performs the Action again, and answers
+ * as though it had not, which is the whole of what ENDP-16 exists to prevent.
+ */
+function unrecorded(worker) {
+    if (worker.actions === undefined || worker.actions.outcomes !== undefined)
+        return null;
+    const keyed = Object.entries(worker.actions.accepts)
+        .filter(([, action]) => action.idempotency !== undefined)
+        .map(([name]) => name);
+    if (keyed.length === 0)
+        return null;
+    return (`ENDP-16: ${keyed.join(", ")} declare${keyed.length === 1 ? "s" : ""} an idempotency key and ` +
+        "this Worker names nowhere to record an outcome. Set `actions.outcomes`: `memoryOutcomes()` " +
+        "in a single long-lived process, or a store over a durable object, a KV namespace or a " +
+        "table anywhere that runs more than one. A Map per isolate performs the Action twice under " +
+        "one key while the caller believes it is protected, and both calls answer 200.");
+}
+/**
+ * A Worker that builds its store INSIDE the function answering it, so there is a new one per
+ * request and each forgets what the last recorded — the same failure, reached by obeying the rule
+ * above. Only a memory store is compared: a Worker that builds a thin adapter per request over a
+ * durable backend is correct, and comparing identity alone would fail it.
+ */
+function forgetful(first, now) {
+    if (first === undefined || now === undefined || first === now)
+        return null;
+    if (first[IN_MEMORY] !== true || now[IN_MEMORY] !== true)
+        return null;
+    return ("ENDP-16: this Worker answered a second `memoryOutcomes()`, which means one is built on every " +
+        "request and forgets what the last recorded. Build it once, outside the function that answers " +
+        "the Worker, and close over it — or name a store that outlives the process.");
+}
+/** Every value of a record, mapped. Three Capabilities declare a map of Zod objects to convert. */
+const mapValues = (record, each) => Object.fromEntries(Object.entries(record).map(([key, value]) => [key, each(value)]));
+/** DESC-1. The Descriptor, derived from what the Worker implements and nothing else. */
+function descriptorOf(worker, edition) {
+    const capabilities = {};
+    // The Capabilities whose entry is the shared one and an address: what a Worker declares about
+    // them is that it implements them. The rest add something of their own below.
+    for (const name of ["health", "alerts", "activity", "nudges"]) {
+        if (worker[name])
+            capabilities[name] = { version: 1, address: `../${name}` };
+    }
+    if (worker.metrics) {
+        const { read, pageSize, ...declared } = worker.metrics;
+        capabilities.metrics = { version: 1, address: "../metrics", ...declared };
+    }
+    if (worker.actions) {
+        // ACT-2, ACT-3: the Descriptor carries JSON Schema, generated from the Zod object the Worker
+        // declared — one declaration, so the form a console renders and the validation a request meets
+        // are the same document and cannot drift.
+        const declared = {};
+        for (const [name, action] of Object.entries(worker.actions.accepts)) {
+            declared[name] = {
+                input: jsonSchema(action.input),
+                ...(action.result === undefined ? {} : { result: jsonSchema(action.result) }),
+                completesWithinCall: action.completesWithinCall ?? true,
+                ...(action.idempotency === undefined ? {} : { idempotency: action.idempotency }),
+                // ACT-15: where the Worker exposes its settings, the reading address is this app's to fix,
+                // because this app serves it — written into the declaration so the two cannot disagree.
+                ...(name === "configure" && worker.actions.settings ? { readAddress: "../settings" } : {}),
+            };
+        }
+        capabilities.actions = { version: 1, address: "../actions", accepts: declared };
+    }
+    // EVT-12, TASK-32, TASK-31: the Descriptor carries JSON Schema, generated from the Zod object the
+    // Worker declared — the same move ACT-2 makes, so a Worker writes one declaration and never two.
+    if (worker.events) {
+        capabilities.events = {
+            version: 1,
+            ...worker.events,
+            publishes: mapValues(worker.events.publishes, (declared) => ({
+                ...declared,
+                data: jsonSchema(declared.data),
+            })),
+        };
+    }
+    if (worker.tasks) {
+        capabilities.tasks = {
+            version: 1,
+            address: "../tasks",
+            raises: mapValues(worker.tasks.raises, (declared) => ({
+                payload: jsonSchema(declared.payload),
+                answeredBy: declared.answeredBy,
+            })),
+        };
+    }
+    const document = { id: worker.id, edition };
+    // TASK-31: at the root, beside the id, and omitted by a Worker with no Skill — which is what
+    // DESC-2 lets a Worker do with anything it does not implement. A Skill that states no
+    // requirement travels as `{}`: the claim, and nothing about what it needs.
+    if (worker.skills !== undefined) {
+        document.skills = mapValues(worker.skills, (skill) => ({
+            ...(skill.payload === undefined ? {} : { payload: jsonSchema(skill.payload) }),
+            ...(skill.produces === undefined ? {} : { produces: jsonSchema(skill.produces) }),
+        }));
+    }
+    document.capabilities = capabilities;
+    return JSON.stringify(document);
+}
+export function mount(source) {
+    /**
+     * What the runtime gave this request, where it gave one.
+     *
+     * Hono's accessor THROWS rather than answering `undefined` when there is none, and there is none
+     * on Node, on Bun, and on any `app.fetch(request, env)` called with two arguments — which is to
+     * say in most of this repository's own tests. A Worker that never uses it must not fail because
+     * of which runtime it woke up in.
+     */
+    const executionCtx = (c) => {
+        try {
+            return c.executionCtx;
+        }
+        catch {
+            return {};
+        }
+    };
+    /** The Worker for the request in hand. A static one is answered without being asked again. */
+    const resolve = typeof source === "function"
+        ? (c) => source(c.env, executionCtx(c))
+        : () => source;
+    /**
+     * ENDP-16's check, run once against the first Worker this app sees.
+     *
+     * Once because the fault it looks for is a mistake in how the Worker was WRITTEN, not in any one
+     * request: an author who named no store for a keyed Action named none on the first request
+     * either. Re-checking every request would buy nothing and would repeat the same message forever.
+     * A Worker handed in whole is checked before a request has arrived at all, which is where it
+     * does the most good; a builder cannot be, so the first one it answers is the first chance.
+     */
+    let checked = false;
+    let firstStore;
+    // Once per app and not once per process: two Workers mounted in one process are two Workers,
+    // and a fault in the second is not said by the first having said its own.
+    const warn = complainer();
+    const audited = async (c) => {
+        const worker = await resolve(c);
+        if (!checked) {
+            checked = true;
+            warn(unrecorded(worker));
+            firstStore = worker.actions?.outcomes;
+        }
+        else {
+            warn(forgetful(firstStore, worker.actions?.outcomes));
+        }
+        return worker;
+    };
+    // A Worker handed in whole is a shape this app can read before a request exists, so the fault is
+    // refused where somebody is still looking at it. A Worker answered per request has no such
+    // moment — so the same fault is said loudly on the first one, and not thrown: ENDP-11 forbids a
+    // `5xx` for a condition that will not change, and this one never will.
+    if (typeof source !== "function") {
+        checked = true;
+        const fault = unrecorded(source);
+        if (fault !== null)
+            throw new Error(fault);
+        firstStore = source.actions?.outcomes;
+    }
+    /**
+     * Which Capabilities this app registers a route for, or `null` when it cannot know yet.
+     *
+     * A Worker handed in whole is a shape this app can read at mount, so it registers exactly the
+     * addresses that Worker declares and its own OpenAPI document describes that Worker. A Worker
+     * answered per request is not knowable before one arrives, so every route is registered and the
+     * handler answers `404` for a Capability the resolved Worker does not declare. The document then
+     * describes the protocol's whole surface rather than this Worker's — which costs nothing on the
+     * wire, because ENDP-1 has every reader start from the Descriptor and nothing there is a path
+     * anybody assembles.
+     */
+    const declared = typeof source === "function"
+        ? null
+        : new Set(SURFACES.map((surface) => surface.capability)
+            .filter((name) => name !== "descriptor")
+            .filter((name) => source[name] !== undefined));
+    // DESC-23. Read from the static Worker where there is one, so the header is right before any
+    // request has arrived; a resolved Worker that declares another edition overrides it below.
+    const staticEdition = typeof source === "function" ? EDITION : (source.edition ?? EDITION);
+    const app = new OpenAPIHono({ defaultHook });
+    // ENDP-5, outermost, so that a refusal from any guard below carries the headers too. A caller
+    // reading a version it did not expect re-reads the Descriptor whatever the status was.
+    app.use(async (c, next) => {
+        await next();
+        if (!c.res.headers.has("worker-protocol-edition")) {
+            c.res.headers.set("worker-protocol-edition", staticEdition);
+        }
+        c.res.headers.set("worker-protocol-capability-version", "1");
+    });
+    // REG-7 and its converse: an address this Worker genuinely does not serve is `404`, and an
+    // address it does serve is never `404` in place of `401` — the guard below is registered on
+    // every path this app serves, so a credential is looked at exactly where a route answers.
+    app.notFound(() => envelope({ code: "not_found", message: "No such address." }));
+    const guard = async (c, next) => {
+        const worker = await audited(c);
+        // REG-21: the Worker accepts the credential recorded for it on every address this protocol
+        // defines, the Descriptor's route included. What makes one good is the Worker's (REG-3).
+        // REG-32: the refusal distinguishes nothing — a refusal that explains itself is an oracle.
+        const verdict = (await worker.authenticate?.(bearer(c))) ?? "accepted";
+        if (verdict !== "accepted")
+            return envelope({ code: verdict, message: "No." });
+        // ENDP-6: a caller may state the Capability version it expects, and a Worker that cannot
+        // answer that version refuses the request WHOLE rather than substituting its own. On every
+        // route, reads and writes alike, because ENDP-6 says `on a request` and a write is a request.
+        const asked = c.req.header("worker-protocol-capability-version");
+        if (asked !== undefined && asked !== "1") {
+            return envelope({ code: "unsupported_version", message: "This Worker answers version 1." });
+        }
+        c.res.headers.set("worker-protocol-edition", worker.edition ?? EDITION);
+        await next();
+    };
+    /**
+     * One surface, at the path this app serves it.
+     *
+     * **Every route is registered whether or not this Worker declares its Capability**, and the
+     * handler answers `404` when it does not — because with a Worker resolved per request there is
+     * no Worker at mount time to ask. That is the same answer an undeclared address gives today:
+     * DESC-2 admits any combination of Capabilities including none, and nothing a Descriptor does
+     * not declare is an address any reader of this protocol calls (ENDP-1).
+     */
+    const serve = (capability, path, route, handler, ownParameters = false) => {
+        if (capability !== null && declared !== null && !declared.has(capability))
+            return;
+        app.use(path, guard);
+        if (!ownParameters)
+            app.use(path, noParameters);
+        app.openapi({ ...route, path }, (async (c) => {
+            const worker = await audited(c);
+            return handler(c, worker);
+        }));
+    };
+    const undeclared = (capability) => envelope({ code: "not_found", message: `This Worker declares no \`${capability}\`.` });
+    /**
+     * DESC-1's document, built once where it can be.
+     *
+     * A Worker handed in whole is one object that nothing here can change, so building its Descriptor
+     * a second time could only produce the same bytes. A Worker answered per request is the case
+     * `WorkerSource` argues for: what it DECLARES may legitimately differ between two requests
+     * because its configuration may have, so that one is built each time and a cache would serve a
+     * document the Worker has stopped meaning. Nothing in `spec/` bears on this either way — REG-8
+     * is about two CALLERS seeing one document and says nothing about two moments.
+     */
+    const staticDescriptor = typeof source === "function" ? null : descriptorOf(source, source.edition ?? EDITION);
+    serve(null, readDescriptor.path, readDescriptor, async (c, worker) => c.body(staticDescriptor ?? descriptorOf(worker, worker.edition ?? EDITION), 200, JSON_UTF8));
+    // HLTH-5: `200` whatever it reports. The status is read from the body.
+    serve("health", "/health", pollHealth, async (c, worker) => worker.health ? c.json(await worker.health(), 200) : undeclared("health"));
+    serve("metrics", "/metrics", readMetric, async (c, worker) => {
+        const read = surfacesOf(worker).metrics;
+        if (!read)
+            return undeclared("metrics");
+        return page(c, await read(query(c)));
+    }, true);
+    // ACT-5: the Action is named in the query and the body is the input, raw.
+    serve("actions", "/actions", performAction, async (c, worker) => {
+        const perform = surfacesOf(worker).actions;
+        if (!perform)
+            return undeclared("actions");
+        return reply(c, await perform(query(c).get("action") ?? "", await c.req.text(), c.req.header("idempotency-key"), bearer(c)));
+    }, true);
+    // ACT-15: where the Worker exposes its settings, this app serves the reading address, which is
+    // why the declaration above points at it and the two cannot disagree.
+    app.use("/settings", guard);
+    app.use("/settings", noParameters);
+    app.get("/settings", async (c) => {
+        const worker = await audited(c);
+        const settings = worker.actions?.settings;
+        if (!settings || !worker.actions?.accepts.configure)
+            return undeclared("configure");
+        return c.json((await settings()));
+    });
+    // ALRT-2, ENDP-20: the Alerts whose conditions hold, in the page envelope this app builds.
+    serve("alerts", "/alerts", readAlerts, async (c, worker) => worker.alerts
+        ? page(c, collection(await worker.alerts(), query(c), serializeSince))
+        : undeclared("alerts"), true);
+    // ACTV-2, ENDP-20, ENDP-23: what this Worker holds, serialized and ordered here so that a Worker
+    // writes neither the instant's format nor the order. By id, which the Worker mints and nothing
+    // else here reorders — the same order the Tasks surface declares, for the same reason.
+    serve("activity", "/activity", readActivity, async (c, worker) => worker.activity
+        ? page(c, collection(await worker.activity(), query(c), serializeSince))
+        : undeclared("activity"), true);
+    /**
+     * NDG-2, NDG-3: told there is work of a Task type, and answered `204`.
+     *
+     * Every refusal here is written out rather than left to the route's validator, because the body is
+     * the one in this protocol whose shape is fixed by the protocol: a Worker that declares `nudges`
+     * owes exactly these answers, and a library's own `400` for a body it could not parse is not one
+     * of them (ENDP-25).
+     */
+    serve("nudges", "/nudges", takeNudge, async (c, worker) => {
+        if (!worker.nudges)
+            return undeclared("nudges");
+        let body;
+        try {
+            body = JSON.parse(await c.req.text());
+        }
+        catch {
+            return envelope({ code: "malformed_request", message: "The body did not parse as JSON." });
+        }
+        const told = nudge.safeParse(body);
+        if (!told.success) {
+            return envelope({
+                code: "schema_mismatch",
+                message: "A nudge carries one Task type and nothing else.",
+            });
+        }
+        // NDG-3: a type this Worker declares no Skill for is `404`, and nothing happened. Taking one
+        // would tell an owner it had been told, and the owner would stop nudging whoever could help.
+        if (worker.skills?.[told.data.type] === undefined) {
+            return envelope({
+                code: "not_found",
+                message: `This Worker declares no Skill for ${told.data.type}.`,
+            });
+        }
+        await worker.nudges(told.data.type);
+        return c.body(null, 204);
+    });
+    // TASK-5, TASK-6: the Tasks whose conditions hold, and only those the credential covers.
+    serve("tasks", "/tasks", readTasks, async (c, worker) => {
+        const tasks = surfacesOf(worker).tasks;
+        if (!tasks)
+            return undeclared("tasks");
+        return page(c, await tasks.read(query(c), bearer(c)));
+    }, true);
+    return app;
+}