@zlink-systems/framework 0.30.0 → 0.30.2

package/src/runtime/backend/mesh-dispatch-pump.ts

@@ -1,6 +1,11 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
+import { awaitWithAbort } from '../abort';
 import { availableParallelism } from 'node:os';
-import { runWithApplicationJobPermit } from '../application-jobs/application-job-queue-scope';
+import {
+  enterApplicationJobPermitScope,
+  leaveApplicationJobPermitScope,
+  releaseApplicationJobPermitTurn
+} from '../application-jobs/application-job-queue-scope';
 import type {
   ApplicationJobPermitPort,
   ApplicationJobQueuePort
@@ -8,6 +13,7 @@ import type {
 import { runZLinkExecutionArea } from '../execution';
 import {
   ReadyDomain,
+  type Claim,
   type ReadyBatch,
   type ReadyRecord,
   type ReceiveBatch,
@@ -67,6 +73,10 @@ export class ZLinkMeshDispatchPump {
   private readonly capacityStop = new AbortController();
   private recordsSinceYield = 0;
   private yieldStartedAtMs = 0;
+  /** Drains in progress; the batch budget begins when work starts on an idle pump. */
+  private draining = 0;
+  /** The macrotask boundary every drain waits for once the shared budget is spent. */
+  private pendingYield?: Promise<void>;
 
   constructor(
     private readonly node: ZLinkBackendMeshNode,
@@ -84,7 +94,7 @@ export class ZLinkMeshDispatchPump {
     });
   }
 
-  async dispose(): Promise<void> {
+  async dispose(signal?: AbortSignal): Promise<void> {
     if (this.disposed) {
       return;
     }
@@ -94,7 +104,7 @@ export class ZLinkMeshDispatchPump {
     for (const wake of this.idleApplicationWorkers) wake();
     this.idleApplicationWorkers.clear();
     while (this.activeDrains.size > 0) {
-      await Promise.all([...this.activeDrains]);
+      await awaitWithAbort(Promise.all([...this.activeDrains]), signal);
     }
   }
 
@@ -158,12 +168,40 @@ export class ZLinkMeshDispatchPump {
     try {
       for (;;) {
         await this.waitForApplicationReady();
-        if (this.disposed) return;
+        this.beginDrain();
         try {
-          await this.drainDomain(ReadyDomain.Application, readyBatch, receiveBatch);
+          while (!this.disposed) {
+            readyBatch.reset();
+            const drained = this.node.drainReady(
+              ReadyDomain.Application,
+              readyBatch,
+              ZLINK_BACKEND_RECV_DONT_WAIT
+            );
+            if (!drained.ok || drained.records.length === 0) break;
+            if (drained.hasResidue) this.markReady(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(
+                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 {
       receiveBatch.close();
@@ -180,6 +218,64 @@ export class ZLinkMeshDispatchPump {
     return new Promise((resolve) => this.idleApplicationWorkers.add(resolve));
   }
 
+  /**
+   * 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(
+    owner: ReadyRecord,
+    record: ReceiveRecord,
+    permit: ApplicationJobPermitPort | undefined
+  ): boolean | PromiseLike<void> {
+    const previous = permit === undefined ? undefined : enterApplicationJobPermitScope(permit);
+    let result: void | PromiseLike<void>;
+    try {
+      result = this.options.dispatch(owner, record);
+    } catch (error) {
+      this.failRecord(error, record, permit);
+      return false;
+    } finally {
+      if (permit !== undefined) leaveApplicationJobPermitScope(previous);
+    }
+    return result ?? true;
+  }
+
+  private failRecord(
+    error: unknown,
+    record: ReceiveRecord,
+    permit: ApplicationJobPermitPort | undefined
+  ): void {
+    releaseApplicationJobPermitTurn(permit);
+    this.reportDispatchError(error, meshDispatchFailureContext(record));
+  }
+
+  /** Runs the record's terminal completion, then releases its permit turn. */
+  private finishRecord(
+    record: ReceiveRecord,
+    permit: ApplicationJobPermitPort | undefined
+  ): void | Promise<void> {
+    let result: void | Promise<void> = undefined;
+    try {
+      result = record.onTerminalCompletion?.();
+    } catch (error) {
+      this.reportDispatchError(error, meshDispatchFailureContext(record));
+    }
+    if (result === undefined) {
+      releaseApplicationJobPermitTurn(permit);
+      return;
+    }
+    return Promise.resolve(result).then(
+      () => releaseApplicationJobPermitTurn(permit),
+      (error) => {
+        this.reportDispatchError(error, meshDispatchFailureContext(record));
+        releaseApplicationJobPermitTurn(permit);
+      }
+    );
+  }
+
   private reportDispatchError(error: unknown, context?: ZLinkMeshDispatchFailureContext): void {
     this.options.reportError?.(error, context);
   }
@@ -229,12 +325,7 @@ export class ZLinkMeshDispatchPump {
         if ((this.pendingDomains & ReadyDomain.Application) !== 0) {
           setImmediate(() => this.wakeApplicationWorker());
         }
-        const lifecycleBudgetExhausted = await this.drainDomain(
-          ReadyDomain.Infrastructure,
-          readyBatch,
-          undefined,
-          MESH_DISPATCH_LIFECYCLE_CLAIM_BUDGET
-        );
+        const lifecycleBudgetExhausted = await this.drainDomain(readyBatch);
         if (lifecycleBudgetExhausted) {
           this.pendingDomains |= ReadyDomain.Infrastructure;
           await yieldToEventLoop();
@@ -245,118 +336,40 @@ export class ZLinkMeshDispatchPump {
     }
   }
 
-  private async drainDomain(
-    domain: number,
-    readyBatch: ReadyBatch,
-    receiveBatch: ReceiveBatch | undefined,
-    claimBudget?: number
-  ): Promise<boolean> {
+  private async drainDomain(readyBatch: ReadyBatch): Promise<boolean> {
     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, ZLINK_BACKEND_RECV_DONT_WAIT);
+        const drained = this.node.drainReady(
+          ReadyDomain.Infrastructure,
+          readyBatch,
+          ZLINK_BACKEND_RECV_DONT_WAIT
+        );
         if (!drained.ok || drained.records.length === 0) {
           return false;
         }
-        if (domain === ReadyDomain.Application && drained.hasResidue) {
-          this.markReady(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 === ReadyDomain.Infrastructure
-                  ? undefined
-                  : await this.acquirePermit();
-              try {
-                if (this.capacityStop.signal.aborted) return;
-                ownerReceiveBatch.reset(capacity);
-                const received = claim.recvBatch(ownerReceiveBatch, 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;
-                      const dispatch = async () => {
-                        try {
-                          await this.options.dispatch(owner, record);
-                          await record.onTerminalCompletion?.();
-                        } catch (error) {
-                          this.reportDispatchError(error, meshDispatchFailureContext(record));
-                        }
-                      };
-                      if (permit === undefined) {
-                        await dispatch();
-                      } else {
-                        if (
-                          domain === 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;
-                        await runWithApplicationJobPermit(permit, dispatch);
-                      }
-                    }
-                  } 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(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;
         }
@@ -369,10 +382,123 @@ export class ZLinkMeshDispatchPump {
       return false;
     } 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).
+   */
+  private beginDrain(): void {
+    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. */
+  private async drainClaim(
+    domain: number,
+    owner: ReadyRecord,
+    claim: Claim,
+    receiveBatch: ReceiveBatch | undefined
+  ): Promise<void> {
+    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 === ReadyDomain.Infrastructure
+          ? undefined
+          : await this.acquirePermit();
+      try {
+        if (this.capacityStop.signal.aborted) return;
+        ownerReceiveBatch.reset(capacity);
+        const received = claim.recvBatch(ownerReceiveBatch, 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 === 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) {
+                    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.
+   */
   private yieldIfNeeded(): Promise<void> | undefined {
+    if (this.pendingYield !== undefined) return this.pendingYield;
     const nowMs = this.nowMs();
     if (
       this.recordsSinceYield < MESH_DISPATCH_YIELD_RECORDS &&
@@ -380,9 +506,12 @@ export class ZLinkMeshDispatchPump {
     )
       return undefined;
     this.recordsSinceYield = 0;
-    return yieldToTimers().then(() => {
+    const pendingYield = yieldToTimers().then(() => {
+      this.pendingYield = undefined;
       this.yieldStartedAtMs = this.nowMs();
     });
+    this.pendingYield = pendingYield;
+    return pendingYield;
   }
 
   private nowMs(): number {

package/src/runtime/backend/node/node-backend-adapter-support.ts

@@ -7,6 +7,7 @@ import {
 import { loadBinding } from '../node-backend-adapter';
 import { SubmitResult, ZLinkBackendResultError } from '../runtime-values';
 const nativeErrnoValues = osConstants.errno;
+const completedSend: Promise<void> = Promise.resolve();
 
 export type ZLinkBindingModule = typeof import('@zlink-systems/zlink');
 export const zlink = loadBinding() as ZLinkBindingModule;
@@ -119,12 +120,16 @@ export function submitBindingReply(operation: ZLinkBindingReplyOperation, payloa
   }
 }
 
-export async function submitBindingAsyncSend(
+export function submitBindingAsyncSend(
   operation: ZLinkBindingAsyncSendOperation,
   payload: unknown
 ): Promise<void> {
-  const submission = submitBindingSend(operation, payload);
-  if (submission.result === SubmitResult.Backpressured) await submission.admitted;
+  try {
+    const submission = submitBindingSend(operation, payload);
+    return submission.result === SubmitResult.Backpressured ? submission.admitted : completedSend;
+  } catch (error) {
+    return Promise.reject(error);
+  }
 }
 
 export function submitBindingSend(
@@ -152,7 +157,8 @@ export function submitBindingSend(
       })
     };
   }
-  return { result: SubmitResult.Ok, admitted: submission.admitted };
+  // Binding SendSubmission is the closed OK | BACKPRESSURED snapshot.
+  return submission as import('../raw-binding-port').ZLinkRawSendSubmission;
 }
 
 export function submitBindingSyncSend(
@@ -177,7 +183,8 @@ export async function submitBindingRequest(
   operation: ZLinkBindingRequestOperation,
   payload: unknown,
   timeoutMs: number | undefined,
-  recordReceived?: () => void
+  recordReceived?: () => void,
+  onAdmitted?: () => void
 ): Promise<readonly unknown[]> {
   const deadlineMs = timeoutMs === undefined ? undefined : performance.now() + timeoutMs;
   try {
@@ -195,7 +202,7 @@ export async function submitBindingRequest(
     if (timeoutMs !== undefined) {
       current = current.timeout(timeoutMs);
     }
-    return await bindingRequestReply(current.submit(), deadlineMs, recordReceived);
+    return await bindingRequestReply(current.submit(), deadlineMs, recordReceived, onAdmitted);
   } catch (error) {
     throw translateBindingResultError(error);
   }
@@ -204,13 +211,14 @@ export async function submitBindingRequest(
 export async function bindingRequestReply(
   submission: import('@zlink-systems/zlink').RequestSubmission,
   deadlineMs: number | undefined,
-  recordReceived?: () => void
+  recordReceived?: () => void,
+  onAdmitted?: () => void
 ): Promise<import('@zlink-systems/zlink').Message[]> {
   const reply = submission.reply;
   if (submission.result === SubmitResult.Backpressured) {
     try {
       const [, replies] = await waitRequestReply(
-        Promise.all([submission.admitted, reply]),
+        Promise.all([submission.admitted.then(() => onAdmitted?.()), reply]),
         'Request',
         deadlineMs
       );
@@ -227,6 +235,7 @@ export async function bindingRequestReply(
       throw error;
     }
   }
+  onAdmitted?.();
   const replies = await reply;
   recordReceived?.();
   return replies;

package/src/runtime/backend/node/node-dealer-channel-client-transport.ts

@@ -1,3 +1,4 @@
+import { bindingRequestReply } from './node-backend-adapter-support';
 import type { DealerSocket, Message, PubSocket } from '@zlink-systems/zlink';
 import { ZLinkConfigurationException } from '../../configuration';
 import { ZLinkSubmitStatus, type ZLinkSubmitResult } from '../../messaging/submission-result';
@@ -56,7 +57,8 @@ export class ZLinkDealerChannelClientTransport implements ZLinkChannelClientTran
     request: Message,
     timeoutMs: number | undefined,
     signal?: AbortSignal,
-    metadata: ReadonlyMap<string, string> = EMPTY_METADATA
+    metadata: ReadonlyMap<string, string> = EMPTY_METADATA,
+    onAdmitted?: () => void
   ): Promise<TReply> {
     throwIfAborted(signal);
     const operation = runWithOutboundFlow(true, () =>
@@ -78,7 +80,15 @@ export class ZLinkDealerChannelClientTransport implements ZLinkChannelClientTran
     );
     if (timeoutMs !== undefined) operation.timeout(timeoutMs);
     const reply = await submitRequestOperation(
-      { submit: () => operation.submit().reply },
+      {
+        submit: () =>
+          bindingRequestReply(
+            operation.submit(),
+            timeoutMs === undefined ? undefined : performance.now() + timeoutMs,
+            undefined,
+            onAdmitted
+          )
+      },
       'channel request'
     );
     try {