camusdb 0.1.0

package/dist/transaction.d.ts

@@ -0,0 +1,117 @@
+/**
+ * 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 { CamusTransactionOptions } from './options.js';
+import type { ClientRuntime } from './runtime.js';
+/**
+ * A set of reads and writes that take effect atomically, at one logical instant, across columns,
+ * rows, and tables.
+ *
+ * **Where a transaction starts.** With learned routing off, `BEGIN` is sent when the transaction is
+ * created, on the pool's next endpoint. With learned routing on, `BEGIN` is deferred: the
+ * transaction is started by its first statement, on the endpoint that statement's learned route
+ * names, so a transaction whose first statement touches a table runs where that table's leader is.
+ * Once started it is pinned to that endpoint for its whole life; a statement's own route may inform
+ * a later transaction, but never relocates this one. A caller that knows the transaction's hot
+ * statement can choose the endpoint at `BEGIN` with `options.affinity` instead.
+ *
+ * Two consequences of the deferral are visible, and only in routed mode: the server-minted identity
+ * reads as zero until the first statement, and a failure to begin surfaces from that first
+ * statement rather than from the call that created the transaction.
+ */
+export declare class CamusTransaction {
+    private readonly runtime;
+    private txnIdPTValue;
+    private txnIdCounterValue;
+    private endpointValue;
+    private startedValue;
+    /**
+     * The single `BEGIN` in flight or finished, for a deferred transaction. Every racing first
+     * statement awaits this same promise, and a `BEGIN` that failed stays failed: nothing was minted,
+     * the transaction is unusable, and the caller begins a new one — which is the state a failed
+     * eager `BEGIN` leaves too.
+     */
+    private startPromise;
+    private startFailed;
+    private finalized;
+    /** The concurrency knobs this transaction was begun with, after every default was applied. */
+    readonly options: CamusTransactionOptions;
+    /**
+     * The stream slot this transaction's statements pin to, so the server sees them in one ordering
+     * chain. It is a gRPC concept; REST does not pin.
+     */
+    streamSlot: number | undefined;
+    /** @internal Use `CamusClient.beginTransaction`. */
+    constructor(runtime: ClientRuntime, options: CamusTransactionOptions, started?: {
+        txnIdPT: bigint;
+        txnIdCounter: number;
+        endpoint: string;
+        streamSlot?: number | undefined;
+    });
+    /**
+     * True once the server minted this transaction.
+     *
+     * It is always true with learned routing off. With routing on it is false until the first
+     * statement, or until an explicit `affinity`, starts it.
+     */
+    get isStarted(): boolean;
+    /** True once this transaction was committed or rolled back. */
+    get isFinalized(): boolean;
+    /** The physical-time half of the server-minted identity. Zero until the transaction starts. */
+    get txnIdPT(): bigint;
+    /** The counter half of the server-minted identity. Zero until the transaction starts. */
+    get txnIdCounter(): number;
+    /** The identity as one string, for logs and correlation. */
+    get transactionId(): string;
+    /** The endpoint this transaction is pinned to, or `undefined` while it has not started. */
+    get endpoint(): string | undefined;
+    /**
+     * Starts the transaction if it has not started, and reports the endpoint it is pinned to.
+     *
+     * It starts on `preferredEndpoint` when one is given — a learned route for the statement about
+     * to run — and on the pool's rotation otherwise. The first caller sends `BEGIN`; a concurrent
+     * caller awaits that same send. Once started, a later call's preferred endpoint is ignored,
+     * because the pin is final.
+     *
+     * @internal
+     */
+    ensureStarted(preferredEndpoint: string | undefined, signal?: AbortSignal): Promise<string>;
+    private startOn;
+    /** Makes this transaction's writes durable. */
+    commit(signal?: AbortSignal): Promise<void>;
+    /** Discards this transaction's writes. */
+    rollback(signal?: AbortSignal): Promise<void>;
+    /**
+     * Issues a commit or a rollback, and resolves a `CADB0509` outcome by re-issuing the **same**
+     * finalize on the **same** handle, bounded and backing off.
+     *
+     * `CADB0509` says the outcome is not known yet. The transaction is not dead, so the operation
+     * must never be replayed from `BEGIN`: that could apply an already-durable commit a second time.
+     * Every other failure reaches the caller.
+     *
+     * A deferred transaction that ran no statement is started here first, on the pool's rotation, so
+     * the server sees the same `BEGIN` and finalize pair it always did.
+     */
+    private finalize;
+    /**
+     * Rolls the transaction back if it was neither committed nor rolled back, so a `using` block
+     * cannot leave one open. A rollback that itself fails is swallowed: the block is unwinding, and
+     * the server ends an abandoned transaction on its own session timeout.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * The routing kind a statement of this transaction reports. Statements inside a transaction still
+     * negotiate and learn, for the benefit of the next transaction, but the route they learn never
+     * moves this one.
+     *
+     * @internal
+     */
+    static readonly routeKind: {
+        readonly Query: 0;
+        readonly NonQuery: 1;
+    };
+}
+//# sourceMappingURL=transaction.d.ts.map

package/dist/transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../src/transaction.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAE5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAGlD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IAExC,OAAO,CAAC,YAAY,CAAM;IAE1B,OAAO,CAAC,iBAAiB,CAAK;IAE9B,OAAO,CAAC,aAAa,CAAqB;IAE1C,OAAO,CAAC,YAAY,CAAS;IAE7B;;;;;OAKG;IACH,OAAO,CAAC,YAAY,CAA4B;IAEhD,OAAO,CAAC,WAAW,CAAS;IAE5B,OAAO,CAAC,SAAS,CAAS;IAE1B,8FAA8F;IAC9F,QAAQ,CAAC,OAAO,EAAE,uBAAuB,CAAC;IAE1C;;;OAGG;IACH,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAE/B,oDAAoD;gBAElD,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,uBAAuB,EAChC,OAAO,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE;IAcxG;;;;;OAKG;IACH,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,+DAA+D;IAC/D,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,+FAA+F;IAC/F,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,yFAAyF;IACzF,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,4DAA4D;IAC5D,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,2FAA2F;IAC3F,IAAI,QAAQ,IAAI,MAAM,GAAG,SAAS,CAEjC;IAED;;;;;;;;;OASG;IACG,aAAa,CAAC,iBAAiB,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;YAUnF,OAAO;IAqBrB,+CAA+C;IAC/C,MAAM,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3C,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7C;;;;;;;;;;OAUG;YACW,QAAQ;IA4CtB;;;;OAIG;IACG,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;IAU5C;;;;;;OAMG;IACH,MAAM,CAAC,QAAQ,CAAC,SAAS;;;MAAoB;CAC9C"}

package/dist/transaction.js

@@ -0,0 +1,204 @@
+/**
+ * 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';
+import { delay } from './retry.js';
+import { CamusRouteOpKind } from './routing/route-cache.js';
+/**
+ * A set of reads and writes that take effect atomically, at one logical instant, across columns,
+ * rows, and tables.
+ *
+ * **Where a transaction starts.** With learned routing off, `BEGIN` is sent when the transaction is
+ * created, on the pool's next endpoint. With learned routing on, `BEGIN` is deferred: the
+ * transaction is started by its first statement, on the endpoint that statement's learned route
+ * names, so a transaction whose first statement touches a table runs where that table's leader is.
+ * Once started it is pinned to that endpoint for its whole life; a statement's own route may inform
+ * a later transaction, but never relocates this one. A caller that knows the transaction's hot
+ * statement can choose the endpoint at `BEGIN` with `options.affinity` instead.
+ *
+ * Two consequences of the deferral are visible, and only in routed mode: the server-minted identity
+ * reads as zero until the first statement, and a failure to begin surfaces from that first
+ * statement rather than from the call that created the transaction.
+ */
+export class CamusTransaction {
+    runtime;
+    txnIdPTValue = 0n;
+    txnIdCounterValue = 0;
+    endpointValue;
+    startedValue = false;
+    /**
+     * The single `BEGIN` in flight or finished, for a deferred transaction. Every racing first
+     * statement awaits this same promise, and a `BEGIN` that failed stays failed: nothing was minted,
+     * the transaction is unusable, and the caller begins a new one — which is the state a failed
+     * eager `BEGIN` leaves too.
+     */
+    startPromise;
+    startFailed = false;
+    finalized = false;
+    /** The concurrency knobs this transaction was begun with, after every default was applied. */
+    options;
+    /**
+     * The stream slot this transaction's statements pin to, so the server sees them in one ordering
+     * chain. It is a gRPC concept; REST does not pin.
+     */
+    streamSlot;
+    /** @internal Use `CamusClient.beginTransaction`. */
+    constructor(runtime, options, started) {
+        this.runtime = runtime;
+        this.options = options;
+        if (started !== undefined) {
+            this.txnIdPTValue = started.txnIdPT;
+            this.txnIdCounterValue = started.txnIdCounter;
+            this.endpointValue = started.endpoint;
+            this.streamSlot = started.streamSlot;
+            this.startedValue = true;
+        }
+    }
+    /**
+     * True once the server minted this transaction.
+     *
+     * It is always true with learned routing off. With routing on it is false until the first
+     * statement, or until an explicit `affinity`, starts it.
+     */
+    get isStarted() {
+        return this.startedValue;
+    }
+    /** True once this transaction was committed or rolled back. */
+    get isFinalized() {
+        return this.finalized;
+    }
+    /** The physical-time half of the server-minted identity. Zero until the transaction starts. */
+    get txnIdPT() {
+        return this.txnIdPTValue;
+    }
+    /** The counter half of the server-minted identity. Zero until the transaction starts. */
+    get txnIdCounter() {
+        return this.txnIdCounterValue;
+    }
+    /** The identity as one string, for logs and correlation. */
+    get transactionId() {
+        return `${this.txnIdPTValue.toString()}:${String(this.txnIdCounterValue)}`;
+    }
+    /** The endpoint this transaction is pinned to, or `undefined` while it has not started. */
+    get endpoint() {
+        return this.endpointValue;
+    }
+    /**
+     * Starts the transaction if it has not started, and reports the endpoint it is pinned to.
+     *
+     * It starts on `preferredEndpoint` when one is given — a learned route for the statement about
+     * to run — and on the pool's rotation otherwise. The first caller sends `BEGIN`; a concurrent
+     * caller awaits that same send. Once started, a later call's preferred endpoint is ignored,
+     * because the pin is final.
+     *
+     * @internal
+     */
+    async ensureStarted(preferredEndpoint, signal) {
+        if (!this.startedValue) {
+            this.startPromise ??= this.startOn(preferredEndpoint ?? this.runtime.nextEndpoint(), signal);
+            await this.startPromise;
+        }
+        return this.endpointValue;
+    }
+    async startOn(target, signal) {
+        try {
+            const result = await this.runtime.transport.startTransaction(target, this.runtime.database, this.options, this.runtime.timeoutSeconds, signal);
+            this.txnIdPTValue = result.txnIdPT;
+            this.txnIdCounterValue = result.txnIdCounter;
+            this.streamSlot = result.streamSlot;
+            this.endpointValue = target;
+            this.startedValue = true;
+        }
+        catch (error) {
+            this.startFailed = true;
+            throw error;
+        }
+    }
+    /** Makes this transaction's writes durable. */
+    commit(signal) {
+        return this.finalize(true, signal);
+    }
+    /** Discards this transaction's writes. */
+    rollback(signal) {
+        return this.finalize(false, signal);
+    }
+    /**
+     * Issues a commit or a rollback, and resolves a `CADB0509` outcome by re-issuing the **same**
+     * finalize on the **same** handle, bounded and backing off.
+     *
+     * `CADB0509` says the outcome is not known yet. The transaction is not dead, so the operation
+     * must never be replayed from `BEGIN`: that could apply an already-durable commit a second time.
+     * Every other failure reaches the caller.
+     *
+     * A deferred transaction that ran no statement is started here first, on the pool's rotation, so
+     * the server sees the same `BEGIN` and finalize pair it always did.
+     */
+    async finalize(commit, signal) {
+        if (this.finalized) {
+            throw new CamusError(CamusErrorCode.Generic, 'This transaction was already committed or rolled back.');
+        }
+        // A deferred `BEGIN` that failed left nothing on the server. The failure already surfaced at
+        // the statement that triggered it, so a rollback — which a scope issues without looking — has
+        // nothing to undo and finishes quietly, while a commit still reports the failed start.
+        if (!commit && !this.startedValue && this.startFailed) {
+            this.finalized = true;
+            return;
+        }
+        const target = await this.ensureStarted(undefined, signal);
+        for (let attempt = 0;; attempt++) {
+            try {
+                await this.runtime.transport.finalizeTransaction(commit, target, this.runtime.database, this.txnIdPTValue, this.txnIdCounterValue, this.streamSlot, this.runtime.timeoutSeconds, signal);
+                this.finalized = true;
+                return;
+            }
+            catch (error) {
+                if (!CamusError.is(error) ||
+                    error.code !== CamusErrorCode.FinalizeUnresolved ||
+                    attempt >= MAX_FINALIZE_ATTEMPTS) {
+                    throw error;
+                }
+                await delay(finalizeDelayMs(attempt), signal);
+            }
+        }
+    }
+    /**
+     * Rolls the transaction back if it was neither committed nor rolled back, so a `using` block
+     * cannot leave one open. A rollback that itself fails is swallowed: the block is unwinding, and
+     * the server ends an abandoned transaction on its own session timeout.
+     */
+    async [Symbol.asyncDispose]() {
+        if (this.finalized)
+            return;
+        try {
+            await this.rollback();
+        }
+        catch {
+            // Nothing useful can be done while a scope is unwinding.
+        }
+    }
+    /**
+     * The routing kind a statement of this transaction reports. Statements inside a transaction still
+     * negotiate and learn, for the benefit of the next transaction, but the route they learn never
+     * moves this one.
+     *
+     * @internal
+     */
+    static routeKind = CamusRouteOpKind;
+}
+/**
+ * How many times an unresolved commit or rollback is re-issued on the same handle before the error
+ * reaches the caller. The server's own session timeout is the ultimate backstop.
+ */
+const MAX_FINALIZE_ATTEMPTS = 10;
+/**
+ * The finalize back-off: 50 ms doubling to about 3.2 seconds, which matches the server's contract
+ * for an unresolved outcome.
+ */
+function finalizeDelayMs(attempt) {
+    return 50 * 2 ** Math.min(attempt, 6);
+}
+//# sourceMappingURL=transaction.js.map

package/dist/transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../src/transaction.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,gBAAgB;IACV,OAAO,CAAgB;IAEhC,YAAY,GAAG,EAAE,CAAC;IAElB,iBAAiB,GAAG,CAAC,CAAC;IAEtB,aAAa,CAAqB;IAElC,YAAY,GAAG,KAAK,CAAC;IAE7B;;;;;OAKG;IACK,YAAY,CAA4B;IAExC,WAAW,GAAG,KAAK,CAAC;IAEpB,SAAS,GAAG,KAAK,CAAC;IAE1B,8FAA8F;IACrF,OAAO,CAA0B;IAE1C;;;OAGG;IACH,UAAU,CAAqB;IAE/B,oDAAoD;IACpD,YACE,OAAsB,EACtB,OAAgC,EAChC,OAAsG;QAEtG,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QAEvB,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC;YACpC,IAAI,CAAC,iBAAiB,GAAG,OAAO,CAAC,YAAY,CAAC;YAC9C,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,QAAQ,CAAC;YACtC,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;YACrC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QAC3B,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED,+DAA+D;IAC/D,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED,+FAA+F;IAC/F,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED,yFAAyF;IACzF,IAAI,YAAY;QACd,OAAO,IAAI,CAAC,iBAAiB,CAAC;IAChC,CAAC;IAED,4DAA4D;IAC5D,IAAI,aAAa;QACf,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,IAAI,MAAM,CAAC,IAAI,CAAC,iBAAiB,CAAC,EAAE,CAAC;IAC7E,CAAC;IAED,2FAA2F;IAC3F,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,aAAa,CAAC;IAC5B,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,aAAa,CAAC,iBAAqC,EAAE,MAAoB;QAC7E,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YACvB,IAAI,CAAC,YAAY,KAAK,IAAI,CAAC,OAAO,CAAC,iBAAiB,IAAI,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,MAAM,CAAC,CAAC;YAE7F,MAAM,IAAI,CAAC,YAAY,CAAC;QAC1B,CAAC;QAED,OAAO,IAAI,CAAC,aAAc,CAAC;IAC7B,CAAC;IAEO,KAAK,CAAC,OAAO,CAAC,MAAc,EAAE,MAA+B;QACnE,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,gBAAgB,CAC1D,MAAM,EACN,IAAI,CAAC,OAAO,CAAC,QAAQ,EACrB,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,OAAO,CAAC,cAAc,EAC3B,MAAM,CACP,CAAC;YAEF,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,OAAO,CAAC;YACnC,IAAI,CAAC,iBAAiB,GAAG,MAAM,CAAC,YAAY,CAAC;YAC7C,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;YACpC,IAAI,CAAC,aAAa,GAAG,MAAM,CAAC;YAC5B,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QAC3B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;YACxB,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,+CAA+C;IAC/C,MAAM,CAAC,MAAoB;QACzB,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACrC,CAAC;IAED,0CAA0C;IAC1C,QAAQ,CAAC,MAAoB;QAC3B,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACtC,CAAC;IAED;;;;;;;;;;OAUG;IACK,KAAK,CAAC,QAAQ,CAAC,MAAe,EAAE,MAA+B;QACrE,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,MAAM,IAAI,UAAU,CAAC,cAAc,CAAC,OAAO,EAAE,wDAAwD,CAAC,CAAC;QACzG,CAAC;QAED,6FAA6F;QAC7F,8FAA8F;QAC9F,uFAAuF;QACvF,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACtD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;YACtB,OAAO;QACT,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QAE3D,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,EAAE,EAAE,CAAC;YAClC,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,mBAAmB,CAC9C,MAAM,EACN,MAAM,EACN,IAAI,CAAC,OAAO,CAAC,QAAQ,EACrB,IAAI,CAAC,YAAY,EACjB,IAAI,CAAC,iBAAiB,EACtB,IAAI,CAAC,UAAU,EACf,IAAI,CAAC,OAAO,CAAC,cAAc,EAC3B,MAAM,CACP,CAAC;gBAEF,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;gBACtB,OAAO;YACT,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IACE,CAAC,UAAU,CAAC,EAAE,CAAC,KAAK,CAAC;oBACrB,KAAK,CAAC,IAAI,KAAK,cAAc,CAAC,kBAAkB;oBAChD,OAAO,IAAI,qBAAqB,EAChC,CAAC;oBACD,MAAM,KAAK,CAAC;gBACd,CAAC;gBAED,MAAM,KAAK,CAAC,eAAe,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC;YAChD,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC;QACzB,IAAI,IAAI,CAAC,SAAS;YAAE,OAAO;QAE3B,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;QACxB,CAAC;QAAC,MAAM,CAAC;YACP,yDAAyD;QAC3D,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAU,SAAS,GAAG,gBAAgB,CAAC;;AAG/C;;;GAGG;AACH,MAAM,qBAAqB,GAAG,EAAE,CAAC;AAEjC;;;GAGG;AACH,SAAS,eAAe,CAAC,OAAe;IACtC,OAAO,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;AACxC,CAAC"}

package/dist/transport/authenticating-transport.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.
+ */
+import type { CamusTokenProvider } from '../auth/token-provider.js';
+import type { CamusProtocol } from '../config.js';
+import type { CamusTransactionOptions } from '../options.js';
+import type { CamusRowSource } from '../row-source.js';
+import type { CamusBranchRow, CamusTransport, NonQueryTransportResult, PreparedStatementInfo, QueryTransportResult, StartTransactionResult, TransportInsertRequest, TransportSqlRequest } from './transport.js';
+/**
+ * Wraps a transport with the reactive half of token management.
+ *
+ * The inner transport attaches whatever token the provider currently holds. This wrapper watches
+ * for the server rejecting it with `CADB0516`, discards it, and replays the operation once with a
+ * freshly minted one.
+ *
+ * That covers the failures a client-side expiry timer cannot see: a rotated password, a dropped
+ * user, a logout from elsewhere, a server configured with a shorter token lifetime than the driver
+ * assumes, or a token minted before a server restart. It does **not** retry `CADB0517`,
+ * insufficient privilege: authenticating again as the same user cannot grant a privilege, so a
+ * retry would only double the work before the same refusal.
+ *
+ * There is exactly one replay per call, and only when the attempt actually presented a token the
+ * provider can replace. A rejection with no token in hand came from the login itself — a wrong
+ * password — and replaying it would burn two attempts per statement against a limit of twenty per
+ * account per minute. A token supplied directly is likewise reported as it is, because there is no
+ * password to mint a replacement with.
+ *
+ * A replayed statement never reached execution, so a replay here is no less safe than the retry
+ * paths the driver already runs for a serializable conflict.
+ */
+export declare class AuthenticatingTransport implements CamusTransport {
+    /** The wrapped transport, for tests and for the login client the gRPC transport also is. */
+    readonly inner: CamusTransport;
+    private readonly auth;
+    constructor(inner: CamusTransport, auth: CamusTokenProvider);
+    get protocol(): CamusProtocol;
+    startTransaction(endpoint: string, database: string, options: CamusTransactionOptions, timeoutSeconds: number, signal?: AbortSignal): Promise<StartTransactionResult>;
+    finalizeTransaction(commit: boolean, endpoint: string, database: string, txnIdPT: bigint, txnIdCounter: number, streamSlot: number | undefined, timeoutSeconds: number, signal?: AbortSignal): Promise<void>;
+    executeQuery(request: TransportSqlRequest): Promise<QueryTransportResult>;
+    executeQueryStream(request: TransportSqlRequest): Promise<CamusRowSource>;
+    executeNonQuery(request: TransportSqlRequest): Promise<NonQueryTransportResult>;
+    insert(request: TransportInsertRequest): Promise<number>;
+    executeDdl(request: TransportSqlRequest): Promise<boolean>;
+    prepare(endpoint: string, database: string, sql: string, timeoutSeconds: number, signal?: AbortSignal): Promise<PreparedStatementInfo>;
+    /**
+     * Closing is best-effort and idempotent. A token the server has already rejected means the
+     * handle it named is unreachable anyway, so there is nothing a replay could still release.
+     */
+    closePrepared(endpoint: string, database: string, sql: string, signal?: AbortSignal): Promise<void>;
+    ping(endpoint: string, timeoutSeconds: number, signal?: AbortSignal): Promise<boolean>;
+    createDatabase(endpoint: string, database: string, ifNotExists: boolean, timeoutSeconds: number, signal?: AbortSignal): Promise<void>;
+    createBranchDatabase(endpoint: string, branchName: string, sourceDatabaseName: string, ifNotExists: boolean, timeoutSeconds: number, signal?: AbortSignal): Promise<void>;
+    dropDatabase(endpoint: string, database: string, timeoutSeconds: number, signal?: AbortSignal): Promise<void>;
+    showBranches(endpoint: string, database: string, timeoutSeconds: number, signal?: AbortSignal): Promise<CamusBranchRow[]>;
+    showAncestors(endpoint: string, database: string, timeoutSeconds: number, signal?: AbortSignal): Promise<CamusBranchRow[]>;
+    close(): Promise<void>;
+    private run;
+    private isRenewable;
+}
+//# sourceMappingURL=authenticating-transport.d.ts.map

package/dist/transport/authenticating-transport.d.ts.map

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

package/dist/transport/authenticating-transport.js

@@ -0,0 +1,119 @@
+/**
+ * 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';
+/**
+ * Wraps a transport with the reactive half of token management.
+ *
+ * The inner transport attaches whatever token the provider currently holds. This wrapper watches
+ * for the server rejecting it with `CADB0516`, discards it, and replays the operation once with a
+ * freshly minted one.
+ *
+ * That covers the failures a client-side expiry timer cannot see: a rotated password, a dropped
+ * user, a logout from elsewhere, a server configured with a shorter token lifetime than the driver
+ * assumes, or a token minted before a server restart. It does **not** retry `CADB0517`,
+ * insufficient privilege: authenticating again as the same user cannot grant a privilege, so a
+ * retry would only double the work before the same refusal.
+ *
+ * There is exactly one replay per call, and only when the attempt actually presented a token the
+ * provider can replace. A rejection with no token in hand came from the login itself — a wrong
+ * password — and replaying it would burn two attempts per statement against a limit of twenty per
+ * account per minute. A token supplied directly is likewise reported as it is, because there is no
+ * password to mint a replacement with.
+ *
+ * A replayed statement never reached execution, so a replay here is no less safe than the retry
+ * paths the driver already runs for a serializable conflict.
+ */
+export class AuthenticatingTransport {
+    /** The wrapped transport, for tests and for the login client the gRPC transport also is. */
+    inner;
+    auth;
+    constructor(inner, auth) {
+        this.inner = inner;
+        this.auth = auth;
+    }
+    get protocol() {
+        return this.inner.protocol;
+    }
+    startTransaction(endpoint, database, options, timeoutSeconds, signal) {
+        return this.run(() => this.inner.startTransaction(endpoint, database, options, timeoutSeconds, signal));
+    }
+    finalizeTransaction(commit, endpoint, database, txnIdPT, txnIdCounter, streamSlot, timeoutSeconds, signal) {
+        return this.run(() => this.inner.finalizeTransaction(commit, endpoint, database, txnIdPT, txnIdCounter, streamSlot, timeoutSeconds, signal));
+    }
+    executeQuery(request) {
+        return this.run(() => this.inner.executeQuery(request));
+    }
+    executeQueryStream(request) {
+        return this.run(() => this.inner.executeQueryStream(request));
+    }
+    executeNonQuery(request) {
+        return this.run(() => this.inner.executeNonQuery(request));
+    }
+    insert(request) {
+        return this.run(() => this.inner.insert(request));
+    }
+    executeDdl(request) {
+        return this.run(() => this.inner.executeDdl(request));
+    }
+    prepare(endpoint, database, sql, timeoutSeconds, signal) {
+        return this.run(() => this.inner.prepare(endpoint, database, sql, timeoutSeconds, signal));
+    }
+    /**
+     * Closing is best-effort and idempotent. A token the server has already rejected means the
+     * handle it named is unreachable anyway, so there is nothing a replay could still release.
+     */
+    closePrepared(endpoint, database, sql, signal) {
+        return this.inner.closePrepared(endpoint, database, sql, signal);
+    }
+    ping(endpoint, timeoutSeconds, signal) {
+        return this.run(() => this.inner.ping(endpoint, timeoutSeconds, signal));
+    }
+    createDatabase(endpoint, database, ifNotExists, timeoutSeconds, signal) {
+        return this.run(() => this.inner.createDatabase(endpoint, database, ifNotExists, timeoutSeconds, signal));
+    }
+    createBranchDatabase(endpoint, branchName, sourceDatabaseName, ifNotExists, timeoutSeconds, signal) {
+        return this.run(() => this.inner.createBranchDatabase(endpoint, branchName, sourceDatabaseName, ifNotExists, timeoutSeconds, signal));
+    }
+    dropDatabase(endpoint, database, timeoutSeconds, signal) {
+        return this.run(() => this.inner.dropDatabase(endpoint, database, timeoutSeconds, signal));
+    }
+    showBranches(endpoint, database, timeoutSeconds, signal) {
+        return this.run(() => this.inner.showBranches(endpoint, database, timeoutSeconds, signal));
+    }
+    showAncestors(endpoint, database, timeoutSeconds, signal) {
+        return this.run(() => this.inner.showAncestors(endpoint, database, timeoutSeconds, signal));
+    }
+    close() {
+        return this.inner.close();
+    }
+    async run(operation) {
+        // Read before the call, so a refresh by a concurrent caller is not thrown away: only the token
+        // this attempt actually presented is discarded.
+        let presented = this.auth.currentToken;
+        try {
+            return await operation();
+        }
+        catch (error) {
+            if (!this.isRenewable(error))
+                throw error;
+            // The cache is normally warm before the call. On a client's first statement it is not: the
+            // inner transport mints the token during the call, and the read above returned undefined.
+            // Falling back to the token the provider holds now discards the one that call actually
+            // presented, instead of invalidating nothing and replaying with the same rejected token.
+            presented ??= this.auth.currentToken;
+            if (presented === undefined)
+                throw error;
+            this.auth.invalidate(presented);
+        }
+        return operation();
+    }
+    isRenewable(error) {
+        return CamusError.is(error) && error.code === CamusErrorCode.AuthenticationFailed && this.auth.canRenew;
+    }
+}
+//# sourceMappingURL=authenticating-transport.js.map

package/dist/transport/authenticating-transport.js.map

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

package/dist/transport/branch-statements.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 { CamusResultSet } from '../result-set.js';
+import type { CamusBranchRow } from './transport.js';
+/**
+ * The branch statements, composed as SQL, and the mapping of what they return.
+ *
+ * Database branching has no REST route of its own: the server implements it only as SQL, so both
+ * transports compose the statement and send it down the ordinary DDL and query routes. This module
+ * holds that composition once, so the two transports cannot spell a statement differently.
+ *
+ * A database name is a bare identifier in the grammar, so it is backtick-delimited here, and a name
+ * carrying a backtick is refused rather than doubled — the server trims the delimiters instead of
+ * decoding a doubled backtick, so doubling would neutralize nothing. These statements are among the
+ * few this driver composes as text, and a database name can come from an application's own input.
+ */
+/** `CREATE DATABASE <branch> BRANCH FROM <source>`. */
+export declare function createBranchDatabaseSql(branchName: string, sourceDatabaseName: string, ifNotExists: boolean): string;
+/** `CREATE DATABASE <name>`. */
+export declare function createDatabaseSql(database: string, ifNotExists: boolean): string;
+/** `DROP DATABASE <name>`. */
+export declare function dropDatabaseSql(database: string): string;
+/** `SHOW BRANCHES FROM <name>`. */
+export declare function showBranchesSql(database: string): string;
+/** `SHOW ANCESTORS FROM <name>`. */
+export declare function showAncestorsSql(database: string): string;
+/**
+ * Reads what a branch listing returned.
+ *
+ * `SHOW BRANCHES` emits `[database, id, depth, parent, fork_timestamp]`, and `SHOW ANCESTORS` emits
+ * the same without `parent`. The columns are read by name, so either shape reconstructs, and a
+ * server that adds a column changes nothing here.
+ */
+export declare function mapBranchRows(result: CamusResultSet): CamusBranchRow[];
+//# sourceMappingURL=branch-statements.d.ts.map

package/dist/transport/branch-statements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-statements.d.ts","sourceRoot":"","sources":["../../src/transport/branch-statements.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD;;;;;;;;;;;GAWG;AAEH,uDAAuD;AACvD,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,MAAM,EAClB,kBAAkB,EAAE,MAAM,EAC1B,WAAW,EAAE,OAAO,GACnB,MAAM,CAIR;AAED,gCAAgC;AAChC,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,GAAG,MAAM,CAIhF;AAED,8BAA8B;AAC9B,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,mCAAmC;AACnC,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,oCAAoC;AACpC,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,EAAE,CA2BtE"}

package/dist/transport/branch-statements.js

@@ -0,0 +1,74 @@
+/**
+ * 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 { delimitIdentifier } from '../sql-syntax.js';
+/**
+ * The branch statements, composed as SQL, and the mapping of what they return.
+ *
+ * Database branching has no REST route of its own: the server implements it only as SQL, so both
+ * transports compose the statement and send it down the ordinary DDL and query routes. This module
+ * holds that composition once, so the two transports cannot spell a statement differently.
+ *
+ * A database name is a bare identifier in the grammar, so it is backtick-delimited here, and a name
+ * carrying a backtick is refused rather than doubled — the server trims the delimiters instead of
+ * decoding a doubled backtick, so doubling would neutralize nothing. These statements are among the
+ * few this driver composes as text, and a database name can come from an application's own input.
+ */
+/** `CREATE DATABASE <branch> BRANCH FROM <source>`. */
+export function createBranchDatabaseSql(branchName, sourceDatabaseName, ifNotExists) {
+    const prefix = ifNotExists ? 'CREATE DATABASE IF NOT EXISTS ' : 'CREATE DATABASE ';
+    return `${prefix}${quote(branchName)} BRANCH FROM ${quote(sourceDatabaseName)}`;
+}
+/** `CREATE DATABASE <name>`. */
+export function createDatabaseSql(database, ifNotExists) {
+    const prefix = ifNotExists ? 'CREATE DATABASE IF NOT EXISTS ' : 'CREATE DATABASE ';
+    return `${prefix}${quote(database)}`;
+}
+/** `DROP DATABASE <name>`. */
+export function dropDatabaseSql(database) {
+    return `DROP DATABASE ${quote(database)}`;
+}
+/** `SHOW BRANCHES FROM <name>`. */
+export function showBranchesSql(database) {
+    return `SHOW BRANCHES FROM ${quote(database)}`;
+}
+/** `SHOW ANCESTORS FROM <name>`. */
+export function showAncestorsSql(database) {
+    return `SHOW ANCESTORS FROM ${quote(database)}`;
+}
+/**
+ * Reads what a branch listing returned.
+ *
+ * `SHOW BRANCHES` emits `[database, id, depth, parent, fork_timestamp]`, and `SHOW ANCESTORS` emits
+ * the same without `parent`. The columns are read by name, so either shape reconstructs, and a
+ * server that adds a column changes nothing here.
+ */
+export function mapBranchRows(result) {
+    const index = new Map();
+    result.columnNames.forEach((name, position) => index.set(name, position));
+    const rows = [];
+    for (let r = 0; r < result.rowCount; r++) {
+        const text = (name) => {
+            const column = index.get(name);
+            if (column === undefined)
+                return undefined;
+            return result.cell(r, column).strValue ?? undefined;
+        };
+        const depthColumn = index.get('depth');
+        rows.push({
+            database: text('database'),
+            id: text('id'),
+            depth: depthColumn === undefined ? 0 : Number(result.cell(r, depthColumn).longValue ?? 0n),
+            parent: text('parent'),
+            forkTimestamp: text('fork_timestamp'),
+        });
+    }
+    return rows;
+}
+function quote(name) {
+    return delimitIdentifier(name, 'name');
+}
+//# sourceMappingURL=branch-statements.js.map