@phreshos/server 0.1.0

package/dist/wire.js

@@ -0,0 +1,234 @@
+import { randomUUID } from "node:crypto";
+import Deadline from "./deadline.js";
+import { defaultTimeout } from "./events.js";
+/** The server endpoint's sole IPC adapter. */
+class Wire {
+    pending = new Map();
+    subscribers = new Map();
+    every = new Map();
+    answerers = new Map();
+    waiting = new Map();
+    impossible = new Map();
+    identity;
+    constructor() {
+        let identify = () => undefined;
+        this.identity = new Promise(resolve => { identify = resolve; });
+        process.on("message", message => {
+            if (!Array.isArray(message))
+                return;
+            const [route, ...values] = message;
+            if (route === "boundary") {
+                const [operation, ...rest] = values;
+                if (operation === "forget" && typeof rest[0] === "string")
+                    this.forgetIncoming(rest[0]);
+                if (operation === "impossible" && typeof rest[0] === "string" && typeof rest[1] === "string") {
+                    this.impossible.get(rest[0])?.(new Error(rest[1]));
+                    this.impossible.delete(rest[0]);
+                }
+                return;
+            }
+            if (route === "host-end" && values[0] === "identity" && typeof values[1] === "string" && typeof values[2] === "string") {
+                identify({ process: values[1], program: values[2] });
+                return;
+            }
+            if (values[0] === "answer" && typeof values[1] === "string") {
+                this.settle(values[1], values.at(-1));
+                return;
+            }
+            if (values[0] === "wait" && typeof values[1] === "string" && typeof values[2] === "string" && typeof values[3] === "string") {
+                this.receiveQuestion(route, values.slice(3), { address: values[1], id: values[2] });
+                return;
+            }
+            this.deliver(route, values);
+        });
+        process.send?.(["boundary", "identity"]);
+        process.send?.(["boundary", "ready"]);
+    }
+    send(route, ...values) {
+        process.send?.([route, ...values]);
+    }
+    request(values, timeout = defaultTimeout) {
+        return this.requestWithin(values, new Deadline(timeout));
+    }
+    requestWithin(values, deadline) {
+        const question = randomUUID();
+        return new Promise((resolve, reject) => {
+            this.send("boundary", "expect", question);
+            const timer = setTimeout(() => {
+                this.pending.delete(question);
+                this.send("boundary", "forget", question);
+                reject(new Error(`Answer timeout ${deadline.milliseconds}ms`));
+            }, deadline.remaining());
+            this.pending.set(question, { resolve, reject, timer });
+            this.send("end-host", "wait", question, ...values);
+        });
+    }
+    expectWithin(question, deadline) {
+        return new Promise((resolve, reject) => {
+            this.send("boundary", "expect", question);
+            const timer = setTimeout(() => {
+                this.pending.delete(question);
+                this.send("boundary", "forget", question);
+                reject(new Error(`Answer timeout ${deadline.milliseconds}ms`));
+            }, deadline.remaining());
+            this.pending.set(question, { resolve, reject, timer });
+        });
+    }
+    forget(question) {
+        const pending = this.pending.get(question);
+        if (pending)
+            clearTimeout(pending.timer);
+        this.pending.delete(question);
+        this.send("boundary", "forget", question);
+    }
+    on(route, event, handler, subject = null, impossible) {
+        const key = `${route}:${event}`;
+        const handlers = this.subscribers.get(key) ?? new Set();
+        handlers.add(handler);
+        this.subscribers.set(key, handlers);
+        const subscription = this.register("publish", route, event, subject, impossible);
+        return once(() => {
+            handlers.delete(handler);
+            if (!handlers.size)
+                this.subscribers.delete(key);
+            this.unregister(subscription);
+        });
+    }
+    onAll(route, handler, subject = null) {
+        const handlers = this.every.get(route) ?? new Set();
+        handlers.add(handler);
+        this.every.set(route, handlers);
+        const subscription = this.register("publish", route, null, subject);
+        return once(() => {
+            handlers.delete(handler);
+            if (!handlers.size)
+                this.every.delete(route);
+            this.unregister(subscription);
+        });
+    }
+    answer(route, event, handler) {
+        const key = `${route}:${event}`;
+        if (this.answerers.has(key))
+            throw new Error(`The "${event}" event already has an answerer`);
+        this.answerers.set(key, handler);
+        const subscription = this.register("ask", route, event, null);
+        this.releaseWaiting(route, event);
+        return once(() => {
+            if (this.answerers.get(key) === handler)
+                this.answerers.delete(key);
+            this.unregister(subscription);
+        });
+    }
+    observe(target, half, kind, event, handler, impossible) {
+        const subscription = randomUUID();
+        const stop = this.on("observed", subscription, handler);
+        if (impossible)
+            this.impossible.set(subscription, impossible);
+        this.send("end-host", "observe", subscription, target, half, kind, event, impossible !== undefined);
+        return once(() => {
+            stop();
+            this.impossible.delete(subscription);
+            this.send("end-host", "unobserve", subscription);
+        });
+    }
+    register(kind, route, event, subject, impossible) {
+        const subscription = randomUUID();
+        if (impossible)
+            this.impossible.set(subscription, impossible);
+        this.send("boundary", "subscribe", subscription, kind, route, event, subject, impossible !== undefined);
+        return subscription;
+    }
+    unregister(subscription) {
+        this.impossible.delete(subscription);
+        this.send("boundary", "unsubscribe", subscription);
+    }
+    deliver(route, values) {
+        const [event, ...message] = values;
+        if (typeof event !== "string")
+            return;
+        const handlers = [...this.subscribers.get(`${route}:${event}`) ?? []];
+        for (const handler of handlers)
+            invoke(handler, message);
+        const observers = [...this.every.get(route) ?? []];
+        for (const observer of observers)
+            invoke(observer, [event, ...message]);
+    }
+    receiveQuestion(route, values, question) {
+        const [event, ...message] = values;
+        if (typeof event !== "string")
+            return;
+        const answerer = this.answerers.get(`${route}:${event}`);
+        if (!answerer) {
+            const key = `${route}:${event}`;
+            const waiting = this.waiting.get(key) ?? [];
+            waiting.push({ values, question });
+            this.waiting.set(key, waiting);
+            return;
+        }
+        let result;
+        try {
+            result = answerer(...message);
+        }
+        catch (error) {
+            this.sendAnswer(route, question, event, failed(error));
+            return;
+        }
+        Promise.resolve(result).then(answer => this.sendAnswer(route, question, event, { success: true, result: answer }), error => this.sendAnswer(route, question, event, failed(error)));
+    }
+    sendAnswer(route, question, event, outcome) {
+        this.send(route, "answer", question.address, question.id, event, outcome);
+    }
+    releaseWaiting(route, event) {
+        const key = `${route}:${event}`;
+        const waiting = this.waiting.get(key);
+        if (!waiting)
+            return;
+        this.waiting.delete(key);
+        for (const held of waiting)
+            this.receiveQuestion(route, held.values, held.question);
+    }
+    forgetIncoming(question) {
+        for (const [key, waiting] of this.waiting) {
+            const remaining = waiting.filter(entry => entry.question.address !== question);
+            if (remaining.length)
+                this.waiting.set(key, remaining);
+            else
+                this.waiting.delete(key);
+        }
+    }
+    settle(question, outcome) {
+        const pending = this.pending.get(question);
+        if (!pending)
+            return;
+        this.pending.delete(question);
+        clearTimeout(pending.timer);
+        this.send("boundary", "forget", question);
+        if (outcome?.success === true)
+            pending.resolve(outcome.result);
+        else if (outcome?.success === false && typeof outcome.error === "string")
+            pending.reject(new Error(outcome.error));
+        else
+            pending.reject(new Error("The boundary returned an invalid outcome"));
+    }
+}
+function failed(error) {
+    return {
+        success: false,
+        error: error instanceof Error ? error.message : "An unknown exception occurred"
+    };
+}
+function invoke(handler, values) {
+    Promise.resolve().then(() => handler(...values)).catch(error => {
+        queueMicrotask(() => { throw error; });
+    });
+}
+function once(cleanup) {
+    let active = true;
+    return () => {
+        if (!active)
+            return;
+        active = false;
+        cleanup();
+    };
+}
+export default new Wire();

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@phreshos/server",
+  "version": "0.1.0",
+  "description": "The SDK used by a Program's server endpoint.",
+  "type": "module",
+  "main": "dist/main.js",
+  "types": "dist/main.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/main.d.ts",
+      "default": "./dist/main.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "build": "tsc --noEmit false --outDir dist --rootDir source",
+    "prepack": "node --run build"
+  },
+  "peerDependencies": {
+    "@phreshos/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@phreshos/core": "0.1.0",
+    "@types/node": "^26.2.0",
+    "typescript": "^6.0.3"
+  }
+}