@mesofact/runtime 0.8.29

package/dist/validate.js

@@ -0,0 +1,333 @@
+// Manifest validator — structural shape + semantic rules. Used by the build
+// (fail before bad HTML hits R2) and mirrored in `crates/mesofact/src/validate.rs`
+// for the proxy. Shared fixtures live at `tests/fixtures/manifests/`.
+//
+// Semantic rules:
+//   R1. Mode 1 (static) + `source_reads` referencing a non-`global` source
+//       is rejected. Mode 1 builds can't enumerate per-user/per-project keys.
+//   R2. Mode 1 + `requires` containing "user" is rejected. The build can't
+//       know who the user is.
+//
+// See `.yah/docs/architecture/mesofact.md` §"Render axis × source axis".
+import { MANIFEST_VERSION } from "./manifest.js";
+import { HOOK_NAMES, isHookName } from "./hooks.js";
+const MODES = new Set(["static", "ssr", "spa"]);
+const REQUIRES = new Set(["user", "project", "region"]);
+const RESOLVED_PLACEMENTS = new Set(["host", "edge"]);
+function isObject(x) {
+    return typeof x === "object" && x !== null && !Array.isArray(x);
+}
+function shape(path, message) {
+    return { kind: "shape", path, message };
+}
+function checkRoute(idx, raw, errs) {
+    const base = `routes[${idx}]`;
+    if (!isObject(raw)) {
+        errs.push(shape(base, "expected object"));
+        return null;
+    }
+    const out = {};
+    if (typeof raw.route !== "string")
+        errs.push(shape(`${base}.route`, "expected string"));
+    else
+        out.route = raw.route;
+    if (typeof raw.mode !== "string" || !MODES.has(raw.mode)) {
+        errs.push(shape(`${base}.mode`, "expected 'static' | 'ssr' | 'spa'"));
+    }
+    else {
+        out.mode = raw.mode;
+    }
+    if (typeof raw.render_entrypoint !== "string") {
+        errs.push(shape(`${base}.render_entrypoint`, "expected string"));
+    }
+    else {
+        out.render_entrypoint = raw.render_entrypoint;
+    }
+    if (raw.requires !== undefined) {
+        if (!Array.isArray(raw.requires) || raw.requires.some((r) => typeof r !== "string" || !REQUIRES.has(r))) {
+            errs.push(shape(`${base}.requires`, "expected ('user' | 'project' | 'region')[]"));
+        }
+        else {
+            out.requires = raw.requires;
+        }
+    }
+    if (raw.source_reads !== undefined) {
+        if (!Array.isArray(raw.source_reads) || raw.source_reads.some((s) => typeof s !== "string")) {
+            errs.push(shape(`${base}.source_reads`, "expected string[]"));
+        }
+        else {
+            out.source_reads = raw.source_reads;
+        }
+    }
+    if (raw.data_inputs !== undefined) {
+        if (!Array.isArray(raw.data_inputs) || raw.data_inputs.some((s) => typeof s !== "string")) {
+            errs.push(shape(`${base}.data_inputs`, "expected string[]"));
+        }
+        else {
+            out.data_inputs = raw.data_inputs;
+        }
+    }
+    if (!isObject(raw.cache_policy) || typeof raw.cache_policy.ttl !== "number") {
+        errs.push(shape(`${base}.cache_policy`, "expected { ttl: number, ... }"));
+    }
+    else {
+        out.cache_policy = raw.cache_policy;
+    }
+    if (raw.concurrency !== undefined) {
+        if (typeof raw.concurrency !== "number") {
+            errs.push(shape(`${base}.concurrency`, "expected number"));
+        }
+        else {
+            out.concurrency = raw.concurrency;
+        }
+    }
+    if (raw.hydration !== undefined) {
+        const h = raw.hydration;
+        if (!isObject(h) || typeof h.script !== "string" || !Array.isArray(h.code_split)) {
+            errs.push(shape(`${base}.hydration`, "expected { script: string, code_split: string[] }"));
+        }
+        else {
+            out.hydration = h;
+        }
+    }
+    if (raw.prerender !== undefined) {
+        if (!isObject(raw.prerender)) {
+            errs.push(shape(`${base}.prerender`, "expected object"));
+        }
+        else {
+            out.prerender = raw.prerender;
+        }
+    }
+    if (raw.placement !== undefined) {
+        if (typeof raw.placement !== "string" || !RESOLVED_PLACEMENTS.has(raw.placement)) {
+            // The build resolves `"auto"` to a concrete value before emission, so
+            // the manifest only ever carries `"host"` or `"edge"`.
+            errs.push(shape(`${base}.placement`, "expected 'host' | 'edge'"));
+        }
+        else if (out.mode !== undefined && out.mode !== "ssr") {
+            errs.push(shape(`${base}.placement`, "placement is only valid on mode:'ssr'"));
+        }
+        else {
+            out.placement = raw.placement;
+        }
+    }
+    if (raw.resilience !== undefined) {
+        const res = checkResilience(base, raw.resilience, out.mode, errs);
+        if (res)
+            out.resilience = res;
+    }
+    if (errs.length && errs.some((e) => e.path.startsWith(base)))
+        return null;
+    return out;
+}
+const RETRY_ON_VALUES = new Set(["connection", "5xx", "any"]);
+// Structural check for the W181 resilience block as carried in the manifest.
+// `defineRoutes` already enforced the semantic rules (ssr-only, queue
+// reserved, backoff length); this pass keeps a hand-written manifest honest
+// and — like data_inputs before it (R014) — prevents the field from being
+// silently stripped when the validator rebuilds the route object.
+function checkResilience(base, raw, mode, errs) {
+    const path = `${base}.resilience`;
+    if (!isObject(raw)) {
+        errs.push(shape(path, "expected object"));
+        return null;
+    }
+    if (mode !== undefined && mode !== "ssr") {
+        errs.push(shape(path, "resilience is only valid on mode:'ssr'"));
+        return null;
+    }
+    if (raw.queue !== undefined) {
+        errs.push(shape(`${path}.queue`, "queue policy is reserved for v2 (W181) and must not be emitted"));
+        return null;
+    }
+    if (raw.timeout_ms !== undefined && typeof raw.timeout_ms !== "number") {
+        errs.push(shape(`${path}.timeout_ms`, "expected number"));
+        return null;
+    }
+    if (raw.retry !== undefined) {
+        const retry = raw.retry;
+        if (!isObject(retry) ||
+            typeof retry.attempts !== "number" ||
+            !Array.isArray(retry.backoff_ms) ||
+            retry.backoff_ms.some((b) => typeof b !== "number") ||
+            retry.backoff_ms.length !== retry.attempts - 1) {
+            errs.push(shape(`${path}.retry`, "expected { attempts: number, backoff_ms: number[attempts - 1], ... }"));
+            return null;
+        }
+        if (retry.retry_on !== undefined && (typeof retry.retry_on !== "string" || !RETRY_ON_VALUES.has(retry.retry_on))) {
+            errs.push(shape(`${path}.retry.retry_on`, "expected 'connection' | '5xx' | 'any'"));
+            return null;
+        }
+        if (retry.budget_ms !== undefined && typeof retry.budget_ms !== "number") {
+            errs.push(shape(`${path}.retry.budget_ms`, "expected number"));
+            return null;
+        }
+    }
+    return raw;
+}
+function checkStaticAsset(idx, raw, errs) {
+    const base = `static_assets[${idx}]`;
+    if (!isObject(raw)) {
+        errs.push(shape(base, "expected object"));
+        return null;
+    }
+    if (typeof raw.key !== "string" ||
+        typeof raw.content_hash !== "string" ||
+        typeof raw.content_type !== "string" ||
+        typeof raw.immutable !== "boolean") {
+        errs.push(shape(base, "expected { key, content_hash, content_type, immutable }"));
+        return null;
+    }
+    return {
+        key: raw.key,
+        content_hash: raw.content_hash,
+        content_type: raw.content_type,
+        immutable: raw.immutable,
+    };
+}
+function checkErrorRoutes(raw, errs) {
+    if (raw === undefined)
+        return undefined;
+    if (!isObject(raw)) {
+        errs.push(shape("error_routes", "expected object"));
+        return undefined;
+    }
+    const out = {};
+    if (raw["404"] !== undefined) {
+        if (typeof raw["404"] !== "string")
+            errs.push(shape("error_routes.404", "expected string"));
+        else
+            out["404"] = raw["404"];
+    }
+    if (raw["5xx"] !== undefined) {
+        if (typeof raw["5xx"] !== "string")
+            errs.push(shape("error_routes.5xx", "expected string"));
+        else
+            out["5xx"] = raw["5xx"];
+    }
+    return out;
+}
+// Mode 2 hooks (R756-F6). The name set is closed — only the engine invokes a
+// hook, so an unrecognised name in a manifest is a build that emitted
+// something nothing will ever call, not a forward-compatible extension.
+function checkHooks(raw, errs) {
+    if (raw === undefined)
+        return undefined;
+    if (!isObject(raw)) {
+        errs.push(shape("hooks", "expected object"));
+        return undefined;
+    }
+    const out = {};
+    for (const [name, value] of Object.entries(raw)) {
+        if (!isHookName(name)) {
+            errs.push({
+                kind: "unknown_hook",
+                path: `hooks.${name}`,
+                message: `unknown hook '${name}' (known: ${HOOK_NAMES.join(", ")})`,
+            });
+            continue;
+        }
+        if (!isObject(value) || typeof value.entrypoint !== "string") {
+            errs.push(shape(`hooks.${name}`, "expected { entrypoint: string }"));
+            continue;
+        }
+        out[name] = { entrypoint: value.entrypoint };
+    }
+    return out;
+}
+function checkRules(manifest, catalog, errs) {
+    manifest.routes.forEach((route, idx) => {
+        if (route.mode !== "static")
+            return;
+        if (route.source_reads) {
+            for (const name of route.source_reads) {
+                const entry = catalog[name];
+                if (!entry) {
+                    errs.push({
+                        kind: "shape",
+                        path: `routes[${idx}].source_reads`,
+                        message: `route ${route.route}: source '${name}' not declared in catalog`,
+                    });
+                    continue;
+                }
+                if (entry.scope !== "global") {
+                    errs.push({
+                        kind: "mode1_scoped_source",
+                        path: `routes[${idx}].source_reads`,
+                        message: `route ${route.route}: Mode 1 cannot read from non-'global' source '${name}' (scope='${entry.scope}')`,
+                    });
+                }
+            }
+        }
+        if (route.requires?.includes("user")) {
+            errs.push({
+                kind: "mode1_requires_user",
+                path: `routes[${idx}].requires`,
+                message: `route ${route.route}: Mode 1 cannot require 'user' (the build can't enumerate users)`,
+            });
+        }
+    });
+}
+export function validate(input, catalog = {}) {
+    const errs = [];
+    if (!isObject(input)) {
+        return { ok: false, errors: [shape("$", "expected object")] };
+    }
+    if (input.version !== MANIFEST_VERSION) {
+        errs.push({
+            kind: "unsupported_version",
+            path: "version",
+            message: `unsupported manifest version '${String(input.version)}' (expected '${MANIFEST_VERSION}')`,
+        });
+    }
+    if (typeof input.build_id !== "string")
+        errs.push(shape("build_id", "expected string"));
+    if (!Array.isArray(input.routes)) {
+        errs.push(shape("routes", "expected array"));
+        return { ok: false, errors: errs };
+    }
+    const routes = [];
+    input.routes.forEach((r, i) => {
+        const route = checkRoute(i, r, errs);
+        if (route)
+            routes.push(route);
+    });
+    const staticAssetsRaw = input.static_assets ?? [];
+    if (!Array.isArray(staticAssetsRaw)) {
+        errs.push(shape("static_assets", "expected array"));
+        return { ok: false, errors: errs };
+    }
+    const staticAssets = [];
+    staticAssetsRaw.forEach((a, i) => {
+        const asset = checkStaticAsset(i, a, errs);
+        if (asset)
+            staticAssets.push(asset);
+    });
+    const errorRoutes = checkErrorRoutes(input.error_routes, errs);
+    let ssrPrefixes;
+    if (input.ssr_prefixes !== undefined) {
+        if (!Array.isArray(input.ssr_prefixes) || input.ssr_prefixes.some((s) => typeof s !== "string")) {
+            errs.push(shape("ssr_prefixes", "expected string[]"));
+        }
+        else {
+            ssrPrefixes = input.ssr_prefixes;
+        }
+    }
+    const hooks = checkHooks(input.hooks, errs);
+    if (errs.length)
+        return { ok: false, errors: errs };
+    const manifest = {
+        version: input.version,
+        build_id: input.build_id,
+        routes,
+        static_assets: staticAssets,
+        ...(errorRoutes ? { error_routes: errorRoutes } : {}),
+        ...(ssrPrefixes !== undefined ? { ssr_prefixes: ssrPrefixes } : {}),
+        ...(hooks !== undefined ? { hooks } : {}),
+    };
+    checkRules(manifest, catalog, errs);
+    if (errs.length)
+        return { ok: false, errors: errs };
+    return { ok: true, manifest };
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@mesofact/runtime",
+  "version": "0.8.29",
+  "description": "Render contract types and adapter API for mesofact (RenderRequest, RenderResult, Source, error taxonomy)",
+  "license": "MIT OR Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./hydration": {
+      "types": "./dist/hydration.d.ts",
+      "import": "./dist/hydration.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.8.3"
+  },
+  "dependencies": {
+    "aws4fetch": "^1.0.20",
+    "smol-toml": "^1.6.1"
+  }
+}

package/src/adapters/r2.ts

@@ -0,0 +1,163 @@
+// `r2` adapter — read-only BlobSource over Cloudflare R2 (or any S3-compatible
+// endpoint). Signs requests with SigV4 via `aws4fetch`, emits `r2:<bucket>:<key>`
+// tags into the ambient trackCtx, honors per-call `.noTrack()` / `.timeout(ms)`.
+//
+// See `.yah/docs/architecture/mesofact.md` §"Adapter API surface" + §"Adapter
+// read-set provenance".
+
+import { AwsClient } from "aws4fetch";
+import { BaseSource, type BlobSource, type ListOpts, type R2Object } from "../source.js";
+import { SourceQueryError, SourceTimeoutError, SourceUnavailableError } from "../errors.js";
+
+const DEFAULT_TIMEOUT_MS = 2000;
+
+export type R2Config = {
+  // Logical source name from `mesofact.config.toml` (e.g. "assets"). Used as
+  // the registry key and surfaced in errors.
+  name: string;
+  // R2 bucket — also the `r2:<bucket>:...` tag prefix, per the design's tag
+  // taxonomy.
+  bucket: string;
+  // Endpoint root. For Cloudflare R2 this is
+  // `https://<account_id>.r2.cloudflarestorage.com`. No trailing slash.
+  endpoint: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  // Test seam — swap `fetch` to inject a stub. Defaults to `globalThis.fetch`,
+  // which aws4fetch already uses internally; passing a custom fn lets tests
+  // observe the signed request without hitting the network.
+  httpFetch?: typeof fetch;
+};
+
+export class R2Adapter extends BaseSource implements BlobSource {
+  readonly bucket: string;
+  private readonly client: AwsClient;
+  private readonly endpoint: string;
+  private readonly httpFetch: typeof fetch;
+
+  constructor(config: R2Config) {
+    super(config.name);
+    this.bucket = config.bucket;
+    this.endpoint = config.endpoint.replace(/\/$/, "");
+    this.client = new AwsClient({
+      accessKeyId: config.accessKeyId,
+      secretAccessKey: config.secretAccessKey,
+      service: "s3",
+      region: "auto",
+    });
+    // aws4fetch always uses globalThis.fetch internally; we sign manually and
+    // dispatch through `httpFetch` so tests can swap it without touching the
+    // global. Calling `globalThis.fetch.bind(globalThis)` preserves the
+    // expected receiver for fetch implementations that check it.
+    this.httpFetch = config.httpFetch ?? globalThis.fetch.bind(globalThis);
+  }
+
+  async fetch(key: string): Promise<Uint8Array | null> {
+    const { track, timeout_ms } = this.consumeOverrides(DEFAULT_TIMEOUT_MS);
+    this.emitTag(`r2:${this.bucket}:${key}`, track);
+    const url = `${this.endpoint}/${this.bucket}/${encodeKey(key)}`;
+    const res = await this.send(url, { method: "GET" }, timeout_ms);
+    if (res.status === 404) return null;
+    if (!res.ok) {
+      throw new SourceQueryError(this.name, `r2 GET ${key} → HTTP ${res.status}`);
+    }
+    const buf = await res.arrayBuffer();
+    return new Uint8Array(buf);
+  }
+
+  async list(prefix: string, opts: ListOpts = {}): Promise<R2Object[]> {
+    const { track, timeout_ms } = this.consumeOverrides(DEFAULT_TIMEOUT_MS);
+    this.emitTag(`r2:${this.bucket}:${prefix}*`, track);
+    const params = new URLSearchParams({ "list-type": "2", prefix });
+    if (opts.limit !== undefined) params.set("max-keys", String(opts.limit));
+    if (opts.cursor) params.set("continuation-token", opts.cursor);
+    if (opts.delimiter) params.set("delimiter", opts.delimiter);
+    const url = `${this.endpoint}/${this.bucket}?${params.toString()}`;
+    const res = await this.send(url, { method: "GET" }, timeout_ms);
+    if (!res.ok) {
+      throw new SourceQueryError(this.name, `r2 LIST ${prefix} → HTTP ${res.status}`);
+    }
+    return parseListV2(await res.text());
+  }
+
+  private async send(url: string, init: RequestInit, timeout_ms: number): Promise<Response> {
+    const signed = await this.client.sign(url, init);
+    return this.race(() => this.httpFetch(signed), timeout_ms);
+  }
+
+  private async race(call: () => Promise<Response>, timeout_ms: number): Promise<Response> {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      return await Promise.race<Response>([
+        call().catch((err) => {
+          throw new SourceUnavailableError(this.name, { cause: err });
+        }),
+        new Promise<Response>((_, reject) => {
+          timer = setTimeout(() => reject(new SourceTimeoutError(this.name, timeout_ms)), timeout_ms);
+        }),
+      ]);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+}
+
+// `encodeURIComponent` re-encodes `/`, which we want to preserve so S3 sees
+// path-style keys correctly. Other reserved chars stay percent-encoded.
+function encodeKey(key: string): string {
+  return key
+    .split("/")
+    .map((segment) => encodeURIComponent(segment))
+    .join("/");
+}
+
+// Minimal ListBucketResult v2 parser. S3's XML is a fixed shape; a regex over
+// the `<Contents>` blocks is faster and dep-free than pulling in a full XML
+// parser, and the only fields the contract exposes are key/size/last_modified/
+// etag (per `R2Object`).
+function parseListV2(xml: string): R2Object[] {
+  const out: R2Object[] = [];
+  for (const match of xml.matchAll(/<Contents>([\s\S]*?)<\/Contents>/g)) {
+    const inner = match[1]!;
+    const key = pick(inner, "Key");
+    const sizeStr = pick(inner, "Size");
+    const last_modified = pick(inner, "LastModified");
+    const etagRaw = pick(inner, "ETag");
+    if (key === undefined || sizeStr === undefined || last_modified === undefined) continue;
+    out.push({
+      key,
+      size: Number.parseInt(sizeStr, 10),
+      last_modified,
+      ...(etagRaw ? { etag: etagRaw.replace(/^"|"$/g, "") } : {}),
+    });
+  }
+  return out;
+}
+
+function pick(haystack: string, tag: string): string | undefined {
+  const m = haystack.match(new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`));
+  return m?.[1];
+}
+
+// Per-process registry. Configuration in T4 loads `mesofact.config.toml` and
+// calls `registerR2()` for each `[sources.*]` of `kind = "r2"`. Render code
+// looks up by name via `r2(name)`.
+const registry = new Map<string, R2Adapter>();
+
+export function registerR2(adapter: R2Adapter): void {
+  registry.set(adapter.name, adapter);
+}
+
+export function clearR2Registry(): void {
+  registry.clear();
+}
+
+export function r2(name: string): BlobSource {
+  const adapter = registry.get(name);
+  if (!adapter) {
+    throw new Error(
+      `r2 source not registered: ${name} (declare it in mesofact.config.toml under [sources.${name}])`,
+    );
+  }
+  return adapter;
+}