@dcasegr/skein 0.0.0-stage → 0.1.2

package/dist/host/liveness.js

@@ -0,0 +1,155 @@
+// The liveness tool (#138): a runtime handler keyed by event name, like the
+// deadline, fetch and beacon handlers (#126). An app's installed program
+// declares, once per topic,
+//
+//   liveness   {event: "liveness", topic, window: <ms, a second to a day>}
+//   unliveness {event: "unliveness", topic}
+//
+// and the kernel records it on the step's update (kernel-zig/src/
+// subscriptions.zig livenessProblem / livenessFold). Here, for each liveness
+// topic the apps keep (folded from the log, livenessOf, then followed live):
+//
+//   - the instance's own libp2p node subscribes the topic WITHOUT admitting
+//     its messages: no front-door call, no entry, nothing logged (P2PHost:
+//     a topic only liveness takes is judged here alone);
+//   - each message is a beacon beat (p2p.ts beaconFrame: {body, at, sender,
+//     signature}); its instance signature is checked (beaconBeat) and a beat
+//     that does not verify is dropped (and rejected to GossipSub);
+//   - the beats newer than the window are kept, the latest per sender
+//     (identity key), with the peer that published it (`from`); the node's
+//     OWN beats on the topic are written into the same set (gossip does not
+//     echo them: P2PHost.beacons);
+//   - in memory only: empty after a restart until the next beats; dropped at
+//     the app's unliveness or uninstall.
+//
+// The set is served to the app's page by the host itself, no program in
+// between (Router: GET /<app>/.live/<topic> on the instance's origin).
+// A runtime without this tool records the events and nothing happens.
+import { beaconBeat, emittedEvents, isTopic } from "./p2p.js";
+/** A window's bounds (ms): a second, a day (subscriptions.zig LIVENESS_MIN_MS / _MAX_MS). */
+export const LIVENESS_MIN_MS = 1000;
+export const LIVENESS_MAX_MS = 86_400_000;
+/** A `liveness` / `unliveness` event record, read (subscriptions.zig livenessEventOf); or why it is not one this host follows. */
+export function livenessEvent(rec) {
+    const event = rec.event;
+    if (rec.kind !== "event" || (event !== "liveness" && event !== "unliveness"))
+        return { refused: "not a liveness or unliveness event" };
+    if (typeof rec.app !== "string" || !rec.app)
+        return { refused: "it names no app (its program record is not installed): ignored" };
+    if (!isTopic(rec.topic))
+        return { refused: `${JSON.stringify(rec.topic)} is not a topic` };
+    if (event === "unliveness")
+        return { event, app: rec.app, topic: rec.topic };
+    const window = typeof rec.window === "number" ? rec.window : typeof rec.window === "bigint" ? Number(rec.window) : NaN;
+    if (!Number.isInteger(window) || window < LIVENESS_MIN_MS || window > LIVENESS_MAX_MS)
+        return { refused: "a liveness window is from a second to a day (`window`, ms)" };
+    return { event, live: { app: rec.app, topic: rec.topic, window } };
+}
+/** Fold liveness events in order: a liveness replaces the app's own on the topic, an unliveness removes it. */
+export function foldLiveness(events, into = []) {
+    for (const e of events) {
+        const [app, topic] = e.event === "liveness" ? [e.live.app, e.live.topic] : [e.app, e.topic];
+        const i = into.findIndex((l) => l.app === app && l.topic === topic);
+        if (e.event === "liveness") {
+            if (i >= 0)
+                into[i] = e.live;
+            else
+                into.push(e.live);
+        }
+        else if (i >= 0)
+            into.splice(i, 1);
+    }
+    return into;
+}
+/** The liveness standing, folded from the store's log as the subscriptions and beacons are (p2p.ts subscriptionsOf). Read only. */
+export async function livenessOf(store) {
+    return foldLiveness(await emittedEvents(store, (rec) => { const e = livenessEvent(rec); return "refused" in e ? undefined : e; }));
+}
+/** The tool's state: per instance, the apps' liveness and the beats kept per topic (in memory). */
+export class Liveness {
+    lives = new Map();
+    /** handle → topic → sender → the latest beat. */
+    beats = new Map();
+    now;
+    /** Told each beat newly kept (shruggr/skein#150: the overlay's sync reads a peer's tip anchor from it). */
+    kept;
+    constructor(now = Date.now) { this.now = now; }
+    /** `handle`'s apps keep this liveness now: the beats of topics none keeps any more are dropped. */
+    set(handle, lives) {
+        if (!lives.length) {
+            this.drop(handle);
+            return;
+        }
+        this.lives.set(handle, lives.map((l) => ({ ...l })));
+        const kept = this.beats.get(handle);
+        if (kept)
+            for (const t of kept.keys())
+                if (!lives.some((l) => l.topic === t))
+                    kept.delete(t);
+    }
+    /** The topics `handle`'s apps keep liveness for (each once). */
+    topics(handle) { return [...new Set((this.lives.get(handle) ?? []).map((l) => l.topic))]; }
+    /** Whether an app of `handle` keeps liveness for `topic`. */
+    takes(handle, topic) { return (this.lives.get(handle) ?? []).some((l) => l.topic === topic); }
+    /** The longest window on `topic` among `handle`'s apps (ms), or undefined. */
+    windowOf(handle, topic) {
+        const ws = (this.lives.get(handle) ?? []).filter((l) => l.topic === topic).map((l) => l.window);
+        return ws.length ? Math.max(...ws) : undefined;
+    }
+    /**
+     * A message on `topic` at `handle`'s node, published by peer `from`: kept when it is a beat whose
+     * instance signature verifies (beaconBeat) and is newer than the longest window on the topic — the
+     * sender's latest replaces an older one. Nothing logged.
+     */
+    observe(handle, topic, frame, from) {
+        const window = this.windowOf(handle, topic);
+        if (window === undefined)
+            return "ignore";
+        const b = beaconBeat(topic, frame);
+        if ("problem" in b)
+            return "reject";
+        const now = this.now();
+        // A beat older than the window is not live; one dated more than a window ahead of this clock is not believed.
+        if (now - b.at >= window || b.at - now > window)
+            return "ignore";
+        let byTopic = this.beats.get(handle);
+        if (!byTopic)
+            this.beats.set(handle, byTopic = new Map());
+        let bySender = byTopic.get(topic);
+        if (!bySender)
+            byTopic.set(topic, bySender = new Map());
+        const sender = Buffer.from(b.sender).toString("hex");
+        const was = bySender.get(sender);
+        if (!was || b.at > was.at) {
+            const beat = { sender, at: b.at, body: b.body, from };
+            bySender.set(sender, beat);
+            this.kept?.(handle, topic, beat);
+        }
+        // The stale ones go as the set is touched.
+        for (const [k, x] of bySender)
+            if (now - x.at >= window)
+                bySender.delete(k);
+        return "accept";
+    }
+    /** The beats live for `app`'s liveness on `topic` (newer than its window), newest first; undefined: the app keeps no liveness for the topic. */
+    read(handle, app, topic) {
+        const l = (this.lives.get(handle) ?? []).find((x) => x.app === app && x.topic === topic);
+        if (!l)
+            return undefined;
+        const now = this.now();
+        return [...(this.beats.get(handle)?.get(topic)?.values() ?? [])].filter((b) => now - b.at < l.window).sort((x, y) => y.at - x.at);
+    }
+    /** Every beat live on `topic` at `handle` (newer than the longest window on it), whichever app keeps it. */
+    live(handle, topic) {
+        const window = this.windowOf(handle, topic);
+        if (window === undefined)
+            return [];
+        const now = this.now();
+        return [...(this.beats.get(handle)?.get(topic)?.values() ?? [])].filter((b) => now - b.at < window);
+    }
+    /** Forget `handle`: its liveness and its beats. */
+    drop(handle) {
+        this.lives.delete(handle);
+        this.beats.delete(handle);
+    }
+}

package/dist/host/manifest.d.ts

@@ -0,0 +1,160 @@
+export type RouteTransport = "mailbox" | "event" | "http" | "libp2p";
+/** A route as the manifest writes it (#143). */
+export interface RouteIn {
+    transport?: RouteTransport;
+    address: string;
+    prefix?: true;
+    filters?: string[];
+    handler?: string;
+    [setting: string]: unknown;
+}
+export interface FunctionDecl {
+    writes: boolean;
+    args?: unknown;
+    answer?: unknown;
+}
+export interface Provide {
+    interface: string;
+    functions: Record<string, FunctionDecl>;
+}
+export interface Manifest {
+    kind: "app";
+    name: string;
+    version: string;
+    programs: Record<string, string | Record<string, unknown>>;
+    routes?: RouteIn[];
+    filters?: Record<string, string>;
+    roles?: Record<string, string[]>;
+    config?: Record<string, unknown>;
+    provides?: Provide[];
+    requires?: string[];
+    start?: {
+        body: Record<string, unknown>;
+    };
+    stop?: {
+        body: Record<string, unknown>;
+    };
+    description?: string;
+}
+/** A shell program's support for one command (#25, #83): files mounted read-only at `mount` for that command only, env defaults. */
+export interface ShellSupport {
+    mount: string;
+    files: Record<string, string>;
+    env: Record<string, string>;
+}
+/** A shell program as the manifest names it (#83): its modules and support files, paths in the tree. */
+export interface ShellSource {
+    kind: "shell";
+    modules: Record<string, string>;
+    support: Record<string, ShellSupport>;
+    description?: string;
+}
+/** Where a role's program comes from. */
+export type ProgramSource = {
+    kind: "wasm" | "cid";
+    path: string;
+    name: string;
+} | {
+    kind: "instance";
+    name: string;
+} | ShellSource;
+/** A route normalised: transport set; the address, filters and handler as written. */
+export type Route = RouteIn & {
+    transport: RouteTransport;
+};
+/** A manifest checked: the fields as installed. */
+export interface Checked {
+    manifest: Omit<Manifest, "routes"> & {
+        routes: Route[];
+        provides: Provide[];
+        requires: string[];
+    };
+    sources: Record<string, ProgramSource>;
+    /** What `config.overlay` added (APPS.md §6): route keys (routeKey). */
+    derived: Derived;
+}
+export declare class ManifestError extends Error {
+    readonly problems: string[];
+    constructor(problems: string[]);
+}
+export declare const RESERVED_NAMES: string[];
+/** Why `shape` is not a shape (APPS.md §2), or undefined. */
+export declare function shapeProblem(shape: unknown, at: string): string | undefined;
+/**
+ * An http route's path as served: relative to /<app>/ (a leading "/" too). Throws
+ * on anything that could name a path outside that prefix.
+ */
+export declare function appPath(app: string, p: string): string;
+/**
+ * A box as the kernel's table holds it (#128): relative to the app, as an http
+ * path is — "" or the app's own name is the app's box `<app>`; "x" is `<app>/x`. Throws on a
+ * box that is not one: an empty, "." or ".." segment (a leading, trailing or doubled "/"),
+ * whitespace or a control character, or more than 128 bytes resolved (the messagebox
+ * server's limit).
+ */
+export declare function appBox(app: string, b: string): string;
+/** A route's address as served: an http path under /<app>/ (appPath); a box under the app's (appBox); a libp2p name as written. */
+export declare function rowAddress(app: string, r: {
+    transport: string;
+    address: string;
+}): string;
+/** A route's key as the kernel's table knows it (dispatch.ts rowKey): `<transport> <address as served>[ prefix]`. */
+export declare function routeKey(app: string, r: {
+    transport: string;
+    address: string;
+    prefix?: boolean;
+}): string;
+/**
+ * A handler (or a declared filter's function) resolved against the app's programs (#143):
+ * "<role>.<fn>"; a bare name that is a role — the program, no function named; any other bare name
+ * — a function of the app's one program. Undefined: none of these.
+ */
+export declare function handlerOf(h: unknown, roles: string[]): {
+    role: string;
+    fn?: string;
+} | undefined;
+/** A route's filter as the kernel's table names it (#143): the kernel's; an own filter's name → `<app>.<name>`; another app's as written. */
+export declare const filterRef: (app: string, f: string) => string;
+/** Check and normalise a manifest. `has(path)`: whether the tree has a file at the path. */
+export declare function checkManifest(json: unknown, has: (path: string) => boolean): Checked;
+/**
+ * A shell program as the manifest names it (#83), checked: `code: "shell"`;
+ * `modules` command → bin/<x>.wasm in the tree, brush and coreutils among
+ * them (every other name a command the shell runs; two names may share a
+ * module: `node` is qjs); `support` per command of `modules`: an absolute
+ * `mount`, `files` (path under the mount → a file in the tree), `env` text →
+ * text. The install turns it into the record the kernel's shell runs.
+ */
+export declare function shellSource(p: Record<string, unknown>, has: (path: string) => boolean, at: string): ShellSource | string[];
+/** The role of an overlay app's engine (its `config.overlay` is the engine's). */
+export declare const OVERLAY_ROLE = "overlay";
+/** What the install derived from `config.overlay` (route keys), for the prompt. */
+export interface Derived {
+    routes: string[];
+}
+/** An overlay app's wiring. */
+export interface OverlayWiring {
+    routes: Route[];
+    topics: string[];
+}
+/**
+ * The wiring `config.overlay` asks for (APPS.md §6, #79, #143), or its problems. For each topic:
+ * the libp2p routes `<topic>` → submit (kernel.beef), `<topic>-admit` → peerAdmit, `<topic>-proof`
+ * → peerProof; the http route `/submit` (kernel.beef: a submission validates itself — #135, signed
+ * or validated) and `/lookup` (BRC-24's POST: answered by the engine's `lookup`, a filter — a read
+ * route, nothing logged); and the app's own box twice: an `event` route (what its libp2p routes
+ * admit — a gossiped submission, a peer's admit) and a `mailbox` route (its own watch of a
+ * submission the chain app has accepted, sent by the host's loopback). All to the role `overlay`,
+ * the engine, which the manifest must declare `lookup` a filter of. No `chain` or `status` box (the
+ * chain app's): the engine writes `<app>/…` only. No topics is accepted: the box routes, `/submit`
+ * and `/lookup` and no per-topic routes — the topics registered at runtime get theirs from the
+ * engine (#120). `market` ({window: <ms>}), `validator` ({every: <ms>}) and `terms` (a map, the
+ * beat's initial terms: skein-overlay 0.17.0) are the engine's own settings, read from the app record:
+ * checked, no routes derived. A field other than these is
+ * refused (no prefix declarations, #120). `isRole` tells which roles the manifest has.
+ */
+export declare function overlayWiring(app: string, ov: unknown, isRole: (role: string) => boolean): OverlayWiring | string[];
+/** The interfaces `requires` names that no installed app provides. */
+export declare function missingInterfaces(requires: string[], installed: Array<{
+    provides?: Provide[];
+}>): string[];