@zlink-systems/framework 0.30.3 → 0.32.0

package/src/runtime/channels/channel-receive-loops.ts

@@ -19,8 +19,9 @@ import {
 } from './channel-receive-task-tracker';
 import { ApplicationJobQueue, type ApplicationJobQueuePermit } from '../host/application-job-queue';
 import {
-  bindApplicationJobPermit,
-  runWithApplicationJobPermit
+  enterApplicationJobPermitScope,
+  leaveApplicationJobPermitScope,
+  releaseApplicationJobPermitTurn
 } from '../application-jobs/application-job-queue-scope';
 import {
   ZLinkSerialExecutionQueue,
@@ -29,12 +30,45 @@ import {
 
 export function createChannelApplicationDispatchQueue(): ZLinkSerialExecutionQueue {
   return new ZLinkSerialExecutionQueue(async (record: ZLinkSerialWorkRecord<unknown>) => {
+    const permit = record.context as ApplicationJobQueuePermit;
+    const previousPermit = enterApplicationJobPermitScope(permit);
     try {
-      record.resolve(await record.operation());
+      void Promise.resolve(record.operation()).then(
+        (value) => {
+          try {
+            record.resolve(value);
+          } finally {
+            try {
+              record.release();
+            } finally {
+              releaseApplicationJobPermitTurn(permit);
+            }
+          }
+        },
+        (error) => {
+          try {
+            record.reject(error);
+          } finally {
+            try {
+              record.release();
+            } finally {
+              releaseApplicationJobPermitTurn(permit);
+            }
+          }
+        }
+      );
     } catch (error) {
-      record.reject(error);
+      try {
+        record.reject(error);
+      } finally {
+        try {
+          record.release();
+        } finally {
+          releaseApplicationJobPermitTurn(permit);
+        }
+      }
     } finally {
-      record.release();
+      leaveApplicationJobPermitScope(previousPermit);
     }
   });
 }
@@ -71,7 +105,8 @@ interface ZLinkChannelRequestDispatchLoop {
       reply(routingId: unknown, replyToken: unknown): ZLinkMultipartReplyOperation;
     },
     signal?: AbortSignal,
-    decodedHeader?: ZLinkChannelEnvelopeHeader
+    decodedHeader?: ZLinkChannelEnvelopeHeader,
+    receivedAt?: Date
   ): Promise<boolean | void>;
 }
 
@@ -79,7 +114,8 @@ interface ZLinkChannelPublishDispatchLoop {
   dispatch(
     topicMessage: { readonly topic: string; readonly parts: readonly Message[] },
     signal?: AbortSignal,
-    decodedHeader?: ZLinkChannelEnvelopeHeader
+    decodedHeader?: ZLinkChannelEnvelopeHeader,
+    receivedAt?: Date
   ): Promise<void>;
 }
 
@@ -110,7 +146,8 @@ interface ZLinkRoutePacketDispatchLoop {
     },
     signal?: AbortSignal,
     decodedHeader?: ZLinkChannelEnvelopeHeader,
-    infrastructureChecked?: boolean
+    infrastructureChecked?: boolean,
+    receivedAt?: Date
   ): Promise<boolean | void>;
 }
 
@@ -232,7 +269,8 @@ export class ZLinkChannelReceiveLoop {
     private readonly applicationJobQueue: ApplicationJobQueue,
     reportError?: ZLinkReceiveTaskErrorReporter,
     private readonly roundRobin?: ZLinkReceiveRoundRobinCoordinator,
-    private readonly applicationDispatchQueue = createChannelApplicationDispatchQueue()
+    private readonly applicationDispatchQueue = createChannelApplicationDispatchQueue(),
+    private readonly receivedAtClock: () => Date = () => new Date()
   ) {
     this.inFlight = new ZLinkReceiveTaskTracker(reportError);
     this.receiveOwner = roundRobin?.register() ?? Symbol('channel-receive-owner');
@@ -258,90 +296,94 @@ export class ZLinkChannelReceiveLoop {
 
   private async runLoop(signal?: AbortSignal): Promise<void> {
     const batch = new ZLinkReceiveBatchBudget();
+    const rotation = this.applicationJobQueue.createReceiveRotation(
+      RECEIVE_BATCH_MESSAGE_LIMIT,
+      'remote'
+    );
     const capacitySignal =
       signal === undefined
         ? this.capacityStop.signal
         : AbortSignal.any([signal, this.capacityStop.signal]);
-    while (!this.isStopped() && signal?.aborted !== true) {
+    while (!this.isStopped() && !signalAborted(capacitySignal)) {
       if (!this.poller.wait(0)) {
         this.roundRobin?.setReady(this.receiveOwner, false);
-        this.roundRobin?.release(this.receiveOwner);
-        batch.reset();
         if (!(await this.poller.waitForReadable(capacitySignal))) break;
         continue;
       }
-      const applicationJobPermit = await this.acquirePermit(capacitySignal);
-      if (applicationJobPermit === undefined) break;
-      // Readiness can become stale while admission waits. The nonblocking
-      // recv below owns the empty-result check and returns the permit then.
-      this.roundRobin?.setReady(this.receiveOwner, true);
-      if (this.roundRobin?.tryAcquire(this.receiveOwner) === false) {
-        applicationJobPermit.releaseAfterInternalProcessing();
-        await waitReceiveLoopTurn();
-        continue;
-      }
-      const releaseRawReceive =
-        this.roundRobin === undefined
-          ? this.rawReceiveReservations.tryAcquire()
-          : this.roundRobin.tryAcquireRawReceiveReservation();
-      if (releaseRawReceive === undefined) {
-        applicationJobPermit.releaseAfterInternalProcessing();
-        this.roundRobin?.release(this.receiveOwner);
-        await waitReceiveLoopTurn();
-        continue;
-      }
-      const received = this.router.recv(1);
-      if (received == null) {
-        this.poller.markDrained();
-        applicationJobPermit.releaseAfterInternalProcessing();
-        releaseRawReceive();
-        this.roundRobin?.setReady(this.receiveOwner, false);
-        this.roundRobin?.release(this.receiveOwner);
-        batch.reset();
-        if (!(await this.poller.waitForReadable(capacitySignal))) break;
-        continue;
-      }
-      const receivedBytes = messageBytes(received.parts);
-      let classification: ReturnType<ZLinkChannelReceiveLoop['classify']>;
       try {
-        classification = this.classify(received);
-      } catch (error) {
-        applicationJobPermit.releaseAfterInternalProcessing();
-        releaseRawReceive();
-        received.close();
-        this.inFlight.track(Promise.reject(error));
-        continue;
-      }
-      if (classification.kind === 'consumed') {
-        applicationJobPermit.releaseAfterInternalProcessing();
-        releaseRawReceive();
-        if (classification.closeReceived) received.close();
-        if (batch.record(receivedBytes)) {
-          this.roundRobin?.release(this.receiveOwner);
-          await batch.yieldAndReset();
+        await rotation.acquire(capacitySignal);
+        this.roundRobin?.setReady(this.receiveOwner, true);
+        if (this.roundRobin?.tryAcquire(this.receiveOwner) !== false) {
+          batch.reset();
+          while (!this.isStopped() && !signalAborted(capacitySignal)) {
+            const applicationJobPermit = rotation.take();
+            if (applicationJobPermit === undefined) break;
+            const releaseRawReceive =
+              this.roundRobin === undefined
+                ? this.rawReceiveReservations.tryAcquire()
+                : this.roundRobin.tryAcquireRawReceiveReservation();
+            if (releaseRawReceive === undefined) {
+              applicationJobPermit.releaseAfterInternalProcessing();
+              break;
+            }
+            try {
+              // Readiness can become stale during admission; recv owns no_data.
+              const received = this.router.recv(1);
+              if (received == null) {
+                this.poller.markDrained();
+                this.roundRobin?.setReady(this.receiveOwner, false);
+                break;
+              }
+              const receivedAt = this.receivedAtClock();
+              const receivedBytes = messageBytes(received.parts);
+              let classification: ReturnType<ZLinkChannelReceiveLoop['classify']>;
+              try {
+                classification = this.classify(received);
+              } catch (error) {
+                received.close();
+                this.inFlight.track(Promise.reject(error));
+                if (batch.record(receivedBytes)) break;
+                continue;
+              }
+              if (classification.kind === 'consumed') {
+                applicationJobPermit.releaseAfterInternalProcessing();
+                if (classification.closeReceived) received.close();
+              } else if (this.isStopped() || signalAborted(capacitySignal)) {
+                received.close();
+                break;
+              } else {
+                applicationJobPermit.markApplicationQueued();
+                const task = this.applicationDispatchQueue.submitPreAdmitted(
+                  () =>
+                    this.dispatchAndClose(
+                      received,
+                      signal,
+                      classification.decodedHeader,
+                      true,
+                      undefined,
+                      receivedAt
+                    ),
+                  undefined,
+                  applicationJobPermit
+                );
+                this.inFlight.track(task);
+              }
+              if (batch.record(receivedBytes)) break;
+            } finally {
+              releaseRawReceive();
+              // A queued record owns its lease until its dispatch turn ends.
+              // Reserved leases (no_data, control, failure, stop) return here.
+              applicationJobPermit.releaseUnqueued();
+            }
+          }
         }
-        continue;
-      }
-      if (this.isStopped() || signalAborted(signal)) {
-        applicationJobPermit.releaseAfterInternalProcessing();
-        releaseRawReceive();
-        received.close();
-        break;
-      }
-      applicationJobPermit.markApplicationQueued();
-      const task = runWithApplicationJobPermit(applicationJobPermit, () =>
-        this.applicationDispatchQueue.submitPreAdmitted(
-          bindApplicationJobPermit(() =>
-            this.dispatchAndClose(received, signal, classification.decodedHeader, true)
-          )
-        )
-      );
-      releaseRawReceive();
-      this.inFlight.track(task);
-      if (batch.record(receivedBytes)) {
+      } catch (error) {
+        if (!this.isStopped() && !signalAborted(capacitySignal)) throw error;
+      } finally {
+        rotation.releaseUnused();
         this.roundRobin?.release(this.receiveOwner);
-        await batch.yieldAndReset();
       }
+      await waitReceiveLoopTurn();
     }
   }
 
@@ -357,15 +399,6 @@ export class ZLinkChannelReceiveLoop {
     }
   }
 
-  private async acquirePermit(signal: AbortSignal): Promise<ApplicationJobQueuePermit | undefined> {
-    try {
-      return await this.applicationJobQueue.acquire(signal, 'remote');
-    } catch (error) {
-      if (this.isStopped() || signal.aborted) return undefined;
-      throw error;
-    }
-  }
-
   private async dispatchAndClose(
     received: {
       parts: readonly Message[];
@@ -378,7 +411,8 @@ export class ZLinkChannelReceiveLoop {
     signal?: AbortSignal,
     decodedHeader?: ZLinkChannelEnvelopeHeader,
     infrastructureChecked = false,
-    releaseRawReceive?: () => void
+    releaseRawReceive?: () => void,
+    receivedAt: Date = this.receivedAtClock()
   ): Promise<void> {
     let closeReceived = true;
     try {
@@ -390,7 +424,13 @@ export class ZLinkChannelReceiveLoop {
         }
         decodedHeader = classification.decodedHeader;
       }
-      const consumed = await this.dispatcher.dispatch(received, this.router, signal, decodedHeader);
+      const consumed = await this.dispatcher.dispatch(
+        received,
+        this.router,
+        signal,
+        decodedHeader,
+        receivedAt
+      );
       if (consumed === true) {
         closeReceived = false;
       }
@@ -456,7 +496,8 @@ export class ZLinkSubscriberReceiveLoop {
     ) => boolean | ZLinkSubscriberInfrastructureResult,
     private readonly roundRobin?: ZLinkReceiveRoundRobinCoordinator,
     reportError?: ZLinkReceiveTaskErrorReporter,
-    private readonly applicationDispatchQueue = createChannelApplicationDispatchQueue()
+    private readonly applicationDispatchQueue = createChannelApplicationDispatchQueue(),
+    private readonly receivedAtClock: () => Date = () => new Date()
   ) {
     this.inFlight = new ZLinkReceiveTaskTracker(reportError);
     this.poller = adapter.createReadablePoller(subscriber);
@@ -527,6 +568,7 @@ export class ZLinkSubscriberReceiveLoop {
         if (!(await this.poller.waitForReadable(capacitySignal))) break;
         continue;
       }
+      const receivedAt = this.receivedAtClock();
       const receivedBytes = messageBytes(topicMessage.parts as readonly Message[]);
       let classification: ReturnType<ZLinkSubscriberReceiveLoop['classify']>;
       try {
@@ -555,12 +597,18 @@ export class ZLinkSubscriberReceiveLoop {
         break;
       }
       applicationJobPermit.markApplicationQueued();
-      const task = runWithApplicationJobPermit(applicationJobPermit, () =>
-        this.applicationDispatchQueue.submitPreAdmitted(
-          bindApplicationJobPermit(() =>
-            this.dispatchAndClose(topicMessage, signal, classification.decodedHeader, true)
-          )
-        )
+      const task = this.applicationDispatchQueue.submitPreAdmitted(
+        () =>
+          this.dispatchAndClose(
+            topicMessage,
+            signal,
+            classification.decodedHeader,
+            true,
+            undefined,
+            receivedAt
+          ),
+        undefined,
+        applicationJobPermit
       );
       releaseRawReceive();
       this.inFlight.track(task);
@@ -597,7 +645,8 @@ export class ZLinkSubscriberReceiveLoop {
     signal?: AbortSignal,
     decodedHeader?: ZLinkChannelEnvelopeHeader,
     infrastructureChecked = false,
-    releaseRawReceive?: () => void
+    releaseRawReceive?: () => void,
+    receivedAt: Date = this.receivedAtClock()
   ): Promise<void> {
     try {
       if (!infrastructureChecked) {
@@ -605,7 +654,7 @@ export class ZLinkSubscriberReceiveLoop {
         if (classification.kind === 'consumed') return;
         decodedHeader = classification.decodedHeader;
       }
-      await this.dispatcher.dispatch(topicMessage, signal, decodedHeader);
+      await this.dispatcher.dispatch(topicMessage, signal, decodedHeader, receivedAt);
     } finally {
       releaseRawReceive?.();
       closeMessages(topicMessage.parts as readonly Message[]);
@@ -654,7 +703,8 @@ export class ZLinkRouteReceiveLoop {
     private readonly applicationJobQueue: ApplicationJobQueue,
     private readonly roundRobin?: ZLinkReceiveRoundRobinCoordinator,
     reportError?: ZLinkReceiveTaskErrorReporter,
-    private readonly applicationDispatchQueue = createChannelApplicationDispatchQueue()
+    private readonly applicationDispatchQueue = createChannelApplicationDispatchQueue(),
+    private readonly receivedAtClock: () => Date = () => new Date()
   ) {
     this.inFlight = new ZLinkReceiveTaskTracker(reportError);
     this.receiveOwner = roundRobin?.register() ?? Symbol('route-receive-owner');
@@ -716,6 +766,7 @@ export class ZLinkRouteReceiveLoop {
         if (!(await this.poller.waitForReadable(capacitySignal))) break;
         continue;
       }
+      const receivedAt = this.receivedAtClock();
       const receivedBytes = messageBytes(received.parts);
       let infrastructure: boolean | Promise<void> | undefined;
       try {
@@ -767,10 +818,10 @@ export class ZLinkRouteReceiveLoop {
         break;
       }
       applicationJobPermit.markApplicationQueued();
-      const task = runWithApplicationJobPermit(applicationJobPermit, () =>
-        this.applicationDispatchQueue.submitPreAdmitted(
-          bindApplicationJobPermit(() => this.dispatchAndClose(received, signal, true))
-        )
+      const task = this.applicationDispatchQueue.submitPreAdmitted(
+        () => this.dispatchAndClose(received, signal, true, undefined, receivedAt),
+        undefined,
+        applicationJobPermit
       );
       releaseRawReceive();
       this.inFlight.track(task);
@@ -812,7 +863,8 @@ export class ZLinkRouteReceiveLoop {
     },
     signal?: AbortSignal,
     infrastructureChecked = false,
-    releaseRawReceive?: () => void
+    releaseRawReceive?: () => void,
+    receivedAt: Date = this.receivedAtClock()
   ): Promise<void> {
     let closeReceived = true;
     try {
@@ -821,7 +873,8 @@ export class ZLinkRouteReceiveLoop {
         this.router,
         signal,
         tryDecodeChannelHeader(received.parts, this.dispatcher.flowEnabled?.() ?? true),
-        infrastructureChecked
+        infrastructureChecked,
+        receivedAt
       );
       if (consumed === true) {
         closeReceived = false;