@cratis/arc 22.185.0 → 22.186.0

package/package.json

@@ -1,7 +1,7 @@
 {
     "type": "module",
     "name": "@cratis/arc",
-    "version": "22.185.0",
+    "version": "22.186.0",
     "description": "TypeScript command, query, validation, identity, and messaging runtime for Cratis Arc — the CQRS application framework for ASP.NET Core — used by generated proxies.",
     "keywords": [
         "cratis",

package/queries/ObservableQueryFor.ts

@@ -124,29 +124,7 @@ export abstract class ObservableQueryFor<
             this._connection.disconnect();
         }
 
-        const clientValidationErrors =
-            this.validation?.validate((args as object) || {}) || [];
-        if (clientValidationErrors.length > 0) {
-            // Serve the failure through the connection rather than throwing, so a subscriber sees an invalid result
-            // on its normal callback path instead of the empty result an unestablished connection would emit.
-            this._connection = new NullObservableQueryConnection(
-                this.defaultValue,
-                QueryResult.validationFailed(clientValidationErrors, this),
-            );
-        } else if (this.validateArguments(args)) {
-            this._connection = createObservableQueryConnection({
-                route: this.route,
-                queryName: this.queryName ?? this.constructor.name,
-                origin: this._origin,
-                apiBasePath: this._apiBasePath,
-                microservice: this._microservice,
-                args: args as object,
-                httpHeadersCallback: this._httpHeadersCallback,
-                pollingOptions: this._pollingOptions,
-            });
-        } else {
-            this._connection = new NullObservableQueryConnection(this.defaultValue);
-        }
+        this._connection = this.createConnection(args);
 
         // Descriptor-backed instance properties provide defaults; fresh args passed to subscribe()
         // must take precedence over any stale instance property values. Spread parameterValues
@@ -185,6 +163,47 @@ export abstract class ObservableQueryFor<
         return subscriber;
     }
 
+    private createConnection(args?: TParameters): IObservableQueryConnection<TDataType> {
+        const clientValidationErrors =
+            this.validation?.validate((args as object) || {}) || [];
+        if (clientValidationErrors.length > 0) {
+            // Serve the failure through the connection rather than throwing, so a subscriber sees an invalid result
+            // on its normal callback path instead of the empty result an unestablished connection would emit.
+            return new NullObservableQueryConnection(
+                this.defaultValue,
+                QueryResult.validationFailed(clientValidationErrors, this),
+            );
+        }
+
+        if (!this.validateArguments(args)) {
+            return new NullObservableQueryConnection(this.defaultValue);
+        }
+
+        return createObservableQueryConnection({
+            route: this.route,
+            queryName: this.queryName ?? this.constructor.name,
+            origin: this._origin,
+            apiBasePath: this._apiBasePath,
+            microservice: this._microservice,
+            args: args as object,
+            httpHeadersCallback: this._httpHeadersCallback,
+            pollingOptions: this._pollingOptions,
+        });
+    }
+
+    private buildRequestHeaders(): Record<string, any> {
+        const headers: Record<string, any> = {
+            ...(this._httpHeadersCallback?.() || {}),
+            Accept: 'application/json',
+            'Content-Type': 'application/json',
+        };
+
+        if (this._microservice?.length > 0) {
+            headers[Globals.microserviceHttpHeader] = this._microservice;
+        }
+        return headers;
+    }
+
     /** @inheritdoc */
     async perform(args?: TParameters): Promise<QueryResult<TDataType>> {
         const noSuccess = {
@@ -207,15 +226,7 @@ export abstract class ObservableQueryFor<
         // Collect parameter values from parameterDescriptors that are set
         const parameterValues = ParametersHelper.collectParameterValues(this);
 
-        const headers = {
-            ...(this._httpHeadersCallback?.() || {}),
-            Accept: 'application/json',
-            'Content-Type': 'application/json',
-        };
-
-        if (this._microservice?.length > 0) {
-            headers[Globals.microserviceHttpHeader] = this._microservice;
-        }
+        const headers = this.buildRequestHeaders();
 
         const response = await executeQueryHttpRequest(this._httpMethod, {
             route: this.route,

package/queries/QueryInstanceCache.ts

@@ -378,15 +378,19 @@ export class QueryInstanceCache {
      */
     teardownAllSubscriptions(): void {
         for (const [, entry] of this._entries) {
-            if (entry.pendingCleanup !== undefined) {
-                clearTimeout(entry.pendingCleanup);
-                entry.pendingCleanup = undefined;
-            }
+            this.teardownEntry(entry);
+        }
+    }
 
-            entry.subscribed = false;
-            entry.teardown?.();
-            entry.teardown = undefined;
+    private teardownEntry(entry: QueryCacheEntry<unknown>): void {
+        if (entry.pendingCleanup !== undefined) {
+            clearTimeout(entry.pendingCleanup);
+            entry.pendingCleanup = undefined;
         }
+
+        entry.subscribed = false;
+        entry.teardown?.();
+        entry.teardown = undefined;
     }
 
     /**
@@ -395,17 +399,7 @@ export class QueryInstanceCache {
      * unmounts permanently so that all query connections are closed synchronously.
      */
     dispose(): void {
-        for (const [, entry] of this._entries) {
-            if (entry.pendingCleanup !== undefined) {
-                clearTimeout(entry.pendingCleanup);
-                entry.pendingCleanup = undefined;
-            }
-
-            entry.subscribed = false;
-            entry.teardown?.();
-            entry.teardown = undefined;
-        }
-
+        this.teardownAllSubscriptions();
         this._entries.clear();
     }
 

package/queries/ServerSentEventHubConnection.ts

@@ -31,6 +31,19 @@ interface ActiveSubscription {
  */
 const IDLE_THRESHOLD_FACTOR = 2;
 
+/** Maximum number of subscribe retries before falling back to a full SSE reconnect. */
+const SUBSCRIBE_MAX_RETRIES = 3;
+
+/** Base delay between subscribe retries; multiplied by the attempt number. */
+const SUBSCRIBE_RETRY_DELAY_MS = 200;
+
+interface SubscribeTarget {
+    queryId: string;
+    subscription: ActiveSubscription;
+    connectionId: string;
+    attempt: number;
+}
+
 /**
  * A multiplexed SSE hub connection that uses EventSource for server→client streaming
  * and fetch POST requests for client→server subscribe/unsubscribe commands.
@@ -225,11 +238,7 @@ export class ServerSentEventHubConnection implements IObservableQueryHubConnecti
         }
 
         this._policy.cancel();
-        let url = this._sseUrl;
-        if (this._microservice?.length > 0) {
-            const param = `${Globals.microserviceWSQueryArgument}=${encodeURIComponent(this._microservice)}`;
-            url += (url.includes('?') ? '&' : '?') + param;
-        }
+        const url = this.buildEventSourceUrl();
 
         this._connectionId = undefined;
         this._supportsSubscriptionRevisions = false;
@@ -239,43 +248,59 @@ export class ServerSentEventHubConnection implements IObservableQueryHubConnecti
         this._eventSource = eventSource;
 
         eventSource.onopen = () => {
-            if (this._disconnected || this._eventSource !== eventSource) return;
+            if (!this.isActiveSource(eventSource)) return;
             console.log('SSE hub connection established', url);
             this._policy.reset();
             this._keepAlive.start();
-
-            // If the server does not send a Connected message within the timeout, the
-            // connection is broken. Close and retry via the reconnect policy.
-            this.clearConnectTimeout();
-            this._connectTimeoutTimer = setTimeout(() => {
-                if (
-                    !this._disconnected &&
-                    this._eventSource === eventSource &&
-                    !this._connectionId
-                ) {
-                    console.warn(
-                        'SSE hub: no Connected message within timeout; retrying',
-                        this._connectTimeoutMs,
-                        url,
-                    );
-                    this.reconnect();
-                }
-            }, this._connectTimeoutMs);
+            this.startConnectTimeout(eventSource, url);
         };
 
         eventSource.onmessage = (event: MessageEvent) => {
-            if (this._disconnected || this._eventSource !== eventSource) return;
+            if (!this.isActiveSource(eventSource)) return;
             this._keepAlive.recordActivity();
             this.handleMessage(event.data as string);
         };
 
         eventSource.onerror = () => {
-            if (this._disconnected || this._eventSource !== eventSource) return;
+            if (!this.isActiveSource(eventSource)) return;
             console.warn('SSE hub connection error', url);
             this.reconnect();
         };
     }
 
+    private buildEventSourceUrl(): string {
+        let url = this._sseUrl;
+        if (this._microservice?.length > 0) {
+            const param = `${Globals.microserviceWSQueryArgument}=${encodeURIComponent(this._microservice)}`;
+            url += (url.includes('?') ? '&' : '?') + param;
+        }
+        return url;
+    }
+
+    private isActiveSource(eventSource: EventSource): boolean {
+        return !this._disconnected && this._eventSource === eventSource;
+    }
+
+    /**
+     * If the server does not send a Connected message within the timeout, the
+     * connection is broken. Close and retry via the reconnect policy.
+     * @param {EventSource} eventSource The source the timeout guards.
+     * @param {string} url The URL used for diagnostics.
+     */
+    private startConnectTimeout(eventSource: EventSource, url: string): void {
+        this.clearConnectTimeout();
+        this._connectTimeoutTimer = setTimeout(() => {
+            if (this.isActiveSource(eventSource) && !this._connectionId) {
+                console.warn(
+                    'SSE hub: no Connected message within timeout; retrying',
+                    this._connectTimeoutMs,
+                    url,
+                );
+                this.reconnect();
+            }
+        }, this._connectTimeoutMs);
+    }
+
     private reconnect(): void {
         this._keepAlive.stop();
         this.clearConnectTimeout();
@@ -321,20 +346,10 @@ export class ServerSentEventHubConnection implements IObservableQueryHubConnecti
                     // Server-sent keep-alive ping — activity already recorded in onmessage.
                     break;
                 case HubMessageType.Unauthorized:
-                    if (this.isMessageForCurrentSubscription(message)) {
-                        console.warn('SSE hub: query unauthorized', message.queryId);
-                        this.handleUnauthorized(message);
-                    }
+                    this.handleUnauthorizedMessage(message);
                     break;
                 case HubMessageType.Error:
-                    if (this.isMessageForCurrentSubscription(message)) {
-                        console.error(
-                            'SSE hub: query error',
-                            message.queryId,
-                            message.payload,
-                        );
-                        this.handleError(message);
-                    }
+                    this.handleErrorMessage(message);
                     break;
             }
         } catch (error) {
@@ -342,6 +357,18 @@ export class ServerSentEventHubConnection implements IObservableQueryHubConnecti
         }
     }
 
+    private handleUnauthorizedMessage(message: HubMessage): void {
+        if (!this.isMessageForCurrentSubscription(message)) return;
+        console.warn('SSE hub: query unauthorized', message.queryId);
+        this.handleUnauthorized(message);
+    }
+
+    private handleErrorMessage(message: HubMessage): void {
+        if (!this.isMessageForCurrentSubscription(message)) return;
+        console.error('SSE hub: query error', message.queryId, message.payload);
+        this.handleError(message);
+    }
+
     private handleConnected(message: HubMessage): void {
         const connectionId = message.payload as string;
         const connectionIdChanged = this._connectionId !== connectionId;
@@ -458,15 +485,7 @@ export class ServerSentEventHubConnection implements IObservableQueryHubConnecti
         }
 
         const customHeaders = Globals.httpHeadersCallback?.() ?? {};
-
-        // Maximum number of subscribe retries before falling back to a full SSE reconnect.
-        // In a round-robin load-balanced deployment the subscribe POST may land on a different
-        // backend instance than the one holding the SSE connection.  Retrying gives the load
-        // balancer the chance to route a subsequent attempt to the correct instance without
-        // tearing down the SSE connection unnecessarily.  With N backend instances at most
-        // N-1 retries are needed, so 3 retries covers deployments with up to 4 replicas.
-        const maxRetries = 3;
-        const retryDelayMs = 200;
+        const target: SubscribeTarget = { queryId, subscription, connectionId, attempt };
 
         fetch(this._subscribeUrl, {
             method: 'POST',
@@ -475,78 +494,66 @@ export class ServerSentEventHubConnection implements IObservableQueryHubConnecti
         })
             .then((response) => {
                 if (!response.ok) {
-                    if (
-                        !this.isCurrentSubscription(queryId, subscription, connectionId)
-                    ) {
-                        console.warn(
-                            'SSE hub: subscribe POST returned a failure for an obsolete connection or subscription; ignoring',
-                            queryId,
-                            response.status,
-                        );
-                    } else if (attempt < maxRetries) {
-                        setTimeout(
-                            () => {
-                                if (
-                                    this.isCurrentSubscription(
-                                        queryId,
-                                        subscription,
-                                        connectionId,
-                                    )
-                                ) {
-                                    this.sendSubscribe(
-                                        queryId,
-                                        subscription,
-                                        attempt + 1,
-                                    );
-                                }
-                            },
-                            retryDelayMs * (attempt + 1),
-                        );
-                    } else {
-                        console.warn(
-                            'SSE hub: subscribe POST failed after retries; reconnecting',
-                            queryId,
-                            response.status,
-                            attempt + 1,
-                        );
-                        this.reconnect();
-                    }
+                    this.handleSubscribeFailure(target, console.warn, response.status);
                 }
             })
             .catch((error) => {
-                if (!this.isCurrentSubscription(queryId, subscription, connectionId)) {
-                    console.warn(
-                        'SSE hub: subscribe POST failed for an obsolete connection or subscription; ignoring',
-                        queryId,
-                        error,
-                    );
-                } else if (attempt < maxRetries) {
-                    setTimeout(
-                        () => {
-                            if (
-                                this.isCurrentSubscription(
-                                    queryId,
-                                    subscription,
-                                    connectionId,
-                                )
-                            ) {
-                                this.sendSubscribe(queryId, subscription, attempt + 1);
-                            }
-                        },
-                        retryDelayMs * (attempt + 1),
-                    );
-                } else {
-                    console.error(
-                        'SSE hub: subscribe POST failed after retries; reconnecting',
-                        queryId,
-                        attempt + 1,
-                        error,
-                    );
-                    this.reconnect();
-                }
+                this.handleSubscribeFailure(target, console.error, undefined, error);
             });
     }
 
+    /**
+     * Decide what to do after a failed subscribe POST: ignore it when obsolete, retry with back-off,
+     * or fall back to a full reconnect once the retries are exhausted.
+     *
+     * The retry limit exists because in a round-robin load-balanced deployment the subscribe POST may
+     * land on a different backend instance than the one holding the SSE connection. Retrying gives
+     * the load balancer the chance to route a subsequent attempt to the correct instance without
+     * tearing down the SSE connection unnecessarily. With N backend instances at most N-1 retries
+     * are needed, so 3 retries covers deployments with up to 4 replicas.
+     * @param {SubscribeTarget} target The subscribe attempt that failed.
+     * @param {Function} exhaustedLog The logger used when the retries are exhausted.
+     * @param {number | undefined} status The HTTP status, when the server responded.
+     * @param {unknown} error The thrown error, when the request itself failed.
+     */
+    private handleSubscribeFailure(
+        target: SubscribeTarget,
+        exhaustedLog: (...data: unknown[]) => void,
+        status?: number,
+        error?: unknown,
+    ): void {
+        const { queryId, subscription, connectionId, attempt } = target;
+        const detail = error === undefined ? [status] : [error];
+
+        if (!this.isCurrentSubscription(queryId, subscription, connectionId)) {
+            const reason = error === undefined ? 'returned a failure' : 'failed';
+            console.warn(
+                `SSE hub: subscribe POST ${reason} for an obsolete connection or subscription; ignoring`,
+                queryId,
+                ...detail,
+            );
+        } else if (attempt < SUBSCRIBE_MAX_RETRIES) {
+            this.scheduleSubscribeRetry(target);
+        } else {
+            const tail = error === undefined ? [status, attempt + 1] : [attempt + 1, error];
+            exhaustedLog(
+                'SSE hub: subscribe POST failed after retries; reconnecting',
+                queryId,
+                ...tail,
+            );
+            this.reconnect();
+        }
+    }
+
+    private scheduleSubscribeRetry(target: SubscribeTarget): void {
+        const { queryId, subscription, connectionId, attempt } = target;
+        setTimeout(() => {
+            if (this.isCurrentSubscription(queryId, subscription, connectionId)) {
+                this.sendSubscribe(queryId, subscription, attempt + 1);
+            }
+        }, SUBSCRIBE_RETRY_DELAY_MS * (attempt + 1));
+    }
+
     private isMessageForCurrentSubscription(message: HubMessage): boolean {
         if (!message.queryId) return false;
 

package/queries/WebSocketHubConnection.ts

@@ -167,7 +167,7 @@ export class WebSocketHubConnection {
         this._subscriptions.set(queryId, subscription);
         this.ensureConnected();
 
-        if (this._socket?.readyState === WebSocket.OPEN && this._subscriptionsReleased) {
+        if (this.isOpenAndReleased()) {
             this.sendSubscribeMessage(queryId, subscription);
         }
         // Until the server has said what it supports, subscriptions are held back and sent once, by releaseSubscriptions.
@@ -181,7 +181,7 @@ export class WebSocketHubConnection {
         const subscription = this._subscriptions.get(queryId);
         this._subscriptions.delete(queryId);
 
-        if (this._socket?.readyState === WebSocket.OPEN && this._subscriptionsReleased && subscription) {
+        if (this.isOpenAndReleased() && subscription) {
             const message: HubMessage = {
                 type: HubMessageType.Unsubscribe,
                 queryId,
@@ -212,11 +212,7 @@ export class WebSocketHubConnection {
             this._disconnected = false;
         }
 
-        if (
-            this._socket &&
-            (this._socket.readyState === WebSocket.OPEN ||
-                this._socket.readyState === WebSocket.CONNECTING)
-        ) {
+        if (this.isSocketLive(this._socket)) {
             this.cancelPendingReconnect();
             return;
         }
@@ -243,11 +239,7 @@ export class WebSocketHubConnection {
 
     private openSocket(): void {
         const currentSocket = this._socket;
-        if (
-            currentSocket &&
-            (currentSocket.readyState === WebSocket.OPEN ||
-                currentSocket.readyState === WebSocket.CONNECTING)
-        ) {
+        if (this.isSocketLive(currentSocket)) {
             return;
         }
 
@@ -259,67 +251,94 @@ export class WebSocketHubConnection {
         this._supportsSubscriptionRevisions = false;
         this.resetSubscriptionRelease();
 
-        let url = this._url;
-        if (this._microservice?.length > 0) {
-            const param = `${Globals.microserviceWSQueryArgument}=${encodeURIComponent(this._microservice)}`;
-            url += (url.includes('?') ? '&' : '?') + param;
-        }
-
+        const url = this.buildSocketUrl();
         const socket = new WebSocket(url);
         this._socket = socket;
 
         socket.onopen = () => {
-            if (this._socket !== socket || this._disconnected) return;
-            console.log('Hub connection established', url);
-            this.cancelPendingReconnect();
-            this._policy.reset();
-            this._keepAlive.start();
-
-            // A capable server announces itself with a Connected message straight after accepting the socket. Sending
-            // the subscriptions before that would mean sending them twice (once without a revision, once with), and the
-            // server would run every query twice and cancel the first run. Wait for it, and only fall back to the
-            // revision-less form for a server that never says anything.
-            this._releaseTimer = setTimeout(() => {
-                this._releaseTimer = undefined;
-                if (this._socket === socket && !this._disconnected) {
-                    this.releaseSubscriptions();
-                }
-            }, WebSocketHubConnection.ConnectedGraceMs);
+            if (!this.isActiveSocket(socket)) return;
+            this.handleSocketOpened(socket, url);
         };
 
         socket.onclose = () => {
-            if (this._socket !== socket || this._disconnected) return;
-            console.log('Hub connection closed', url);
-            this._socket = undefined;
-            this._supportsSubscriptionRevisions = false;
-            this.resetSubscriptionRelease();
-            this._keepAlive.stop();
-            if (this._subscriptions.size === 0) return;
-            this._reconnectPending = true;
-            const scheduled = this._policy.schedule(() => {
-                this._reconnectPending = false;
-                if (!this._disconnected && this._subscriptions.size > 0) {
-                    this.ensureConnected();
-                }
-            }, this._url);
-            if (!scheduled) {
-                this._reconnectPending = false;
-            }
+            if (!this.isActiveSocket(socket)) return;
+            this.handleSocketClosed(url);
         };
 
         socket.onerror = (error) => {
-            if (this._socket !== socket || this._disconnected) return;
+            if (!this.isActiveSocket(socket)) return;
             console.error('Hub connection error', url, error);
             this._keepAlive.stop();
             // onclose will fire after onerror, triggering reconnect
         };
 
         socket.onmessage = (ev) => {
-            if (this._socket !== socket || this._disconnected) return;
+            if (!this.isActiveSocket(socket)) return;
             this.handleMessage(ev.data as string);
         };
     }
 
+    private buildSocketUrl(): string {
+        let url = this._url;
+        if (this._microservice?.length > 0) {
+            const param = `${Globals.microserviceWSQueryArgument}=${encodeURIComponent(this._microservice)}`;
+            url += (url.includes('?') ? '&' : '?') + param;
+        }
+        return url;
+    }
+
+    private isSocketLive(socket: WebSocket | undefined): boolean {
+        return (
+            socket !== undefined &&
+            (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING)
+        );
+    }
+
+    private isActiveSocket(socket: WebSocket): boolean {
+        return this._socket === socket && !this._disconnected;
+    }
+
+    private isOpenAndReleased(): boolean {
+        return this._socket?.readyState === WebSocket.OPEN && this._subscriptionsReleased;
+    }
+
+    private handleSocketOpened(socket: WebSocket, url: string): void {
+        console.log('Hub connection established', url);
+        this.cancelPendingReconnect();
+        this._policy.reset();
+        this._keepAlive.start();
+
+        // A capable server announces itself with a Connected message straight after accepting the socket. Sending
+        // the subscriptions before that would mean sending them twice (once without a revision, once with), and the
+        // server would run every query twice and cancel the first run. Wait for it, and only fall back to the
+        // revision-less form for a server that never says anything.
+        this._releaseTimer = setTimeout(() => {
+            this._releaseTimer = undefined;
+            if (this.isActiveSocket(socket)) {
+                this.releaseSubscriptions();
+            }
+        }, WebSocketHubConnection.ConnectedGraceMs);
+    }
+
+    private handleSocketClosed(url: string): void {
+        console.log('Hub connection closed', url);
+        this._socket = undefined;
+        this._supportsSubscriptionRevisions = false;
+        this.resetSubscriptionRelease();
+        this._keepAlive.stop();
+        if (this._subscriptions.size === 0) return;
+        this._reconnectPending = true;
+        const scheduled = this._policy.schedule(() => {
+            this._reconnectPending = false;
+            if (!this._disconnected && this._subscriptions.size > 0) {
+                this.ensureConnected();
+            }
+        }, this._url);
+        if (!scheduled) {
+            this._reconnectPending = false;
+        }
+    }
+
     private cancelPendingReconnect(): void {
         if (!this._reconnectPending) return;