@dcasegr/skein 0.0.0-stage → 0.1.1

package/dist/host/install.js

@@ -0,0 +1,139 @@
+// Installing an app (#72, #76, #77, #79, #143; docs/APPS.md §3): root's client. An
+// app is a tree (a directory or a git repository) with etc/app.json;
+// installing it into an instance is root-signed messages to the kernel's
+// admin boxes — the kernel's own operations on its tables — nothing else, and
+// no key (#143: the deployer is root, and grants itself nothing):
+//
+//   1. objects    the tree's git objects, the modules its bin/*.wasm carry (a
+//                 shell program's modules and support files too, #83), a program
+//                 record per program, and the **app record** (below)
+//                 — ≤ 1 MiB bundles; no bundle names a root (an app never
+//                 becomes `main`)
+//   2. head       {name: "<app>/app", tree: <the app record>}: the app's root head, under its
+//                 own name (owner = the app).
+//   3. dispatch   one per route the manifest asks for (#77, #143): {op: "add", row: {transport,
+//                 address, prefix?, filters?, program?: <the handler's role's program record>,
+//                 fn?, …settings, app}} — a box under the app's (#128: "" or `<app>` → `<app>`,
+//                 "x" → `<app>/x`), an http address under /<app>/, a libp2p topic or protocol as
+//                 written; the filters named in full (an own filter `<app>.<name>`); a read
+//                 route (no handler) with no program.
+//   4. start      the manifest's `start.body`, into the app's box
+//
+// The **app record** is the head's root: the manifest as installed, so "what
+// does this head provide" is one read (`head("<app>/app")`, `get`):
+//
+//   {kind: "app", name, version, programs: {<role>: <program record CID>},
+//    routes: [<route as the manifest wrote it: relative addresses, handlers, filters as written>],
+//    filters?: {<filter>: <handler>}, roles?: {<role>: [<fn>…]},
+//    config?, provides, requires, start?, stop?, description?, tree: <the app's git tree>,
+//    state?: <the app's own state>}
+//
+// `state` is the app's: its handler advances the head to the record with
+// `state` replaced (the SDK's app.Call.setState). An install over an earlier
+// version carries `state` over, removes the routes the earlier record had and
+// the new one does not, and sends `start` again (the restart). Uninstall:
+// `stop`, then every route removed; the heads are left.
+//
+// **Write scope** (#77, #79): an app's programs write only heads under
+// `<app>/` (the kernel's rule, by the program record's `app`). No alias head,
+// no form before #77. Who may run an app's functions is its `roles`' and
+// root's grants (#143), never the install's.
+//
+// **Two paths to the tree** (#91; docs/APPS.md §3). This client reads it from
+// a directory or clones a repository itself (`readApp`, `fetchApp`:
+// `skein install`, #124; a coding-session tool). Or the instance already holds
+// it: the git app (shruggr/skein-git) cloned one commit into the store by
+// hash and answered {tree, app}; `readStoredApp` reads that tree out of the
+// store (reads are open), and the same `planInstall` rebuilds the app record
+// — whose CID must be the git app's `app` — with nothing left to send but
+// `head`, `dispatch` and `start`.
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { hashDir } from "../client/client.js";
+import { defaultIgnore } from "../dev/scan.js";
+import { currentDispatch } from "../runtime/dispatch.js";
+import { headTree } from "../runtime/heads.js";
+import { addressBook } from "./deploy.js";
+import { checkManifest } from "./manifest.js";
+import { appHead, parseManifest } from "./plan.js";
+// The plan — what an install or an uninstall sends, read from an instance
+// view — is ./plan.ts, which runs in a browser too (the management site,
+// shruggr/skein-site, #92, plans an install over the explorer's reads).
+export * from "./plan.js";
+/** What a tree carries that is not the app: build output, dependencies, VCS. */
+export function appIgnore(rel) {
+    const base = rel.slice(rel.lastIndexOf("/") + 1);
+    return defaultIgnore(rel) || base === "zig-out" || base === ".zig-cache" || base === "zig-pkg";
+}
+/** Read and check the app in `dir`. */
+export async function readApp(dir) {
+    const p = join(dir, "etc/app.json");
+    if (!existsSync(p))
+        throw new Error(`${dir}: no etc/app.json (an app is a tree with a manifest: docs/APPS.md §2)`);
+    const json = parseManifest(readFileSync(p, "utf8"));
+    const isFile = (rel) => existsSync(join(dir, rel)) && statSync(join(dir, rel)).isFile();
+    const checked = checkManifest(json, isFile);
+    const { root, records } = await hashDir(dir, { ignore: appIgnore });
+    return { root, records, checked, read: (rel) => (isFile(rel) ? new Uint8Array(readFileSync(join(dir, rel))) : undefined) };
+}
+/**
+ * Where the app is: a directory, or a git repository URL (`<url>` or
+ * `<url>#<rev>`) cloned into a temporary directory.
+ */
+export function fetchApp(spec) {
+    if (existsSync(spec) && statSync(spec).isDirectory())
+        return resolve(spec);
+    if (!/^(https?:\/\/|git@|ssh:\/\/|file:\/\/)/.test(spec))
+        throw new Error(`${spec}: not a directory or a git URL`);
+    const [url, rev] = spec.split("#");
+    const dir = join(mkdtempSync(join(tmpdir(), "skein-app-")), "app");
+    const git = (...args) => {
+        const r = spawnSync("git", args, { encoding: "utf8" });
+        if (r.status !== 0)
+            throw new Error(`git ${args.join(" ")}: ${r.stderr.trim() || `exit ${r.status}`}`);
+    };
+    git("clone", "-q", ...(rev ? [] : ["--depth", "1"]), url, dir);
+    if (rev)
+        git("-C", dir, "checkout", "-q", rev);
+    return dir;
+}
+// ---------------------------------------------------------------- the instance as the client sees it
+/** The view of an instance's store file (the CLI's, the tests'). */
+export async function instanceView(store) {
+    let g;
+    for await (const { entry } of store.log.entries(0)) {
+        const c = entry.genesis;
+        if (c)
+            g = await store.get(c);
+        break;
+    }
+    if (!g)
+        throw new Error("the instance's store has no genesis yet");
+    const heads = typeof store.heads === "function" ? store.heads() : [];
+    return {
+        store,
+        identity: g.identity instanceof Uint8Array ? Buffer.from(g.identity).toString("hex") : String(g.identity),
+        programs: (g.programs ?? {}),
+        addressBook: await addressBook(store),
+        heads,
+        dispatch: (await currentDispatch(store)) ?? [],
+    };
+}
+/** The root holders (hex) as the head `grants` names them (#143; none: an unclaimed image). */
+export async function rootOf(store) {
+    const root = await headTree(store, "grants");
+    if (!root)
+        return [];
+    const g = await store.get(root).catch(() => undefined);
+    return g?.kind === "grants" ? (g.roles?.root ?? []).map((k) => Buffer.from(k).toString("hex")) : [];
+}
+/** The app record a head's root is, if it is one. */
+export async function appRecordOf(store, name) {
+    const root = await headTree(store, appHead(name));
+    if (!root)
+        return undefined;
+    const r = await store.get(root).catch(() => undefined);
+    return r && r.kind === "app" ? { cid: root, record: r } : undefined;
+}

package/dist/host/instances.d.ts

@@ -0,0 +1,227 @@
+import { DatabaseSync } from "node:sqlite";
+/**
+ * A handle: one hostname label (lower-case letters, digits and "-", at most
+ * 63, no "-" at either end), so `<handle>.<domain>` is the instance's origin.
+ * The one grammar for every row (H22): `add`, the instance manager's
+ * `create`, a mailbox instance.
+ */
+export declare const HANDLE: RegExp;
+/**
+ * A path-only handle (#161): a token id `<txid>_<vout>` (64 lower-case hex digits, `_`, the output
+ * index). Not a hostname label, so its instance is published under no hostname: it is reached at
+ * `/@<handle>/…` on the host's origin only (Router.target, originOf). Everything else about its row is
+ * a row's.
+ */
+export declare const TOKEN_HANDLE: RegExp;
+/** Whether `handle` is a handle this host takes (#161): a hostname label (HANDLE), or a path-only token id (TOKEN_HANDLE). */
+export declare const validHandle: (handle: string) => boolean;
+/** Whether `handle` is path-only (#161): a token id, reached by `/@<handle>` and never by a hostname. */
+export declare const pathOnly: (handle: string) => boolean;
+export type Status = "enabled" | "disabled";
+export type Kind = "agent" | "mailbox";
+/** One row of the fuel ledger. */
+export interface Ledger {
+    instance: string;
+    caller: string;
+    op: string;
+    calls: number;
+    fuel: number;
+    updated_at: string;
+}
+export interface InstanceRow {
+    handle: string;
+    domain: string;
+    identity: string | null;
+    store: string;
+    tree: string | null;
+    source: string | null;
+    /** JSON array of handles, `["*"]` for every other row; null: none. See knowsOf. */
+    knows: string | null;
+    status: Status;
+    created_at: string;
+    kind?: Kind;
+    /** A mailbox instance's: whose mailbox it is (hex). */
+    owner?: string | null;
+    /**
+     * JSON array of the overlay names (gossip topics and lookup services alike) a bare-host POST /submit
+     * or /lookup naming them is routed to this instance by (#137: what the instance manager's create or
+     * start named; Router.overlayTarget); null: none. See topicsOf.
+     */
+    topics?: string | null;
+}
+/** The fields `add` sets; absent ones keep their value (or the column's default on insert). */
+export type RowFields = Partial<Omit<InstanceRow, "handle" | "created_at">>;
+/** The overlay names a row is routed by (#137): its `topics` column, a list (none: empty). */
+export declare function topicsOf(row: Pick<InstanceRow, "topics">): string[];
+/** The handles a row knows: a list, or "all" (every other enabled row). */
+export declare function knowsOf(row: Pick<InstanceRow, "knows">): string[] | "all";
+/** The `knows` column for a list of handles (`*` among them: everyone); an empty list is null. */
+export declare function knowsColumn(handles: string[] | "all"): string | null;
+export declare class HostDb {
+    readonly db: DatabaseSync;
+    /** `readOnly`: an existing file, read only (an instance's resolver beside the supervisor): no schema, no migration. */
+    constructor(path: string, o?: {
+        readOnly?: boolean;
+    });
+    /**
+     * Insert `handle`, or update the given fields of the row that has it (so a
+     * provisioning script can run again). A new row needs `store`.
+     */
+    add(handle: string, f: RowFields, now?: Date): InstanceRow;
+    get(handle: string): InstanceRow | undefined;
+    /**
+     * The identity handle@domain names (BRC-169's answer): an agent's own, or
+     * the owner of a mailbox instance (whose mailbox the instance is).
+     */
+    identityOf(handle: string, domain: string): string | undefined;
+    list(status?: Status): InstanceRow[];
+    /** Set which handles a row knows (knowsColumn); false if there is no such row. */
+    setKnows(handle: string, handles: string[] | "all"): boolean;
+    /** Set the overlay names a row is routed by (#137; topicsOf); an empty list is null; false if there is no such row. */
+    setTopics(handle: string, topics: string[]): boolean;
+    /** Set a row's status; false if there is no such row. */
+    setStatus(handle: string, status: Status): boolean;
+    /** Remove the row (not its store or wallet); false if there was none. */
+    remove(handle: string): boolean;
+    /** The enabled mailbox instance for identity `owner` (hex). */
+    /** A beat kept from `peer` on `handle`'s overlay `topic` (sync): upserted with its addresses (kept when none are known now). */
+    seenPeer(handle: string, topic: string, peer: string, addrs: string[], now: number): void;
+    /** The peers `handle`'s overlay `topic` heard beats from, the latest first. */
+    topicPeers(handle: string, topic: string): Array<{
+        peer: string;
+        addrs: string[];
+        lastSeen: number;
+    }>;
+    /** Forget the peers not heard from since `before` (ms). → how many rows went. */
+    prunePeers(before: number): number;
+    mailboxOf(owner: string): InstanceRow | undefined;
+    /** Add calls and fuel to the ledger (#40): `rows` aggregated by (instance, caller, op). */
+    charge(rows: Array<{
+        instance: string;
+        caller: string;
+        op: string;
+        calls: number;
+        fuel: number;
+    }>, now?: Date): void;
+    ledger(instance?: string): Ledger[];
+    /** The last event id taken from an SSE stream (#58), if any. */
+    cursor(stream: string): string | undefined;
+    setCursor(stream: string, id: string, now?: Date): void;
+    /** Note a status as routed (#58); false if it was already. */
+    markStatus(txid: string, status: string, now?: Date): boolean;
+    hasStatus(txid: string, status: string): boolean;
+    /** Queue a broadcast (#65, arc.ts), due now; one already queued keeps its schedule and gains `instance`. */
+    queueBroadcast(txid: string, body: Uint8Array, instance: string, now: number): void;
+    /** The queued broadcasts due at `now`, oldest first. */
+    dueBroadcasts(now: number): Array<{
+        txid: string;
+        body: Uint8Array;
+        instances: string[];
+        attempts: number;
+        since: number;
+    }>;
+    /** When the next queued broadcast is due (ms), if any. */
+    nextBroadcastAt(): number | undefined;
+    /** A queued broadcast Arcade did not take: one more attempt, posted again at `next`. */
+    retryBroadcast(txid: string, next: number, error: string): void;
+    /** A broadcast Arcade answered (or one given up): off the queue. */
+    unqueueBroadcast(txid: string): void;
+    /** The queue as it stands. */
+    broadcasts(): Array<{
+        txid: string;
+        attempts: number;
+        next: number;
+        error?: string;
+    }>;
+    /** Keep a cron schedule (#69): an instance's, by name (a later one replaces it). */
+    saveSchedule(s: {
+        instance: string;
+        name: string;
+        recipient: string;
+        spec: Uint8Array;
+        request: string;
+        next: number;
+    }): void;
+    /** Drop an instance's schedule; false if it had none by that name. */
+    dropSchedule(instance: string, name: string): boolean;
+    /** Every kept schedule. */
+    schedules(): Array<{
+        instance: string;
+        name: string;
+        recipient: string;
+        spec: Uint8Array;
+        request: string;
+        next: number;
+    }>;
+    /** The enabled row whose identity is `identity`. */
+    byIdentity(identity: string): InstanceRow | undefined;
+    /** A host setting (#90), if set. */
+    setting(key: string): string | undefined;
+    setSetting(key: string, value: string): void;
+    /** An object of the default image's chain part (#132), if held. */
+    imageBlock(cid: string): Uint8Array | undefined;
+    /** One write of the image's chain part (#132): objects put, objects dropped, settings set — all or nothing. */
+    writeImage(puts: Map<string, Uint8Array>, drops: Set<string>, settings: Record<string, string>): void;
+    /** A billed instance as last read (#130); asleep: when it went asleep (ms) is kept from the first time seen. */
+    setBilling(instance: string, b: {
+        host?: string;
+        tally?: bigint;
+        allocation?: bigint;
+        asleep: boolean;
+        mismatch?: string;
+    }, now: number, at?: Date): void;
+    billing(instance: string): {
+        instance: string;
+        host: string | null;
+        tally: string | null;
+        allocation: string | null;
+        asleep_since: number | null;
+        mismatch: string | null;
+        updated_at: string;
+    } | undefined;
+    billings(): Array<{
+        instance: string;
+        host: string | null;
+        tally: string | null;
+        allocation: string | null;
+        asleep_since: number | null;
+        mismatch: string | null;
+        updated_at: string;
+    }>;
+    /** The instances asleep since before `now - graceMs` (#130: the host may reclaim them). */
+    reclaimable(now: number, graceMs: number): Array<{
+        instance: string;
+        asleep_since: number;
+    }>;
+    forgetBilling(instance: string): void;
+    /** A period ticked (#130): its log record and CID. */
+    billingTick(instance: string, at: number, log: string, record: Uint8Array): void;
+    billingTicks(instance: string): Array<{
+        at: number;
+        log: string;
+        record: Uint8Array;
+    }>;
+    /** A payment taken (#130); false if it was already. */
+    billingPayment(p: {
+        instance: string;
+        txid: string;
+        amount: number;
+        at: number;
+        beef: Uint8Array;
+        remittance: unknown;
+        ours: boolean;
+        checkpoint?: string;
+    }): boolean;
+    billingPayments(instance?: string): Array<{
+        instance: string;
+        txid: string;
+        amount: number;
+        at: number;
+        ours: boolean;
+        checkpoint: string | null;
+        remittance: string;
+    }>;
+    /** The host skein (#90): the operator's instance (`skein-host init`), the one row whose identity reaches the instance manager. */
+    hostSkein(): InstanceRow | undefined;
+    close(): void;
+}