@earendil-works/pi-client 0.84.4 → 0.85.0

package/dist/client.js

@@ -1,32 +1,34 @@
-import { encodeClientMessage, ProtocolValidationError, } from "@earendil-works/pi-protocol";
+import { createServiceCatalogueCall, createServiceStateDecoder, createServiceSubscribeCall, createServiceUnsubscribeCall, parseServiceCall, parseServiceCatalogue, parseWireServiceProviderUpdate, parseWireServiceSubscriptionSnapshot, } from "@earendil-works/chord";
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { encodeClientMessage, isServerId, ProtocolValidationError, } from "@earendil-works/pi-protocol";
 import { Connection } from "./connection.js";
-import { PiClientDisposedError, PiDisconnectedError, PiServerError, PiSessionDetachedError, PiSessionOwnershipError, toError, } from "./errors.js";
+import { ClientDisposedError, DisconnectedError, ServerError, toError } from "./errors.js";
 import { createPromiseResolvers } from "./promise.js";
-import { SessionHandle, } from "./session-handle.js";
-import { ClientState } from "./state.js";
-export class PiClient {
+export class Client {
     #options;
     #connection;
-    #state;
     #pendingRequests = new Map();
-    #sessionLeaseCounts = new Map();
-    #exclusiveSessionLeases = new Map();
-    #sessionLeaseGenerations = new Map();
-    #sessionAttachments = new Map();
-    #sessionDetachments = new Map();
-    #sessionCleanupRequired = new Set();
-    #sessionReconciliations = new Map();
     #connectionStateListeners = new Set();
+    #attachmentListeners = new Set();
+    #serviceListeners = new Map();
     #requestSequence = 0;
+    #serviceSubscriptionSequence = 0;
+    #hello;
+    #attachment;
     #disposed = false;
     #disposePromise;
     constructor(options) {
+        if (!isServerId(options.serverId)) {
+            throw new TypeError("serverId must be a canonical lowercase UUIDv4");
+        }
         this.#options = options;
-        this.#state = new ClientState(options.onListenerError);
         this.#connection = new Connection({
             transportFactory: options.transportFactory,
+            serverId: options.serverId,
             maxFrameLength: options.maxFrameLength,
-            onHandshake: (snapshot) => this.#state.applyServerSnapshot(snapshot),
+            onHandshake: (hello) => {
+                this.#hello = hello;
+            },
             onMessage: (message) => this.#handleMessage(message),
             onStateChange: (change) => this.#handleConnectionStateChange(change),
         });
@@ -40,11 +42,17 @@ export class PiClient {
     get connected() {
         return this.#connection.state === "connected";
     }
-    get snapshot() {
-        return this.#state.snapshot;
+    get serverId() {
+        return this.#options.serverId;
+    }
+    get hello() {
+        return this.#hello;
+    }
+    get attachment() {
+        return this.#attachment;
     }
     static async connect(options) {
-        const client = new PiClient(options);
+        const client = new Client(options);
         try {
             await client.connect();
             return client;
@@ -56,9 +64,8 @@ export class PiClient {
     }
     connect() {
         if (this.#disposed)
-            return Promise.reject(new PiClientDisposedError());
-        if (this.#connection.state === "disconnected")
-            this.#state.reset();
+            return Promise.reject(new ClientDisposedError());
+        this.#hello = undefined;
         return this.#connection.connect();
     }
     reconnect() {
@@ -67,188 +74,185 @@ export class PiClient {
     disconnect(reason = "Client disconnected") {
         this.#connection.disconnect(reason);
     }
-    subscribe(listener) {
-        this.#assertNotDisposed();
-        return this.#state.subscribe(listener);
-    }
-    onEvent(listener) {
-        this.#assertNotDisposed();
-        return this.#state.onEvent(listener);
-    }
     onConnectionStateChange(listener) {
         this.#assertNotDisposed();
         this.#connectionStateListeners.add(listener);
         return () => this.#connectionStateListeners.delete(listener);
     }
-    async listSessions() {
-        return (await this.#request({ command: "list" })).sessions;
-    }
-    async createSession(options = {}) {
-        const result = await this.#request({ command: "create", ...options });
-        const token = this.#reserveSessionLease(result.session.id, "exclusive");
-        return this.#createSessionLease(result.session.id, token);
+    onAttachmentChange(listener) {
+        this.#assertNotDisposed();
+        this.#attachmentListeners.add(listener);
+        return () => this.#attachmentListeners.delete(listener);
     }
-    async attachSession(sessionId) {
-        return this.acquireSession(sessionId, { mode: "shared" });
+    /** Invoke one low-level protocol call against an explicit routed target. */
+    request(target, call, signal) {
+        return this.#request(target, call, signal);
     }
-    async acquireSession(sessionId, options) {
-        this.#assertNotDisposed();
-        const token = this.#reserveSessionLease(sessionId, options.mode);
+    async serviceCatalogue(target, signal) {
+        const result = await this.#request(target, createServiceCatalogueCall(), signal);
         try {
-            const detachment = this.#sessionDetachments.get(sessionId);
-            if (detachment)
-                await detachment.catch(() => { });
-            const reconciled = this.#sessionCleanupRequired.has(sessionId)
-                ? await this.#reconcileSessionCleanup(sessionId)
-                : false;
-            if (reconciled || !this.#state.isSessionAttached(sessionId)) {
-                let attachment = this.#sessionAttachments.get(sessionId);
-                if (!attachment) {
-                    attachment = this.#attachSession(sessionId);
-                    this.#sessionAttachments.set(sessionId, attachment);
-                }
-                try {
-                    await attachment;
-                }
-                finally {
-                    if (this.#sessionAttachments.get(sessionId) === attachment)
-                        this.#sessionAttachments.delete(sessionId);
-                }
-            }
-            return this.#createSessionLease(sessionId, token);
+            return parseServiceCatalogue(result);
         }
         catch (error) {
-            this.#releaseSessionLease(sessionId, token);
-            throw error;
+            const validationError = new ProtocolValidationError(error instanceof Error ? error.message : "Invalid service catalogue");
+            this.#connection.fail(validationError);
+            throw validationError;
         }
     }
-    async #attachSession(sessionId) {
-        const previous = this.#state.forgetSessionSnapshot(sessionId);
+    async subscribeService(target, serviceId, mode, listener, signal) {
+        const subscriptionId = `service-${++this.#serviceSubscriptionSequence}`;
+        const active = {
+            target,
+            listener,
+            decoder: createServiceStateDecoder(),
+            queuedWireUpdates: [],
+            queued: [],
+            deliveryTail: Promise.resolve(),
+            hydrated: false,
+            ready: false,
+        };
+        this.#serviceListeners.set(subscriptionId, active);
+        let snapshot;
         try {
-            await this.#request({ command: "attach", sessionId });
+            snapshot = await this.#request(target, createServiceSubscribeCall(subscriptionId, serviceId, mode), signal, (result) => {
+                const decoded = active.decoder.decodeSnapshot(parseWireServiceSubscriptionSnapshot(result));
+                active.hydrated = true;
+                for (const update of active.queuedWireUpdates.splice(0)) {
+                    active.queued.push(active.decoder.decodeUpdate(parseWireServiceProviderUpdate(update)));
+                }
+                return decoded;
+            });
         }
         catch (error) {
-            if (previous)
-                this.#state.restoreSessionSnapshot(previous);
+            if (this.#serviceListeners.get(subscriptionId) === active)
+                this.#serviceListeners.delete(subscriptionId);
             throw error;
         }
+        if (this.#serviceListeners.get(subscriptionId) !== active)
+            throw new DisconnectedError();
+        let disposed = false;
+        return {
+            id: subscriptionId,
+            target,
+            snapshot,
+            start: () => {
+                if (disposed || active.ready)
+                    return;
+                active.ready = true;
+                for (const update of active.queued.splice(0))
+                    this.#deliverServiceUpdate(active, update);
+            },
+            dispose: async () => {
+                if (disposed)
+                    return;
+                disposed = true;
+                if (this.#serviceListeners.get(subscriptionId) === active)
+                    this.#serviceListeners.delete(subscriptionId);
+                try {
+                    if (this.connected && this.#targetIsCurrent(target)) {
+                        await this.#request(target, createServiceUnsubscribeCall(subscriptionId));
+                    }
+                    await active.deliveryTail;
+                }
+                finally {
+                    active.queuedWireUpdates.length = 0;
+                    active.queued.length = 0;
+                }
+            },
+        };
     }
-    #request(command) {
+    #request(target, call, signal, transform) {
         if (this.#disposed)
-            return Promise.reject(new PiClientDisposedError());
+            return Promise.reject(new ClientDisposedError());
         if (!this.connected)
-            return Promise.reject(new PiDisconnectedError());
+            return Promise.reject(new DisconnectedError());
+        if (signal?.aborted)
+            return Promise.reject(abortError(signal));
         const id = `request-${++this.#requestSequence}`;
         const { promise, resolve, reject } = createPromiseResolvers();
-        this.#pendingRequests.set(id, { command, resolve, reject });
+        let sent = false;
+        let aborted = false;
+        let onAbort;
+        const sendCancel = () => {
+            if (!sent || !this.connected)
+                return;
+            try {
+                this.#connection.send(encodeClientMessage({ type: "cancel", id, target }, { maxFrameLength: this.#connection.maxFrameLength }));
+            }
+            catch (error) {
+                this.#connection.fail(toError(error));
+            }
+        };
+        if (signal !== undefined) {
+            onAbort = () => {
+                if (aborted)
+                    return;
+                aborted = true;
+                reject(abortError(signal));
+                sendCancel();
+            };
+            signal.addEventListener("abort", onAbort, { once: true });
+        }
+        this.#pendingRequests.set(id, {
+            resolve: (result) => {
+                try {
+                    resolve(transform === undefined ? result : transform(result));
+                }
+                catch (error) {
+                    const validationError = new ProtocolValidationError(error instanceof Error ? error.message : "Invalid service operation stream");
+                    this.#connection.fail(validationError);
+                    reject(validationError);
+                }
+            },
+            reject,
+            cleanup: () => {
+                if (signal !== undefined && onAbort !== undefined)
+                    signal.removeEventListener("abort", onAbort);
+            },
+        });
         let frame;
         try {
-            frame = encodeClientMessage({ type: "request", id, request: command }, { maxFrameLength: this.#connection.maxFrameLength });
+            frame = encodeClientMessage({ type: "request", id, target, call: parseServiceCall(call) }, { maxFrameLength: this.#connection.maxFrameLength });
         }
         catch (error) {
             this.#takePendingRequest(id)?.reject(toError(error));
             return promise;
         }
         this.#connection.send(frame);
+        sent = true;
+        if (aborted)
+            sendCancel();
         return promise;
     }
-    #createSessionLease(sessionId, token) {
-        const generation = this.#sessionLeaseGenerations.get(sessionId) ?? 0;
-        this.#sessionLeaseGenerations.set(sessionId, generation);
-        let state = "active";
-        let releasePromise;
-        const refreshState = () => {
-            if ((state === "active" || state === "releasing") &&
-                this.#sessionLeaseGenerations.get(sessionId) !== generation) {
-                state = "invalidated";
-            }
-        };
-        const isActive = () => {
-            refreshState();
-            return state === "active" && this.#state.isSessionAttached(sessionId);
-        };
-        const assertActive = () => {
-            this.#assertNotDisposed();
-            if (!this.connected)
-                throw new PiDisconnectedError();
-            if (!isActive())
-                throw new PiSessionDetachedError(sessionId);
-        };
-        const release = (relinquishOnFailure) => {
-            refreshState();
-            if (state === "released" || state === "invalidated")
-                return Promise.resolve();
-            if (releasePromise)
-                return releasePromise;
-            assertActive();
-            state = "releasing";
-            releasePromise = (async () => {
-                const count = this.#sessionLeaseCounts.get(sessionId) ?? 0;
-                if (count <= 1) {
-                    const detachment = this.#request({ command: "detach", sessionId }).then(() => undefined);
-                    this.#sessionDetachments.set(sessionId, detachment);
-                    try {
-                        await detachment;
-                        this.#releaseSessionLease(sessionId, token);
-                    }
-                    finally {
-                        if (this.#sessionDetachments.get(sessionId) === detachment) {
-                            this.#sessionDetachments.delete(sessionId);
-                        }
-                    }
-                }
-                else {
-                    this.#releaseSessionLease(sessionId, token);
-                }
-                state = "released";
-            })().catch((error) => {
-                refreshState();
-                if (state === "invalidated")
-                    return;
-                if (relinquishOnFailure) {
-                    this.#releaseSessionLease(sessionId, token);
-                    this.#sessionCleanupRequired.add(sessionId);
-                    state = "released";
-                }
-                else {
-                    state = "active";
-                    releasePromise = undefined;
-                }
-                throw error;
-            });
-            return releasePromise;
-        };
-        const callbacks = {
-            isAttached: isActive,
-            getSnapshot: () => (isActive() ? this.#state.getSessionSnapshot(sessionId) : undefined),
-            subscribe: (listener) => {
-                assertActive();
-                return this.#state.subscribeSession(sessionId, (snapshot) => {
-                    if (isActive())
-                        listener(snapshot);
-                });
-            },
-            onEvent: (listener) => {
-                assertActive();
-                return this.#state.onSessionEvent(sessionId, (event) => {
-                    if (isActive() || event.type === "session_removed")
-                        listener(event);
-                });
-            },
-            detach: () => release(false),
-            dispose: () => release(true),
-            request: (command) => {
-                assertActive();
-                return this.#request(command);
-            },
-        };
-        return new SessionHandle(sessionId, callbacks);
-    }
     #handleMessage(message) {
-        if (message.type === "event") {
-            if (message.event.type === "session_removed")
-                this.#invalidateSessionLeases(message.event.sessionId);
-            this.#state.applyEvent(message.event);
+        if (message.type === "attachment") {
+            if (message.attachment !== null && message.attachment.serverId !== this.#options.serverId) {
+                this.#connection.fail(new ProtocolValidationError("Attachment update belongs to another server"));
+                return;
+            }
+            this.#setAttachment(message.attachment ?? undefined);
+            return;
+        }
+        if (message.type === "service_update") {
+            const active = this.#serviceListeners.get(message.subscriptionId);
+            if (active === undefined)
+                return;
+            if (!active.hydrated) {
+                active.queuedWireUpdates.push(message.update);
+                return;
+            }
+            let update;
+            try {
+                update = active.decoder.decodeUpdate(parseWireServiceProviderUpdate(message.update));
+            }
+            catch (error) {
+                this.#connection.fail(new ProtocolValidationError(error instanceof Error ? error.message : "Invalid service operation stream"));
+                return;
+            }
+            if (active.ready)
+                this.#deliverServiceUpdate(active, update);
+            else
+                active.queued.push(update);
             return;
         }
         const pending = this.#takePendingRequest(message.id);
@@ -257,120 +261,95 @@ export class PiClient {
             return;
         }
         if (!message.ok) {
-            pending.reject(new PiServerError(message.error));
-            return;
-        }
-        if (message.result.command !== pending.command.command) {
-            const error = new ProtocolValidationError(`Response command ${message.result.command} does not match ${pending.command.command}`);
-            pending.reject(error);
-            this.#connection.fail(error);
+            pending.reject(new ServerError(message.error));
             return;
         }
-        this.#state.applyResult(message.result);
         pending.resolve(message.result);
     }
     #handleConnectionStateChange(change) {
         if (change.state === "disconnected") {
-            this.#state.clearAttachments();
-            this.#invalidateAllSessionLeases();
-            this.#rejectPendingRequests(change.error ?? new PiDisconnectedError());
+            this.#hello = undefined;
+            this.#setAttachment(undefined);
+            this.#rejectPendingRequests(change.error ?? new DisconnectedError());
+            this.#serviceListeners.clear();
+        }
+        for (const listener of this.#connectionStateListeners) {
+            try {
+                listener(change);
+            }
+            catch (error) {
+                this.#reportListenerError(error);
+            }
         }
-        this.#notifyConnectionStateListeners(change);
     }
     #takePendingRequest(id) {
         const request = this.#pendingRequests.get(id);
-        if (request)
+        if (request) {
             this.#pendingRequests.delete(id);
+            request.cleanup();
+        }
         return request;
     }
     #rejectPendingRequests(error) {
         const requests = [...this.#pendingRequests.values()];
         this.#pendingRequests.clear();
-        for (const request of requests)
+        for (const request of requests) {
+            request.cleanup();
             request.reject(error);
+        }
     }
     dispose() {
         if (this.#disposePromise)
             return this.#disposePromise;
         this.#disposed = true;
         this.#disposePromise = Promise.resolve();
-        const error = new PiClientDisposedError();
+        const error = new ClientDisposedError();
         this.#rejectPendingRequests(error);
         this.#connection.disconnect(error);
-        this.#state.dispose();
-        this.#invalidateAllSessionLeases();
+        this.#hello = undefined;
+        this.#setAttachment(undefined);
         this.#connectionStateListeners.clear();
+        this.#attachmentListeners.clear();
+        this.#serviceListeners.clear();
         return this.#disposePromise;
     }
     [Symbol.asyncDispose]() {
         return this.dispose();
     }
-    #assertNotDisposed() {
-        if (this.#disposed)
-            throw new PiClientDisposedError();
-    }
-    async #reconcileSessionCleanup(sessionId) {
-        if (!this.#sessionCleanupRequired.has(sessionId))
-            return false;
-        let reconciliation = this.#sessionReconciliations.get(sessionId);
-        if (!reconciliation) {
-            reconciliation = this.#request({ command: "detach", sessionId })
-                .then(() => undefined)
-                .then(() => {
-                this.#sessionCleanupRequired.delete(sessionId);
-            })
-                .finally(() => {
-                this.#sessionReconciliations.delete(sessionId);
-            });
-            this.#sessionReconciliations.set(sessionId, reconciliation);
-        }
-        await reconciliation;
-        return true;
-    }
-    #reserveSessionLease(sessionId, mode) {
-        const count = this.#sessionLeaseCounts.get(sessionId) ?? 0;
-        if (mode === "exclusive" && count > 0) {
-            throw new PiSessionOwnershipError(sessionId, `Session ${sessionId} already has an active lease`);
-        }
-        if (mode === "shared" && this.#exclusiveSessionLeases.has(sessionId)) {
-            throw new PiSessionOwnershipError(sessionId, `Session ${sessionId} has an exclusive lease`);
+    #setAttachment(attachment) {
+        const previous = this.#attachment;
+        if (previous?.serverId === attachment?.serverId &&
+            previous?.sessionId === attachment?.sessionId &&
+            previous?.attachmentId === attachment?.attachmentId) {
+            return;
         }
-        const token = { mode };
-        this.#sessionLeaseCounts.set(sessionId, count + 1);
-        if (mode === "exclusive")
-            this.#exclusiveSessionLeases.set(sessionId, token);
-        return token;
-    }
-    #releaseSessionLease(sessionId, token) {
-        const count = this.#sessionLeaseCounts.get(sessionId) ?? 0;
-        if (count <= 1)
-            this.#sessionLeaseCounts.delete(sessionId);
-        else
-            this.#sessionLeaseCounts.set(sessionId, count - 1);
-        if (this.#exclusiveSessionLeases.get(sessionId) === token)
-            this.#exclusiveSessionLeases.delete(sessionId);
-    }
-    #invalidateSessionLeases(sessionId) {
-        this.#sessionLeaseCounts.delete(sessionId);
-        this.#exclusiveSessionLeases.delete(sessionId);
-        this.#sessionCleanupRequired.delete(sessionId);
-        this.#sessionLeaseGenerations.set(sessionId, (this.#sessionLeaseGenerations.get(sessionId) ?? 0) + 1);
-    }
-    #invalidateAllSessionLeases() {
-        for (const sessionId of this.#sessionLeaseCounts.keys())
-            this.#invalidateSessionLeases(sessionId);
-        this.#sessionCleanupRequired.clear();
-    }
-    #notifyConnectionStateListeners(change) {
-        for (const listener of this.#connectionStateListeners) {
+        this.#attachment = attachment;
+        for (const listener of this.#attachmentListeners) {
             try {
-                listener(change);
+                listener(attachment);
             }
             catch (error) {
                 this.#reportListenerError(error);
             }
         }
     }
+    #deliverServiceUpdate(active, update) {
+        active.deliveryTail = active.deliveryTail
+            .then(() => active.listener(update))
+            .catch((error) => this.#reportListenerError(error));
+    }
+    #targetIsCurrent(target) {
+        if (!("sessionId" in target))
+            return this.#hello?.serverId === target.serverId;
+        const attachment = this.#attachment;
+        return (attachment?.serverId === target.serverId &&
+            attachment.sessionId === target.sessionId &&
+            attachment.attachmentId === target.attachmentId);
+    }
+    #assertNotDisposed() {
+        if (this.#disposed)
+            throw new ClientDisposedError();
+    }
     #reportListenerError(error) {
         if (!this.#options.onListenerError)
             return;
@@ -382,4 +361,28 @@ export class PiClient {
         }
     }
 }
+/** Adapts a lazily resolved routed client target to a Chord service transport. */
+export function createClientServiceTransport(client, getTarget) {
+    const target = () => {
+        const resolved = getTarget();
+        if (resolved === undefined)
+            throw new Error("Remote service target is unavailable");
+        return resolved;
+    };
+    return {
+        invoke: async (call, context) => client.request(target(), call, context.abortSignal),
+        async subscribe(serviceId, mode, listener, context) {
+            const subscription = await client.subscribeService(target(), serviceId, mode, (update) => listener(update, BACKGROUND_CONTEXT), context.abortSignal);
+            return {
+                snapshot: subscription.snapshot,
+                activate: () => subscription.start(),
+                close: () => subscription.dispose(),
+            };
+        },
+    };
+}
+function abortError(signal) {
+    const reason = signal.reason;
+    return reason instanceof Error ? reason : new DOMException("The operation was aborted", "AbortError");
+}
 //# sourceMappingURL=client.js.map