@cratis/arc 19.12.0 → 20.1.0

package/queries/QueryInstanceCache.ts

@@ -0,0 +1,243 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { QueryResultWithState } from './QueryResultWithState';
+
+/**
+ * Represents a key that uniquely identifies a query instance in the cache, based on the query type name and its serialized arguments.
+ */
+export type QueryCacheKey = string;
+
+/**
+ * Callback invoked when the cached result for an entry changes.
+ */
+export type QueryCacheListener<TDataType> = (result: QueryResultWithState<TDataType>) => void;
+
+/**
+ * Represents a single entry in the {@link QueryInstanceCache}.
+ * @template TDataType The type of data returned by the query.
+ */
+export interface QueryCacheEntry<TDataType> {
+    /**
+     * The cached query instance.
+     */
+    readonly instance: unknown;
+
+    /**
+     * The last result received from the query, if any.
+     */
+    lastResult?: QueryResultWithState<TDataType>;
+
+    /**
+     * The number of active subscribers holding a reference to this entry.
+     */
+    subscriberCount: number;
+
+    /**
+     * Set of listener callbacks that are notified when {@link lastResult} changes.
+     */
+    readonly listeners: Set<QueryCacheListener<TDataType>>;
+
+    /**
+     * Cleanup function returned by the first subscriber that starts the query connection.
+     * Called when the last subscriber releases the entry.
+     */
+    teardown?: () => void;
+
+    /**
+     * Whether an active subscription has been established for this entry.
+     */
+    subscribed: boolean;
+}
+
+/**
+ * Provides a cache for query instances, keyed by query type and serialized arguments.
+ *
+ * Two callers requesting the same query type with identical arguments receive the same
+ * cached instance and immediately see the last known result — without an additional
+ * round trip to the server. When the last subscriber releases its reference the entry
+ * is evicted.
+ */
+export class QueryInstanceCache {
+    private readonly _entries = new Map<QueryCacheKey, QueryCacheEntry<unknown>>();
+
+    /**
+     * Builds the cache key for a query.
+     * @param queryTypeName The name of the query constructor (i.e. `constructor.name`).
+     * @param args Optional arguments supplied to the query.
+     * @returns A stable string key.
+     */
+    buildKey(queryTypeName: string, args?: object): QueryCacheKey {
+        if (!args || Object.keys(args).length === 0) {
+            return `${queryTypeName}::`;
+        }
+
+        const sorted = Object.keys(args)
+            .sort()
+            .reduce<Record<string, unknown>>((accumulator, key) => {
+                accumulator[key] = (args as Record<string, unknown>)[key];
+                return accumulator;
+            }, {});
+
+        return `${queryTypeName}::${JSON.stringify(sorted)}`;
+    }
+
+    /**
+     * Returns a cached instance for the given key, or creates a new one using the provided factory.
+     * The subscriber count of the entry is incremented.
+     * @template TInstance The type of the query instance.
+     * @param key The cache key produced by {@link buildKey}.
+     * @param factory A zero-argument factory that creates a fresh query instance when one is not yet cached.
+     * @returns The cached (or newly created) instance and whether it was newly created.
+     */
+    getOrCreate<TInstance>(
+        key: QueryCacheKey,
+        factory: () => TInstance
+    ): { instance: TInstance; isNew: boolean } {
+        if (!this._entries.has(key)) {
+            const entry: QueryCacheEntry<unknown> = {
+                instance: factory(),
+                lastResult: undefined,
+                subscriberCount: 0,
+                listeners: new Set(),
+                subscribed: false,
+            };
+
+            this._entries.set(key, entry);
+            return { instance: entry.instance as TInstance, isNew: true };
+        }
+
+        const entry = this._entries.get(key)!;
+        return { instance: entry.instance as TInstance, isNew: false };
+    }
+
+    /**
+     * Increments the active subscriber count for the given key.
+     * Call from `useEffect` setup to pair with {@link release} in the cleanup.
+     * @param key The cache key produced by {@link buildKey}.
+     */
+    acquire(key: QueryCacheKey): void {
+        const entry = this._entries.get(key);
+
+        if (entry) {
+            entry.subscriberCount++;
+        }
+    }
+
+    /**
+     * Returns the last cached result for the given key, or `undefined` if no result has been stored yet.
+     * @template TDataType The type of data returned by the query.
+     * @param key The cache key produced by {@link buildKey}.
+     * @returns The last {@link QueryResultWithState}, or `undefined`.
+     */
+    getLastResult<TDataType>(key: QueryCacheKey): QueryResultWithState<TDataType> | undefined {
+        return this._entries.get(key)?.lastResult as QueryResultWithState<TDataType> | undefined;
+    }
+
+    /**
+     * Stores the most recent result for the given key and notifies all registered listeners.
+     * @template TDataType The type of data returned by the query.
+     * @param key The cache key produced by {@link buildKey}.
+     * @param result The result to store.
+     */
+    setLastResult<TDataType>(key: QueryCacheKey, result: QueryResultWithState<TDataType>): void {
+        const entry = this._entries.get(key);
+
+        if (entry) {
+            entry.lastResult = result as QueryResultWithState<unknown>;
+
+            for (const listener of entry.listeners) {
+                (listener as QueryCacheListener<TDataType>)(result);
+            }
+        }
+    }
+
+    /**
+     * Registers a listener that is invoked whenever the cached result for the given key changes.
+     * @template TDataType The type of data returned by the query.
+     * @param key The cache key produced by {@link buildKey}.
+     * @param listener The callback to register.
+     */
+    addListener<TDataType>(key: QueryCacheKey, listener: QueryCacheListener<TDataType>): void {
+        const entry = this._entries.get(key);
+
+        if (entry) {
+            entry.listeners.add(listener as QueryCacheListener<unknown>);
+        }
+    }
+
+    /**
+     * Removes a previously registered listener.
+     * @template TDataType The type of data returned by the query.
+     * @param key The cache key produced by {@link buildKey}.
+     * @param listener The callback to remove.
+     */
+    removeListener<TDataType>(key: QueryCacheKey, listener: QueryCacheListener<TDataType>): void {
+        const entry = this._entries.get(key);
+
+        if (entry) {
+            entry.listeners.delete(listener as QueryCacheListener<unknown>);
+        }
+    }
+
+    /**
+     * Stores a teardown function for the given key and marks the entry as subscribed.
+     * Called automatically when the last subscriber releases the entry.
+     * @param key The cache key produced by {@link buildKey}.
+     * @param teardown Cleanup function that disconnects the underlying query subscription.
+     */
+    setTeardown(key: QueryCacheKey, teardown: () => void): void {
+        const entry = this._entries.get(key);
+
+        if (entry) {
+            entry.teardown = teardown;
+            entry.subscribed = true;
+        }
+    }
+
+    /**
+     * Returns whether an active subscription exists for the given key.
+     * @param key The cache key to check.
+     * @returns `true` if a subscription has been established; `false` otherwise.
+     */
+    isSubscribed(key: QueryCacheKey): boolean {
+        return this._entries.get(key)?.subscribed ?? false;
+    }
+
+    /**
+     * Decrements the subscriber count for the given key. When the count reaches zero the teardown
+     * function is called (if set) and the entry is evicted.
+     * @param key The cache key produced by {@link buildKey}.
+     */
+    release(key: QueryCacheKey): void {
+        const entry = this._entries.get(key);
+
+        if (entry) {
+            entry.subscriberCount--;
+
+            if (entry.subscriberCount <= 0) {
+                entry.subscribed = false;
+                entry.teardown?.();
+                entry.teardown = undefined;
+
+                // Defer deletion so React Strict Mode re-mounts can re-acquire the entry.
+                setTimeout(() => {
+                    const current = this._entries.get(key);
+
+                    if (current && current.subscriberCount <= 0) {
+                        this._entries.delete(key);
+                    }
+                }, 0);
+            }
+        }
+    }
+
+    /**
+     * Returns whether an entry exists for the given key.
+     * @param key The cache key to check.
+     * @returns `true` if an entry exists; `false` otherwise.
+     */
+    has(key: QueryCacheKey): boolean {
+        return this._entries.has(key);
+    }
+}

package/queries/QueryTransportMethod.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Defines the transport method used for observable query connections.
+ */
+export enum QueryTransportMethod {
+    /**
+     * Use WebSocket for real-time data streaming.
+     */
+    WebSocket = 'webSocket',
+
+    /**
+     * Use Server-Sent Events (SSE) for real-time data streaming.
+     */
+    ServerSentEvents = 'serverSentEvents',
+}

package/queries/ReconnectPolicy.ts

@@ -0,0 +1,68 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { IReconnectPolicy, ReconnectCallback } from './IReconnectPolicy';
+
+/**
+ * Default exponential back-off reconnect policy shared by all observable query connections.
+ *
+ * Delay formula: `Math.min(initialDelayMs + delayStepMs * attempt, maxDelayMs)`
+ *
+ * With the default parameters:
+ * - Attempt 1 → 1 000 ms
+ * - Attempt 2 → 1 500 ms
+ * - …
+ * - Attempt 19+ → 10 000 ms (capped)
+ * - After 100 attempts → abandoned (returns `false`)
+ */
+export class ReconnectPolicy implements IReconnectPolicy {
+    private _attempt = 0;
+    private _timer?: ReturnType<typeof setTimeout>;
+
+    /**
+     * Initializes a new instance of {@link ReconnectPolicy}.
+     * @param {number} maxAttempts Maximum number of reconnect attempts before giving up (default: 100).
+     * @param {number} initialDelayMs Base delay in milliseconds added to every attempt (default: 500).
+     * @param {number} delayStepMs Additional delay per attempt in milliseconds (default: 500).
+     * @param {number} maxDelayMs Upper bound on the computed delay in milliseconds (default: 10 000).
+     */
+    constructor(
+        private readonly _maxAttempts: number = 100,
+        private readonly _initialDelayMs: number = 500,
+        private readonly _delayStepMs: number = 500,
+        private readonly _maxDelayMs: number = 10_000,
+    ) {}
+
+    /** @inheritdoc */
+    get attempt(): number {
+        return this._attempt;
+    }
+
+    /** @inheritdoc */
+    schedule(onReconnect: ReconnectCallback, label: string): boolean {
+        if (this._attempt >= this._maxAttempts) {
+            console.log(`Reconnect: abandoned after ${this._maxAttempts} attempts for '${label}'`);
+            return false;
+        }
+
+        this._attempt++;
+        const delay = Math.min(this._initialDelayMs + this._delayStepMs * this._attempt, this._maxDelayMs);
+        console.log(`Reconnect: attempt ${this._attempt} in ${delay}ms for '${label}'`);
+        this._timer = setTimeout(onReconnect, delay);
+        return true;
+    }
+
+    /** @inheritdoc */
+    reset(): void {
+        this._attempt = 0;
+        this.cancel();
+    }
+
+    /** @inheritdoc */
+    cancel(): void {
+        if (this._timer) {
+            clearTimeout(this._timer);
+            this._timer = undefined;
+        }
+    }
+}

package/queries/ServerSentEventHubConnection.ts

@@ -0,0 +1,309 @@
+// 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 { IObservableQueryHubConnection } from './IObservableQueryHubConnection';
+import { DataReceived } from './ObservableQueryConnection';
+import { HubConnectionKeepAlive } from './HubConnectionKeepAlive';
+import { IReconnectPolicy } from './IReconnectPolicy';
+import { ReconnectPolicy } from './ReconnectPolicy';
+import { QueryResult } from './QueryResult';
+import { HubMessage, HubMessageType, SubscriptionRequest } from './WebSocketHubConnection';
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+interface ActiveSubscription {
+    request: SubscriptionRequest;
+    callback: DataReceived<any>;
+}
+
+/**
+ * A multiplexed SSE hub connection that uses EventSource for server→client streaming
+ * and fetch POST requests for client→server subscribe/unsubscribe commands.
+ *
+ * Protocol:
+ * 1. Open EventSource to the SSE hub endpoint.
+ * 2. Server sends a {@link HubMessageType.Connected} message with the connection identifier.
+ * 3. Client sends POST to subscribe/unsubscribe endpoints using the connection identifier.
+ * 4. Server streams {@link HubMessageType.QueryResult} messages tagged with queryId.
+ * 5. When EventSource closes, server cleans up all subscriptions for this connection.
+ */
+export class ServerSentEventHubConnection implements IObservableQueryHubConnection {
+    private _eventSource?: EventSource;
+    private _connectionId?: string;
+    private _disconnected = false;
+    private _subscriptions: Map<string, ActiveSubscription> = new Map();
+    private _pendingSubscriptions: Map<string, ActiveSubscription> = new Map();
+    private _lastPongLatency: number = 0;
+    private _latencySamples: number[] = [];
+    private _connectTimeoutTimer?: ReturnType<typeof setTimeout>;
+    private readonly _keepAlive: HubConnectionKeepAlive;
+
+    /**
+     * Initializes a new instance of {@link ServerSentEventHubConnection}.
+     * @param {string} _sseUrl The SSE hub endpoint URL (e.g. `http://localhost:5000/.cratis/queries/sse`).
+     * @param {string} _subscribeUrl The subscribe POST endpoint URL.
+     * @param {string} _unsubscribeUrl The unsubscribe POST endpoint URL.
+     * @param {string} _microservice The microservice name to pass as a query argument.
+     * @param {number} keepAliveIntervalMs How long without any server message before the connection
+     *   is considered stale and a reconnect is forced (default: 30 000 ms).
+     * @param {number} connectTimeoutMs How long to wait for the {@link HubMessageType.Connected}
+     *   message after the HTTP connection opens before giving up and retrying (default: 15 000 ms).
+     * @param {IReconnectPolicy} _policy The reconnect policy to use (default: {@link ReconnectPolicy}).
+     */
+    constructor(
+        private readonly _sseUrl: string,
+        private readonly _subscribeUrl: string,
+        private readonly _unsubscribeUrl: string,
+        private readonly _microservice: string,
+        keepAliveIntervalMs: number = 30000,
+        private readonly _connectTimeoutMs: number = 15000,
+        private readonly _policy: IReconnectPolicy = new ReconnectPolicy()
+    ) {
+        // SSE is server→client only: the client cannot send pings. Instead we watch for
+        // inactivity — if the server stops sending messages (including its own keep-alive
+        // pings) for the entire interval, the connection is stale and we reconnect.
+        this._keepAlive = new HubConnectionKeepAlive(keepAliveIntervalMs, () => {
+            if (!this._disconnected && this._subscriptions.size > 0) {
+                console.warn(`SSE hub: no messages received for ${keepAliveIntervalMs}ms, reconnecting '${this._sseUrl}'`);
+                this.reconnect();
+            }
+        });
+    }
+
+    /** @inheritdoc */
+    get queryCount(): number {
+        return this._subscriptions.size;
+    }
+
+    /** @inheritdoc */
+    get lastPingLatency(): number {
+        return this._lastPongLatency;
+    }
+
+    /** @inheritdoc */
+    get averageLatency(): number {
+        if (this._latencySamples.length === 0) return 0;
+        return this._latencySamples.reduce((a, b) => a + b, 0) / this._latencySamples.length;
+    }
+
+    /** @inheritdoc */
+    subscribe(queryId: string, request: SubscriptionRequest, callback: DataReceived<any>): void {
+        const sub: ActiveSubscription = { request, callback };
+        this._subscriptions.set(queryId, sub);
+
+        this.ensureConnected();
+
+        if (this._connectionId) {
+            this.sendSubscribe(queryId, request);
+        } else {
+            // Not yet connected, queue for when Connected message arrives.
+            this._pendingSubscriptions.set(queryId, sub);
+        }
+    }
+
+    /** @inheritdoc */
+    unsubscribe(queryId: string): void {
+        this._subscriptions.delete(queryId);
+        this._pendingSubscriptions.delete(queryId);
+
+        if (this._connectionId) {
+            this.sendUnsubscribe(queryId);
+        }
+
+        if (this._subscriptions.size === 0) {
+            this.close();
+        }
+    }
+
+    /** @inheritdoc */
+    dispose(): void {
+        this._disconnected = true;
+        this._subscriptions.clear();
+        this._pendingSubscriptions.clear();
+        this._policy.cancel();
+        this._keepAlive.stop();
+        this.clearConnectTimeout();
+        this._eventSource?.close();
+        this._eventSource = undefined;
+        this._connectionId = undefined;
+    }
+
+    private ensureConnected(): void {
+        if (this._disconnected) {
+            this._disconnected = false;
+        }
+
+        if (this._eventSource && this._eventSource.readyState !== EventSource.CLOSED) {
+            return;
+        }
+
+        this.openEventSource();
+    }
+
+    private close(): void {
+        this._disconnected = true;
+        this._policy.cancel();
+        this._keepAlive.stop();
+        this.clearConnectTimeout();
+        this._eventSource?.close();
+        this._eventSource = undefined;
+        this._connectionId = undefined;
+    }
+
+    private openEventSource(): void {
+        let url = this._sseUrl;
+        if (this._microservice?.length > 0) {
+            const param = `${Globals.microserviceWSQueryArgument}=${encodeURIComponent(this._microservice)}`;
+            url += (url.includes('?') ? '&' : '?') + param;
+        }
+
+        this._connectionId = undefined;
+        this._eventSource = new EventSource(url);
+
+        this._eventSource.onopen = () => {
+            if (this._disconnected) 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._connectionId) {
+                    console.warn(`SSE hub: no Connected message within ${this._connectTimeoutMs}ms, retrying '${url}'`);
+                    this.reconnect();
+                }
+            }, this._connectTimeoutMs);
+        };
+
+        this._eventSource.onmessage = (event: MessageEvent) => {
+            if (this._disconnected) return;
+            this._keepAlive.recordActivity();
+            this.handleMessage(event.data as string);
+        };
+
+        this._eventSource.onerror = () => {
+            if (this._disconnected) return;
+            console.warn(`SSE hub connection error: '${url}'`);
+            this.reconnect();
+        };
+    }
+
+    private reconnect(): void {
+        this._keepAlive.stop();
+        this.clearConnectTimeout();
+
+        // Close the EventSource so the reconnect policy manages the schedule.
+        this._eventSource?.close();
+        this._eventSource = undefined;
+        this._connectionId = undefined;
+
+        // Move all active subscriptions to pending so they re-subscribe when
+        // the next Connected message arrives after the managed reconnect.
+        for (const [queryId, sub] of this._subscriptions) {
+            this._pendingSubscriptions.set(queryId, sub);
+        }
+
+        if (this._subscriptions.size === 0) return;
+
+        this._policy.schedule(() => {
+            if (!this._disconnected && this._subscriptions.size > 0) {
+                this.openEventSource();
+            }
+        }, this._sseUrl);
+    }
+
+    private clearConnectTimeout(): void {
+        if (this._connectTimeoutTimer !== undefined) {
+            clearTimeout(this._connectTimeoutTimer);
+            this._connectTimeoutTimer = undefined;
+        }
+    }
+
+    private handleMessage(rawData: string): void {
+        try {
+            const message = JSON.parse(rawData) as HubMessage;
+
+            switch (message.type) {
+                case HubMessageType.Connected:
+                    this.handleConnected(message);
+                    break;
+                case HubMessageType.QueryResult:
+                    this.handleQueryResult(message);
+                    break;
+                case HubMessageType.Ping:
+                    // Server-sent keep-alive ping — activity already recorded in onmessage.
+                    break;
+                case HubMessageType.Unauthorized:
+                    console.warn(`SSE hub: query '${message.queryId}' unauthorized`);
+                    break;
+                case HubMessageType.Error:
+                    console.error(`SSE hub: query '${message.queryId}' error:`, message.payload);
+                    break;
+            }
+        } catch (error) {
+            console.error('SSE hub: error parsing message', error);
+        }
+    }
+
+    private handleConnected(message: HubMessage): void {
+        this._connectionId = message.payload as string;
+        console.log(`SSE hub: connected with id '${this._connectionId}'`);
+
+        // Connected message arrived — cancel the connect timeout.
+        this.clearConnectTimeout();
+
+        // Send all pending subscriptions now that we have a connection ID.
+        for (const [queryId, sub] of this._pendingSubscriptions) {
+            this.sendSubscribe(queryId, sub.request);
+        }
+        this._pendingSubscriptions.clear();
+    }
+
+    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 sendSubscribe(queryId: string, request: SubscriptionRequest): void {
+        if (!this._connectionId) return;
+
+        const body = {
+            connectionId: this._connectionId,
+            queryId,
+            request,
+        };
+
+        fetch(this._subscribeUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        }).catch(error => {
+            console.error(`SSE hub: subscribe POST failed for '${queryId}'`, error);
+        });
+    }
+
+    private sendUnsubscribe(queryId: string): void {
+        if (!this._connectionId) return;
+
+        const body = {
+            connectionId: this._connectionId,
+            queryId,
+        };
+
+        fetch(this._unsubscribeUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        }).catch(error => {
+            console.error(`SSE hub: unsubscribe POST failed for '${queryId}'`, error);
+        });
+    }
+}