@txco/web-abi 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,110 @@
-# Temporary Holding Version
+# @txco/web-abi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The conformance kit for the [Thanks, Computer](https://www.thanks.computer) (TxCo) Web ABI: the contract a framework's build
+produces so `txco` can deploy it.
+
+```
+<out>/
+  txco-web.json     the manifest: what the build is, never its routing
+  public/           files, installed as the stack's FILES/
+  server/           an optional Fetch handler: export default { fetch(request, ctx) }
+  ops/              ordinary .txcl, in scope directories (ops/900000/…)
+```
+
+The kit has four parts:
+
+- **The manifest schema** (`txco-web.schema.json`) and a validator. `txco`
+  embeds the same schema file, and both validators pass the same test corpus.
+- **The envelope ↔ Fetch bridge**, which every runner uses. It turns the
+  chassis's request envelope into a Fetch `Request`, calls the handler, and
+  turns the `Response` into the delta the chassis merges.
+- **A harness** that checks a build's `server/` before any runner exists, and
+  serves a build locally.
+- **The producer helpers** (`@txco/web-abi/producer`) that a framework adapter,
+  preset or plugin writes a build with. They render the ops (a navigation op
+  and the catch-all), write and validate the manifest, and guard the output
+  directory before a build wipes it. Producers built on them answer requests
+  the same way.
+
+`txco web check <out>` checks the rest: the files, the ops, and every request
+the build has to answer.
+
+## The manifest
+
+```json
+{
+  "abi": 1,
+  "server": { "entry": "server/index.mjs" },
+  "immutable": ["_app/immutable/"]
+}
+```
+
+| Field          | Meaning                                                                               |
+| -------------- | ------------------------------------------------------------------------------------- |
+| `abi`          | `1`                                                                                   |
+| `server.entry` | The handler module, under `server/`. Leave it out for a static build.                 |
+| `immutable`    | `public/` prefixes whose file names carry a content hash. They are cached for a year. |
+
+Keys starting with `x-` are free for producers. Any other key is an error.
+
+## The server contract
+
+```js
+export default {
+  async fetch(request, ctx) {
+    // a Fetch Request; ctx = { client: { ip } }
+    return new Response("…");
+  },
+};
+```
+
+- **Buffered both ways.** An answer is capped at about 3 MiB of body.
+- **Cookies.** Each `Set-Cookie` arrives on its own line.
+- **Errors.** A handler that throws, or returns something other than a
+  `Response`, answers `500` without revealing why.
+
+## Use
+
+```sh
+npx txco-web-abi validate <out>                 # the manifest
+npx txco-web-abi check-server <out> [--json]    # drive server/ through the bridge
+npx txco-web-abi serve <out> [--port 8787]      # public/ first, then server/
+```
+
+```js
+import {
+  dispatch,
+  envelopeToRequest,
+  responseToDelta,
+} from "@txco/web-abi/bridge";
+import { validateManifest } from "@txco/web-abi/manifest";
+```
+
+## Write a producer
+
+```js
+import { checkOutDir, renderOps, writeManifest, writeOps } from "@txco/web-abi/producer";
+
+// Before the build: refuse an output dir inside OPS/, one holding foreign
+// files, or one holding the project.
+const problems = checkOutDir({ dir: out, protect: [root, outDir], notInside: [outDir], entries });
+
+// After it: public/ is in place. One navigation op (the shell with 200 for
+// an app that routes in the browser, or the 404 page with 404), plus the
+// catch-all at 900900.
+await writeOps(out, renderOps({ mode: "spa", producer: "my-adapter", page: { name: "index.html", html } }));
+await writeManifest(out, { abi: 1, immutable: ["assets/"], "x-producer": { name: "my-adapter" } });
+```
+
+`@txco/vite-plugin` is built this way.
+
+## Develop
+
+```sh
+npm install
+npm test     # tsc, then node --test (Node 20+)
+```
+
+## License
+
+MIT

package/dist/bridge.d.ts

@@ -0,0 +1,25 @@
+import type { FetchHandler, TxcContext, TxcDelta, TxcEnvelope } from "./envelope.js";
+/** An op answer is capped at 4 MiB (--op-payload-max); the body is base64 inside it. */
+export declare const DEFAULT_MAX_ANSWER_BYTES: number;
+export interface RequestOptions {
+    /** Refuse a request body larger than this (bytes). Default: no limit. */
+    maxBodyBytes?: number;
+}
+/** Builds the Fetch Request an envelope describes. */
+export declare function envelopeToRequest(env: TxcEnvelope, opts?: RequestOptions): Request;
+/** The handler's context: only what the contract defines. */
+export declare function contextFrom(env: TxcEnvelope): TxcContext;
+export interface DeltaOptions {
+    /** The request's method: a HEAD answer carries no body. */
+    method?: string;
+    /** Refuse a body larger than this (bytes). */
+    maxAnswerBytes?: number;
+}
+/** Turns a Response into the chassis delta. */
+export declare function responseToDelta(res: Response, opts?: DeltaOptions): Promise<TxcDelta>;
+/**
+ * Runs one request through a handler, end to end. A handler that throws, or
+ * returns something other than a Response, answers 500; the error is never
+ * shown to the client.
+ */
+export declare function dispatch(handler: FetchHandler, env: TxcEnvelope, opts?: RequestOptions & DeltaOptions): Promise<TxcDelta>;

package/dist/bridge.js

@@ -0,0 +1,103 @@
+// The envelope ↔ Fetch bridge. A runner hands it the chassis's request
+// envelope; it builds a Fetch Request, calls the server entry, and turns the
+// Response into the delta the chassis merges. Every runner uses this one
+// mapping, so a handler sees the same Request wherever it runs.
+/** An op answer is capped at 4 MiB (--op-payload-max); the body is base64 inside it. */
+export const DEFAULT_MAX_ANSWER_BYTES = 3 * 1024 * 1024;
+// Hop-by-hop headers (RFC 9110 §7.6.1) and those the Request computes.
+const DROPPED_HEADERS = new Set([
+    "connection", "keep-alive", "proxy-connection", "transfer-encoding", "te", "trailer",
+    "upgrade", "content-length", "host",
+]);
+/** Builds the Fetch Request an envelope describes. */
+export function envelopeToRequest(env, opts = {}) {
+    const req = env._txc?.web?.req ?? {};
+    const method = (req.method ?? "GET").toUpperCase();
+    let url = req.url?.full;
+    if (!url) {
+        const host = req.host ?? "localhost";
+        const raw = req.url?.query?.raw;
+        url = `http://${host}${req.url?.path ?? "/"}${raw ? "?" + raw : ""}`;
+    }
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(req.headers ?? {})) {
+        if (DROPPED_HEADERS.has(name.toLowerCase()))
+            continue;
+        for (const v of Array.isArray(value) ? value : [value])
+            headers.append(name, v);
+    }
+    let body;
+    if (req.body && method !== "GET" && method !== "HEAD") {
+        const bytes = Buffer.from(req.body, "base64");
+        if (opts.maxBodyBytes !== undefined && bytes.byteLength > opts.maxBodyBytes) {
+            throw new Error(`request body is ${bytes.byteLength} bytes, over ${opts.maxBodyBytes}`);
+        }
+        body = new ArrayBuffer(bytes.byteLength);
+        new Uint8Array(body).set(bytes);
+    }
+    return new Request(url, { method, headers, body });
+}
+/** The handler's context: only what the contract defines. */
+export function contextFrom(env) {
+    return Object.freeze({ client: Object.freeze({ ip: env._txc?.client?.ip ?? "" }) });
+}
+/** Turns a Response into the chassis delta. */
+export async function responseToDelta(res, opts = {}) {
+    const headers = {};
+    res.headers.forEach((value, name) => {
+        if (name === "set-cookie")
+            return; // each cookie on its own line, below
+        (headers[name] ??= []).push(value);
+    });
+    const cookies = res.headers.getSetCookie();
+    if (cookies.length > 0)
+        headers["set-cookie"] = cookies;
+    const delta = { _txc: { web: { res: { status: res.status, headers } }, halt: true } };
+    const noBody = (opts.method ?? "GET").toUpperCase() === "HEAD" || res.status === 204 || res.status === 304;
+    if (!noBody) {
+        const bytes = Buffer.from(await res.arrayBuffer());
+        const max = opts.maxAnswerBytes ?? DEFAULT_MAX_ANSWER_BYTES;
+        if (bytes.byteLength > max) {
+            throw new Error(`response body is ${bytes.byteLength} bytes, over the ${max}-byte answer limit`);
+        }
+        if (bytes.byteLength > 0)
+            delta._txc.web.res.body = bytes.toString("base64");
+    }
+    return delta;
+}
+function errorDelta(status, message, method) {
+    const res = { status, headers: { "content-type": ["text/plain; charset=utf-8"] } };
+    if (method.toUpperCase() !== "HEAD")
+        res.body = Buffer.from(message + "\n").toString("base64");
+    return { _txc: { web: { res }, halt: true } };
+}
+/**
+ * Runs one request through a handler, end to end. A handler that throws, or
+ * returns something other than a Response, answers 500; the error is never
+ * shown to the client.
+ */
+export async function dispatch(handler, env, opts = {}) {
+    const method = env._txc?.web?.req?.method ?? "GET";
+    let request;
+    try {
+        request = envelopeToRequest(env, opts);
+    }
+    catch {
+        return errorDelta(413, "request body too large", method);
+    }
+    let res;
+    try {
+        res = await handler.fetch(request, contextFrom(env));
+    }
+    catch {
+        return errorDelta(500, "internal error", method);
+    }
+    if (!(res instanceof Response))
+        return errorDelta(500, "internal error", method);
+    try {
+        return await responseToDelta(res, { ...opts, method: request.method });
+    }
+    catch {
+        return errorDelta(502, "response too large", method);
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// txco-web-abi: validate a manifest, check a build's server/, or serve a
+// build locally.
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { checkServer, serve } from "./harness.js";
+import { MANIFEST_NAME, validateManifest } from "./manifest.js";
+const USAGE = `Usage: txco-web-abi <command> <abi-dir>
+
+Commands:
+  validate <abi-dir>                 check txco-web.json against the Web ABI schema
+  check-server <abi-dir> [--json]    drive the build's server/ entry through the bridge
+  serve <abi-dir> [--port N]         serve public/ and server/ locally
+`;
+async function main(argv) {
+    const [cmd, dir, ...rest] = argv;
+    if (!cmd || !dir) {
+        process.stderr.write(USAGE);
+        return 2;
+    }
+    switch (cmd) {
+        case "validate": {
+            let doc;
+            try {
+                doc = JSON.parse(await readFile(join(dir, MANIFEST_NAME), "utf8"));
+            }
+            catch (e) {
+                process.stderr.write(`${MANIFEST_NAME}: ${e.message}\n`);
+                return 1;
+            }
+            const r = validateManifest(doc);
+            if (r.ok) {
+                process.stdout.write(`${MANIFEST_NAME}: ok\n`);
+                return 0;
+            }
+            for (const p of r.errors)
+                process.stdout.write(`${p.pointer || "/"}: ${p.message}\n`);
+            return 1;
+        }
+        case "check-server": {
+            const results = await checkServer(dir);
+            if (rest.includes("--json")) {
+                process.stdout.write(JSON.stringify({ ok: results.every((r) => r.ok), results }, null, 2) + "\n");
+            }
+            else {
+                for (const r of results)
+                    process.stdout.write(`${r.ok ? "✓" : "✗"} ${r.name}${r.detail ? "  " + r.detail : ""}\n`);
+            }
+            return results.every((r) => r.ok) ? 0 : 1;
+        }
+        case "serve": {
+            const i = rest.indexOf("--port");
+            const port = i >= 0 ? Number(rest[i + 1]) : 8787;
+            const server = await serve(dir, { port });
+            const addr = server.address();
+            process.stdout.write(`serving ${dir} on http://127.0.0.1:${typeof addr === "object" && addr ? addr.port : port}\n`);
+            return await new Promise(() => { }); // until interrupted
+        }
+        default:
+            process.stderr.write(USAGE);
+            return 2;
+    }
+}
+main(process.argv.slice(2)).then((code) => process.exit(code), (e) => {
+    process.stderr.write(`txco-web-abi: ${e.message}\n`);
+    process.exit(1);
+});

package/dist/envelope.d.ts

@@ -0,0 +1,57 @@
+/** The parts of the chassis's request envelope the bridge reads. */
+export interface TxcEnvelope {
+    _txc?: {
+        client?: {
+            ip?: string;
+        };
+        web?: {
+            req?: {
+                method?: string;
+                host?: string;
+                url?: {
+                    full?: string;
+                    path?: string;
+                    query?: {
+                        raw?: string;
+                    };
+                };
+                /** Header name → values, one per line. */
+                headers?: Record<string, string[] | string>;
+                /** The body, base64; absent when empty. */
+                body?: string;
+            };
+        };
+    };
+    [k: string]: unknown;
+}
+/** The response half: what an op writes to answer an HTTP request. */
+export interface TxcWebRes {
+    status: number;
+    /** Lower-case header name → values. */
+    headers: Record<string, string[]>;
+    /** The body, base64; absent for HEAD, 204 and 304. */
+    body?: string;
+}
+/**
+ * The bridge's answer: a delta the chassis merges into the run, never the
+ * envelope echoed back (op answers merge by appending arrays, so an echo
+ * would duplicate every header).
+ */
+export interface TxcDelta {
+    _txc: {
+        web: {
+            res: TxcWebRes;
+        };
+        halt: true;
+    };
+}
+/** What a server entry gets beside the Request. Deliberately minimal. */
+export interface TxcContext {
+    readonly client: {
+        readonly ip: string;
+    };
+}
+/** The server/ entry's default export. */
+export interface FetchHandler {
+    fetch(request: Request, ctx: TxcContext): Response | Promise<Response>;
+}

package/dist/envelope.js

@@ -0,0 +1,3 @@
+// The chassis's side of the contract: the request envelope a runner hands
+// the bridge, and the delta the bridge answers with.
+export {};

package/dist/harness.d.ts

@@ -0,0 +1,32 @@
+import { type Server } from "node:http";
+import type { FetchHandler, TxcEnvelope } from "./envelope.js";
+/** Imports a build's server entry and checks its default export. */
+export declare function loadServer(abiDir: string): Promise<FetchHandler>;
+/** Builds an envelope the way the chassis's web head does, for a request. */
+export declare function envelopeFor(method: string, path: string, init?: {
+    headers?: Record<string, string[]>;
+    body?: Uint8Array;
+    host?: string;
+    ip?: string;
+}): TxcEnvelope;
+export interface CheckResult {
+    name: string;
+    ok: boolean;
+    detail?: string;
+}
+/**
+ * Drives a server entry with the requests every handler must answer, through
+ * the bridge, and checks each answer is a valid delta: a status in
+ * 100–599, headers as arrays, no echo of the request envelope, a body only
+ * where one is allowed.
+ */
+export declare function checkServer(abiDir: string): Promise<CheckResult[]>;
+/**
+ * Serves a build locally: public/ files first (as the chassis's static
+ * serving answers first), everything else through the bridge to server/.
+ * For local development; not a chassis.
+ */
+export declare function serve(abiDir: string, opts?: {
+    port?: number;
+    host?: string;
+}): Promise<Server>;

package/dist/harness.js

@@ -0,0 +1,144 @@
+// The harness: load a build's server/ entry and check it honours the
+// contract, before any runner exists; and serve a build locally behind the
+// same bridge a runner will use.
+import { createServer } from "node:http";
+import { readFile, stat } from "node:fs/promises";
+import { extname, join, normalize, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { dispatch } from "./bridge.js";
+import { readManifest } from "./manifest.js";
+/** Imports a build's server entry and checks its default export. */
+export async function loadServer(abiDir) {
+    const m = await readManifest(abiDir);
+    if (!m.server)
+        throw new Error("the manifest names no server.entry: this is a static build");
+    const mod = await import(pathToFileURL(join(abiDir, m.server.entry)).href);
+    const h = mod.default;
+    if (!h || typeof h.fetch !== "function") {
+        throw new Error(`${m.server.entry}: the default export must be { fetch(request, ctx) }`);
+    }
+    return h;
+}
+/** Builds an envelope the way the chassis's web head does, for a request. */
+export function envelopeFor(method, path, init = {}) {
+    const host = init.host ?? "localhost";
+    const q = path.indexOf("?");
+    return {
+        _txc: {
+            client: { ip: init.ip ?? "127.0.0.1" },
+            web: {
+                req: {
+                    method,
+                    host,
+                    url: { full: `http://${host}${path}`, path: q < 0 ? path : path.slice(0, q), query: { raw: q < 0 ? "" : path.slice(q + 1) } },
+                    headers: init.headers ?? {},
+                    body: init.body && init.body.byteLength > 0 ? Buffer.from(init.body).toString("base64") : undefined,
+                },
+            },
+        },
+    };
+}
+/**
+ * Drives a server entry with the requests every handler must answer, through
+ * the bridge, and checks each answer is a valid delta: a status in
+ * 100–599, headers as arrays, no echo of the request envelope, a body only
+ * where one is allowed.
+ */
+export async function checkServer(abiDir) {
+    const results = [];
+    let handler;
+    try {
+        handler = await loadServer(abiDir);
+        results.push({ name: "load", ok: true });
+    }
+    catch (e) {
+        return [{ name: "load", ok: false, detail: e.message }];
+    }
+    const probes = [
+        ["GET /", envelopeFor("GET", "/", { headers: { accept: ["text/html"] } }), "GET"],
+        ["GET unknown page", envelopeFor("GET", "/txco-web-abi-check-unknown", { headers: { accept: ["text/html"] } }), "GET"],
+        ["POST unknown", envelopeFor("POST", "/txco-web-abi-check-unknown", { headers: { "content-type": ["application/json"] }, body: new TextEncoder().encode("{}") }), "POST"],
+        ["HEAD /", envelopeFor("HEAD", "/"), "HEAD"],
+    ];
+    for (const [name, env, method] of probes) {
+        const delta = await dispatch(handler, env);
+        const res = delta?._txc?.web?.res;
+        const problems = [];
+        if (!res || !Number.isInteger(res.status) || res.status < 100 || res.status > 599)
+            problems.push("no valid status");
+        if (res && Object.values(res.headers).some((v) => !Array.isArray(v)))
+            problems.push("headers must be arrays");
+        if (delta._txc.web.req !== undefined)
+            problems.push("the answer echoes the request");
+        if (method === "HEAD" && res?.body)
+            problems.push("a HEAD answer carries a body");
+        if (res?.status === 500 && (method === "HEAD" || (res.body && Buffer.from(res.body, "base64").toString() === "internal error\n"))) {
+            problems.push("the handler threw or returned no Response (a 500 from the bridge)");
+        }
+        try {
+            JSON.stringify(delta);
+        }
+        catch {
+            problems.push("the delta isn't serialisable");
+        }
+        results.push({ name, ok: problems.length === 0, detail: problems.join("; ") || `→ ${res?.status}` });
+    }
+    return results;
+}
+const TYPES = {
+    ".html": "text/html; charset=utf-8", ".css": "text/css", ".js": "text/javascript", ".mjs": "text/javascript",
+    ".json": "application/json", ".svg": "image/svg+xml", ".png": "image/png", ".jpg": "image/jpeg",
+    ".webp": "image/webp", ".ico": "image/x-icon", ".txt": "text/plain; charset=utf-8", ".woff2": "font/woff2",
+};
+async function readBody(req) {
+    const chunks = [];
+    for await (const c of req)
+        chunks.push(c);
+    return Buffer.concat(chunks);
+}
+/**
+ * Serves a build locally: public/ files first (as the chassis's static
+ * serving answers first), everything else through the bridge to server/.
+ * For local development; not a chassis.
+ */
+export async function serve(abiDir, opts = {}) {
+    const handler = await loadServer(abiDir);
+    const pub = join(abiDir, "public");
+    const server = createServer(async (req, res) => {
+        const method = (req.method ?? "GET").toUpperCase();
+        const path = new URL(req.url ?? "/", "http://localhost").pathname;
+        if (method === "GET" || method === "HEAD") {
+            const segs = path.split("/").filter(Boolean);
+            if (!segs.some((s) => s.startsWith("."))) {
+                const file = normalize(join(pub, ...segs, path.endsWith("/") ? "index.html" : ""));
+                if (file.startsWith(pub + sep) || file === pub) {
+                    try {
+                        if ((await stat(file)).isFile()) {
+                            const bytes = await readFile(file);
+                            res.writeHead(200, { "content-type": TYPES[extname(file)] ?? "application/octet-stream" });
+                            res.end(method === "HEAD" ? undefined : bytes);
+                            return;
+                        }
+                    }
+                    catch {
+                        // not a file: the server answers
+                    }
+                }
+            }
+        }
+        const headers = {};
+        for (let i = 0; i < req.rawHeaders.length; i += 2) {
+            (headers[req.rawHeaders[i].toLowerCase()] ??= []).push(req.rawHeaders[i + 1]);
+        }
+        const delta = await dispatch(handler, envelopeFor(method, req.url ?? "/", {
+            headers, body: await readBody(req), host: req.headers.host, ip: req.socket.remoteAddress ?? "",
+        }));
+        const out = delta._txc.web.res;
+        for (const [name, values] of Object.entries(out.headers))
+            res.setHeader(name, values);
+        res.writeHead(out.status);
+        res.end(out.body ? Buffer.from(out.body, "base64") : undefined);
+    });
+    await new Promise((resolve) => server.listen(opts.port ?? 0, opts.host ?? "127.0.0.1", resolve));
+    return server;
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./manifest.js";
+export * from "./envelope.js";
+export * from "./bridge.js";
+export * from "./harness.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./manifest.js";
+export * from "./envelope.js";
+export * from "./bridge.js";
+export * from "./harness.js";

package/dist/manifest.d.ts

@@ -0,0 +1,36 @@
+/** The manifest's file name at the root of an ABI directory. */
+export declare const MANIFEST_NAME = "txco-web.json";
+/** The manifest's abi value this kit reads. */
+export declare const ABI_VERSION = 1;
+/** Producers' ops live in the band starting here, after every author op. */
+export declare const PRODUCER_SCOPE = 900000;
+export interface Manifest {
+    abi: 1;
+    server?: {
+        entry: string;
+    };
+    immutable?: string[];
+    [extension: `x-${string}`]: unknown;
+}
+export interface Problem {
+    /** A JSON pointer into the manifest ("" is the root). */
+    pointer: string;
+    message: string;
+}
+export type ValidationResult = {
+    ok: true;
+    manifest: Manifest;
+} | {
+    ok: false;
+    errors: Problem[];
+};
+/** Validates a parsed manifest. */
+export declare function validateManifest(doc: unknown): ValidationResult;
+/** Reads and validates <dir>/txco-web.json. Throws on an unreadable or invalid manifest. */
+export declare function readManifest(dir: string): Promise<Manifest>;
+/**
+ * The private root of a public/ path: cut at the end of its first "_"
+ * segment ("" when it has none). The installer writes one public marker per
+ * root, so `_app/x.js` → `_app`, `assets/_Dk3.js` → itself.
+ */
+export declare function publicRoot(rel: string): string;