@cratis/arc 22.150.0 → 22.152.0

package/package.json

@@ -1,7 +1,7 @@
 {
     "type": "module",
     "name": "@cratis/arc",
-    "version": "22.150.0",
+    "version": "22.152.0",
     "description": "TypeScript command, query, validation, identity, and messaging runtime for Cratis Arc — the CQRS application framework for ASP.NET Core — used by generated proxies.",
     "keywords": [
         "cratis",

package/queries/ObservableQueryConnectionFactory.ts

@@ -1,6 +1,9 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import { GetHttpHeaders } from '../GetHttpHeaders.js';
+import { PollingOptions } from './PollingOptions.js';
+import { PollingQueryConnection } from './PollingQueryConnection.js';
 import { Globals } from '../Globals.js';
 import { joinPaths } from '../joinPaths.js';
 import { UrlHelpers } from '../UrlHelpers.js';
@@ -40,12 +43,17 @@ export interface QueryConnectionDescriptor {
     microservice: string;
     /** Route/query arguments for the current subscription. */
     args?: object;
+    /** Per-query custom headers used by HTTP polling. */
+    httpHeadersCallback?: GetHttpHeaders;
+    /** Per-query timing overrides for HTTP polling. */
+    pollingOptions?: Partial<PollingOptions>;
 }
 
 /**
  * Single entry-point for creating observable query connections.
  *
- * The transport is chosen as a 2x2 matrix of (direct | hub) x (WebSocket | SSE):
+ * Polling always uses each query's HTTP route. Persistent transports use a
+ * 2x2 matrix of (direct | hub) x (WebSocket | SSE):
  *
  * |                | Direct (per-query URL)         | Hub (centralized endpoint)    |
  * |----------------|-------------------------------|-------------------------------|
@@ -58,6 +66,13 @@ export interface QueryConnectionDescriptor {
  * {@link ObservableQueryFor} never needs to know which transport is in use.
  */
 export function createObservableQueryConnection<TDataType>(descriptor: QueryConnectionDescriptor): IObservableQueryConnection<TDataType> {
+    if (Globals.queryTransportMethod === QueryTransportMethod.Polling) {
+        return new PollingQueryConnection<TDataType>(
+            buildDirectUrl(descriptor), descriptor.httpHeadersCallback ?? (() => ({})),
+            descriptor.microservice, { ...Globals.queryPollingOptions, ...descriptor.pollingOptions }
+        );
+    }
+
     const isSSE = Globals.queryTransportMethod === QueryTransportMethod.ServerSentEvents;
 
     if (Globals.queryDirectMode) {
@@ -69,6 +84,14 @@ export function createObservableQueryConnection<TDataType>(descriptor: QueryConn
     return createMultiplexedConnection<TDataType>(descriptor, isSSE);
 }
 
+/**
+ * Determines whether the selected transport connects to each query's own route rather than a hub.
+ * @returns True for direct mode or HTTP polling.
+ */
+export function connectsToQueryRoute(): boolean {
+    return Globals.queryDirectMode || Globals.queryTransportMethod === QueryTransportMethod.Polling;
+}
+
 // ---- Direct mode: one connection per query, hitting the query's own URL ----
 
 function buildDirectUrl(descriptor: QueryConnectionDescriptor): URL {

package/queries/ObservableQueryFor.ts

@@ -7,7 +7,8 @@ import { ValidateRequestArguments } from './ValidateRequestArguments.js';
 import type { QueryValidator } from './QueryValidator.js';
 import type { IObservableQueryConnection } from './IObservableQueryConnection.js';
 import { NullObservableQueryConnection } from './NullObservableQueryConnection.js';
-import { createObservableQueryConnection } from './ObservableQueryConnectionFactory.js';
+import { PollingOptions } from './PollingOptions.js';
+import { createObservableQueryConnection, connectsToQueryRoute } from './ObservableQueryConnectionFactory.js';
 import type { Constructor } from '@cratis/fundamentals';
 import { deserializeQueryModel, deserializeQueryModels } from './deserializeQueryModel.js';
 import { QueryResult } from './QueryResult.js';
@@ -44,6 +45,7 @@ export abstract class ObservableQueryFor<
     private _connection?: IObservableQueryConnection<TDataType>;
     private _httpHeadersCallback: GetHttpHeaders;
     private _httpMethod?: QueryHttpMethod;
+    private _pollingOptions?: Partial<PollingOptions>;
 
     abstract readonly route: string;
     abstract readonly defaultValue: TDataType;
@@ -100,6 +102,14 @@ export abstract class ObservableQueryFor<
         this._httpHeadersCallback = callback;
     }
 
+    /**
+     * Overrides {@link Globals.queryPollingOptions} for this query instance on its next subscription.
+     * @param options The polling timing overrides to apply on the next subscribe.
+     */
+    setPollingOptions(options: Partial<PollingOptions>): void {
+        this._pollingOptions = options;
+    }
+
     /** @inheritdoc */
     setHttpMethod(method: QueryHttpMethod): void {
         this._httpMethod = method;
@@ -131,6 +141,8 @@ export abstract class ObservableQueryFor<
                 apiBasePath: this._apiBasePath,
                 microservice: this._microservice,
                 args: args as object,
+                httpHeadersCallback: this._httpHeadersCallback,
+                pollingOptions: this._pollingOptions,
             });
         } else {
             this._connection = new NullObservableQueryConnection(this.defaultValue);
@@ -140,7 +152,7 @@ export abstract class ObservableQueryFor<
         // must take precedence over any stale instance property values. Spread parameterValues
         // first so that the caller-supplied args can override them.
         //
-        // In direct mode the route arguments are already embedded in the URL path, so only
+        // In direct mode or polling the route arguments are already embedded in the URL path, so only
         // the unused (non-route) parameters are appended as additional query arguments.
         // In multiplexed mode ALL arguments — including route-derived ones — must be included
         // in the subscribe payload so the server can execute the query correctly.
@@ -151,7 +163,7 @@ export abstract class ObservableQueryFor<
         );
         const connectionQueryArguments: any = {
             ...parameterValues,
-            ...(Globals.queryDirectMode ? unusedParameters : (args as object) || {}),
+            ...(connectsToQueryRoute() ? unusedParameters : (args as object) || {}),
             ...this.buildQueryArguments(),
         };
 

package/queries/PollingOptions.ts

@@ -0,0 +1,16 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** Timing policy for HTTP observable-query polling. */
+export interface PollingOptions {
+    /** Normal interval after a successful poll, in milliseconds. Defaults to 5000. */
+    intervalMs: number;
+    /** Minimum delay, including server hints and jitter, in milliseconds. Defaults to 1000. */
+    minIntervalMs: number;
+    /** Maximum delay, including server hints and jitter, in milliseconds. Defaults to 60000. */
+    maxIntervalMs: number;
+    /** Exponential multiplier after transient failures. Defaults to 2. */
+    backoffMultiplier: number;
+    /** Symmetric random proportion applied to backoff delays. Defaults to 0.2 (20%). */
+    jitterRatio: number;
+}

package/queries/PollingQueryConnection.ts

@@ -0,0 +1,149 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { GetHttpHeaders } from '../GetHttpHeaders.js';
+import { Globals } from '../Globals.js';
+import { UrlHelpers } from '../UrlHelpers.js';
+import { deepEqual } from '../deepEqual.js';
+import { DataReceived } from './ObservableQueryConnection.js';
+import { IObservableQueryConnection } from './IObservableQueryConnection.js';
+import { PollingOptions } from './PollingOptions.js';
+import { QueryResult } from './QueryResult.js';
+import { isAbortError } from './isAbortError.js';
+
+/** Response header specifying the next poll delay in seconds. */
+export const QUERY_POLL_AFTER_HEADER = 'Cratis-Query-Poll-After';
+
+/** Observes a query using sequential HTTP GET snapshots rather than a persistent connection. */
+export class PollingQueryConnection<TDataType> implements IObservableQueryConnection<TDataType> {
+    private _started = false;
+    private _disconnected = false;
+    private _unauthorized = false;
+    private _timer?: ReturnType<typeof setTimeout>;
+    private _controller?: AbortController;
+    private _failures = 0;
+    private _previousComparable?: object;
+    private _lastPingLatency = 0;
+    private _totalLatency = 0;
+    private _requestCount = 0;
+
+    /**
+     * Initializes a polling connection.
+     * @param _url The per-query HTTP endpoint.
+     * @param _httpHeadersCallback Custom headers evaluated for each request.
+     * @param _microservice The microservice identifier sent in the configured HTTP header.
+     * @param _options The resolved timing policy for this connection.
+     */
+    constructor(
+        private readonly _url: URL,
+        private readonly _httpHeadersCallback: GetHttpHeaders,
+        private readonly _microservice: string,
+        private readonly _options: PollingOptions
+    ) {}
+
+    /** @inheritdoc */
+    get lastPingLatency(): number { return this._lastPingLatency; }
+
+    /** @inheritdoc */
+    get averageLatency(): number {
+        return this._requestCount ? this._totalLatency / this._requestCount : 0;
+    }
+
+    /** @inheritdoc */
+    connect(dataReceived: DataReceived<TDataType>, queryArguments?: object): void {
+        if (this._started || this._disconnected || this._unauthorized) return;
+        this._started = true;
+        const url = new URL(this._url);
+        const parameters = UrlHelpers.buildQueryParams(queryArguments ?? {}, { waitForFirstResult: 'true' });
+        parameters.forEach((value, key) => url.searchParams.append(key, value));
+        void this.poll(url, dataReceived);
+    }
+
+    /** @inheritdoc */
+    disconnect(): void {
+        this._disconnected = true;
+        clearTimeout(this._timer);
+        this._timer = undefined;
+        this._controller?.abort();
+    }
+
+    private async poll(url: URL, dataReceived: DataReceived<TDataType>): Promise<void> {
+        this._controller = new AbortController();
+        const started = performance.now();
+        let delay: number;
+        try {
+            const headers = new Headers({
+                ...Object.fromEntries(new Headers(Globals.httpHeadersCallback?.())),
+                ...Object.fromEntries(new Headers(this._httpHeadersCallback()))
+            });
+            headers.set('Accept', 'application/json');
+            headers.set('Content-Type', 'application/json');
+            if (this._microservice) headers.set(Globals.microserviceHttpHeader, this._microservice);
+            const response = await fetch(url.toString(), { method: 'GET', headers, signal: this._controller.signal });
+            if (this._disconnected) return;
+            const body = await response.text();
+            if (this._disconnected) return;
+            this._lastPingLatency = performance.now() - started;
+            this._totalLatency += this._lastPingLatency;
+            this._requestCount++;
+            delay = this.handleResponse(response, body, dataReceived);
+        } catch (error) {
+            if (this._disconnected || this._unauthorized || isAbortError(error)) return;
+            delay = this.backoff();
+        }
+        if (!this._disconnected && !this._unauthorized) {
+            this._timer = setTimeout(() => { void this.poll(url, dataReceived); }, delay);
+        }
+    }
+
+    private handleResponse(response: Response, body: string, dataReceived: DataReceived<TDataType>): number {
+        let result = this.parseResult(body);
+        if (response.status === 401 || response.status === 403 || result?.isAuthorized === false) {
+            console.warn(`Polling: query for '${this._url}' was ended by the server - no longer authorized`);
+            this._unauthorized = true;
+            result ??= { ...QueryResult.unauthorized<TDataType>() } as QueryResult<TDataType>;
+            result = { ...result, isAuthorized: false } as QueryResult<TDataType>;
+            this.emitChanged(result, JSON.stringify(result), dataReceived);
+            return 0;
+        }
+        if (result?.isValid === false) {
+            this.disconnect();
+            this.emitChanged(result, body, dataReceived);
+            return 0;
+        }
+        const success = response.status === 200 && result !== undefined;
+        if (result && (success || response.status >= 500)) this.emitChanged(result, body, dataReceived);
+        if (success) this._failures = 0;
+        const delay = success ? this.clamp(this._options.intervalMs) : this.backoff();
+        const hint = response.headers.get(QUERY_POLL_AFTER_HEADER);
+        const seconds = hint?.trim() ? Number(hint) : NaN;
+        return Number.isFinite(seconds) && seconds >= 0 ? this.clamp(seconds * 1000) : delay;
+    }
+
+    private parseResult(body: string): QueryResult<TDataType> | undefined {
+        try {
+            const result = JSON.parse(body) as QueryResult<TDataType>;
+            if (result && typeof result === 'object' && typeof result.isAuthorized === 'boolean') return result;
+        } catch {
+            // Non-JSON responses are transient failures, except for terminal authentication failures.
+        }
+        return undefined;
+    }
+
+    private emitChanged(result: QueryResult<TDataType>, body: string, dataReceived: DataReceived<TDataType>): void {
+        const comparable = JSON.parse(body) as { correlationId?: string };
+        delete comparable.correlationId;
+        if (deepEqual(this._previousComparable, comparable)) return;
+        this._previousComparable = comparable;
+        dataReceived(result);
+    }
+
+    private backoff(): number {
+        const jitter = 1 + this._options.jitterRatio * (2 * Math.random() - 1);
+        return this.clamp(this._options.intervalMs * this._options.backoffMultiplier ** ++this._failures * jitter);
+    }
+
+    private clamp(delay: number): number {
+        return Math.min(this._options.maxIntervalMs, Math.max(this._options.minIntervalMs, delay));
+    }
+}

package/queries/QueryTransportMethod.ts

@@ -14,4 +14,7 @@ export enum QueryTransportMethod {
      * Use Server-Sent Events (SSE) for real-time data streaming.
      */
     ServerSentEvents = 'serverSentEvents',
+
+    /** Use HTTP GET snapshots for observable queries. */
+    Polling = 'polling',
 }

package/queries/for_ObservableQueryConnectionFactory/when_creating/with_direct_mode_and_polling_transport.ts

@@ -0,0 +1,47 @@
+// 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.js';
+import { Globals } from '../../../Globals.js';
+import { a_descriptor } from '../given/a_descriptor.js';
+import { QueryTransportMethod } from '../../QueryTransportMethod.js';
+import { PollingQueryConnection } from '../../PollingQueryConnection.js';
+import { createObservableQueryConnection } from '../../ObservableQueryConnectionFactory.js';
+import { getSharedMultiplexer, resetSharedMultiplexer } from '../../ObservableQueryMultiplexer.js';
+import { IObservableQueryConnection } from '../../IObservableQueryConnection.js';
+
+describe('when creating with direct mode and polling transport', given(a_descriptor, context => {
+    let connection: IObservableQueryConnection<unknown>;
+    let eventSource: sinon.SinonStub;
+    let webSocket: sinon.SinonStub;
+    const originalEventSource = Object.getOwnPropertyDescriptor(globalThis, 'EventSource');
+    const originalWebSocket = Object.getOwnPropertyDescriptor(globalThis, 'WebSocket');
+
+    beforeEach(() => {
+        resetSharedMultiplexer();
+        Globals.queryDirectMode = true;
+        Globals.queryTransportMethod = QueryTransportMethod.Polling;
+        eventSource = sinon.stub().throws('EventSource must not be used');
+        webSocket = sinon.stub().throws('WebSocket must not be used');
+        Object.defineProperty(globalThis, 'EventSource', { configurable: true, value: eventSource });
+        Object.defineProperty(globalThis, 'WebSocket', { configurable: true, value: webSocket });
+        connection = createObservableQueryConnection(context.descriptor);
+    });
+    afterEach(() => {
+        connection?.disconnect();
+        Globals.queryDirectMode = context.originalDirectMode;
+        Globals.queryTransportMethod = context.originalTransportMethod;
+        if (originalEventSource) Object.defineProperty(globalThis, 'EventSource', originalEventSource);
+        else delete (globalThis as Record<string, unknown>).EventSource;
+        if (originalWebSocket) Object.defineProperty(globalThis, 'WebSocket', originalWebSocket);
+        else delete (globalThis as Record<string, unknown>).WebSocket;
+        resetSharedMultiplexer();
+    });
+    it('should return a polling connection', () => connection.should.be.instanceOf(PollingQueryConnection));
+    it('should not create persistent transports', () => {
+        eventSource.called.should.be.false;
+        webSocket.called.should.be.false;
+    });
+    it('should not create a multiplexer', () => (getSharedMultiplexer() === undefined).should.be.true);
+}));

package/queries/for_ObservableQueryConnectionFactory/when_creating/with_hub_mode_and_polling_transport.ts

@@ -0,0 +1,47 @@
+// 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.js';
+import { Globals } from '../../../Globals.js';
+import { a_descriptor } from '../given/a_descriptor.js';
+import { QueryTransportMethod } from '../../QueryTransportMethod.js';
+import { PollingQueryConnection } from '../../PollingQueryConnection.js';
+import { createObservableQueryConnection } from '../../ObservableQueryConnectionFactory.js';
+import { getSharedMultiplexer, resetSharedMultiplexer } from '../../ObservableQueryMultiplexer.js';
+import { IObservableQueryConnection } from '../../IObservableQueryConnection.js';
+
+describe('when creating with hub mode and polling transport', given(a_descriptor, context => {
+    let connection: IObservableQueryConnection<unknown>;
+    let eventSource: sinon.SinonStub;
+    let webSocket: sinon.SinonStub;
+    const originalEventSource = Object.getOwnPropertyDescriptor(globalThis, 'EventSource');
+    const originalWebSocket = Object.getOwnPropertyDescriptor(globalThis, 'WebSocket');
+
+    beforeEach(() => {
+        resetSharedMultiplexer();
+        Globals.queryDirectMode = false;
+        Globals.queryTransportMethod = QueryTransportMethod.Polling;
+        eventSource = sinon.stub().throws('EventSource must not be used');
+        webSocket = sinon.stub().throws('WebSocket must not be used');
+        Object.defineProperty(globalThis, 'EventSource', { configurable: true, value: eventSource });
+        Object.defineProperty(globalThis, 'WebSocket', { configurable: true, value: webSocket });
+        connection = createObservableQueryConnection(context.descriptor);
+    });
+    afterEach(() => {
+        connection?.disconnect();
+        Globals.queryDirectMode = context.originalDirectMode;
+        Globals.queryTransportMethod = context.originalTransportMethod;
+        if (originalEventSource) Object.defineProperty(globalThis, 'EventSource', originalEventSource);
+        else delete (globalThis as Record<string, unknown>).EventSource;
+        if (originalWebSocket) Object.defineProperty(globalThis, 'WebSocket', originalWebSocket);
+        else delete (globalThis as Record<string, unknown>).WebSocket;
+        resetSharedMultiplexer();
+    });
+    it('should return a polling connection', () => connection.should.be.instanceOf(PollingQueryConnection));
+    it('should not create persistent transports', () => {
+        eventSource.called.should.be.false;
+        webSocket.called.should.be.false;
+    });
+    it('should not create a multiplexer', () => (getSharedMultiplexer() === undefined).should.be.true);
+}));

package/queries/for_ObservableQueryFor/when_subscribing/with_polling_transport.ts

@@ -0,0 +1,115 @@
+// 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.js';
+import { Globals } from '../../../Globals.js';
+import { createFetchHelper } from '../../../helpers/fetchHelper.js';
+import { an_observable_query_for } from '../given/an_observable_query_for.js';
+import { QueryTransportMethod } from '../../QueryTransportMethod.js';
+import { ObservableQuerySubscription } from '../../ObservableQuerySubscription.js';
+import { Paging } from '../../Paging.js';
+import { Sorting } from '../../Sorting.js';
+import { SortDirection } from '../../SortDirection.js';
+
+describe('when subscribing with polling transport', given(an_observable_query_for, context => {
+    const fetchHelper = createFetchHelper();
+    let originals: Pick<typeof Globals, 'queryDirectMode' | 'queryTransportMethod' | 'queryPollingOptions'>;
+    let subscription: ObservableQuerySubscription<string>;
+    let clock: sinon.SinonFakeTimers;
+    let fetchStub: sinon.SinonStub;
+    let callback: sinon.SinonStub;
+    let callsBeforeInterval: number;
+    let callsAtInterval: number;
+
+    beforeEach(async () => {
+        originals = { queryDirectMode: Globals.queryDirectMode, queryTransportMethod: Globals.queryTransportMethod, queryPollingOptions: Globals.queryPollingOptions };
+        Globals.queryDirectMode = false;
+        Globals.queryTransportMethod = QueryTransportMethod.Polling;
+        Globals.queryPollingOptions = { ...Globals.queryPollingOptions, minIntervalMs: 100 };
+        // Keep Response body microtasks native; faking them stalls Node 23's body reader.
+        clock = sinon.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'performance'] });
+        fetchStub = fetchHelper.stubFetch();
+        fetchStub.callsFake(async () => new Response(JSON.stringify({
+            data: 'value', isSuccess: true, isAuthorized: true, isValid: true,
+            hasExceptions: false, validationResults: [], exceptionMessages: [], exceptionStackTrace: '',
+            paging: { page: 2, size: 10, totalItems: 35, totalPages: 4 }
+        })));
+        callback = sinon.stub();
+        const query = context.queryWithRouteAndQueryArgs;
+        query.setOrigin('https://example.com');
+        query.setMicroservice('svc');
+        query.setHttpHeadersCallback(() => ({ Authorization: 'Bearer test' }));
+        query.setPollingOptions({ intervalMs: 250 });
+        query.paging = new Paging(2, 10);
+        query.sorting = new Sorting('name', SortDirection.descending);
+        subscription = query.subscribe(callback, { id: 'item-42', filter: 'active', limit: 50 });
+        await clock.tickAsync(0);
+        await clock.tickAsync(249);
+        callsBeforeInterval = fetchStub.callCount;
+        await clock.tickAsync(1);
+        callsAtInterval = fetchStub.callCount;
+        subscription.unsubscribe();
+        await clock.tickAsync(2000);
+    });
+    afterEach(() => {
+        subscription?.unsubscribe();
+        clock.restore();
+        fetchHelper.restore();
+        Object.assign(Globals, originals);
+    });
+    it('should embed route arguments and append only HTTP query arguments', () => {
+        const url = new URL(fetchStub.firstCall.args[0]);
+        url.pathname.should.equal('/api/items/item-42');
+        Object.fromEntries(url.searchParams).should.deep.equal({ filter: 'active', limit: '50', page: '2', pageSize: '10', sortBy: 'name', sortDirection: 'desc', waitForFirstResult: 'true' });
+    });
+    it('should use per-query headers', () => fetchStub.firstCall.args[1].headers.get('Authorization').should.equal('Bearer test'));
+    it('should deliver a ready deserialized result with paging metadata', () => {
+        callback.firstCall.args[0].data.should.equal('value');
+        callback.firstCall.args[0].isReady.should.be.true;
+        callback.firstCall.args[0].paging.totalItems.should.equal(35);
+    });
+    it('should apply the per-query polling interval', () => {
+        callsBeforeInterval.should.equal(1);
+        callsAtInterval.should.equal(2);
+    });
+    it('should suppress unchanged snapshots after deserialization', () => callback.callCount.should.equal(1));
+    it('should stop after unsubscribe', () => fetchStub.callCount.should.equal(callsAtInterval));
+}));
+
+describe('when subscribing with polling transport and invalid arguments', given(an_observable_query_for, context => {
+    const fetchHelper = createFetchHelper();
+    let originalTransport: QueryTransportMethod;
+    let subscription: ObservableQuerySubscription<string>;
+    let clock: sinon.SinonFakeTimers;
+    let fetchStub: sinon.SinonStub;
+    let callback: sinon.SinonStub;
+    beforeEach(async () => {
+        originalTransport = Globals.queryTransportMethod;
+        Globals.queryTransportMethod = QueryTransportMethod.Polling;
+        clock = sinon.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'performance'] });
+        fetchStub = fetchHelper.stubFetch();
+        fetchStub.callsFake(async () => new Response(JSON.stringify({
+            data: '', isSuccess: false, isAuthorized: true, isValid: false,
+            hasExceptions: false, validationResults: [{ message: 'Invalid filter' }],
+            exceptionMessages: [], exceptionStackTrace: '',
+            paging: { page: 0, size: 0, totalItems: 0, totalPages: 0 }
+        }), { status: 400 }));
+        callback = sinon.stub();
+        context.queryWithRouteAndQueryArgs.setOrigin('https://example.com');
+        subscription = context.queryWithRouteAndQueryArgs.subscribe(callback, { id: 'item', filter: 'invalid', limit: 10 });
+        await clock.tickAsync(60000);
+    });
+    afterEach(() => {
+        subscription?.unsubscribe();
+        clock.restore();
+        fetchHelper.restore();
+        Globals.queryTransportMethod = originalTransport;
+    });
+    it('should deliver ready validation results', () => {
+        callback.firstCall.args[0].isReady.should.be.true;
+        callback.firstCall.args[0].isValid.should.be.false;
+        callback.firstCall.args[0].validationResults[0].message.should.equal('Invalid filter');
+    });
+    it('should stop polling', () => fetchStub.callCount.should.equal(1));
+}));

package/queries/for_ObservableQueryFor/when_subscribing/with_polling_transport_and_unauthorized_response.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 { given } from '../../../given.js';
+import { Globals } from '../../../Globals.js';
+import { createFetchHelper } from '../../../helpers/fetchHelper.js';
+import { an_observable_query_for } from '../given/an_observable_query_for.js';
+import { QueryTransportMethod } from '../../QueryTransportMethod.js';
+import { ObservableQuerySubscription } from '../../ObservableQuerySubscription.js';
+
+describe('when subscribing with polling transport and unauthorized response', given(an_observable_query_for, context => {
+    const fetchHelper = createFetchHelper();
+    let originalTransport: QueryTransportMethod;
+    let clock: sinon.SinonFakeTimers;
+    let fetchStub: sinon.SinonStub;
+    let callback: sinon.SinonStub;
+    let subscription: ObservableQuerySubscription<string>;
+    beforeEach(async () => {
+        originalTransport = Globals.queryTransportMethod;
+        Globals.queryTransportMethod = QueryTransportMethod.Polling;
+        // Keep Response body microtasks native; faking them stalls Node 23's body reader.
+        clock = sinon.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'performance'] });
+        sinon.stub(console, 'warn');
+        fetchStub = fetchHelper.stubFetch();
+        fetchStub.callsFake(async () => new Response('Unauthorized', { status: 401 }));
+        callback = sinon.stub();
+        context.queryWithRouteAndQueryArgs.setOrigin('https://example.com');
+        subscription = context.queryWithRouteAndQueryArgs.subscribe(callback, { id: 'item', filter: 'active', limit: 10 });
+        await clock.tickAsync(60000);
+    });
+    afterEach(() => {
+        subscription?.unsubscribe();
+        clock.restore();
+        fetchHelper.restore();
+        sinon.restore();
+        Globals.queryTransportMethod = originalTransport;
+    });
+    it('should deliver a ready unauthorized result', () => {
+        callback.firstCall.args[0].isAuthorized.should.be.false;
+        callback.firstCall.args[0].isReady.should.be.true;
+    });
+    it('should stop polling', () => fetchStub.callCount.should.equal(1));
+}));

package/queries/for_PollingQueryConnection/given/a_polling_query_connection.ts

@@ -0,0 +1,60 @@
+// 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 { Globals } from '../../../Globals.js';
+import { createFetchHelper } from '../../../helpers/fetchHelper.js';
+import { PollingQueryConnection } from '../../PollingQueryConnection.js';
+
+export class a_polling_query_connection {
+    connection!: PollingQueryConnection<unknown>;
+    dataReceived!: sinon.SinonStub;
+    fetchStub!: sinon.SinonStub;
+    clock!: sinon.SinonFakeTimers;
+    random!: sinon.SinonStub;
+    responses: Response[] = [];
+    private _correlationId = 0;
+
+    constructor() {
+        const fetchHelper = createFetchHelper();
+        const originalOptions = Globals.queryPollingOptions;
+        beforeEach(() => {
+            // Keep Response body microtasks native; faking them stalls Node 23's body reader.
+            this.clock = sinon.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'performance'] });
+            this.random = sinon.stub(Math, 'random').returns(0.5);
+            sinon.stub(console, 'warn');
+            this.responses = [
+                new Response(JSON.stringify(this.envelope('same'))),
+                new Response(JSON.stringify(this.envelope('same')))
+            ];
+            this.fetchStub = fetchHelper.stubFetch();
+            this.fetchStub.callsFake(async () => this.responses.shift() ?? new Response(JSON.stringify(this.envelope('same'))));
+            this.dataReceived = sinon.stub();
+            this.connection = new PollingQueryConnection(new URL('https://example.com/api/items/42'),
+                () => ({ Authorization: 'Bearer x' }), 'svc', {
+                    intervalMs: 1000, minIntervalMs: 500, maxIntervalMs: 8000,
+                    backoffMultiplier: 2, jitterRatio: 0.2
+                });
+        });
+        afterEach(() => {
+            this.connection.disconnect();
+            this.clock.restore();
+            fetchHelper.restore();
+            sinon.restore();
+            Globals.queryPollingOptions = originalOptions;
+        });
+    }
+
+    envelope(data: unknown, overrides: Record<string, unknown> = {}) {
+        return {
+            data, correlationId: String(++this._correlationId), isSuccess: true,
+            isAuthorized: true, isValid: true, hasExceptions: false,
+            validationResults: [], exceptionMessages: [], exceptionStackTrace: '',
+            paging: { page: 1, size: 10, totalItems: 25, totalPages: 3 }, ...overrides
+        };
+    }
+
+    respond(status: number, headers: Record<string, string> = {}, overrides: Record<string, unknown> = {}) {
+        this.fetchStub.onFirstCall().resolves(new Response(JSON.stringify(this.envelope('same', overrides)), { status, headers }));
+    }
+}

package/queries/for_PollingQueryConnection/when_backing_off/after_a_network_error.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 a network error', given(a_polling_query_connection, context => {
+    let beforeRetry: number;
+    beforeEach(async () => {
+        context.fetchStub.onFirstCall().rejects(new TypeError('offline'));
+        context.connection.connect(context.dataReceived);
+        await context.clock.tickAsync(1999);
+        beforeRetry = context.fetchStub.callCount;
+        await context.clock.tickAsync(1001);
+    });
+    it('should wait twice the interval before retrying', () => beforeRetry.should.equal(1));
+    it('should reset to the normal interval after recovery', () => context.fetchStub.callCount.should.equal(3));
+    it('should emit the recovered result', () => context.dataReceived.callCount.should.equal(1));
+}));