cloving 0.3.19 → 1.0.1

package/dist/src/operation-identity.js

@@ -0,0 +1,59 @@
+const component = /^[A-Za-z0-9._:/-]{1,128}$/;
+export function operationIdentity(value) {
+    const scope = fields(value);
+    const round = scope["round"];
+    const stage = optionalStage(scope["stage"]);
+    const key = scope["key"];
+    const required = [scope["run"], scope["phase"], scope["operation"]];
+    if (typeof round !== "number" ||
+        !Number.isSafeInteger(round) ||
+        round < 0 ||
+        stage === undefined ||
+        !required.every(isComponent) ||
+        (key !== undefined && !isComponent(key)))
+        return { kind: "invalid", reason: "invalid-operation-scope" };
+    return {
+        kind: "valid",
+        value: JSON.stringify([
+            "cloving-operation",
+            round,
+            ...required,
+            stage,
+            key ?? null,
+        ]),
+    };
+}
+function optionalStage(value) {
+    if (value === undefined)
+        return null;
+    const stage = fields(value);
+    const [id, visit, branch] = [stage["id"], stage["visit"], stage["branch"]];
+    if (!isComponent(id) || !isComponent(visit) || !isComponent(branch))
+        return undefined;
+    return [id, visit, branch];
+}
+function isComponent(value) {
+    return typeof value === "string" && component.test(value);
+}
+function fields(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return {};
+    return Object.fromEntries(Object.entries(value));
+}
+export function operationScope(operationId) {
+    const [marker, , run, , operation] = parsedList(operationId);
+    if (marker !== "cloving-operation")
+        return null;
+    if (!isComponent(run) || !isComponent(operation))
+        return null;
+    return { run, operation };
+}
+function parsedList(text) {
+    try {
+        const value = JSON.parse(text);
+        return Array.isArray(value) ? value : [];
+    }
+    catch {
+        return [];
+    }
+}

package/dist/src/protocol.d.ts

@@ -0,0 +1,35 @@
+export declare const protocolVersion = 1;
+export declare const maximumFrameBytes = 1048576;
+export type Fields = Readonly<Record<string, unknown>>;
+export interface ServiceRequest {
+    readonly operation: string;
+    readonly parameters: Fields;
+}
+export interface ServiceError extends Fields {
+    readonly code: string;
+    readonly detail: string;
+}
+export type Reply = {
+    readonly kind: "result";
+    readonly result: Fields;
+} | {
+    readonly kind: "error";
+    readonly error: ServiceError;
+};
+export type ParsedRequest = {
+    readonly kind: "request";
+    readonly request: ServiceRequest;
+} | {
+    readonly kind: "error";
+    readonly error: ServiceError;
+};
+export type ReplyLine = Reply | {
+    readonly kind: "event";
+    readonly event: Fields;
+};
+export declare function record(value: unknown): Fields | undefined;
+export declare function parseRequest(line: string): ParsedRequest;
+export declare function requestLine(request: ServiceRequest): string;
+export declare function replyLine(reply: Reply): string;
+export declare function eventLine(event: Fields): string;
+export declare function parseReplyLine(line: string): ReplyLine | undefined;

package/dist/src/protocol.js

@@ -0,0 +1,64 @@
+export const protocolVersion = 1;
+export const maximumFrameBytes = 1_048_576;
+export function record(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    return Object.fromEntries(Object.entries(value));
+}
+function decoded(line) {
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+}
+function invalid(detail) {
+    return { kind: "error", error: { code: "invalid-request", detail } };
+}
+export function parseRequest(line) {
+    const fields = record(decoded(line));
+    if (fields === undefined)
+        return invalid("The request is not a JSON object.");
+    if (fields["protocol"] !== protocolVersion)
+        return {
+            kind: "error",
+            error: {
+                code: "service-incompatible",
+                detail: `The service uses protocol ${String(protocolVersion)}.`,
+            },
+        };
+    const { operation } = fields;
+    const parameters = record(fields["parameters"]);
+    if (typeof operation !== "string" || parameters === undefined)
+        return invalid("The request needs an operation and a parameters object.");
+    return { kind: "request", request: { operation, parameters } };
+}
+export function requestLine(request) {
+    return `${JSON.stringify({ protocol: protocolVersion, ...request })}\n`;
+}
+export function replyLine(reply) {
+    return reply.kind === "result"
+        ? `${JSON.stringify({ ok: true, result: reply.result })}\n`
+        : `${JSON.stringify({ ok: false, error: reply.error })}\n`;
+}
+export function eventLine(event) {
+    return `${JSON.stringify({ event })}\n`;
+}
+export function parseReplyLine(line) {
+    const fields = record(decoded(line));
+    if (fields === undefined)
+        return undefined;
+    const event = record(fields["event"]);
+    if (event !== undefined)
+        return { kind: "event", event };
+    const result = record(fields["result"]);
+    if (fields["ok"] === true && result !== undefined)
+        return { kind: "result", result };
+    const error = record(fields["error"]);
+    const code = error?.["code"];
+    const detail = error?.["detail"];
+    if (typeof code !== "string" || typeof detail !== "string")
+        return undefined;
+    return { kind: "error", error: { ...error, code, detail } };
+}

package/dist/src/resource-files.d.ts

@@ -0,0 +1 @@
+export declare function collectResources(root: string, paths: readonly string[]): Promise<Readonly<Record<string, string>>>;

package/dist/src/resource-files.js

@@ -0,0 +1,29 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, realpath } from "node:fs/promises";
+import { isAbsolute, join, relative, sep } from "node:path";
+export async function collectResources(root, paths) {
+    const base = await realpath(root);
+    const entries = [];
+    for (const path of paths) {
+        const digest = await resourceDigest(base, path);
+        if (digest !== null)
+            entries.push([path, digest]);
+    }
+    return Object.fromEntries(entries);
+}
+async function resourceDigest(base, path) {
+    if (isAbsolute(path))
+        return null;
+    const file = await realpath(join(base, path)).catch(() => null);
+    if (file === null)
+        return null;
+    const inside = relative(base, file);
+    if (inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute(inside))
+        return null;
+    if (!(await lstat(file)).isFile())
+        return null;
+    const bytes = await readFile(file).catch(() => null);
+    if (bytes === null)
+        return null;
+    return createHash("sha256").update(bytes).digest("hex");
+}

package/dist/src/service/changes.d.ts

@@ -0,0 +1,11 @@
+export interface ChangeWait {
+    readonly after: number;
+    readonly milliseconds: number;
+}
+export interface ChangeSignal {
+    readonly next: (wait: ChangeWait) => Promise<void>;
+    readonly close: () => void;
+}
+type Subscribe = (listener: (sequence: number) => void) => () => void;
+export declare function changeSignal(subscribe: Subscribe): ChangeSignal;
+export {};

package/dist/src/service/changes.js

@@ -0,0 +1,32 @@
+export function changeSignal(subscribe) {
+    const waiting = new Set();
+    const seen = { latest: -1, closed: false };
+    const wake = () => {
+        for (const settle of [...waiting])
+            settle();
+    };
+    const unsubscribe = subscribe((sequence) => {
+        seen.latest = Math.max(seen.latest, sequence);
+        wake();
+    });
+    return {
+        next: ({ after, milliseconds }) => {
+            if (seen.closed || seen.latest > after)
+                return Promise.resolve();
+            return new Promise((settle) => {
+                const done = () => {
+                    clearTimeout(timer);
+                    waiting.delete(done);
+                    settle();
+                };
+                const timer = setTimeout(done, milliseconds);
+                waiting.add(done);
+            });
+        },
+        close: () => {
+            seen.closed = true;
+            unsubscribe();
+            wake();
+        },
+    };
+}

package/dist/src/service/decision-handler.d.ts

@@ -0,0 +1,9 @@
+import type { StoredState } from "../broker/actor/authority.ts";
+import type { Fields, Reply } from "../protocol.ts";
+import { type ServiceContext } from "./replies.ts";
+export declare function feedbackOf(context: ServiceContext, scope: {
+    readonly state: StoredState;
+    readonly runId: string;
+}): Promise<readonly Fields[]>;
+export declare function questions(context: ServiceContext, parameters: Fields): Promise<Reply>;
+export declare function decision(context: ServiceContext, parameters: Fields): Promise<Reply>;

package/dist/src/service/decision-handler.js

@@ -0,0 +1,233 @@
+import { continues, gateKey } from "../authority/gates.js";
+import { gateContinuation } from "../authority/reduction.js";
+import { documentDigest } from "../broker/decision-restore.js";
+import { committed, failed, invalidRequest, isIdentifier, publicReceipt, rejection, result, wholeNumber, } from "./replies.js";
+const decisions = {
+    answer: "answered",
+    approve: "approved",
+    deny: "denied",
+};
+const feedbackBytes = 8_000;
+const commands = {
+    question: ["answer"],
+    approval: ["approve", "deny"],
+};
+function decisionId(gate) {
+    return `${gate.runId}/${gate.gateId}`;
+}
+function label(gate) {
+    return gate.label === null ? null : `Q${String(gate.label)}`;
+}
+function typed(state) {
+    return Object.values(state.gates)
+        .filter((gate) => gate.kind !== "untyped")
+        .sort((left, right) => left.openedSequence - right.openedSequence);
+}
+function pending(state) {
+    return typed(state).filter((gate) => gate.outcome === null &&
+        ["waiting_gate", "paused"].includes(state.runs[gate.runId]?.status ?? ""));
+}
+export async function feedbackOf(context, scope) {
+    const denied = Object.values(scope.state.gates)
+        .filter((gate) => gate.runId === scope.runId &&
+        gate.outcome?.decision === "denied" &&
+        gate.outcome.answer !== null)
+        .sort((left, right) => left.openedSequence - right.openedSequence);
+    const shown = [];
+    for (const gate of denied) {
+        const text = await context.authority.queries.document(gate.outcome?.answer ?? "");
+        shown.push({
+            decisionId: `${gate.runId}/${gate.gateId}`,
+            text: text ?? "",
+        });
+    }
+    return shown;
+}
+async function described(context, shown) {
+    const { state, gate } = shown;
+    const { queries } = context.authority;
+    const opened = await queries.eventsAfter({
+        after: gate.openedSequence - 1,
+        limit: 1,
+    });
+    return {
+        decisionId: decisionId(gate),
+        label: label(gate),
+        type: gate.kind,
+        runId: gate.runId,
+        gateId: gate.gateId,
+        prompt: (await queries.document(gate.prompt ?? "")) ?? "",
+        allowed: commands[gate.kind] ?? [],
+        revision: gate.revision,
+        generation: gate.generation,
+        subjectDigest: gate.subject,
+        openedAt: opened.events[0]?.recordedAt ?? "",
+        expiresAt: gate.expiresAt,
+        context: [],
+        feedback: await feedbackOf(context, { state, runId: gate.runId }),
+    };
+}
+export async function questions(context, parameters) {
+    const { runId } = parameters;
+    const state = await context.authority.state();
+    const listed = pending(state).filter((gate) => runId === undefined || gate.runId === runId);
+    const views = [];
+    for (const gate of listed)
+        views.push(await described(context, { state, gate }));
+    return result("decision-list", { decisions: views });
+}
+function referenced(gates, reference) {
+    const matches = [
+        (gate) => decisionId(gate) === reference,
+        (gate) => label(gate) === reference,
+        (gate) => gate.runId === reference,
+    ].map((matcher) => gates.filter(matcher));
+    return matches.find((found) => found.length > 0) ?? [];
+}
+function refusedTarget(code, extra) {
+    return { kind: "refused", reply: failed(code, extra) };
+}
+function target(state, request) {
+    const { reference, command } = request;
+    const open = referenced(pending(state), reference);
+    if (open.length === 0)
+        return refusedTarget(referenced(typed(state), reference).length > 0
+            ? "decision-not-pending"
+            : "unknown-decision", { detail: `No pending decision matches ${reference}.` });
+    const allowing = open.filter((gate) => commands[gate.kind]?.includes(command));
+    const [gate] = allowing;
+    if (gate === undefined)
+        return refusedTarget("decision-not-allowed", {
+            detail: `The decision does not allow the command ${command}.`,
+        });
+    if (allowing.length > 1)
+        return refusedTarget("ambiguous-decision", {
+            detail: "The reference matches more than one pending decision.",
+            candidates: allowing.map(decisionId),
+        });
+    return { kind: "gate", gate };
+}
+function validText(command, text) {
+    const given = typeof text === "string" && text.trim().length > 0;
+    if (command === "answer")
+        return given;
+    if (command === "deny")
+        return given || text === undefined || text === null;
+    return text === undefined || text === null;
+}
+function textLimit(context, command) {
+    return command === "deny"
+        ? { bytes: feedbackBytes, name: "A feedback text" }
+        : { bytes: context.textBytes, name: "An answer" };
+}
+function decisionRequest(parameters) {
+    const { command, reference, expectedRevision, generation } = parameters;
+    const { subjectDigest, commandId } = parameters;
+    const text = parameters["text"] ?? null;
+    if (typeof command !== "string" ||
+        !Object.hasOwn(decisions, command) ||
+        typeof reference !== "string" ||
+        !wholeNumber(expectedRevision, 1) ||
+        !wholeNumber(generation, 1) ||
+        !isIdentifier(subjectDigest) ||
+        !isIdentifier(commandId) ||
+        !validText(command, text))
+        return undefined;
+    return {
+        command,
+        reference,
+        text,
+        expectedRevision,
+        generation,
+        subjectDigest,
+        commandId,
+    };
+}
+async function located(context, request) {
+    const { commandId, text } = request;
+    const limit = textLimit(context, request.command);
+    if (text !== null && Buffer.byteLength(text) > limit.bytes)
+        return refusedTarget("input-too-large", {
+            commandId,
+            detail: `${limit.name} has at most ${String(limit.bytes)} bytes.`,
+        });
+    const existing = await context.authority.queries.receipt(commandId);
+    if (existing === undefined)
+        return target(await context.authority.state(), request);
+    const { gateId } = existing.command;
+    if (existing.command.kind !== "decide-gate" || gateId === undefined)
+        return refusedTarget("conflicting-command", {
+            commandId,
+            detail: "The command ID is known with a different request.",
+        });
+    return { kind: "known", runId: existing.runId, gateId };
+}
+export async function decision(context, parameters) {
+    const request = decisionRequest(parameters);
+    if (request === undefined)
+        return invalidRequest("The decision request is not valid.");
+    const found = await located(context, request);
+    if (found.kind === "refused")
+        return found.reply;
+    const { runId, gateId } = found.kind === "gate" ? found.gate : found;
+    const { commandId, text } = request;
+    const receipt = await context.gateway.execute({
+        principal: "operator",
+        command: {
+            kind: "decide-gate",
+            commandId,
+            runId,
+            gateId,
+            decision: decisions[request.command],
+            expectedRevision: request.expectedRevision,
+            generation: request.generation,
+            subject: request.subjectDigest,
+            ...(text === null ? {} : { answer: documentDigest(text) }),
+        },
+        documents: text === null ? [] : [text],
+    });
+    if (!committed(receipt)) {
+        const state = await context.authority.state();
+        return rejection(receipt, {
+            commandId,
+            runId,
+            currentRevision: state.gates[gateKey(runId, gateId)]?.revision ?? null,
+        });
+    }
+    return recorded(context, {
+        commandId,
+        runId,
+        gateId,
+        replayed: receipt.kind === "duplicate",
+    });
+}
+async function continuationState(context, decided) {
+    const { gate, run } = decided;
+    if (!continues(gate))
+        return "held";
+    const { operationId } = gateContinuation(gate);
+    const operation = (await context.authority.operations()).find((item) => item.operationId === operationId);
+    if (operation?.deliveries.some((delivery) => delivery.outcome === "sent"))
+        return "admitted";
+    const deliverable = operation?.releasedSequence === null && run.status === "running";
+    return deliverable ? "admitted" : "held";
+}
+async function recorded(context, outcome) {
+    const { commandId, runId, gateId } = outcome;
+    const stored = await context.authority.queries.receipt(commandId);
+    const state = await context.authority.state();
+    const gate = state.gates[gateKey(runId, gateId)];
+    const run = state.runs[runId];
+    if (stored === undefined || gate === undefined || run === undefined)
+        return failed("authority-unavailable", { commandId, runId });
+    return result("decision-recorded", {
+        decisionId: decisionId(gate),
+        runId,
+        decision: gate.outcome?.decision ?? null,
+        commandId,
+        replayed: outcome.replayed,
+        receipt: publicReceipt(stored),
+        run: { state: run.status, revision: run.revision },
+        continuation: await continuationState(context, { gate, run }),
+    });
+}

package/dist/src/service/event-handler.d.ts

@@ -0,0 +1,10 @@
+import type { Fields, Reply } from "../protocol.ts";
+import { type ServiceContext } from "./replies.ts";
+export interface Connection {
+    readonly send: (events: readonly Fields[]) => Promise<boolean>;
+    readonly closed: () => boolean;
+}
+export declare function events(context: ServiceContext, request: {
+    readonly parameters: Fields;
+    readonly connection: Connection;
+}): Promise<Reply | undefined>;

package/dist/src/service/event-handler.js

@@ -0,0 +1,70 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { failed, invalidRequest, isIdentifier, result, wholeNumber, } from "./replies.js";
+function cursor(parameters) {
+    const { runId } = parameters;
+    const after = parameters["after"] ?? 0;
+    const limit = parameters["limit"] ?? 100;
+    if (!wholeNumber(after, 0) ||
+        !wholeNumber(limit, 1) ||
+        limit > 1000 ||
+        (runId !== undefined && typeof runId !== "string"))
+        return undefined;
+    return { after, limit, ...(runId === undefined ? {} : { runId }) };
+}
+function published(page) {
+    return page.events.map((event) => ({ schemaVersion: 1, ...event }));
+}
+function gap(after, page) {
+    return failed("event-gap", {
+        detail: `The service has no events after sequence ${String(after)}.`,
+        after,
+        earliestAvailable: page.earliest,
+        latestSequence: page.latest,
+    });
+}
+async function followed(context, stream) {
+    const { connection } = stream;
+    let { after } = stream.start;
+    while (!connection.closed()) {
+        const page = await context.authority.queries.eventsAfter({
+            ...stream.start,
+            after,
+        });
+        if (!(await connection.send(published(page))))
+            return undefined;
+        after = page.events.at(-1)?.sequence ?? after;
+        if (page.events.length === 0)
+            await changed(context, page.latest);
+    }
+    return undefined;
+}
+function changed(context, latest) {
+    const milliseconds = context.followMilliseconds;
+    return context.changed === undefined
+        ? delay(milliseconds)
+        : context.changed({ after: latest, milliseconds });
+}
+async function known(context, runId) {
+    if (!isIdentifier(runId))
+        return false;
+    return (await context.authority.state()).runs[runId] !== undefined;
+}
+export async function events(context, request) {
+    const start = cursor(request.parameters);
+    if (start === undefined)
+        return invalidRequest("The events request is not valid.");
+    if (start.runId !== undefined && !(await known(context, start.runId)))
+        return failed("unknown-run", {
+            runId: start.runId,
+            detail: `No run has the ID ${start.runId}.`,
+        });
+    const page = await context.authority.queries.eventsAfter(start);
+    if (start.after > page.latest)
+        return gap(start.after, page);
+    if (request.parameters["follow"] === true)
+        return followed(context, { start, connection: request.connection });
+    return result("event-page", {
+        events: published(page),
+        latestSequence: page.latest,
+    });
+}

package/dist/src/service/expiry.d.ts

@@ -0,0 +1,13 @@
+import type { Authority } from "../broker/actor/authority.ts";
+import type { Gateway } from "./gateway.ts";
+export interface ExpiryScan {
+    readonly stop: () => Promise<void>;
+}
+interface ScanParts {
+    readonly authority: Authority;
+    readonly gateway: Gateway;
+    readonly clock: () => string;
+    readonly intervalMilliseconds: number;
+}
+export declare function expiryScan(parts: ScanParts): ExpiryScan;
+export {};

package/dist/src/service/expiry.js

@@ -0,0 +1,53 @@
+import { createHash } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+import { notBefore } from "../authority/instants.js";
+import { operationDigest } from "../broker/operation-digest.js";
+function expiryIdentity(runId, gateId) {
+    return `expire:${createHash("sha256").update(`${runId} ${gateId}`).digest("hex").slice(0, 32)}`;
+}
+async function scanned(parts) {
+    const { authority, gateway, clock } = parts;
+    const state = await authority.state();
+    const now = clock();
+    const due = Object.values(state.gates).filter((gate) => gate.outcome === null &&
+        gate.expiresAt !== null &&
+        notBefore(now, gate.expiresAt) &&
+        state.runs[gate.runId]?.status === "waiting_gate");
+    for (const gate of due)
+        await gateway.execute({
+            principal: "controller",
+            command: {
+                kind: "expire-gate",
+                commandId: expiryIdentity(gate.runId, gate.gateId),
+                runId: gate.runId,
+                gateId: gate.gateId,
+            },
+        });
+    for (const lease of await authority.effects.dueLeases(now))
+        await gateway.execute({
+            principal: "controller",
+            command: {
+                kind: "expire-lease",
+                commandId: `expire-lease:${operationDigest(lease.operationId)}:${String(lease.generation)}`,
+                runId: lease.runId,
+                operationId: lease.operationId,
+                leaseGeneration: lease.generation,
+            },
+        });
+}
+async function cycle(parts, signal) {
+    while (!signal.aborted) {
+        await scanned(parts).catch(() => undefined);
+        await delay(parts.intervalMilliseconds, undefined, { signal }).catch(() => undefined);
+    }
+}
+export function expiryScan(parts) {
+    const stopping = new AbortController();
+    const running = cycle(parts, stopping.signal);
+    return {
+        stop: async () => {
+            stopping.abort();
+            await running;
+        },
+    };
+}

package/dist/src/service/gateway.d.ts

@@ -0,0 +1,21 @@
+import type { Authority, StoreReceipt } from "../broker/actor/authority.ts";
+import type { Registry } from "./registry.ts";
+export type Principal = "operator" | "worker" | "controller";
+export type Command = Readonly<Record<string, unknown>>;
+export interface Submission {
+    readonly principal: Principal;
+    readonly command: Command;
+    readonly documents?: readonly string[];
+    readonly epoch?: number;
+}
+export declare const workerCommandBound = 1000;
+export interface Gateway {
+    readonly execute: (submission: Submission) => Promise<StoreReceipt>;
+}
+export declare function commandGateway(parts: {
+    readonly authority: Authority;
+    readonly registry: Registry;
+    readonly clock: () => string;
+    readonly textBytes: number;
+    readonly pendingWorkerCommands?: number;
+}): Gateway;