camusdb 0.1.0

package/dist/result-set.js.map

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

package/dist/retry.d.ts

@@ -0,0 +1,38 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+/**
+ * True when running the same work again may succeed.
+ *
+ * `CADB0509` is deliberately **not** retryable here. It says a commit or rollback outcome is not
+ * resolved yet, which means the transaction may already be durable — replaying the work from
+ * `BEGIN` could apply it twice. The driver resolves that code by re-issuing the same finalize on
+ * the same handle, which `CamusTransaction` does on its own.
+ */
+export declare function isRetryable(error: unknown): boolean;
+/** How a retry loop behaves. */
+export interface RetryOptions {
+    /** How many times the work runs in total, the first attempt included. Default 5. */
+    readonly maxAttempts?: number;
+    /** Ends the loop between attempts. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Runs `operation` and retries it while it fails with a retryable error.
+ *
+ * Use it around a unit of work that is safe to run twice — a single autocommit statement, or a
+ * whole transaction from `BEGIN` to `COMMIT`. Do not use it around a commit alone: a commit whose
+ * outcome is unknown must not be replayed from the start.
+ *
+ * The delay grows exponentially from 20 ms, caps at 400 ms, and carries 25% jitter, so a set of
+ * clients that conflicted do not retry in step.
+ */
+export declare function withRetry<T>(operation: (attempt: number) => Promise<T>, options?: RetryOptions): Promise<T>;
+/** The back-off for one attempt, in milliseconds. Exported so a caller can mirror the schedule. */
+export declare function computeDelayMs(attempt: number): number;
+/** A cancellable sleep. Rejects with the signal's reason when the signal ends the wait. */
+export declare function delay(milliseconds: number, signal?: AbortSignal): Promise<void>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAwBH;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAanD;AAED,gCAAgC;AAChC,MAAM,WAAW,YAAY;IAC3B,oFAAoF;IACpF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B,sCAAsC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED;;;;;;;;;GASG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAC1C,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,CAAC,CAAC,CAYZ;AAED,mGAAmG;AACnG,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKtD;AAED,2FAA2F;AAC3F,wBAAgB,KAAK,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB/E"}

package/dist/retry.js

@@ -0,0 +1,93 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+import { CamusError } from './errors.js';
+import { CamusErrorCode } from './error-codes.js';
+/**
+ * Which failures a caller may retry, and a loop that does it.
+ *
+ * A serializable transaction can lose a conflict and be aborted. The abort is not a bug and it is
+ * not a lasting condition: the same work, run again, usually commits. This module holds the one
+ * classification of "run it again" the whole driver uses, so a retry loop a caller writes and the
+ * loops inside the driver agree on what is retryable.
+ */
+/** The server codes that name a lost conflict or a transient internal condition. */
+const RETRYABLE_CODES = new Set(['CADB0502', 'CADB0504', 'CADB0505']);
+/**
+ * Message fragments that name the same conditions on a server that reported them without a
+ * dedicated code. A message test is coarse, but the alternative is failing a transaction that
+ * would have committed on its second attempt.
+ */
+const RETRYABLE_MESSAGE_MARKERS = ['MustRetry', 'AlreadyLocked', 'commit returned Aborted'];
+/**
+ * True when running the same work again may succeed.
+ *
+ * `CADB0509` is deliberately **not** retryable here. It says a commit or rollback outcome is not
+ * resolved yet, which means the transaction may already be durable — replaying the work from
+ * `BEGIN` could apply it twice. The driver resolves that code by re-issuing the same finalize on
+ * the same handle, which `CamusTransaction` does on its own.
+ */
+export function isRetryable(error) {
+    for (let current = error; current != null; current = current.cause) {
+        if (!CamusError.is(current))
+            continue;
+        if (current.code === CamusErrorCode.FinalizeUnresolved)
+            return false;
+        if (RETRYABLE_CODES.has(current.code))
+            return true;
+        for (const marker of RETRYABLE_MESSAGE_MARKERS) {
+            if (current.message.includes(marker))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Runs `operation` and retries it while it fails with a retryable error.
+ *
+ * Use it around a unit of work that is safe to run twice — a single autocommit statement, or a
+ * whole transaction from `BEGIN` to `COMMIT`. Do not use it around a commit alone: a commit whose
+ * outcome is unknown must not be replayed from the start.
+ *
+ * The delay grows exponentially from 20 ms, caps at 400 ms, and carries 25% jitter, so a set of
+ * clients that conflicted do not retry in step.
+ */
+export async function withRetry(operation, options = {}) {
+    const maxAttempts = Math.max(1, options.maxAttempts ?? 5);
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await operation(attempt);
+        }
+        catch (error) {
+            if (attempt >= maxAttempts || !isRetryable(error))
+                throw error;
+            await delay(computeDelayMs(attempt), options.signal);
+        }
+    }
+}
+/** The back-off for one attempt, in milliseconds. Exported so a caller can mirror the schedule. */
+export function computeDelayMs(attempt) {
+    const base = Math.min(20 * 2 ** attempt, 400);
+    const jitter = base * 0.25 * (2 * Math.random() - 1);
+    return Math.max(1, base + jitter);
+}
+/** A cancellable sleep. Rejects with the signal's reason when the signal ends the wait. */
+export function delay(milliseconds, signal) {
+    if (signal?.aborted === true)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, milliseconds);
+        function onAbort() {
+            clearTimeout(timer);
+            reject(signal.reason);
+        }
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+//# sourceMappingURL=retry.js.map

package/dist/retry.js.map

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

package/dist/routing/advice.d.ts

@@ -0,0 +1,63 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+/** Whether routing advice asks the client to remember a destination or to forget one. */
+export declare const CamusRoutingDisposition: {
+    /** A disposition this driver does not know. The advice is ignored. */
+    readonly Unknown: "unknown";
+    /** Remember the advertised node for future executions of this statement. */
+    readonly Prefer: "prefer";
+    /** Forget any destination learned for this statement. */
+    readonly Clear: "clear";
+};
+export type CamusRoutingDisposition = (typeof CamusRoutingDisposition)[keyof typeof CamusRoutingDisposition];
+/** The only routing metadata version this driver accepts. */
+export declare const ROUTING_ACCEPT_VERSION = 1;
+/**
+ * Advisory routing metadata attached to a successful statement response.
+ *
+ * It is a performance hint, never an instruction: the statement that carried it already ran
+ * normally, and a client that ignores it loses nothing but a network hop. It never carries SQL
+ * literals, row values, encoded keys, credentials, or a cluster map.
+ *
+ * `preferredNodeId` is an opaque node identity, not an address to dial. It becomes a destination
+ * only through the client's configured `routingNodes` trust map.
+ */
+export interface CamusRoutingAdvice {
+    /** The metadata contract version. Advice of any other version is ignored. */
+    readonly version: number;
+    readonly disposition: CamusRoutingDisposition;
+    /** The opaque node identity to prefer. */
+    readonly preferredNodeId?: string | undefined;
+    /**
+     * True when the destination holds across different parameter values for this statement. A
+     * narrower scope is not reusable, so the advice is ignored.
+     */
+    readonly parametersIndependentScope: boolean;
+    /**
+     * An opaque change detector over the statement's resolved physical dependencies. It changes when
+     * the dependency set changes: a schema change, a TRUNCATE, a view refresh, a recreated database.
+     * It is not sortable and it is not authentication.
+     */
+    readonly dependencyToken?: string | undefined;
+    /** The longest period the route may be reused, in milliseconds, measured from receipt. */
+    readonly maxAgeMs: number;
+    /** Why the server chose this disposition. Diagnostic only. */
+    readonly reason?: string | undefined;
+}
+/** Builds the public object from decoded parts, whichever transport decoded them. */
+export declare function makeRoutingAdvice(parts: {
+    version: number;
+    disposition: string | undefined;
+    preferredNodeId: string | undefined;
+    reuseScope: string | undefined;
+    dependencyToken: string | undefined;
+    maxAgeMs: number;
+    reason: string | undefined;
+}): CamusRoutingAdvice;
+/** Reads advice out of a REST response body, or reports `undefined` when the body carried none. */
+export declare function routingAdviceFromJson(body: unknown): CamusRoutingAdvice | undefined;
+//# sourceMappingURL=advice.d.ts.map

package/dist/routing/advice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"advice.d.ts","sourceRoot":"","sources":["../../src/routing/advice.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,yFAAyF;AACzF,eAAO,MAAM,uBAAuB;IAClC,sEAAsE;;IAEtE,4EAA4E;;IAE5E,yDAAyD;;CAEjD,CAAC;AAEX,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,OAAO,uBAAuB,CAAC,CAAC;AAE7G,6DAA6D;AAC7D,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,QAAQ,CAAC,WAAW,EAAE,uBAAuB,CAAC;IAE9C,0CAA0C;IAC1C,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAE9C;;;OAGG;IACH,QAAQ,CAAC,0BAA0B,EAAE,OAAO,CAAC;IAE7C;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAE9C,0FAA0F;IAC1F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAED,qFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,eAAe,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,eAAe,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B,GAAG,kBAAkB,CAUrB;AAaD,mGAAmG;AACnG,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,kBAAkB,GAAG,SAAS,CAiBnF"}

package/dist/routing/advice.js

@@ -0,0 +1,61 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+/** Whether routing advice asks the client to remember a destination or to forget one. */
+export const CamusRoutingDisposition = {
+    /** A disposition this driver does not know. The advice is ignored. */
+    Unknown: 'unknown',
+    /** Remember the advertised node for future executions of this statement. */
+    Prefer: 'prefer',
+    /** Forget any destination learned for this statement. */
+    Clear: 'clear',
+};
+/** The only routing metadata version this driver accepts. */
+export const ROUTING_ACCEPT_VERSION = 1;
+/** Builds the public object from decoded parts, whichever transport decoded them. */
+export function makeRoutingAdvice(parts) {
+    return {
+        version: parts.version,
+        disposition: parseDisposition(parts.disposition),
+        preferredNodeId: parts.preferredNodeId,
+        parametersIndependentScope: parts.reuseScope === 'statementParametersIndependent',
+        dependencyToken: parts.dependencyToken,
+        maxAgeMs: parts.maxAgeMs,
+        reason: parts.reason,
+    };
+}
+function parseDisposition(disposition) {
+    switch (disposition) {
+        case 'prefer':
+            return CamusRoutingDisposition.Prefer;
+        case 'clear':
+            return CamusRoutingDisposition.Clear;
+        default:
+            return CamusRoutingDisposition.Unknown;
+    }
+}
+/** Reads advice out of a REST response body, or reports `undefined` when the body carried none. */
+export function routingAdviceFromJson(body) {
+    if (typeof body !== 'object' || body === null)
+        return undefined;
+    const routing = body.routing;
+    if (typeof routing !== 'object' || routing === null)
+        return undefined;
+    const record = routing;
+    return makeRoutingAdvice({
+        version: typeof record.version === 'number' ? record.version : 0,
+        disposition: readString(record.disposition),
+        preferredNodeId: readString(record.preferredNodeId),
+        reuseScope: readString(record.reuseScope),
+        dependencyToken: readString(record.dependencyToken),
+        maxAgeMs: typeof record.maxAgeMs === 'number' ? record.maxAgeMs : 0,
+        reason: readString(record.reason),
+    });
+}
+function readString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+//# sourceMappingURL=advice.js.map

package/dist/routing/advice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"advice.js","sourceRoot":"","sources":["../../src/routing/advice.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,yFAAyF;AACzF,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,sEAAsE;IACtE,OAAO,EAAE,SAAS;IAClB,4EAA4E;IAC5E,MAAM,EAAE,QAAQ;IAChB,yDAAyD;IACzD,KAAK,EAAE,OAAO;CACN,CAAC;AAIX,6DAA6D;AAC7D,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC;AAyCxC,qFAAqF;AACrF,MAAM,UAAU,iBAAiB,CAAC,KAQjC;IACC,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,WAAW,EAAE,gBAAgB,CAAC,KAAK,CAAC,WAAW,CAAC;QAChD,eAAe,EAAE,KAAK,CAAC,eAAe;QACtC,0BAA0B,EAAE,KAAK,CAAC,UAAU,KAAK,gCAAgC;QACjF,eAAe,EAAE,KAAK,CAAC,eAAe;QACtC,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,MAAM,EAAE,KAAK,CAAC,MAAM;KACrB,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB,CAAC,WAA+B;IACvD,QAAQ,WAAW,EAAE,CAAC;QACpB,KAAK,QAAQ;YACX,OAAO,uBAAuB,CAAC,MAAM,CAAC;QACxC,KAAK,OAAO;YACV,OAAO,uBAAuB,CAAC,KAAK,CAAC;QACvC;YACE,OAAO,uBAAuB,CAAC,OAAO,CAAC;IAC3C,CAAC;AACH,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,qBAAqB,CAAC,IAAa;IACjD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAEhE,MAAM,OAAO,GAAI,IAA8B,CAAC,OAAO,CAAC;IACxD,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAEtE,MAAM,MAAM,GAAG,OAAkC,CAAC;IAElD,OAAO,iBAAiB,CAAC;QACvB,OAAO,EAAE,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QAChE,WAAW,EAAE,UAAU,CAAC,MAAM,CAAC,WAAW,CAAC;QAC3C,eAAe,EAAE,UAAU,CAAC,MAAM,CAAC,eAAe,CAAC;QACnD,UAAU,EAAE,UAAU,CAAC,MAAM,CAAC,UAAU,CAAC;QACzC,eAAe,EAAE,UAAU,CAAC,MAAM,CAAC,eAAe,CAAC;QACnD,QAAQ,EAAE,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;QACnE,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC;KAClC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,UAAU,CAAC,KAAc;IAChC,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACvD,CAAC"}

package/dist/routing/route-cache.d.ts

@@ -0,0 +1,53 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+/** Whether a statement was a query or a write. A route is learned per kind. */
+export declare const CamusRouteOpKind: {
+    readonly Query: 0;
+    readonly NonQuery: 1;
+};
+export type CamusRouteOpKind = (typeof CamusRouteOpKind)[keyof typeof CamusRouteOpKind];
+/**
+ * The bounded cache of destinations learned for statements.
+ *
+ * Each entry is keyed by database, exact SQL text, and statement kind, and holds a node identity
+ * with an expiry measured on a monotonic clock. Two properties matter beyond ordinary caching:
+ *
+ * - A late reply cannot overwrite a newer route. Every read reports the entry's revision, and a
+ *   write applies only when the revision it observed is still the current one. Two replies for the
+ *   same statement can arrive out of order, and the older one must not win.
+ * - The cache is bounded twice, by entry count and by retained bytes. SQL text is unbounded in
+ *   length, so a count alone does not bound memory.
+ */
+export declare class CamusStatementRouteCache {
+    private readonly entries;
+    private readonly maxEntries;
+    private readonly maxBytes;
+    private retainedBytes;
+    private revisionSeq;
+    constructor(maxEntries: number, maxBytes: number);
+    get size(): number;
+    /**
+     * The node identity learned for a statement, and the revision that read observed. A miss, an
+     * expired entry, and an entry that was never written all report `undefined` with revision 0.
+     */
+    tryGet(key: string, now: number): {
+        nodeId: string | undefined;
+        revision: number;
+    };
+    /**
+     * Records a destination, but only when the caller's observed revision still matches. A first
+     * write must observe revision 0, which is what a read of an absent entry reports.
+     */
+    learn(key: string, keyBytes: number, nodeId: string, dependencyToken: string | undefined, expiresAt: number, observedRevision: number, now: number): void;
+    /** Forgets a destination, but only when the caller's observed revision still matches. */
+    clear(key: string, observedRevision: number): void;
+    private remove;
+    private evict;
+}
+/** The cache key for one statement. The separator cannot appear in a kind or a database name. */
+export declare function routeKey(database: string, sql: string, kind: CamusRouteOpKind): string;
+//# sourceMappingURL=route-cache.d.ts.map

package/dist/routing/route-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-cache.d.ts","sourceRoot":"","sources":["../../src/routing/route-cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,+EAA+E;AAC/E,eAAO,MAAM,gBAAgB;;;CAGnB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC;AAWxF;;;;;;;;;;;GAWG;AACH,qBAAa,wBAAwB;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IAEpD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC,OAAO,CAAC,aAAa,CAAK;IAE1B,OAAO,CAAC,WAAW,CAAK;gBAEZ,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;IAKhD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG;QAAE,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE;IAclF;;;OAGG;IACH,KAAK,CACH,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,eAAe,EAAE,MAAM,GAAG,SAAS,EACnC,SAAS,EAAE,MAAM,EACjB,gBAAgB,EAAE,MAAM,EACxB,GAAG,EAAE,MAAM,GACV,IAAI;IA6BP,yFAAyF;IACzF,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,IAAI;IAMlD,OAAO,CAAC,MAAM;IAKd,OAAO,CAAC,KAAK;CA2Bd;AAED,iGAAiG;AACjG,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAEtF"}

package/dist/routing/route-cache.js

@@ -0,0 +1,123 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+/** Whether a statement was a query or a write. A route is learned per kind. */
+export const CamusRouteOpKind = {
+    Query: 0,
+    NonQuery: 1,
+};
+/**
+ * The bounded cache of destinations learned for statements.
+ *
+ * Each entry is keyed by database, exact SQL text, and statement kind, and holds a node identity
+ * with an expiry measured on a monotonic clock. Two properties matter beyond ordinary caching:
+ *
+ * - A late reply cannot overwrite a newer route. Every read reports the entry's revision, and a
+ *   write applies only when the revision it observed is still the current one. Two replies for the
+ *   same statement can arrive out of order, and the older one must not win.
+ * - The cache is bounded twice, by entry count and by retained bytes. SQL text is unbounded in
+ *   length, so a count alone does not bound memory.
+ */
+export class CamusStatementRouteCache {
+    entries = new Map();
+    maxEntries;
+    maxBytes;
+    retainedBytes = 0;
+    revisionSeq = 0;
+    constructor(maxEntries, maxBytes) {
+        this.maxEntries = Math.max(1, maxEntries);
+        this.maxBytes = Math.max(1, maxBytes);
+    }
+    get size() {
+        return this.entries.size;
+    }
+    /**
+     * The node identity learned for a statement, and the revision that read observed. A miss, an
+     * expired entry, and an entry that was never written all report `undefined` with revision 0.
+     */
+    tryGet(key, now) {
+        const entry = this.entries.get(key);
+        if (entry === undefined)
+            return { nodeId: undefined, revision: 0 };
+        if (now >= entry.expiresAt) {
+            this.remove(key, entry);
+            return { nodeId: undefined, revision: 0 };
+        }
+        entry.lastTouched = now;
+        return { nodeId: entry.nodeId, revision: entry.revision };
+    }
+    /**
+     * Records a destination, but only when the caller's observed revision still matches. A first
+     * write must observe revision 0, which is what a read of an absent entry reports.
+     */
+    learn(key, keyBytes, nodeId, dependencyToken, expiresAt, observedRevision, now) {
+        const existing = this.entries.get(key);
+        if (existing !== undefined && existing.revision !== observedRevision)
+            return;
+        if (existing === undefined && observedRevision !== 0)
+            return;
+        const entry = existing ?? {
+            nodeId,
+            dependencyToken,
+            expiresAt,
+            revision: 0,
+            lastTouched: now,
+            bytes: 0,
+        };
+        if (existing !== undefined)
+            this.retainedBytes -= existing.bytes;
+        else
+            this.entries.set(key, entry);
+        entry.nodeId = nodeId;
+        entry.dependencyToken = dependencyToken;
+        entry.expiresAt = expiresAt;
+        entry.revision = ++this.revisionSeq;
+        entry.lastTouched = now;
+        entry.bytes = keyBytes + (nodeId.length + (dependencyToken?.length ?? 0)) * 2 + 64;
+        this.retainedBytes += entry.bytes;
+        this.evict(now);
+    }
+    /** Forgets a destination, but only when the caller's observed revision still matches. */
+    clear(key, observedRevision) {
+        const entry = this.entries.get(key);
+        if (entry !== undefined && entry.revision === observedRevision)
+            this.remove(key, entry);
+    }
+    remove(key, entry) {
+        this.entries.delete(key);
+        this.retainedBytes -= entry.bytes;
+    }
+    evict(now) {
+        if (this.entries.size <= this.maxEntries && this.retainedBytes <= this.maxBytes)
+            return;
+        // Expired entries first: they are free to drop and cost a live route nothing.
+        for (const [key, entry] of this.entries) {
+            if (now >= entry.expiresAt)
+                this.remove(key, entry);
+        }
+        while (this.entries.size > this.maxEntries || this.retainedBytes > this.maxBytes) {
+            let victimKey;
+            let oldest = Number.POSITIVE_INFINITY;
+            for (const [key, entry] of this.entries) {
+                if (entry.lastTouched < oldest) {
+                    oldest = entry.lastTouched;
+                    victimKey = key;
+                }
+            }
+            if (victimKey === undefined)
+                return;
+            const victim = this.entries.get(victimKey);
+            if (victim === undefined)
+                return;
+            this.remove(victimKey, victim);
+        }
+    }
+}
+/** The cache key for one statement. The separator cannot appear in a kind or a database name. */
+export function routeKey(database, sql, kind) {
+    return `${String(kind)} ${database} ${sql}`;
+}
+//# sourceMappingURL=route-cache.js.map

package/dist/routing/route-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-cache.js","sourceRoot":"","sources":["../../src/routing/route-cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,+EAA+E;AAC/E,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,KAAK,EAAE,CAAC;IACR,QAAQ,EAAE,CAAC;CACH,CAAC;AAaX;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,wBAAwB;IAClB,OAAO,GAAG,IAAI,GAAG,EAAiB,CAAC;IAEnC,UAAU,CAAS;IAEnB,QAAQ,CAAS;IAE1B,aAAa,GAAG,CAAC,CAAC;IAElB,WAAW,GAAG,CAAC,CAAC;IAExB,YAAY,UAAkB,EAAE,QAAgB;QAC9C,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;QAC1C,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IACxC,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,GAAW,EAAE,GAAW;QAC7B,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAEpC,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;QAEnE,IAAI,GAAG,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;YAC3B,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YACxB,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;QAC5C,CAAC;QAED,KAAK,CAAC,WAAW,GAAG,GAAG,CAAC;QACxB,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC;IAC5D,CAAC;IAED;;;OAGG;IACH,KAAK,CACH,GAAW,EACX,QAAgB,EAChB,MAAc,EACd,eAAmC,EACnC,SAAiB,EACjB,gBAAwB,EACxB,GAAW;QAEX,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAEvC,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,QAAQ,KAAK,gBAAgB;YAAE,OAAO;QAC7E,IAAI,QAAQ,KAAK,SAAS,IAAI,gBAAgB,KAAK,CAAC;YAAE,OAAO;QAE7D,MAAM,KAAK,GAAU,QAAQ,IAAI;YAC/B,MAAM;YACN,eAAe;YACf,SAAS;YACT,QAAQ,EAAE,CAAC;YACX,WAAW,EAAE,GAAG;YAChB,KAAK,EAAE,CAAC;SACT,CAAC;QAEF,IAAI,QAAQ,KAAK,SAAS;YAAE,IAAI,CAAC,aAAa,IAAI,QAAQ,CAAC,KAAK,CAAC;;YAC5D,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAElC,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC;QACtB,KAAK,CAAC,eAAe,GAAG,eAAe,CAAC;QACxC,KAAK,CAAC,SAAS,GAAG,SAAS,CAAC;QAC5B,KAAK,CAAC,QAAQ,GAAG,EAAE,IAAI,CAAC,WAAW,CAAC;QACpC,KAAK,CAAC,WAAW,GAAG,GAAG,CAAC;QACxB,KAAK,CAAC,KAAK,GAAG,QAAQ,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,eAAe,EAAE,MAAM,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC;QAEnF,IAAI,CAAC,aAAa,IAAI,KAAK,CAAC,KAAK,CAAC;QAClC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClB,CAAC;IAED,yFAAyF;IACzF,KAAK,CAAC,GAAW,EAAE,gBAAwB;QACzC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAEpC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ,KAAK,gBAAgB;YAAE,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC1F,CAAC;IAEO,MAAM,CAAC,GAAW,EAAE,KAAY;QACtC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACzB,IAAI,CAAC,aAAa,IAAI,KAAK,CAAC,KAAK,CAAC;IACpC,CAAC;IAEO,KAAK,CAAC,GAAW;QACvB,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO;QAExF,8EAA8E;QAC9E,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACxC,IAAI,GAAG,IAAI,KAAK,CAAC,SAAS;gBAAE,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACtD,CAAC;QAED,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;YACjF,IAAI,SAA6B,CAAC;YAClC,IAAI,MAAM,GAAG,MAAM,CAAC,iBAAiB,CAAC;YAEtC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBACxC,IAAI,KAAK,CAAC,WAAW,GAAG,MAAM,EAAE,CAAC;oBAC/B,MAAM,GAAG,KAAK,CAAC,WAAW,CAAC;oBAC3B,SAAS,GAAG,GAAG,CAAC;gBAClB,CAAC;YACH,CAAC;YAED,IAAI,SAAS,KAAK,SAAS;gBAAE,OAAO;YAEpC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YAC3C,IAAI,MAAM,KAAK,SAAS;gBAAE,OAAO;YAEjC,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;CACF;AAED,iGAAiG;AACjG,MAAM,UAAU,QAAQ,CAAC,QAAgB,EAAE,GAAW,EAAE,IAAsB;IAC5E,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,QAAQ,IAAI,GAAG,EAAE,CAAC;AAC9C,CAAC"}

package/dist/routing/router.d.ts

@@ -0,0 +1,53 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+import type { CamusEndpointPool } from '../endpoint-pool.js';
+import type { CamusRoutingAdvice } from './advice.js';
+import type { CamusRouteOpKind } from './route-cache.js';
+/**
+ * Learned statement routing for one deployment: the operator-configured trust map from server node
+ * identities to endpoint pool members, plus the bounded cache of learned routes.
+ *
+ * The trust map is the routing authority. Advice names an opaque node identity; it becomes a
+ * destination only through this map, and only when the mapped address is a member of the endpoint
+ * pool. So a response can never steer traffic, or credentials, anywhere the operator did not list,
+ * and every routable address already passed the same validation the pool applies.
+ *
+ * A router is shared per deployment and routing configuration, for the same reason the endpoint
+ * pool is: an application that builds a client per request would otherwise start cold every time
+ * and never learn anything.
+ */
+export declare class CamusStatementRouter {
+    private static readonly shared;
+    private static readonly MAX_ENTRIES;
+    private static readonly MAX_BYTES;
+    /** The process-wide router for a deployment-and-configuration key. */
+    static forKey(key: string, factory: () => CamusStatementRouter): CamusStatementRouter;
+    /** @internal Test hook: drops every shared router. */
+    static resetShared(): void;
+    private readonly routes;
+    private readonly nodeAddresses;
+    private readonly pool;
+    private readonly maxHintAgeMs;
+    /** @internal Test hook: the monotonic clock this router reads. */
+    clock: () => number;
+    constructor(nodeAddresses: ReadonlyMap<string, string>, pool: CamusEndpointPool, maxHintAgeMs: number);
+    /** How many destinations are currently learned. Diagnostic. */
+    get learnedRouteCount(): number;
+    /**
+     * The endpoint to prefer for a statement, or `undefined` to fall back to the pool's rotation.
+     *
+     * The returned `revision` must be handed back to `learn` for the same statement, so a reply that
+     * arrives late cannot overwrite a route a faster reply already refreshed.
+     */
+    selectEndpoint(database: string, sql: string, kind: CamusRouteOpKind): {
+        endpoint: string | undefined;
+        revision: number;
+    };
+    /** Applies the advice a statement's reply carried. Unusable advice is dropped, never an error. */
+    learn(database: string, sql: string, kind: CamusRouteOpKind, advice: CamusRoutingAdvice | undefined, observedRevision: number): void;
+}
+//# sourceMappingURL=router.d.ts.map

package/dist/routing/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/routing/router.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE7D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGzD;;;;;;;;;;;;GAYG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAA8C;IAE5E,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAQ;IAE3C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAmB;IAEpD,sEAAsE;IACtE,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,oBAAoB,GAAG,oBAAoB;IAIrF,sDAAsD;IACtD,MAAM,CAAC,WAAW,IAAI,IAAI;IAI1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAGrB;IAEF,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA8B;IAE5D,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAoB;IAEzC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IAEtC,kEAAkE;IAClE,KAAK,EAAE,MAAM,MAAM,CAA2B;gBAElC,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM;IAMrG,+DAA+D;IAC/D,IAAI,iBAAiB,IAAI,MAAM,CAE9B;IAED;;;;;OAKG;IACH,cAAc,CACZ,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,gBAAgB,GACrB;QAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE;IAerD,kGAAkG;IAClG,KAAK,CACH,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,gBAAgB,EACtB,MAAM,EAAE,kBAAkB,GAAG,SAAS,EACtC,gBAAgB,EAAE,MAAM,GACvB,IAAI;CAiCR"}

package/dist/routing/router.js

@@ -0,0 +1,89 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+import { SharedRegistry } from '../shared-registry.js';
+import { CamusRoutingDisposition, ROUTING_ACCEPT_VERSION } from './advice.js';
+import { CamusStatementRouteCache, routeKey } from './route-cache.js';
+/**
+ * Learned statement routing for one deployment: the operator-configured trust map from server node
+ * identities to endpoint pool members, plus the bounded cache of learned routes.
+ *
+ * The trust map is the routing authority. Advice names an opaque node identity; it becomes a
+ * destination only through this map, and only when the mapped address is a member of the endpoint
+ * pool. So a response can never steer traffic, or credentials, anywhere the operator did not list,
+ * and every routable address already passed the same validation the pool applies.
+ *
+ * A router is shared per deployment and routing configuration, for the same reason the endpoint
+ * pool is: an application that builds a client per request would otherwise start cold every time
+ * and never learn anything.
+ */
+export class CamusStatementRouter {
+    static shared = new SharedRegistry();
+    static MAX_ENTRIES = 4096;
+    static MAX_BYTES = 4 * 1024 * 1024;
+    /** The process-wide router for a deployment-and-configuration key. */
+    static forKey(key, factory) {
+        return CamusStatementRouter.shared.get(key, factory);
+    }
+    /** @internal Test hook: drops every shared router. */
+    static resetShared() {
+        CamusStatementRouter.shared.clear();
+    }
+    routes = new CamusStatementRouteCache(CamusStatementRouter.MAX_ENTRIES, CamusStatementRouter.MAX_BYTES);
+    nodeAddresses;
+    pool;
+    maxHintAgeMs;
+    /** @internal Test hook: the monotonic clock this router reads. */
+    clock = () => performance.now();
+    constructor(nodeAddresses, pool, maxHintAgeMs) {
+        this.nodeAddresses = nodeAddresses;
+        this.pool = pool;
+        this.maxHintAgeMs = Math.max(1, maxHintAgeMs);
+    }
+    /** How many destinations are currently learned. Diagnostic. */
+    get learnedRouteCount() {
+        return this.routes.size;
+    }
+    /**
+     * The endpoint to prefer for a statement, or `undefined` to fall back to the pool's rotation.
+     *
+     * The returned `revision` must be handed back to `learn` for the same statement, so a reply that
+     * arrives late cannot overwrite a route a faster reply already refreshed.
+     */
+    selectEndpoint(database, sql, kind) {
+        const key = routeKey(database, sql, kind);
+        const { nodeId, revision } = this.routes.tryGet(key, this.clock());
+        if (nodeId === undefined)
+            return { endpoint: undefined, revision };
+        const address = this.nodeAddresses.get(nodeId);
+        if (address === undefined)
+            return { endpoint: undefined, revision };
+        // A route pointing at a node that stopped answering falls back to rotation rather than
+        // steering traffic at it.
+        return { endpoint: this.pool.isQuarantined(address) ? undefined : address, revision };
+    }
+    /** Applies the advice a statement's reply carried. Unusable advice is dropped, never an error. */
+    learn(database, sql, kind, advice, observedRevision) {
+        if (advice === undefined || advice.version !== ROUTING_ACCEPT_VERSION)
+            return;
+        const key = routeKey(database, sql, kind);
+        if (advice.disposition === CamusRoutingDisposition.Clear) {
+            this.routes.clear(key, observedRevision);
+            return;
+        }
+        if (advice.disposition !== CamusRoutingDisposition.Prefer ||
+            !advice.parametersIndependentScope ||
+            advice.preferredNodeId === undefined ||
+            advice.maxAgeMs <= 0 ||
+            !this.nodeAddresses.has(advice.preferredNodeId)) {
+            return;
+        }
+        const now = this.clock();
+        const ttl = Math.min(advice.maxAgeMs, this.maxHintAgeMs);
+        this.routes.learn(key, (database.length + sql.length) * 2, advice.preferredNodeId, advice.dependencyToken, now + ttl, observedRevision, now);
+    }
+}
+//# sourceMappingURL=router.js.map

package/dist/routing/router.js.map

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