@zlink-systems/framework 0.25.0 → 0.27.0

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

@@ -6,7 +6,6 @@ import type {
   ZLinkBackendDealerSocket,
   ZLinkBackendPublisherSocket,
   ZLinkBackendReadablePoller,
-  ZLinkBackendReceived,
   ZLinkBackendRouterSocket,
   ZLinkBackendSocket,
   ZLinkBackendSocketMonitor,
@@ -17,21 +16,12 @@ import type {
   ZLinkMonitoringBackendAdapter,
   ZLinkStreamBackendAdapter
 } from '../contracts';
-import {
-  closeWithBusyRetry,
-  isContextTerminatedError,
-  zlink,
-  type ZLinkBindingModule
-} from './node-backend-adapter-support';
+import { closeBindingHandle, zlink, type ZLinkBindingModule } from './node-backend-adapter-support';
 import { wrapMonitorSocket } from './node-monitor-backend-adapter';
 import { nodeEventLoopPollerOf, wrapSocket } from './node-socket-backend-adapter';
 import { ZLinkNodeMeshBackendAdapter } from './node-mesh-backend-adapter';
 
 export class ZLinkNodeBackendAdapterFactory implements ZLinkBackendAdapterFactory {
-  createReceived(): ZLinkBackendReceived {
-    return new zlink.Received();
-  }
-
   createTopicMessage(): TopicMessage {
     return new zlink.TopicMessage();
   }
@@ -96,7 +86,8 @@ class ZLinkNodeChannelBackendAdapter implements ZLinkChannelBackendAdapter {
 
 class ZLinkNodeStreamBackendAdapter implements ZLinkStreamBackendAdapter {
   createStreamSocket(context: ZLinkBackendContext): ZLinkBackendStreamSocket {
-    const socket = zlink.createStreamSocket(asNodeContext(context));
+    const nodeContext = asNodeContext(context);
+    const socket = zlink.createStreamSocket(nodeContext);
     socket.options.recvMode = zlink.StreamRecvMode.Packet;
     return wrapSocket(socket, true) as unknown as ZLinkBackendStreamSocket;
   }
@@ -148,19 +139,8 @@ class ZLinkNodeBackendContext implements ZLinkBackendContext {
   }
 
   async dispose(): Promise<void> {
-    // Terminal cleanup shuts the context down before terminating it, the same
-    // sequence the .NET reference binding runs inside `Context.Dispose()`
-    // (`zlink_ctx_shutdown` then `zlink_ctx_term`). Without the shutdown signal
-    // termination can block forever waiting on the reaper even after every
-    // socket this runtime owns has been closed.
-    try {
-      this.nativeInstance.shutdown();
-    } catch (error) {
-      if (!isContextTerminatedError(error)) {
-        throw error;
-      }
-    }
-    await closeWithBusyRetry(this.nativeInstance);
+    // Binding Context.close() shuts down and then terminates the native context.
+    closeBindingHandle(this.nativeInstance);
   }
 
   close(): void {

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

@@ -1,6 +1,8 @@
+import { constants as osConstants } from 'node:os';
+import { requireOneWayCompletion, ZLinkSubmitStatus } from '../../messaging/submission-result';
 import { loadBinding } from '../node-backend-adapter';
 import { SubmitResult, ZLinkBackendResultError } from '../runtime-values';
-import { requireOneWayCompletion, ZLinkSubmitStatus } from '../../messaging/submission-result';
+const nativeErrnoValues = osConstants.errno;
 
 export type ZLinkBindingModule = typeof import('@zlink-systems/zlink');
 export const zlink = loadBinding() as ZLinkBindingModule;
@@ -46,7 +48,7 @@ interface ZLinkBindingRequestSubmitOperation {
 }
 
 export function isBindingNotFound(error: unknown): boolean {
-  return error instanceof zlink.ConfigError && error.result === zlink.ConfigResult.NotFound;
+  return error instanceof zlink.ConnectError && error.result === zlink.ConnectResult.NotFound;
 }
 
 function isNonBlockingRecvEmpty(error: unknown): boolean {
@@ -63,12 +65,11 @@ export function isRouteRecvRetryable(error: unknown): boolean {
   );
 }
 
-export function isPollerInterruptedError(error: unknown): boolean {
-  return error instanceof zlink.RecvError && error.nativeErrno === 4;
-}
-
 function isNativeBadAddress(error: { nativeErrno?: unknown; message?: unknown }): boolean {
-  return error.nativeErrno === 14 || /Bad address/i.test(String(error.message ?? ''));
+  return (
+    error.nativeErrno === nativeErrnoValues.EFAULT ||
+    /Bad address/i.test(String(error.message ?? ''))
+  );
 }
 
 export function submitBindingPublish(
@@ -176,32 +177,16 @@ export async function submitBindingRequest(
   }
 }
 
-export async function closeWithBusyRetry(target: { close(): void }): Promise<void> {
-  let lastError: unknown;
-  for (let attempt = 0; attempt < 8; attempt++) {
-    try {
-      target.close();
-      return;
-    } catch (error) {
-      if (isSuccessfulOrAlreadyShutdownCloseError(error)) {
-        return;
-      }
-      if (!isBusyCloseError(error)) {
-        throw error;
-      }
-      lastError = error;
-      await new Promise<void>((resolve) => setImmediate(resolve));
-    }
+/**
+ * Closes a binding handle once. An already closed or terminated handle counts as
+ * closed. A busy close propagates to the caller.
+ */
+export function closeBindingHandle(target: { close(): void }): void {
+  try {
+    target.close();
+  } catch (error) {
+    if (!isSuccessfulOrAlreadyShutdownCloseError(error)) throw error;
   }
-  throw lastError;
-}
-
-function isBusyCloseError(error: unknown): boolean {
-  return (
-    error instanceof Error &&
-    'code' in error &&
-    [401, 404].includes((error as { code: number }).code)
-  );
 }
 
 function isSuccessfulOrAlreadyShutdownCloseError(error: unknown): boolean {
@@ -209,7 +194,13 @@ function isSuccessfulOrAlreadyShutdownCloseError(error: unknown): boolean {
     isContextTerminatedError(error) ||
     (error instanceof Error &&
       'code' in error &&
-      [0, 402, 403].includes((error as { code: number }).code))
+      (
+        [
+          zlink.CloseResult.Ok,
+          zlink.CloseResult.Shutdown,
+          zlink.CloseResult.InvalidHandle
+        ] as readonly number[]
+      ).includes((error as { code: number }).code))
   );
 }
 
@@ -259,9 +250,15 @@ function toNativeMessageLike(message: unknown): unknown {
   return message;
 }
 
-export function translateBindingResultError(error: unknown): unknown {
+export function translateBindingResultError(
+  error: unknown,
+  phase: 'submit' | 'completion' = 'completion'
+): unknown {
   if (error instanceof zlink.SubmitError) {
-    return new ZLinkBackendResultError('submit', error.result, error.nativeErrno, { cause: error });
+    return new ZLinkBackendResultError('submit', error.result, error.nativeErrno, {
+      cause: error,
+      phase
+    });
   }
   if (error instanceof zlink.RequestError) {
     return new ZLinkBackendResultError('request', error.result, error.nativeErrno, {

package/src/runtime/backend/node/node-event-loop-poller.ts

@@ -9,14 +9,22 @@ import { zlink } from './node-backend-adapter-support';
 export class ZLinkNodeEventLoopPoller {
   private readonly poller = zlink.createPoller();
   private readonly events = zlink.createPollEvents(1);
-  private readableHandler: () => void;
+  private readableHandler: (receiveReady: boolean, routeReady: boolean) => void;
   private disposed = false;
 
-  constructor(socket: Socket, pollCompletion: boolean, readableHandler: () => void) {
+  constructor(
+    socket: Socket,
+    pollCompletion: boolean,
+    readableHandler: (receiveReady: boolean, routeReady: boolean) => void,
+    pollRoute = false
+  ) {
     this.readableHandler = readableHandler;
     try {
       const pollEvents: PollEventFlagValue[] = [zlink.PollEventFlag.PollIn];
       if (pollCompletion) pollEvents.push(zlink.PollEventFlag.PollCompletion);
+      // A ROUTER selected-route change (Core ROUTER §10.1) wakes the same
+      // handler, whose owner is the socket's one route observer.
+      if (pollRoute) pollEvents.push(zlink.PollEventFlag.PollRoute);
       this.poller.add(socket as BaseSocket, pollEvents, 0);
       socket.setReadableHandler(this.onReady);
     } catch (error) {
@@ -26,22 +34,22 @@ export class ZLinkNodeEventLoopPoller {
     }
   }
 
-  setReadableHandler(handler: () => void): void {
+  setReadableHandler(handler: (receiveReady: boolean, routeReady: boolean) => void): void {
     this.readableHandler = handler;
   }
 
   dispose(): void {
     if (this.disposed) return;
-    this.disposed = true;
-    this.events.close();
     this.poller.close();
+    this.events.close();
+    this.disposed = true;
   }
 
   private readonly onReady = (): void => {
     if (this.disposed) return;
     const ready = this.poller.wait(this.events, 0);
-    if (ready === 0 || this.events.hasEvent(0, zlink.PollEventFlag.PollIn)) {
-      this.readableHandler();
-    }
+    const receiveReady = ready === 0 || this.events.hasEvent(0, zlink.PollEventFlag.PollIn);
+    const routeReady = ready > 0 && this.events.hasEvent(0, zlink.PollEventFlag.PollRoute);
+    if (receiveReady || routeReady) this.readableHandler(receiveReady, routeReady);
   };
 }

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

@@ -32,6 +32,7 @@ export function wrapMonitorSocket(nativeInstance: {
 function toBackendMonitorEvent(event: MonitorEvent): ZLinkBackendSocketMonitorEvent {
   return {
     nativeEvent: event.event,
+    readyEdge: (event.flags & zlink.MonitorEventFlag.ConnectionReadyEdge) !== 0,
     routingId: event.routingId ?? undefined,
     localAddr: event.localAddr,
     remoteAddr: event.remoteAddr,

package/src/runtime/backend/node/node-raw-binding-port.ts

@@ -33,6 +33,7 @@ import type {
   ZLinkRawMonitorRecord,
   ZLinkRawReceivedRecord,
   ZLinkRawRouterPort,
+  ZLinkRawRouterRoute,
   ZLinkRawSocketPort
 } from '../raw-binding-port';
 export type {
@@ -43,6 +44,7 @@ export type {
   ZLinkRawMonitorRecord,
   ZLinkRawReceivedRecord,
   ZLinkRawRouterPort,
+  ZLinkRawRouterRoute,
   ZLinkRawSocketPort
 } from '../raw-binding-port';
 
@@ -93,24 +95,25 @@ class NodeRawHostPort implements ZLinkRawHostPort {
     if (this.state === 'closed') return;
     this.state = 'stopping';
     const failures: unknown[] = [];
-    for (const resource of this.resources.splice(0).reverse()) {
+    for (const resource of [...this.resources].reverse()) {
       try {
         resource.close();
+        this.resources.splice(this.resources.indexOf(resource), 1);
       } catch (error) {
         failures.push(error);
       }
     }
-    if (this.ownsContext) {
+    if (this.ownsContext && failures.length === 0) {
       try {
         this.context.close();
       } catch (error) {
         failures.push(error);
       }
     }
-    this.state = 'closed';
     if (failures.length > 0) {
       throw new AggregateError(failures, 'Raw binding host cleanup failed.');
     }
+    this.state = 'closed';
   }
 
   private own<T extends { close(): void }>(resource: T): T {
@@ -131,11 +134,14 @@ abstract class NodeRawSocketPort<TSocket extends Socket> implements ZLinkRawSock
   private readonly eventLoopPoller: ZLinkNodeEventLoopPoller;
   private closed = false;
 
-  protected constructor(protected readonly socket: TSocket) {
-    this.eventLoopPoller = new ZLinkNodeEventLoopPoller(socket, true, () => {});
+  protected constructor(
+    protected readonly socket: TSocket,
+    pollRoute = false
+  ) {
+    this.eventLoopPoller = new ZLinkNodeEventLoopPoller(socket, true, () => {}, pollRoute);
   }
 
-  setReadableHandler(handler: () => void): void {
+  setReadableHandler(handler: (receiveReady: boolean, routeReady: boolean) => void): void {
     this.requireOpen();
     this.eventLoopPoller.setReadableHandler(handler);
   }
@@ -206,17 +212,16 @@ abstract class NodeRawSocketPort<TSocket extends Socket> implements ZLinkRawSock
         failures.push(error);
       }
     }
+    if (failures.length > 0) {
+      throw new AggregateError(failures, 'Raw socket cleanup failed.');
+    }
     this.endpoints.clear();
     try {
       this.socket.close();
     } catch (error) {
-      failures.push(error);
+      throw new AggregateError([error], 'Raw socket cleanup failed.');
     }
     this.closed = true;
-    if (failures.length > 0) {
-      console.error('Raw socket cleanup causes:', failures);
-      throw new AggregateError(failures, 'Raw socket cleanup failed.');
-    }
   }
 
   protected requireOpen(): void {
@@ -236,7 +241,7 @@ class NodeRawRouterPort extends NodeRawSocketPort<RouterSocket> implements ZLink
   }
 
   constructor(socket: RouterSocket, receiveTimeoutMs?: number) {
-    super(socket);
+    super(socket, true);
     socket.options.handover = true;
     socket.options.mandatory = true;
     socket.options.probe = true;
@@ -278,19 +283,30 @@ class NodeRawRouterPort extends NodeRawSocketPort<RouterSocket> implements ZLink
     timeoutMs: number
   ): Promise<readonly Buffer[]> {
     this.requireOpen();
+    let submission: ReturnType<RequestSubmitOperation['submit']>;
     try {
-      const replies = await appendRequestParts(
-        this.socket.request(bindingRoutingId(targetRid)),
-        parts
-      )
+      submission = appendRequestParts(this.socket.request(bindingRoutingId(targetRid)), parts)
         .timeout(timeoutMs)
-        .submit().reply;
+        .submit();
+    } catch (error) {
+      throw translateBindingResultError(error, 'submit');
+    }
+    try {
+      const replies = await requestReply(submission);
       return copyAndClose(replies);
     } catch (error) {
-      throw translateBindingResultError(error);
+      throw translateBindingResultError(error, 'completion');
     }
   }
 
+  routesSnapshot(): readonly ZLinkRawRouterRoute[] {
+    this.requireOpen();
+    return this.socket.routesSnapshot().map((route) => ({
+      routingId: route.routingId.toString(),
+      routeGeneration: route.routeGeneration
+    }));
+  }
+
   receive(dontWait = false): ZLinkRawReceivedRecord | undefined {
     this.requireOpen();
     return receiveRecord(
@@ -332,10 +348,18 @@ class NodeRawDealerPort extends NodeRawSocketPort<DealerSocket> implements ZLink
 
   async request(parts: readonly Uint8Array[], timeoutMs: number): Promise<readonly Buffer[]> {
     this.requireOpen();
-    const replies = await appendRequestParts(this.socket.request(), parts)
-      .timeout(timeoutMs)
-      .submit().reply;
-    return copyAndClose(replies);
+    let submission: ReturnType<RequestSubmitOperation['submit']>;
+    try {
+      submission = appendRequestParts(this.socket.request(), parts).timeout(timeoutMs).submit();
+    } catch (error) {
+      throw translateBindingResultError(error, 'submit');
+    }
+    try {
+      const replies = await requestReply(submission);
+      return copyAndClose(replies);
+    } catch (error) {
+      throw translateBindingResultError(error, 'completion');
+    }
   }
 
   receive(dontWait = false): ZLinkRawReceivedRecord | undefined {
@@ -344,6 +368,16 @@ class NodeRawDealerPort extends NodeRawSocketPort<DealerSocket> implements ZLink
   }
 }
 
+async function requestReply(
+  submission: ReturnType<RequestSubmitOperation['submit']>
+): Promise<Message[]> {
+  if (submission.result === SubmitResult.Backpressured) {
+    const [, replies] = await Promise.all([submission.admitted, submission.reply]);
+    return replies;
+  }
+  return submission.reply;
+}
+
 class NodeRawMonitorPort implements ZLinkRawMonitorPort {
   private closed = false;
 
@@ -370,9 +404,9 @@ class NodeRawMonitorPort implements ZLinkRawMonitorPort {
 
   close(): void {
     if (this.closed) return;
+    this.monitor.close();
     this.closed = true;
     this.release();
-    this.monitor.close();
   }
 }
 
@@ -450,6 +484,7 @@ function receiveRecord(
     return {
       sourceRid,
       sourceRoute,
+      routeGeneration: received.routeGeneration,
       ...(requestSeq === undefined ? {} : { requestSeq }),
       ...(receivedReply === undefined
         ? {}