@harperfast/harper 5.3.0-alpha.1 → 5.3.0-beta.1

package/dist/resources/DatabaseTransaction.d.ts

@@ -48,6 +48,8 @@ declare class StartedTransaction extends Error {
  * transactions, while core keeps the consistency guarantee.
  */
 export declare function transactionOpenTooLongError(): ServerError;
+export declare function getReadTransactionGuard(transaction: ReadTransaction): (() => void) | undefined;
+export declare function trackReadRange(transaction: ReadTransaction, createRange: () => any): any;
 type MaybePromise<T> = T | Promise<T>;
 export type CommitOptions = {
     doneWriting?: boolean;
@@ -62,6 +64,10 @@ type ReadTransaction = (LMDBTransaction | RocksTransaction) & {
     isDone?: boolean;
     isCommitted?: boolean;
 };
+export type WriteGeneration = {
+    closed: boolean;
+    internalWrites: number;
+};
 export type TransactionWrite = {
     key: Id;
     store: any;
@@ -96,7 +102,12 @@ export type TransactionWrite = {
     trackRecordVersion?: boolean;
     recordVersionApplied?: boolean;
     innerCommit?: MaybePromise<CommitResolution>;
+    reloadCommitBase?: boolean;
+    writeGeneration?: WriteGeneration;
+    instanceClosed?: boolean;
 };
+export declare function closeWriteInstance(operation: TransactionWrite | null | undefined): void;
+export declare function validateWrite(operation: TransactionWrite, txnTime: number, transaction: DatabaseTransaction): any;
 export declare function getAppliedWriteVersion(recordVersion: number | undefined, txnLogKey: number): number;
 /**
  * The state a preceding write in this transaction left for `operation`'s key, or undefined if this
@@ -128,6 +139,7 @@ export declare class DatabaseTransaction implements Transaction {
         scopeOwned?: boolean;
     });
     writes: TransactionWrite[];
+    ownedWrites?: WeakSet<TransactionWrite>;
     writesByKey?: Map<any, Map<unknown, TransactionWrite>>;
     completions: Promise<void>[];
     db: RootDatabaseKind;
@@ -169,8 +181,21 @@ export declare class DatabaseTransaction implements Transaction {
     commitPhaseTicks: number;
     commitChainHead?: DatabaseTransaction;
     recordLocks?: Map<any, Map<unknown, RecordLockHandle>>;
+    /**
+     * Whether any staged write was made through a record lock handle. The commit-time lease fence
+     * below is skipped entirely when this is false, which is every transaction in a core-only
+     * deployment: without it a bulk transaction of 100,000 plain writes pays 100,000 property checks
+     * before submission, on a path that is supposed to be untouched when no lock is involved. It
+     * latches rather than tracking a count, because a write whose handle was released or expired after
+     * staging is exactly what the fence exists to catch.
+     */
+    hasLeaseProtectedWrite?: boolean;
     pendingLocks?: Map<any, Map<unknown, Promise<RecordLockHandle>>>;
     setCommitPhase(committing: boolean): void;
+    rangeReadActive: boolean;
+    renewReadTimeout(): void;
+    renewIdleTimeout(): void;
+    renewChainForNativeCommit(): void;
     getReadTxn(disableSnapshot?: boolean): ReadTransaction;
     private attachOwnedTransaction;
     /**

package/dist/resources/DatabaseTransaction.js

@@ -40,6 +40,10 @@ exports.setCommitLatencyRecorder = setCommitLatencyRecorder;
 exports.getTransactionQueueDepths = getTransactionQueueDepths;
 exports.replicationConfirmation = replicationConfirmation;
 exports.transactionOpenTooLongError = transactionOpenTooLongError;
+exports.getReadTransactionGuard = getReadTransactionGuard;
+exports.trackReadRange = trackReadRange;
+exports.closeWriteInstance = closeWriteInstance;
+exports.validateWrite = validateWrite;
 exports.getAppliedWriteVersion = getAppliedWriteVersion;
 exports.priorStagedWrite = priorStagedWrite;
 exports.writeKeyId = writeKeyId;
@@ -65,6 +69,7 @@ const RETRY_NOW_VALUE = rocksdb_js_1.constants.RETRY_NOW_VALUE;
 const ordered_binary_1 = require("ordered-binary");
 const longLivedTransactions_ts_1 = require("./longLivedTransactions.js");
 const trackedTxns = new Set();
+const readTransactionOwners = new WeakMap();
 // Read options for a rotated generation's native transactions; shared because they never vary.
 const SNAPSHOT_FREE = Object.freeze({ disableSnapshot: true });
 // Logical transactions the monitor supervises for their WRITES, kept apart from trackedTxns because the
@@ -297,6 +302,104 @@ function transactionOpenTooLongError() {
     // 422 signals the request itself must change (split the work), which is the actionable response.
     return new hdbError_ts_1.ServerError('Transaction was aborted after exceeding the maximum open-transaction time; split long-running work into smaller transactions', 422);
 }
+class ReadSnapshotExpiredError extends hdbError_ts_1.ServerError {
+    constructor() {
+        super('Read scan snapshot expired; retry the read without replaying previously committed writes', 503);
+        this.name = 'ReadSnapshotExpiredError';
+    }
+}
+function getReadTransactionGuard(transaction) {
+    const owner = readTransactionOwners.get(transaction);
+    if (!owner)
+        return;
+    return function checkActive() {
+        if (owner.timedOut)
+            throw transactionOpenTooLongError();
+        if (owner.transaction !== transaction) {
+            throw new ReadSnapshotExpiredError();
+        }
+    };
+}
+function trackReadRange(transaction, createRange) {
+    const owner = readTransactionOwners.get(transaction);
+    if (!owner)
+        return createRange();
+    const checkActive = getReadTransactionGuard(transaction);
+    checkActive();
+    const range = createRange();
+    const iterate = range.iterate;
+    range.iterate = function (options) {
+        const iterator = iterate.call(this, options);
+        let done = false;
+        // Closing the underlying iterator is the one step here that can throw for a reason the caller
+        // must not see: `next()` only reaches it once the snapshot is already gone, which is the
+        // likeliest moment for the native layer to object, and an error from cleanup would replace the
+        // named 503 with exactly the raw iterator error this wrapper exists to stop surfacing. The
+        // closure reference rather than `this` so a destructured `next` still cleans up.
+        const wrapper = {
+            [Symbol.iterator]() {
+                return this;
+            },
+            next() {
+                if (done)
+                    return { done: true, value: undefined };
+                try {
+                    checkActive();
+                    owner.rangeReadActive = true;
+                    const result = iterator.next();
+                    done = result.done === true;
+                    return result;
+                }
+                catch (error) {
+                    closeQuietly();
+                    throw error;
+                }
+            },
+            return(value) {
+                if (!done) {
+                    done = true;
+                    iterator.return?.(value);
+                }
+                return { done: true, value };
+            },
+            throw(error) {
+                // Not delegated to `iterator.throw`: it closes and rethrows the same error anyway, and
+                // delegating after the close below would run it against an iterator already closed.
+                closeQuietly();
+                throw error;
+            },
+        };
+        function closeQuietly() {
+            try {
+                wrapper.return();
+            }
+            catch {
+                // the error being propagated is the actionable one
+            }
+        }
+        return wrapper;
+    };
+    return range;
+}
+function closeWriteInstance(operation) {
+    if (operation && !operation.instanceClosed) {
+        operation.instanceClosed = true;
+        if (operation.writeGeneration)
+            operation.writeGeneration.closed = true;
+    }
+}
+function validateWrite(operation, txnTime, transaction) {
+    const generation = operation.writeGeneration;
+    if (generation)
+        generation.internalWrites++;
+    try {
+        return operation.validate?.(txnTime, transaction);
+    }
+    finally {
+        if (generation)
+            generation.internalWrites--;
+    }
+}
 function getAppliedWriteVersion(recordVersion, txnLogKey) {
     return recordVersion == null ? txnLogKey : Math.min(recordVersion, txnLogKey);
 }
@@ -342,6 +445,7 @@ class DatabaseTransaction {
         this.#scopeOwned = options?.scopeOwned === true;
     }
     writes = []; // the set of writes to commit if the conditions are met
+    ownedWrites;
     completions = []; // the set of outstanding async operations to complete
     db;
     transaction;
@@ -388,8 +492,8 @@ class DatabaseTransaction {
                 txn.commitPhaseTicks = 0;
         }
     }
-    getReadTxn(disableSnapshot) {
-        this.readTxnRefCount = (this.readTxnRefCount || 0) + 1;
+    rangeReadActive = false;
+    renewReadTimeout() {
         // The limit is an IDLE limit. Writes always re-arm it (see addWrite), but reads only do so
         // while no uncommitted writes are held: staged writes hold write intents that other writers'
         // coordinated-retry commits park on, so a handler that wrote once and then only reads — an
@@ -402,6 +506,23 @@ class DatabaseTransaction {
         if ((this.writes.length === 0 && !this.next) || this.open !== exports.TRANSACTION_STATE.OPEN || !this.hasPendingWrites()) {
             this.timeout = Math.max(txnExpiration, this.timeoutBudget);
         }
+    }
+    // Each engine keeps its own expiration; LMDBTransaction overrides this with its own.
+    renewIdleTimeout() {
+        this.timeout = Math.max(txnExpiration, this.timeoutBudget ?? 0);
+    }
+    // The links after this one wait for its native commit before their own commit() is entered; each
+    // hop starts with a full idle window and a stalled native commit is still bounded by one.
+    renewChainForNativeCommit() {
+        for (let txn = this; txn; txn = txn.next) {
+            if (txn.timedOut || txn.open === exports.TRANSACTION_STATE.CLOSED)
+                continue;
+            txn.renewIdleTimeout();
+        }
+    }
+    getReadTxn(disableSnapshot) {
+        this.readTxnRefCount = (this.readTxnRefCount || 0) + 1;
+        this.renewReadTimeout();
         if (this.transaction) {
             if (this.transaction.openTimer)
                 this.transaction.openTimer = 0;
@@ -434,6 +555,8 @@ class DatabaseTransaction {
     // Monitor state is not ownership state: it stays with `trackedTxns.add` in getReadTxn().
     attachOwnedTransaction(transaction) {
         this.transaction = transaction;
+        readTransactionOwners.set(transaction, this);
+        this.rangeReadActive = false;
         this.readTxnsUsed = 1;
         this.baseReadRefConsumed = false;
         this.handleOpenedAt = performance.now();
@@ -475,6 +598,7 @@ class DatabaseTransaction {
         trackedTxns.delete(this);
         this.endWriteSupervision();
         this.transaction = null;
+        this.rangeReadActive = false;
         this.readTxnsUsed = 0;
         this.readTxnRefCount = 0;
         this.handleOpenedAt = 0;
@@ -576,6 +700,7 @@ class DatabaseTransaction {
         const index = this.writes.indexOf(operation);
         if (index > -1)
             this.writes[index] = null;
+        this.ownedWrites?.delete(operation);
         if (operation.key === undefined)
             return;
         const writesForStore = this.writesByKey?.get(operation.store);
@@ -585,7 +710,7 @@ class DatabaseTransaction {
         // Membership, not `stagedIn`, which every commit handler clears and so cannot tell a takeover from a
         // write done in place; a prior already taken over must not become this transaction's basis again.
         let prior = operation.priorWrite;
-        while (prior && !this.writes.includes(prior))
+        while (prior && !this.ownedWrites?.has(prior))
             prior = prior.priorWrite;
         const tail = writesForStore.get(keyId);
         if (tail === operation) {
@@ -619,10 +744,10 @@ class DatabaseTransaction {
         const h = storeMap.get(keyId);
         if (!h)
             return undefined;
-        if (!h.released)
+        if (!h.isExpired())
             return h;
-        // Prune released handles so they don't accumulate; an expired handle checking re-entrancy
-        // would otherwise be seen as the holder and incorrectly granted access.
+        // Prune released/expired handles so they don't accumulate; a handle past its deadline checking
+        // re-entrancy would otherwise be seen as the holder and incorrectly granted access.
         storeMap.delete(keyId);
         return undefined;
     }
@@ -684,11 +809,19 @@ class DatabaseTransaction {
         // fire after a commit or abort, and routing it back here would revive a write this transaction
         // already rolled back — whose blobs abort() has reclaimed. Cleared here, save() resolves the
         // context's current transaction as it did before `stagedIn` existed.
-        for (const write of this.writes)
+        for (const write of this.writes) {
             if (write?.stagedIn === this)
                 write.stagedIn = undefined;
+            if (write)
+                this.ownedWrites?.delete(write);
+        }
         this.writes = [];
         this.writesByKey = undefined;
+        // The commit-fence latch belongs to the discarded batch. A reused transaction that once staged
+        // a locked write would otherwise re-scan every write of every later unlocked batch. Assigned
+        // only when it was set, so an ordinary transaction never gains the property at all.
+        if (this.hasLeaseProtectedWrite)
+            this.hasLeaseProtectedWrite = false;
     }
     /**
      * Drop this transaction's back-reference from its context once completed (commit or abort),
@@ -811,6 +944,7 @@ class DatabaseTransaction {
         this.writeTick = monitorTick;
         this.linkWrite(operation);
         this.writes.push(operation);
+        (this.ownedWrites ??= new WeakSet()).add(operation);
         operation.stagedIn = this;
         // Hold this write back while any earlier same-key write has not run — out of staging order both
         // diff against the pre-transaction record (harper#2211, DESIGN.md). The whole chain, not just the
@@ -841,16 +975,26 @@ class DatabaseTransaction {
         const lockHandle = operation.lockHandle;
         // Guard: a write staged through an expired or released lock handle must not land.
         // The handle's lease timer already unlocked the native key; another holder may have taken it.
-        if (lockHandle && (lockHandle.expired || lockHandle.released)) {
-            // Remove the operation from the staged set so subsequent writes on this context do not
-            // re-throw 409 due to a stale null-saved entry sitting in this.writes.
-            const failedIdx = this.writes.indexOf(operation);
-            if (failedIdx > -1)
-                this.writes[failedIdx] = null;
+        // isExpired() re-evaluates the deadline here rather than trusting the timer to have run: a
+        // holder whose event loop stalled past its lease would otherwise commit in the window between
+        // the deadline and its own timer callback, after peers had already granted the key onward.
+        //
+        // A RE-save is judged by the lease alone. `released` belongs to the first stage — a caller that
+        // unlocked and then saved is writing through a handle it gave back — but an operation already
+        // staged was staged while the lock was held, and an `unlock()` inside the lease leaves it valid
+        // (the same rule the pre-submit fence applies below). Without the distinction,
+        // `lock(); save(); unlock(); commit()` succeeded normally and threw 409 only when a conflict
+        // retry or an open read iterator forced the replay to re-save it.
+        if (operation.saved ? lockHandle?.isLeaseExpired() : lockHandle?.isExpired()) {
+            // Through `detachWrite`, which also repairs the per-key chain: dropping it from `writes` alone
+            // leaves `writesByKey` pointing at a write that was refused, so a caller that catches this 409
+            // and stages the same key again would take the rejected operation as its merge basis.
+            this.detachWrite(operation);
             throw (0, recordLock_ts_1.lockNotHeldError)(lockHandle);
         }
         // Lock-write timestamp rules.
         if (lockHandle) {
+            this.hasLeaseProtectedWrite = true;
             if (this.open === exports.TRANSACTION_STATE.CLOSED || this.saveCommits) {
                 // CLOSED path (second+ write per ImmediateTransaction cycle) OR the first write in
                 // an ImmediateTransaction (open=OPEN until commit sets it CLOSED, but saveCommits
@@ -910,21 +1054,44 @@ class DatabaseTransaction {
         }
         if (!txnTime)
             txnTime = this.timestamp = transaction.getTimestamp();
+        if (!operation.saved && operation.pendingPriorWrite) {
+            const pendingWrites = [];
+            for (let pending = operation.pendingPriorWrite; pending;) {
+                if (!pending.saved && this.ownedWrites?.has(pending))
+                    pendingWrites.push(pending);
+                pending = pending.pendingPriorWrite !== undefined ? pending.pendingPriorWrite : pending.priorWrite;
+            }
+            for (let index = pendingWrites.length - 1; index >= 0; index--)
+                this.save(pendingWrites[index], transaction, false, options);
+            operation.pendingPriorWrite = null;
+        }
         // `txnTime` is this transaction's timestamp — the key its entries take in the per-origin log.
         // A write applied from elsewhere carries the origin's record version too, and that is what the
         // record is stored at; the two coincide for every locally-originated write. Gated on the apply
         // flags so an ordinary write never reads the property (harper#2412).
         const writeVersion = this.sourceApply || this.isReplay ? getAppliedWriteVersion(operation.recordVersion, txnTime) : txnTime;
-        if (reloadEntry || operation.entry === undefined) {
-            operation.entry = operation.store.getEntry(operation.key, { transaction });
+        // A base that feeds stored state must come from this transaction's snapshot, never the
+        // cross-worker cache vouch (stale when a resequenced write reused a version). That closes the
+        // lost-update window only when this transaction holds a snapshot to validate the later Put
+        // against; a snapshot-free transaction (this.snapshotFree, after a mid-scope-commit rotation)
+        // has no snapshot for rocksdb-js to validate the Put against, so it only narrows the window to
+        // the read-to-put span rather than closing it (open follow-up, tracked in the PR description).
+        // Replays keep their pre-read base — their convergence contract is the replay pass itself.
+        const reloadsCommitBase = operation.reloadCommitBase && !operation.saved && !this.isReplay;
+        if (reloadEntry || operation.entry === undefined || reloadsCommitBase) {
+            const uncachedRead = (!!operation.reloadCommitBase && !this.isReplay) || reloadEntry;
+            operation.entry = operation.store.getEntry(operation.key, { transaction, uncachedRead });
         }
         if (!operation.saved) {
-            operation.saved = true;
             // immediately execute in this transaction
-            if (operation.validate?.(writeVersion, this) === false) {
+            const validated = validateWrite(operation, writeVersion, this);
+            if (validated === false) {
+                operation.saved = true;
                 operation.commit = () => { }; // noop if we try again
+                closeWriteInstance(operation);
                 return;
             }
+            operation.saved = true;
             let result = operation.before?.();
             if (result?.then)
                 this.stageCompletion(result);
@@ -936,7 +1103,13 @@ class DatabaseTransaction {
             operation.trackRecordVersion = true;
         if (operation.trackRecordVersion)
             operation.recordVersionApplied = false;
-        const completion = operation.commit(writeVersion, operation.entry, this.retries > 0, transaction);
+        let completion;
+        try {
+            completion = operation.commit(writeVersion, operation.entry, this.retries > 0, transaction);
+        }
+        finally {
+            closeWriteInstance(operation);
+        }
         if (operation.trackRecordVersion)
             operation.appliedRecordVersion = operation.recordVersionApplied ? writeVersion : undefined;
         if (typeof completion?.then === 'function')
@@ -1013,6 +1186,8 @@ class DatabaseTransaction {
             // and replay branches below deliberately commit a handle other than this.transaction.
             if (!transaction)
                 transaction = this.transaction;
+            if (!options.transaction && this.writes.some((write) => write))
+                this.renewChainForNativeCommit();
             this.open = exports.TRANSACTION_STATE.CLOSED;
             // RocksTransaction.commit() resolves with RETRY_NOW_VALUE (a number) under
             // coordinatedRetry, or void on a normal commit/abort.
@@ -1096,6 +1271,33 @@ class DatabaseTransaction {
                 if (transaction) {
                     this.writes = this.writes.filter((write) => write); // filter out removed entries
                     if (this.writes.length > 0) {
+                        // Commit retries can construct fresh ranges on this live handle after read ownership ends.
+                        readTransactionOwners.delete(transaction);
+                        // Re-fence before submitting: the loop above skips operations already marked saved, so
+                        // save()'s own check cannot see a holder that stalled between staging and commit. The
+                        // retry/replay path re-saves every operation and is fenced there instead. Lease expiry
+                        // only: an unlock() inside the lease leaves the staged write valid, an elapsed lease
+                        // does not, whether or not the caller also unlocked.
+                        for (let i = 0; this.hasLeaseProtectedWrite && i < this.writes.length; i++) {
+                            const lapsed = this.writes[i].lockHandle;
+                            if (!lapsed?.isLeaseExpired())
+                                continue;
+                            try {
+                                transaction.abort();
+                            }
+                            catch { }
+                            // Every other terminal exit from commit() runs the logical cleanup too. Throwing
+                            // straight out would strand the OTHER locks this transaction holds, its staged
+                            // blobs, and the context's back-reference to a CLOSED transaction — and
+                            // transaction()'s onComplete has no rejection path to run it later.
+                            try {
+                                this.abort();
+                            }
+                            catch (error) {
+                                harperLogger.debug?.('cleaning up a transaction whose record lock lapsed', error);
+                            }
+                            throw (0, recordLock_ts_1.lockNotHeldError)(lapsed);
+                        }
                         // The transaction was created with coordinatedRetry:true (see
                         // getReadTxn), so commit() can resolve to RETRY_NOW_VALUE. That
                         // sentinel (a number) is why commitResolution is typed
@@ -1855,6 +2057,10 @@ function startMonitoringTxns() {
         (0, longLivedTransactions_ts_1.finishLongLivedHolderReports)(reportBudget);
     }, txnExpiration).unref();
     function monitorTransaction(txn, checkedCommitPhaseChains, reportThresholdMs, reportNow, reportBudget) {
+        if (txn.rangeReadActive) {
+            txn.rangeReadActive = false;
+            txn.renewReadTimeout();
+        }
         reportIfLongLived(txn, reportThresholdMs, reportNow, reportBudget);
         {
             const commitChainHead = txn.commitChainHead ?? txn;