@cratis/arc 22.150.0 → 22.152.0

package/queries/for_PollingQueryConnection/when_backing_off/after_a_server_error_with_an_envelope.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 { given } from '../../../given.js';
+import { a_polling_query_connection } from '../given/a_polling_query_connection.js';
+
+describe('when backing off after a server error with an envelope', given(a_polling_query_connection, context => {
+    let beforeRetry: number;
+    beforeEach(async () => {
+        context.fetchStub.callsFake(async () => new Response(JSON.stringify(context.envelope(null, { hasExceptions: true })), { status: 500 }));
+        context.connection.connect(context.dataReceived);
+        await context.clock.tickAsync(0);
+        await context.clock.tickAsync(1999);
+        beforeRetry = context.fetchStub.callCount;
+        await context.clock.tickAsync(1);
+    });
+    it('should emit the error envelope once', () => {
+        context.dataReceived.callCount.should.equal(1);
+        context.dataReceived.firstCall.args[0].hasExceptions.should.be.true;
+    });
+    it('should back off before retrying', () => {
+        beforeRetry.should.equal(1);
+        context.fetchStub.callCount.should.equal(2);
+    });
+}));

package/queries/for_PollingQueryConnection/when_backing_off/after_not_ready.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { given } from '../../../given.js';
+import { a_polling_query_connection } from '../given/a_polling_query_connection.js';
+
+describe('when backing off after not ready', given(a_polling_query_connection, context => {
+    let beforeRetry: number;
+    let emissionsBeforeRetry: number;
+    beforeEach(async () => {
+        context.respond(202);
+        context.connection.connect(context.dataReceived);
+        await context.clock.tickAsync(0);
+        await context.clock.tickAsync(1999);
+        beforeRetry = context.fetchStub.callCount;
+        emissionsBeforeRetry = context.dataReceived.callCount;
+        await context.clock.tickAsync(1001);
+    });
+    it('should wait twice the interval', () => beforeRetry.should.equal(1));
+    it('should not emit the not ready response', () => emissionsBeforeRetry.should.equal(0));
+    it('should return to the normal interval after recovery', () => context.fetchStub.callCount.should.equal(3));
+}));

package/queries/for_PollingQueryConnection/when_backing_off/after_repeated_failures.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { given } from '../../../given.js';
+import { a_polling_query_connection } from '../given/a_polling_query_connection.js';
+
+describe('when backing off after repeated failures', given(a_polling_query_connection, context => {
+    const requestTimes: number[] = [];
+    beforeEach(async () => {
+        requestTimes.length = 0;
+        context.fetchStub.callsFake(async () => {
+            requestTimes.push(context.clock.now);
+            throw new TypeError('offline');
+        });
+        context.connection.connect(context.dataReceived);
+        await context.clock.tickAsync(22000);
+    });
+    it('should double the delay up to the maximum', () => requestTimes.should.deep.equal([0, 2000, 6000, 14000, 22000]));
+}));

package/queries/for_PollingQueryConnection/when_backing_off/after_request_timeout.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { given } from '../../../given.js';
+import { a_polling_query_connection } from '../given/a_polling_query_connection.js';
+
+describe('when backing off after request timeout', given(a_polling_query_connection, context => {
+    let beforeRetry: number;
+    let emissionsBeforeRetry: number;
+    beforeEach(async () => {
+        context.respond(408);
+        context.connection.connect(context.dataReceived);
+        await context.clock.tickAsync(0);
+        await context.clock.tickAsync(1999);
+        beforeRetry = context.fetchStub.callCount;
+        emissionsBeforeRetry = context.dataReceived.callCount;
+        await context.clock.tickAsync(1001);
+    });
+    it('should wait twice the interval', () => beforeRetry.should.equal(1));
+    it('should not emit the timeout response', () => emissionsBeforeRetry.should.equal(0));
+    it('should return to the normal interval after recovery', () => context.fetchStub.callCount.should.equal(3));
+}));

package/queries/for_PollingQueryConnection/when_backing_off/with_jitter.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { given } from '../../../given.js';
+import { a_polling_query_connection } from '../given/a_polling_query_connection.js';
+
+describe('when backing off with jitter', given(a_polling_query_connection, context => {
+    let beforeRetry: number;
+    beforeEach(async () => {
+        context.random.returns(1);
+        context.fetchStub.onFirstCall().rejects(new TypeError('offline'));
+        context.connection.connect(context.dataReceived);
+        await context.clock.tickAsync(2399);
+        beforeRetry = context.fetchStub.callCount;
+        await context.clock.tickAsync(1);
+    });
+    it('should not retry before the jittered delay', () => beforeRetry.should.equal(1));
+    it('should retry at the jittered delay', () => context.fetchStub.callCount.should.equal(2));
+}));

package/queries/for_PollingQueryConnection/when_disconnecting/and_fetch_rejects_on_abort.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { given } from '../../../given.js';
+import { a_polling_query_connection } from '../given/a_polling_query_connection.js';
+
+describe('when disconnecting and fetch rejects on abort', given(a_polling_query_connection, context => {
+    beforeEach(async () => {
+        context.fetchStub.callsFake((_url: string, init: RequestInit) => new Promise<Response>((_resolve, reject) => {
+            init.signal!.addEventListener('abort', () => reject(new DOMException('The operation was aborted.', 'AbortError')), { once: true });
+        }));
+        context.connection.connect(context.dataReceived);
+        context.connection.disconnect();
+        await context.clock.tickAsync(60000);
+    });
+    it('should not deliver a result', () => context.dataReceived.called.should.be.false);
+    it('should not retry the aborted request', () => context.fetchStub.callCount.should.equal(1));
+    it('should leave no pending polling timer', () => context.clock.countTimers().should.equal(0));
+}));

package/queries/for_PollingQueryConnection/when_disconnecting/while_a_request_is_in_flight.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { given } from '../../../given.js';
+import { a_polling_query_connection } from '../given/a_polling_query_connection.js';
+
+describe('when disconnecting while a request is in flight', given(a_polling_query_connection, context => {
+    beforeEach(async () => {
+        let resolveRequest!: (response: Response) => void;
+        context.fetchStub.returns(new Promise<Response>(resolve => { resolveRequest = resolve; }));
+        context.connection.connect(context.dataReceived);
+        context.connection.disconnect();
+        resolveRequest(new Response(JSON.stringify(context.envelope('late'))));
+        await context.clock.tickAsync(60000);
+    });
+    it('should abort the request', () => context.fetchStub.firstCall.args[1].signal.aborted.should.be.true);
+    it('should ignore a late result', () => context.dataReceived.called.should.be.false);
+    it('should not poll again', () => context.fetchStub.callCount.should.equal(1));
+}));

package/queries/for_PollingQueryConnection/when_disconnecting/while_waiting_for_the_next_poll.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { given } from '../../../given.js';
+import { a_polling_query_connection } from '../given/a_polling_query_connection.js';
+
+describe('when disconnecting while waiting for the next poll', given(a_polling_query_connection, context => {
+    beforeEach(async () => {
+        context.connection.connect(context.dataReceived);
+        await context.clock.tickAsync(0);
+        context.connection.disconnect();
+        context.connection.connect(context.dataReceived);
+        await context.clock.tickAsync(60000);
+    });
+    it('should not poll again even if connect is called', () => context.fetchStub.callCount.should.equal(1));
+    it('should clear the timer', () => context.clock.countTimers().should.equal(0));
+}));

package/queries/for_PollingQueryConnection/when_polling/and_a_request_is_still_in_flight.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.
+
+import { given } from '../../../given.js';
+import { a_polling_query_connection } from '../given/a_polling_query_connection.js';
+
+describe('when polling and a request is still in flight', given(a_polling_query_connection, context => {
+    beforeEach(async () => {
+        context.fetchStub.returns(new Promise<Response>(() => {}));
+        context.connection.connect(context.dataReceived);
+        context.connection.connect(context.dataReceived);
+        await context.clock.tickAsync(5000);
+    });
+    it('should have only one request in flight', () => context.fetchStub.callCount.should.equal(1));
+}));

package/queries/for_PollingQueryConnection/when_polling/and_data_changes.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 { given } from '../../../given.js';
+import { a_polling_query_connection } from '../given/a_polling_query_connection.js';
+
+describe('when polling and data changes', given(a_polling_query_connection, context => {
+    beforeEach(async () => {
+        context.fetchStub.onFirstCall().resolves(new Response(JSON.stringify(context.envelope('first'))));
+        context.connection.connect(context.dataReceived, { filter: 'a', page: 1, pageSize: 10 });
+        await context.clock.tickAsync(0);
+        await context.clock.tickAsync(1000);
+    });
+    it('should get the query route with the HTTP arguments immediately', () => {
+        String(context.fetchStub.firstCall.args[0]).should.equal('https://example.com/api/items/42?filter=a&page=1&pageSize=10&waitForFirstResult=true');
+        context.fetchStub.firstCall.args[1].method.should.equal('GET');
+    });
+    it('should include custom and query headers', () => {
+        Object.fromEntries(context.fetchStub.firstCall.args[1].headers).should.deep.equal({
+            authorization: 'Bearer x', accept: 'application/json', 'content-type': 'application/json', 'x-cratis-microservice': 'svc'
+        });
+    });
+    it('should deliver changed data and paging metadata', () => {
+        context.dataReceived.callCount.should.equal(2);
+        context.dataReceived.secondCall.args[0].data.should.equal('same');
+        context.dataReceived.secondCall.args[0].paging.totalItems.should.equal(25);
+    });
+    it('should measure request latency', () => {
+        context.connection.lastPingLatency.should.be.at.least(0);
+        context.connection.averageLatency.should.be.at.least(0);
+    });
+}));
+
+for (const changes of [
+    { paging: { page: 2, size: 10, totalItems: 30, totalPages: 3 } },
+    { isSuccess: false }, { isAuthorized: false }, { isValid: false }, { hasExceptions: true },
+    { validationResults: [{ message: 'invalid' }] }, { exceptionMessages: ['failed'] }, { exceptionStackTrace: 'trace' }
+]) {
+    describe(`when polling and envelope metadata changes: ${Object.keys(changes)[0]}`, given(a_polling_query_connection, context => {
+        beforeEach(async () => {
+            context.responses = [
+                new Response(JSON.stringify(context.envelope('same'))),
+                new Response(JSON.stringify(context.envelope('same', changes)))
+            ];
+            context.connection.connect(context.dataReceived);
+            await context.clock.tickAsync(0);
+            await context.clock.tickAsync(1000);
+        });
+        it('should emit changed metadata even when the data is unchanged', () => context.dataReceived.callCount.should.equal(2));
+    }));
+}

package/queries/for_PollingQueryConnection/when_polling/and_data_is_unchanged.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 { given } from '../../../given.js';
+import { a_polling_query_connection } from '../given/a_polling_query_connection.js';
+
+describe('when polling and only the correlation id changes', given(a_polling_query_connection, context => {
+    beforeEach(async () => {
+        const first = context.envelope({ name: 'same', value: 1 });
+        const second = { ...context.envelope({ value: 1, name: 'same' }) };
+        context.responses = [new Response(JSON.stringify(first)), new Response(JSON.stringify(second))];
+        context.dataReceived.callsFake(result => {
+            result.isReady = true;
+            result.paging.totalItems = 999;
+        });
+        context.connection.connect(context.dataReceived);
+        await context.clock.tickAsync(0);
+        await context.clock.tickAsync(1000);
+    });
+    it('should ignore property order, correlation id and consumer mutation when comparing', () => {
+        context.fetchStub.callCount.should.equal(2);
+        context.dataReceived.callCount.should.equal(1);
+    });
+}));

package/queries/for_PollingQueryConnection/when_polling/with_global_and_instance_headers.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 { given } from '../../../given.js';
+import { Globals } from '../../../Globals.js';
+import { a_polling_query_connection } from '../given/a_polling_query_connection.js';
+
+describe('when polling with global and instance headers', given(a_polling_query_connection, context => {
+    let originalHeadersCallback: typeof Globals.httpHeadersCallback;
+    beforeEach(async () => {
+        originalHeadersCallback = Globals.httpHeadersCallback;
+        Globals.httpHeadersCallback = () => ({ 'X-Global': 'global', Authorization: 'Bearer global' });
+        context.connection.connect(context.dataReceived);
+        await context.clock.tickAsync(0);
+        await context.clock.tickAsync(1000);
+    });
+    afterEach(() => {
+        Globals.httpHeadersCallback = originalHeadersCallback;
+    });
+    it('should include global headers on every poll', () => {
+        context.fetchStub.firstCall.args[1].headers.get('X-Global').should.equal('global');
+        context.fetchStub.secondCall.args[1].headers.get('X-Global').should.equal('global');
+    });
+    it('should let instance headers override the same global header', () => {
+        context.fetchStub.firstCall.args[1].headers.get('Authorization').should.equal('Bearer x');
+        context.fetchStub.secondCall.args[1].headers.get('Authorization').should.equal('Bearer x');
+    });
+}));

package/queries/for_PollingQueryConnection/when_receiving_a_poll_hint/above_the_maximum.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { given } from '../../../given.js';
+import { a_polling_query_connection } from '../given/a_polling_query_connection.js';
+
+describe('when receiving a poll hint above the maximum', given(a_polling_query_connection, context => {
+    let beforeNextPoll: number;
+    beforeEach(async () => {
+        context.respond(200, { 'Cratis-Query-Poll-After': '60' });
+        context.connection.connect(context.dataReceived);
+        await context.clock.tickAsync(0);
+        await context.clock.tickAsync(7999);
+        beforeNextPoll = context.fetchStub.callCount;
+        await context.clock.tickAsync(1);
+    });
+    it('should wait until the maximum', () => beforeNextPoll.should.equal(1));
+    it('should poll at the maximum', () => context.fetchStub.callCount.should.equal(2));
+}));

package/queries/for_PollingQueryConnection/when_receiving_a_poll_hint/below_the_minimum.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 { given } from '../../../given.js';
+import { a_polling_query_connection } from '../given/a_polling_query_connection.js';
+
+for (const hint of ['0', '0.1']) {
+    describe(`when receiving a poll hint below the minimum: ${hint}`, given(a_polling_query_connection, context => {
+        let beforeNextPoll: number;
+        beforeEach(async () => {
+            context.respond(200, { 'Cratis-Query-Poll-After': hint });
+            context.connection.connect(context.dataReceived);
+            await context.clock.tickAsync(0);
+            await context.clock.tickAsync(499);
+            beforeNextPoll = context.fetchStub.callCount;
+            await context.clock.tickAsync(1);
+        });
+        it('should not poll before the minimum', () => beforeNextPoll.should.equal(1));
+        it('should poll at the minimum', () => context.fetchStub.callCount.should.equal(2));
+    }));
+}

package/queries/for_PollingQueryConnection/when_receiving_a_poll_hint/on_a_not_ready_response.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { given } from '../../../given.js';
+import { a_polling_query_connection } from '../given/a_polling_query_connection.js';
+
+describe('when receiving a poll hint on a not ready response', given(a_polling_query_connection, context => {
+    let beforeNextPoll: number;
+    beforeEach(async () => {
+        context.respond(202, { 'Cratis-Query-Poll-After': '3' });
+        context.connection.connect(context.dataReceived);
+        await context.clock.tickAsync(0);
+        await context.clock.tickAsync(2999);
+        beforeNextPoll = context.fetchStub.callCount;
+        await context.clock.tickAsync(1);
+    });
+    it('should prefer the hint over backoff', () => beforeNextPoll.should.equal(1));
+    it('should poll at the hinted interval', () => context.fetchStub.callCount.should.equal(2));
+}));

package/queries/for_PollingQueryConnection/when_receiving_a_poll_hint/that_is_invalid.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 { given } from '../../../given.js';
+import { a_polling_query_connection } from '../given/a_polling_query_connection.js';
+
+for (const hint of ['abc', '-1', 'Infinity', '5abc', '', ' ']) {
+    describe(`when receiving a poll hint that is invalid: ${hint}`, given(a_polling_query_connection, context => {
+        let beforeNextPoll: number;
+        beforeEach(async () => {
+            context.respond(200, { 'Cratis-Query-Poll-After': hint });
+            context.connection.connect(context.dataReceived);
+            await context.clock.tickAsync(0);
+            await context.clock.tickAsync(999);
+            beforeNextPoll = context.fetchStub.callCount;
+            await context.clock.tickAsync(1);
+        });
+        it('should wait until the configured interval', () => beforeNextPoll.should.equal(1));
+        it('should poll at the configured interval', () => context.fetchStub.callCount.should.equal(2));
+    }));
+}

package/queries/for_PollingQueryConnection/when_receiving_a_poll_hint/within_bounds.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { given } from '../../../given.js';
+import { a_polling_query_connection } from '../given/a_polling_query_connection.js';
+
+describe('when receiving a poll hint within bounds', given(a_polling_query_connection, context => {
+    let beforeNextPoll: number;
+    beforeEach(async () => {
+        context.respond(200, { 'Cratis-Query-Poll-After': '3' });
+        context.connection.connect(context.dataReceived);
+        await context.clock.tickAsync(0);
+        await context.clock.tickAsync(2999);
+        beforeNextPoll = context.fetchStub.callCount;
+        await context.clock.tickAsync(1);
+    });
+    it('should wait for the hint in seconds', () => beforeNextPoll.should.equal(1));
+    it('should poll at the hinted interval', () => context.fetchStub.callCount.should.equal(2));
+}));

package/queries/for_PollingQueryConnection/when_receiving_invalid_arguments/stops_polling.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.
+
+import { given } from '../../../given.js';
+import { a_polling_query_connection } from '../given/a_polling_query_connection.js';
+
+describe('when receiving invalid arguments', given(a_polling_query_connection, context => {
+    beforeEach(async () => {
+        context.respond(400, {}, { isValid: false });
+        context.connection.connect(context.dataReceived);
+        await context.clock.tickAsync(60000);
+    });
+    it('should deliver the validation result', () => context.dataReceived.firstCall.args[0].isValid.should.be.false);
+    it('should stop polling', () => context.fetchStub.callCount.should.equal(1));
+}));

package/queries/for_PollingQueryConnection/when_receiving_unauthorized/stops_polling.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { given } from '../../../given.js';
+import { a_polling_query_connection } from '../given/a_polling_query_connection.js';
+
+for (const status of [200, 401, 403]) {
+    describe(`when receiving an unauthorized envelope with status ${status}`, given(a_polling_query_connection, context => {
+        beforeEach(async () => {
+            context.respond(status, {}, { isAuthorized: false });
+            context.connection.connect(context.dataReceived);
+            await context.clock.tickAsync(60000);
+        });
+        it('should deliver the unauthorized result', () => context.dataReceived.firstCall.args[0].isAuthorized.should.be.false);
+        it('should stop polling', () => context.fetchStub.callCount.should.equal(1));
+    }));
+}

package/queries/for_PollingQueryConnection/when_receiving_unauthorized/with_a_non_json_body.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { given } from '../../../given.js';
+import { a_polling_query_connection } from '../given/a_polling_query_connection.js';
+
+for (const status of [401, 403]) {
+    describe(`when receiving unauthorized with a non JSON body and status ${status}`, given(a_polling_query_connection, context => {
+        beforeEach(async () => {
+            context.fetchStub.onFirstCall().resolves(new Response('Unauthorized', { status }));
+            context.connection.connect(context.dataReceived);
+            await context.clock.tickAsync(60000);
+        });
+        it('should deliver an unauthorized result', () => context.dataReceived.firstCall.args[0].isAuthorized.should.be.false);
+        it('should stop polling', () => context.fetchStub.callCount.should.equal(1));
+    }));
+}

package/queries/index.ts

@@ -34,6 +34,8 @@ export * from './ObservableQueryMultiplexer.js';
 export * from './ObservableQuerySubscription.js';
 export * from './WebSocketMessage.js';
 export * from './QueryTransportMethod.js';
+export * from './PollingOptions.js';
+export * from './PollingQueryConnection.js';
 export * from './QueryInstanceCache.js';
 export * from './reconcileQueryData.js';
 export * from './deserializeQueryModel.js';