@worker-protocol/conformance 0.1.0

package/dist/checks/endpoints.js

@@ -0,0 +1,139 @@
+import { error as errorSchema } from "@worker-protocol/schemas";
+import { verdicts } from "../report.js";
+import { isJson } from "../transcript.js";
+/**
+ * The rules that are about every response rather than about one surface.
+ *
+ * These run last, over the whole transcript, because several of them are statements no single
+ * exchange can break: ENDP-26 forbids one code arriving under two statuses, which is a fact about
+ * a set. A check that asked it inside one surface would be asking a question it could not answer.
+ */
+export const CLAIMS = [
+    "ENDP-1",
+    "ENDP-11",
+    "ENDP-4",
+    "ENDP-5",
+    "ENDP-19",
+    "ENDP-25",
+    "ENDP-26",
+    "ENDP-29",
+];
+export function judgeTranscript(exchanges, codes, declared, rules) {
+    const { results, say } = verdicts(rules, CLAIMS);
+    if (exchanges.length === 0) {
+        for (const id of CLAIMS)
+            say(id, "notExercised", "no response was collected");
+        return results;
+    }
+    /**
+     * ENDP-1 is about an address, not about a URL.
+     *
+     * A read carries its parameters in the query string — MET-16 spells a dimension into one — and
+     * comparing whole URLs would report every filtered read as an undeclared address. What the
+     * Descriptor declares is where a surface answers; what a caller puts after the `?` is the
+     * question it asks there, and each surface's own file says which parameters those are.
+     */
+    const address = (url) => {
+        const parsed = new URL(url);
+        return `${parsed.origin}${parsed.pathname}`;
+    };
+    const addresses = new Set([...declared].map(address));
+    const byCode = new Map(codes.map((c) => [c.code, c]));
+    const failures = new Map();
+    const fail = (id, why) => {
+        const already = failures.get(id);
+        if (already)
+            already.push(why);
+        else
+            failures.set(id, [why]);
+    };
+    for (const exchange of exchanges) {
+        const where = `${exchange.method} ${exchange.url} → ${exchange.status}`;
+        // ENDP-1: every address other than the Descriptor's own route is declared in the Descriptor.
+        // The verifier can only judge its own behaviour here: it reaches an address because it read
+        // one, so what this establishes is that nothing it called was undeclared.
+        if (!addresses.has(address(exchange.url))) {
+            fail("ENDP-1", `${where} — an address the Descriptor did not declare`);
+        }
+        // ENDP-4: bodies and responses are JSON, UTF-8, `application/json`.
+        //
+        // A response with no body is not judged, and that is the rule read as written rather than a
+        // concession. A content type is a claim ABOUT a body; ACT-10 and ACT-11 have a Worker answer
+        // `204` and `202` with none, and requiring one there would be this verifier inventing an
+        // obligation out of a sentence that constrains bodies.
+        if (exchange.body.length > 0) {
+            if (!isJson(exchange.headers)) {
+                const got = exchange.headers.get("content-type") ?? "(none)";
+                fail("ENDP-4", `${where} — content-type ${got}`);
+            }
+            else if (exchange.json === null) {
+                fail("ENDP-4", `${where} — said application/json and did not parse`);
+            }
+        }
+        // ENDP-5: every protocol response carries both headers, stating what produced it.
+        for (const header of ["worker-protocol-edition", "worker-protocol-capability-version"]) {
+            if (!exchange.headers.has(header))
+                fail("ENDP-5", `${where} — no ${header}`);
+        }
+        if (exchange.status >= 200 && exchange.status < 300)
+            continue;
+        // ENDP-29: a response that is not a success carries one of the statuses the table lists. The
+        // success side is deliberately open, which is why only this branch is judged.
+        const statuses = new Set(codes.map((c) => c.status));
+        if (!statuses.has(exchange.status)) {
+            fail("ENDP-29", `${where} — a status no code in spec/endpoints.md names`);
+        }
+        // ENDP-25: every response that is not a success carries the shared envelope.
+        const envelope = errorSchema.safeParse(exchange.json);
+        if (!envelope.success) {
+            fail("ENDP-25", `${where} — ${envelope.error.issues[0]?.message ?? "no error envelope"}`);
+            continue;
+        }
+        // ENDP-26: a Worker answers a code with the status that code names. The class is already
+        // carried with the code by schemas/error.json, which is the half a schema can assert; this is
+        // the other half, and it is the reason the status table is generated rather than retyped.
+        const expected = byCode.get(envelope.data.code);
+        if (expected && expected.status !== exchange.status) {
+            fail("ENDP-26", `${where} — the code \`${envelope.data.code}\` fixes ${expected.status}`);
+        }
+    }
+    // ENDP-11: a Worker does not answer 5xx for a condition that will not change. A bad body
+    // answered with a 500 is an instruction to redeliver an unusable payload forever, and the
+    // sender will comply. The witness is ordinarily out of reach — nothing outside can tell a
+    // transient fault from a permanent one — but the verifier knows which of its OWN requests were
+    // deliberately and permanently wrong, because it made them that way.
+    const permanent = exchanges.filter((exchange) => exchange.permanent);
+    const wrongly = permanent.filter((exchange) => exchange.status >= 500);
+    if (permanent.length === 0) {
+        say("ENDP-11", "notExercised", "the run provoked no condition that will not change");
+    }
+    else if (wrongly.length === 0) {
+        say("ENDP-11", "passes");
+    }
+    else {
+        const first = wrongly[0];
+        say("ENDP-11", "fails", `${first.intent} answered ${first.status}`);
+    }
+    // ENDP-19 recommends that a Worker cap the page size rather than negotiating it. The witness is
+    // a collection longer than the cap, which is a cursor coming back; short of that there is
+    // nothing to see, and a Worker whose collections all fit in one page has not been observed
+    // either following it or not.
+    const capped = exchanges.some((exchange) => {
+        const cursor = exchange.json?.nextCursor;
+        return typeof cursor === "string" && cursor.length > 0;
+    });
+    if (capped)
+        say("ENDP-19", "passes");
+    else
+        say("ENDP-19", "notExercised", "no collection was long enough to be capped");
+    for (const id of CLAIMS) {
+        if (id === "ENDP-11" || id === "ENDP-19")
+            continue;
+        const why = failures.get(id);
+        if (why === undefined)
+            say(id, "passes");
+        else
+            say(id, "fails", why.length === 1 ? why[0] : `${why.length} responses: ${why[0]}, …`);
+    }
+    return results;
+}

package/dist/checks/events.d.ts

@@ -0,0 +1,16 @@
+import { type Attribution } from "../attribution.ts";
+import { type Result, type Rule } from "../report.ts";
+/**
+ * The `events` Capability, which is as far as a Descriptor reaches.
+ *
+ * **Nothing here calls anything, because there is nothing to call.** An event travels over a broker
+ * this protocol declines to name, so DESC-22 leaves the shared entry's address optional for this
+ * one Capability and a verifier has no surface to point at. Four of its nine rules are read off the
+ * Descriptor and the other five are somebody else's or nobody's — a protocol that declines to own
+ * a transport declines to see what crosses it, and that is a property of the design rather than a
+ * gap in this file.
+ *
+ * It takes no transcript for the same reason. A check that sent nothing is the honest shape here.
+ */
+export declare const CLAIMS: readonly ["EVT-11", "EVT-12", "EVT-4", "EVT-8"];
+export declare function checkEvents(entry: Record<string, unknown> | undefined, rules: Map<string, Rule>, attribution: Attribution): Result[];

package/dist/checks/events.js

@@ -0,0 +1,58 @@
+import { eventsEntry } from "@worker-protocol/schemas";
+import { ruleFor } from "../attribution.js";
+import { verdicts } from "../report.js";
+/**
+ * The `events` Capability, which is as far as a Descriptor reaches.
+ *
+ * **Nothing here calls anything, because there is nothing to call.** An event travels over a broker
+ * this protocol declines to name, so DESC-22 leaves the shared entry's address optional for this
+ * one Capability and a verifier has no surface to point at. Four of its nine rules are read off the
+ * Descriptor and the other five are somebody else's or nobody's — a protocol that declines to own
+ * a transport declines to see what crosses it, and that is a property of the design rather than a
+ * gap in this file.
+ *
+ * It takes no transcript for the same reason. A check that sent nothing is the honest shape here.
+ */
+export const CLAIMS = ["EVT-11", "EVT-12", "EVT-4", "EVT-8"];
+export function checkEvents(entry, rules, attribution) {
+    const { results, say } = verdicts(rules, CLAIMS);
+    if (entry === undefined) {
+        for (const id of CLAIMS)
+            say(id, "notExercised", "the Worker declares no `events`");
+        return results;
+    }
+    const declared = eventsEntry.safeParse(entry);
+    if (!declared.success) {
+        const blamed = new Set();
+        for (const issue of declared.error.issues) {
+            const id = ruleFor(attribution, "events-entry", issue.path) ?? "EVT-11";
+            if (blamed.has(id))
+                continue;
+            blamed.add(id);
+            say(id, "fails", `${issue.path.join(".") || "(root)"}: ${issue.message}`);
+        }
+        for (const id of CLAIMS) {
+            if (!blamed.has(id))
+                say(id, "notExercised", "the `events` entry did not validate");
+        }
+        return results;
+    }
+    const { publishes } = declared.data;
+    // EVT-11 and EVT-8 are what validation established: a broker, a protocol binding, a destination
+    // and the window a consumer sizes its deduplication store against. Neither string is parsed —
+    // this protocol names no broker and fixes no protocol binding — so a check says both are there.
+    say("EVT-11", "passes");
+    say("EVT-8", "passes");
+    // EVT-12 and EVT-4: every event type it publishes, each with the schema of its data, under a
+    // qualified name. A Worker that publishes none exercises neither, and an empty map is
+    // conformant — DESC-2 needs no qualification for a Capability declared with nothing in it.
+    if (Object.keys(publishes).length === 0) {
+        say("EVT-12", "notExercised", "the entry declares no event type");
+        say("EVT-4", "notExercised", "the entry declares no event type");
+    }
+    else {
+        say("EVT-12", "passes");
+        say("EVT-4", "passes");
+    }
+    return results;
+}

package/dist/checks/health.d.ts

@@ -0,0 +1,13 @@
+import { type Attribution } from "../attribution.ts";
+import { type Result, type Rule } from "../report.ts";
+import type { Transcript } from "../transcript.ts";
+/**
+ * The `health` Capability.
+ *
+ * HLTH-4 is not here and is not missing: a Worker that has not yet established its state answers
+ * `unhealthy`, and the only window in which that is observable is between a process starting and
+ * its first evaluation. Only whoever started the Worker knows a poll is inside one, so it is
+ * classified `H` and lives in `checks/arranged.ts` with the rest of what an arrangement reaches.
+ */
+export declare const CLAIMS: readonly ["HLTH-1", "HLTH-2", "HLTH-3", "HLTH-5"];
+export declare function checkHealth(entry: Record<string, unknown> | undefined, url: string | null, rules: Map<string, Rule>, attribution: Attribution, transcript: Transcript): Promise<Result[]>;

package/dist/checks/health.js

@@ -0,0 +1,85 @@
+import { healthEntry, health as healthSchema } from "@worker-protocol/schemas";
+import { ruleFor } from "../attribution.js";
+import { verdicts } from "../report.js";
+/**
+ * The `health` Capability.
+ *
+ * HLTH-4 is not here and is not missing: a Worker that has not yet established its state answers
+ * `unhealthy`, and the only window in which that is observable is between a process starting and
+ * its first evaluation. Only whoever started the Worker knows a poll is inside one, so it is
+ * classified `H` and lives in `checks/arranged.ts` with the rest of what an arrangement reaches.
+ */
+export const CLAIMS = ["HLTH-1", "HLTH-2", "HLTH-3", "HLTH-5"];
+export async function checkHealth(entry, url, rules, attribution, transcript) {
+    const { results, say } = verdicts(rules, CLAIMS);
+    if (entry === undefined) {
+        // DESC-2: a Worker that declares no `health` is conformant, and DESC-1's argument says what
+        // stands in for it — the Tower fetches the Descriptor on a schedule anyway.
+        for (const id of CLAIMS)
+            say(id, "notExercised", "the Worker declares no `health`");
+        return results;
+    }
+    // HLTH-1: a `health` entry declares an address. A verifier sees this in the Descriptor and fails
+    // the Worker without calling anything.
+    //
+    // It parses `healthEntry` and attributes the issue rather than reaching for `entry.address` by
+    // hand, which is what every other Capability here does. A check that read the shape itself would
+    // be the verifier holding an opinion about a document `schemas/` already describes.
+    const declared = healthEntry.safeParse(entry);
+    if (!declared.success) {
+        const issue = declared.error.issues[0];
+        const id = ruleFor(attribution, "health-entry", issue?.path ?? []) ?? "HLTH-1";
+        say(id, "fails", `${issue?.path.join(".") || "(root)"}: ${issue?.message}`);
+        for (const other of CLAIMS) {
+            if (other !== id)
+                say(other, "notExercised", "the `health` entry did not validate");
+        }
+        return results;
+    }
+    say("HLTH-1", "passes");
+    if (url === null) {
+        for (const id of ["HLTH-2", "HLTH-3", "HLTH-5"]) {
+            say(id, "notExercised", "the declared address did not resolve");
+        }
+        return results;
+    }
+    let answer;
+    try {
+        answer = await transcript.send(url, "the `health` address");
+    }
+    catch (cause) {
+        const why = cause instanceof Error ? cause.message : String(cause);
+        for (const id of ["HLTH-2", "HLTH-3", "HLTH-5"]) {
+            say(id, "notExercised", `${url} could not be reached: ${why}`);
+        }
+        return results;
+    }
+    // HLTH-5: a Worker answers its health address 200 whatever it reports. Anything else means the
+    // Worker did not answer, not that it is unwell — which is the one distinction a health surface
+    // exists to draw, and the one `503` destroys.
+    if (answer.status === 200) {
+        say("HLTH-5", "passes");
+    }
+    else {
+        say("HLTH-5", "fails", `answered ${answer.status}; the status is read from the body`);
+    }
+    const parsed = healthSchema.safeParse(answer.json);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        say("HLTH-2", "fails", `${issue?.path.join(".") || "(root)"}: ${issue?.message}`);
+        say("HLTH-3", "notExercised", "the answer did not validate, so it could not be judged");
+        return results;
+    }
+    say("HLTH-2", "passes");
+    // HLTH-3: a Worker does not answer `healthy` while any check it reports is not. It is what stops
+    // the summary from being decorative — the one field every console renders first.
+    const unwell = Object.entries(parsed.data.checks).filter(([, c]) => c.status !== "healthy");
+    if (parsed.data.status === "healthy" && unwell.length > 0) {
+        const names = unwell.map(([name, c]) => `${name} is ${c.status}`).join(", ");
+        say("HLTH-3", "fails", `the Worker answers \`healthy\` while ${names}`);
+    }
+    else {
+        say("HLTH-3", "passes");
+    }
+    return results;
+}

package/dist/checks/metrics.d.ts

@@ -0,0 +1,14 @@
+import { type Attribution } from "../attribution.ts";
+import { type Result, type Rule } from "../report.ts";
+import type { Transcript } from "../transcript.ts";
+/**
+ * The `metrics` Capability.
+ *
+ * The most checkable file in the specification — nineteen of its twenty rules have a witness a
+ * tool holding one ordinary credential can reach — and the one that needs a Worker with numbers in
+ * it. Several checks below report `notExercised` against a Worker that has accumulated nothing,
+ * which is not a weaker verdict than `passes`: it says a check exists and this run did not reach
+ * it, which is a gap somebody can close by pointing the tool at a Worker that has been running.
+ */
+export declare const CLAIMS: readonly ["MET-1", "MET-21", "MET-3", "MET-4", "MET-5", "MET-6", "MET-7", "MET-8", "MET-9", "MET-10", "MET-11", "MET-12", "MET-13", "MET-14", "MET-16", "MET-17", "MET-18", "MET-19", "MET-20", "NAME-1", "ENDP-20", "ENDP-23"];
+export declare function checkMetrics(entry: Record<string, unknown> | undefined, url: string | null, rules: Map<string, Rule>, attribution: Attribution, transcript: Transcript): Promise<Result[]>;