@worker-protocol/hono 0.1.0

package/dist/metrics.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The `metrics` surface: every rule in `spec/metrics.md` that is not a number.
+ *
+ * What a Worker knows is how much of something happened. What it has had to write until now is the
+ * parameter validation, the half-open interval, the boundaries cut in a declared zone, the ISO
+ * week, the ordering with its tiebreak and the page envelope — all of it fixed by MET-8 through
+ * MET-20 and identical in every Worker. So this asks a Worker for values over buckets it has
+ * already cut, and answers the rest itself.
+ */
+import { type metricDeclaration, type metricPage } from "@worker-protocol/schemas";
+import type * as z from "zod";
+import { type Granularity } from "./buckets.ts";
+import type { Refusal } from "./worker.ts";
+export type MetricDeclarations = Record<string, z.infer<typeof metricDeclaration>>;
+/** One period of one metric, already cut in the zone the entry declares (MET-12, MET-20). */
+export type Bucket = {
+    start: Date;
+    end: Date;
+};
+/** What a Worker is asked for: values, over buckets it did not have to compute. */
+export type MetricQuery = {
+    /** MET-8. One of the metrics the entry declares. */
+    metric: string;
+    /** MET-3. One of the granularities that metric declares. */
+    granularity: Granularity;
+    /** MET-11, MET-12. The whole buckets the interval covers, ascending. */
+    buckets: Bucket[];
+    /** MET-16, MET-17. The dimensions this read fixes, each a value the declaration admits. */
+    fixed: Record<string, string>;
+    /** MET-19. The dimensions to break down by, each one that declared its set of values. */
+    by: string[];
+};
+/**
+ * One value. MET-15 draws the distinction that matters: a bucket a Worker accumulated nothing in
+ * is ABSENT from the answer, and one it no longer holds carries `null`. Returning neither is the
+ * first case, and it is the common one.
+ */
+export type MetricSample = {
+    /** The `start` of one of the buckets that were asked for. */
+    start: Date;
+    value: number | null;
+    /** MET-19. One value per dimension named in `by`, and absent where nothing was broken down. */
+    dimensions?: Record<string, string>;
+};
+export type MetricFacts = {
+    timeZone: string;
+    /** MET-21. Every metric this Worker publishes, keyed by name. */
+    publishes: MetricDeclarations;
+    /** The Worker's own facts. Everything around this call is the specification's. */
+    read: (query: MetricQuery) => MetricSample[] | Refusal | Promise<MetricSample[] | Refusal>;
+    /** ENDP-19 (recommended). The most buckets one page carries. */
+    pageSize?: number;
+};
+type MetricPage = z.infer<typeof metricPage>;
+export declare function metrics(facts: MetricFacts): (query: URLSearchParams) => Promise<Refusal | MetricPage>;
+export {};

package/dist/metrics.js

@@ -0,0 +1,122 @@
+/**
+ * The `metrics` surface: every rule in `spec/metrics.md` that is not a number.
+ *
+ * What a Worker knows is how much of something happened. What it has had to write until now is the
+ * parameter validation, the half-open interval, the boundaries cut in a declared zone, the ISO
+ * week, the ordering with its tiebreak and the page envelope — all of it fixed by MET-8 through
+ * MET-20 and identical in every Worker. So this asks a Worker for values over buckets it has
+ * already cut, and answers the rest itself.
+ */
+import { INSTANT } from "@worker-protocol/schemas";
+import { bucketsIn, rfc3339 } from "./buckets.js";
+const refuse = (code, message) => ({ code, message });
+/** MET-5, MET-8, MET-11, MET-19, ENDP-20 — what this read defines, and what a dimension may not be. */
+const OWN_PARAMETERS = new Set(["metric", "granularity", "from", "to", "by", "cursor"]);
+export function metrics(facts) {
+    const cap = facts.pageSize ?? 500;
+    return async function read(query) {
+        // MET-8: a read names one metric. MET-9: one the entry does not declare is a resource that
+        // does not exist, which is MET-10's division — the name is wrong, not the parameter.
+        const name = query.get("metric");
+        if (name === null)
+            return refuse("invalid_parameter", "A read names one metric.");
+        const declaration = facts.publishes[name];
+        if (declaration === undefined) {
+            return refuse("not_found", `No metric named ${name} is declared.`);
+        }
+        const { dimensions, granularities } = declaration;
+        // ENDP-24: an unrecognized filter is `400` and is never ignored. A dimension is spelled into a
+        // parameter of its own name (MET-16), so what is left after those is a name nobody declared.
+        for (const key of query.keys()) {
+            if (OWN_PARAMETERS.has(key) || key in dimensions)
+                continue;
+            return refuse("unknown_filter", `This metric declares no dimension named ${key}.`);
+        }
+        // MET-8, MET-10: named where the metric declares more than one, omittable where it declares
+        // exactly one, and `400` for one it does not accumulate by.
+        const asked = query.get("granularity");
+        if (asked === null && granularities.length > 1) {
+            return refuse("invalid_parameter", "This metric declares more than one granularity.");
+        }
+        const granularity = (asked ?? granularities[0]);
+        if (!granularities.includes(granularity)) {
+            return refuse("invalid_parameter", `This metric does not accumulate by ${granularity}.`);
+        }
+        // MET-11: RFC 3339 instants carrying an offset, half-open, so two adjacent reads add up.
+        const instant = (raw) => {
+            if (raw === null)
+                return null;
+            return INSTANT.test(raw) ? Date.parse(raw) : Number.NaN;
+        };
+        const from = instant(query.get("from"));
+        const to = instant(query.get("to"));
+        if (Number.isNaN(from) || Number.isNaN(to)) {
+            return refuse("invalid_parameter", "`from` and `to` are RFC 3339 instants.");
+        }
+        const now = Date.now();
+        const end = to ?? now;
+        // Absent, `from` is the start of the current bucket: the question a console asks by default is
+        // about the period in progress, not about all of history.
+        const start = from ?? bucketsIn(end - 1, end, granularity, facts.timeZone)[0]?.start ?? end;
+        // MET-19: only a dimension that declared its set of values may be grouped by. Over a free one
+        // nothing bounds the number of series, so it is filtered and never grouped.
+        const by = query.getAll("by");
+        for (const dimension of by) {
+            const declared = dimensions[dimension];
+            if (declared === undefined) {
+                return refuse("unknown_filter", `This metric declares no dimension named ${dimension}.`);
+            }
+            if (declared.values === undefined) {
+                return refuse("invalid_parameter", `${dimension} declares no set of values to group by.`);
+            }
+        }
+        // MET-16, MET-17: a value outside a declared set is refused. Where no set is declared the
+        // Worker cannot tell a typo from a value it has not seen, so any string is accepted.
+        const fixed = {};
+        for (const [dimension, declared] of Object.entries(dimensions)) {
+            const value = query.get(dimension);
+            if (value === null)
+                continue;
+            if (declared.values !== undefined && !declared.values.includes(value)) {
+                return refuse("invalid_parameter", `${dimension} does not take the value ${value}.`);
+            }
+            fixed[dimension] = value;
+        }
+        const cut = bucketsIn(start, end, granularity, facts.timeZone);
+        const samples = await facts.read({
+            metric: name,
+            granularity,
+            buckets: cut.map((bucket) => ({ start: new Date(bucket.start), end: new Date(bucket.end) })),
+            fixed,
+            by,
+        });
+        if (!Array.isArray(samples))
+            return samples;
+        const endOf = new Map(cut.map((bucket) => [bucket.start, bucket.end]));
+        // MET-14: ascending by start, and within one start by the values broken down by — an order
+        // with ties in it is not one a cursor could resume from. MET-13: the end is carried rather
+        // than derived, because a day across a transition is 23 or 25 hours.
+        const ordered = samples
+            .map((sample) => ({ sample, at: sample.start.getTime() }))
+            .filter(({ at }) => endOf.has(at))
+            .sort((a, b) => a.at - b.at ||
+            by
+                .map((d) => a.sample.dimensions?.[d] ?? "")
+                .join()
+                .localeCompare(by.map((d) => b.sample.dimensions?.[d] ?? "").join()));
+        const from_ = Number(query.get("cursor") ?? "0");
+        if (!Number.isInteger(from_) || from_ < 0) {
+            return refuse("invalid_parameter", "That cursor was not produced by this Worker.");
+        }
+        const items = ordered.slice(from_, from_ + cap).map(({ sample, at }) => ({
+            start: rfc3339(at),
+            end: rfc3339(endOf.get(at)),
+            value: sample.value,
+            ...(by.length > 0 && sample.dimensions !== undefined
+                ? { dimensions: sample.dimensions }
+                : {}),
+        }));
+        const next = from_ + cap;
+        return next < ordered.length ? { items, nextCursor: String(next) } : { items };
+    };
+}

package/dist/mount.d.ts

@@ -0,0 +1,92 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { Worker } from "./worker.ts";
+/**
+ * Everything a conformant Worker owes and nobody should write twice, as one Hono app.
+ *
+ * `mount(worker)` takes what only the Worker knows — see `worker.ts` — and returns an app that
+ * serves the Descriptor at the one route this protocol fixes (DESC-3) and every declared
+ * Capability at an address of its own. Mount it wherever the Worker lives: at the root, or under a
+ * path beside an application that already owns the root.
+ *
+ * **It takes a Worker, or a function that answers one from an environment.** The second form is
+ * the one most Workers on this network need and the reason is not a detail of any one platform: a
+ * Cloudflare Worker, a Vercel edge function and a Deno Deploy handler are all handed their
+ * bindings, secrets and execution context *per request*, so a Worker built once at module scope
+ * cannot reach a database, a queue or a durable object at all. Only a long-lived Node or Bun
+ * process has an ambient environment, and that is the narrower case.
+ *
+ * ```ts
+ * // Cloudflare, Vercel edge, Deno Deploy — env arrives with the request
+ * export default { fetch: mount<Env>((env) => workerFor(env)).fetch }
+ *
+ * // Node, Bun, Deno with an ambient environment
+ * export const app = mount(worker)
+ * ```
+ *
+ * What it carries, so that a Worker author does not: ENDP-5's two headers on every response;
+ * REG-3 and REG-21; ENDP-6's whole refusal of a version it cannot answer; ENDP-24; ENDP-25 and
+ * ENDP-26's envelope; ENDP-19 through ENDP-23's page and cursor; DESC-12's addresses; TASK-5's
+ * filter and TASK-28's page; MET-7 through MET-20, the parameters and the boundaries; ACT-6 through
+ * ACT-12 and ENDP-15 through ENDP-18; and ACT-2 and ACT-3's JSON Schema, generated from the Zod
+ * object a Worker declared so the document a console renders a form from and the object a request
+ * is validated against are one declaration.
+ *
+ * What it does not carry is anything the Worker is authoritative over: whether a credential is
+ * good, which conditions hold, what a number is, what performing an Action does.
+ */
+/** What a runtime hands a `fetch` handler beside the environment. Structural, so every one fits. */
+export type ExecutionCtx = {
+    waitUntil?: (promise: Promise<unknown>) => void;
+};
+/**
+ * A Worker, or how to answer one from the environment of the request in hand.
+ *
+ * **It may be async, and that is how a configurable Worker declares what its configuration says.**
+ * A time zone kept in a database, a set of metrics that depends on what an operator switched on, a
+ * broker read from a settings row: all of it is awaited here, once, and the object answered is an
+ * ordinary Worker. No field of that object needs to be a function of its own, which is why none is.
+ *
+ * ```ts
+ * export default {
+ *   fetch: mount<Env>(async (env) => {
+ *     const settings = await configuration(env); // cached; see below
+ *     return { id: "…", metrics: { timeZone: settings.zone, publishes: published(settings), read } };
+ *   }).fetch,
+ * }
+ * ```
+ *
+ * Two things follow and both are worth knowing before writing that. **It runs on every request**,
+ * the Tower's polls included, so a Worker that reads a store here caches the result — in module
+ * scope, which on an isolate runtime is a cache and not durable state, and is exactly the right
+ * place for one. And **what it DECLARES may not differ between two callers**, because REG-8
+ * requires the Descriptor to be the same document for every one of them: configuration that
+ * changes gives every caller a new Descriptor, which is ordinary, and configuration read per
+ * caller is the thing REG-8 forbids.
+ */
+export type WorkerSource<E = unknown> = Worker | WorkerBuilder<E>;
+/** What `mount()` takes when a Worker is answered from the environment of each request. */
+export type WorkerBuilder<E = unknown> = (env: E, ctx: ExecutionCtx) => Worker | Promise<Worker>;
+/**
+ * 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 declare const defineWorker: <E = unknown>(build: WorkerBuilder<E>) => WorkerBuilder<E>;
+export declare function mount<E = unknown>(source: WorkerSource<E>): OpenAPIHono;