@cratis/arc 19.11.1 → 20.0.0

package/queries/for_QueryInstanceCache/when_getting_last_result/with_stored_result.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { QueryInstanceCache } from '../../QueryInstanceCache';
+import { QueryResultWithState } from '../../QueryResultWithState';
+
+describe('when getting the last result for a key that has a stored result', () => {
+    let cache: QueryInstanceCache;
+    let stored: QueryResultWithState<string[]>;
+    let retrieved: QueryResultWithState<string[]> | undefined;
+
+    beforeEach(() => {
+        cache = new QueryInstanceCache();
+        cache.getOrCreate('MyQuery::', () => ({}));
+
+        stored = QueryResultWithState.empty<string[]>([]);
+        cache.setLastResult('MyQuery::', stored);
+
+        retrieved = cache.getLastResult<string[]>('MyQuery::');
+    });
+
+    it('should return the stored result', () => retrieved!.should.equal(stored));
+});

package/queries/for_QueryInstanceCache/when_getting_or_creating/with_existing_entry.ts

@@ -0,0 +1,29 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { QueryInstanceCache } from '../../QueryInstanceCache';
+
+describe('when getting or creating an entry that already exists', () => {
+    let cache: QueryInstanceCache;
+    const factoryResult = { id: 42 };
+    let firstInstance: object;
+    let secondInstance: object;
+    let isNewFirst: boolean;
+    let isNewSecond: boolean;
+
+    beforeEach(() => {
+        cache = new QueryInstanceCache();
+        const first = cache.getOrCreate('MyQuery::', () => factoryResult);
+        firstInstance = first.instance;
+        isNewFirst = first.isNew;
+
+        const second = cache.getOrCreate('MyQuery::', () => ({ id: 99 }));
+        secondInstance = second.instance;
+        isNewSecond = second.isNew;
+    });
+
+    it('should return the same instance', () => secondInstance.should.equal(firstInstance));
+    it('should not call factory a second time', () => secondInstance.should.not.deep.equal({ id: 99 }));
+    it('should report the first entry as new', () => isNewFirst.should.be.true);
+    it('should report the second entry as not new', () => isNewSecond.should.be.false);
+});

package/queries/for_QueryInstanceCache/when_getting_or_creating/with_new_entry.ts

@@ -0,0 +1,21 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { QueryInstanceCache } from '../../QueryInstanceCache';
+
+describe('when getting or creating an entry that does not exist yet', () => {
+    let cache: QueryInstanceCache;
+    let instance: object;
+    let isNew: boolean;
+
+    beforeEach(() => {
+        cache = new QueryInstanceCache();
+        const result = cache.getOrCreate('MyQuery::', () => ({ id: 1 }));
+        instance = result.instance;
+        isNew = result.isNew;
+    });
+
+    it('should create a new instance', () => instance.should.deep.equal({ id: 1 }));
+    it('should report the entry as new', () => isNew.should.be.true);
+    it('should record the entry in the cache', () => cache.has('MyQuery::').should.be.true);
+});

package/queries/for_QueryInstanceCache/when_releasing/a_key_that_does_not_exist.ts

@@ -0,0 +1,21 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { QueryInstanceCache } from '../../QueryInstanceCache';
+
+describe('when releasing a key that does not exist', () => {
+    let cache: QueryInstanceCache;
+    let threwError: boolean;
+
+    beforeEach(() => {
+        cache = new QueryInstanceCache();
+        threwError = false;
+        try {
+            cache.release('NonExistentKey::');
+        } catch {
+            threwError = true;
+        }
+    });
+
+    it('should not throw', () => threwError.should.be.false);
+});

package/queries/for_QueryInstanceCache/when_releasing/one_of_two_subscribers.ts

@@ -0,0 +1,18 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { QueryInstanceCache } from '../../QueryInstanceCache';
+
+describe('when releasing one of two subscribers', () => {
+    let cache: QueryInstanceCache;
+
+    beforeEach(() => {
+        cache = new QueryInstanceCache();
+        cache.getOrCreate('MyQuery::', () => ({}));
+        cache.acquire('MyQuery::');
+        cache.acquire('MyQuery::'); // second subscriber
+        cache.release('MyQuery::');
+    });
+
+    it('should keep the entry because one subscriber remains', () => cache.has('MyQuery::').should.be.true);
+});

package/queries/for_QueryInstanceCache/when_releasing/the_only_subscriber.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { QueryInstanceCache } from '../../QueryInstanceCache';
+
+describe('when releasing the only subscriber', () => {
+    let cache: QueryInstanceCache;
+
+    beforeEach(() => {
+        vi.useFakeTimers();
+        cache = new QueryInstanceCache();
+        cache.getOrCreate('MyQuery::', () => ({}));
+        cache.acquire('MyQuery::');
+        cache.release('MyQuery::');
+        vi.advanceTimersByTime(0);
+    });
+
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+
+    it('should evict the entry', () => cache.has('MyQuery::').should.be.false);
+});

package/queries/for_QueryInstanceCache/when_setting_last_result/with_a_result.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { QueryInstanceCache } from '../../QueryInstanceCache';
+import { QueryResultWithState } from '../../QueryResultWithState';
+
+describe('when setting the last result', () => {
+    let cache: QueryInstanceCache;
+    let retrieved: QueryResultWithState<number> | undefined;
+    const stored = QueryResultWithState.empty<number>(0);
+
+    beforeEach(() => {
+        cache = new QueryInstanceCache();
+        cache.getOrCreate('MyQuery::', () => ({}));
+        cache.setLastResult('MyQuery::', stored);
+        retrieved = cache.getLastResult<number>('MyQuery::');
+    });
+
+    it('should persist the result so subsequent getLastResult returns it', () => retrieved!.should.equal(stored));
+});

package/queries/for_ReconnectPolicy/when_canceling/with_pending_timer.ts

@@ -0,0 +1,33 @@
+// 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 { ReconnectPolicy } from '../../ReconnectPolicy';
+
+describe('when canceling a pending reconnect', () => {
+    let policy: ReconnectPolicy;
+    let clock: sinon.SinonFakeTimers;
+    let callbackStub: sinon.SinonStub;
+
+    beforeEach(() => {
+        clock = sinon.useFakeTimers();
+        policy = new ReconnectPolicy(100, 500, 500, 10_000);
+        callbackStub = sinon.stub();
+
+        // Schedule a reconnect, then cancel before the timer fires
+        policy.schedule(callbackStub, 'url');
+        policy.cancel();
+    });
+
+    afterEach(() => {
+        clock.restore();
+        sinon.restore();
+    });
+
+    it('should not invoke the callback after the timer would have fired', () => {
+        clock.tick(60_000);
+        callbackStub.callCount.should.equal(0);
+    });
+
+    it('should preserve the attempt counter', () => policy.attempt.should.equal(1));
+});

package/queries/for_ReconnectPolicy/when_cancelling/with_pending_timer.ts

@@ -0,0 +1,33 @@
+// 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 { ReconnectPolicy } from '../../ReconnectPolicy';
+
+describe('when canceling a pending reconnect', () => {
+    let policy: ReconnectPolicy;
+    let clock: sinon.SinonFakeTimers;
+    let callbackStub: sinon.SinonStub;
+
+    beforeEach(() => {
+        clock = sinon.useFakeTimers();
+        policy = new ReconnectPolicy(100, 500, 500, 10_000);
+        callbackStub = sinon.stub();
+
+        // Schedule a reconnect, then cancel before the timer fires
+        policy.schedule(callbackStub, 'url');
+        policy.cancel();
+    });
+
+    afterEach(() => {
+        clock.restore();
+        sinon.restore();
+    });
+
+    it('should not invoke the callback after the timer would have fired', () => {
+        clock.tick(60_000);
+        callbackStub.callCount.should.equal(0);
+    });
+
+    it('should preserve the attempt counter', () => policy.attempt.should.equal(1));
+});

package/queries/for_ReconnectPolicy/when_resetting/after_scheduling.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 { ReconnectPolicy } from '../../ReconnectPolicy';
+
+describe('when resetting the reconnect policy', () => {
+    let policy: ReconnectPolicy;
+    let clock: sinon.SinonFakeTimers;
+    let callbackStub: sinon.SinonStub;
+
+    beforeEach(() => {
+        clock = sinon.useFakeTimers();
+        policy = new ReconnectPolicy(100, 500, 500, 10_000);
+        callbackStub = sinon.stub();
+
+        // Schedule a reconnect, then reset before the timer fires
+        policy.schedule(callbackStub, 'url');
+        policy.reset();
+    });
+
+    afterEach(() => {
+        clock.restore();
+        sinon.restore();
+    });
+
+    it('should reset the attempt counter to 0', () => policy.attempt.should.equal(0));
+
+    it('should cancel the pending timer so the callback is never invoked', () => {
+        clock.tick(60_000);
+        callbackStub.callCount.should.equal(0);
+    });
+
+    it('should allow rescheduling from attempt 1 again', () => {
+        const rescheduled = policy.schedule(callbackStub, 'url');
+        rescheduled.should.be.true;
+        policy.attempt.should.equal(1);
+    });
+});

package/queries/for_ReconnectPolicy/when_scheduling/and_max_attempts_not_reached/delay_is_capped_at_max.ts

@@ -0,0 +1,44 @@
+// 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 { ReconnectPolicy } from '../../../ReconnectPolicy';
+
+describe('when scheduling and delay is capped at max', () => {
+    let policy: ReconnectPolicy;
+    let clock: sinon.SinonFakeTimers;
+    let callbackStub: sinon.SinonStub;
+
+    beforeEach(() => {
+        clock = sinon.useFakeTimers();
+        // Set maxDelayMs to a low value to make the cap observable
+        policy = new ReconnectPolicy(100, 500, 500, 2_000);
+        callbackStub = sinon.stub();
+
+        // Exhaust enough attempts to hit the cap: min(500 + 500*n, 2000) hits cap at n=3
+        policy.schedule(callbackStub, 'url'); // attempt 1, delay=1000
+        clock.tick(1000);
+        policy.schedule(callbackStub, 'url'); // attempt 2, delay=1500
+        clock.tick(1500);
+        policy.schedule(callbackStub, 'url'); // attempt 3, delay=2000 (at cap)
+        clock.tick(2000);
+        callbackStub.reset();
+
+        policy.schedule(callbackStub, 'url'); // attempt 4, delay should still be capped at 2000
+    });
+
+    afterEach(() => {
+        clock.restore();
+        sinon.restore();
+    });
+
+    it('should not fire before the cap delay', () => {
+        clock.tick(1999);
+        callbackStub.callCount.should.equal(0);
+    });
+
+    it('should fire exactly at the cap delay', () => {
+        clock.tick(2000);
+        callbackStub.calledOnce.should.be.true;
+    });
+});

package/queries/for_ReconnectPolicy/when_scheduling/and_max_attempts_not_reached/first_attempt.ts

@@ -0,0 +1,38 @@
+// 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 { ReconnectPolicy } from '../../../ReconnectPolicy';
+
+describe('when scheduling and max attempts not reached', () => {
+    let policy: ReconnectPolicy;
+    let clock: sinon.SinonFakeTimers;
+    let callbackStub: sinon.SinonStub;
+    let scheduled: boolean;
+
+    beforeEach(() => {
+        clock = sinon.useFakeTimers();
+        policy = new ReconnectPolicy(100, 500, 500, 10_000);
+        callbackStub = sinon.stub();
+
+        scheduled = policy.schedule(callbackStub, 'test-label');
+    });
+
+    afterEach(() => {
+        clock.restore();
+        sinon.restore();
+    });
+
+    it('should return true', () => scheduled.should.be.true);
+    it('should increment the attempt counter to 1', () => policy.attempt.should.equal(1));
+    it('should not invoke the callback immediately', () => callbackStub.callCount.should.equal(0));
+
+    describe('when the delay elapses', () => {
+        beforeEach(() => {
+            // Attempt 1: delay = min(500 + 500*1, 10_000) = 1000ms
+            clock.tick(1000);
+        });
+
+        it('should invoke the callback once', () => callbackStub.calledOnce.should.be.true);
+    });
+});

package/queries/for_ReconnectPolicy/when_scheduling/and_max_attempts_reached/abandons_reconnect.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 { ReconnectPolicy } from '../../../ReconnectPolicy';
+
+describe('when scheduling and max attempts reached', () => {
+    let policy: ReconnectPolicy;
+    let clock: sinon.SinonFakeTimers;
+    let callbackStub: sinon.SinonStub;
+    let scheduled: boolean;
+
+    beforeEach(() => {
+        clock = sinon.useFakeTimers();
+        // Use maxAttempts=2 so we can exhaust quickly
+        policy = new ReconnectPolicy(2, 500, 500, 10_000);
+        callbackStub = sinon.stub();
+
+        policy.schedule(callbackStub, 'url'); // attempt 1
+        clock.tick(1000);
+        policy.schedule(callbackStub, 'url'); // attempt 2
+        clock.tick(1500);
+        callbackStub.reset();
+
+        // This is the 3rd call — attempt >= maxAttempts (2), should not schedule
+        scheduled = policy.schedule(callbackStub, 'url');
+    });
+
+    afterEach(() => {
+        clock.restore();
+        sinon.restore();
+    });
+
+    it('should return false', () => scheduled.should.be.false);
+    it('should not invoke the callback', () => {
+        clock.tick(60_000);
+        callbackStub.callCount.should.equal(0);
+    });
+});

package/queries/for_ServerSentEventHubConnection/given/a_server_sent_event_hub_connection.ts

@@ -0,0 +1,85 @@
+// 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 { ServerSentEventHubConnection } from '../../ServerSentEventHubConnection';
+import { IReconnectPolicy, ReconnectCallback } from '../../IReconnectPolicy';
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+export class a_server_sent_event_hub_connection {
+    connection!: ServerSentEventHubConnection;
+    fakeEventSource!: {
+        onopen: (() => void) | null;
+        onmessage: ((event: MessageEvent) => void) | null;
+        onerror: (() => void) | null;
+        close: sinon.SinonStub;
+        readyState: number;
+    };
+    policy!: sinon.SinonStubbedInstance<IReconnectPolicy>;
+    fetchStub!: sinon.SinonStub;
+
+    constructor() {
+        this.setup();
+    }
+
+    /**
+     * Re-initializes stubs and creates a fresh {@link ServerSentEventHubConnection}.
+     * Call this at the start of each {@code beforeEach} to prevent stub-call
+     * accumulation across tests sharing the same context instance.
+     */
+    setup(): void {
+        this.fakeEventSource = {
+            onopen: null,
+            onmessage: null,
+            onerror: null,
+            close: sinon.stub(),
+            readyState: 0, // CONNECTING
+        };
+
+        // 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;
+        };
+        (globalThis as any)['EventSource'] = FakeEventSourceClass;
+        (globalThis as any)['EventSource'].CONNECTING = 0;
+        (globalThis as any)['EventSource'].OPEN = 1;
+        (globalThis as any)['EventSource'].CLOSED = 2;
+
+        this.fetchStub = sinon.stub().resolves({ ok: true });
+        (globalThis as any)['fetch'] = this.fetchStub;
+
+        this.policy = {
+            attempt: 0,
+            schedule: sinon.stub<[ReconnectCallback, string], boolean>().returns(true),
+            reset: sinon.stub(),
+            cancel: sinon.stub(),
+        };
+
+        this.connection = new ServerSentEventHubConnection(
+            'http://localhost/.cratis/queries/sse',
+            'http://localhost/.cratis/queries/sse/subscribe',
+            'http://localhost/.cratis/queries/sse/unsubscribe',
+            '',
+            undefined,
+            undefined,
+            this.policy
+        );
+    }
+
+    simulateOpen(): void {
+        this.fakeEventSource.readyState = 1; // OPEN
+        this.fakeEventSource.onopen?.();
+    }
+
+    simulateMessage(payload: object): void {
+        this.fakeEventSource.onmessage?.({ data: JSON.stringify(payload) } as MessageEvent);
+    }
+
+    simulateError(): void {
+        this.fakeEventSource.onerror?.();
+    }
+}

package/queries/for_ServerSentEventHubConnection/when_connect_timeout_fires/triggers_reconnect.ts

@@ -0,0 +1,46 @@
+// 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';
+
+const CONNECT_TIMEOUT_MS = 500;
+
+describe('when the connect timeout elapses before a Connected message arrives', given(a_server_sent_event_hub_connection, context => {
+    let clock: sinon.SinonFakeTimers;
+
+    beforeEach(() => {
+        clock = sinon.useFakeTimers();
+        context.setup();
+
+        // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+        const { ServerSentEventHubConnection } = require('../../ServerSentEventHubConnection');
+        context.connection = new ServerSentEventHubConnection(
+            'http://localhost/.cratis/queries/sse',
+            'http://localhost/.cratis/queries/sse/subscribe',
+            'http://localhost/.cratis/queries/sse/unsubscribe',
+            '',
+            30000,
+            CONNECT_TIMEOUT_MS,
+            context.policy
+        );
+
+        context.connection.subscribe('q1', { queryName: 'MyQuery' }, sinon.stub());
+
+        // Open the EventSource but never deliver a Connected message.
+        context.simulateOpen();
+
+        // Advance past the connect timeout.
+        clock.tick(CONNECT_TIMEOUT_MS + 1);
+    });
+
+    afterEach(() => {
+        clock.restore();
+        sinon.restore();
+    });
+
+    it('should schedule a reconnect via the policy', () => {
+        (context.policy.schedule as sinon.SinonStub).calledOnce.should.be.true;
+    });
+}));

package/queries/for_ServerSentEventHubConnection/when_disposing/cleans_up_resources.ts

@@ -0,0 +1,34 @@
+// 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 disposing the hub connection', given(a_server_sent_event_hub_connection, context => {
+    beforeEach(() => {
+        context.setup();
+        context.connection.subscribe('q1', { queryName: 'MyQuery' }, sinon.stub());
+        context.simulateOpen();
+        context.simulateMessage({ type: HubMessageType.Connected, payload: 'conn-1' });
+        context.connection.dispose();
+    });
+
+    afterEach(() => sinon.restore());
+
+    it('should close the EventSource', () => context.fakeEventSource.close.calledOnce.should.be.true);
+    it('should cancel the reconnect policy', () => (context.policy.cancel as sinon.SinonStub).calledOnce.should.be.true);
+    it('should report zero active subscriptions', () => context.connection.queryCount.should.equal(0));
+
+    describe('when an error event fires after dispose', () => {
+        beforeEach(() => {
+            (context.policy.schedule as sinon.SinonStub).reset();
+            context.simulateError();
+        });
+
+        it('should not schedule a reconnect', () => {
+            (context.policy.schedule as sinon.SinonStub).callCount.should.equal(0);
+        });
+    });
+}));

package/queries/for_ServerSentEventHubConnection/when_keep_alive_is_idle/triggers_reconnect.ts

@@ -0,0 +1,48 @@
+// 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';
+
+const KEEP_ALIVE_MS = 500;
+
+describe('when keep-alive interval elapses without any server message', given(a_server_sent_event_hub_connection, context => {
+    let clock: sinon.SinonFakeTimers;
+
+    beforeEach(() => {
+        clock = sinon.useFakeTimers();
+        context.setup();
+
+        // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+        const { ServerSentEventHubConnection } = require('../../ServerSentEventHubConnection');
+        context.connection = new ServerSentEventHubConnection(
+            'http://localhost/.cratis/queries/sse',
+            'http://localhost/.cratis/queries/sse/subscribe',
+            'http://localhost/.cratis/queries/sse/unsubscribe',
+            '',
+            KEEP_ALIVE_MS,
+            15000,
+            context.policy
+        );
+
+        context.connection.subscribe('q1', { queryName: 'MyQuery' }, sinon.stub());
+        context.simulateOpen();
+
+        // Deliver Connected so the connection is fully established.
+        context.simulateMessage({ type: HubMessageType.Connected, payload: 'conn-123' });
+
+        // Advance past the keep-alive interval without any further messages.
+        clock.tick(KEEP_ALIVE_MS + 1);
+    });
+
+    afterEach(() => {
+        clock.restore();
+        sinon.restore();
+    });
+
+    it('should schedule a reconnect via the policy', () => {
+        (context.policy.schedule as sinon.SinonStub).calledOnce.should.be.true;
+    });
+}));