harper 5.3.2 → 5.3.4

package/resources/record-locks.md

@@ -37,14 +37,24 @@ Consequences that shape the code:
   no-op. The key is `lockAttemptKey(tableId, id)` = `[LOCK_KEY_PREFIX, tableId, ...id]`, distinct from
   `getFromSource`'s bare-id single-flight lock.
 - **`RecordLockHandle`** (`recordLock.ts`) carries `store`, `key`, `keyId`, `acquiredAt`, `expiresAt`,
-  `hold`, `released`, and `expired`. `release()` is synchronous: it sets `released`, clears the lease
-  timer, and calls `store.unlock(key)`. A lease timer sets `expired = true` then calls `store.unlock()`
-  on fire; any write staged through an expired or released handle throws 409 in
-  `DatabaseTransaction.save()` before the write reaches the store — from `lockNotHeldError()`, which
-  names the actual cause, since an expired lease and a handle already released (by `unlock()` or by
-  the commit) send a caller after different bugs. `acquireRecordKey` loops
-  `tryLock` → await wake → retry until acquired or `waitMs` elapsed (then 423). The contender wait
-  timer uses `.unref()` so it does not prevent process exit.
+  `hold`, `released`, and `expired`. `release()` sets `released` and clears the lease timer; a lease
+  timer sets `expired = true` and `released = true` on fire. When no native commit is holding the
+  handle, both immediately call `store.unlock(key)` and emit `onRelease` (and `release()` returns `true`).
+  While a submitted native `RocksTransaction` is in flight (`retainForCommit(holdDeadlineMono)` called at
+  first native submission in `DatabaseTransaction.performCommit()`), `store.unlock(key)` and `onRelease`
+  are deferred (and `release()` returns `false`) until `releaseCommitHold()` releases the last commit
+  hold — at local commit landing (immediately before `releaseRecordLocks()`), in `commitOutcome`'s
+  rejection handler on any unlogged give-up, or at the commit-conflict budget boundary via
+  `noteOverdueLoggedCommit` or the handle's own hold-deadline timer when a native commit never settles
+  (harper#3236) — so a logged commit that retries past its lease cannot be overtaken by a same-node
+  contender or emit an early `LOCK_RELEASE` while within its conflict budget. `isExpired()` flips
+  immediately when the timer fires or `revokeLease()`/`release()` runs (while `isLeaseExpired()` reflects
+  only lease expiry or `revokeLease()`, not `release()`), so any new write staged through an expired or
+  released handle (and any unlogged conflict retry) throws 409 in `DatabaseTransaction.save()` or
+  `performCommit()` — from `lockNotHeldError()`, which names the actual cause, since an expired lease and
+  a handle already released (by `unlock()` or by the commit) send a caller after different bugs.
+  `acquireRecordKey` loops `tryLock` → await wake → retry until acquired or `waitMs` elapsed (then 423).
+  The contender wait timer uses `.unref()` so it does not prevent process exit.
 - **Re-entrancy is per-transaction.** `DatabaseTransaction.recordLocks` is a lazily allocated
   `Map<store, Map<keyId, handle>>` (O(1) lookup). `registerRecordLock`, `recordLockFor`, and
   `unregisterRecordLock` manage it. `lock()` consults it before calling `tryLock`; a re-entrant call
@@ -53,7 +63,8 @@ Consequences that shape the code:
 - **Release.** Every handle — scoped or hold — is registered in `link.recordLocks` and kept on the
   locked instance as `#lockHandle`; every commit or abort calls `releaseRecordLocks()`, which calls
   `handle.release()` on each non-hold handle, so a `{ hold: true }` handle outlives the transaction.
-  `unlock()` calls `handle.release()` directly (synchronous, returns false if already released).
+  `unlock()` calls `handle.release()` directly (synchronous; returns false if already released, or
+  while a commit hold defers the native unlock until the in-flight commit settles).
   `unlock()` also accepts scoped handles: it calls `release()` early and unregisters the handle so the transaction commit does
   not release it again. After any `unlock()` call `#lockWritable` is cleared so writes through the
   instance are no longer accepted. In an explicit transaction with no staged writes and no open
@@ -1066,9 +1077,12 @@ feature that has not yet been measured.
 >
 > **§2's exclusion invariant is wider than what (1) and (2) leave.** It requires a successor to
 > exclude every predecessor capability that can still admit _or commit_; what ships excludes
-> admission, and the commit half holds only up to the pre-submission expiry fence
-> (the `hasLeaseProtectedWrite` fence in `DatabaseTransaction.performCommit()`) — a native commit that clears that fence and settles
-> afterwards is limitation (2)'s third route.
+> admission, and the commit half holds up to the pre-submission expiry fence
+> (the `hasLeaseProtectedWrite` fence in `DatabaseTransaction.performCommit()`) plus, on the local
+> node and for clean recall drain, `KeyLockHandle`'s per-handle commit hold (`retainForCommit()` /
+> `releaseCommitHold()`, harper#3236) up to `commitConflictBudget()` — a native commit that clears the
+> pre-submission fence and settles past `commitConflictBudget()` (or after the home's own monotonic
+> delegation lease expires on a peer) is limitation (2)'s third route.
 >
 > **There is no caller-side mitigation for (2) — the obvious candidate is unreachable and, where it
 > is reachable, makes things worse.** `X-Replicate-To` / `confirm=` is meant to be super-user only —
@@ -1306,11 +1320,14 @@ drain and caps, §§5/6/8, plus the three inherited substrate defects in §11) a
 machine is gone, and the home ring, the delegation table, recall with §6 steps 1, 2 and 4, ordered
 fencing tokens, the caps, the §4.3 restart quarantine, the generation monotonicity floor and the
 transport-swap grant fence are in place, with all three inherited defects fixed. **§6 step 3 —
-settlement — is not implemented**: a recall revokes capability and then writes the release without
-waiting for a native commit already submitted to complete. That is exactly limitation (2)'s third
-route in §10, which the contract already states, so the gap is disclosed rather than hidden — but §6
-must not be read as fully implemented. Closing it means hanging the release hook off
-logical-transaction settlement rather than off the last admission unlocking. harper-pro#822 supplies
+settlement — is bounded by the commit-conflict budget (`retainForCommit(holdDeadlineMono)` /
+`releaseCommitHold()`, harper#3236)**: a submitted native `RocksTransaction` retains a commit hold
+on each write's `KeyLockHandle` until local commit landing (or `commitOutcome` rejection), so
+`revokeLease()` defers `store.unlock(key)` and `onRelease` (`LOCK_RELEASE` emission) while the
+commit is within `commitConflictBudget()`. Past `commitConflictBudget()`, `KeyLockHandle`'s
+`#holdTimer` (as well as `noteOverdueLoggedCommit` between retry attempts) releases the hold so a
+wedged conflict cannot pin the key forever, and a peer's own monotonic delegation lease (§5.2) can
+still expire first — which is limitation (2)'s third route in §10. harper-pro#822 supplies
 the operator-agreed home map and `establishLockFreshness()`; the feature is opt-in
 (`replication.recordLocks: true`). A `lockRelease` that reaches a non-coordinating thread is handed
 to the transport's `relayControlEntry` (harper-pro#977). Without the hook, a thread that has a

package/resources/recordLock.ts

@@ -52,10 +52,11 @@ export interface ResolvedRecordLockOptions {
 
 /**
  * The handle returned by `lock()` and held by each gated write until its transaction completes.
- * `release()` is synchronous: it calls `store.unlock(key)` which is ownerless and fires any
- * waiting callbacks cross-thread. The `expired` flag is set in the holder thread by the lease
- * timer, so a stale holder cannot accidentally call unlock after its lease already fired and
- * released the key to a new holder.
+ * `release()` is synchronous: it calls `store.unlock(key)` (or defers it while a commit hold
+ * acquired via `retainForCommit` is still active), which is ownerless and fires any waiting
+ * callbacks cross-thread. The lease timer sets `expired` in the holder thread when it fires
+ * (while a commit hold is active, only the native unlock is deferred), so a stale holder cannot
+ * accidentally call unlock after its lease already fired and released the key to a new holder.
  */
 export interface RecordLockHandle {
 	store: any;
@@ -107,7 +108,11 @@ export interface RecordLockHandle {
 	 * version has been noted; otherwise advances by the minimum monotonic step from the recorded floor.
 	 */
 	nextHolderVersion(): number;
+	/** True when this call returned the native key; false if already released, or while a commit hold defers the unlock. */
 	release(): boolean;
+	/** Defer `store.unlock(key)` until an in-flight native commit settles or `holdDeadlineMono` expires. */
+	retainForCommit?(holdDeadlineMono?: number): void;
+	releaseCommitHold?(): void;
 	/**
 	 * Flip this handle to hold mode and reset its lease timer. Used during scoped→hold upgrades
 	 * so all instances that reference this handle object remain valid (no retire + replace).
@@ -192,6 +197,10 @@ class KeyLockHandle implements RecordLockHandle {
 	// an NTP step nor a manual clock change can extend a lease past what peers assumed.
 	#deadlineMono: number | undefined;
 	#onRelease: (() => void) | undefined;
+	#commitHolds = 0;
+	#deferredUnlock = false;
+	#holdDeadlineMono: number | undefined;
+	#holdTimer: ReturnType<typeof setTimeout> | undefined;
 
 	constructor(store: any, key: any[], keyId: unknown, lease?: number, hold = false, acquiredAt?: number) {
 		this.store = store;
@@ -238,8 +247,9 @@ class KeyLockHandle implements RecordLockHandle {
 	// bound and the key may belong to someone else.
 	#leaseLapsed(): boolean {
 		if (this.#deadlineMono === undefined || performance.now() < this.#deadlineMono) return false;
-		// Finish the expiry rather than only reporting it: the native key must actually go back so a
-		// stalled holder does not keep a key every participant has already written off.
+		// Finish the expiry rather than only reporting it: once no in-flight commit holds the handle,
+		// the native key must go back so a stalled holder does not keep a key every participant has
+		// already written off.
 		if (!this.released) this.#onLeaseExpire();
 		return true;
 	}
@@ -259,8 +269,8 @@ class KeyLockHandle implements RecordLockHandle {
 		// no-op in the one state it was written for.
 		this.expired = true;
 		if (this.released) {
-			// The native key is already back and `onRelease` already fired; only the fence flag and the
-			// lease timer are left to settle.
+			// `release()` already ran (returning the native key or deferring the unlock onto an active
+			// commit hold); only the fence flag and the lease timer are left to settle.
 			clearTimeout(this.#timer);
 			return;
 		}
@@ -294,22 +304,84 @@ class KeyLockHandle implements RecordLockHandle {
 		return next;
 	}
 
-	#onLeaseExpire() {
-		if (this.released) return;
-		this.released = true;
-		this.expired = true;
-		clearTimeout(this.#timer);
+	retainForCommit(holdDeadlineMono?: number): void {
+		if (this.released && !this.#deferredUnlock) return;
+		this.#commitHolds++;
+		if (holdDeadlineMono !== undefined && Number.isFinite(holdDeadlineMono)) {
+			this.#holdDeadlineMono = Math.max(this.#holdDeadlineMono ?? holdDeadlineMono, holdDeadlineMono);
+			if (this.#deferredUnlock) this.#armHoldTimer();
+		}
+	}
+
+	releaseCommitHold(): void {
+		if (this.#commitHolds <= 0) return;
+		if (--this.#commitHolds === 0) {
+			clearTimeout(this.#holdTimer);
+			this.#holdTimer = undefined;
+			this.#holdDeadlineMono = undefined;
+			if (this.#deferredUnlock) {
+				this.#deferredUnlock = false;
+				this.#unlockAndEmitRelease('record lock deferred release failed (store may have been dropped)');
+			}
+		}
+	}
+
+	// True when the native key went back now; false when the unlock waits on the commit hold.
+	#deferOrFlushUnlock(warningMessage: string): boolean {
+		if (this.#holdDeadlineMono !== undefined && performance.now() >= this.#holdDeadlineMono) {
+			this.#commitHolds = 0;
+			this.#deferredUnlock = false;
+			this.#holdDeadlineMono = undefined;
+			clearTimeout(this.#holdTimer);
+			this.#holdTimer = undefined;
+			this.#unlockAndEmitRelease(warningMessage);
+			return true;
+		}
+		this.#deferredUnlock = true;
+		this.#armHoldTimer();
+		return false;
+	}
+
+	#armHoldTimer() {
+		clearTimeout(this.#holdTimer);
+		this.#holdTimer = undefined;
+		if (!this.#deferredUnlock || this.#holdDeadlineMono === undefined) return;
+		const remaining = Math.max(0, Math.ceil(this.#holdDeadlineMono - performance.now()));
+		this.#holdTimer = setTimeout(() => {
+			this.#holdTimer = undefined;
+			this.#commitHolds = 0;
+			this.#holdDeadlineMono = undefined;
+			if (this.#deferredUnlock) {
+				this.#deferredUnlock = false;
+				this.#unlockAndEmitRelease('record lock commit hold timer failed (store may have been dropped)');
+			}
+		}, remaining).unref();
+	}
+
+	#unlockAndEmitRelease(warningMessage: string) {
 		try {
 			this.store.unlock(this.key);
 		} catch (err) {
 			if (!warnedLeaseTimerStores.has(this.store)) {
 				warnedLeaseTimerStores.add(this.store);
-				harperLogger.warn?.('record lock lease timer failed (store may have been dropped)', err);
+				harperLogger.warn?.(warningMessage, err);
 			}
 		}
 		this.#emitRelease();
 	}
 
+	#onLeaseExpire() {
+		if (this.released) return;
+		this.released = true;
+		this.expired = true;
+		clearTimeout(this.#timer);
+		if (this.#commitHolds > 0) {
+			this.#deferOrFlushUnlock('record lock lease timer failed (store may have been dropped)');
+			return;
+		}
+		this.#unlockAndEmitRelease('record lock lease timer failed (store may have been dropped)');
+	}
+
 	// The cluster release is a durability optimization, not the safety mechanism — peers expire the
 	// hold on their own lease bound — so neither a throw nor a rejected promise may escape here. This
 	// runs from a lease timer and from post-commit cleanup, where an escaping rejection would take
@@ -331,15 +403,10 @@ class KeyLockHandle implements RecordLockHandle {
 		if (this.released) return false;
 		this.released = true;
 		clearTimeout(this.#timer);
-		try {
-			this.store.unlock(this.key);
-		} catch (err) {
-			if (!warnedLeaseTimerStores.has(this.store)) {
-				warnedLeaseTimerStores.add(this.store);
-				harperLogger.warn?.('record lock release failed (store may have been dropped)', err);
-			}
+		if (this.#commitHolds > 0) {
+			return this.#deferOrFlushUnlock('record lock release failed (store may have been dropped)');
 		}
-		this.#emitRelease();
+		this.#unlockAndEmitRelease('record lock release failed (store may have been dropped)');
 		return true;
 	}
 

package/server/DESIGN.md

@@ -73,6 +73,11 @@ A request entering `http.ts` does **not** go through Fastify unless no Harper ha
 > all. Only mutating an object _without_ changing its version can serve stale bytes, and that is
 > indistinguishable from re-sending the same message.
 
+> **Pass-through payloads are `Buffer | string`.** A message that carries its own `{ contentType, data }`
+> is delivered as its `data`, but binary data leaves `serializeMessage` as a `Buffer`: on a worker other
+> than the publisher's, the record is decoded from the transaction log and `data` is a plain `Uint8Array`,
+> which mqtt-packet cannot encode. Pinned by `integrationTests/mqtt/opaque-payload-across-workers.test.ts`.
+
 ### Threads
 
 | File                       | Purpose                                                                                                                                                                           |
@@ -353,11 +358,13 @@ The `@table(cacheControl:)` value is persisted on the primary-key attribute (lik
 
 A persisted QoS 1/2 entry is `{ qos, topic, startTime, databaseGeneration? }`, and the record carries the `incarnation` of the connection that owns it (harper#2448). A QoS 0 entry is `{ qos, topic }`: it is session state with no position, resumed live with retain handling 2 and no acknowledgement tracking.
 
-- **Positions are certified, never clocks.** A new subscription starts at its registration watermark (`registeredThrough`), bound to the database generation when one exists, and otherwise at `getNextMonotonicTime()` unbound until the first certified position replaces it. A SUBSCRIBE that replaces a QoS 1/2 topic's subscription continues that topic's position through the checked replay, since replacing must lose nothing; a pruned-history refusal there resets the session as it would at reconnect. A topic's position is `min(subscription.progress(), previousKey of its oldest unacknowledged delivery)`; a transaction's messages share a key, so one unacked message holds the position before its whole transaction, and while a message is still queued the position stays before the last delivered transaction, which that message may share. Live events arrive in commit order, and a RocksDB transaction takes its key before it commits, so a transaction can arrive after a higher key. Its previousKey is then the position just below its own key, and while such a late delivery is unacknowledged the position takes the lowest previousKey of all of them rather than the oldest's (harper#3101). Scan deliveries (`fromScan`) stay out of this ordering: they are retained state, which a resumed session does not resend.
+- **Positions are certified, never clocks.** A new subscription starts at its registration watermark (`registeredThrough`), bound to the database generation when one exists, and otherwise at `getNextMonotonicTime()` unbound until the first certified position replaces it. A SUBSCRIBE that replaces a QoS 1/2 topic's subscription continues that topic's position through the checked replay, since replacing must lose nothing; a pruned-history refusal there resets the session as it would at reconnect. A topic's position is `min(subscription.progress(), previousKey of its oldest unacknowledged delivery)`; a transaction's messages share a key, so one unacked message holds the position before its whole transaction, and while a message is still queued the position stays before the last delivered transaction, which that message may share. Live events arrive in commit order, and a RocksDB transaction takes its key before it commits, so a transaction can arrive after a higher key. Its previousKey is then the position just below its own key, and while such a late delivery is unacknowledged the position takes the lowest previousKey of all of them rather than the oldest's (harper#3101). Scan deliveries (`fromScan`) stay out of this ordering: they are retained state, which a resumed session does not resend: `resumeTopics` subscribes with retain handling 2 (`addSubscription` omits current values for that or an explicit `omitCurrent`), since a record topic whose saved position covers its current version would otherwise send that version again.
 - **Checkpoints:** coalesced after acknowledgements, on an unref'd timer (`min(auditRetention / 10, 1h)`), and at disconnect, where positions are taken before subscriptions end because `close()` clears a queue and would read as idle. Nothing past a resumed position is saved until that subscription's `resumeVerified` resolves true. Out-of-order acks are not persisted: a partly acked transaction is redelivered. Legacy `acks` lists are ignored.
 - **Before CONNACK,** a collection entry bound to its database's current generation is checked against the floor (a record entry's own walk decides after CONNACK); a failure deletes the record and reports the session as not present. The connection then writes its incarnation (`takeOver`), and every later write first checks the stored incarnation: a connection that finds another's stops writing and closes (0x8E), and one resumed from a record never creates one. Any newer authenticated connection for the client id on the same thread, a clean start included, closes the older durable connection the same way before it reads or deletes the record, once that connection has saved its positions, and waits for that save to settle; a connection that has already closed counts until its last save settles. A save that failed leaves the record at the last one that landed, so the newer connection resumes from there and may redeliver, never skip. Simultaneous CONNECTs for one client id take their turn through a per-thread claim, so each sees the one before it; one that gives up waiting keeps its place until the one before it finishes. The CONNECT's pending session is assigned before it waits, so packets sent right behind the CONNECT wait with it rather than being refused; the wait is bounded (10 s, then CONNACK 0x88, or 0x03 on v3.1.1), and a CONNECT whose client closes while it waits takes nothing over. A session that has ended, by a disconnect or by yielding to a takeover, saves nothing after its final save, so a SUBSCRIBE still in flight cannot write over the record a newer connection claimed.
 - **Subscription changes are serial.** Packets are handled concurrently, so a durable session applies SUBSCRIBE, UNSUBSCRIBE and `resume()` one at a time: a topic's state belongs to one subscription. A SUBSCRIBE of any QoS is saved before SUBACK. A failed SUBSCRIBE leaves its topic unsubscribed and saves that. It ends the subscription it started, and drops the state of the one it replaced, which replacing ended. An UNSUBSCRIBE whose save fails is reported failed again on a retry until the removal is saved, and any failed save starts the checkpoint timer, so a session with only QoS 0 topics retries it too.
+- **A delivery that cannot be sent ends the connection, not just the session.** The listener's `catch` in `mqtt.ts` aborts the transport (`destroy`/`terminate`, as for a parse error) and `onClose` ends the session, so the client sees the drop and reconnects. Ending only the session, as before, left the client connected and receiving nothing. An abort rather than a graceful end, because teardown on a graceful TCP end waits for the peer to close its side. A delivery that fails every time therefore repeats on each reconnect (a durable QoS≥1 session replays the unacknowledged message).
 - **Wills are kept per connection,** keyed `[clientId, incarnation]`: a connection closing after a takeover publishes and deletes only its own will (MQTT 5 §3.1.4 publishes a taken-over client's will), never the will of the connection that replaced it.
+- **Only a will's publish is authorized** (`settleWill`, harper#1874). The `hdb_session_will` row is the session's bookkeeping: it is read and deleted on contexts of its own, not the session's `authorize: true` context, which spends its one-shot check on the first call (roles are not granted system tables, so a non-super user's will never published and its row leaked). The publish then runs on a fresh session context, as the connection's user or a scoped will's embedded role, and the row is deleted after any outcome, a refused or failed publish included, so a will that fails for a transient reason is lost: the boot sweep, the only retry path, would replay a kept row only at the next restart, with no liveness check (harper#3034). The publish commits before the delete, so a crash between them leaves the row for that sweep and the will may be published twice (by design; untested). `unitTests/server/sessionWill.test.js` and `integrationTests/mqtt/will-authorization.test.ts` enforce that only the publish is authorized and that the row is deleted after a publish, a refusal and a clean DISCONNECT.
 - **One terminal path** (`subscriptionFailed`): a refused resume subscribe, a final `Error` value (observed through the subscription's `close` as well as the consumer loop, which may be parked on socket back-pressure), or an iterator failure. Only a 410 (pruned history) discards the session — writers fenced, siblings ended, a v5 DISCONNECT (0x83, the client-error message when problem information is allowed) and a socket close that never waits on storage, then a deletion only if the record still carries this incarnation. Anything else, a 409 from a restored or copied database included, saves positions and closes the connection so the client resumes.
 - **Only the current generation is checked.** A position bound to another generation, another node's (`hdb_durable_session` replicates, and each node mints its own generations) or this database's before a restore or copy, resumes best-effort: it is not checked before CONNACK, replays unchecked from where it is, and binds again at the first certified position. Until a live write gives it a watermark, that replay saves no position, so a reconnect on a quiet database replays it again.
 - **Not covered:** concurrent connections for one client id on different threads, together with crash replay of a failed conditional write (harper#2940); late commits below a saved position, including a late transaction still queued behind the message being sent, which the session cannot see (harper#2928); a replay from another generation, which is unchecked.
@@ -647,6 +654,7 @@ The SQL and job paths are additive rather than exclusive: `verifyPermsAST` valid
 - **Headers commit exactly once, through `this.writeHead`.** `write()`, `end()`, `flushHeaders()` and `_implicitHeader()` all reach `this.writeHead(this.statusCode)` by property lookup, so a `writeHead` that `on-headers` replaced on the instance runs its listeners (the ones that set `Content-Encoding` and remove `Content-Length`) before the promise resolves. After commit, `setHeader`/`appendHeader`/`removeHeader` and a second `writeHead` throw `ERR_HTTP_HEADERS_SENT` as Node's do; `_header` (which `compression` ≤ 1.7 tests instead of `headersSent`) and `finished` (which `on-finished` tests) derive from that state.
 - **The adapter owns the `'error'` listener.** A `destroy(err)` right after `writeHead()` emits before the awaiting caller can attach one; the error stays in the stream's `errored` state for `pipeline()`, `finished()` or async iteration. Client disconnect (`Request.signal`) destroys the response without an error after headers (a plain premature close, which `pipeBodyToResponse` treats as routine) and rejects the promise with the abort reason before them; a handler that throws or rejects before ending the response destroys it, and one that fails after `end()` is logged at warn.
 - **Header names are case-insensitive on removal too.** `Headers.delete` lowercases like `set`/`get`/`has`; the inherited `Map.delete` silently left `send`'s `Content-Length` on a gzip body (truncated transfers).
+- **Every piped chunk reaches `write()` by property lookup.** Node 26.11's `Readable.pipe` fast path (nodejs/node#66182) calls `_write()` directly when pipe's listener is a byte-mode source's only `'data'` listener, so `compression`'s instance patch of `res.write` was skipped for most chunks of `send(...).pipe(res)`: raw bytes inside the gzip stream, or a stall once `compression` had routed pipe's `'drain'` to its idle zlib stream. On runtimes that have the fast path (`'writeKnownBuffer' in Writable`, a static it added) the response adds an inert `'data'` listener to each byte-mode core `Readable` on `'pipe'`, which fails the fast path's single-listener check, and removes it on `'unpipe'` through a listener prepended in the constructor: pipe's own cleanup resumes a source awaiting `'drain'` while any `'data'` listener remains, which would leave an unpiped source flowing into nothing. Object-mode and decoded sources, and legacy `Stream.prototype.pipe` (which never emits `'unpipe'`), are skipped. Remove it once every supported Node 26 release dispatches pipe through an overridden `write()`.
 - **Express is not a target.** `express`'s `app.handle()` replaces the response's prototype with one rooted at `http.ServerResponse.prototype`, which no Writable-derived response survives, and would do the same to the request `Proxy`'s target, Harper's real `IncomingMessage`. Middleware that duck-types the response (Next.js, `compression`, `send`, `serve-static`, `finalhandler`, h3, fastify) is the supported surface.
 
 ## `manageThreads` has two different `workerCount`s (`server/threads/manageThreads.js`)

package/server/DurableSubscriptionsSession.ts

@@ -254,13 +254,13 @@ class SubscriptionsSession {
 		if (path.indexOf('.') > -1) throw new Error('Dots are not allowed in topic names');
 		// might be faster to somehow modify existing subscription and re-get the retained record, but this should work for now
 		const existingSubscription = this.subscriptions.find((subscription) => subscription.topic === topic);
-		let omitCurrent;
+		let omitCurrent = subscriptionRequest.omitCurrent === true;
 		if (existingSubscription) {
-			omitCurrent = retainHandling > 0;
+			omitCurrent ||= retainHandling > 0;
 			existingSubscription.end();
 			this.subscriptions.splice(this.subscriptions.indexOf(existingSubscription), 1);
 		} else {
-			omitCurrent = retainHandling === 2;
+			omitCurrent ||= retainHandling === 2;
 		}
 		if (startTime) trace('Resuming subscription from', topic, 'from', startTime);
 		const entry = resources.getMatch(path, 'mqtt');
@@ -484,22 +484,7 @@ class SubscriptionsSession {
 		const willId = this.willId;
 		this.willId = undefined;
 		if (willId) {
-			const context = this.createContext();
-			transaction(context, async () => {
-				try {
-					if (!clientTerminated) {
-						const will = await getLastWill().get(willId);
-						if (will && !isWillFromExpiredScopedToken(will)) {
-							// A scoped will authorizes under its own embedded role, never the disconnecting
-							// session's user (which may be a later same-clientId reconnect).
-							const willContext = will.user?._scopedToken ? { ...context, user: will.user } : context;
-							await publishMessage(will, will.data, willContext);
-						}
-					}
-				} finally {
-					await getLastWill().delete(willId);
-				}
-			}).catch((error) => {
+			this.settleWill(willId, !clientTerminated).catch((error) => {
 				warn(`Error publishing MQTT will for ${this.sessionId}`, error);
 			});
 		}
@@ -509,6 +494,23 @@ class SubscriptionsSession {
 		}
 		this.subscriptions = [];
 	}
+	/** The will row is session bookkeeping on contexts of its own; only the publish runs as the session (server/DESIGN.md). */
+	async settleWill(willId: [string, string], publish: boolean) {
+		try {
+			if (publish) {
+				const will = await getLastWill().get(willId, {});
+				if (will && !isWillFromExpiredScopedToken(will)) {
+					const context = this.createContext();
+					// A scoped will authorizes under its own embedded role, never the disconnecting
+					// session's user (which may be a later same-clientId reconnect).
+					if (will.user?._scopedToken) context.user = will.user;
+					await publishMessage(will, will.data, context);
+				}
+			}
+		} finally {
+			await getLastWill().delete(willId, {});
+		}
+	}
 	receivedPacket() {
 		if (this.keepalive) {
 			clearTimeout(this.keepaliveTimer);
@@ -670,11 +672,8 @@ export class DurableSubscriptionsSession extends SubscriptionsSession {
 			const { qos, topic, startTime, databaseGeneration } = state.entry;
 			const durable = qos > 0;
 			try {
-				// retain handling, not omitCurrent, decides whether a subscription starts with current values
 				await this.resumeSubscription(
-					durable
-						? { omitCurrent: true, topic, qos, startTime, databaseGeneration, reportProgress: true }
-						: { topic, qos, rh: 2 },
+					durable ? { topic, qos, rh: 2, startTime, databaseGeneration, reportProgress: true } : { topic, qos, rh: 2 },
 					durable
 				);
 			} catch (error) {

package/server/mqtt.ts

@@ -206,6 +206,19 @@ const SERVER_SHUTTING_DOWN = 0x8b; // MQTT v5 DISCONNECT reason code
 const REASON_STRING_LIMIT = 256; // bytes
 /** Fixed header, message id and reason code, plus the property identifier and its length prefix. */
 const ACK_PACKET_OVERHEAD = 16;
+/** `AccessViolation` is 401 for a request with no user and 403 for a user lacking permission; an MQTT client sees both as "Not authorized". */
+const isNotAuthorized = (error: any) => error?.statusCode === 401 || error?.statusCode === 403;
+/** Only failures this layer maps to a code of their own are safe to describe: any other carries an internal message. */
+const hasClientSafeMessage = (error: any) => isNotAuthorized(error) || error?.statusCode === 404;
+/** REASON_STRING_LIMIT counts encoded bytes, and a character must not be cut in half. */
+function boundedReasonString(message: unknown): string {
+	const text = String(message);
+	if (Buffer.byteLength(text) <= REASON_STRING_LIMIT) return text;
+	const bytes = Buffer.from(text, 'utf8');
+	let end = REASON_STRING_LIMIT;
+	while (end > 0 && (bytes[end] & 0xc0) === 0x80) end--;
+	return bytes.subarray(0, end).toString('utf8');
+}
 
 /**
  * Every live MQTT connection on this worker, so a shutdown can announce itself: a bare socket close
@@ -316,6 +329,8 @@ function onSocket(socket, send, request, user, mqttSettings) {
 		}
 	}
 	let disconnected;
+	// set by a failed delivery, so sibling subscriptions stop writing before the aborted socket's 'close' arrives
+	let aborted = false;
 	numberOfConnections++;
 	const connection = {
 		protocolVersion: () => mqttOptions.protocolVersion,
@@ -327,17 +342,14 @@ function onSocket(socket, send, request, user, mqttSettings) {
 	function closeConnection(error?: Error) {
 		try {
 			if (mqttOptions.protocolVersion >= 5) {
-				const packet: any = { cmd: 'disconnect', reasonCode: error ? 0x83 : 0x8e };
+				const packet: any = { cmd: 'disconnect', reasonCode: error ? (isNotAuthorized(error) ? 0x87 : 0x83) : 0x8e };
 				// as for PUBACK: only failures this layer describes itself are safe to hand a client
 				const describable =
 					error instanceof DatabaseGenerationChangedError ||
 					error instanceof ResumeHistoryUnavailableError ||
-					(error as any)?.statusCode === 403 ||
-					(error as any)?.statusCode === 404;
+					hasClientSafeMessage(error);
 				const reasonString =
-					describable && error.message && sendProblemInformation
-						? Buffer.from(String(error.message), 'utf8').subarray(0, REASON_STRING_LIMIT).toString('utf8')
-						: undefined;
+					describable && error.message && sendProblemInformation ? boundedReasonString(error.message) : undefined;
 				if (
 					reasonString &&
 					(!maximumPacketSize || maximumPacketSize >= Buffer.byteLength(reasonString) + ACK_PACKET_OVERHEAD)
@@ -547,7 +559,14 @@ function onSocket(socket, send, request, user, mqttSettings) {
 					});
 					const listener = async (topic, message, messageId, subscription, version) => {
 						try {
-							if (disconnected) throw new Error('Session disconnected while trying to send message to', topic);
+							if (disconnected || aborted) {
+								// a delivery already past the subscription when the client left or a failed delivery aborted
+								// the connection; onClose ends the session
+								mqttLog.debug?.(
+									`Session ${session?.sessionId} ${aborted ? 'aborted' : 'disconnected'} while trying to send message to ${topic}`
+								);
+								return false;
+							}
 							const slashIndex = topic.indexOf('/', 1);
 							const generalTopic = slashIndex > 0 ? topic.slice(0, slashIndex) : topic;
 							const qos = subscription.qos || 0;
@@ -555,11 +574,12 @@ function onSocket(socket, send, request, user, mqttSettings) {
 							// payload is encoded once per (message, content type) and reused across all of them.
 							const encoding = getSharedMessageEncoding(message, request, version);
 							const encoded = encoding.payload;
+							let payload: Buffer | string;
 							// only pay for a microtask when the serialization is genuinely still pending
-							const payload =
-								typeof (encoded as any)?.then === 'function'
-									? await resolveSharedPayload(encoding, message, request, version)
-									: (encoded as Buffer | string);
+							if (typeof (encoded as any)?.then === 'function') {
+								payload = await resolveSharedPayload(encoding, message, request, version);
+								if (disconnected || aborted) return false;
+							} else payload = encoded as Buffer | string;
 							if (qos > 0) {
 								// mqtt-packet requires a numeric message identifier once qos is non-zero
 								const packetData: any = {
@@ -595,9 +615,11 @@ function onSocket(socket, send, request, user, mqttSettings) {
 							return !rawSocket.closed;
 						} catch (error) {
 							mqttLog.error?.(error);
-							session?.disconnect(false);
-							mqttSettings.sessions.delete(session);
-							releaseClientSession(session);
+							// Ending only the session would leave the client connected and receiving nothing. An abort,
+							// unlike a graceful end, closes without waiting on the peer, and onClose ends the session.
+							aborted = true;
+							if (socket.destroy) socket.destroy();
+							else socket.terminate();
 							return false;
 						}
 					};
@@ -606,6 +628,8 @@ function onSocket(socket, send, request, user, mqttSettings) {
 					break;
 				case 'subscribe':
 					const granted = [];
+					// a SUBACK carries one reason string for the whole packet, so the first refusal's is the one sent
+					let refusalMessage: string | undefined;
 					for (const subscription of packet.subscriptions) {
 						let grantedQos;
 						try {
@@ -624,21 +648,27 @@ function onSocket(socket, send, request, user, mqttSettings) {
 							grantedQos =
 								mqttOptions.protocolVersion < 5
 									? 0x80 // the only error code in v3.1.1
-									: error.statusCode === 403
+									: isNotAuthorized(error)
 										? 0x87 // unauthorized
 										: error.statusCode === 404
 											? 0x8f // invalid topic
 											: 0x80; // generic failure
+							if (mqttOptions.protocolVersion >= 5 && error.message && hasClientSafeMessage(error))
+								refusalMessage ??= error.message;
 						}
 						granted.push(grantedQos);
 					}
 					await session.committed;
-					generateAndSendPacket({
-						// Send a subscription acknowledgment
-						cmd: 'suback',
-						granted,
-						messageId: packet.messageId,
-					});
+					const subackPacket: any = { cmd: 'suback', granted, messageId: packet.messageId };
+					if (refusalMessage !== undefined && sendProblemInformation)
+						subackPacket.properties = { reasonString: boundedReasonString(refusalMessage) };
+					let suback = generate(subackPacket, mqttOptions);
+					// the result vector grows with the filter count, so only the encoded packet says whether the string fits
+					if (subackPacket.properties && maximumPacketSize && suback.length > maximumPacketSize) {
+						delete subackPacket.properties;
+						suback = generate(subackPacket, mqttOptions);
+					}
+					sendPacket(suback, 'suback');
 					break;
 				case 'unsubscribe': {
 					const granted = [];
@@ -691,23 +721,18 @@ function onSocket(socket, send, request, user, mqttSettings) {
 								reasonCode:
 									mqttOptions.protocolVersion < 5
 										? 0x80 // the only error code in v3.1.1
-										: error?.statusCode === 403
+										: isNotAuthorized(error)
 											? 0x87 // not authorized
 											: error?.statusCode === 404
 												? 0x90 // topic name invalid
 												: 0x80, // unspecified error
 							};
-							// Only errors this layer maps to a code of their own are safe to describe: any other
-							// failure carries an internal message that a client must not be handed. Both limits
-							// are in encoded bytes, so measure and trim the string in bytes too.
 							const describable =
 								mqttOptions.protocolVersion >= 5 &&
 								sendProblemInformation &&
 								error?.message &&
-								(error.statusCode === 403 || error.statusCode === 404);
-							const reasonString = describable
-								? Buffer.from(String(error.message), 'utf8').subarray(0, REASON_STRING_LIMIT).toString('utf8')
-								: undefined;
+								hasClientSafeMessage(error);
+							const reasonString = describable ? boundedReasonString(error.message) : undefined;
 							if (
 								reasonString &&
 								(!maximumPacketSize || maximumPacketSize >= Buffer.byteLength(reasonString) + ACK_PACKET_OVERHEAD)

package/server/serverHelpers/NodeAdapterResponse.ts

@@ -6,7 +6,7 @@ import type {
 	ServerResponse as NodeServerResponse,
 } from 'node:http';
 import type { Socket } from 'node:net';
-import { PassThrough } from 'node:stream';
+import { PassThrough, Readable, Writable } from 'node:stream';
 import { Headers as ResponseHeaders, applyWriteHeadHeaders } from './Headers.ts';
 
 export interface AdaptedResponse {
@@ -29,6 +29,20 @@ class UnsupportedResponseMethodError extends Error {
 }
 
 const ignoreError = () => {};
+const ignoreChunk = () => {};
+
+// Node 26.11's pipe fast path (nodejs/node#66182) skips write() overrides such as compression's while pipe's listener
+// is a byte-mode source's only 'data' listener; see server/DESIGN.md
+const pipeSkipsWrite = 'writeKnownBuffer' in Writable;
+function guardPipeSource(source: Readable) {
+	// object mode, a decoder, and legacy or userland pipe() never take the fast path; legacy pipe() never emits 'unpipe'
+	if (source instanceof Readable && !source.readableObjectMode && !source.readableEncoding)
+		source.on('data', ignoreChunk);
+}
+// must run before pipe's own unpipe cleanup, which resumes a source awaiting 'drain' while any 'data' listener remains
+function releasePipeSource(source: unknown) {
+	if (source instanceof Readable) source.removeListener('data', ignoreChunk);
+}
 
 export class NodeAdapterResponse extends PassThrough implements NodeServerResponse {
 	statusCode = 200;
@@ -60,6 +74,10 @@ export class NodeAdapterResponse extends PassThrough implements NodeServerRespon
 		this.#resolve = resolve;
 		this.#reject = reject;
 		this.on('error', ignoreError);
+		if (pipeSkipsWrite) {
+			this.on('pipe', guardPipeSource);
+			this.prependListener('unpipe', releasePipeSource);
+		}
 		if (typeof nodeResponse?.on === 'function') {
 			const forward = (...args: any[]) => this.emit('timeout', ...args);
 			let forwarding = false;

package/server/serverHelpers/contentTypes.ts

@@ -536,7 +536,14 @@ export function serializeMessage(
 	request?: Request,
 	inAsyncContinuation?: boolean
 ): Buffer | string | Promise<Buffer | string> {
-	if (message?.contentType != null && message.data != null) return message.data;
+	if (message?.contentType != null && message.data != null) {
+		const data = message.data;
+		// a record read on another thread decodes binary as a plain Uint8Array view, which protocol
+		// encoders (mqtt-packet) reject; wrap the same bytes rather than copy them
+		return ArrayBuffer.isView(data) && !Buffer.isBuffer(data)
+			? Buffer.from(data.buffer, data.byteOffset, data.byteLength)
+			: data;
+	}
 	asyncSerializations = inAsyncContinuation ? undefined : [];
 	try {
 		const serialized: Buffer | string = getMessageSerializer(request)(message);

package/server/serverHelpers/sharedMessageEncoding.ts

@@ -162,8 +162,9 @@ function fill(encoding: SharedMessageEncoding, message: any, request: any) {
 	const payload = serializeMessage(message, request);
 	encoding.payload = payload;
 	encoding.failed = false;
-	// A pass-through payload IS the message's own data, already reachable from the WeakMap key, so
-	// caching it retains nothing extra and must not be billed against the budget.
+	// A pass-through payload IS the message's own data (or a Buffer over the same memory), already
+	// reachable from the WeakMap key, so caching it retains nothing extra and must not be billed
+	// against the budget.
 	if (encoding.serializer === PASS_THROUGH) return;
 	if (typeof (payload as any)?.then === 'function')
 		// collapse an async serialization in place so later subscribers, and frame sharing, see the