@zlink-systems/framework 0.25.0 → 0.27.0

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

@@ -18,7 +18,26 @@ import {
   type ZLinkReceiveTaskErrorReporter
 } from './channel-receive-task-tracker';
 import { ApplicationJobQueue, type ApplicationJobQueuePermit } from '../host/application-job-queue';
-import { runWithApplicationJobPermit } from '../application-jobs/application-job-queue-scope';
+import {
+  bindApplicationJobPermit,
+  runWithApplicationJobPermit
+} from '../application-jobs/application-job-queue-scope';
+import {
+  ZLinkSerialExecutionQueue,
+  type ZLinkSerialWorkRecord
+} from '../execution/serial-execution-queue';
+
+export function createChannelApplicationDispatchQueue(): ZLinkSerialExecutionQueue {
+  return new ZLinkSerialExecutionQueue(async (record: ZLinkSerialWorkRecord<unknown>) => {
+    try {
+      record.resolve(await record.operation());
+    } catch (error) {
+      record.reject(error);
+    } finally {
+      record.release();
+    }
+  });
+}
 
 //  The loop awaits between reads and the signal can abort in that gap. Reading
 //  through a function keeps the later check honest; an inline read stays
@@ -212,7 +231,8 @@ export class ZLinkChannelReceiveLoop {
     private readonly poller: ZLinkBackendReadablePoller,
     private readonly applicationJobQueue: ApplicationJobQueue,
     reportError?: ZLinkReceiveTaskErrorReporter,
-    private readonly roundRobin?: ZLinkReceiveRoundRobinCoordinator
+    private readonly roundRobin?: ZLinkReceiveRoundRobinCoordinator,
+    private readonly applicationDispatchQueue = createChannelApplicationDispatchQueue()
   ) {
     this.inFlight = new ZLinkReceiveTaskTracker(reportError);
     this.receiveOwner = roundRobin?.register() ?? Symbol('channel-receive-owner');
@@ -310,7 +330,11 @@ export class ZLinkChannelReceiveLoop {
       }
       applicationJobPermit.markApplicationQueued();
       const task = runWithApplicationJobPermit(applicationJobPermit, () =>
-        this.dispatchAndClose(received, signal, classification.decodedHeader, true)
+        this.applicationDispatchQueue.submitPreAdmitted(
+          bindApplicationJobPermit(() =>
+            this.dispatchAndClose(received, signal, classification.decodedHeader, true)
+          )
+        )
       );
       releaseRawReceive();
       this.inFlight.track(task);
@@ -431,7 +455,8 @@ export class ZLinkSubscriberReceiveLoop {
       topicMessage: ReturnType<ZLinkChannelBackendAdapter['createTopicMessage']>
     ) => boolean | ZLinkSubscriberInfrastructureResult,
     private readonly roundRobin?: ZLinkReceiveRoundRobinCoordinator,
-    reportError?: ZLinkReceiveTaskErrorReporter
+    reportError?: ZLinkReceiveTaskErrorReporter,
+    private readonly applicationDispatchQueue = createChannelApplicationDispatchQueue()
   ) {
     this.inFlight = new ZLinkReceiveTaskTracker(reportError);
     this.poller = adapter.createReadablePoller(subscriber);
@@ -531,7 +556,11 @@ export class ZLinkSubscriberReceiveLoop {
       }
       applicationJobPermit.markApplicationQueued();
       const task = runWithApplicationJobPermit(applicationJobPermit, () =>
-        this.dispatchAndClose(topicMessage, signal, classification.decodedHeader, true)
+        this.applicationDispatchQueue.submitPreAdmitted(
+          bindApplicationJobPermit(() =>
+            this.dispatchAndClose(topicMessage, signal, classification.decodedHeader, true)
+          )
+        )
       );
       releaseRawReceive();
       this.inFlight.track(task);
@@ -624,7 +653,8 @@ export class ZLinkRouteReceiveLoop {
     private readonly poller: ZLinkBackendReadablePoller,
     private readonly applicationJobQueue: ApplicationJobQueue,
     private readonly roundRobin?: ZLinkReceiveRoundRobinCoordinator,
-    reportError?: ZLinkReceiveTaskErrorReporter
+    reportError?: ZLinkReceiveTaskErrorReporter,
+    private readonly applicationDispatchQueue = createChannelApplicationDispatchQueue()
   ) {
     this.inFlight = new ZLinkReceiveTaskTracker(reportError);
     this.receiveOwner = roundRobin?.register() ?? Symbol('route-receive-owner');
@@ -738,7 +768,9 @@ export class ZLinkRouteReceiveLoop {
       }
       applicationJobPermit.markApplicationQueued();
       const task = runWithApplicationJobPermit(applicationJobPermit, () =>
-        this.dispatchAndClose(received, signal, true)
+        this.applicationDispatchQueue.submitPreAdmitted(
+          bindApplicationJobPermit(() => this.dispatchAndClose(received, signal, true))
+        )
       );
       releaseRawReceive();
       this.inFlight.track(task);

package/src/runtime/channels/channel-runtime-lifecycle.ts

@@ -1,3 +1,4 @@
+import { RuntimeDisposal } from '../disposal';
 import type { ZLinkLocationOptionOverrides } from '../../contracts/Locations/Options';
 import type { ZLinkRequestHandler, ZLinkSendHandler } from '../../contracts/Handlers';
 import { ZLinkConfigurationException } from '../configuration';
@@ -31,6 +32,7 @@ import {
   type ZLinkRouteRuntimeSendHandler
 } from './channel-dispatchers';
 import {
+  createChannelApplicationDispatchQueue,
   ZLinkChannelReceiveLoop,
   ZLinkReceiveRoundRobinCoordinator,
   ZLinkRouteReceiveLoop,
@@ -50,6 +52,7 @@ import {
 import type { ApplicationJobQueue } from '../host/application-job-queue';
 import { AsyncResource } from 'node:async_hooks';
 import { ZLinkStateLane } from '../execution/state-lane';
+import { ZLinkSerialExecutionQueue } from '../execution/serial-execution-queue';
 
 const detachedStateLaneResource = new AsyncResource('zlink:channel-runtime-lifecycle');
 
@@ -82,6 +85,7 @@ interface ChannelRuntimeDisposeWork {
   readonly subscriberLoops: readonly ZLinkSubscriberReceiveLoop[];
   readonly manualTransitions: readonly Promise<void>[];
   readonly routeLoops: readonly { stop(): Promise<void> }[];
+  readonly applicationDispatchQueues: readonly ZLinkSerialExecutionQueue[];
   readonly clientServerLocation?: ZLinkClientServerLocationRuntime;
   readonly fanoutLocation?: ZLinkFanoutLocationRuntime;
   readonly spotRouteBridges: readonly ZLinkBackendSpotRouteBridge[];
@@ -108,10 +112,11 @@ export class ZLinkChannelRuntimeLifecycle {
   private readonly manualFanoutSubscribers = new Map<string, ManualFanoutSubscriberState>();
   private readonly manualFanoutSubscriberOwners = new Set<object>();
   private readonly routeReceiveLoops: Array<{ stop(): Promise<void> }> = [];
+  private readonly applicationDispatchQueues = new Map<string, ZLinkSerialExecutionQueue>();
   private readonly meshChannelDispatchers = new Map<string, ZLinkChannelRequestDispatcher>();
   private readonly meshRouteDispatchers = new Map<string, ZLinkRoutePacketDispatcher>();
   private nextManualFanoutIndex = 0;
-  private disposed = false;
+  private readonly disposal = new RuntimeDisposal();
   private locationAutoConnect?: ZLinkChannelLocationAutoConnectContext;
   private clientServerLocation?: ZLinkClientServerLocationRuntime;
   private fanoutLocation?: ZLinkFanoutLocationRuntime;
@@ -119,6 +124,10 @@ export class ZLinkChannelRuntimeLifecycle {
 
   constructor(private readonly options: ZLinkChannelRuntimeLifecycleOptions) {}
 
+  fanoutTopologyTargets(channelName: string) {
+    return this.fanoutLocation?.topologyTargets(channelName);
+  }
+
   configureLocationAutoConnect(
     runtime: ZLinkLocationRuntime,
     stores: ZLinkLocationRuntimeStores,
@@ -384,7 +393,11 @@ export class ZLinkChannelRuntimeLifecycle {
     return this.meshRouteDispatchers.has(meshName);
   }
 
-  async dispose(signal?: AbortSignal): Promise<void> {
+  dispose(signal?: AbortSignal): Promise<void> {
+    return this.disposal.run(() => this.disposeCore(signal));
+  }
+
+  private async disposeCore(signal?: AbortSignal): Promise<void> {
     const work = await this.lane.run(() => this.beginDisposeCore());
     const transportStopped = await startOutsideStateLane(() =>
       Promise.allSettled([
@@ -394,6 +407,9 @@ export class ZLinkChannelRuntimeLifecycle {
         ...work.manualTransitions
       ])
     );
+    const applicationStopped = await startOutsideStateLane(() =>
+      Promise.allSettled(work.applicationDispatchQueues.map((queue) => queue.close()))
+    );
     const descriptorStopped =
       work.clientServerLocation === undefined
         ? []
@@ -414,6 +430,7 @@ export class ZLinkChannelRuntimeLifecycle {
     );
     const errors = [
       ...transportStopped,
+      ...applicationStopped,
       ...descriptorStopped,
       ...fanoutDescriptorStopped,
       ...cleanup
@@ -422,18 +439,29 @@ export class ZLinkChannelRuntimeLifecycle {
       .map((result) => result.reason);
     if (errors.length === 1) throw errors[0];
     if (errors.length > 1) throw new AggregateError(errors, 'Channel runtime cleanup failed.');
+    await this.lane.run(() => {
+      this.manualFanoutSubscriberOwners.clear();
+      this.manualFanoutSubscribers.clear();
+      this.channelReceiveLoops.length = 0;
+      this.subscriberReceiveLoops.length = 0;
+      this.routeReceiveLoops.length = 0;
+      this.applicationDispatchQueues.clear();
+      this.clientServerLocation = undefined;
+      this.fanoutLocation = undefined;
+      this.taskRunner = undefined;
+      this.meshChannelDispatchers.clear();
+      this.meshRouteDispatchers.clear();
+      this.options.spotRouteBridges.clear();
+    });
   }
 
   private beginDisposeCore(): ChannelRuntimeDisposeWork {
     const channelLoops = [...this.channelReceiveLoops];
     const manualStates = [...this.manualFanoutSubscribers.values()];
-    this.disposed = true;
     for (const state of manualStates) state.desired = false;
     for (const owner of this.manualFanoutSubscriberOwners) {
       detachEndpointConnections(owner);
     }
-    this.manualFanoutSubscriberOwners.clear();
-    this.manualFanoutSubscribers.clear();
     const manualLoops = new Set(
       manualStates
         .map((state) => state.active?.loop ?? state.stopping?.loop)
@@ -446,29 +474,31 @@ export class ZLinkChannelRuntimeLifecycle {
       this.drainManualFanoutSubscriberCore(state)
     );
     const routeLoops = [...this.routeReceiveLoops];
+    const applicationDispatchQueues = [...this.applicationDispatchQueues.values()];
     const clientServerLocation = this.clientServerLocation;
     const fanoutLocation = this.fanoutLocation;
     const spotRouteBridges = [...this.options.spotRouteBridges.values()];
-    this.channelReceiveLoops.length = 0;
-    this.subscriberReceiveLoops.length = 0;
-    this.routeReceiveLoops.length = 0;
-    this.clientServerLocation = undefined;
-    this.fanoutLocation = undefined;
-    this.taskRunner = undefined;
-    this.meshChannelDispatchers.clear();
-    this.meshRouteDispatchers.clear();
-    this.options.spotRouteBridges.clear();
     return {
       channelLoops,
       subscriberLoops,
       manualTransitions,
       routeLoops,
+      applicationDispatchQueues,
       clientServerLocation,
       fanoutLocation,
       spotRouteBridges
     };
   }
 
+  private applicationDispatchQueue(channelName: string): ZLinkSerialExecutionQueue {
+    let queue = this.applicationDispatchQueues.get(channelName);
+    if (queue === undefined) {
+      queue = createChannelApplicationDispatchQueue();
+      this.applicationDispatchQueues.set(channelName, queue);
+    }
+    return queue;
+  }
+
   private openOutboundSockets(): void {
     // The process-local Server is an independent peer source. Location Store
     // discovery may later alias the same admitted identity, but startup and
@@ -532,7 +562,8 @@ export class ZLinkChannelRuntimeLifecycle {
         this.options.applicationJobQueue,
         (error) =>
           taskRunner.errorSink.reportRuntimeTaskException(`channel:${channelName}:dispatch`, error),
-        this.receiveRoundRobin
+        this.receiveRoundRobin,
+        this.applicationDispatchQueue(channelName)
       );
       this.channelReceiveLoops.push(loop);
       tasks.push(taskRunner.run(`channel:${channelName}`, (signal) => loop.run(signal)));
@@ -622,7 +653,7 @@ export class ZLinkChannelRuntimeLifecycle {
     taskRunner: ZLinkRuntimeTaskRunner,
     dispatcher: ZLinkChannelPublishDispatcher
   ): void {
-    if (this.disposed) return;
+    if (this.disposal.started) return;
     const state = this.getOrCreateManualFanoutSubscriber(
       channelName,
       endpoint,
@@ -678,7 +709,7 @@ export class ZLinkChannelRuntimeLifecycle {
 
   private openManualFanoutSubscriber(state: ManualFanoutSubscriberState): Promise<void> {
     const { channelName, endpoint, connectionId, taskRunner, dispatcher } = state;
-    if (this.disposed || !state.desired || this.taskRunner !== taskRunner) {
+    if (this.disposal.started || !state.desired || this.taskRunner !== taskRunner) {
       return Promise.resolve();
     }
     const token = Symbol(`manual-fanout:${channelName}:${endpoint}`);
@@ -694,7 +725,7 @@ export class ZLinkChannelRuntimeLifecycle {
           onReady() {},
           onTerminated: () => {
             if (
-              this.disposed ||
+              this.disposal.started ||
               (state.active?.token !== token && state.openingToken !== token) ||
               reconnecting
             )
@@ -702,7 +733,7 @@ export class ZLinkChannelRuntimeLifecycle {
             reconnecting = true;
             setImmediate(() => {
               if (
-                this.disposed ||
+                this.disposal.started ||
                 (state.active?.token !== token && state.openingToken !== token)
               ) {
                 reconnecting = false;
@@ -710,7 +741,7 @@ export class ZLinkChannelRuntimeLifecycle {
               }
               this.enqueueManualFanoutTransition(state, async () => {
                 reconnecting = false;
-                if (this.disposed || state.active?.token !== token) return;
+                if (this.disposal.started || state.active?.token !== token) return;
                 try {
                   await this.closeManualFanoutSubscriber(state, token);
                 } catch (error) {
@@ -744,7 +775,8 @@ export class ZLinkChannelRuntimeLifecycle {
           taskRunner.errorSink.reportRuntimeTaskException(
             `subscriber:${state.channelName}:manual:${state.index}:dispatch`,
             error
-          )
+          ),
+        this.applicationDispatchQueue(channelName)
       );
       state.openingToken = undefined;
       state.active = { token, loop };
@@ -780,8 +812,6 @@ export class ZLinkChannelRuntimeLifecycle {
       await startOutsideStateLane(() => active.loop.stop());
     } catch (error) {
       errors.push(error);
-    } finally {
-      await this.lane.run(() => this.finishCloseManualFanoutSubscriberCore(state, active));
     }
     try {
       await startOutsideStateLane(() =>
@@ -794,17 +824,18 @@ export class ZLinkChannelRuntimeLifecycle {
     if (errors.length > 1) {
       throw new AggregateError(errors, `Fanout subscriber '${state.connectionId}' cleanup failed.`);
     }
+    await this.lane.run(() => this.finishCloseManualFanoutSubscriberCore(state, active));
   }
 
   private shouldReconnectManualFanoutSubscriber(state: ManualFanoutSubscriberState): boolean {
-    return !this.disposed && state.desired;
+    return !this.disposal.started && state.desired;
   }
 
   private beginCloseManualFanoutSubscriberCore(
     state: ManualFanoutSubscriberState,
     expectedToken?: symbol
   ): ManualFanoutSubscriberActive | undefined {
-    const active = state.active;
+    const active = state.active ?? state.stopping;
     if (active === undefined || (expectedToken !== undefined && active.token !== expectedToken)) {
       return undefined;
     }
@@ -864,7 +895,8 @@ export class ZLinkChannelRuntimeLifecycle {
         taskRunner.errorSink.reportRuntimeTaskException(
           `subscriber:${channelName}:automatic:${connectionId}:dispatch`,
           error
-        )
+        ),
+      this.applicationDispatchQueue(channelName)
     );
     this.subscriberReceiveLoops.push(loop);
     void taskRunner.run(`subscriber:${channelName}:automatic:${connectionId}`, (signal) =>
@@ -933,7 +965,8 @@ export class ZLinkChannelRuntimeLifecycle {
           taskRunner.errorSink.reportRuntimeTaskException(
             `route:${routeChannel.routerChannelId}:dispatch`,
             error
-          )
+          ),
+        this.applicationDispatchQueue(routeChannel.routerChannelId)
       );
       this.routeReceiveLoops.push(loop);
       tasks.push(

package/src/runtime/channels/channel-runtime-manager.ts

@@ -1,3 +1,4 @@
+import type { ZLinkListenerRecords } from '../foundation/listener-records';
 import type { ZLinkLocationOptionOverrides } from '../../contracts/Locations/Options';
 import type { RoutingId } from '../../contracts';
 import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
@@ -62,7 +63,8 @@ export class ZLinkChannelRuntimeManager {
       context,
       options.monitoringAdapter,
       options.oneWayFailureSink,
-      applicationJobQueue
+      applicationJobQueue,
+      options.listenerRecords
     );
     const codecs: ZLinkChannelEnvelopeCodecRegistry = {
       serializers: registration.messageSerializers
@@ -115,26 +117,16 @@ export class ZLinkChannelRuntimeManager {
   }
 
   fanoutTopology(channelName: string) {
-    return { descriptors: this.sockets.fanoutActiveTargets(channelName) };
-  }
-
-  getFanoutListenerStatus(channelName: string) {
-    const endpoint = this.sockets.fanoutPublisherEndpoint(channelName);
-    if (endpoint === undefined) {
-      throw new ZLinkConfigurationException(
-        `Fanout publisher '${channelName}' has not reported a bound listener.`
-      );
-    }
     return {
-      channelName,
-      endpoint,
-      observedAt: new Date()
+      descriptors:
+        this.lifecycle.fanoutTopologyTargets(channelName) ??
+        this.sockets.fanoutActiveTargets(channelName)
     };
   }
 
   observeClientServerTopology(channelName: string, changed: () => void): () => void {
     const monitor = this.sockets.clientServerMonitoringSource(channelName);
-    monitor.onEvent(changed);
+    monitor.onChange(changed);
     return () => {
       void monitor.dispose();
     };
@@ -447,6 +439,7 @@ function splitMonitoringSocketSourceName(sourceName: string): readonly [string,
 }
 
 export interface ZLinkChannelRuntimeManagerOptions {
+  readonly listenerRecords?: ZLinkListenerRecords;
   readonly internalRouteSendHandlers?: ReadonlyMap<string, ZLinkRouteRuntimeSendHandler>;
   readonly internalRouteRequestHandlers?: ReadonlyMap<string, ZLinkRouteRuntimeRequestHandler>;
   readonly monitoringAdapter?: ZLinkMonitoringBackendAdapter;

package/src/runtime/channels/channel-socket-options.ts

@@ -1,3 +1,7 @@
+import {
+  ZLINK_MAX_PUBLIC_WEIGHT,
+  isValidPublicWeight
+} from '../../contracts/Configuration/RegistrationBuilderPolicy';
 import type { ZLinkSocketConfig } from '../../contracts';
 import type { ZLinkSocketConfig as ZLinkRuntimeSocketConfig } from '../../contracts/Configuration';
 import { ZLinkConfigurationException } from '../configuration';
@@ -139,8 +143,10 @@ function requireChannelName(channelName: string): void {
 }
 
 function validatePublicWeight(value: number): void {
-  if (!Number.isInteger(value) || value < 0 || value > 10_000) {
-    throw new ZLinkConfigurationException('Weight must be an integer in 0..10000.');
+  if (!isValidPublicWeight(value)) {
+    throw new ZLinkConfigurationException(
+      `Weight must be an integer in 0..${ZLINK_MAX_PUBLIC_WEIGHT}.`
+    );
   }
 }