@cratis/chronicle 2.0.0 → 2.1.1

package/dist/connection/ChronicleSrvResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChronicleSrvResolver.js","sourceRoot":"","sources":["../../connection/ChronicleSrvResolver.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,qGAAqG;AAErG,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAExC,OAAO,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAE5E,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAE5B;;;;;GAKG;AACH,MAAM,OAAO,oBAAoB;IAMA;IAL7B;;;;OAIG;IACH,YAA6B,kBAAkC,GAAG,EAAE,CAAC,IAAI,QAAQ,EAAE;QAAtD,oBAAe,GAAf,eAAe,CAAuC;IAAG,CAAC;IAEvF;;;;;;;OAOG;IACH,KAAK,CAAC,OAAO,CAAC,IAAY,EAAE,UAAmB;QAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC;QAExC,IAAI,UAAU,EAAE,CAAC;YACb,QAAQ,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC5D,CAAC;QAED,MAAM,IAAI,GAAG,mBAAmB,IAAI,EAAE,CAAC;QACvC,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QAEhD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,2BAA2B,CAAC,IAAI,CAAC,CAAC;QAChD,CAAC;QAED,OAAO,OAAO;aACT,KAAK,EAAE;aACP,IAAI,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;YAC1F,yEAAyE;aACxE,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACtF,CAAC;IAEO,eAAe,CAAC,UAAkB;QACtC,MAAM,UAAU,GAAG,UAAU,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QAC/C,OAAO,UAAU,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,UAAU,IAAI,gBAAgB,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC;IAChF,CAAC;CACJ"}

package/dist/connection/ILoadBalancerStrategy.d.ts

@@ -0,0 +1,13 @@
+import type { ChronicleServerAddress } from './ChronicleConnectionString';
+/**
+ * Selects one server address from a list of candidates for a connect/reconnect attempt.
+ */
+export interface ILoadBalancerStrategy {
+    /**
+     * Selects one address from the given candidates.
+     * @param candidates - The addresses to select from. Never empty.
+     * @returns A promise resolving to the selected address.
+     */
+    select(candidates: ChronicleServerAddress[]): Promise<ChronicleServerAddress>;
+}
+//# sourceMappingURL=ILoadBalancerStrategy.d.ts.map

package/dist/connection/ILoadBalancerStrategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ILoadBalancerStrategy.d.ts","sourceRoot":"","sources":["../../connection/ILoadBalancerStrategy.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAE1E;;GAEG;AACH,MAAM,WAAW,qBAAqB;IAClC;;;;OAIG;IACH,MAAM,CAAC,UAAU,EAAE,sBAAsB,EAAE,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;CACjF"}

package/dist/connection/ILoadBalancerStrategy.js

@@ -0,0 +1,4 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+export {};
+//# sourceMappingURL=ILoadBalancerStrategy.js.map

package/dist/connection/ILoadBalancerStrategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ILoadBalancerStrategy.js","sourceRoot":"","sources":["../../connection/ILoadBalancerStrategy.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,qGAAqG"}

package/dist/connection/KernelKeepAlive.d.ts

@@ -0,0 +1,73 @@
+import type { ConnectRequest } from '@cratis/chronicle.contracts';
+/**
+ * Overrides for how long {@link KernelKeepAlive} waits before giving up on the kernel.
+ */
+export interface KeepAliveTimeouts {
+    /** How long to wait for a keep-alive before treating the connection as dead. */
+    idleTimeoutMs?: number;
+    /** How long a single answer may take before the connection is considered dead. */
+    answerTimeoutMs?: number;
+}
+/**
+ * The subset of the connection service {@link KernelKeepAlive} needs, so it can be
+ * exercised without a live kernel.
+ */
+export interface IKeepAliveConnections {
+    connect(request: ConnectRequest, options?: {
+        signal?: AbortSignal;
+    }): AsyncIterable<unknown>;
+    connectionKeepAlive(request: object, options?: {
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+}
+/**
+ * Drives the client half of Chronicle's keep-alive ping-pong.
+ *
+ * The kernel pushes a `ConnectionKeepAlive` down the `Connect` server stream once
+ * per second, and for each one the client must call the separate unary
+ * `ConnectionKeepAlive` RPC back — that is what bumps `LastSeen` on the kernel and
+ * keeps the client registered. A client that stops answering is evicted, its
+ * observers are unsubscribed, and reactors and reducers go silent while appends
+ * keep working.
+ *
+ * Eviction does not close the `Connect` stream, so a dead session usually presents
+ * as a stream that simply goes quiet rather than one that errors. Both a gap
+ * between keep-alives and an ended stream therefore mean the same thing: the
+ * connection is gone and the client must reconnect.
+ */
+export declare class KernelKeepAlive {
+    private readonly connections;
+    private readonly onConnectionLost;
+    /**
+     * How long to wait for a keep-alive before treating the connection as dead.
+     * The kernel emits one per second and evicts clients whose `LastSeen` falls
+     * more than five seconds behind, which is the threshold the C# client uses too.
+     */
+    static readonly defaultIdleTimeoutMs = 5000;
+    /** How long a single answer may take before the connection is considered dead. */
+    static readonly defaultAnswerTimeoutMs = 5000;
+    private readonly _logger;
+    private readonly _idleTimeoutMs;
+    private readonly _answerTimeoutMs;
+    /**
+     * Creates a new {@link KernelKeepAlive}.
+     * @param connections - The connection service to ping-pong with.
+     * @param onConnectionLost - Called once when the connection is found to be dead.
+     * @param timeouts - Overrides for the default timeouts.
+     */
+    constructor(connections: IKeepAliveConnections, onConnectionLost: (reason: string, error: unknown) => void, timeouts?: KeepAliveTimeouts);
+    /**
+     * Opens the `Connect` stream and answers the first keep-alive, establishing the
+     * client's registration with the kernel. Resolves once the kernel has been heard
+     * from; the ongoing ping-pong then continues in the background until the
+     * connection is lost or `signal` is aborted.
+     * @param request - The connect request identifying this client.
+     * @param signal - Aborted to stop the keep-alive entirely.
+     */
+    start(request: ConnectRequest, signal: AbortSignal): Promise<void>;
+    private run;
+    private answer;
+    private connectionLost;
+    private withTimeout;
+}
+//# sourceMappingURL=KernelKeepAlive.d.ts.map

package/dist/connection/KernelKeepAlive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"KernelKeepAlive.d.ts","sourceRoot":"","sources":["../../connection/KernelKeepAlive.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAElE;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAC9B,gFAAgF;IAChF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kFAAkF;IAClF,eAAe,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IAClC,OAAO,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IAC7F,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9F;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,eAAe;IAyBpB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IAzBrC;;;;OAIG;IACH,MAAM,CAAC,QAAQ,CAAC,oBAAoB,QAAQ;IAE5C,kFAAkF;IAClF,MAAM,CAAC,QAAQ,CAAC,sBAAsB,QAAQ;IAE9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAErB;IAEH,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAE1C;;;;;OAKG;gBAEkB,WAAW,EAAE,qBAAqB,EAClC,gBAAgB,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,EAC3E,QAAQ,GAAE,iBAAsB;IAMpC;;;;;;;OAOG;IACG,KAAK,CAAC,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;YAqB1D,GAAG;YAuBH,MAAM;IAUpB,OAAO,CAAC,cAAc;YAQR,WAAW;CAiB5B"}

package/dist/connection/KernelKeepAlive.js

@@ -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 { diag } from '@opentelemetry/api';
+/**
+ * Drives the client half of Chronicle's keep-alive ping-pong.
+ *
+ * The kernel pushes a `ConnectionKeepAlive` down the `Connect` server stream once
+ * per second, and for each one the client must call the separate unary
+ * `ConnectionKeepAlive` RPC back — that is what bumps `LastSeen` on the kernel and
+ * keeps the client registered. A client that stops answering is evicted, its
+ * observers are unsubscribed, and reactors and reducers go silent while appends
+ * keep working.
+ *
+ * Eviction does not close the `Connect` stream, so a dead session usually presents
+ * as a stream that simply goes quiet rather than one that errors. Both a gap
+ * between keep-alives and an ended stream therefore mean the same thing: the
+ * connection is gone and the client must reconnect.
+ */
+export class KernelKeepAlive {
+    connections;
+    onConnectionLost;
+    /**
+     * How long to wait for a keep-alive before treating the connection as dead.
+     * The kernel emits one per second and evicts clients whose `LastSeen` falls
+     * more than five seconds behind, which is the threshold the C# client uses too.
+     */
+    static defaultIdleTimeoutMs = 5000;
+    /** How long a single answer may take before the connection is considered dead. */
+    static defaultAnswerTimeoutMs = 5000;
+    _logger = diag.createComponentLogger({
+        namespace: '@cratis/chronicle/KernelKeepAlive'
+    });
+    _idleTimeoutMs;
+    _answerTimeoutMs;
+    /**
+     * Creates a new {@link KernelKeepAlive}.
+     * @param connections - The connection service to ping-pong with.
+     * @param onConnectionLost - Called once when the connection is found to be dead.
+     * @param timeouts - Overrides for the default timeouts.
+     */
+    constructor(connections, onConnectionLost, timeouts = {}) {
+        this.connections = connections;
+        this.onConnectionLost = onConnectionLost;
+        this._idleTimeoutMs = timeouts.idleTimeoutMs ?? KernelKeepAlive.defaultIdleTimeoutMs;
+        this._answerTimeoutMs = timeouts.answerTimeoutMs ?? KernelKeepAlive.defaultAnswerTimeoutMs;
+    }
+    /**
+     * Opens the `Connect` stream and answers the first keep-alive, establishing the
+     * client's registration with the kernel. Resolves once the kernel has been heard
+     * from; the ongoing ping-pong then continues in the background until the
+     * connection is lost or `signal` is aborted.
+     * @param request - The connect request identifying this client.
+     * @param signal - Aborted to stop the keep-alive entirely.
+     */
+    async start(request, signal) {
+        const stream = this.connections.connect(request, { signal });
+        const iterator = stream[Symbol.asyncIterator]();
+        // A kernel that accepts the stream but never sends anything must not hang
+        // the connect indefinitely — every caller awaiting the connection would
+        // block forever behind it.
+        const first = await this.withTimeout(iterator.next(), this._idleTimeoutMs, 'Timed out waiting for the first keep-alive from the kernel');
+        if (first.done) {
+            throw new Error('Connection service stream ended before sending first keep-alive');
+        }
+        await this.answer(first.value, signal);
+        void this.run(iterator, signal);
+    }
+    async run(iterator, signal) {
+        try {
+            while (!signal.aborted) {
+                const result = await this.withTimeout(iterator.next(), this._idleTimeoutMs, 'No keep-alive received from the kernel within the idle timeout');
+                if (result.done) {
+                    this.connectionLost('keep-alive-stream-ended', new Error('Keep-alive stream ended'));
+                    return;
+                }
+                await this.answer(result.value, signal);
+            }
+        }
+        catch (error) {
+            if (!signal.aborted) {
+                this.connectionLost('keep-alive-failed', error);
+            }
+        }
+    }
+    async answer(keepAlive, signal) {
+        // An answer that never returns would stop the loop draining the stream, which
+        // gets the client evicted just as surely as never answering at all.
+        await this.withTimeout(this.connections.connectionKeepAlive(keepAlive, { signal }), this._answerTimeoutMs, 'Timed out answering a kernel keep-alive');
+    }
+    connectionLost(reason, error) {
+        this._logger.warn('Kernel keep-alive lost the connection', {
+            reason,
+            error: error instanceof Error ? error.message : String(error)
+        });
+        this.onConnectionLost(reason, error);
+    }
+    async withTimeout(promise, timeoutMs, message) {
+        let handle;
+        try {
+            return await Promise.race([
+                promise,
+                new Promise((_, reject) => {
+                    handle = setTimeout(() => reject(new Error(message)), timeoutMs);
+                    handle.unref?.();
+                })
+            ]);
+        }
+        finally {
+            if (handle) {
+                clearTimeout(handle);
+            }
+        }
+    }
+}
+//# sourceMappingURL=KernelKeepAlive.js.map

package/dist/connection/KernelKeepAlive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"KernelKeepAlive.js","sourceRoot":"","sources":["../../connection/KernelKeepAlive.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,qGAAqG;AAErG,OAAO,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAsB1C;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,eAAe;IAyBH;IACA;IAzBrB;;;;OAIG;IACH,MAAM,CAAU,oBAAoB,GAAG,IAAI,CAAC;IAE5C,kFAAkF;IAClF,MAAM,CAAU,sBAAsB,GAAG,IAAI,CAAC;IAE7B,OAAO,GAAG,IAAI,CAAC,qBAAqB,CAAC;QAClD,SAAS,EAAE,mCAAmC;KACjD,CAAC,CAAC;IAEc,cAAc,CAAS;IACvB,gBAAgB,CAAS;IAE1C;;;;;OAKG;IACH,YACqB,WAAkC,EAClC,gBAA0D,EAC3E,WAA8B,EAAE;QAFf,gBAAW,GAAX,WAAW,CAAuB;QAClC,qBAAgB,GAAhB,gBAAgB,CAA0C;QAG3E,IAAI,CAAC,cAAc,GAAG,QAAQ,CAAC,aAAa,IAAI,eAAe,CAAC,oBAAoB,CAAC;QACrF,IAAI,CAAC,gBAAgB,GAAG,QAAQ,CAAC,eAAe,IAAI,eAAe,CAAC,sBAAsB,CAAC;IAC/F,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,KAAK,CAAC,OAAuB,EAAE,MAAmB;QACpD,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;QAC7D,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC;QAEhD,0EAA0E;QAC1E,wEAAwE;QACxE,2BAA2B;QAC3B,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,WAAW,CAChC,QAAQ,CAAC,IAAI,EAAE,EACf,IAAI,CAAC,cAAc,EACnB,4DAA4D,CAC/D,CAAC;QAEF,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,iEAAiE,CAAC,CAAC;QACvF,CAAC;QAED,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QACvC,KAAK,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACpC,CAAC;IAEO,KAAK,CAAC,GAAG,CAAC,QAAyC,EAAE,MAAmB;QAC5E,IAAI,CAAC;YACD,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBACrB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,WAAW,CACjC,QAAQ,CAAC,IAAI,EAAE,EACf,IAAI,CAAC,cAAc,EACnB,gEAAgE,CACnE,CAAC;gBAEF,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;oBACd,IAAI,CAAC,cAAc,CAAC,yBAAyB,EAAE,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC,CAAC;oBACrF,OAAO;gBACX,CAAC;gBAED,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YAC5C,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBAClB,IAAI,CAAC,cAAc,CAAC,mBAAmB,EAAE,KAAK,CAAC,CAAC;YACpD,CAAC;QACL,CAAC;IACL,CAAC;IAEO,KAAK,CAAC,MAAM,CAAC,SAAkB,EAAE,MAAmB;QACxD,8EAA8E;QAC9E,oEAAoE;QACpE,MAAM,IAAI,CAAC,WAAW,CAClB,IAAI,CAAC,WAAW,CAAC,mBAAmB,CAAC,SAAmB,EAAE,EAAE,MAAM,EAAE,CAAC,EACrE,IAAI,CAAC,gBAAgB,EACrB,yCAAyC,CAC5C,CAAC;IACN,CAAC;IAEO,cAAc,CAAC,MAAc,EAAE,KAAc;QACjD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,uCAAuC,EAAE;YACvD,MAAM;YACN,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SAChE,CAAC,CAAC;QACH,IAAI,CAAC,gBAAgB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACzC,CAAC;IAEO,KAAK,CAAC,WAAW,CAAI,OAAmB,EAAE,SAAiB,EAAE,OAAe;QAChF,IAAI,MAAiD,CAAC;QAEtD,IAAI,CAAC;YACD,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC;gBACtB,OAAO;gBACP,IAAI,OAAO,CAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE;oBAC7B,MAAM,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;oBACjE,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC;gBACrB,CAAC,CAAC;aACL,CAAC,CAAC;QACP,CAAC;gBAAS,CAAC;YACP,IAAI,MAAM,EAAE,CAAC;gBACT,YAAY,CAAC,MAAM,CAAC,CAAC;YACzB,CAAC;QACL,CAAC;IACL,CAAC"}

package/dist/connection/LeastConnectionsLoadBalancerStrategy.d.ts

@@ -0,0 +1,30 @@
+import type { ChronicleServerAddress } from './ChronicleConnectionString';
+import type { ILoadBalancerStrategy } from './ILoadBalancerStrategy';
+/**
+ * Selects the least-loaded candidate by probing each one's current connection count over
+ * HTTP and picking the minimum, breaking ties randomly. This is the default strategy.
+ *
+ * Before every probe attempt (not just the first), waits a random jitter to avoid a
+ * thundering herd of clients probing every candidate at the exact same instant. A single
+ * candidate is returned immediately without probing, since there is nothing to choose
+ * between.
+ */
+export declare class LeastConnectionsLoadBalancerStrategy implements ILoadBalancerStrategy {
+    private readonly _skipTlsValidation;
+    private readonly _maxJitterMs;
+    private readonly _dispatcher;
+    /**
+     * Initializes a new instance of {@link LeastConnectionsLoadBalancerStrategy}.
+     * @param skipTlsValidation - Whether to skip TLS certificate validation on the
+     * `/connections/count` and `/connections/reserve` probe requests, matching the toggle
+     * used for the gRPC channel itself.
+     * @param maxJitterMs - The maximum jitter, in milliseconds, to wait before every probe
+     * attempt. Defaults to 250ms. 0 disables jitter entirely.
+     */
+    constructor(_skipTlsValidation: boolean, _maxJitterMs?: number);
+    select(candidates: ChronicleServerAddress[]): Promise<ChronicleServerAddress>;
+    private jitter;
+    private probeConnectionCount;
+    private reserve;
+}
+//# sourceMappingURL=LeastConnectionsLoadBalancerStrategy.d.ts.map

package/dist/connection/LeastConnectionsLoadBalancerStrategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LeastConnectionsLoadBalancerStrategy.d.ts","sourceRoot":"","sources":["../../connection/LeastConnectionsLoadBalancerStrategy.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAE1E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAWrE;;;;;;;;GAQG;AACH,qBAAa,oCAAqC,YAAW,qBAAqB;IAY1E,OAAO,CAAC,QAAQ,CAAC,kBAAkB;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY;IAZjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAQ;IAEpC;;;;;;;OAOG;gBAEkB,kBAAkB,EAAE,OAAO,EAC3B,YAAY,GAAE,MAA8B;IAK3D,MAAM,CAAC,UAAU,EAAE,sBAAsB,EAAE,GAAG,OAAO,CAAC,sBAAsB,CAAC;YA2BrE,MAAM;YAaN,oBAAoB;YAqBpB,OAAO;CAWxB"}

package/dist/connection/LeastConnectionsLoadBalancerStrategy.js

@@ -0,0 +1,95 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+import { Agent } from 'undici';
+import { formatServerAddress } from './formatServerAddress';
+const DEFAULT_MAX_JITTER_MS = 250;
+const PROBE_TIMEOUT_MS = 2000;
+/**
+ * Selects the least-loaded candidate by probing each one's current connection count over
+ * HTTP and picking the minimum, breaking ties randomly. This is the default strategy.
+ *
+ * Before every probe attempt (not just the first), waits a random jitter to avoid a
+ * thundering herd of clients probing every candidate at the exact same instant. A single
+ * candidate is returned immediately without probing, since there is nothing to choose
+ * between.
+ */
+export class LeastConnectionsLoadBalancerStrategy {
+    _skipTlsValidation;
+    _maxJitterMs;
+    _dispatcher;
+    /**
+     * Initializes a new instance of {@link LeastConnectionsLoadBalancerStrategy}.
+     * @param skipTlsValidation - Whether to skip TLS certificate validation on the
+     * `/connections/count` and `/connections/reserve` probe requests, matching the toggle
+     * used for the gRPC channel itself.
+     * @param maxJitterMs - The maximum jitter, in milliseconds, to wait before every probe
+     * attempt. Defaults to 250ms. 0 disables jitter entirely.
+     */
+    constructor(_skipTlsValidation, _maxJitterMs = DEFAULT_MAX_JITTER_MS) {
+        this._skipTlsValidation = _skipTlsValidation;
+        this._maxJitterMs = _maxJitterMs;
+        this._dispatcher = new Agent({ connect: { rejectUnauthorized: !this._skipTlsValidation } });
+    }
+    async select(candidates) {
+        if (candidates.length === 0) {
+            throw new Error('Cannot select a server address from an empty candidate list');
+        }
+        if (candidates.length === 1) {
+            return candidates[0];
+        }
+        await this.jitter();
+        const connectionCounts = await Promise.all(candidates.map(candidate => this.probeConnectionCount(candidate)));
+        const minimumCount = Math.min(...connectionCounts);
+        const minimumIndices = connectionCounts.reduce((indices, count, index) => {
+            if (count === minimumCount) {
+                indices.push(index);
+            }
+            return indices;
+        }, []);
+        const selected = candidates[minimumIndices[Math.floor(Math.random() * minimumIndices.length)]];
+        await this.reserve(selected);
+        return selected;
+    }
+    async jitter() {
+        if (this._maxJitterMs <= 0) {
+            return;
+        }
+        const delayMs = Math.floor(Math.random() * this._maxJitterMs);
+        if (delayMs <= 0) {
+            return;
+        }
+        await new Promise(resolve => setTimeout(resolve, delayMs));
+    }
+    async probeConnectionCount(candidate) {
+        try {
+            const response = await fetch(`https://${formatServerAddress(candidate)}/connections/count`, {
+                signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+                dispatcher: this._dispatcher
+            });
+            if (!response.ok) {
+                return Number.MAX_SAFE_INTEGER;
+            }
+            const body = (await response.text()).trim();
+            const count = Number(body);
+            return body.length > 0 && Number.isFinite(count) ? count : Number.MAX_SAFE_INTEGER;
+        }
+        catch {
+            // A candidate that cannot be reached or answers with garbage is never preferred
+            // over one that responds normally, but must not fail the whole selection round.
+            return Number.MAX_SAFE_INTEGER;
+        }
+    }
+    async reserve(candidate) {
+        try {
+            await fetch(`https://${formatServerAddress(candidate)}/connections/reserve`, {
+                method: 'POST',
+                signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+                dispatcher: this._dispatcher
+            });
+        }
+        catch {
+            // Best-effort reservation; the selected server is still used even if this fails.
+        }
+    }
+}
+//# sourceMappingURL=LeastConnectionsLoadBalancerStrategy.js.map

package/dist/connection/LeastConnectionsLoadBalancerStrategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LeastConnectionsLoadBalancerStrategy.js","sourceRoot":"","sources":["../../connection/LeastConnectionsLoadBalancerStrategy.ts"],"names":[],"mappings":"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"}

package/dist/connection/LoadBalancerMode.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The strategy used to select one server address from a multi-host connection string
+ * (or a resolved set of `chronicle+srv://` addresses) for each connect/reconnect attempt.
+ */
+export declare enum LoadBalancerMode {
+    /**
+     * Probes every candidate's current connection count and picks the least-loaded one,
+     * breaking ties randomly. The default strategy.
+     */
+    LeastConnections = "least-connections",
+    /**
+     * Cycles through candidates in order, starting from a random offset chosen once per
+     * strategy instance.
+     */
+    RoundRobin = "round-robin",
+    /**
+     * Picks a uniformly random candidate on every call.
+     */
+    Random = "random"
+}
+//# sourceMappingURL=LoadBalancerMode.d.ts.map

package/dist/connection/LoadBalancerMode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LoadBalancerMode.d.ts","sourceRoot":"","sources":["../../connection/LoadBalancerMode.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,oBAAY,gBAAgB;IACxB;;;OAGG;IACH,gBAAgB,sBAAsB;IAEtC;;;OAGG;IACH,UAAU,gBAAgB;IAE1B;;OAEG;IACH,MAAM,WAAW;CACpB"}

package/dist/connection/LoadBalancerMode.js

@@ -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.
+/**
+ * The strategy used to select one server address from a multi-host connection string
+ * (or a resolved set of `chronicle+srv://` addresses) for each connect/reconnect attempt.
+ */
+export var LoadBalancerMode;
+(function (LoadBalancerMode) {
+    /**
+     * Probes every candidate's current connection count and picks the least-loaded one,
+     * breaking ties randomly. The default strategy.
+     */
+    LoadBalancerMode["LeastConnections"] = "least-connections";
+    /**
+     * Cycles through candidates in order, starting from a random offset chosen once per
+     * strategy instance.
+     */
+    LoadBalancerMode["RoundRobin"] = "round-robin";
+    /**
+     * Picks a uniformly random candidate on every call.
+     */
+    LoadBalancerMode["Random"] = "random";
+})(LoadBalancerMode || (LoadBalancerMode = {}));
+//# sourceMappingURL=LoadBalancerMode.js.map

package/dist/connection/LoadBalancerMode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LoadBalancerMode.js","sourceRoot":"","sources":["../../connection/LoadBalancerMode.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,qGAAqG;AAErG;;;GAGG;AACH,MAAM,CAAN,IAAY,gBAiBX;AAjBD,WAAY,gBAAgB;IACxB;;;OAGG;IACH,0DAAsC,CAAA;IAEtC;;;OAGG;IACH,8CAA0B,CAAA;IAE1B;;OAEG;IACH,qCAAiB,CAAA;AACrB,CAAC,EAjBW,gBAAgB,KAAhB,gBAAgB,QAiB3B"}

package/dist/connection/LoadBalancerStrategyFactory.d.ts

@@ -0,0 +1,11 @@
+import type { ILoadBalancerStrategy } from './ILoadBalancerStrategy';
+import { LoadBalancerMode } from './LoadBalancerMode';
+/**
+ * Creates the {@link ILoadBalancerStrategy} instance matching a {@link LoadBalancerMode}.
+ * @param mode - The load balancer mode to create a strategy for.
+ * @param skipTlsValidation - Whether to skip TLS certificate validation for strategies that
+ * probe candidates over HTTP (currently only {@link LoadBalancerMode.LeastConnections}).
+ * @returns The load balancer strategy instance.
+ */
+export declare function createLoadBalancerStrategy(mode: LoadBalancerMode, skipTlsValidation: boolean): ILoadBalancerStrategy;
+//# sourceMappingURL=LoadBalancerStrategyFactory.d.ts.map

package/dist/connection/LoadBalancerStrategyFactory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LoadBalancerStrategyFactory.d.ts","sourceRoot":"","sources":["../../connection/LoadBalancerStrategyFactory.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAErE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAItD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,OAAO,GAAG,qBAAqB,CAWpH"}

package/dist/connection/LoadBalancerStrategyFactory.js

@@ -0,0 +1,26 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+import { LeastConnectionsLoadBalancerStrategy } from './LeastConnectionsLoadBalancerStrategy';
+import { LoadBalancerMode } from './LoadBalancerMode';
+import { RandomLoadBalancerStrategy } from './RandomLoadBalancerStrategy';
+import { RoundRobinLoadBalancerStrategy } from './RoundRobinLoadBalancerStrategy';
+/**
+ * Creates the {@link ILoadBalancerStrategy} instance matching a {@link LoadBalancerMode}.
+ * @param mode - The load balancer mode to create a strategy for.
+ * @param skipTlsValidation - Whether to skip TLS certificate validation for strategies that
+ * probe candidates over HTTP (currently only {@link LoadBalancerMode.LeastConnections}).
+ * @returns The load balancer strategy instance.
+ */
+export function createLoadBalancerStrategy(mode, skipTlsValidation) {
+    switch (mode) {
+        case LoadBalancerMode.RoundRobin:
+            return new RoundRobinLoadBalancerStrategy();
+        case LoadBalancerMode.Random:
+            return new RandomLoadBalancerStrategy();
+        case LoadBalancerMode.LeastConnections:
+            return new LeastConnectionsLoadBalancerStrategy(skipTlsValidation);
+        default:
+            throw new Error(`Unknown load balancer mode: ${mode}`);
+    }
+}
+//# sourceMappingURL=LoadBalancerStrategyFactory.js.map

package/dist/connection/LoadBalancerStrategyFactory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LoadBalancerStrategyFactory.js","sourceRoot":"","sources":["../../connection/LoadBalancerStrategyFactory.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,qGAAqG;AAGrG,OAAO,EAAE,oCAAoC,EAAE,MAAM,wCAAwC,CAAC;AAC9F,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAC1E,OAAO,EAAE,8BAA8B,EAAE,MAAM,kCAAkC,CAAC;AAElF;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B,CAAC,IAAsB,EAAE,iBAA0B;IACzF,QAAQ,IAAI,EAAE,CAAC;QACX,KAAK,gBAAgB,CAAC,UAAU;YAC5B,OAAO,IAAI,8BAA8B,EAAE,CAAC;QAChD,KAAK,gBAAgB,CAAC,MAAM;YACxB,OAAO,IAAI,0BAA0B,EAAE,CAAC;QAC5C,KAAK,gBAAgB,CAAC,gBAAgB;YAClC,OAAO,IAAI,oCAAoC,CAAC,iBAAiB,CAAC,CAAC;QACvE;YACI,MAAM,IAAI,KAAK,CAAC,+BAA+B,IAAI,EAAE,CAAC,CAAC;IAC/D,CAAC;AACL,CAAC"}

package/dist/connection/RandomLoadBalancerStrategy.d.ts

@@ -0,0 +1,9 @@
+import type { ChronicleServerAddress } from './ChronicleConnectionString';
+import type { ILoadBalancerStrategy } from './ILoadBalancerStrategy';
+/**
+ * Selects a uniformly random candidate on every call.
+ */
+export declare class RandomLoadBalancerStrategy implements ILoadBalancerStrategy {
+    select(candidates: ChronicleServerAddress[]): Promise<ChronicleServerAddress>;
+}
+//# sourceMappingURL=RandomLoadBalancerStrategy.d.ts.map

package/dist/connection/RandomLoadBalancerStrategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RandomLoadBalancerStrategy.d.ts","sourceRoot":"","sources":["../../connection/RandomLoadBalancerStrategy.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAC1E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAErE;;GAEG;AACH,qBAAa,0BAA2B,YAAW,qBAAqB;IAC9D,MAAM,CAAC,UAAU,EAAE,sBAAsB,EAAE,GAAG,OAAO,CAAC,sBAAsB,CAAC;CAQtF"}

package/dist/connection/RandomLoadBalancerStrategy.js

@@ -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.
+/**
+ * Selects a uniformly random candidate on every call.
+ */
+export class RandomLoadBalancerStrategy {
+    async select(candidates) {
+        if (candidates.length === 0) {
+            throw new Error('Cannot select a server address from an empty candidate list');
+        }
+        const index = Math.floor(Math.random() * candidates.length);
+        return candidates[index];
+    }
+}
+//# sourceMappingURL=RandomLoadBalancerStrategy.js.map

package/dist/connection/RandomLoadBalancerStrategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RandomLoadBalancerStrategy.js","sourceRoot":"","sources":["../../connection/RandomLoadBalancerStrategy.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,qGAAqG;AAKrG;;GAEG;AACH,MAAM,OAAO,0BAA0B;IACnC,KAAK,CAAC,MAAM,CAAC,UAAoC;QAC7C,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;QACnF,CAAC;QAED,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;QAC5D,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC;CACJ"}

package/dist/connection/RoundRobinLoadBalancerStrategy.d.ts

@@ -0,0 +1,12 @@
+import type { ChronicleServerAddress } from './ChronicleConnectionString';
+import type { ILoadBalancerStrategy } from './ILoadBalancerStrategy';
+/**
+ * Cycles through candidates in order, starting from a random offset chosen once per
+ * strategy instance so that multiple clients don't all start at the same candidate.
+ */
+export declare class RoundRobinLoadBalancerStrategy implements ILoadBalancerStrategy {
+    private _startOffset?;
+    private _callCount;
+    select(candidates: ChronicleServerAddress[]): Promise<ChronicleServerAddress>;
+}
+//# sourceMappingURL=RoundRobinLoadBalancerStrategy.d.ts.map

package/dist/connection/RoundRobinLoadBalancerStrategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RoundRobinLoadBalancerStrategy.d.ts","sourceRoot":"","sources":["../../connection/RoundRobinLoadBalancerStrategy.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAC1E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAErE;;;GAGG;AACH,qBAAa,8BAA+B,YAAW,qBAAqB;IACxE,OAAO,CAAC,YAAY,CAAC,CAAS;IAC9B,OAAO,CAAC,UAAU,CAAK;IAEjB,MAAM,CAAC,UAAU,EAAE,sBAAsB,EAAE,GAAG,OAAO,CAAC,sBAAsB,CAAC;CActF"}

package/dist/connection/RoundRobinLoadBalancerStrategy.js

@@ -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.
+/**
+ * Cycles through candidates in order, starting from a random offset chosen once per
+ * strategy instance so that multiple clients don't all start at the same candidate.
+ */
+export class RoundRobinLoadBalancerStrategy {
+    _startOffset;
+    _callCount = 0;
+    async select(candidates) {
+        if (candidates.length === 0) {
+            throw new Error('Cannot select a server address from an empty candidate list');
+        }
+        if (this._startOffset === undefined) {
+            this._startOffset = Math.floor(Math.random() * candidates.length);
+        }
+        const index = (this._startOffset + this._callCount) % candidates.length;
+        this._callCount++;
+        return candidates[index];
+    }
+}
+//# sourceMappingURL=RoundRobinLoadBalancerStrategy.js.map

package/dist/connection/RoundRobinLoadBalancerStrategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RoundRobinLoadBalancerStrategy.js","sourceRoot":"","sources":["../../connection/RoundRobinLoadBalancerStrategy.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,qGAAqG;AAKrG;;;GAGG;AACH,MAAM,OAAO,8BAA8B;IAC/B,YAAY,CAAU;IACtB,UAAU,GAAG,CAAC,CAAC;IAEvB,KAAK,CAAC,MAAM,CAAC,UAAoC;QAC7C,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;QACnF,CAAC;QAED,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;YAClC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;QACtE,CAAC;QAED,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC;QACxE,IAAI,CAAC,UAAU,EAAE,CAAC;QAElB,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC;CACJ"}

package/dist/connection/TokenProvider.d.ts

@@ -1,9 +1,14 @@
+import { type OAuthTokenResponse } from './fetchOAuthAccessToken';
 /**
  * Interface for providing authentication tokens.
  */
 export interface ITokenProvider {
     /**
      * Gets the current access token.
+     *
+     * Never rejects — when no token can be obtained the result is undefined, the RPC
+     * proceeds without authorization and fails with the server's rejection, which the
+     * session machinery recovers from.
      * @returns Promise resolving to the access token or undefined if not available.
      */
     getAccessToken(): Promise<string | undefined>;
@@ -21,19 +26,39 @@ export declare class NoOpTokenProvider implements ITokenProvider {
     refresh(): Promise<string | undefined>;
 }
 /**
- * OAuth token provider using client credentials flow.
+ * OAuth token provider using the client credentials flow.
+ *
+ * Owns the access token so it can be attached to every RPC individually instead of
+ * being baked into the channel at connect time: the token is fetched lazily on first
+ * use, cached, and refreshed once it enters the refresh margin ahead of expiry, so
+ * token expiry never invalidates the channel. A failed refresh falls back to the
+ * cached token while it is still actually valid — only the refresh margin has been
+ * crossed, not the expiry — and further attempts are throttled so an unreachable
+ * auth endpoint does not turn every RPC into a fetch attempt.
  */
 export declare class OAuthTokenProvider implements ITokenProvider {
-    private readonly _tokenEndpoint;
-    private readonly _clientId;
-    private readonly _clientSecret;
+    private readonly _fetchToken;
+    private readonly _logger;
     private _accessToken?;
-    private _tokenExpiry;
+    private _expiresAt;
+    private _lastFailedFetch?;
     private _refreshPromise?;
-    constructor(_tokenEndpoint: string, _clientId: string, _clientSecret: string);
+    /**
+     * Creates a new {@link OAuthTokenProvider}.
+     * @param tokenEndpoint - The OAuth2 token endpoint to request tokens from.
+     * @param clientId - The client identifier.
+     * @param clientSecret - The client secret.
+     * @param skipTlsValidation - Whether to skip TLS certificate chain validation.
+     * @param _fetchToken - Test-only seam replacing the OAuth2 token request.
+     */
+    constructor(tokenEndpoint: string, clientId: string, clientSecret: string, skipTlsValidation?: boolean, _fetchToken?: () => Promise<OAuthTokenResponse>);
     getAccessToken(): Promise<string | undefined>;
     refresh(): Promise<string | undefined>;
-    private fetchAccessToken;
+    private hasFreshToken;
+    private isThrottled;
+    private cachedTokenWhileValid;
+    private fetchAndCacheAccessToken;
+    private lifetimeSecondsFrom;
 }
 export type TokenProvider = ITokenProvider;
 //# sourceMappingURL=TokenProvider.d.ts.map

package/dist/connection/TokenProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TokenProvider.d.ts","sourceRoot":"","sources":["../../connection/TokenProvider.ts"],"names":[],"mappings":"AASA;;GAEG;AACH,MAAM,WAAW,cAAc;IAC3B;;;OAGG;IACH,cAAc,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAE9C;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CAC1C;AAED;;GAEG;AACH,qBAAa,iBAAkB,YAAW,cAAc;IAC9C,cAAc,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAI7C,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;CAG/C;AAOD;;GAEG;AACH,qBAAa,kBAAmB,YAAW,cAAc;IAMjD,OAAO,CAAC,QAAQ,CAAC,cAAc;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAPlC,OAAO,CAAC,YAAY,CAAC,CAAS;IAC9B,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,eAAe,CAAC,CAA8B;gBAGjC,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM;IAGpC,cAAc,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAiB7C,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;YAM9B,gBAAgB;CAuDjC;AAED,MAAM,MAAM,aAAa,GAAG,cAAc,CAAC"}
+{"version":3,"file":"TokenProvider.d.ts","sourceRoot":"","sources":["../../connection/TokenProvider.ts"],"names":[],"mappings":"AAIA,OAAO,EAAyB,KAAK,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAUzF;;GAEG;AACH,MAAM,WAAW,cAAc;IAC3B;;;;;;;OAOG;IACH,cAAc,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAE9C;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CAC1C;AAED;;GAEG;AACH,qBAAa,iBAAkB,YAAW,cAAc;IAC9C,cAAc,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAI7C,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;CAG/C;AAED;;;;;;;;;;GAUG;AACH,qBAAa,kBAAmB,YAAW,cAAc;IAuBjD,OAAO,CAAC,QAAQ,CAAC,WAAW;IAtBhC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAErB;IAEH,OAAO,CAAC,YAAY,CAAC,CAAS;IAC9B,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,gBAAgB,CAAC,CAAS;IAClC,OAAO,CAAC,eAAe,CAAC,CAA8B;IAEtD;;;;;;;OAOG;gBAEC,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,iBAAiB,GAAE,OAAc,EAChB,WAAW,GAAE,MAAM,OAAO,CAAC,kBAAkB,CACqB;IAGjF,cAAc,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAqB7C,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAO5C,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,qBAAqB;YAIf,wBAAwB;IAkBtC,OAAO,CAAC,mBAAmB;CAI9B;AAED,MAAM,MAAM,aAAa,GAAG,cAAc,CAAC"}