@cratis/arc 22.0.2 → 22.1.0

package/queries/for_ObservableQueryFor/when_subscribing/with_direct_mode_disabled_and_sse_transport.ts

@@ -8,63 +8,135 @@ import { QueryTransportMethod } from '../../QueryTransportMethod';
 import { ObservableQuerySubscription } from '../../ObservableQuerySubscription';
 import { SSE_HUB_ROUTE } from '../../ServerSentEventQueryConnection';
 import { resetSharedMultiplexer } from '../../ObservableQueryMultiplexer';
+import { HubMessageType } from '../../WebSocketHubConnection';
 
 import * as sinon from 'sinon';
 
-describe('when subscribing with direct mode disabled and SSE transport', given(an_observable_query_for, context => {
-    let callback: sinon.SinonStub;
-    let subscription: ObservableQuerySubscription<string>;
-    let capturedUrl: string;
-    let originalQueryDirectMode: boolean;
-    let originalTransportMethod: QueryTransportMethod;
-
-    beforeEach(() => {
-        originalQueryDirectMode = Globals.queryDirectMode;
-        originalTransportMethod = Globals.queryTransportMethod;
-        resetSharedMultiplexer();
-
-        Globals.queryDirectMode = false;
-        Globals.queryTransportMethod = QueryTransportMethod.ServerSentEvents;
-
-        context.query.setOrigin('https://example.com');
-        callback = sinon.stub();
-
-        // EventSource doesn't exist in Node.js — inject a fake via globalThis
-        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(),
-            });
+describe(
+    'when subscribing with direct mode disabled and SSE transport',
+    given(an_observable_query_for, (context) => {
+        let callback: sinon.SinonStub;
+        let subscription: ObservableQuerySubscription<string>;
+        let capturedUrl: string;
+        let fetchStub: sinon.SinonStub;
+        let eventSourceInstance: EventSource & {
+            onopen: (() => void) | null;
+            onmessage: ((event: { data: string }) => void) | null;
         };
-        (globalThis as Record<string, unknown>)['EventSource'] = FakeEventSourceConstructor;
+        let originalQueryDirectMode: boolean;
+        let originalTransportMethod: QueryTransportMethod;
+
+        beforeEach(() => {
+            originalQueryDirectMode = Globals.queryDirectMode;
+            originalTransportMethod = Globals.queryTransportMethod;
+            resetSharedMultiplexer();
+
+            Globals.queryDirectMode = false;
+            Globals.queryTransportMethod = QueryTransportMethod.ServerSentEvents;
+
+            context.query.setOrigin('https://example.com');
+            callback = sinon.stub();
+
+            // EventSource doesn't exist in Node.js — inject a fake via globalThis
+            const FakeEventSourceConstructor = function (this: EventSource, url: string) {
+                capturedUrl = url;
+                eventSourceInstance = this as EventSource & {
+                    onopen: (() => void) | null;
+                    onmessage: ((event: { data: string }) => void) | null;
+                };
+                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;
+            fetchStub = sinon.stub().resolves({ ok: true } as Response);
+            (globalThis as Record<string, unknown>)['fetch'] = fetchStub;
+
+            subscription = context.query.subscribe(callback, { id: 'test-id' });
+            eventSourceInstance.onopen?.();
+            // An older Arc server omits subscription capabilities from Connected, so this fixture
+            // intentionally exercises legacy missing-revision result frames.
+            eventSourceInstance.onmessage?.({
+                data: JSON.stringify({
+                    type: HubMessageType.Connected,
+                    payload: 'connection-1',
+                }),
+            });
 
-        subscription = context.query.subscribe(callback, { id: 'test-id' });
-    });
+            let subscribeRequest: { queryId: string; revision?: number };
+            try {
+                subscribeRequest = JSON.parse(fetchStub.firstCall.args[1].body as string);
+            } catch (error) {
+                throw new Error('The SSE hub subscribe request was not valid JSON', {
+                    cause: error,
+                });
+            }
+            eventSourceInstance.onmessage?.({
+                data: JSON.stringify({
+                    type: HubMessageType.QueryResult,
+                    queryId: subscribeRequest.queryId,
+                    payload: {
+                        data: 'ready result',
+                        isSuccess: true,
+                        isAuthorized: true,
+                        isValid: true,
+                        hasExceptions: false,
+                        validationResults: [],
+                        exceptionMessages: [],
+                        exceptionStackTrace: '',
+                        paging: { page: 0, size: 0, totalItems: 0, totalPages: 0 },
+                    },
+                }),
+            });
+        });
+
+        afterEach(() => {
+            Globals.queryDirectMode = originalQueryDirectMode;
+            Globals.queryTransportMethod = originalTransportMethod;
+            if (subscription) {
+                subscription.unsubscribe();
+            }
+            delete (globalThis as Record<string, unknown>)['EventSource'];
+            delete (globalThis as Record<string, unknown>)['fetch'];
+            resetSharedMultiplexer();
+        });
+
+        it('should connect to the centralized SSE hub endpoint', () => {
+            capturedUrl.should.include(SSE_HUB_ROUTE);
+        });
+
+        it('should not include query name in URL since subscriptions are done via POST', () => {
+            capturedUrl.should.not.include('query=');
+        });
 
-    afterEach(() => {
-        Globals.queryDirectMode = originalQueryDirectMode;
-        Globals.queryTransportMethod = originalTransportMethod;
-        if (subscription) {
-            subscription.unsubscribe();
+        it('should return a subscription', () => {
+            (subscription === undefined).should.equal(false);
+        });
+
+        it('should omit revisions when the server does not advertise support', () => {
+            (getSubscribeBody().revision === undefined).should.equal(true);
+        });
+
+        function getSubscribeBody(): { revision?: number } {
+            try {
+                return JSON.parse(fetchStub.firstCall.args[1].body as string) as {
+                    revision?: number;
+                };
+            } catch (error) {
+                throw new Error('Expected a valid subscribe request body', {
+                    cause: error,
+                });
+            }
         }
-        delete (globalThis as Record<string, unknown>)['EventSource'];
-        resetSharedMultiplexer();
-    });
-
-    it('should connect to the centralized SSE hub endpoint', () => {
-        capturedUrl.should.include(SSE_HUB_ROUTE);
-    });
-
-    it('should not include query name in URL since subscriptions are done via POST', () => {
-        capturedUrl.should.not.include('query=');
-    });
-
-    it('should return a subscription', () => {
-        subscription.should.not.be.undefined;
-    });
-}));
+
+        it('should normalize omitted readiness to true', () => {
+            callback.firstCall.args[0].isReady.should.equal(true);
+        });
+    }),
+);

package/queries/for_ObservableQueryFor/when_subscribing/with_web_socket_hub_payload_without_readiness.ts

@@ -0,0 +1,107 @@
+// 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 { given } from '../../../given';
+import { Globals } from '../../../Globals';
+import { HubMessageType } from '../../WebSocketHubConnection';
+import type { ObservableQuerySubscription } from '../../ObservableQuerySubscription';
+import { resetSharedMultiplexer } from '../../ObservableQueryMultiplexer';
+import { QueryTransportMethod } from '../../QueryTransportMethod';
+import { an_observable_query_for } from '../given/an_observable_query_for';
+
+describe(
+    'when subscribing with web socket hub payload without readiness',
+    given(an_observable_query_for, (context) => {
+        let callback: sinon.SinonStub;
+        let subscription: ObservableQuerySubscription<string>;
+        let originalQueryDirectMode: boolean;
+        let originalTransportMethod: QueryTransportMethod;
+        let originalWebSocket: typeof WebSocket;
+        let socket: {
+            readyState: number;
+            onopen: (() => void) | null;
+            onclose: (() => void) | null;
+            onerror: ((event: Event) => void) | null;
+            onmessage: ((event: { data: string }) => void) | null;
+            send: sinon.SinonStub;
+            close: sinon.SinonStub;
+        };
+
+        beforeEach(() => {
+            originalQueryDirectMode = Globals.queryDirectMode;
+            originalTransportMethod = Globals.queryTransportMethod;
+            originalWebSocket = globalThis.WebSocket;
+            resetSharedMultiplexer();
+
+            Globals.queryDirectMode = false;
+            Globals.queryTransportMethod = QueryTransportMethod.WebSocket;
+            context.query.setOrigin('https://example.com');
+            callback = sinon.stub();
+
+            socket = {
+                readyState: 0,
+                onopen: null,
+                onclose: null,
+                onerror: null,
+                onmessage: null,
+                send: sinon.stub(),
+                close: sinon.stub(),
+            };
+
+            const WebSocketStub = sinon.stub().returns(socket);
+            Object.assign(WebSocketStub, {
+                CONNECTING: 0,
+                OPEN: 1,
+                CLOSING: 2,
+                CLOSED: 3,
+            });
+            (globalThis as Record<string, unknown>)['WebSocket'] = WebSocketStub;
+
+            subscription = context.query.subscribe(callback, { id: 'test-id' });
+            socket.readyState = 1;
+            socket.onopen?.();
+
+            // An older Arc server sends no Connected capability message, so this fixture intentionally
+            // remains in legacy mode and accepts only result frames without a revision.
+            let subscribeMessage: { queryId: string };
+            try {
+                subscribeMessage = JSON.parse(socket.send.firstCall.args[0]);
+            } catch (error) {
+                throw new Error('The WebSocket subscribe message was not valid JSON', {
+                    cause: error,
+                });
+            }
+            socket.onmessage?.({
+                data: JSON.stringify({
+                    type: HubMessageType.QueryResult,
+                    queryId: subscribeMessage.queryId,
+                    payload: {
+                        data: 'ready result',
+                        isSuccess: true,
+                        isAuthorized: true,
+                        isValid: true,
+                        hasExceptions: false,
+                        validationResults: [],
+                        exceptionMessages: [],
+                        exceptionStackTrace: '',
+                        paging: { page: 0, size: 0, totalItems: 0, totalPages: 0 },
+                    },
+                }),
+            });
+        });
+
+        afterEach(() => {
+            subscription?.unsubscribe();
+            Globals.queryDirectMode = originalQueryDirectMode;
+            Globals.queryTransportMethod = originalTransportMethod;
+            globalThis.WebSocket = originalWebSocket;
+            resetSharedMultiplexer();
+            sinon.restore();
+        });
+
+        it('should normalize omitted readiness to true', () => {
+            callback.firstCall.args[0].isReady.should.equal(true);
+        });
+    }),
+);

package/queries/for_QueryInstanceCache/when_setting_last_result/with_only_readiness_changed.ts

@@ -0,0 +1,63 @@
+// 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 { PagingInfo } from '../../PagingInfo';
+import { QueryInstanceCache } from '../../QueryInstanceCache';
+import { QueryResultWithState } from '../../QueryResultWithState';
+
+describe('when setting the last result with only readiness changed', () => {
+    const key = 'MyQuery::';
+    const data = ['a', 'b'];
+    let listener: sinon.SinonStub;
+
+    beforeEach(() => {
+        const cache = new QueryInstanceCache();
+        cache.getOrCreate(key, () => ({}));
+        listener = sinon.stub();
+        cache.addListener<string[]>(key, listener);
+
+        cache.setLastResult(
+            key,
+            new QueryResultWithState(
+                data,
+                PagingInfo.noPaging,
+                false,
+                true,
+                true,
+                [],
+                false,
+                [],
+                '',
+                false,
+                undefined,
+                false,
+            ),
+        );
+        listener.resetHistory();
+
+        cache.setLastResult(
+            key,
+            new QueryResultWithState(
+                data,
+                PagingInfo.noPaging,
+                false,
+                true,
+                true,
+                [],
+                false,
+                [],
+                '',
+                false,
+                undefined,
+                true,
+            ),
+        );
+    });
+
+    afterEach(() => sinon.restore());
+
+    it('should notify the listener', () => listener.calledOnce.should.be.true);
+    it('should provide the changed readiness', () =>
+        listener.firstCall.args[0].isReady.should.be.true);
+});

package/queries/for_QueryResult/when_constructing_from_a_server_result/with_readiness_false.ts

@@ -0,0 +1,25 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { QueryResult } from '../../QueryResult';
+
+describe('when constructing from a server result with readiness false', () => {
+    const result = new QueryResult(
+        {
+            data: null,
+            isSuccess: false,
+            isReady: false,
+            isAuthorized: true,
+            isValid: true,
+            hasExceptions: false,
+            validationResults: [],
+            exceptionMessages: [],
+            exceptionStackTrace: '',
+            paging: { page: 0, size: 0, totalItems: 0, totalPages: 0 },
+        },
+        Object,
+        false,
+    );
+
+    it('should not be ready', () => result.isReady.should.be.false);
+});

package/queries/for_QueryResult/when_constructing_from_a_server_result/without_readiness.ts

@@ -0,0 +1,24 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { QueryResult } from '../../QueryResult';
+
+describe('when constructing from a server result without readiness', () => {
+    const result = new QueryResult(
+        {
+            data: {},
+            isSuccess: true,
+            isAuthorized: true,
+            isValid: true,
+            hasExceptions: false,
+            validationResults: [],
+            exceptionMessages: [],
+            exceptionStackTrace: '',
+            paging: { page: 0, size: 0, totalItems: 0, totalPages: 0 },
+        },
+        Object,
+        false,
+    );
+
+    it('should be ready', () => result.isReady.should.be.true);
+});

package/queries/for_QueryResultWithState/when_creating_from_query_result/with_readiness_false.ts

@@ -0,0 +1,28 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { QueryResult } from '../../QueryResult';
+import { QueryResultWithState } from '../../QueryResultWithState';
+
+describe('when creating from query result with readiness false', () => {
+    const queryResult = new QueryResult(
+        {
+            data: null,
+            isSuccess: false,
+            isReady: false,
+            isAuthorized: true,
+            isValid: true,
+            hasExceptions: false,
+            validationResults: [],
+            exceptionMessages: [],
+            exceptionStackTrace: '',
+            paging: { page: 0, size: 0, totalItems: 0, totalPages: 0 },
+        },
+        Object,
+        false,
+    );
+
+    const result = QueryResultWithState.fromQueryResult(queryResult, false);
+
+    it('should not be ready', () => result.isReady.should.be.false);
+});

package/queries/for_QueryResultWithState/when_creating_from_query_result/without_readiness.ts

@@ -0,0 +1,25 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { IQueryResult } from '../../IQueryResult';
+import { PagingInfo } from '../../PagingInfo';
+import { QueryResultWithState } from '../../QueryResultWithState';
+
+describe('when creating from query result without readiness', () => {
+    const queryResult: IQueryResult<string> = {
+        data: 'ready result',
+        paging: PagingInfo.noPaging,
+        isSuccess: true,
+        isAuthorized: true,
+        isValid: true,
+        validationResults: [],
+        hasExceptions: false,
+        exceptionMessages: [],
+        exceptionStackTrace: '',
+        hasData: true,
+    };
+
+    const result = QueryResultWithState.fromQueryResult(queryResult, false);
+
+    it('should be ready', () => result.isReady.should.be.true);
+});

package/queries/for_ServerSentEventHubConnection/given/a_deferred_promise.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export class a_deferred_promise<T> {
+    readonly promise: Promise<T>;
+    resolve!: (value: T) => void;
+    reject!: (reason?: unknown) => void;
+
+    constructor() {
+        this.promise = new Promise<T>((resolve, reject) => {
+            this.resolve = resolve;
+            this.reject = reject;
+        });
+    }
+}

package/queries/for_ServerSentEventHubConnection/given/a_server_sent_event_hub_connection.ts

@@ -16,6 +16,7 @@ export class a_server_sent_event_hub_connection {
         close: sinon.SinonStub;
         readyState: number;
     };
+    eventSources!: Array<typeof this.fakeEventSource>;
     policy!: sinon.SinonStubbedInstance<IReconnectPolicy>;
     fetchStub!: sinon.SinonStub;
 
@@ -29,20 +30,28 @@ export class a_server_sent_event_hub_connection {
      * accumulation across tests sharing the same context instance.
      */
     setup(): void {
+        this.eventSources = [];
         this.fakeEventSource = {
             onopen: null,
             onmessage: null,
             onerror: null,
             close: sinon.stub(),
-            readyState: 0, // CONNECTING
+            readyState: 0,
         };
 
         // eslint-disable-next-line @typescript-eslint/no-this-alias
         const self = this;
         const FakeEventSourceClass = function (this: any) {
-            Object.assign(self.fakeEventSource, { onopen: null, onmessage: null, onerror: null });
-            self.fakeEventSource.readyState = 0; // CONNECTING
-            return self.fakeEventSource;
+            const eventSource = {
+                onopen: null,
+                onmessage: null,
+                onerror: null,
+                close: sinon.stub(),
+                readyState: 0, // CONNECTING
+            };
+            self.eventSources.push(eventSource);
+            self.fakeEventSource = eventSource;
+            return eventSource;
         };
         (globalThis as any)['EventSource'] = FakeEventSourceClass;
         (globalThis as any)['EventSource'].CONNECTING = 0;
@@ -66,7 +75,7 @@ export class a_server_sent_event_hub_connection {
             '',
             undefined,
             undefined,
-            this.policy
+            this.policy,
         );
     }
 
@@ -75,8 +84,10 @@ export class a_server_sent_event_hub_connection {
         this.fakeEventSource.onopen?.();
     }
 
-    simulateMessage(payload: object): void {
-        this.fakeEventSource.onmessage?.({ data: JSON.stringify(payload) } as MessageEvent);
+    simulateMessage(payload: Record<string, unknown>): void {
+        this.fakeEventSource.onmessage?.({
+            data: JSON.stringify(payload),
+        } as MessageEvent);
     }
 
     simulateError(): void {

package/queries/for_ServerSentEventHubConnection/when_a_retired_event_source_fires/ignores_connected_and_error_callbacks.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 sinon from 'sinon';
+import { a_server_sent_event_hub_connection } from '../given/a_server_sent_event_hub_connection';
+import { given } from '../../../given';
+import { HubMessageType } from '../../WebSocketHubConnection';
+
+describe(
+    'when a retired EventSource fires connected and error callbacks',
+    given(a_server_sent_event_hub_connection, (context) => {
+        let staleMessage: (event: MessageEvent) => void;
+        let staleError: () => void;
+        let currentSource: typeof context.fakeEventSource;
+
+        beforeEach(() => {
+            context.setup();
+            sinon.stub(console, 'warn');
+            context.connection.subscribe('q1', { queryName: 'MyQuery' }, sinon.stub());
+            context.simulateOpen();
+            context.simulateMessage({
+                type: HubMessageType.Connected,
+                payload: 'connection-a',
+            });
+
+            const retiredSource = context.eventSources[0];
+            staleMessage = retiredSource.onmessage!;
+            staleError = retiredSource.onerror!;
+            staleError();
+
+            const reconnect = (context.policy.schedule as sinon.SinonStub).firstCall
+                .args[0] as () => void;
+            reconnect();
+            currentSource = context.eventSources[1];
+            context.simulateOpen();
+            context.simulateMessage({
+                type: HubMessageType.Connected,
+                payload: 'connection-b',
+            });
+
+            staleMessage({
+                data: JSON.stringify({
+                    type: HubMessageType.Connected,
+                    payload: 'stale-connection',
+                }),
+            } as MessageEvent);
+            staleError();
+        });
+
+        afterEach(() => sinon.restore());
+
+        it('should not send another subscription for stale connected', () =>
+            context.fetchStub.callCount.should.equal(2));
+        it('should keep the current EventSource open', () =>
+            currentSource.close.called.should.be.false);
+        it('should not schedule another reconnect for stale error', () =>
+            (context.policy.schedule as sinon.SinonStub).calledOnce.should.be.true);
+    }),
+);