@cratis/arc 22.0.2 → 22.1.0

package/queries/for_ServerSentEventHubConnection/when_replacing_a_subscription/ignores_messages_from_the_retired_generation.ts

@@ -0,0 +1,92 @@
+// 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 messages arrive from a retired subscription generation',
+    given(a_server_sent_event_hub_connection, (context) => {
+        const queryId = 'q1';
+        let originalCallback: sinon.SinonStub;
+        let replacementCallback: sinon.SinonStub;
+        let originalGeneration: number;
+        let replacementGeneration: number;
+
+        beforeEach(() => {
+            context.setup();
+            sinon.stub(console, 'warn');
+            sinon.stub(console, 'error');
+            originalCallback = sinon.stub();
+            replacementCallback = sinon.stub();
+
+            context.connection.subscribe(
+                queryId,
+                { queryName: 'OriginalQuery' },
+                originalCallback,
+            );
+            context.simulateOpen();
+            context.simulateMessage({
+                type: HubMessageType.Connected,
+                payload: 'connection-a',
+                supportsSubscriptionRevisions: true,
+            });
+            originalGeneration = getGeneration(0);
+
+            context.connection.subscribe(
+                queryId,
+                { queryName: 'ReplacementQuery' },
+                replacementCallback,
+            );
+            replacementGeneration = getGeneration(1);
+
+            context.simulateMessage({
+                type: HubMessageType.QueryResult,
+                queryId,
+                revision: originalGeneration,
+                payload: { isSuccess: true, data: ['stale'] },
+            });
+            context.simulateMessage({
+                type: HubMessageType.Unauthorized,
+                queryId,
+                revision: originalGeneration,
+            });
+            context.simulateMessage({
+                type: HubMessageType.Error,
+                queryId,
+                revision: originalGeneration,
+                payload: 'stale error',
+            });
+            context.simulateMessage({
+                type: HubMessageType.QueryResult,
+                queryId,
+                revision: replacementGeneration,
+                payload: { isSuccess: true, data: ['current'] },
+            });
+        });
+
+        afterEach(() => sinon.restore());
+
+        it('should not notify the retired callback', () =>
+            originalCallback.called.should.be.false);
+        it('should deliver the current generation result', () =>
+            replacementCallback.calledOnce.should.be.true);
+        it('should retain the replacement after stale unauthorized', () =>
+            context.connection.queryCount.should.equal(1));
+        it('should not log the stale server error', () =>
+            (console.error as sinon.SinonStub).called.should.be.false);
+
+        function getGeneration(callIndex: number): number {
+            const rawBody = context.fetchStub.getCall(callIndex).args[1].body as string;
+            try {
+                return (JSON.parse(rawBody) as { revision: number }).revision;
+            } catch (error) {
+                throw new Error('Expected a valid subscribe request body', {
+                    cause: error,
+                });
+            }
+        }
+    }),
+);

package/queries/for_ServerSentEventHubConnection/when_subscribing/sends_subscribe_post.ts

@@ -6,37 +6,76 @@ import { a_server_sent_event_hub_connection } from '../given/a_server_sent_event
 import { given } from '../../../given';
 import { HubMessageType } from '../../WebSocketHubConnection';
 
-describe('when subscribing sends the subscribe POST after Connected', given(a_server_sent_event_hub_connection, context => {
-    const queryId = 'q1';
-    const connectionId = 'conn-abc';
-
-    beforeEach(() => {
-        context.setup();
-        context.connection.subscribe(queryId, { queryName: 'MyQuery' }, sinon.stub());
-        context.simulateOpen();
-        context.simulateMessage({ type: HubMessageType.Connected, payload: connectionId });
-    });
-
-    afterEach(() => sinon.restore());
-
-    it('should POST to the subscribe URL', () => context.fetchStub.calledOnce.should.be.true);
-    it('should pass the connection id in the request body', () => {
-        const body = JSON.parse(context.fetchStub.getCall(0).args[1].body);
-        body.connectionId.should.equal(connectionId);
-    });
-    it('should pass the query id in the request body', () => {
-        const body = JSON.parse(context.fetchStub.getCall(0).args[1].body);
-        body.queryId.should.equal(queryId);
-    });
-
-    describe('when a query result message arrives', () => {
-        const result = { isSuccess: true, data: ['x'] };
+describe(
+    'when subscribing sends the subscribe POST after Connected',
+    given(a_server_sent_event_hub_connection, (context) => {
+        const queryId = 'q1';
+        const connectionId = 'conn-abc';
+        let callback: sinon.SinonStub;
 
         beforeEach(() => {
-            context.simulateMessage({ type: HubMessageType.QueryResult, queryId, payload: result });
+            context.setup();
+            callback = sinon.stub();
+            context.connection.subscribe(queryId, { queryName: 'MyQuery' }, callback);
+            context.simulateOpen();
+            context.simulateMessage({
+                type: HubMessageType.Connected,
+                payload: connectionId,
+                supportsSubscriptionRevisions: true,
+            });
         });
 
-        // The callback passed to subscribe during beforeEach is a stub — re-verify via query count
-        it('should have one active subscription', () => context.connection.queryCount.should.equal(1));
-    });
-}));
+        afterEach(() => sinon.restore());
+
+        it('should POST to the subscribe URL', () =>
+            context.fetchStub.calledOnce.should.be.true);
+        it('should pass the connection id in the request body', () =>
+            getBody().connectionId.should.equal(connectionId));
+        it('should pass the query id in the request body', () =>
+            getBody().queryId.should.equal(queryId));
+        it('should pass a positive numeric revision in the request body', () =>
+            getBody().revision.should.equal(1));
+
+        function getBody(): {
+            connectionId: string;
+            queryId: string;
+            revision: number;
+        } {
+            const rawBody = context.fetchStub.getCall(0).args[1].body as string;
+            try {
+                return JSON.parse(rawBody) as {
+                    connectionId: string;
+                    queryId: string;
+                    revision: number;
+                };
+            } catch (error) {
+                throw new Error('Expected a valid subscribe request body', {
+                    cause: error,
+                });
+            }
+        }
+
+        describe('when a query result message arrives', () => {
+            const result = { isSuccess: true, data: ['x'] };
+
+            beforeEach(() => {
+                context.simulateMessage({
+                    type: HubMessageType.QueryResult,
+                    queryId,
+                    payload: { isSuccess: true, data: ['legacy'] },
+                });
+                context.simulateMessage({
+                    type: HubMessageType.QueryResult,
+                    queryId,
+                    revision: getBody().revision,
+                    payload: result,
+                });
+            });
+
+            it('should ignore the missing-revision frame and deliver the exact revision once', () => {
+                callback.calledOnce.should.equal(true);
+                callback.firstCall.args[0].should.deep.equal(result);
+            });
+        });
+    }),
+);

package/queries/for_ServerSentEventHubConnection/when_subscription_revisions_are_not_advertised/uses_legacy_protocol.ts

@@ -0,0 +1,69 @@
+// 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 { HubMessageType } from '../../WebSocketHubConnection';
+import { a_server_sent_event_hub_connection } from '../given/a_server_sent_event_hub_connection';
+
+describe(
+    'when the SSE server does not advertise subscription revision support',
+    given(a_server_sent_event_hub_connection, (context) => {
+        const queryId = 'query-1';
+        let callback: sinon.SinonStub;
+
+        beforeEach(() => {
+            context.setup();
+            callback = sinon.stub();
+            context.connection.subscribe(queryId, { queryName: 'MyQuery' }, callback);
+            context.simulateOpen();
+            context.simulateMessage({
+                type: HubMessageType.Connected,
+                payload: 'legacy-connection',
+            });
+            context.simulateMessage({
+                type: HubMessageType.QueryResult,
+                queryId,
+                payload: { data: ['legacy'] },
+            });
+            context.connection.unsubscribe(queryId);
+        });
+
+        afterEach(() => sinon.restore());
+
+        it('should omit the revision from the subscribe request', () =>
+            (subscribeBody().revision === undefined).should.equal(true));
+
+        it('should accept a missing-revision result frame', () => {
+            callback.calledOnce.should.equal(true);
+            callback.firstCall.args[0].should.deep.equal({ data: ['legacy'] });
+        });
+
+        it('should omit the revision from the unsubscribe request', () =>
+            (unsubscribeBody().revision === undefined).should.equal(true));
+
+        function subscribeBody(): { revision?: number } {
+            return parseBody(context.fetchStub.firstCall.args[1].body as string);
+        }
+
+        function unsubscribeBody(): { revision?: number } {
+            const unsubscribeCall = context.fetchStub
+                .getCalls()
+                .find((call) => (call.args[0] as string).includes('unsubscribe'));
+            if (!unsubscribeCall) {
+                throw new Error('Expected an unsubscribe request');
+            }
+            return parseBody(unsubscribeCall.args[1].body as string);
+        }
+
+        function parseBody(rawBody: string): { revision?: number } {
+            try {
+                return JSON.parse(rawBody) as { revision?: number };
+            } catch (error) {
+                throw new Error('Expected a valid subscription request body', {
+                    cause: error,
+                });
+            }
+        }
+    }),
+);

package/queries/for_ServerSentEventHubConnection/when_unsubscribing/the_only_query.ts

@@ -6,27 +6,46 @@ import { a_server_sent_event_hub_connection } from '../given/a_server_sent_event
 import { given } from '../../../given';
 import { HubMessageType } from '../../WebSocketHubConnection';
 
-describe('when unsubscribing the only query', given(a_server_sent_event_hub_connection, context => {
-    beforeEach(async () => {
-        context.setup();
-        context.connection.subscribe('q1', { queryName: 'MyQuery' }, sinon.stub());
-        context.simulateOpen();
-        context.simulateMessage({ type: HubMessageType.Connected, payload: 'conn-abc' });
-
-        context.connection.unsubscribe('q1');
-
-        // Allow the micro-task queue to drain so the async fetch completes.
-        await Promise.resolve();
-    });
-
-    afterEach(() => sinon.restore());
-
-    it('should close the event source', () => context.fakeEventSource.close.calledOnce.should.be.true);
-
-    it('should send an unsubscribe POST request', () => {
-        const unsubscribeCalls = context.fetchStub.args.filter(
-            (args: unknown[]) => typeof args[0] === 'string' && (args[0] as string).includes('unsubscribe')
-        );
-        unsubscribeCalls.length.should.equal(1);
-    });
-}));
+describe(
+    'when unsubscribing the only query',
+    given(a_server_sent_event_hub_connection, (context) => {
+        beforeEach(async () => {
+            context.setup();
+            context.connection.subscribe('q1', { queryName: 'MyQuery' }, sinon.stub());
+            context.simulateOpen();
+            context.simulateMessage({
+                type: HubMessageType.Connected,
+                payload: 'conn-abc',
+                supportsSubscriptionRevisions: true,
+            });
+
+            context.connection.unsubscribe('q1');
+
+            // Allow the micro-task queue to drain so the async fetch completes.
+            await Promise.resolve();
+        });
+
+        afterEach(() => sinon.restore());
+
+        it('should close the event source', () =>
+            context.fakeEventSource.close.calledOnce.should.be.true);
+
+        it('should send an unsubscribe POST request with the exact revision', () => {
+            const unsubscribeCalls = context.fetchStub.args.filter(
+                (args: unknown[]) =>
+                    typeof args[0] === 'string' &&
+                    (args[0] as string).includes('unsubscribe'),
+            );
+            unsubscribeCalls.length.should.equal(1);
+            getBody(unsubscribeCalls[0][1]).revision.should.equal(1);
+        });
+
+        function getBody(init: RequestInit): { revision: number } {
+            try {
+                return JSON.parse(init.body as string) as { revision: number };
+            } catch (error) {
+                throw new Error('Expected a valid unsubscribe body', { cause: error });
+            }
+        }
+    }),
+);

package/queries/for_WebSocketHubConnection/when_receiving_unauthorized/notifies_subscriber_and_removes_subscription.ts

@@ -7,41 +7,65 @@ import { given } from '../../../given';
 import { HubMessageType } from '../../WebSocketHubConnection';
 import { QueryResult } from '../../QueryResult';
 
-describe('when receiving unauthorized for a subscribed query', given(a_web_socket_hub_connection, context => {
-    let callback: sinon.SinonStub;
-    let receivedResult: QueryResult<unknown> | undefined;
-    const queryId = 'q-auth-1';
+describe(
+    'when receiving unauthorized for a subscribed query',
+    given(a_web_socket_hub_connection, (context) => {
+        let callback: sinon.SinonStub;
+        let receivedResult: QueryResult<unknown> | undefined;
+        const queryId = 'q-auth-1';
 
-    beforeEach(() => {
-        context.setup();
-        callback = sinon.stub();
+        beforeEach(() => {
+            context.setup();
+            callback = sinon.stub();
 
-        context.connection.subscribe(queryId, { queryName: 'SecureQuery' }, callback);
-        context.simulateOpen();
+            context.connection.subscribe(queryId, { queryName: 'SecureQuery' }, callback);
+            context.simulateOpen();
+            context.simulateMessage({
+                type: HubMessageType.Connected,
+                supportsSubscriptionRevisions: true,
+            });
+            const subscribe = getSubscribeMessage();
 
-        // Server replies with Unauthorized for this subscription.
-        context.simulateMessage({ type: HubMessageType.Unauthorized, queryId });
+            // Server replies with Unauthorized for this exact subscription.
+            context.simulateMessage({
+                type: HubMessageType.Unauthorized,
+                queryId,
+                revision: subscribe.revision,
+            });
 
-        receivedResult = callback.firstCall?.args[0] as QueryResult<unknown> | undefined;
-    });
+            receivedResult = callback.firstCall?.args[0] as
+                | QueryResult<unknown>
+                | undefined;
+        });
 
-    afterEach(() => {
-        sinon.restore();
-    });
+        afterEach(() => {
+            sinon.restore();
+        });
 
-    it('should invoke the subscriber callback', () => {
-        callback.calledOnce.should.be.true;
-    });
+        function getSubscribeMessage(): { revision: number } {
+            try {
+                return JSON.parse(context.fakeSocket.send.getCall(1).args[0]) as {
+                    revision: number;
+                };
+            } catch (error) {
+                throw new Error('Expected a valid subscribe message', { cause: error });
+            }
+        }
 
-    it('should report isAuthorized as false', () => {
-        receivedResult!.isAuthorized.should.be.false;
-    });
+        it('should invoke the subscriber callback', () => {
+            callback.calledOnce.should.equal(true);
+        });
 
-    it('should report isSuccess as false', () => {
-        receivedResult!.isSuccess.should.be.false;
-    });
+        it('should report isAuthorized as false', () => {
+            receivedResult!.isAuthorized.should.equal(false);
+        });
 
-    it('should remove the subscription', () => {
-        context.connection.queryCount.should.equal(0);
-    });
-}));
+        it('should report isSuccess as false', () => {
+            receivedResult!.isSuccess.should.equal(false);
+        });
+
+        it('should remove the subscription', () => {
+            context.connection.queryCount.should.equal(0);
+        });
+    }),
+);

package/queries/for_WebSocketHubConnection/when_reconnecting/ignores_a_pending_reconnect_and_stale_socket_callbacks.ts

@@ -0,0 +1,131 @@
+// 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_web_socket_hub_connection } from '../given/a_web_socket_hub_connection';
+import { given } from '../../../given';
+import { type HubMessage, HubMessageType } from '../../WebSocketHubConnection';
+import type { ReconnectCallback } from '../../IReconnectPolicy';
+
+for (const supportsSubscriptionRevisions of [false, true]) {
+    const mode = supportsSubscriptionRevisions ? 'revision-aware' : 'legacy';
+
+    describe(`when an immediate ${mode} socket open wins during reconnect backoff`, given(a_web_socket_hub_connection, context => {
+        const queryId = 'query-a';
+        let callback: sinon.SinonStub;
+        let secondSocket: typeof context.fakeSocket;
+
+        beforeEach(() => {
+            context.setup();
+            sinon.stub(console, 'log');
+            sinon.stub(console, 'warn');
+            sinon.stub(console, 'error');
+            callback = sinon.stub();
+
+            context.connection.subscribe(queryId, { queryName: 'Original' }, sinon.stub());
+            const firstSocket = context.fakeSocket;
+            firstSocket.readyState = WebSocket.OPEN;
+            firstSocket.onopen?.();
+            if (supportsSubscriptionRevisions) {
+                firstSocket.onmessage?.(messageEvent({
+                    type: HubMessageType.Connected,
+                    supportsSubscriptionRevisions: true,
+                }));
+            }
+
+            const staleMessage = firstSocket.onmessage!;
+            const staleClose = firstSocket.onclose!;
+            const staleError = firstSocket.onerror!;
+            firstSocket.readyState = WebSocket.CLOSED;
+            staleClose();
+
+            secondSocket = createSocket();
+            context.WebSocketStub.onSecondCall().returns(secondSocket);
+            context.connection.subscribe(queryId, { queryName: 'Replacement' }, callback);
+
+            const reconnectCallback = (context.policy.schedule as sinon.SinonStub).firstCall.args[0] as ReconnectCallback;
+            reconnectCallback();
+
+            secondSocket.readyState = WebSocket.OPEN;
+            secondSocket.onopen?.();
+            if (supportsSubscriptionRevisions) {
+                secondSocket.onmessage?.(messageEvent({
+                    type: HubMessageType.Connected,
+                    supportsSubscriptionRevisions: true,
+                }));
+            }
+
+            const revision = supportsSubscriptionRevisions
+                ? sentMessages(secondSocket).find(message => message.type === HubMessageType.Subscribe && message.revision !== undefined)!.revision
+                : undefined;
+
+            staleMessage(messageEvent({
+                type: HubMessageType.Connected,
+                supportsSubscriptionRevisions: true,
+            }));
+            staleMessage(messageEvent({
+                type: HubMessageType.QueryResult,
+                queryId,
+                revision,
+                payload: { data: ['stale'] },
+            }));
+            staleMessage(messageEvent({
+                type: HubMessageType.Unauthorized,
+                queryId,
+                revision,
+            }));
+            staleMessage(messageEvent({
+                type: HubMessageType.Error,
+                queryId,
+                revision,
+                payload: 'stale',
+            }));
+            staleError({} as Event);
+            staleClose();
+
+            secondSocket.onmessage?.(messageEvent({
+                type: HubMessageType.QueryResult,
+                queryId,
+                revision,
+                payload: { data: ['current'] },
+            }));
+        });
+
+        afterEach(() => {
+            context.connection.dispose();
+            sinon.restore();
+        });
+
+        it('should cancel the pending reconnect when the immediate open wins', () =>
+            (context.policy.cancel as sinon.SinonStub).calledOnce.should.be.true);
+        it('should not let the pending callback create a third socket', () =>
+            context.WebSocketStub.callCount.should.equal(2));
+        it('should not close the current socket', () => secondSocket.close.called.should.be.false);
+        it('should not schedule another reconnect from the stale close', () =>
+            (context.policy.schedule as sinon.SinonStub).calledOnce.should.be.true);
+        it('should not process stale result or unauthorized frames', () => callback.calledOnce.should.be.true);
+        it('should retain the current subscription', () => context.connection.queryCount.should.equal(1));
+        it('should not process the stale error frame or callback', () =>
+            (console.error as sinon.SinonStub).called.should.be.false);
+    }));
+}
+
+function createSocket() {
+    return {
+        onopen: null as (() => void) | null,
+        onclose: null as (() => void) | null,
+        onerror: null as ((error: Event) => void) | null,
+        onmessage: null as ((event: MessageEvent) => void) | null,
+        send: sinon.stub(),
+        close: sinon.stub(),
+        readyState: WebSocket.CONNECTING as number,
+    };
+}
+
+function messageEvent(message: HubMessage): MessageEvent {
+    return { data: JSON.stringify(message) } as MessageEvent;
+}
+
+function sentMessages(socket: ReturnType<typeof createSocket>): HubMessage[] {
+    return socket.send.args.map(args => JSON.parse(args[0]) as HubMessage);
+}

package/queries/for_WebSocketHubConnection/when_reconnecting/replaces_a_closing_socket_safely.ts

@@ -0,0 +1,39 @@
+// 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_web_socket_hub_connection } from '../given/a_web_socket_hub_connection';
+import { given } from '../../../given';
+
+describe('when opening while the owned socket is closing', given(a_web_socket_hub_connection, context => {
+    let firstSocket: typeof context.fakeSocket;
+
+    beforeEach(() => {
+        context.setup();
+        context.connection.subscribe('q1', { queryName: 'First' }, sinon.stub());
+        firstSocket = context.fakeSocket;
+        firstSocket.readyState = WebSocket.CLOSING;
+        context.WebSocketStub.onSecondCall().returns({
+            onopen: null,
+            onclose: null,
+            onerror: null,
+            onmessage: null,
+            send: sinon.stub(),
+            close: sinon.stub(),
+            readyState: WebSocket.CONNECTING,
+        });
+        context.connection.subscribe('q2', { queryName: 'Second' }, sinon.stub());
+    });
+
+    afterEach(() => {
+        context.connection.dispose();
+        sinon.restore();
+    });
+
+    it('should close the replaced socket', () => firstSocket.close.calledOnce.should.be.true);
+    it('should detach the replaced socket open handler', () => (firstSocket.onopen === null).should.be.true);
+    it('should detach the replaced socket close handler', () => (firstSocket.onclose === null).should.be.true);
+    it('should detach the replaced socket error handler', () => (firstSocket.onerror === null).should.be.true);
+    it('should detach the replaced socket message handler', () => (firstSocket.onmessage === null).should.be.true);
+    it('should create one replacement socket', () => context.WebSocketStub.callCount.should.equal(2));
+}));