@crow-agent/server 0.0.0-stage → 0.2.0

package/dist/session-server.js

@@ -0,0 +1,678 @@
+import { RemoteServiceError, createServiceStateEncoder as makeStateEncoder, decodeServiceControlCall as decodeControl, parseServiceCall, parseServiceSubscriptionSnapshot as parseSnapshot, } from "@crow-agent/chord";
+import { BACKGROUND_CONTEXT, TODO_CONTEXT, withAbortSignal, } from "@crow-agent/agent-core";
+import { ClientMessageDecoder, DEFAULT_MAX_FRAME_LENGTH as PROTOCOL_FRAME_LIMIT, encodeServerMessage, isServerId, isSupportedProtocolVersion, PROTOCOL_VERSION, ProtocolValidationError, } from "@crow-agent/protocol";
+import { isTerminalConnection, } from "./server-connection.js";
+import { INTERNAL_SERVER_ERROR_MESSAGE as FALLBACK_ERROR_TEXT, ServerError, WrongServerError, } from "./server-errors.js";
+import { SessionRouter, } from "./session-routing.js";
+const HANDSHAKE_TIMEOUT_DEFAULT_MS = 5000;
+const UINT32_MAX = 0xffffffff;
+const TIMER_DELAY_MAX_MS = 2147483647;
+class ActiveSubscription {
+    subscriptionId;
+    #emit;
+    #queued = [];
+    #ready = false;
+    #installed = false;
+    constructor(subscriptionId, emit) {
+        this.subscriptionId = subscriptionId;
+        this.#emit = emit;
+    }
+    async publish(subscriptionId, update) {
+        const early = subscriptionId === this.subscriptionId && !this.#ready;
+        if (early) {
+            this.#queued.push({ update });
+            return;
+        }
+        await this.#emit(subscriptionId, update);
+    }
+    install(result, encoders) {
+        if (result === undefined) {
+            const missing = "Service subscription did not return a snapshot";
+            throw new ProtocolValidationError(missing);
+        }
+        const encoder = makeStateEncoder();
+        const encoded = encoder.encodeSnapshot(parseSnapshot(result));
+        encoders.set(this.subscriptionId, encoder);
+        this.#installed = true;
+        return encoded;
+    }
+    async drain() {
+        for (;;) {
+            const pending = this.#queued.shift();
+            if (pending === undefined)
+                break;
+            await this.#emit(this.subscriptionId, pending.update);
+        }
+        this.#ready = true;
+    }
+    rollback(encoders, responded) {
+        const stray = this.#installed && !responded;
+        if (stray)
+            encoders.delete(this.subscriptionId);
+    }
+}
+export class Server {
+    serverId;
+    /** Settles after shutdown; rejects if listener or routed-Session cleanup fails. */
+    closed;
+    #appHost;
+    #listeners;
+    #maxFrameLength;
+    #handshakeTimeoutMs;
+    #onConnectionCountChanged;
+    #onError;
+    #connections = new Set();
+    #router;
+    #draining = false;
+    #closeTask;
+    #closedDone = false;
+    #failClosed;
+    #finishClosed;
+    #startTask;
+    #isStarted = false;
+    constructor(host, options) {
+        const limits = checkOptions(options);
+        this.#appHost = host;
+        this.#listeners = options.listeners;
+        const { serverId } = options;
+        this.serverId = serverId;
+        this.#maxFrameLength = limits.maxFrameLength;
+        this.#handshakeTimeoutMs = limits.handshakeTimeoutMs;
+        this.#onConnectionCountChanged = options.onConnectionCountChanged;
+        this.#onError = options.onError;
+        this.#router = new SessionRouter({
+            host,
+            serverId: this.serverId,
+            isClosing: () => this.#draining,
+            publishAttachment: (client, attachment, context) => this.#transmit(client, {
+                type: "attachment",
+                attachment: attachment === undefined ? null : attachment,
+            }).then(() => undefined),
+            reportError: (error) => this.#noteError(error),
+        });
+        let resolveClosed;
+        let rejectClosed;
+        this.closed = new Promise((resolve, reject) => {
+            resolveClosed = resolve;
+            rejectClosed = reject;
+        });
+        this.#finishClosed = resolveClosed;
+        this.#failClosed = rejectClosed;
+        void this.closed.then(() => undefined, () => undefined);
+    }
+    start() {
+        if (this.#isStarted)
+            return Promise.reject(new Error("Server is already started"));
+        if (this.#startTask !== undefined)
+            return Promise.reject(new Error("Server is already starting"));
+        if (this.#draining)
+            return Promise.reject(new Error("Server is closing or closed"));
+        const task = this.#boot();
+        this.#startTask = task;
+        return task;
+    }
+    async #boot() {
+        const online = [];
+        try {
+            for (const listener of this.#listeners) {
+                const accept = (connection) => this.accept(connection);
+                await listener.start(accept);
+                online.push(listener);
+            }
+            this.#isStarted = true;
+            return this;
+        }
+        catch (error) {
+            this.#draining = true;
+            const failures = [];
+            const shutdowns = await Promise.allSettled(online.map((listener) => listener.close()));
+            for (const shutdown of shutdowns) {
+                if (shutdown.status === "rejected")
+                    failures.push(shutdown.reason);
+            }
+            try {
+                await this.#tearDown();
+            }
+            catch (cleanupError) {
+                failures.push(cleanupError);
+            }
+            if (failures.length > 0) {
+                const failure = new AggregateError([error, ...failures], "Server startup and cleanup failed");
+                this.#settleClosedPromise(failure);
+                throw failure;
+            }
+            this.#settleClosedPromise();
+            throw error;
+        }
+        finally {
+            this.#startTask = undefined;
+        }
+    }
+    accept(connection) {
+        if (this.#draining) {
+            void this.#terminate(connection);
+            const inert = {
+                onData: () => { },
+                onClose: () => { },
+                onError: (error) => this.#noteError(error),
+            };
+            return inert;
+        }
+        const state = this.#newConnectionState(connection);
+        this.#connections.add(state);
+        this.#emitCountChanged();
+        return {
+            onData: (chunk) => this.#ingest(state, chunk),
+            onClose: () => this.#noteTransportClosed(state),
+            onError: (error) => {
+                this.#noteError(error);
+                void this.#terminate(connection).then(() => this.#drop(state));
+            },
+        };
+    }
+    #newConnectionState(connection) {
+        let state;
+        const onTimeout = () => {
+            const error = { code: "invalid_request", message: "Handshake timeout" };
+            void this.#abortWithProtocolError(state, error);
+        };
+        const timer = setTimeout(onTimeout, this.#handshakeTimeoutMs);
+        timer.unref();
+        const encoders = new Map();
+        const activeRequests = new Map();
+        state = {
+            connection,
+            decoder: new ClientMessageDecoder({ maxFrameLength: this.#maxFrameLength }),
+            serviceStateEncoders: encoders,
+            stage: "awaitingHello",
+            disconnected: false,
+            handshakeTimeout: timer,
+            activeRequests,
+        };
+        return state;
+    }
+    #clearHandshakeTimeout(state) {
+        clearTimeout(state.handshakeTimeout);
+    }
+    #beginClosing(state) {
+        state.stage = "closing";
+        this.#clearHandshakeTimeout(state);
+    }
+    async close() {
+        const existing = this.#closeTask;
+        if (existing !== undefined)
+            return existing;
+        this.#draining = true;
+        const task = this.#closeInternal();
+        this.#closeTask = task;
+        return task;
+    }
+    async #closeInternal() {
+        const starting = this.#startTask;
+        if (starting !== undefined)
+            await starting.catch(() => { });
+        const failures = [];
+        const shutdowns = await Promise.allSettled(this.#listeners.map((listener) => listener.close()));
+        for (const shutdown of shutdowns) {
+            if (shutdown.status === "rejected")
+                failures.push(shutdown.reason);
+        }
+        try {
+            await this.#tearDown();
+        }
+        catch (error) {
+            failures.push(error);
+        }
+        this.#isStarted = false;
+        if (failures.length === 0) {
+            this.#settleClosedPromise();
+            return;
+        }
+        const [only] = failures;
+        const failure = failures.length === 1 && only instanceof Error
+            ? only
+            : new AggregateError(failures, "Server shutdown failed");
+        this.#settleClosedPromise(failure);
+        throw failure;
+    }
+    #ingest(state, chunk) {
+        const terminal = isTerminalConnection(state);
+        if (terminal)
+            return;
+        let messages;
+        try {
+            const decoded = state.decoder.push(chunk);
+            messages = decoded;
+        }
+        catch (error) {
+            void this.#abortWithProtocolError(state, this.#asProtocolError(error));
+        }
+        if (messages === undefined)
+            return;
+        for (const message of messages) {
+            const done = isTerminalConnection(state);
+            if (done)
+                return;
+            this.#routeMessage(state, message);
+        }
+    }
+    #routeMessage(state, message) {
+        const awaitingHello = state.stage === "awaitingHello";
+        if (awaitingHello) {
+            this.#routeHello(state, message);
+            return;
+        }
+        const repeatedHello = message.type === "hello";
+        if (repeatedHello) {
+            const error = {
+                code: "invalid_request",
+                message: "hello is only valid as the first message",
+            };
+            void this.#abortWithProtocolError(state, error);
+            return;
+        }
+        const ready = state.stage === "ready";
+        if (ready) {
+            this.#routeReadyMessage(state, message);
+            return;
+        }
+        const handshaking = state.stage === "handshaking";
+        if (!handshaking)
+            return;
+        const { handshake } = state;
+        if (handshake === undefined)
+            return;
+        void handshake.then(() => {
+            const settled = state.stage === "ready" && !state.disconnected;
+            if (settled)
+                this.#routeReadyMessage(state, message);
+        });
+    }
+    #routeHello(state, message) {
+        const isHello = message.type === "hello";
+        if (!isHello) {
+            const error = {
+                code: "invalid_request",
+                message: "the first client message must be a hello",
+            };
+            void this.#abortWithProtocolError(state, error);
+            return;
+        }
+        state.stage = "handshaking";
+        const completed = this.#completeHandshake(state, message);
+        state.handshake = completed.catch((error) => this.#abortWithProtocolError(state, this.#asProtocolError(error)));
+    }
+    #routeReadyMessage(state, message) {
+        if (message.type === "cancel") {
+            this.#applyCancel(state, message);
+            return;
+        }
+        // The caller excluded hello; only a request envelope remains.
+        void this.#serveRequest(state, message);
+    }
+    async #completeHandshake(state, hello) {
+        const supported = isSupportedProtocolVersion(hello.version);
+        if (!supported) {
+            const detail = `Unsupported protocol version ${hello.version}; expected ${PROTOCOL_VERSION}`;
+            await this.#abortWithProtocolError(state, {
+                code: "version",
+                message: detail,
+            });
+            return;
+        }
+        const viable = !this.#draining && !state.disconnected && state.stage === "handshaking" && !state.connection.closed;
+        if (!viable)
+            return;
+        const presentation = {
+            attachSession: (sessionId, context) => this.#router.attachClient(state, sessionId, context),
+            detachSession: (context) => this.#router.detachClient(state, context),
+            prepareSessionRemoval: (sessionId, context) => this.#router.removeSession(sessionId, context),
+        };
+        const services = await this.#appHost.serverServices.attachClient(presentation, TODO_CONTEXT);
+        const stillViable = !this.#draining && !state.disconnected && state.stage === "handshaking" && !state.connection.closed;
+        if (!stillViable) {
+            const context = TODO_CONTEXT;
+            await services.release(context);
+            return;
+        }
+        state.serverServices = services;
+        const greeting = {
+            type: "hello",
+            version: PROTOCOL_VERSION,
+            serverId: this.serverId,
+        };
+        const sent = await this.#transmit(state, greeting);
+        const ready = sent && !state.disconnected && state.stage === "handshaking";
+        if (ready) {
+            state.stage = "ready";
+            this.#clearHandshakeTimeout(state);
+        }
+    }
+    #applyCancel(state, envelope) {
+        const { id, target } = envelope;
+        const addressedHere = target.serverId === this.serverId;
+        if (!addressedHere)
+            return;
+        const active = state.activeRequests.get(id);
+        const matches = active !== undefined && sameTarget(active.target, target);
+        if (matches) {
+            const reason = new DOMException("RPC request cancelled", "AbortError");
+            active.controller.abort(reason);
+        }
+    }
+    async #serveRequest(state, envelope) {
+        const id = envelope.id;
+        const duplicate = state.activeRequests.has(id);
+        if (duplicate) {
+            const error = { code: "invalid_request", message: "Request ID is already active" };
+            await this.#respondError(state, id, error);
+            return;
+        }
+        const call = this.#parseCall(state, envelope);
+        if (call === undefined)
+            return;
+        const controller = new AbortController();
+        const target = envelope.target;
+        const active = { controller, target };
+        state.activeRequests.set(id, active);
+        const signal = controller.signal;
+        const context = withAbortSignal(signal, TODO_CONTEXT);
+        const control = decodeControl(call);
+        const subscription = control?.type === "subscribe"
+            ? new ActiveSubscription(control.subscriptionId, (subscriptionId, update) => this.#publishUpdate(state, subscriptionId, update))
+            : undefined;
+        const publish = async (subscriptionId, update) => {
+            if (subscription === undefined) {
+                await this.#publishUpdate(state, subscriptionId, update);
+                return;
+            }
+            await subscription.publish(subscriptionId, update);
+        };
+        let responded = false;
+        try {
+            await this.#invokeRouted(state, envelope, call, control, subscription, publish, context);
+            responded = true;
+            if (subscription !== undefined)
+                await subscription.drain();
+        }
+        catch (error) {
+            subscription?.rollback(state.serviceStateEncoders, responded);
+            const afterResponse = responded;
+            if (afterResponse) {
+                this.#noteError(error);
+                await this.#terminate(state.connection);
+                this.#drop(state);
+                return;
+            }
+            const cancelled = controller.signal.aborted;
+            const failure = cancelled
+                ? { code: "cancelled", message: "RPC request cancelled" }
+                : this.#asProtocolError(error);
+            await this.#respondError(state, id, failure);
+        }
+        finally {
+            const current = state.activeRequests.get(id);
+            if (current === active)
+                state.activeRequests.delete(id);
+        }
+    }
+    #parseCall(state, envelope) {
+        try {
+            return parseServiceCall(envelope.call);
+        }
+        catch {
+            const error = { code: "invalid_request", message: "Invalid service call" };
+            void this.#respondError(state, envelope.id, error);
+            return undefined;
+        }
+    }
+    async #respondError(state, id, error) {
+        await this.#transmit(state, {
+            type: "response",
+            id,
+            ok: false,
+            error,
+        });
+    }
+    async #invokeRouted(state, envelope, call, control, subscription, publish, context) {
+        const addressedHere = envelope.target.serverId === this.serverId;
+        if (!addressedHere)
+            throw new WrongServerError();
+        const duplicateSubscription = subscription !== undefined && state.serviceStateEncoders.has(subscription.subscriptionId);
+        if (duplicateSubscription) {
+            throw new ProtocolValidationError(`Duplicate service subscription ${subscription.subscriptionId}`);
+        }
+        let result = undefined;
+        const sessionTarget = "sessionId" in envelope.target;
+        if (sessionTarget) {
+            result = await this.#router.executeServiceCall(call, envelope.target, state, publish, context);
+        }
+        else {
+            const services = state.serverServices;
+            if (services === undefined) {
+                const unknown = `Unknown service member ${call.serviceId}.${call.member}`;
+                throw new ProtocolValidationError(unknown);
+            }
+            result = await services.invokeService(call, publish, context);
+        }
+        if (subscription !== undefined) {
+            result = subscription.install(result, state.serviceStateEncoders);
+        }
+        else if (control?.type === "unsubscribe") {
+            const { subscriptionId } = control;
+            state.serviceStateEncoders.delete(subscriptionId);
+        }
+        let response;
+        if (result === undefined) {
+            response = { type: "response", id: envelope.id, ok: true };
+        }
+        else {
+            response = { type: "response", id: envelope.id, ok: true, result };
+        }
+        await this.#transmit(state, response);
+    }
+    #noteTransportClosed(connection) {
+        const orderly = connection.disconnected || connection.stage === "closing";
+        if (!orderly) {
+            try {
+                const { decoder } = connection;
+                decoder.end();
+            }
+            catch (error) {
+                this.#noteError(error);
+            }
+        }
+        this.#drop(connection);
+    }
+    #drop(connection) {
+        const dropped = connection.disconnected;
+        if (dropped)
+            return;
+        connection.disconnected = true;
+        connection.stage = "closed";
+        this.#clearHandshakeTimeout(connection);
+        for (const active of connection.activeRequests.values()) {
+            active.controller.abort(new Error("Client disconnected"));
+        }
+        connection.activeRequests.clear();
+        connection.serviceStateEncoders.clear();
+        const removed = this.#connections.delete(connection);
+        if (removed)
+            this.#emitCountChanged();
+        const { serverServices } = connection;
+        delete connection.serverServices;
+        const releases = [this.#router.disconnect(connection, TODO_CONTEXT)];
+        if (serverServices !== undefined)
+            releases.push(Promise.resolve(serverServices.release(TODO_CONTEXT)));
+        const cleanup = Promise.allSettled(releases);
+        void cleanup.then((results) => {
+            for (const result of results) {
+                if (result.status === "rejected")
+                    this.#noteError(result.reason);
+            }
+        });
+    }
+    async #publishUpdate(connection, subscriptionId, update) {
+        const encoders = connection.serviceStateEncoders;
+        const stateEncoder = encoders.get(subscriptionId);
+        const missing = stateEncoder === undefined;
+        if (missing)
+            return;
+        const encoded = stateEncoder.encodeUpdate(update);
+        await this.#transmit(connection, {
+            type: "service_update",
+            subscriptionId,
+            update: encoded,
+        });
+    }
+    async #transmit(connection, message) {
+        const writable = !connection.disconnected && !connection.connection.closed;
+        if (!writable)
+            return false;
+        const frame = this.#encodeFrame(connection, message);
+        if (frame === undefined)
+            return false;
+        try {
+            const transport = connection.connection;
+            await transport.send(frame);
+            return true;
+        }
+        catch (error) {
+            this.#noteError(error);
+            await this.#terminate(connection.connection);
+            this.#drop(connection);
+            return false;
+        }
+    }
+    #encodeFrame(connection, message) {
+        try {
+            return encodeServerMessage(message, { maxFrameLength: this.#maxFrameLength });
+        }
+        catch (error) {
+            this.#noteError(error);
+            void this.#terminate(connection.connection).then(() => this.#drop(connection));
+            return undefined;
+        }
+    }
+    async #abortWithProtocolError(connection, error) {
+        const terminal = connection.disconnected || connection.stage === "closing" || connection.stage === "closed";
+        if (terminal)
+            return;
+        this.#beginClosing(connection);
+        const message = { type: "hello_error", error };
+        let finalFrame;
+        try {
+            finalFrame = encodeServerMessage(message, { maxFrameLength: this.#maxFrameLength });
+        }
+        catch (encodeError) {
+            this.#noteError(encodeError);
+        }
+        await this.#terminate(connection.connection, finalFrame);
+        this.#drop(connection);
+    }
+    async #tearDown() {
+        const connections = [...this.#connections];
+        for (const connection of connections)
+            this.#beginClosing(connection);
+        const shutdowns = connections.map((connection) => this.#terminate(connection.connection));
+        await Promise.all(shutdowns);
+        for (const connection of connections)
+            this.#drop(connection);
+        const cleanup = await Promise.allSettled([this.#router.close(BACKGROUND_CONTEXT)]);
+        this.#connections.clear();
+        throwTearDownErrors(cleanup);
+    }
+    async #terminate(connection, finalChunk) {
+        const closing = connection.close(finalChunk);
+        try {
+            await closing;
+        }
+        catch (error) {
+            this.#noteError(error);
+        }
+    }
+    #asProtocolError(error) {
+        const serviceError = error instanceof ServerError || error instanceof RemoteServiceError;
+        if (serviceError) {
+            const typed = error;
+            return { code: typed.code, message: typed.message };
+        }
+        const invalid = error instanceof ProtocolValidationError;
+        if (invalid) {
+            const message = error.message;
+            return { code: "invalid_request", message };
+        }
+        this.#noteError(error);
+        return { code: "internal_error", message: FALLBACK_ERROR_TEXT };
+    }
+    #emitCountChanged() {
+        try {
+            this.#onConnectionCountChanged?.(this.#connections.size);
+        }
+        catch (error) {
+            this.#noteError(error);
+        }
+    }
+    #noteError(error) {
+        const normalized = error instanceof Error ? error : new Error(String(error));
+        try {
+            this.#onError?.(normalized);
+        }
+        catch {
+            // Observer failures stay local; server state is unaffected.
+        }
+    }
+    #settleClosedPromise(error) {
+        if (this.#closedDone)
+            return;
+        this.#closedDone = true;
+        if (error === undefined)
+            this.#finishClosed();
+        else
+            this.#failClosed(error);
+    }
+}
+function sameTarget(left, right) {
+    const sameServer = left.serverId === right.serverId;
+    if (!sameServer)
+        return false;
+    const leftSession = "sessionId" in left;
+    const rightSession = "sessionId" in right;
+    if (!leftSession || !rightSession)
+        return leftSession === rightSession;
+    return left.sessionId === right.sessionId && left.attachmentId === right.attachmentId;
+}
+function checkOptions(options) {
+    const listenersValid = Array.isArray(options.listeners);
+    if (!listenersValid)
+        throw new TypeError("Server listeners must be an array");
+    const validId = isServerId(options.serverId);
+    if (!validId) {
+        throw new TypeError("serverId must be a canonical lowercase UUIDv4");
+    }
+    const maxFrameLength = options.maxFrameLength ?? PROTOCOL_FRAME_LIMIT;
+    const frameLimitValid = Number.isSafeInteger(maxFrameLength) && maxFrameLength > 0 && maxFrameLength <= UINT32_MAX;
+    if (!frameLimitValid) {
+        throw new TypeError(`Server maxFrameLength must be an integer between 1 and ${UINT32_MAX}`);
+    }
+    const handshakeTimeoutMs = options.handshakeTimeoutMs ?? HANDSHAKE_TIMEOUT_DEFAULT_MS;
+    const timeoutValid = Number.isSafeInteger(handshakeTimeoutMs) && handshakeTimeoutMs > 0 && handshakeTimeoutMs <= TIMER_DELAY_MAX_MS;
+    if (!timeoutValid) {
+        throw new TypeError(`Server handshakeTimeoutMs must be an integer between 1 and ${TIMER_DELAY_MAX_MS}`);
+    }
+    const limits = { maxFrameLength, handshakeTimeoutMs };
+    return limits;
+}
+function throwTearDownErrors(cleanup) {
+    const failures = [];
+    for (const result of cleanup) {
+        if (result.status === "rejected")
+            failures.push(result.reason);
+    }
+    if (failures.length === 1)
+        throw failures[0];
+    if (failures.length > 1) {
+        throw new AggregateError(failures, "Failed to close server Sessions");
+    }
+}
+//# sourceMappingURL=session-server.js.map