@zlink-systems/framework 0.30.1 → 0.30.2

package/dist/runtime/backend/mesh-dispatch-pump.d.ts

@@ -20,7 +20,6 @@ export interface ZLinkMeshDispatchFailureContext {
 export declare class ZLinkMeshDispatchPump {
     private readonly node;
     private readonly options;
-    private readonly dispatchOwnedRecord;
     private pendingDomains;
     private infrastructureScheduled;
     private disposed;
@@ -30,15 +29,28 @@ export declare class ZLinkMeshDispatchPump {
     private readonly capacityStop;
     private recordsSinceYield;
     private yieldStartedAtMs;
+    /** Drains in progress; the batch budget begins when work starts on an idle pump. */
+    private draining;
+    /** The macrotask boundary every drain waits for once the shared budget is spent. */
+    private pendingYield?;
     constructor(node: ZLinkBackendMeshNode, options: ZLinkMeshDispatchPumpOptions);
     start(): void;
-    dispose(): Promise<void>;
+    dispose(signal?: AbortSignal): Promise<void>;
     private markReady;
     private wakeApplicationWorker;
     private startApplicationWorker;
     private runApplicationWorker;
     private waitForApplicationReady;
+    /**
+     * Starts one record in this worker's turn; a permit's scope covers the
+     * synchronous dispatch. Returns `false` when the dispatch threw (already
+     * reported), `true` when it returned synchronously, or the handler's pending
+     * completion, which the draining turn awaits itself before
+     * {@link finishRecord}.
+     */
     private dispatchRecord;
+    private failRecord;
+    /** Runs the record's terminal completion, then releases its permit turn. */
     private finishRecord;
     private reportDispatchError;
     /**
@@ -51,6 +63,18 @@ export declare class ZLinkMeshDispatchPump {
     private scheduleInfrastructure;
     private drainInfrastructure;
     private drainDomain;
+    /**
+     * Time the pump spent idle is not batch work: when work starts on an idle
+     * pump, its batch budget starts with it (spec 08 §6).
+     */
+    private beginDrain;
+    /** Drains one claimed owner in this worker's turn, in claim order. */
+    private drainClaim;
+    /**
+     * The batch budget is shared by every drain of this pump, so once it is
+     * spent every drain waits for the same macrotask boundary; one drain that
+     * keeps running would otherwise hold the event loop the yield was for.
+     */
     private yieldIfNeeded;
     private nowMs;
     private acquirePermit;

package/dist/runtime/backend/mesh-dispatch-pump.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkMeshDispatchPump = void 0;
 const node_async_hooks_1 = require("node:async_hooks");
+const abort_1 = require("../abort");
 const node_os_1 = require("node:os");
 const application_job_queue_scope_1 = require("../application-jobs/application-job-queue-scope");
 const execution_1 = require("../execution");
@@ -24,7 +25,6 @@ const detachedMeshDispatchScope = node_async_hooks_1.AsyncLocalStorage.snapshot(
 class ZLinkMeshDispatchPump {
     node;
     options;
-    dispatchOwnedRecord = this.dispatchRecord.bind(this);
     pendingDomains = service_runtime_contracts_1.ReadyDomain.None;
     infrastructureScheduled = false;
     disposed = false;
@@ -34,6 +34,10 @@ class ZLinkMeshDispatchPump {
     capacityStop = new AbortController();
     recordsSinceYield = 0;
     yieldStartedAtMs = 0;
+    /** Drains in progress; the batch budget begins when work starts on an idle pump. */
+    draining = 0;
+    /** The macrotask boundary every drain waits for once the shared budget is spent. */
+    pendingYield;
     constructor(node, options) {
         this.node = node;
         this.options = options;
@@ -49,7 +53,7 @@ class ZLinkMeshDispatchPump {
             return domains;
         });
     }
-    async dispose() {
+    async dispose(signal) {
         if (this.disposed) {
             return;
         }
@@ -60,7 +64,7 @@ class ZLinkMeshDispatchPump {
             wake();
         this.idleApplicationWorkers.clear();
         while (this.activeDrains.size > 0) {
-            await Promise.all([...this.activeDrains]);
+            await (0, abort_1.awaitWithAbort)(Promise.all([...this.activeDrains]), signal);
         }
     }
     markReady(domains) {
@@ -117,14 +121,37 @@ class ZLinkMeshDispatchPump {
         try {
             for (;;) {
                 await this.waitForApplicationReady();
-                if (this.disposed)
-                    return;
+                this.beginDrain();
                 try {
-                    await this.drainDomain(service_runtime_contracts_1.ReadyDomain.Application, readyBatch, receiveBatch);
+                    while (!this.disposed) {
+                        readyBatch.reset();
+                        const drained = this.node.drainReady(service_runtime_contracts_1.ReadyDomain.Application, readyBatch, runtime_values_1.ZLINK_BACKEND_RECV_DONT_WAIT);
+                        if (!drained.ok || drained.records.length === 0)
+                            break;
+                        if (drained.hasResidue)
+                            this.markReady(service_runtime_contracts_1.ReadyDomain.Application);
+                        for (let index = 0; index < drained.records.length; index += 1) {
+                            const claim = readyBatch.takeClaim(index);
+                            // Raw ingress already attached one host permit to each record.
+                            // A claim reserving admission may receive only that permit's record.
+                            await this.drainClaim(service_runtime_contracts_1.ReadyDomain.Application, drained.records[index], claim, receiveBatch);
+                        }
+                        // Empty ready claims count toward the shared pump budget too.
+                        this.recordsSinceYield += 1;
+                        const yieldTurn = this.yieldIfNeeded();
+                        if (yieldTurn !== undefined)
+                            await yieldTurn;
+                    }
                 }
                 catch (error) {
                     this.reportDispatchError(error);
                 }
+                finally {
+                    readyBatch.reset();
+                    this.draining -= 1;
+                }
+                if (this.disposed)
+                    return;
             }
         }
         finally {
@@ -141,30 +168,50 @@ class ZLinkMeshDispatchPump {
         }
         return new Promise((resolve) => this.idleApplicationWorkers.add(resolve));
     }
-    dispatchRecord(owner, record) {
+    /**
+     * Starts one record in this worker's turn; a permit's scope covers the
+     * synchronous dispatch. Returns `false` when the dispatch threw (already
+     * reported), `true` when it returned synchronously, or the handler's pending
+     * completion, which the draining turn awaits itself before
+     * {@link finishRecord}.
+     */
+    dispatchRecord(owner, record, permit) {
+        const previous = permit === undefined ? undefined : (0, application_job_queue_scope_1.enterApplicationJobPermitScope)(permit);
         let result;
         try {
             result = this.options.dispatch(owner, record);
         }
         catch (error) {
-            this.reportDispatchError(error, meshDispatchFailureContext(record));
-            return;
+            this.failRecord(error, record, permit);
+            return false;
+        }
+        finally {
+            if (permit !== undefined)
+                (0, application_job_queue_scope_1.leaveApplicationJobPermitScope)(previous);
         }
-        return result === undefined
-            ? this.finishRecord(record)
-            : Promise.resolve(result).then(() => this.finishRecord(record), (error) => this.reportDispatchError(error, meshDispatchFailureContext(record)));
+        return result ?? true;
     }
-    finishRecord(record) {
-        let result;
+    failRecord(error, record, permit) {
+        (0, application_job_queue_scope_1.releaseApplicationJobPermitTurn)(permit);
+        this.reportDispatchError(error, meshDispatchFailureContext(record));
+    }
+    /** Runs the record's terminal completion, then releases its permit turn. */
+    finishRecord(record, permit) {
+        let result = undefined;
         try {
             result = record.onTerminalCompletion?.();
         }
         catch (error) {
             this.reportDispatchError(error, meshDispatchFailureContext(record));
+        }
+        if (result === undefined) {
+            (0, application_job_queue_scope_1.releaseApplicationJobPermitTurn)(permit);
             return;
         }
-        if (result !== undefined)
-            return Promise.resolve(result).catch((error) => this.reportDispatchError(error, meshDispatchFailureContext(record)));
+        return Promise.resolve(result).then(() => (0, application_job_queue_scope_1.releaseApplicationJobPermitTurn)(permit), (error) => {
+            this.reportDispatchError(error, meshDispatchFailureContext(record));
+            (0, application_job_queue_scope_1.releaseApplicationJobPermitTurn)(permit);
+        });
     }
     reportDispatchError(error, context) {
         this.options.reportError?.(error, context);
@@ -204,7 +251,7 @@ class ZLinkMeshDispatchPump {
                 if ((this.pendingDomains & service_runtime_contracts_1.ReadyDomain.Application) !== 0) {
                     setImmediate(() => this.wakeApplicationWorker());
                 }
-                const lifecycleBudgetExhausted = await this.drainDomain(service_runtime_contracts_1.ReadyDomain.Infrastructure, readyBatch, undefined, MESH_DISPATCH_LIFECYCLE_CLAIM_BUDGET);
+                const lifecycleBudgetExhausted = await this.drainDomain(readyBatch);
                 if (lifecycleBudgetExhausted) {
                     this.pendingDomains |= service_runtime_contracts_1.ReadyDomain.Infrastructure;
                     await yieldToEventLoop();
@@ -215,111 +262,34 @@ class ZLinkMeshDispatchPump {
             readyBatch.close();
         }
     }
-    async drainDomain(domain, readyBatch, receiveBatch, claimBudget) {
+    async drainDomain(readyBatch) {
         let claimsDrained = 0;
+        this.beginDrain();
         try {
             while (!this.disposed) {
-                if (claimBudget !== undefined && claimsDrained >= claimBudget) {
+                if (claimsDrained >= MESH_DISPATCH_LIFECYCLE_CLAIM_BUDGET) {
                     // Lifecycle work has priority, but a bounded turn lets application
                     // work make progress when lifecycle records keep arriving.
                     return true;
                 }
                 readyBatch.reset();
-                const drained = this.node.drainReady(domain, readyBatch, runtime_values_1.ZLINK_BACKEND_RECV_DONT_WAIT);
+                const drained = this.node.drainReady(service_runtime_contracts_1.ReadyDomain.Infrastructure, readyBatch, runtime_values_1.ZLINK_BACKEND_RECV_DONT_WAIT);
                 if (!drained.ok || drained.records.length === 0) {
                     return false;
                 }
-                if (domain === service_runtime_contracts_1.ReadyDomain.Application && drained.hasResidue) {
-                    this.markReady(service_runtime_contracts_1.ReadyDomain.Application);
-                }
                 for (let index = 0; index < drained.records.length; index += 1) {
                     const claim = readyBatch.takeClaim(index);
                     claimsDrained += 1;
                     const owner = drained.records[index];
-                    // Raw ingress already attached one host permit to each record.
-                    // A claim that reserves admission here may receive only that permit's record.
-                    const drainClaim = async () => {
-                        let ownerReceiveBatch = receiveBatch;
-                        try {
-                            ownerReceiveBatch ??= this.node.createReceiveBatch(MESH_DISPATCH_RECEIVE_CAPACITY, this.options.partCapacity ?? DEFAULT_MESH_PART_CAPACITY);
-                            const capacity = owner.ordinaryIngressPreAdmitted === true ? MESH_DISPATCH_RECEIVE_CAPACITY : 1;
-                            let claimPermit = owner.terminalCompletion === true ||
-                                owner.ordinaryIngressPreAdmitted === true ||
-                                domain === service_runtime_contracts_1.ReadyDomain.Infrastructure
-                                ? undefined
-                                : await this.acquirePermit();
-                            try {
-                                if (this.capacityStop.signal.aborted)
-                                    return;
-                                ownerReceiveBatch.reset(capacity);
-                                const received = claim.recvBatch(ownerReceiveBatch, runtime_values_1.ZLINK_BACKEND_RECV_DONT_WAIT);
-                                if (received.ok) {
-                                    // The bounded batch stays in claim order until its records finish.
-                                    try {
-                                        for (const record of received.records) {
-                                            if (this.disposed)
-                                                break;
-                                            const permit = record.applicationJobPermit ?? claimPermit;
-                                            if (owner.ordinaryIngressPreAdmitted === true && permit === undefined) {
-                                                throw new Error('Pre-admitted raw ingress record lost its Application Job Queue permit.');
-                                            }
-                                            this.recordsSinceYield += 1;
-                                            if (permit === undefined) {
-                                                const dispatched = this.dispatchRecord(owner, record);
-                                                if (dispatched !== undefined)
-                                                    await dispatched;
-                                            }
-                                            else {
-                                                if (domain === service_runtime_contracts_1.ReadyDomain.Application &&
-                                                    record.applicationJobPermit === undefined)
-                                                    permit.markApplicationQueued();
-                                                // The scope now owns this reservation, including failure
-                                                // and detached handler handoff. Only unused permits remain
-                                                // owned by the receive attempt's finally block.
-                                                if (permit === claimPermit)
-                                                    claimPermit = undefined;
-                                                const dispatched = (0, application_job_queue_scope_1.runWithApplicationJobPermit)(permit, this.dispatchOwnedRecord, owner, record);
-                                                if (dispatched !== undefined)
-                                                    await dispatched;
-                                            }
-                                        }
-                                    }
-                                    finally {
-                                        // Batch ownership includes records whose dispatch never began,
-                                        // including on failure or shutdown in the middle of the batch.
-                                        for (const record of received.records) {
-                                            for (const part of record.parts)
-                                                part.close();
-                                            record.releaseRetainedIngress?.();
-                                        }
-                                    }
-                                }
-                            }
-                            finally {
-                                claimPermit?.releaseAfterInternalProcessing();
-                            }
-                        }
-                        finally {
-                            claim.release();
-                            if (receiveBatch === undefined)
-                                ownerReceiveBatch?.close();
-                        }
-                        const yieldTurn = this.yieldIfNeeded();
-                        if (yieldTurn !== undefined)
-                            await yieldTurn;
-                    };
-                    // An application worker drains the one owner it claimed. Infrastructure owners
-                    // drain independently, so a suspended owner does not hold the other claims.
-                    if (receiveBatch !== undefined) {
-                        await drainClaim();
-                    }
-                    else {
-                        const drain = drainClaim().catch((error) => this.reportDispatchError(error));
-                        this.activeDrains.add(drain);
-                        void drain.finally(() => this.activeDrains.delete(drain));
-                    }
+                    this.beginDrain();
+                    const drain = this.drainClaim(service_runtime_contracts_1.ReadyDomain.Infrastructure, owner, claim, undefined).catch((error) => this.reportDispatchError(error));
+                    this.activeDrains.add(drain);
+                    void drain.finally(() => {
+                        this.draining -= 1;
+                        this.activeDrains.delete(drain);
+                    });
                 }
-                if (claimBudget !== undefined && claimsDrained >= claimBudget) {
+                if (claimsDrained >= MESH_DISPATCH_LIFECYCLE_CLAIM_BUDGET) {
                     this.wakeApplicationWorker();
                     return true;
                 }
@@ -334,17 +304,133 @@ class ZLinkMeshDispatchPump {
         }
         finally {
             readyBatch.reset();
+            this.draining -= 1;
+        }
+    }
+    /**
+     * Time the pump spent idle is not batch work: when work starts on an idle
+     * pump, its batch budget starts with it (spec 08 §6).
+     */
+    beginDrain() {
+        if (this.draining === 0) {
+            this.recordsSinceYield = 0;
+            this.yieldStartedAtMs = this.nowMs();
+        }
+        this.draining += 1;
+    }
+    /** Drains one claimed owner in this worker's turn, in claim order. */
+    async drainClaim(domain, owner, claim, receiveBatch) {
+        let ownerReceiveBatch = receiveBatch;
+        try {
+            ownerReceiveBatch ??= this.node.createReceiveBatch(MESH_DISPATCH_RECEIVE_CAPACITY, this.options.partCapacity ?? DEFAULT_MESH_PART_CAPACITY);
+            const capacity = owner.ordinaryIngressPreAdmitted === true ? MESH_DISPATCH_RECEIVE_CAPACITY : 1;
+            let claimPermit = owner.terminalCompletion === true ||
+                owner.ordinaryIngressPreAdmitted === true ||
+                domain === service_runtime_contracts_1.ReadyDomain.Infrastructure
+                ? undefined
+                : await this.acquirePermit();
+            try {
+                if (this.capacityStop.signal.aborted)
+                    return;
+                ownerReceiveBatch.reset(capacity);
+                const received = claim.recvBatch(ownerReceiveBatch, runtime_values_1.ZLINK_BACKEND_RECV_DONT_WAIT);
+                if (received.ok) {
+                    // The bounded batch stays in claim order until its records finish.
+                    try {
+                        for (const record of received.records) {
+                            if (this.disposed)
+                                break;
+                            const permit = record.applicationJobPermit ?? claimPermit;
+                            if (owner.ordinaryIngressPreAdmitted === true && permit === undefined) {
+                                throw new Error('Pre-admitted raw ingress record lost its Application Job Queue permit.');
+                            }
+                            this.recordsSinceYield += 1;
+                            if (permit !== undefined) {
+                                if (domain === service_runtime_contracts_1.ReadyDomain.Application && record.applicationJobPermit === undefined)
+                                    permit.markApplicationQueued();
+                                // The scope now owns this reservation, including failure
+                                // and detached handler handoff. Only unused permits remain
+                                // owned by the receive attempt's finally block.
+                                if (permit === claimPermit)
+                                    claimPermit = undefined;
+                            }
+                            // The record's terminal and the permit turn release follow the
+                            // handler in this turn's own continuation.
+                            if (record.prepareDispatch !== undefined) {
+                                try {
+                                    const stopSignal = this.capacityStop.signal;
+                                    const preparation = record.prepareDispatch(stopSignal);
+                                    const accepted = preparation instanceof Promise ? await preparation : preparation;
+                                    if (!accepted || stopSignal.aborted) {
+                                        (0, application_job_queue_scope_1.releaseApplicationJobPermitTurn)(permit);
+                                        continue;
+                                    }
+                                }
+                                catch (error) {
+                                    this.failRecord(error, record, permit);
+                                    continue;
+                                }
+                            }
+                            const dispatched = this.dispatchRecord(owner, record, permit);
+                            if (dispatched === false)
+                                continue;
+                            if (dispatched !== true) {
+                                try {
+                                    await dispatched;
+                                }
+                                catch (error) {
+                                    this.failRecord(error, record, permit);
+                                    continue;
+                                }
+                            }
+                            const finished = this.finishRecord(record, permit);
+                            if (finished !== undefined)
+                                await finished;
+                        }
+                    }
+                    finally {
+                        // Batch ownership includes records whose dispatch never began,
+                        // including on failure or shutdown in the middle of the batch.
+                        for (const record of received.records) {
+                            for (const part of record.parts)
+                                part.close();
+                            record.releaseRetainedIngress?.();
+                        }
+                    }
+                }
+            }
+            finally {
+                claimPermit?.releaseAfterInternalProcessing();
+            }
         }
+        finally {
+            claim.release();
+            if (receiveBatch === undefined)
+                ownerReceiveBatch?.close();
+        }
+        const yieldTurn = this.yieldIfNeeded();
+        if (yieldTurn !== undefined)
+            await yieldTurn;
     }
+    /**
+     * The batch budget is shared by every drain of this pump, so once it is
+     * spent every drain waits for the same macrotask boundary; one drain that
+     * keeps running would otherwise hold the event loop the yield was for.
+     */
     yieldIfNeeded() {
+        if (this.pendingYield !== undefined)
+            return this.pendingYield;
         const nowMs = this.nowMs();
         if (this.recordsSinceYield < MESH_DISPATCH_YIELD_RECORDS &&
             nowMs - this.yieldStartedAtMs < MESH_DISPATCH_YIELD_INTERVAL_MS)
             return undefined;
         this.recordsSinceYield = 0;
-        return yieldToTimers().then(() => {
+        const pendingYield = yieldToTimers().then(() => {
+            this.pendingYield = undefined;
             this.yieldStartedAtMs = this.nowMs();
         });
+        this.pendingYield = pendingYield;
+        return pendingYield;
     }
     nowMs() {
         return this.options.monotonicNowMs?.() ?? performance.now();