@freqhole/haruspex 0.0.0

package/dist/flows/add-peer/runner.js

@@ -0,0 +1,349 @@
+// the bundled effect runner for the add-peer flow: executes the effect
+// descriptors the machine emits against an injected `AddPeerFlowDeps`,
+// and feeds each async outcome back into the machine as an event.
+//
+// `createAddPeerFlow` ties machine + runner together: `send(event)` is
+// the pure transition (returns the effects it produced), `runEffect`
+// executes one effect and recursively drains any follow-on effects its
+// result event produces. an adapter that wants full control (its own
+// scheduler, effect logging, replay) can ignore `runEffect` and execute
+// the descriptors itself.
+//
+// cancellation: CHECK_CONNECTION / CHECK_KNOCK_STATUS runs are tracked
+// with a generation counter; CANCEL_IN_FLIGHT (emitted by BACK from
+// `testing` and by MODAL_CLOSE) bumps it, and a superseded run's outcome
+// event is discarded instead of being fed to the machine.
+import { parsePeerAddress } from "../../share/peer-addr.js";
+import { initialContext, projectState, transition, } from "./machine.js";
+function describeConnectError(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (/timeout/i.test(msg)) {
+        return "connection timed out - peer may be offline or unreachable";
+    }
+    if (/not ?found/i.test(msg)) {
+        return "peer not found - check the address and try again";
+    }
+    return `connection failed: ${msg}`;
+}
+function isAuthRejection(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return (msg.includes("401") ||
+        msg.includes("403") ||
+        msg.includes("Unauthorized") ||
+        msg.includes("Forbidden"));
+}
+export function createAddPeerFlow(deps) {
+    let ctx = initialContext();
+    let disposed = false;
+    /** generation counter for cancellable probes; CANCEL_IN_FLIGHT bumps it. */
+    let probeGeneration = 0;
+    const timerCancels = new Map();
+    function send(event) {
+        if (disposed)
+            return [];
+        const result = transition(ctx, event);
+        ctx = result.ctx;
+        return result.effects;
+    }
+    async function feed(event) {
+        for (const effect of send(event)) {
+            await runEffect(effect);
+        }
+    }
+    function scheduleTimer(id, ms) {
+        timerCancels.get(id)?.();
+        const fire = () => {
+            timerCancels.delete(id);
+            void feed({ type: "TIMER_FIRED", id });
+        };
+        if (deps.scheduleTimer) {
+            timerCancels.set(id, deps.scheduleTimer(id, ms, fire));
+        }
+        else {
+            const handle = setTimeout(fire, ms);
+            timerCancels.set(id, () => clearTimeout(handle));
+        }
+    }
+    async function probeConnection(target) {
+        let info;
+        try {
+            info = await deps.getServerInfo(target);
+        }
+        catch (err) {
+            // an auth rejection on the probe itself can still mean "knockable":
+            // the hello surface is public, so re-read it to route to the knock
+            // form instead of a dead-end error.
+            if (isAuthRejection(err)) {
+                try {
+                    const helloInfo = await deps.getServerInfo(target);
+                    if (helloInfo?.knocking_enabled) {
+                        return {
+                            kind: "needs_knock",
+                            serverInfo: helloInfo,
+                            error: "access denied - you can request access from the server admin",
+                        };
+                    }
+                }
+                catch {
+                    // fall through to the generic failure below
+                }
+            }
+            return { kind: "failed", error: describeConnectError(err) };
+        }
+        if (!info) {
+            return {
+                kind: "failed",
+                error: "connection succeeded but the peer did not return valid server info",
+            };
+        }
+        let authed = false;
+        try {
+            authed = await deps.whoami(target);
+        }
+        catch {
+            authed = false;
+        }
+        if (authed)
+            return { kind: "already_authed", serverInfo: info };
+        if (info.knocking_enabled)
+            return { kind: "needs_knock", serverInfo: info };
+        return { kind: "needs_auth", serverInfo: info };
+    }
+    async function probeKnockStatus(pending) {
+        const target = parsePeerAddress(pending.peer_addr) ?? {
+            type: "p2p",
+            peerAddr: pending.peer_addr,
+        };
+        try {
+            const status = await deps.checkKnockStatus(pending.peer_addr);
+            if (status === "rejected")
+                return { kind: "denied" };
+            if (status === "pending")
+                return { kind: "pending" };
+            if (status === "accepted") {
+                const info = await deps.getServerInfo(target).catch(() => null);
+                let authed = false;
+                try {
+                    authed = await deps.whoami(target);
+                }
+                catch {
+                    authed = false;
+                }
+                return authed
+                    ? { kind: "accepted_authed", serverInfo: info }
+                    : { kind: "accepted_needs_auth", serverInfo: info };
+            }
+            // no status available: a successful plain connection means the
+            // knock must have been accepted
+            const info = await deps.getServerInfo(target).catch(() => null);
+            if (info) {
+                let authed = false;
+                try {
+                    authed = await deps.whoami(target);
+                }
+                catch {
+                    authed = false;
+                }
+                return authed
+                    ? { kind: "accepted_authed", serverInfo: info }
+                    : { kind: "accepted_needs_auth", serverInfo: info };
+            }
+            return { kind: "unreachable" };
+        }
+        catch {
+            return { kind: "unreachable" };
+        }
+    }
+    async function upsertPending(peerAddr, patch) {
+        const existing = await deps.getPendingRemoteByPeerAddr(peerAddr);
+        if (existing) {
+            await deps.updatePendingRemote(existing.id, patch);
+        }
+        else {
+            const target = parsePeerAddress(peerAddr) ?? { type: "p2p", peerAddr };
+            await deps.createPendingRemote({
+                peer_addr: peerAddr,
+                transport: deps.transportFor(target),
+                stage: "testing",
+                server_name: null,
+                server_description: null,
+                server_version: null,
+                server_image_data: null,
+                server_image_type: null,
+                knock_username: null,
+                knock_message: null,
+                error_message: null,
+                ...patch,
+            });
+        }
+        const records = await deps.getAllPendingRemotes();
+        await feed({ type: "PENDING_LOADED", records });
+    }
+    async function runEffect(effect) {
+        if (disposed)
+            return;
+        switch (effect.type) {
+            case "LOAD_PENDING_REMOTES": {
+                const records = await deps.getAllPendingRemotes().catch(() => []);
+                await feed({ type: "PENDING_LOADED", records });
+                return;
+            }
+            case "CHECK_DUPLICATE": {
+                const remotes = await deps.getAllRemotes().catch(() => []);
+                const target = effect.target;
+                const duplicate = target.type === "http"
+                    ? remotes.find((r) => r.base_url === target.url)
+                    : remotes.find((r) => r.peer_addr === target.peerAddr);
+                await feed({ type: "DUPLICATE_RESULT", duplicateName: duplicate?.name ?? null });
+                return;
+            }
+            case "UPSERT_PENDING":
+                await upsertPending(effect.peerAddr, effect.patch).catch(() => { });
+                return;
+            case "DELETE_PENDING":
+                await deps.deletePendingRemote(effect.id).catch(() => { });
+                return;
+            case "DELETE_PENDING_BY_ADDR": {
+                await deps.deletePendingRemoteByPeerAddr(effect.peerAddr).catch(() => { });
+                const records = await deps.getAllPendingRemotes().catch(() => []);
+                await feed({ type: "PENDING_LOADED", records });
+                return;
+            }
+            case "CHECK_CONNECTION": {
+                const generation = ++probeGeneration;
+                const outcome = await probeConnection(effect.target);
+                if (disposed || generation !== probeGeneration)
+                    return; // cancelled/superseded
+                await feed({ type: "CONNECTION_RESULT", outcome });
+                return;
+            }
+            case "CHECK_KNOCK_STATUS": {
+                const generation = ++probeGeneration;
+                const outcome = await probeKnockStatus(effect.pending);
+                if (disposed || generation !== probeGeneration)
+                    return;
+                await feed({ type: "KNOCK_STATUS_RESULT", outcome });
+                return;
+            }
+            case "SEND_KNOCK": {
+                try {
+                    await deps.sendKnock(effect.peerAddr, effect.username, effect.message);
+                    await feed({ type: "KNOCK_SENT_RESULT", ok: true });
+                }
+                catch (err) {
+                    await feed({
+                        type: "KNOCK_SENT_RESULT",
+                        ok: false,
+                        error: err instanceof Error ? err.message : "failed to send access request",
+                    });
+                }
+                return;
+            }
+            case "AUTH_HTTP": {
+                try {
+                    await deps.authenticateHttp(effect.url, {
+                        mode: effect.mode,
+                        username: effect.username,
+                        inviteCode: effect.inviteCode,
+                    });
+                    await feed({ type: "AUTH_RESULT", ok: true });
+                }
+                catch (err) {
+                    await feed({
+                        type: "AUTH_RESULT",
+                        ok: false,
+                        error: err instanceof Error ? err.message : "authentication failed",
+                    });
+                }
+                return;
+            }
+            case "AUTH_REDEEM_INVITE": {
+                try {
+                    await deps.redeemInvite(effect.peerAddr, effect.username, effect.inviteCode);
+                    await feed({ type: "AUTH_RESULT", ok: true });
+                }
+                catch (err) {
+                    await feed({
+                        type: "AUTH_RESULT",
+                        ok: false,
+                        error: err instanceof Error ? err.message : "invite code redemption failed",
+                    });
+                }
+                return;
+            }
+            case "AUTH_PASSKEY_REGISTER": {
+                try {
+                    await deps.registerWithPasskey(effect.peerAddr, effect.username, effect.inviteCode);
+                    await feed({ type: "AUTH_RESULT", ok: true });
+                }
+                catch (err) {
+                    await feed({
+                        type: "AUTH_RESULT",
+                        ok: false,
+                        error: err instanceof Error ? err.message : "passkey registration failed",
+                    });
+                }
+                return;
+            }
+            case "AUTH_PASSKEY_LOGIN": {
+                try {
+                    await deps.loginWithPasskey(effect.target, effect.username);
+                    await feed({ type: "AUTH_RESULT", ok: true });
+                }
+                catch (err) {
+                    await feed({
+                        type: "AUTH_RESULT",
+                        ok: false,
+                        error: err instanceof Error ? err.message : "passkey login failed",
+                    });
+                }
+                return;
+            }
+            case "CREATE_REMOTE": {
+                try {
+                    const remote = await deps.createRemote({
+                        base_url: effect.url || undefined,
+                        peer_addr: effect.peerAddr || undefined,
+                    });
+                    await feed({ type: "REMOTE_CREATED", ok: true, remote });
+                }
+                catch (err) {
+                    await feed({
+                        type: "REMOTE_CREATED",
+                        ok: false,
+                        error: err instanceof Error ? err.message : "failed to save remote",
+                    });
+                }
+                return;
+            }
+            case "CANCEL_IN_FLIGHT":
+                probeGeneration++;
+                return;
+            case "SCHEDULE_TIMER":
+                scheduleTimer(effect.id, effect.ms);
+                return;
+            case "CLEAR_QUERY_PARAM":
+                deps.clearQueryParam?.();
+                return;
+            case "CALL_ON_SUCCESS":
+                deps.onSuccess?.(effect.remote);
+                return;
+            case "CALL_ON_CLOSE":
+                deps.onClose?.();
+                return;
+        }
+    }
+    return {
+        state: () => projectState(ctx),
+        send,
+        runEffect,
+        dispatch: feed,
+        dispose() {
+            disposed = true;
+            probeGeneration++;
+            for (const cancel of timerCancels.values())
+                cancel();
+            timerCancels.clear();
+        },
+    };
+}

package/dist/flows/add-peer/runner.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=runner.test.d.ts.map

package/dist/flows/add-peer/runner.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.test.d.ts","sourceRoot":"","sources":["../../../src/flows/add-peer/runner.test.ts"],"names":[],"mappings":""}

package/dist/flows/add-peer/runner.test.js

@@ -0,0 +1,205 @@
+import { describe, expect, it, vi } from "vitest";
+import { createAddPeerFlow } from "./runner.js";
+const NODE_ID = "c".repeat(64);
+const INFO = {
+    name: "hub",
+    version: "1.0",
+    requires_auth: true,
+    knocking_enabled: false,
+};
+/** in-memory deps: a pending-remote store + scriptable network answers. */
+function makeDeps(overrides = {}) {
+    const pendingStore = new Map();
+    const remotes = [];
+    const timers = [];
+    let nextId = 1;
+    const deps = {
+        getAllRemotes: async () => [...remotes],
+        getAllPendingRemotes: async () => [...pendingStore.values()],
+        getPendingRemoteByPeerAddr: async (addr) => [...pendingStore.values()].find((p) => p.peer_addr === addr) ?? null,
+        createPendingRemote: async (record) => {
+            const created = { ...record, id: `p${nextId++}` };
+            pendingStore.set(created.id, created);
+            return created;
+        },
+        updatePendingRemote: async (id, patch) => {
+            const existing = pendingStore.get(id);
+            if (existing)
+                pendingStore.set(id, { ...existing, ...patch });
+        },
+        deletePendingRemote: async (id) => {
+            pendingStore.delete(id);
+        },
+        deletePendingRemoteByPeerAddr: async (addr) => {
+            for (const [id, p] of pendingStore) {
+                if (p.peer_addr === addr)
+                    pendingStore.delete(id);
+            }
+        },
+        createRemote: async (input) => {
+            const remote = {
+                remote_id: `r${nextId++}`,
+                name: "hub",
+                base_url: input.base_url,
+                peer_addr: input.peer_addr,
+            };
+            remotes.push(remote);
+            return remote;
+        },
+        getServerInfo: async () => INFO,
+        whoami: async () => false,
+        sendKnock: async () => { },
+        checkKnockStatus: async () => "pending",
+        authenticateHttp: async () => { },
+        redeemInvite: async () => { },
+        registerWithPasskey: async () => { },
+        loginWithPasskey: async () => { },
+        transportFor: (target) => (target.type === "p2p" ? "wasm" : "http"),
+        scheduleTimer: (id, ms, fire) => {
+            timers.push({ id, ms, fire });
+            return () => { };
+        },
+        ...overrides,
+    };
+    return { deps, pendingStore, remotes, timers };
+}
+describe("createAddPeerFlow (bundled runner)", () => {
+    it("drives submit -> probe -> auth for an unauthed peer, persisting the pending stages", async () => {
+        const { deps, pendingStore } = makeDeps();
+        const flow = createAddPeerFlow(deps);
+        await flow.dispatch({ type: "SUBMIT_URL", input: NODE_ID });
+        const state = flow.state();
+        expect(state.step).toBe("auth");
+        const records = [...pendingStore.values()];
+        expect(records).toHaveLength(1);
+        expect(records[0].stage).toBe("connected");
+        expect(records[0].server_name).toBe("hub");
+        expect(records[0].transport).toBe("wasm");
+    });
+    it("short-circuits to complete when whoami already succeeds, then dismisses via the timer", async () => {
+        const onSuccess = vi.fn();
+        const onClose = vi.fn();
+        const { deps, pendingStore, timers } = makeDeps({
+            whoami: async () => true,
+            onSuccess,
+            onClose,
+        });
+        const flow = createAddPeerFlow(deps);
+        await flow.dispatch({ type: "SUBMIT_URL", input: NODE_ID });
+        expect(flow.state().step).toBe("complete");
+        // pending record was deleted after the remote was created
+        expect(pendingStore.size).toBe(0);
+        expect(timers).toHaveLength(1);
+        expect(timers[0].ms).toBe(1500);
+        timers[0].fire();
+        await Promise.resolve();
+        expect(onClose).toHaveBeenCalled();
+        expect(onSuccess).toHaveBeenCalledWith(expect.objectContaining({ peer_addr: NODE_ID }));
+        expect(flow.state().step).toBe("url");
+    });
+    it("rejects a duplicate before persisting anything", async () => {
+        const { deps, pendingStore } = makeDeps({
+            getAllRemotes: async () => [{ remote_id: "r0", name: "old hub", peer_addr: NODE_ID }],
+        });
+        const flow = createAddPeerFlow(deps);
+        await flow.dispatch({ type: "SUBMIT_URL", input: NODE_ID });
+        const state = flow.state();
+        expect(state.step).toBe("url");
+        expect(state.step === "url" && state.error).toContain('already added as "old hub"');
+        expect(pendingStore.size).toBe(0);
+    });
+    it("marks the pending record failed with a mapped error when the probe throws", async () => {
+        const { deps, pendingStore } = makeDeps({
+            getServerInfo: async () => {
+                throw new Error("connect timeout after 30s");
+            },
+        });
+        const flow = createAddPeerFlow(deps);
+        await flow.dispatch({ type: "SUBMIT_URL", input: NODE_ID });
+        const state = flow.state();
+        expect(state.step).toBe("url");
+        expect(state.step === "url" && state.error).toMatch(/timed out/);
+        const records = [...pendingStore.values()];
+        expect(records[0].stage).toBe("failed");
+        expect(records[0].error_message).toMatch(/timed out/);
+    });
+    it("routes an auth-rejected probe to the knock form when knocking is enabled", async () => {
+        let calls = 0;
+        const { deps } = makeDeps({
+            getServerInfo: async () => {
+                calls++;
+                // first read rejects with a 403; the public re-read succeeds
+                if (calls === 1)
+                    throw new Error("403 Forbidden");
+                return { ...INFO, knocking_enabled: true };
+            },
+        });
+        const flow = createAddPeerFlow(deps);
+        await flow.dispatch({ type: "SUBMIT_URL", input: NODE_ID });
+        const state = flow.state();
+        expect(state.step).toBe("url");
+        expect(state.step === "url" && state.subStep).toBe("knock_form");
+        expect(state.step === "url" && state.error).toMatch(/request access/);
+    });
+    it("runs the knock flow end to end and resumes it to completion", async () => {
+        let knockStatus = "pending";
+        const sendKnock = vi.fn(async () => { });
+        const { deps, pendingStore } = makeDeps({
+            getServerInfo: async () => ({ ...INFO, knocking_enabled: true }),
+            sendKnock,
+            checkKnockStatus: async () => knockStatus,
+            whoami: async () => knockStatus === "accepted",
+        });
+        const flow = createAddPeerFlow(deps);
+        // submit -> knock form (knocking enabled, not authed)
+        await flow.dispatch({ type: "SUBMIT_URL", input: NODE_ID });
+        expect(flow.state().step === "url" && flow.state().subStep).toBe("knock_form");
+        // send the knock
+        await flow.dispatch({ type: "SUBMIT_KNOCK", username: "ed", message: "hello" });
+        expect(sendKnock).toHaveBeenCalledWith(NODE_ID, "ed", "hello");
+        expect(flow.state().step).toBe("knock_sent");
+        const pending = [...pendingStore.values()][0];
+        expect(pending.stage).toBe("knock_pending");
+        expect(pending.knock_username).toBe("ed");
+        // later: the knock has been accepted; the user retries from the list
+        knockStatus = "accepted";
+        await flow.dispatch({ type: "MODAL_OPEN" });
+        await flow.dispatch({ type: "RETRY_PENDING", pending });
+        expect(flow.state().step).toBe("complete");
+        expect(pendingStore.size).toBe(0);
+    });
+    it("discards a probe result that was cancelled by BACK", async () => {
+        let release;
+        const gate = new Promise((resolve) => {
+            release = resolve;
+        });
+        const { deps } = makeDeps({
+            getServerInfo: async () => {
+                await gate;
+                return INFO;
+            },
+        });
+        const flow = createAddPeerFlow(deps);
+        const submitted = flow.dispatch({ type: "SUBMIT_URL", input: NODE_ID });
+        // give the duplicate check a chance to finish and the probe to start
+        await new Promise((r) => setTimeout(r, 0));
+        await flow.dispatch({ type: "BACK" });
+        release();
+        await submitted;
+        // the machine stayed in url/input; the late probe result was discarded
+        expect(flow.state().step).toBe("url");
+    });
+    it("dispose cancels timers and ignores further events", async () => {
+        const cancel = vi.fn(() => { });
+        const { deps } = makeDeps({
+            whoami: async () => true,
+            scheduleTimer: (_id, _ms, _fire) => cancel,
+        });
+        const flow = createAddPeerFlow(deps);
+        await flow.dispatch({ type: "SUBMIT_URL", input: NODE_ID });
+        expect(flow.state().step).toBe("complete");
+        flow.dispose();
+        expect(cancel).toHaveBeenCalled();
+        expect(flow.send({ type: "MODAL_OPEN" })).toEqual([]);
+    });
+});