@cratis/arc 20.1.4 → 20.1.6

package/package.json

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

package/queries/HubConnectionKeepAlive.ts

@@ -5,9 +5,15 @@
  * Manages keep-alive behavior for hub connections (both WebSocket and Server-Sent Events).
  *
  * Records connection activity (any message received or sent). An interval fires every
- * {@link intervalMs} milliseconds; if no activity has been recorded since the last tick the
- * provided {@link onIdle} callback is invoked — the caller decides whether to send a ping,
- * trigger a reconnect, or take some other action.
+ * {@link intervalMs} milliseconds; if no activity has been recorded since the last
+ * {@link idleThresholdMs} milliseconds the provided {@link onIdle} callback is invoked —
+ * the caller decides whether to send a ping, trigger a reconnect, or take some other action.
+ *
+ * The idle threshold defaults to the check interval but can be set higher to tolerate
+ * network latency between the server's keep-alive ping and the client's idle check.
+ * For SSE connections, where the idle callback triggers a reconnect, a tolerance of
+ * 1.5× the server's keep-alive interval prevents spurious reconnects caused by the
+ * client's timer firing just before the server's ping arrives.
  *
  * Both {@link WebSocketHubConnection} and {@link ServerSentEventHubConnection} own one instance
  * of this class so the keep-alive logic is written once and behaves identically for both
@@ -16,17 +22,25 @@
 export class HubConnectionKeepAlive {
     private _lastActivityTime = Date.now();
     private _timer?: ReturnType<typeof setInterval>;
+    private readonly _idleThresholdMs: number;
 
     /**
      * Initializes a new instance of {@link HubConnectionKeepAlive}.
      * @param {number} intervalMs How often (in milliseconds) to check for idle connections.
      * @param {() => void} onIdle Callback invoked when the interval fires and no activity has
-     *   been recorded in the last {@link intervalMs} milliseconds.
+     *   been recorded within the idle threshold.
+     * @param {number} idleThresholdMs Optional. How long (in milliseconds) without activity
+     *   before the connection is considered idle. Defaults to {@link intervalMs}. Set this
+     *   higher than {@link intervalMs} when the peer sends keep-alive messages on a similar
+     *   cadence to account for network latency and timer jitter.
      */
     constructor(
         private readonly _intervalMs: number,
         private readonly _onIdle: () => void,
-    ) {}
+        idleThresholdMs?: number,
+    ) {
+        this._idleThresholdMs = idleThresholdMs ?? _intervalMs;
+    }
 
     /**
      * Start the keep-alive timer. Safe to call multiple times — a running timer is stopped first.
@@ -35,7 +49,7 @@ export class HubConnectionKeepAlive {
         this.stop();
         this._lastActivityTime = Date.now();
         this._timer = setInterval(() => {
-            if (Date.now() - this._lastActivityTime >= this._intervalMs) {
+            if (Date.now() - this._lastActivityTime >= this._idleThresholdMs) {
                 this._onIdle();
             }
         }, this._intervalMs);

package/queries/ReconnectPolicy.ts

@@ -45,6 +45,10 @@ export class ReconnectPolicy implements IReconnectPolicy {
             return false;
         }
 
+        // Cancel any pending reconnect timer so we don't fire multiple
+        // concurrent reconnect attempts when schedule() is called rapidly.
+        this.cancel();
+
         this._attempt++;
         const delay = Math.min(this._initialDelayMs + this._delayStepMs * this._attempt, this._maxDelayMs);
         console.log(`Reconnect: attempt ${this._attempt} in ${delay}ms for '${label}'`);

package/queries/ServerSentEventHubConnection.ts

@@ -62,13 +62,20 @@ export class ServerSentEventHubConnection implements IObservableQueryHubConnecti
     ) {
         // SSE is server→client only: the client cannot send pings. Instead we watch for
         // inactivity — if the server stops sending messages (including its own keep-alive
-        // pings) for the entire interval, the connection is stale and we reconnect.
+        // pings) for the entire idle threshold, the connection is stale and we reconnect.
+        //
+        // The idle threshold is set to 1.5× the check interval so the server's keep-alive
+        // ping (which fires on the same cadence) has time to arrive over the network before
+        // the client declares the connection dead. Without this tolerance the client's timer
+        // and the server's timer race — the client often fires first and reconnects
+        // unnecessarily.
+        const idleThresholdMs = Math.round(keepAliveIntervalMs * 1.5);
         this._keepAlive = new HubConnectionKeepAlive(keepAliveIntervalMs, () => {
             if (!this._disconnected && this._subscriptions.size > 0) {
-                console.warn(`SSE hub: no messages received for ${keepAliveIntervalMs}ms, reconnecting '${this._sseUrl}'`);
+                console.warn(`SSE hub: no messages received for ${idleThresholdMs}ms, reconnecting '${this._sseUrl}'`);
                 this.reconnect();
             }
-        });
+        }, idleThresholdMs);
     }
 
     /** @inheritdoc */
@@ -299,8 +306,14 @@ export class ServerSentEventHubConnection implements IObservableQueryHubConnecti
             method: 'POST',
             headers: { 'Content-Type': 'application/json', ...customHeaders },
             body: JSON.stringify(body),
+        }).then(response => {
+            if (!response.ok) {
+                console.warn(`SSE hub: subscribe POST for '${queryId}' returned ${response.status}, reconnecting`);
+                this.reconnect();
+            }
         }).catch(error => {
-            console.error(`SSE hub: subscribe POST failed for '${queryId}'`, error);
+            console.error(`SSE hub: subscribe POST failed for '${queryId}', reconnecting`, error);
+            this.reconnect();
         });
     }
 

package/queries/for_HubConnectionKeepAlive/when_started_with_custom_idle_threshold/respects_threshold.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 { HubConnectionKeepAlive } from '../../HubConnectionKeepAlive';
+
+describe('when started with a custom idle threshold larger than the check interval', () => {
+    let clock: sinon.SinonFakeTimers;
+    let onIdle: sinon.SinonStub;
+    let keepAlive: HubConnectionKeepAlive;
+
+    const checkIntervalMs = 500;
+    const idleThresholdMs = 750;
+
+    beforeEach(() => {
+        clock = sinon.useFakeTimers();
+        onIdle = sinon.stub();
+        keepAlive = new HubConnectionKeepAlive(checkIntervalMs, onIdle, idleThresholdMs);
+        keepAlive.start();
+    });
+
+    afterEach(() => {
+        keepAlive.stop();
+        clock.restore();
+        sinon.restore();
+    });
+
+    describe('and the check interval elapses but idle threshold has not', () => {
+        beforeEach(() => {
+            // Advance past the check interval (500ms) but not the idle threshold (750ms).
+            clock.tick(checkIntervalMs + 1);
+        });
+
+        it('should not invoke the onIdle callback', () => onIdle.called.should.be.false);
+    });
+
+    describe('and the idle threshold elapses', () => {
+        beforeEach(() => {
+            // Advance past the idle threshold. The second interval tick at 1000ms
+            // sees 1000ms of inactivity which exceeds the 750ms threshold.
+            clock.tick(checkIntervalMs * 2 + 1);
+        });
+
+        it('should invoke the onIdle callback', () => onIdle.calledOnce.should.be.true);
+    });
+});

package/queries/for_ReconnectPolicy/when_scheduling/and_rescheduled_before_first_fires/cancels_previous_timer.ts

@@ -0,0 +1,36 @@
+// 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 twice before the first timer fires', () => {
+    let policy: ReconnectPolicy;
+    let clock: sinon.SinonFakeTimers;
+    let firstCallback: sinon.SinonStub;
+    let secondCallback: sinon.SinonStub;
+
+    beforeEach(() => {
+        clock = sinon.useFakeTimers();
+        policy = new ReconnectPolicy(100, 500, 500, 10_000);
+        firstCallback = sinon.stub();
+        secondCallback = sinon.stub();
+
+        policy.schedule(firstCallback, 'first');
+        // Schedule again before the first timer fires.
+        policy.schedule(secondCallback, 'second');
+
+        // Advance past both potential delays:
+        // Attempt 1: min(500+500*1, 10_000) = 1000ms
+        // Attempt 2: min(500+500*2, 10_000) = 1500ms
+        clock.tick(2000);
+    });
+
+    afterEach(() => {
+        clock.restore();
+        sinon.restore();
+    });
+
+    it('should cancel the first timer so it never fires', () => firstCallback.called.should.be.false);
+    it('should fire the second timer', () => secondCallback.calledOnce.should.be.true);
+});

package/queries/for_ServerSentEventHubConnection/when_keep_alive_is_idle/triggers_reconnect.ts

@@ -33,8 +33,11 @@ describe('when keep-alive interval elapses without any server message', given(a_
         // 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);
+        // Advance past the idle threshold (1.5× keep-alive interval) without any further messages.
+        // The check interval fires every KEEP_ALIVE_MS; the idle threshold is KEEP_ALIVE_MS * 1.5.
+        // After the first interval tick (500ms) the elapsed idle time (500ms) is below the
+        // threshold (750ms). At the second tick (1000ms) the elapsed time exceeds the threshold.
+        clock.tick(KEEP_ALIVE_MS * 2 + 1);
     });
 
     afterEach(() => {

package/queries/for_ServerSentEventHubConnection/when_subscribing/and_subscribe_post_fails.ts

@@ -0,0 +1,51 @@
+// 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 subscribe POST returns a non-OK status', given(a_server_sent_event_hub_connection, context => {
+    beforeEach(async () => {
+        context.setup();
+
+        // Make the subscribe POST resolve with a 404 (connection not found on server).
+        context.fetchStub.resolves({ ok: false, status: 404 });
+
+        context.connection.subscribe('q1', { queryName: 'MyQuery' }, sinon.stub());
+        context.simulateOpen();
+        context.simulateMessage({ type: HubMessageType.Connected, payload: 'conn-abc' });
+
+        // Allow the fetch promise chain (.then) to execute.
+        await new Promise(resolve => setTimeout(resolve, 0));
+    });
+
+    afterEach(() => sinon.restore());
+
+    it('should schedule a reconnect via the policy', () => {
+        (context.policy.schedule as sinon.SinonStub).calledOnce.should.be.true;
+    });
+}));
+
+describe('when subscribe POST rejects with a network error', given(a_server_sent_event_hub_connection, context => {
+    beforeEach(async () => {
+        context.setup();
+
+        // Make the subscribe POST reject (network failure).
+        context.fetchStub.rejects(new Error('Network error'));
+
+        context.connection.subscribe('q1', { queryName: 'MyQuery' }, sinon.stub());
+        context.simulateOpen();
+        context.simulateMessage({ type: HubMessageType.Connected, payload: 'conn-abc' });
+
+        // Allow the fetch promise chain (.catch) to execute.
+        await new Promise(resolve => setTimeout(resolve, 0));
+    });
+
+    afterEach(() => sinon.restore());
+
+    it('should schedule a reconnect via the policy', () => {
+        (context.policy.schedule as sinon.SinonStub).calledOnce.should.be.true;
+    });
+}));