@earendil-works/pi-server 0.84.4 → 0.85.0

package/dist/server.js

@@ -1,61 +1,65 @@
-import { randomUUID } from "node:crypto";
-import { ClientMessageDecoder, DEFAULT_MAX_FRAME_LENGTH, encodeServerMessage, isSupportedProtocolVersion, PROTOCOL_VERSION, ProtocolValidationError, } from "@earendil-works/pi-protocol";
+import { createServiceStateEncoder, decodeServiceControlCall, parseServiceCall, parseServiceSubscriptionSnapshot, RemoteServiceError, } from "@earendil-works/chord";
+import { BACKGROUND_CONTEXT, TODO_CONTEXT, withAbortSignal } from "@earendil-works/pi-agent-core";
+import { ClientMessageDecoder, DEFAULT_MAX_FRAME_LENGTH, encodeServerMessage, isServerId, isSupportedProtocolVersion, PROTOCOL_VERSION, ProtocolValidationError, } from "@earendil-works/pi-protocol";
 import { isTerminalConnection, } from "./connection.js";
-import { INTERNAL_SERVER_ERROR_MESSAGE, InternalServerError, NOT_IMPLEMENTED_MESSAGE, PiServerError, } from "./errors.js";
-import { LiveSessionManager } from "./sessions.js";
-import { ServerSnapshotPublisher } from "./snapshots.js";
+import { INTERNAL_SERVER_ERROR_MESSAGE, ServerError, WrongServerError } from "./errors.js";
+import { SessionRouter } from "./session-router.js";
 const DEFAULT_HANDSHAKE_TIMEOUT_MS = 5_000;
 const MAX_UINT32 = 0xffff_ffff;
 const MAX_TIMER_DELAY_MS = 2_147_483_647;
-export class PiServer {
-    id;
+export class Server {
+    serverId;
+    /** Resolves after shutdown, or rejects when listener or routed-Session cleanup fails. */
+    closed;
+    host;
     listeners;
     maxFrameLength;
     handshakeTimeoutMs;
+    onConnectionCountChanged;
     onError;
     connections = new Set();
     sessions;
-    snapshots;
     closing = false;
     closePromise;
+    closedSettled = false;
+    rejectClosed;
+    resolveClosed;
     startPromise;
     started = false;
-    constructor(service, options) {
+    constructor(host, options) {
         const resolved = resolveOptions(options);
+        this.host = host;
         this.listeners = options.listeners;
-        this.id = options.serverId ?? randomUUID();
+        this.serverId = options.serverId;
         this.maxFrameLength = resolved.maxFrameLength;
         this.handshakeTimeoutMs = resolved.handshakeTimeoutMs;
+        this.onConnectionCountChanged = options.onConnectionCountChanged;
         this.onError = options.onError;
-        this.sessions = new LiveSessionManager({
-            service,
+        this.sessions = new SessionRouter({
+            host,
+            serverId: this.serverId,
             isClosing: () => this.closing,
-            sendMessage: (connection, message) => this.sendMessage(connection, message),
-            closeConnection: (connection) => this.closeConnection(connection),
-            disconnect: (connection) => this.disconnect(connection),
-            broadcastServerSnapshot: () => void this.snapshots.broadcast(),
+            publishAttachment: async (client, attachment) => {
+                await this.sendMessage(client, {
+                    type: "attachment",
+                    attachment: attachment ?? null,
+                });
+            },
             reportError: (error) => this.reportError(error),
         });
-        this.snapshots = new ServerSnapshotPublisher({
-            serverId: this.id,
-            service,
-            connections: this.connections,
-            isClosing: () => this.closing,
-            listSessions: () => this.sessions.listMetadata(),
-            sendMessage: (connection, message) => this.sendMessage(connection, message),
-            reportError: (error) => this.reportError(error),
+        this.closed = new Promise((resolve, reject) => {
+            this.resolveClosed = resolve;
+            this.rejectClosed = reject;
         });
-    }
-    get addresses() {
-        return this.listeners.flatMap((listener) => (listener.address === undefined ? [] : [listener.address]));
+        void this.closed.catch(() => { });
     }
     start() {
         if (this.started)
-            return Promise.reject(new Error("PiServer is already started"));
+            return Promise.reject(new Error("Server is already started"));
         if (this.startPromise)
-            return Promise.reject(new Error("PiServer is already starting"));
+            return Promise.reject(new Error("Server is already starting"));
         if (this.closing)
-            return Promise.reject(new Error("PiServer is closing or closed"));
+            return Promise.reject(new Error("Server is closing or closed"));
         this.startPromise = this.startInternal();
         return this.startPromise;
     }
@@ -71,8 +75,24 @@ export class PiServer {
         }
         catch (error) {
             this.closing = true;
-            await Promise.allSettled(started.map((listener) => listener.close()));
-            await this.closeServerState();
+            const cleanupErrors = [];
+            const listenerResults = await Promise.allSettled(started.map((listener) => listener.close()));
+            for (const result of listenerResults) {
+                if (result.status === "rejected")
+                    cleanupErrors.push(result.reason);
+            }
+            try {
+                await this.closeServerState();
+            }
+            catch (cleanupError) {
+                cleanupErrors.push(cleanupError);
+            }
+            if (cleanupErrors.length > 0) {
+                const failure = new AggregateError([error, ...cleanupErrors], "Server startup and cleanup failed");
+                this.settleClosed(failure);
+                throw failure;
+            }
+            this.settleClosed();
             throw error;
         }
         finally {
@@ -97,16 +117,16 @@ export class PiServer {
         }, this.handshakeTimeoutMs);
         handshakeTimeout.unref();
         state = {
-            id: randomUUID(),
             connection,
             decoder: new ClientMessageDecoder({ maxFrameLength: this.maxFrameLength }),
-            sessionIds: new Set(),
+            serviceStateEncoders: new Map(),
             stage: "awaitingHello",
             disconnected: false,
-            handshakeComplete: false,
             handshakeTimeout,
+            activeRequests: new Map(),
         };
         this.connections.add(state);
+        this.notifyConnectionCountChanged();
         return {
             onData: (chunk) => this.receive(state, chunk),
             onClose: () => this.transportClosed(state),
@@ -127,13 +147,27 @@ export class PiServer {
         const starting = this.startPromise;
         if (starting)
             await starting.catch(() => { });
-        try {
-            await Promise.all(this.listeners.map((listener) => listener.close()));
+        const errors = [];
+        const listenerResults = await Promise.allSettled(this.listeners.map((listener) => listener.close()));
+        for (const result of listenerResults) {
+            if (result.status === "rejected")
+                errors.push(result.reason);
         }
-        finally {
+        try {
             await this.closeServerState();
-            this.started = false;
         }
+        catch (error) {
+            errors.push(error);
+        }
+        this.started = false;
+        if (errors.length > 0) {
+            const failure = errors.length === 1 && errors[0] instanceof Error
+                ? errors[0]
+                : new AggregateError(errors, "Server shutdown failed");
+            this.settleClosed(failure);
+            throw failure;
+        }
+        this.settleClosed();
     }
     receive(state, chunk) {
         if (isTerminalConnection(state))
@@ -173,7 +207,10 @@ export class PiServer {
             return;
         }
         if (state.stage === "ready") {
-            void this.handleRequest(state, message);
+            if (message.type === "cancel")
+                this.handleCancel(state, message);
+            else
+                void this.handleRequest(state, message);
             return;
         }
         if (state.stage !== "handshaking")
@@ -182,7 +219,11 @@ export class PiServer {
         if (!handshake)
             return;
         void handshake.then(() => {
-            if (state.stage === "ready" && !state.disconnected)
+            if (state.stage !== "ready" || state.disconnected)
+                return;
+            if (message.type === "cancel")
+                this.handleCancel(state, message);
+            else
                 void this.handleRequest(state, message);
         });
     }
@@ -194,45 +235,141 @@ export class PiServer {
             });
             return;
         }
-        const snapshot = await this.snapshots.get();
         if (this.closing || state.disconnected || state.stage !== "handshaking" || state.connection.closed)
             return;
+        const services = await this.host.serverServices.attachClient({
+            attachSession: async (sessionId, context) => {
+                await this.sessions.attachClient(state, sessionId, context);
+            },
+            detachSession: (context) => this.sessions.detachClient(state, context),
+            prepareSessionRemoval: (sessionId, context) => this.sessions.removeSession(sessionId, context),
+        }, TODO_CONTEXT);
+        if (this.closing || state.disconnected || state.stage !== "handshaking" || state.connection.closed) {
+            await services.release(TODO_CONTEXT);
+            return;
+        }
+        state.serverServices = services;
         const sent = await this.sendMessage(state, {
             type: "hello",
             version: PROTOCOL_VERSION,
-            connectionId: state.id,
-            snapshot,
+            serverId: this.serverId,
         });
         if (sent && !state.disconnected && state.stage === "handshaking") {
-            state.handshakeComplete = true;
             state.stage = "ready";
             clearTimeout(state.handshakeTimeout);
-            if (snapshot.revision !== this.snapshots.currentRevision) {
-                const current = await this.snapshots.get();
-                await this.sendMessage(state, {
-                    type: "event",
-                    event: { type: "server_snapshot", snapshot: current },
-                });
-            }
+        }
+    }
+    handleCancel(state, envelope) {
+        if (envelope.target.serverId !== this.serverId)
+            return;
+        const active = state.activeRequests.get(envelope.id);
+        if (active !== undefined && sameTarget(active.target, envelope.target)) {
+            active.controller.abort(new DOMException("RPC request cancelled", "AbortError"));
         }
     }
     async handleRequest(state, envelope) {
-        try {
-            const result = await this.sessions.executeCommand(state, envelope.request);
+        if (state.activeRequests.has(envelope.id)) {
             await this.sendMessage(state, {
                 type: "response",
                 id: envelope.id,
-                ok: true,
-                result,
+                ok: false,
+                error: { code: "invalid_request", message: "Request ID is already active" },
             });
+            return;
         }
-        catch (error) {
+        let call;
+        try {
+            call = parseServiceCall(envelope.call);
+        }
+        catch {
             await this.sendMessage(state, {
                 type: "response",
                 id: envelope.id,
                 ok: false,
-                error: this.toProtocolError(error),
+                error: { code: "invalid_request", message: "Invalid service call" },
             });
+            return;
+        }
+        const controller = new AbortController();
+        const active = { controller, target: envelope.target };
+        state.activeRequests.set(envelope.id, active);
+        const context = withAbortSignal(controller.signal, TODO_CONTEXT);
+        const control = decodeServiceControlCall(call);
+        const subscribing = control?.type === "subscribe" ? control : undefined;
+        const pendingUpdates = [];
+        let subscriptionReady = subscribing === undefined;
+        let installedSubscriptionEncoder = false;
+        let responded = false;
+        const publish = async (subscriptionId, update) => {
+            if (subscribing !== undefined && subscriptionId === subscribing.subscriptionId && !subscriptionReady) {
+                pendingUpdates.push({ update });
+                return;
+            }
+            await this.sendServiceUpdate(state, subscriptionId, update);
+        };
+        try {
+            if (envelope.target.serverId !== this.serverId)
+                throw new WrongServerError();
+            if (subscribing !== undefined && state.serviceStateEncoders.has(subscribing.subscriptionId)) {
+                throw new ProtocolValidationError(`Duplicate service subscription ${subscribing.subscriptionId}`);
+            }
+            let result;
+            if ("sessionId" in envelope.target) {
+                result = await this.sessions.executeServiceCall(call, envelope.target, state, publish, context);
+            }
+            else if (state.serverServices !== undefined) {
+                result = await state.serverServices.invokeService(call, publish, context);
+            }
+            else {
+                throw new ProtocolValidationError(`Unknown service member ${call.serviceId}.${call.member}`);
+            }
+            if (subscribing !== undefined) {
+                if (result === undefined)
+                    throw new ProtocolValidationError("Service subscription did not return a snapshot");
+                const stateEncoder = createServiceStateEncoder();
+                result = stateEncoder.encodeSnapshot(parseServiceSubscriptionSnapshot(result));
+                state.serviceStateEncoders.set(subscribing.subscriptionId, stateEncoder);
+                installedSubscriptionEncoder = true;
+            }
+            else if (control?.type === "unsubscribe") {
+                state.serviceStateEncoders.delete(control.subscriptionId);
+            }
+            await this.sendMessage(state, result === undefined
+                ? { type: "response", id: envelope.id, ok: true }
+                : { type: "response", id: envelope.id, ok: true, result });
+            responded = true;
+            if (subscribing !== undefined) {
+                while (pendingUpdates.length > 0) {
+                    const pending = pendingUpdates.shift();
+                    if (pending !== undefined)
+                        await this.sendServiceUpdate(state, subscribing.subscriptionId, pending.update);
+                }
+                subscriptionReady = true;
+            }
+        }
+        catch (error) {
+            if (subscribing !== undefined && installedSubscriptionEncoder && !responded) {
+                state.serviceStateEncoders.delete(subscribing.subscriptionId);
+            }
+            if (responded) {
+                this.reportError(error);
+                await this.closeConnection(state.connection);
+                this.disconnect(state);
+            }
+            else {
+                await this.sendMessage(state, {
+                    type: "response",
+                    id: envelope.id,
+                    ok: false,
+                    error: controller.signal.aborted
+                        ? { code: "cancelled", message: "RPC request cancelled" }
+                        : this.toProtocolError(error),
+                });
+            }
+        }
+        finally {
+            if (state.activeRequests.get(envelope.id) === active)
+                state.activeRequests.delete(envelope.id);
         }
     }
     transportClosed(connection) {
@@ -244,19 +381,41 @@ export class PiServer {
                 this.reportError(error);
             }
         }
-        void this.disconnect(connection);
+        this.disconnect(connection);
     }
-    async disconnect(connection) {
+    disconnect(connection) {
         if (connection.disconnected)
             return;
-        const handshakeComplete = connection.handshakeComplete;
         connection.disconnected = true;
         connection.stage = "closed";
         clearTimeout(connection.handshakeTimeout);
-        this.connections.delete(connection);
-        await this.sessions.disconnect(connection);
-        if (!this.closing && handshakeComplete)
-            void this.snapshots.broadcast();
+        for (const { controller } of connection.activeRequests.values()) {
+            controller.abort(new Error("Client disconnected"));
+        }
+        connection.activeRequests.clear();
+        connection.serviceStateEncoders.clear();
+        if (this.connections.delete(connection))
+            this.notifyConnectionCountChanged();
+        const serverServices = connection.serverServices;
+        delete connection.serverServices;
+        void Promise.allSettled([
+            this.sessions.disconnect(connection, TODO_CONTEXT),
+            serverServices?.release(TODO_CONTEXT),
+        ]).then((results) => {
+            for (const result of results)
+                if (result.status === "rejected")
+                    this.reportError(result.reason);
+        });
+    }
+    async sendServiceUpdate(connection, subscriptionId, update) {
+        const stateEncoder = connection.serviceStateEncoders.get(subscriptionId);
+        if (stateEncoder === undefined)
+            return;
+        await this.sendMessage(connection, {
+            type: "service_update",
+            subscriptionId,
+            update: stateEncoder.encodeUpdate(update),
+        });
     }
     async sendMessage(connection, message) {
         if (connection.disconnected || connection.connection.closed)
@@ -268,7 +427,7 @@ export class PiServer {
         catch (error) {
             this.reportError(error);
             await this.closeConnection(connection.connection);
-            await this.disconnect(connection);
+            this.disconnect(connection);
             return false;
         }
         try {
@@ -278,7 +437,7 @@ export class PiServer {
         catch (error) {
             this.reportError(error);
             await this.closeConnection(connection.connection);
-            await this.disconnect(connection);
+            this.disconnect(connection);
             return false;
         }
     }
@@ -296,7 +455,7 @@ export class PiServer {
             this.reportError(encodeError);
         }
         await this.closeConnection(connection.connection, finalFrame);
-        await this.disconnect(connection);
+        this.disconnect(connection);
     }
     async closeServerState() {
         const connections = [...this.connections];
@@ -305,9 +464,15 @@ export class PiServer {
             clearTimeout(connection.handshakeTimeout);
         }
         await Promise.all(connections.map((connection) => this.closeConnection(connection.connection)));
-        await Promise.all(connections.map((connection) => this.disconnect(connection)));
-        await this.sessions.close();
+        for (const connection of connections)
+            this.disconnect(connection);
+        const cleanup = await Promise.allSettled([this.sessions.close(BACKGROUND_CONTEXT)]);
         this.connections.clear();
+        const errors = cleanup.flatMap((result) => (result.status === "rejected" ? [result.reason] : []));
+        if (errors.length === 1)
+            throw errors[0];
+        if (errors.length > 1)
+            throw new AggregateError(errors, "Failed to close server Sessions");
     }
     async closeConnection(connection, finalChunk) {
         try {
@@ -318,17 +483,8 @@ export class PiServer {
         }
     }
     toProtocolError(error) {
-        if (error instanceof InternalServerError) {
-            this.reportError(error.cause);
-            return { code: "internal_error", message: INTERNAL_SERVER_ERROR_MESSAGE };
-        }
-        if (error instanceof PiServerError) {
-            if (error.code === "not_implemented") {
-                return { code: "not_implemented", message: NOT_IMPLEMENTED_MESSAGE };
-            }
-            return error.details === undefined
-                ? { code: error.code, message: error.message }
-                : { code: error.code, message: error.message, details: error.details };
+        if (error instanceof ServerError || error instanceof RemoteServiceError) {
+            return { code: error.code, message: error.message };
         }
         if (error instanceof ProtocolValidationError) {
             return { code: "invalid_request", message: error.message };
@@ -336,6 +492,14 @@ export class PiServer {
         this.reportError(error);
         return { code: "internal_error", message: INTERNAL_SERVER_ERROR_MESSAGE };
     }
+    notifyConnectionCountChanged() {
+        try {
+            this.onConnectionCountChanged?.(this.connections.size);
+        }
+        catch (error) {
+            this.reportError(error);
+        }
+    }
     reportError(error) {
         try {
             this.onError?.(error instanceof Error ? error : new Error(String(error)));
@@ -344,21 +508,39 @@ export class PiServer {
             // Error observers cannot affect server state.
         }
     }
+    settleClosed(error) {
+        if (this.closedSettled)
+            return;
+        this.closedSettled = true;
+        if (error === undefined)
+            this.resolveClosed();
+        else
+            this.rejectClosed(error);
+    }
+}
+function sameTarget(left, right) {
+    if (left.serverId !== right.serverId)
+        return false;
+    if (!("sessionId" in left) || !("sessionId" in right)) {
+        return !("sessionId" in left) && !("sessionId" in right);
+    }
+    return left.sessionId === right.sessionId && left.attachmentId === right.attachmentId;
 }
 function resolveOptions(options) {
     if (!Array.isArray(options.listeners))
-        throw new TypeError("PiServer listeners must be an array");
-    if (options.serverId === "")
-        throw new TypeError("PiServer serverId must not be empty");
+        throw new TypeError("Server listeners must be an array");
+    if (!isServerId(options.serverId)) {
+        throw new TypeError("serverId must be a canonical lowercase UUIDv4");
+    }
     const maxFrameLength = options.maxFrameLength ?? DEFAULT_MAX_FRAME_LENGTH;
     if (!Number.isSafeInteger(maxFrameLength) || maxFrameLength <= 0 || maxFrameLength > MAX_UINT32) {
-        throw new TypeError(`PiServer maxFrameLength must be an integer between 1 and ${MAX_UINT32}`);
+        throw new TypeError(`Server maxFrameLength must be an integer between 1 and ${MAX_UINT32}`);
     }
     const handshakeTimeoutMs = options.handshakeTimeoutMs ?? DEFAULT_HANDSHAKE_TIMEOUT_MS;
     if (!Number.isSafeInteger(handshakeTimeoutMs) ||
         handshakeTimeoutMs <= 0 ||
         handshakeTimeoutMs > MAX_TIMER_DELAY_MS) {
-        throw new TypeError(`PiServer handshakeTimeoutMs must be an integer between 1 and ${MAX_TIMER_DELAY_MS}`);
+        throw new TypeError(`Server handshakeTimeoutMs must be an integer between 1 and ${MAX_TIMER_DELAY_MS}`);
     }
     return { maxFrameLength, handshakeTimeoutMs };
 }