@cratis/arc 19.11.1 → 20.0.0

package/queries/ServerSentEventQueryConnection.ts

@@ -0,0 +1,84 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { IObservableQueryConnection } from './IObservableQueryConnection';
+import { DataReceived } from './ObservableQueryConnection';
+import { QueryResult } from './QueryResult';
+
+/**
+ * The SSE demultiplexer route used when connecting through the multiplexed observable query endpoint.
+ */
+export const SSE_HUB_ROUTE = '/.cratis/queries/sse';
+
+/**
+ * Represents a direct Server-Sent Events (SSE) connection for a single observable query.
+ *
+ * In direct mode the URL points to the per-query endpoint (e.g. `/api/queries/latest`).
+ * The backend detects the `Accept: text/event-stream` header and streams results directly.
+ *
+ * The caller (typically {@link createObservableQueryConnection}) decides which URL to use;
+ * this class is transport-agnostic beyond being SSE.
+ */
+export class ServerSentEventQueryConnection<TDataType> implements IObservableQueryConnection<TDataType> {
+    private _eventSource?: EventSource;
+    private _disconnected = false;
+
+    /** @inheritdoc */
+    readonly lastPingLatency: number = 0;
+
+    /** @inheritdoc */
+    readonly averageLatency: number = 0;
+
+    /**
+     * Initializes a new instance of {@link ServerSentEventQueryConnection}.
+     * @param {URL} url The fully qualified URL of the SSE endpoint (including query parameters).
+     */
+    constructor(private readonly _url: URL) {}
+
+    /** @inheritdoc */
+    connect(dataReceived: DataReceived<TDataType>, queryArguments?: object): void {
+        if (this._disconnected) return;
+
+        // Guard against environments where EventSource is not available (e.g. Node.js, SSR).
+        if (typeof EventSource === 'undefined') {
+            return;
+        }
+
+        let url = this._url.toString();
+        if (queryArguments) {
+            const separator = url.includes('?') ? '&' : '?';
+            const query = Object.entries(queryArguments)
+                .filter(([, value]) => value !== undefined && value !== null)
+                .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`)
+                .join('&');
+            if (query) {
+                url = `${url}${separator}${query}`;
+            }
+        }
+
+        this._eventSource = new EventSource(url);
+
+        this._eventSource.onmessage = (event: MessageEvent) => {
+            if (this._disconnected) return;
+            try {
+                const result = JSON.parse(event.data as string) as QueryResult<TDataType>;
+                dataReceived(result);
+            } catch (error) {
+                console.error('SSE: error parsing message', error);
+            }
+        };
+
+        this._eventSource.onerror = () => {
+            if (this._disconnected) return;
+            console.warn(`SSE: connection error for '${url}', EventSource will retry automatically.`);
+        };
+    }
+
+    /** @inheritdoc */
+    disconnect(): void {
+        if (this._disconnected) return;
+        this._disconnected = true;
+        this._eventSource?.close();
+        this._eventSource = undefined;
+    }
+}

package/queries/WebSocketHubConnection.ts

@@ -0,0 +1,291 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Globals } from '../Globals';
+import { DataReceived } from './ObservableQueryConnection';
+import { HubConnectionKeepAlive } from './HubConnectionKeepAlive';
+import { IReconnectPolicy } from './IReconnectPolicy';
+import { ReconnectPolicy } from './ReconnectPolicy';
+import { QueryResult } from './QueryResult';
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/**
+ * Message types matching the backend {@link ObservableQueryHubMessageType} enum.
+ * Serialized as integers by the Cratis JSON configuration.
+ */
+export enum HubMessageType {
+    Subscribe = 0,
+    Unsubscribe = 1,
+    QueryResult = 2,
+    Unauthorized = 3,
+    Error = 4,
+    Ping = 5,
+    Pong = 6,
+    Connected = 7,
+}
+
+/**
+ * Wire format for messages exchanged over the {@link WebSocketHubConnection}.
+ */
+export interface HubMessage {
+    type: HubMessageType;
+    queryId?: string;
+    payload?: any;
+    timestamp?: number;
+}
+
+/**
+ * Matches the backend {@link ObservableQuerySubscriptionRequest} record.
+ */
+export interface SubscriptionRequest {
+    queryName: string;
+    arguments?: Record<string, string | null>;
+    page?: number;
+    pageSize?: number;
+    sortBy?: string;
+    sortDirection?: string;
+}
+
+interface ActiveSubscription {
+    request: SubscriptionRequest;
+    callback: DataReceived<any>;
+}
+
+/**
+ * Represents a single multiplexed WebSocket connection to the observable query hub
+ * at {@code /.cratis/queries/ws}.
+ *
+ * Multiple query subscriptions are carried over the same physical WebSocket. Each subscription
+ * is identified by a client-generated {@code queryId}; the server tags every result message with
+ * the same id so responses can be routed to the correct callback.
+ */
+export class WebSocketHubConnection {
+    private _socket?: WebSocket;
+    private _disconnected = false;
+    private _subscriptions: Map<string, ActiveSubscription> = new Map();
+    private readonly _keepAlive: HubConnectionKeepAlive;
+    private _lastPingSentTime?: number;
+    private _lastPongLatency: number = 0;
+    private _latencySamples: number[] = [];
+
+    /**
+     * Initializes a new instance of {@link WebSocketHubConnection}.
+     * @param {string} url The WebSocket URL of the hub endpoint (e.g. {@code ws://localhost:5000/.cratis/queries/ws}).
+     * @param {string} microservice The microservice name to pass as a query argument.
+     * @param {number} pingIntervalMs How often to send keep-alive pings when the connection is idle (default: 10 000 ms).
+     * @param {IReconnectPolicy} reconnectPolicy The reconnect policy to use (default: {@link ReconnectPolicy}).
+     */
+    constructor(
+        private readonly _url: string,
+        private readonly _microservice: string,
+        pingIntervalMs: number = 10000,
+        private readonly _policy: IReconnectPolicy = new ReconnectPolicy()
+    ) {
+        this._keepAlive = new HubConnectionKeepAlive(pingIntervalMs, () => {
+            if (this._socket?.readyState === WebSocket.OPEN) {
+                this._lastPingSentTime = Date.now();
+                this.sendMessage({ type: HubMessageType.Ping, timestamp: this._lastPingSentTime });
+            }
+        });
+    }
+
+    /**
+     * Gets the number of active query subscriptions on this connection.
+     */
+    get queryCount(): number {
+        return this._subscriptions.size;
+    }
+
+    /**
+     * Gets the latency of the last ping/pong sequence in milliseconds.
+     */
+    get lastPingLatency(): number {
+        return this._lastPongLatency;
+    }
+
+    /**
+     * Gets the rolling average latency in milliseconds.
+     */
+    get averageLatency(): number {
+        if (this._latencySamples.length === 0) return 0;
+        return this._latencySamples.reduce((a, b) => a + b, 0) / this._latencySamples.length;
+    }
+
+    /**
+     * Subscribe to a query on this hub connection.
+     * If the WebSocket is not yet open, the subscribe message will be sent once the connection is established.
+     * @param {string} queryId Client-generated unique identifier for this subscription.
+     * @param {SubscriptionRequest} request The subscription request payload.
+     * @param {DataReceived<any>} callback Callback invoked whenever the server pushes a result for this query.
+     */
+    subscribe(queryId: string, request: SubscriptionRequest, callback: DataReceived<any>): void {
+        this._subscriptions.set(queryId, { request, callback });
+        this.ensureConnected();
+
+        if (this._socket?.readyState === WebSocket.OPEN) {
+            this.sendSubscribeMessage(queryId, request);
+        }
+        // If not yet open, sendAllSubscriptions will fire in onopen.
+    }
+
+    /**
+     * Unsubscribe from a query on this hub connection.
+     * @param {string} queryId The identifier of the subscription to cancel.
+     */
+    unsubscribe(queryId: string): void {
+        this._subscriptions.delete(queryId);
+
+        if (this._socket?.readyState === WebSocket.OPEN) {
+            this.sendMessage({ type: HubMessageType.Unsubscribe, queryId });
+        }
+
+        // If no subscriptions remain, close the connection to free resources.
+        if (this._subscriptions.size === 0) {
+            this.close();
+        }
+    }
+
+    /**
+     * Permanently close this hub connection and clean up all subscriptions.
+     */
+    dispose(): void {
+        this._disconnected = true;
+        this._subscriptions.clear();
+        this._keepAlive.stop();
+        this._policy.cancel();
+        this._socket?.close();
+        this._socket = undefined;
+    }
+
+    private ensureConnected(): void {
+        if (this._disconnected) {
+            // Reset disconnected flag when a new subscription comes in
+            this._disconnected = false;
+        }
+
+        if (this._socket && (this._socket.readyState === WebSocket.OPEN || this._socket.readyState === WebSocket.CONNECTING)) {
+            return;
+        }
+
+        this.openSocket();
+    }
+
+    private close(): void {
+        this._disconnected = true;
+        this._keepAlive.stop();
+        this._policy.cancel();
+        this._socket?.close();
+        this._socket = undefined;
+    }
+
+    private openSocket(): void {
+        let url = this._url;
+        if (this._microservice?.length > 0) {
+            const param = `${Globals.microserviceWSQueryArgument}=${encodeURIComponent(this._microservice)}`;
+            url += (url.includes('?') ? '&' : '?') + param;
+        }
+
+        this._socket = new WebSocket(url);
+
+        this._socket.onopen = () => {
+            if (this._disconnected) return;
+            console.log(`Hub connection established: '${url}'`);
+            this._policy.reset();
+            this._keepAlive.start();
+            this.sendAllSubscriptions();
+        };
+
+        this._socket.onclose = () => {
+            if (this._disconnected) return;
+            console.log(`Hub connection closed: '${url}'`);
+            this._keepAlive.stop();
+            if (this._subscriptions.size === 0) return;
+            this._policy.schedule(() => {
+                if (!this._disconnected && this._subscriptions.size > 0) {
+                    this.openSocket();
+                }
+            }, this._url);
+        };
+
+        this._socket.onerror = (error) => {
+            if (this._disconnected) return;
+            console.error(`Hub connection error: '${url}'`, error);
+            this._keepAlive.stop();
+            // onclose will fire after onerror, triggering reconnect
+        };
+
+        this._socket.onmessage = (ev) => {
+            if (this._disconnected) return;
+            this.handleMessage(ev.data as string);
+        };
+    }
+
+    private sendAllSubscriptions(): void {
+        for (const [queryId, sub] of this._subscriptions) {
+            this.sendSubscribeMessage(queryId, sub.request);
+        }
+    }
+
+    private sendSubscribeMessage(queryId: string, request: SubscriptionRequest): void {
+        this.sendMessage({
+            type: HubMessageType.Subscribe,
+            queryId,
+            payload: request,
+        });
+    }
+
+    private sendMessage(message: HubMessage): void {
+        if (this._socket?.readyState === WebSocket.OPEN) {
+            this._socket.send(JSON.stringify(message));
+        }
+    }
+
+    private handleMessage(rawData: string): void {
+        try {
+            const message = JSON.parse(rawData) as HubMessage;
+
+            // Every received message is activity — skip keep-alive ping if data is flowing.
+            this._keepAlive.recordActivity();
+
+            switch (message.type) {
+                case HubMessageType.QueryResult:
+                    this.handleQueryResult(message);
+                    break;
+                case HubMessageType.Pong:
+                    this.handlePong(message);
+                    break;
+                case HubMessageType.Unauthorized:
+                    console.warn(`Hub: query '${message.queryId}' unauthorized`);
+                    break;
+                case HubMessageType.Error:
+                    console.error(`Hub: query '${message.queryId}' error:`, message.payload);
+                    break;
+            }
+        } catch (error) {
+            console.error('Hub: error parsing message', error);
+        }
+    }
+
+    private handleQueryResult(message: HubMessage): void {
+        if (!message.queryId) return;
+
+        const sub = this._subscriptions.get(message.queryId);
+        if (!sub) return;
+
+        const result = message.payload as QueryResult<any>;
+        sub.callback(result);
+    }
+
+    private handlePong(message: HubMessage): void {
+        if (message.timestamp && this._lastPingSentTime) {
+            const latency = Date.now() - message.timestamp;
+            this._lastPongLatency = latency;
+            this._latencySamples.push(latency);
+
+            if (this._latencySamples.length > 100) {
+                this._latencySamples.shift();
+            }
+        }
+    }
+}

package/queries/for_HubConnectionKeepAlive/behavior.ts

@@ -0,0 +1,73 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import sinon from 'sinon';
+import { HubConnectionKeepAlive } from '../HubConnectionKeepAlive';
+
+describe('for HubConnectionKeepAlive', () => {
+    let clock: sinon.SinonFakeTimers;
+
+    beforeEach(() => { clock = sinon.useFakeTimers(); });
+    afterEach(() => { clock.restore(); sinon.restore(); });
+
+    describe('when started and the interval elapses without any activity', () => {
+        let onIdle: sinon.SinonStub;
+        let keepAlive: HubConnectionKeepAlive;
+
+        beforeEach(() => {
+            onIdle = sinon.stub();
+            keepAlive = new HubConnectionKeepAlive(1000, onIdle);
+            keepAlive.start();
+            clock.tick(1001);
+        });
+
+        it('should invoke the onIdle callback', () => onIdle.calledOnce.should.be.true);
+    });
+
+    describe('when activity is recorded before the interval elapses', () => {
+        let onIdle: sinon.SinonStub;
+        let keepAlive: HubConnectionKeepAlive;
+
+        beforeEach(() => {
+            onIdle = sinon.stub();
+            keepAlive = new HubConnectionKeepAlive(1000, onIdle);
+            keepAlive.start();
+            clock.tick(500);
+            keepAlive.recordActivity();
+            clock.tick(600);
+        });
+
+        it('should not invoke the onIdle callback', () => onIdle.called.should.be.false);
+    });
+
+    describe('when stopped before the interval elapses', () => {
+        let onIdle: sinon.SinonStub;
+        let keepAlive: HubConnectionKeepAlive;
+
+        beforeEach(() => {
+            onIdle = sinon.stub();
+            keepAlive = new HubConnectionKeepAlive(1000, onIdle);
+            keepAlive.start();
+            clock.tick(500);
+            keepAlive.stop();
+            clock.tick(600);
+        });
+
+        it('should not invoke the onIdle callback', () => onIdle.called.should.be.false);
+    });
+
+    describe('when started twice', () => {
+        let onIdle: sinon.SinonStub;
+        let keepAlive: HubConnectionKeepAlive;
+
+        beforeEach(() => {
+            onIdle = sinon.stub();
+            keepAlive = new HubConnectionKeepAlive(1000, onIdle);
+            keepAlive.start();
+            keepAlive.start();
+            clock.tick(1001);
+        });
+
+        it('should invoke the onIdle callback exactly once', () => onIdle.calledOnce.should.be.true);
+    });
+});

package/queries/for_ObservableQueryConnection/given/an_observable_query_connection.ts

@@ -8,19 +8,23 @@ export class an_observable_query_connection {
     connection: ObservableQueryConnection<string>;
     url: URL;
     microservice: string;
-    mockWebSocket: sinon.SinonStubbedInstance<WebSocket>;
+    mockWebSocket: Record<string, unknown>;
 
     constructor() {
         this.url = new URL('https://example.com/api/test');
         this.microservice = 'test-microservice';
-        
-        // Stub the WebSocket constructor
-        this.mockWebSocket = sinon.createStubInstance(WebSocket);
-        Object.defineProperty(this.mockWebSocket, 'readyState', {
-            value: WebSocket.OPEN,
-            writable: false
-        });
-        
+
+        // Create a plain mock WebSocket object
+        this.mockWebSocket = {
+            onopen: null,
+            onclose: null,
+            onerror: null,
+            onmessage: null,
+            close: sinon.stub(),
+            send: sinon.stub(),
+            readyState: WebSocket.OPEN,
+        };
+
         // Create connection with a short ping interval for testing (100ms)
         this.connection = new ObservableQueryConnection<string>(this.url, this.microservice, 100);
     }

package/queries/for_ObservableQueryConnectionFactory/given/a_descriptor.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { QueryConnectionDescriptor } from '../../ObservableQueryConnectionFactory';
+import { Globals } from '../../../Globals';
+import { QueryTransportMethod } from '../../QueryTransportMethod';
+
+export class a_descriptor {
+    descriptor: QueryConnectionDescriptor;
+    originalDirectMode: boolean;
+    originalTransportMethod: QueryTransportMethod;
+
+    constructor() {
+        this.originalDirectMode = Globals.queryDirectMode;
+        this.originalTransportMethod = Globals.queryTransportMethod;
+
+        this.descriptor = {
+            route: '/api/test/{id}',
+            queryName: 'TestApp.Features.Queries.AllItems',
+            origin: 'https://example.com',
+            apiBasePath: '',
+            microservice: '',
+            args: { id: 'item-42' },
+        };
+    }
+}

package/queries/for_ObservableQueryConnectionFactory/when_creating/with_direct_mode_and_sse_transport.ts

@@ -0,0 +1,62 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { a_descriptor } from '../given/a_descriptor';
+import { given } from '../../../given';
+import { Globals } from '../../../Globals';
+import { QueryTransportMethod } from '../../QueryTransportMethod';
+import { createObservableQueryConnection } from '../../ObservableQueryConnectionFactory';
+import { ServerSentEventQueryConnection } from '../../ServerSentEventQueryConnection';
+import { IObservableQueryConnection } from '../../IObservableQueryConnection';
+
+import * as sinon from 'sinon';
+
+describe('when creating with direct mode and SSE transport', given(a_descriptor, context => {
+    let connection: IObservableQueryConnection<unknown>;
+    let capturedUrl: string;
+
+    beforeEach(() => {
+        Globals.queryDirectMode = true;
+        Globals.queryTransportMethod = QueryTransportMethod.ServerSentEvents;
+
+        const FakeEventSourceConstructor = function (this: EventSource, url: string) {
+            capturedUrl = url;
+            Object.assign(this, {
+                onopen: null,
+                onerror: null,
+                onmessage: null,
+                close: sinon.stub(),
+                addEventListener: sinon.stub(),
+                removeEventListener: sinon.stub(),
+            });
+        };
+        (globalThis as Record<string, unknown>)['EventSource'] = FakeEventSourceConstructor;
+
+        connection = createObservableQueryConnection(context.descriptor);
+    });
+
+    afterEach(() => {
+        Globals.queryDirectMode = context.originalDirectMode;
+        Globals.queryTransportMethod = context.originalTransportMethod;
+        delete (globalThis as Record<string, unknown>)['EventSource'];
+    });
+
+    it('should return a ServerSentEventQueryConnection', () => {
+        connection.should.be.instanceOf(ServerSentEventQueryConnection);
+    });
+
+    it('should target the per-query URL with route parameters replaced', () => {
+        (connection as ServerSentEventQueryConnection<unknown>).connect(sinon.stub());
+        capturedUrl.should.include('/api/test/item-42');
+    });
+
+    it('should not target the hub SSE endpoint', () => {
+        (connection as ServerSentEventQueryConnection<unknown>).connect(sinon.stub());
+        capturedUrl.should.not.include('/.cratis/queries/sse');
+    });
+
+    it('should not include a query name parameter', () => {
+        (connection as ServerSentEventQueryConnection<unknown>).connect(sinon.stub());
+        capturedUrl.should.not.include('query=');
+    });
+}));

package/queries/for_ObservableQueryConnectionFactory/when_creating/with_direct_mode_and_websocket_transport.ts

@@ -0,0 +1,59 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { a_descriptor } from '../given/a_descriptor';
+import { given } from '../../../given';
+import { Globals } from '../../../Globals';
+import { QueryTransportMethod } from '../../QueryTransportMethod';
+import { createObservableQueryConnection } from '../../ObservableQueryConnectionFactory';
+import { ObservableQueryConnection } from '../../ObservableQueryConnection';
+import { IObservableQueryConnection } from '../../IObservableQueryConnection';
+
+import * as sinon from 'sinon';
+
+describe('when creating with direct mode and WebSocket transport', given(a_descriptor, context => {
+    let connection: IObservableQueryConnection<unknown>;
+    let originalWebSocket: typeof WebSocket;
+    let capturedUrl: string;
+
+    beforeEach(() => {
+        Globals.queryDirectMode = true;
+        Globals.queryTransportMethod = QueryTransportMethod.WebSocket;
+
+        originalWebSocket = global.WebSocket;
+        (global as Record<string, unknown>).WebSocket = function (url: string) {
+            capturedUrl = url;
+            return {
+                onopen: null,
+                onclose: null,
+                onerror: null,
+                onmessage: null,
+                close: sinon.stub(),
+                send: sinon.stub(),
+            };
+        };
+
+        connection = createObservableQueryConnection(context.descriptor);
+    });
+
+    afterEach(() => {
+        Globals.queryDirectMode = context.originalDirectMode;
+        Globals.queryTransportMethod = context.originalTransportMethod;
+        global.WebSocket = originalWebSocket;
+        sinon.restore();
+    });
+
+    it('should return an ObservableQueryConnection', () => {
+        connection.should.be.instanceOf(ObservableQueryConnection);
+    });
+
+    it('should target the per-query URL with route parameters replaced', () => {
+        (connection as ObservableQueryConnection<unknown>).connect(sinon.stub());
+        capturedUrl.should.include('/api/test/item-42');
+    });
+
+    it('should not target the hub endpoint', () => {
+        (connection as ObservableQueryConnection<unknown>).connect(sinon.stub());
+        capturedUrl.should.not.include('/.cratis/queries');
+    });
+}));