@cratis/arc 20.27.2 → 20.33.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/arc",
-    "version": "20.27.2",
+    "version": "20.33.1",
     "description": "",
     "author": "Cratis",
     "license": "MIT",

package/queries/IObservableQueryDiagnostics.ts

@@ -0,0 +1,40 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Observable } from 'rxjs';
+import { ObservableQueryDiagnosticsSnapshot } from './ObservableQueryDiagnosticsSnapshot';
+
+/**
+ * Contract for the observable query diagnostics service.
+ *
+ * The service aggregates runtime state from the query cache, the multiplexer connection pool,
+ * and (optionally) component ownership maps into a single snapshot. Snapshots can be polled
+ * via {@link getSnapshot} or observed through {@link snapshots$}.
+ */
+export interface IObservableQueryDiagnostics {
+    /**
+     * Returns the current diagnostics snapshot.
+     */
+    getSnapshot(): ObservableQueryDiagnosticsSnapshot;
+
+    /**
+     * Stream of diagnostics snapshots.
+     */
+    readonly snapshots$: Observable<ObservableQueryDiagnosticsSnapshot>;
+
+    /**
+     * Associates a human-readable owner label with a cache key.
+     * Used by opt-in hook options (`owner?: string`) to identify which component
+     * is using which query instance.
+     * @param cacheKey The cache key to tag.
+     * @param owner A descriptive label for the owning component (e.g. component name).
+     */
+    beginTracking(cacheKey: string, owner: string): void;
+
+    /**
+     * Removes the ownership association for the given cache key.
+     * Should be called when the component unmounts or the query hook cleans up.
+     * @param cacheKey The cache key to un-tag.
+     */
+    endTracking(cacheKey: string): void;
+}

package/queries/IObservableQueryHubConnection.ts

@@ -19,6 +19,11 @@ export interface IObservableQueryHubConnection {
      */
     readonly queryCount: number;
 
+    /**
+     * Gets whether the physical connection is currently established.
+     */
+    readonly isConnected: boolean;
+
     /**
      * Gets the latency of the last ping/pong sequence in milliseconds.
      */

package/queries/ObservableQueryDiagnostics.ts

@@ -0,0 +1,123 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Observable, Subject } from 'rxjs';
+import { QueryInstanceCache } from './QueryInstanceCache';
+import { ObservableQueryMultiplexer } from './ObservableQueryMultiplexer';
+import { IObservableQueryDiagnostics } from './IObservableQueryDiagnostics';
+import {
+    ObservableQueryDiagnosticsSnapshot,
+    MultiplexerDiagnostics,
+    TransportDiagnostics,
+    HealthDiagnostics,
+    OwnershipDiagnostics,
+} from './ObservableQueryDiagnosticsSnapshot';
+
+/**
+ * Implements the {@link IObservableQueryDiagnostics} contract by collecting live state from
+ * the {@link QueryInstanceCache} and the shared {@link ObservableQueryMultiplexer}.
+ */
+export class ObservableQueryDiagnostics implements IObservableQueryDiagnostics {
+    private readonly _snapshots = new Subject<ObservableQueryDiagnosticsSnapshot>();
+    private readonly _ownersByKey = new Map<string, string>();
+
+    /**
+     * Initializes a new instance of {@link ObservableQueryDiagnostics}.
+     * @param _cache The {@link QueryInstanceCache} whose state will be reflected.
+     * @param _getMultiplexer Factory that returns the current shared multiplexer, or {@code undefined}.
+     * @param _getTransportConfig Factory that returns the current transport diagnostics.
+     */
+    constructor(
+        private readonly _cache: QueryInstanceCache,
+        private readonly _getMultiplexer: () => ObservableQueryMultiplexer | undefined,
+        private readonly _getTransportConfig: () => TransportDiagnostics,
+    ) {}
+
+    /**
+     * Stream of diagnostics snapshots.
+     */
+    get snapshots$(): Observable<ObservableQueryDiagnosticsSnapshot> {
+        return this._snapshots.asObservable();
+    }
+
+    /** @inheritdoc */
+    getSnapshot(): ObservableQueryDiagnosticsSnapshot {
+        const snapshot = this._createSnapshot();
+        this._publishSnapshot(snapshot);
+        return snapshot;
+    }
+
+    /** @inheritdoc */
+    beginTracking(cacheKey: string, owner: string): void {
+        this._ownersByKey.set(cacheKey, owner);
+        this._publishSnapshot(this._createSnapshot());
+    }
+
+    /** @inheritdoc */
+    endTracking(cacheKey: string): void {
+        this._ownersByKey.delete(cacheKey);
+        this._publishSnapshot(this._createSnapshot());
+    }
+
+    private _buildMultiplexerDiagnostics(): MultiplexerDiagnostics {
+        const mux = this._getMultiplexer();
+        if (!mux) {
+            return {
+                isConnected: false,
+                configuredConnectionCount: 0,
+                effectiveConnectionCount: 0,
+                activeConnectionCount: 0,
+                connections: [],
+            };
+        }
+
+        const connections = mux.getConnectionsSnapshot();
+        const activeConnectionCount = connections.filter(c => c.isConnected).length;
+
+        return {
+            isConnected: activeConnectionCount > 0,
+            configuredConnectionCount: connections.length,
+            effectiveConnectionCount: connections.length,
+            activeConnectionCount,
+            connections,
+        };
+    }
+
+    private _createSnapshot(): ObservableQueryDiagnosticsSnapshot {
+        const transport = this._getTransportConfig();
+        const multiplexer = this._buildMultiplexerDiagnostics();
+        const cache = this._cache.getDiagnosticsSnapshot();
+
+        const ownersByQueryKey: Record<string, string> = {};
+        const queriesByOwner: Record<string, string[]> = {};
+
+        for (const [key, owner] of this._ownersByKey) {
+            ownersByQueryKey[key] = owner;
+            if (!queriesByOwner[owner]) {
+                queriesByOwner[owner] = [];
+            }
+            queriesByOwner[owner].push(key);
+        }
+
+        const ownership: OwnershipDiagnostics = { ownersByQueryKey, queriesByOwner };
+
+        const disconnectedQueryCount = multiplexer.connections.filter(c => !c.isConnected).length;
+        const health: HealthDiagnostics = {
+            allQueriesConnected: multiplexer.isConnected && cache.healthy,
+            disconnectedQueryCount,
+        };
+
+        return {
+            health,
+            transport,
+            multiplexer,
+            cache,
+            ownership,
+            timestamp: new Date().toISOString(),
+        };
+    }
+
+    private _publishSnapshot(snapshot: ObservableQueryDiagnosticsSnapshot): void {
+        this._snapshots.next(snapshot);
+    }
+}

package/queries/ObservableQueryDiagnosticsSnapshot.ts

@@ -0,0 +1,112 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Describes the state of a single physical hub connection in the multiplexer.
+ */
+export interface MultiplexerConnectionState {
+    /** Zero-based slot index in the connection pool. */
+    index: number;
+    /** Whether the connection is currently established and receiving messages. */
+    isConnected: boolean;
+    /** Number of active query subscriptions routed through this connection. */
+    queryCount: number;
+}
+
+/**
+ * Multiplexer transport diagnostics.
+ */
+export interface MultiplexerDiagnostics {
+    /** Whether at least one connection in the pool is currently connected. */
+    isConnected: boolean;
+    /** Number of physical connections configured (from Arc props). */
+    configuredConnectionCount: number;
+    /** Number of connections actually created after SSE cap logic. */
+    effectiveConnectionCount: number;
+    /** Number of connections that are currently connected. */
+    activeConnectionCount: number;
+    /** Per-connection state for the current pool. */
+    connections: MultiplexerConnectionState[];
+}
+
+/**
+ * A single entry in the query instance cache.
+ */
+export interface CacheEntryDiagnostics {
+    /** The full cache key (type name + serialized args). */
+    key: string;
+    /** Query name parsed from the key prefix. */
+    queryName: string;
+    /** Number of components currently holding a reference to this entry. */
+    subscriberCount: number;
+    /** Number of result listeners registered on this entry. */
+    listenerCount: number;
+    /** Whether an active server subscription has been established. */
+    subscribed: boolean;
+    /** Whether a cached result has been received at least once. */
+    hasResult: boolean;
+    /** Estimated size of the cached result in bytes (JSON.stringify length, 0 on error). */
+    estimatedBytes: number;
+}
+
+/**
+ * Query instance cache diagnostics.
+ */
+export interface CacheDiagnostics {
+    /** Whether all subscribed entries are connected (no entry has subscriberCount > 0 but subscribed == false). */
+    healthy: boolean;
+    /** Total number of entries in the cache (including unsubscribed retention entries). */
+    entryCount: number;
+    /** Total estimated size of all cached results in bytes. */
+    estimatedBytes: number;
+    /** Per-entry diagnostics. */
+    entries: CacheEntryDiagnostics[];
+}
+
+/**
+ * Transport configuration diagnostics.
+ */
+export interface TransportDiagnostics {
+    /** The configured query transport method (e.g. ServerSentEvents or WebSocket). */
+    queryTransportMethod: string;
+    /** Whether direct per-query connections are used instead of the multiplexer hub. */
+    queryDirectMode: boolean;
+}
+
+/**
+ * Overall health summary.
+ */
+export interface HealthDiagnostics {
+    /** True when every entry with active subscribers is also subscribed. */
+    allQueriesConnected: boolean;
+    /** Number of entries that have subscribers but are not currently subscribed. */
+    disconnectedQueryCount: number;
+}
+
+/**
+ * Ownership map entry.
+ */
+export interface OwnershipDiagnostics {
+    /** Map of cache key → owner label (populated by opt-in owner tagging). */
+    ownersByQueryKey: Record<string, string>;
+    /** Map of owner label → cache keys. */
+    queriesByOwner: Record<string, string[]>;
+}
+
+/**
+ * A point-in-time snapshot of observable query diagnostics.
+ */
+export interface ObservableQueryDiagnosticsSnapshot {
+    /** Overall health summary. */
+    health: HealthDiagnostics;
+    /** Transport configuration. */
+    transport: TransportDiagnostics;
+    /** Multiplexer connection pool state. */
+    multiplexer: MultiplexerDiagnostics;
+    /** Query instance cache state. */
+    cache: CacheDiagnostics;
+    /** Opt-in component ownership mapping. */
+    ownership: OwnershipDiagnostics;
+    /** UTC timestamp when this snapshot was taken. */
+    timestamp: string;
+}

package/queries/ObservableQueryMultiplexer.ts

@@ -6,6 +6,7 @@ import { IObservableQueryHubConnection } from './IObservableQueryHubConnection';
 import { DataReceived } from './ObservableQueryConnection';
 import { SubscriptionRequest } from './WebSocketHubConnection';
 import { Globals } from '../Globals';
+import { MultiplexerConnectionState } from './ObservableQueryDiagnosticsSnapshot';
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
@@ -137,6 +138,18 @@ export class ObservableQueryMultiplexer {
 
         return request;
     }
+
+    /**
+     * Returns a snapshot of the per-connection state for diagnostics.
+     * @returns An array describing each slot in the connection pool.
+     */
+    getConnectionsSnapshot(): MultiplexerConnectionState[] {
+        return this._connections.map((conn, index) => ({
+            index,
+            isConnected: conn.isConnected,
+            queryCount: conn.queryCount,
+        }));
+    }
 }
 
 /**
@@ -217,3 +230,10 @@ export function resetSharedMultiplexer(): void {
     _sharedMultiplexer = undefined;
     _sharedMultiplexerKey = '';
 }
+
+/**
+ * Returns the current shared multiplexer instance, or {@code undefined} if none has been created yet.
+ */
+export function getSharedMultiplexer(): ObservableQueryMultiplexer | undefined {
+    return _sharedMultiplexer;
+}

package/queries/QueryInstanceCache.ts

@@ -2,6 +2,7 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { QueryResultWithState } from './QueryResultWithState';
+import { CacheDiagnostics, CacheEntryDiagnostics } from './ObservableQueryDiagnosticsSnapshot';
 
 /**
  * Represents a key that uniquely identifies a query instance in the cache, based on the query type name and its serialized arguments.
@@ -360,4 +361,50 @@ export class QueryInstanceCache {
             this._pendingDispose = undefined;
         }
     }
+
+    /**
+     * Returns a diagnostics snapshot of the current cache state.
+     * @returns A {@link CacheDiagnostics} describing all entries.
+     */
+    getDiagnosticsSnapshot(): CacheDiagnostics {
+        const entries: CacheEntryDiagnostics[] = [];
+        let totalBytes = 0;
+        let unhealthyCount = 0;
+
+        for (const [key, entry] of this._entries) {
+            const colonIndex = key.indexOf('::');
+            const queryName = colonIndex >= 0 ? key.substring(0, colonIndex) : key;
+
+            let estimatedBytes = 0;
+            try {
+                if (entry.lastResult !== undefined) {
+                    estimatedBytes = JSON.stringify(entry.lastResult).length;
+                }
+            } catch {
+                // Ignore serialization errors
+            }
+
+            if (entry.subscriberCount > 0 && !entry.subscribed) {
+                unhealthyCount++;
+            }
+
+            totalBytes += estimatedBytes;
+            entries.push({
+                key,
+                queryName,
+                subscriberCount: entry.subscriberCount,
+                listenerCount: entry.listeners.size,
+                subscribed: entry.subscribed,
+                hasResult: entry.lastResult !== undefined,
+                estimatedBytes,
+            });
+        }
+
+        return {
+            healthy: unhealthyCount === 0,
+            entryCount: this._entries.size,
+            estimatedBytes: totalBytes,
+            entries,
+        };
+    }
 }

package/queries/ServerSentEventHubConnection.ts

@@ -83,6 +83,11 @@ export class ServerSentEventHubConnection implements IObservableQueryHubConnecti
         return this._subscriptions.size;
     }
 
+    /** @inheritdoc */
+    get isConnected(): boolean {
+        return this._connectionId !== undefined && this._eventSource?.readyState === EventSource.OPEN;
+    }
+
     /** @inheritdoc */
     get lastPingLatency(): number {
         return this._lastPongLatency;

package/queries/WebSocketHubConnection.ts

@@ -98,6 +98,13 @@ export class WebSocketHubConnection {
         return this._subscriptions.size;
     }
 
+    /**
+     * Gets whether the WebSocket connection is currently open.
+     */
+    get isConnected(): boolean {
+        return this._socket?.readyState === WebSocket.OPEN;
+    }
+
     /**
      * Gets the latency of the last ping/pong sequence in milliseconds.
      */

package/queries/for_ObservableQueryDiagnostics/when_tracking_owners.ts

@@ -0,0 +1,49 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, it } from 'vitest';
+import { ObservableQueryDiagnostics, QueryInstanceCache } from '../../queries';
+
+describe('when tracking query owners', () => {
+    it('should publish diagnostics snapshots through an observable', () => {
+        const diagnostics = new ObservableQueryDiagnostics(
+            new QueryInstanceCache(0),
+            () => undefined,
+            () => ({ queryTransportMethod: 'ServerSentEvents', queryDirectMode: false })
+        );
+
+        const snapshots: string[] = [];
+        diagnostics.snapshots$.subscribe(snapshot => snapshots.push(JSON.stringify(snapshot.ownership)));
+
+        diagnostics.beginTracking('cache-key', 'OrdersPage');
+        snapshots.should.have.lengthOf(1);
+        snapshots[0].should.contain('cache-key');
+        snapshots[0].should.contain('OrdersPage');
+
+        diagnostics.endTracking('cache-key');
+        snapshots.should.have.lengthOf(2);
+        snapshots[1].should.equal('{"ownersByQueryKey":{},"queriesByOwner":{}}');
+    });
+
+    it('should not dispatch browser events when publishing snapshots', () => {
+        const diagnostics = new ObservableQueryDiagnostics(
+            new QueryInstanceCache(0),
+            () => undefined,
+            () => ({ queryTransportMethod: 'ServerSentEvents', queryDirectMode: false })
+        );
+
+        const globalWithWindow = globalThis as Record<string, unknown>;
+        const originalWindow = globalWithWindow.window;
+        const dispatchEvent = function(): never {
+            throw new Error('dispatchEvent should not be called');
+        };
+
+        try {
+            globalWithWindow.window = { dispatchEvent };
+            diagnostics.beginTracking('cache-key', 'OrdersPage');
+            diagnostics.endTracking('cache-key');
+        } finally {
+            globalWithWindow.window = originalWindow;
+        }
+    });
+});

package/queries/for_ObservableQueryMultiplexer/when_getting_or_creating/with_a_changed_cache_key.ts

@@ -20,7 +20,8 @@ describe('when getting or creating with a changed cache key', () => {
                 lastPingLatency: 0,
                 averageLatency: 0,
                 subscribe: () => {},
-                unsubscribe: () => {},
+                    isConnected: false,
+                    unsubscribe: () => {},
                 dispose: () => { disposedConnectionCount++; },
             };
         };

package/queries/for_ObservableQueryMultiplexer/when_getting_or_creating/with_a_new_cache_key.ts

@@ -14,7 +14,7 @@ describe('when getting or creating with a new cache key', () => {
         factoryCallCount = 0;
         const factory = (): IObservableQueryHubConnection => {
             factoryCallCount++;
-            return { queryCount: 0, lastPingLatency: 0, averageLatency: 0, subscribe: () => {}, unsubscribe: () => {}, dispose: () => {} };
+            return { queryCount: 0, lastPingLatency: 0, averageLatency: 0, isConnected: false, subscribe: () => {}, unsubscribe: () => {}, dispose: () => {} };
         };
         multiplexer = getOrCreateMultiplexer(factory, 'test-key', 1);
     });

package/queries/for_ObservableQueryMultiplexer/when_getting_or_creating/with_an_explicit_size.ts

@@ -14,7 +14,7 @@ describe('when getting or creating with an explicit size', () => {
         factoryCallCount = 0;
         const factory = (): IObservableQueryHubConnection => {
             factoryCallCount++;
-            return { queryCount: 0, lastPingLatency: 0, averageLatency: 0, subscribe: () => {}, unsubscribe: () => {}, dispose: () => {} };
+            return { queryCount: 0, lastPingLatency: 0, averageLatency: 0, isConnected: false, subscribe: () => {}, unsubscribe: () => {}, dispose: () => {} };
         };
         multiplexer = getOrCreateMultiplexer(factory, 'test-key', 3);
     });

package/queries/for_ObservableQueryMultiplexer/when_getting_or_creating/with_the_same_cache_key.ts

@@ -15,7 +15,7 @@ describe('when getting or creating with the same cache key', () => {
         factoryCallCount = 0;
         const factory = (): IObservableQueryHubConnection => {
             factoryCallCount++;
-            return { queryCount: 0, lastPingLatency: 0, averageLatency: 0, subscribe: () => {}, unsubscribe: () => {}, dispose: () => {} };
+            return { queryCount: 0, lastPingLatency: 0, averageLatency: 0, isConnected: false, subscribe: () => {}, unsubscribe: () => {}, dispose: () => {} };
         };
         first = getOrCreateMultiplexer(factory, 'test-key', 1);
         second = getOrCreateMultiplexer(factory, 'test-key', 1);

package/queries/index.ts

@@ -35,4 +35,7 @@ export * from './QueryInstanceCache';
 export * from './IQueryProvider';
 export * from './QueryProvider';
 export * from './QueryValidator';
+export * from './IObservableQueryDiagnostics';
+export * from './ObservableQueryDiagnostics';
+export * from './ObservableQueryDiagnosticsSnapshot';
 import '../validation';