cloving 1.2.0 → 1.4.0

package/dist/src/relay/relay-service.js

@@ -0,0 +1,218 @@
+import { randomBytes } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+import { mkdir } from "node:fs/promises";
+import { hostname } from "node:os";
+import { dirname, join } from "node:path";
+import { inboxTiming, runInbox } from "./answer-inbox.js";
+import { watchDecisions, watchTiming, } from "./decision-watch.js";
+import { followPairing } from "./pairing-follow.js";
+import { pairingSessions, RegistrationEnded, } from "./pairing-session.js";
+import { pairAccept, pairDeny, phoneRemove, phoneReset, result, } from "./phone-operations.js";
+import { listenPhoneSocket } from "./phone-socket.js";
+import { heartbeatTiming, runHeartbeats, } from "./relay-heartbeat.js";
+import { relayControl } from "./relay-control.js";
+import { relayOrigin } from "./relay-http.js";
+import { forgetRegistration, readLink, registration, } from "./relay-registration.js";
+import { openRelayStore } from "./relay-store.js";
+function unknownOperation(request) {
+    return {
+        kind: "error",
+        error: {
+            code: "unknown-operation",
+            detail: `The phone relay has no operation ${request.operation}.`,
+        },
+    };
+}
+function pairingView(open) {
+    if (open === undefined)
+        return null;
+    const request = open.request;
+    return {
+        pairingId: open.pairingId,
+        expiresAt: open.expiresAt,
+        stage: open.stage,
+        request: request === undefined
+            ? null
+            : {
+                deviceId: request.deviceId,
+                name: request.name,
+                platform: request.platform,
+                code: request.code,
+            },
+    };
+}
+export async function phoneState(relay) {
+    const stored = await readLink(relay.context.phoneDirectory);
+    const lost = relay.registration.lost;
+    const link = lost ? undefined : stored;
+    return result({
+        registered: link !== undefined,
+        daemonId: link?.daemonId ?? null,
+        origin: link?.origin ?? null,
+        pairing: pairingView(relay.sessions.current()),
+        refusal: relay.sessions.refusal(),
+        reason: lost ? "registration-lost" : null,
+        devices: (await relay.store.devices()).map((device) => ({
+            deviceId: device.deviceId,
+            name: device.name,
+            platform: device.platform,
+            pairedAt: device.pairedAt,
+            state: device.state,
+            removedAt: device.removedAt,
+        })),
+    });
+}
+async function opened(relay) {
+    const startedIn = relay.sessions.generation();
+    try {
+        return await relay.sessions.start(await registration(relay.context), startedIn);
+    }
+    catch (error) {
+        if (!(error instanceof RegistrationEnded))
+            throw error;
+        await relay.store.removeAll();
+        await forgetRegistration(relay.context.phoneDirectory);
+        return relay.sessions.start(await registration(relay.context), startedIn);
+    }
+}
+const starts = new WeakMap();
+function sharedStart(relay) {
+    const running = starts.get(relay);
+    if (running !== undefined)
+        return running;
+    const starting = opened(relay).finally(() => starts.delete(relay));
+    starts.set(relay, starting);
+    return starting;
+}
+async function pairStart(relay) {
+    const open = relay.sessions.current() ?? (await sharedStart(relay));
+    relay.registration.lost = false;
+    return result({ link: open.link, expiresAt: open.expiresAt });
+}
+function pairCancel(relay) {
+    relay.sessions.cancel();
+    return Promise.resolve(result({ pairing: null }));
+}
+async function resetAfterStart(relay) {
+    relay.sessions.cancel();
+    await starts.get(relay)?.catch(() => undefined);
+    return phoneReset(relay);
+}
+const operations = {
+    "phone-state": phoneState,
+    "phone-pair-start": pairStart,
+    "phone-pair-cancel": pairCancel,
+    "phone-pair-accept": pairAccept,
+    "phone-pair-deny": pairDeny,
+    "phone-remove": phoneRemove,
+    "phone-reset": resetAfterStart,
+};
+export function computerName(name) {
+    return name.replace(/\.local$/, "").slice(0, 64);
+}
+function deliveringStore(options, opened) {
+    const stop = new AbortController();
+    const reading = new AbortController();
+    const running = opened.run(stop.signal);
+    const context = {
+        runtimeDirectory: options.runtimeDirectory,
+        phoneDirectory: options.phoneDirectory,
+        store: opened,
+        control: relayControl(options.runtimeDirectory),
+        now: () => Date.now(),
+    };
+    const watch = watchDecisions(context, options.watchTiming ?? watchTiming);
+    const answers = runInbox(context, {
+        signal: reading.signal,
+        timing: options.inboxTiming ?? inboxTiming,
+    });
+    return {
+        store: {
+            ...opened,
+            connect: async (deviceId) => {
+                const found = await opened.connect(deviceId);
+                watch.wake();
+                return found;
+            },
+        },
+        close: async () => {
+            reading.abort();
+            await answers;
+            await watch.close();
+            stop.abort();
+            await running;
+        },
+    };
+}
+export async function startRelay(options) {
+    await mkdir(options.runtimeDirectory, { recursive: true, mode: 0o700 });
+    await mkdir(options.phoneDirectory, { recursive: true, mode: 0o700 });
+    const opened = await openRelayStore(options.phoneDirectory);
+    const delivering = deliveringStore(options, opened);
+    const { store } = delivering;
+    const follower = {
+        follow: () => Promise.resolve(),
+    };
+    const relay = {
+        context: {
+            phoneDirectory: options.phoneDirectory,
+            origin: options.origin ?? relayOrigin(undefined),
+            computerName: options.computerName ?? computerName(hostname()),
+        },
+        store,
+        sessions: pairingSessions({
+            secret: options.secret ?? (() => randomBytes(16)),
+            follow: (open) => follower.follow(open),
+        }),
+        registration: { lost: false },
+    };
+    follower.follow = (open) => followPairing(relay, open);
+    const socket = await listenPhoneSocket(join(options.runtimeDirectory, "phone.sock"), (request) => {
+        const operation = operations[request.operation];
+        return operation === undefined
+            ? Promise.resolve(unknownOperation(request))
+            : operation(relay, request.parameters);
+    });
+    const stop = new AbortController();
+    const beating = runHeartbeats({
+        phoneDirectory: options.phoneDirectory,
+        store,
+        timing: options.heartbeatTiming ?? heartbeatTiming,
+        lost: () => {
+            relay.registration.lost = true;
+            relay.sessions.cancel();
+        },
+        wait: (milliseconds, signal) => delay(milliseconds, undefined, { signal }).catch(() => undefined),
+    }, stop.signal);
+    return {
+        close: async () => {
+            stop.abort();
+            relay.sessions.cancel();
+            await beating;
+            await socket.close();
+            await delivering.close();
+            await opened.close();
+        },
+    };
+}
+export async function runRelay(environment, program) {
+    const runtimeDirectory = environment["CLOVING_RUNTIME_DIR"];
+    if (runtimeDirectory === undefined || runtimeDirectory === "") {
+        program.error("runtime-directory-unknown: The phone relay needs CLOVING_RUNTIME_DIR.\n");
+        return 1;
+    }
+    try {
+        const relay = await startRelay({
+            runtimeDirectory,
+            phoneDirectory: join(dirname(runtimeDirectory), "state", "phone"),
+            origin: relayOrigin(environment["CLOVING_RELAY_ORIGIN"]),
+        });
+        await program.stopped;
+        await relay.close();
+        return 0;
+    }
+    catch (error) {
+        program.error(`phone-relay-failed: ${String(Reflect.get(Object(error), "message"))}\n`);
+        return 1;
+    }
+}

package/dist/src/relay/relay-store.d.ts

@@ -0,0 +1,48 @@
+import { type DeviceDelivery, type DeviceEnvelopes, type PostedEnvelope } from "./phone-delivery.ts";
+import { type PhoneDevice } from "./phone-devices.ts";
+import { type InboxWork } from "./phone-inbox.ts";
+import { type OpenDecision } from "./phone-outbox.ts";
+export interface DeliveryOffer {
+    readonly runId: string;
+    readonly promptDigest: string;
+    readonly deviceId: string;
+    readonly envelopes: readonly PostedEnvelope[];
+}
+export interface DeliveryClosing {
+    readonly devices: readonly DeviceEnvelopes[];
+    readonly at: number;
+}
+export interface RelayStore {
+    readonly devices: () => Promise<readonly PhoneDevice[]>;
+    readonly add: (device: PhoneDevice) => Promise<string | undefined>;
+    readonly connect: (deviceId: string) => Promise<boolean>;
+    readonly nextSequence: (deviceId: string) => Promise<number>;
+    readonly remove: (deviceId: string) => Promise<boolean>;
+    readonly removeAll: () => Promise<number>;
+    readonly delivery: RelayDeliveries;
+    readonly inbox: RelayInbox;
+    readonly run: (signal: AbortSignal) => Promise<void>;
+    readonly close: () => Promise<void>;
+}
+export interface RelayDeliveries {
+    readonly offer: (decisionId: string, offer: DeliveryOffer) => Promise<boolean>;
+    readonly close: (decisionId: string, closing: DeliveryClosing) => Promise<boolean>;
+    readonly open: () => Promise<readonly OpenDecision[]>;
+    readonly list: (decisionId: string) => Promise<readonly DeviceDelivery[]>;
+    readonly promptDigest: (decisionId: string) => Promise<string | null>;
+    readonly sweep: () => Promise<number>;
+    readonly drainAt: (now: Date) => Promise<void>;
+}
+export interface RelayInbox {
+    readonly cursor: () => Promise<number>;
+    readonly work: (answerId: string) => Promise<InboxWork | undefined>;
+    readonly record: (work: InboxWork) => Promise<InboxWork>;
+    readonly complete: (done: {
+        readonly answerId: string;
+        readonly sequence: number;
+    }) => Promise<void>;
+}
+export interface RelayStoreOptions {
+    readonly now?: () => number;
+}
+export declare function openRelayStore(phoneDirectory: string, options?: RelayStoreOptions): Promise<RelayStore>;

package/dist/src/relay/relay-store.js

@@ -0,0 +1,131 @@
+import { chmod, open } from "node:fs/promises";
+import { join } from "node:path";
+import { createRuntime, Rejected, } from "solid-objects";
+import { sqlite } from "solid-objects/database/sqlite";
+import { postEnvelopes } from "./envelope-post.js";
+import { deviceRemoved, PhoneDelivery, postEnvelopesEffect, } from "./phone-delivery.js";
+import { PhoneDevices } from "./phone-devices.js";
+import { PhoneInbox } from "./phone-inbox.js";
+import { outboxIdentity, PhoneOutbox, } from "./phone-outbox.js";
+const relayPrincipal = Object.freeze({ principal: "phone-relay" });
+const devicesIdentity = "phone";
+const inboxIdentity = "phone";
+const relayActors = new Set([
+    PhoneDevices.actorType,
+    PhoneDelivery.actorType,
+    PhoneOutbox.actorType,
+    PhoneInbox.actorType,
+]);
+function authorized(input) {
+    return (relayActors.has(input.actorType) &&
+        input.authorizationContext === relayPrincipal);
+}
+function destroyable(input) {
+    return (input.actorType === PhoneDelivery.actorType &&
+        input.authorizationContext === relayPrincipal);
+}
+function postRefusal(devices, deviceId) {
+    const device = devices.find((item) => item.deviceId === deviceId);
+    if (device === undefined || device.removedAt !== null)
+        return deviceRemoved;
+    return device.state === "connected" ? null : "device-not-connected";
+}
+function relayDeliveries(runtime) {
+    const outbox = runtime
+        .ref(PhoneOutbox, outboxIdentity)
+        .with({ authorizationContext: relayPrincipal });
+    const delivery = (decisionId) => runtime
+        .ref(PhoneDelivery, decisionId)
+        .with({ authorizationContext: relayPrincipal });
+    return {
+        offer: async (decisionId, offer) => {
+            await outbox.track({ decisionId, runId: offer.runId });
+            return delivery(decisionId).offer({
+                deviceId: offer.deviceId,
+                envelopes: offer.envelopes,
+                promptDigest: offer.promptDigest,
+            });
+        },
+        close: async (decisionId, closing) => {
+            const closed = await delivery(decisionId).close(closing);
+            await outbox.untrack({ decisionId });
+            return closed;
+        },
+        open: async () => [...(await outbox.decisions)],
+        list: async (decisionId) => [...(await delivery(decisionId).deliveries)],
+        promptDigest: async (decisionId) => delivery(decisionId).promptDigest,
+        sweep: async () => {
+            const retired = [...(await outbox.retired)];
+            for (const decisionId of retired) {
+                await runtime
+                    .ref(PhoneDelivery, decisionId)
+                    .destroy({ authorizationContext: relayPrincipal });
+                await outbox.forget({ decisionId });
+            }
+            return retired.length;
+        },
+        drainAt: async (now) => {
+            await runtime.testing.runDueReminders({ now });
+            await runtime.testing.drain({ roles: ["actors", "effects"] });
+        },
+    };
+}
+function relayInbox(runtime) {
+    const inbox = runtime
+        .ref(PhoneInbox, inboxIdentity)
+        .with({ authorizationContext: relayPrincipal });
+    return {
+        cursor: async () => inbox.cursor,
+        work: async (answerId) => (await inbox.work).find((item) => item.answerId === answerId),
+        record: (work) => inbox.record(work),
+        complete: (done) => inbox.complete(done),
+    };
+}
+export async function openRelayStore(phoneDirectory, options = {}) {
+    const path = join(phoneDirectory, "relay.sqlite3");
+    await (await open(path, "a", 0o600)).close();
+    await chmod(path, 0o600);
+    const runtime = createRuntime({
+        database: sqlite({ path }),
+        authorizeMessage: authorized,
+        authorizeQuery: authorized,
+        authorizeDestroy: destroyable,
+    });
+    await runtime.install();
+    runtime.register(PhoneDevices);
+    runtime.register(PhoneDelivery);
+    runtime.register(PhoneOutbox);
+    runtime.register(PhoneInbox);
+    const devices = runtime
+        .ref(PhoneDevices, devicesIdentity)
+        .with({ authorizationContext: relayPrincipal });
+    const now = options.now ?? (() => Date.now());
+    runtime.registerEffect(postEnvelopesEffect, async (request) => {
+        const refusal = postRefusal(await devices.devices, request["deviceId"]);
+        if (refusal !== null)
+            return { at: now(), failure: refusal };
+        return postEnvelopes({ phoneDirectory, now }, request);
+    });
+    return {
+        devices: async () => [...(await devices.devices)],
+        add: async (device) => {
+            try {
+                await devices.add({ device });
+                return undefined;
+            }
+            catch (error) {
+                if (error instanceof Rejected)
+                    return error.code.replaceAll("_", "-");
+                throw error;
+            }
+        },
+        connect: (deviceId) => devices.connect({ deviceId }),
+        nextSequence: (deviceId) => devices.nextSequence({ deviceId }),
+        remove: (deviceId) => devices.remove({ deviceId, removedAt: new Date().toISOString() }),
+        removeAll: () => devices.removeAll({ removedAt: new Date().toISOString() }),
+        delivery: relayDeliveries(runtime),
+        inbox: relayInbox(runtime),
+        run: (signal) => runtime.run(signal),
+        close: () => runtime.close(),
+    };
+}

package/dist/src/relay/sealed-post.d.ts

@@ -0,0 +1,25 @@
+import { type Fields, type Reply, type ServiceRequest } from "../protocol.ts";
+import type { EnvelopeTarget } from "./decision-envelopes.ts";
+import { type Envelope } from "./envelope.ts";
+import type { PostedEnvelope } from "./phone-delivery.ts";
+import type { PhoneDevice } from "./phone-devices.ts";
+import type { Registration } from "./relay-registration.ts";
+import type { RelayStore } from "./relay-store.ts";
+export interface CheckContext {
+    readonly phoneDirectory: string;
+    readonly store: RelayStore;
+    readonly control: (request: ServiceRequest) => Promise<Reply>;
+    readonly now: () => number;
+}
+export interface Sealing {
+    readonly registration: Registration;
+    readonly device: PhoneDevice;
+    readonly decisionId: string;
+    readonly issuedAt: string;
+    readonly expiresAt: string;
+    readonly build: (target: EnvelopeTarget) => Envelope;
+}
+export declare function rows(value: unknown): readonly Fields[];
+export declare function resultOf(context: CheckContext, request: ServiceRequest): Promise<Fields | undefined>;
+export declare function envelopeExpiry(gateExpiry: unknown, issued: number): string;
+export declare function sealedPost(context: CheckContext, sealing: Sealing): Promise<PostedEnvelope>;

package/dist/src/relay/sealed-post.js

@@ -0,0 +1,52 @@
+import { randomBytes } from "node:crypto";
+import { record, } from "../protocol.js";
+import { collapseId, sealEnvelope, } from "./envelope.js";
+const pushes = {
+    preview: "alert",
+    full: "none",
+    closed: "passive",
+    receipt: "none",
+};
+const collapsing = new Set(["preview", "closed"]);
+const envelopeLifetimeMilliseconds = 7 * 86_400_000 - 3_600_000;
+export function rows(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((item) => {
+        const fields = record(item);
+        return fields === undefined ? [] : [fields];
+    });
+}
+export async function resultOf(context, request) {
+    const reply = await context.control(request);
+    return reply.kind === "result" ? reply.result : undefined;
+}
+export function envelopeExpiry(gateExpiry, issued) {
+    const limit = issued + envelopeLifetimeMilliseconds;
+    const gate = Date.parse(String(gateExpiry));
+    return new Date(Number.isNaN(gate) ? limit : Math.min(gate, limit)).toISOString();
+}
+export async function sealedPost(context, sealing) {
+    const { registration, device } = sealing;
+    const envelope = sealing.build({
+        daemonId: registration.link.daemonId,
+        deviceId: device.deviceId,
+        sequence: await context.store.nextSequence(device.deviceId),
+        issuedAt: sealing.issuedAt,
+        expiresAt: sealing.expiresAt,
+    });
+    const sealed = sealEnvelope(registration.keys, {
+        envelope,
+        agreementPublicKey: device.agreementPublicKey,
+    });
+    return {
+        envelopeId: randomBytes(16).toString("base64url"),
+        kind: envelope.kind,
+        ciphertext: sealed.toString("base64url"),
+        expiresAt: sealing.expiresAt,
+        push: pushes[envelope.kind],
+        collapseId: collapsing.has(envelope.kind)
+            ? collapseId(registration.keys, sealing.decisionId)
+            : null,
+    };
+}

package/dist/src/relay.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/relay.js

@@ -0,0 +1,8 @@
+import { runRelay } from "./relay/relay-service.js";
+process.exitCode = await runRelay(process.env, {
+    stopped: new Promise((settle) => {
+        process.once("SIGTERM", settle);
+        process.once("SIGINT", settle);
+    }),
+    error: (line) => process.stderr.write(line),
+});

package/dist/src/report-ci.d.ts

@@ -0,0 +1,164 @@
+import { type ReportDatum, type ReportWindow } from "./report-statistics.ts";
+export declare const runnerKinds: readonly ["localMacos", "localLinux", "hostedMacos", "hostedLinux"];
+export type RunnerKind = (typeof runnerKinds)[number];
+export type RunnerData = Readonly<Record<RunnerKind, readonly ReportDatum[]>>;
+export interface ReportCiData {
+    readonly jobMinutes: RunnerData | null;
+    readonly jobLimitShare: RunnerData | null;
+    readonly runnerWaitMinutes: RunnerData | null;
+    readonly timeouts: readonly ReportDatum[] | null;
+    readonly reruns: readonly ReportDatum[] | null;
+}
+export declare function reportCiMetrics(input: ReportCiData | undefined, window: ReportWindow): {
+    jobMinutes: {
+        [k: string]: {
+            evidence: Readonly<Record<string, unknown>>[];
+            mark?: string;
+            status: string;
+            value: number | null;
+            comparisonValue: number | null;
+            baseline: {
+                evidence: Readonly<Record<string, unknown>>[];
+                history: string;
+                days: number;
+                median: null;
+                band: null;
+            } | {
+                evidence: Readonly<Record<string, unknown>>[];
+                history: string;
+                days: number;
+                median: number;
+                band: null;
+            } | {
+                evidence: Readonly<Record<string, unknown>>[];
+                history: string;
+                days: number;
+                median: number;
+                band: {
+                    low: number;
+                    high: number;
+                };
+            };
+        };
+    };
+    jobLimitShare: {
+        [k: string]: {
+            evidence: Readonly<Record<string, unknown>>[];
+            mark?: string;
+            status: string;
+            value: number | null;
+            comparisonValue: number | null;
+            baseline: {
+                evidence: Readonly<Record<string, unknown>>[];
+                history: string;
+                days: number;
+                median: null;
+                band: null;
+            } | {
+                evidence: Readonly<Record<string, unknown>>[];
+                history: string;
+                days: number;
+                median: number;
+                band: null;
+            } | {
+                evidence: Readonly<Record<string, unknown>>[];
+                history: string;
+                days: number;
+                median: number;
+                band: {
+                    low: number;
+                    high: number;
+                };
+            };
+        };
+    };
+    runnerWaitMinutes: {
+        [k: string]: {
+            evidence: Readonly<Record<string, unknown>>[];
+            mark?: string;
+            status: string;
+            value: number | null;
+            comparisonValue: number | null;
+            baseline: {
+                evidence: Readonly<Record<string, unknown>>[];
+                history: string;
+                days: number;
+                median: null;
+                band: null;
+            } | {
+                evidence: Readonly<Record<string, unknown>>[];
+                history: string;
+                days: number;
+                median: number;
+                band: null;
+            } | {
+                evidence: Readonly<Record<string, unknown>>[];
+                history: string;
+                days: number;
+                median: number;
+                band: {
+                    low: number;
+                    high: number;
+                };
+            };
+        };
+    };
+    timeouts: {
+        evidence: Readonly<Record<string, unknown>>[];
+        mark?: string;
+        status: string;
+        value: number | null;
+        comparisonValue: number | null;
+        baseline: {
+            evidence: Readonly<Record<string, unknown>>[];
+            history: string;
+            days: number;
+            median: null;
+            band: null;
+        } | {
+            evidence: Readonly<Record<string, unknown>>[];
+            history: string;
+            days: number;
+            median: number;
+            band: null;
+        } | {
+            evidence: Readonly<Record<string, unknown>>[];
+            history: string;
+            days: number;
+            median: number;
+            band: {
+                low: number;
+                high: number;
+            };
+        };
+    };
+    reruns: {
+        evidence: Readonly<Record<string, unknown>>[];
+        mark?: string;
+        status: string;
+        value: number | null;
+        comparisonValue: number | null;
+        baseline: {
+            evidence: Readonly<Record<string, unknown>>[];
+            history: string;
+            days: number;
+            median: null;
+            band: null;
+        } | {
+            evidence: Readonly<Record<string, unknown>>[];
+            history: string;
+            days: number;
+            median: number;
+            band: null;
+        } | {
+            evidence: Readonly<Record<string, unknown>>[];
+            history: string;
+            days: number;
+            median: number;
+            band: {
+                low: number;
+                high: number;
+            };
+        };
+    };
+};

package/dist/src/report-ci.js

@@ -0,0 +1,32 @@
+import { reportMetric, } from "./report-statistics.js";
+export const runnerKinds = [
+    "localMacos",
+    "localLinux",
+    "hostedMacos",
+    "hostedLinux",
+];
+export function reportCiMetrics(input, window) {
+    const runners = (data) => Object.fromEntries(runnerKinds.map((kind) => [
+        kind,
+        reportMetric({
+            data: data?.[kind] ?? null,
+            window,
+            aggregation: "median",
+        }),
+    ]));
+    return {
+        jobMinutes: runners(input?.jobMinutes),
+        jobLimitShare: runners(input?.jobLimitShare),
+        runnerWaitMinutes: runners(input?.runnerWaitMinutes),
+        timeouts: reportMetric({
+            data: input?.timeouts ?? null,
+            window,
+            aggregation: "count",
+        }),
+        reruns: reportMetric({
+            data: input?.reruns ?? null,
+            window,
+            aggregation: "count",
+        }),
+    };
+}