@zlink-systems/framework 0.11.0 → 0.13.0

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

@@ -1,7 +1,6 @@
 import type {
   Context,
   CoreHwmBudgetSnapshot,
-  Received,
   TopicMessage
 } from '@zlink-systems/zlink';
 import type { ZLinkCoreHwmOptions } from '../../../contracts/Configuration';
@@ -11,6 +10,7 @@ import type {
   ZLinkBackendDealerSocket,
   ZLinkBackendPublisherSocket,
   ZLinkBackendReadablePoller,
+  ZLinkBackendReceived,
   ZLinkBackendRouterSocket,
   ZLinkBackendSocket,
   ZLinkBackendSocketMonitor,
@@ -24,18 +24,15 @@ import type {
 import {
   closeWithBusyRetry,
   isContextTerminatedError,
-  isPollerInterruptedError,
   zlink,
   type ZLinkBindingModule
 } from './node-backend-adapter-support';
 import { wrapMonitorSocket } from './node-monitor-backend-adapter';
-import { wrapSocket } from './node-socket-backend-adapter';
+import { nodeEventLoopPollerOf, wrapSocket } from './node-socket-backend-adapter';
 import { ZLinkNodeMeshBackendAdapter } from './node-mesh-backend-adapter';
 
-export { isDisconnectRouteNotFoundError } from './node-socket-backend-adapter';
-
 export class ZLinkNodeBackendAdapterFactory implements ZLinkBackendAdapterFactory {
-  createReceived(): Received {
+  createReceived(): ZLinkBackendReceived {
     return new zlink.Received();
   }
 
@@ -70,11 +67,17 @@ class ZLinkNodeChannelBackendAdapter implements ZLinkChannelBackendAdapter {
   }
 
   createDealerSocket(context: ZLinkBackendContext): ZLinkBackendDealerSocket {
-    return wrapSocket(zlink.createDealerSocket(asNodeContext(context))) as unknown as ZLinkBackendDealerSocket;
+    return wrapSocket(
+      zlink.createDealerSocket(asNodeContext(context)),
+      true
+    ) as unknown as ZLinkBackendDealerSocket;
   }
 
   createRouterSocket(context: ZLinkBackendContext): ZLinkBackendRouterSocket {
-    return wrapSocket(zlink.createRouterSocket(asNodeContext(context))) as unknown as ZLinkBackendRouterSocket;
+    return wrapSocket(
+      zlink.createRouterSocket(asNodeContext(context)),
+      true
+    ) as unknown as ZLinkBackendRouterSocket;
   }
 
   createPublisherSocket(context: ZLinkBackendContext): ZLinkBackendPublisherSocket {
@@ -82,7 +85,10 @@ class ZLinkNodeChannelBackendAdapter implements ZLinkChannelBackendAdapter {
   }
 
   createSubscriberSocket(context: ZLinkBackendContext): ZLinkBackendSubscriberSocket {
-    return wrapSocket(zlink.createSubSocket(asNodeContext(context))) as unknown as ZLinkBackendSubscriberSocket;
+    return wrapSocket(
+      zlink.createSubSocket(asNodeContext(context)),
+      false
+    ) as unknown as ZLinkBackendSubscriberSocket;
   }
 
   createReadablePoller(socket: ZLinkBackendSubscriberSocket): ZLinkBackendReadablePoller {
@@ -94,7 +100,7 @@ class ZLinkNodeStreamBackendAdapter implements ZLinkStreamBackendAdapter {
   createStreamSocket(context: ZLinkBackendContext): ZLinkBackendStreamSocket {
     const socket = zlink.createStreamSocket(asNodeContext(context));
     socket.options.recvMode = zlink.StreamRecvMode.Packet;
-    return wrapSocket(socket) as unknown as ZLinkBackendStreamSocket;
+    return wrapSocket(socket, true) as unknown as ZLinkBackendStreamSocket;
   }
 
   createStreamPacket(): ZLinkBackendStreamPacket {
@@ -167,38 +173,63 @@ function asNodeContext(context: ZLinkBackendContext): Context {
 function createNodeReadablePoller(
   socket: { readonly nativeInstance: unknown }
 ): ZLinkBackendReadablePoller {
-  const poller = zlink.createPoller();
-  const events = zlink.createPollEvents(1);
-  try {
-    poller.add(socket.nativeInstance as never, [zlink.PollEventFlag.PollIn], 0);
-  } catch (error) {
-    events.close();
-    poller.close();
-    throw error;
-  }
+  const eventLoopPoller = nodeEventLoopPollerOf(socket);
   let disposed = false;
+  let readable = false;
+  let pending: {
+    readonly promise: Promise<boolean>;
+    readonly resolve: (readable: boolean) => void;
+    readonly signal?: AbortSignal;
+    readonly onAbort?: () => void;
+  } | undefined;
+
+  const settlePending = (value: boolean): void => {
+    const current = pending;
+    if (current === undefined) return;
+    pending = undefined;
+    if (current.signal !== undefined && current.onAbort !== undefined) {
+      current.signal.removeEventListener('abort', current.onAbort);
+    }
+    current.resolve(value);
+  };
+
+  eventLoopPoller.setReadableHandler(() => {
+    if (disposed) return;
+    readable = true;
+    settlePending(true);
+  });
+
   return {
-    wait(timeoutMs: number): boolean {
-      try {
-        return poller.wait(events, timeoutMs) > 0
-          && events.hasEvent(0, zlink.PollEventFlag.PollIn);
-      } catch (error) {
-        if (isPollerInterruptedError(error)) return false;
-        throw error;
+    wait(_timeoutMs: number): boolean {
+      return !disposed && readable;
+    },
+    waitForReadable(signal?: AbortSignal): Promise<boolean> {
+      if (disposed || signal?.aborted === true) return Promise.resolve(false);
+      if (readable) return Promise.resolve(true);
+      if (pending !== undefined) return pending.promise;
+
+      let resolvePending!: (value: boolean) => void;
+      const promise = new Promise<boolean>((resolve) => {
+        resolvePending = resolve;
+      });
+      const onAbort = signal === undefined
+        ? undefined
+        : (): void => settlePending(false);
+      pending = { promise, resolve: resolvePending, signal, onAbort };
+      if (signal !== undefined && onAbort !== undefined) {
+        signal.addEventListener('abort', onAbort, { once: true });
       }
+      return promise;
+    },
+    markDrained(): void {
+      readable = false;
     },
     dispose(): void {
       if (disposed) return;
       disposed = true;
-      try {
-        poller.remove(socket.nativeInstance as never);
-      } finally {
-        try {
-          events.close();
-        } finally {
-          poller.close();
-        }
-      }
+      readable = false;
+      settlePending(false);
+      eventLoopPoller.setReadableHandler(() => {});
     }
   };
 }

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

@@ -30,7 +30,7 @@ interface ZLinkBindingReplySubmitOperation {
 
 interface ZLinkBindingAsyncSendSubmitOperation {
   message(message: unknown): ZLinkBindingAsyncSendSubmitOperation;
-  submit(): Promise<void>;
+  submit(): import('@zlink-systems/zlink').SendSubmission;
   submit_sync(): void;
 }
 
@@ -41,7 +41,7 @@ export interface ZLinkBindingRequestOperation {
 interface ZLinkBindingRequestSubmitOperation {
   message(message: unknown): ZLinkBindingRequestSubmitOperation;
   timeout(timeoutMs: number): ZLinkBindingRequestSubmitOperation;
-  submit(): Promise<readonly unknown[]>;
+  submit(): import('@zlink-systems/zlink').RequestSubmission;
 }
 
 export function isBindingNotFound(error: unknown): boolean {
@@ -113,7 +113,7 @@ export async function submitBindingAsyncSend(
       current = current === undefined ? operation.message(nativePart) : current.message(nativePart);
     }
     current ??= operation.message(Buffer.alloc(0));
-    await current.submit();
+    await current.submit().admitted;
   } catch (error) {
     throw translateBindingResultError(error);
   }
@@ -156,7 +156,7 @@ export async function submitBindingRequest(
     if (timeoutMs !== undefined) {
       current = current.timeout(timeoutMs);
     }
-    return await current.submit();
+    return await current.submit().reply;
   } catch (error) {
     throw translateBindingResultError(error);
   }

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

@@ -54,7 +54,7 @@ export class ZLinkDealerChannelClientTransport implements ZLinkChannelClientTran
         true,
         metadata
       )
-    ).submit());
+    ).submit().admitted);
     return { status: ZLinkSubmitStatus.Submitted };
   }
 
@@ -83,7 +83,7 @@ export class ZLinkDealerChannelClientTransport implements ZLinkChannelClientTran
       )
     ));
     if (timeoutMs !== undefined) operation.timeout(timeoutMs);
-    const reply = await submitRequestOperation(operation, 'channel request');
+    const reply = await submitRequestOperation({ submit: () => operation.submit().reply }, 'channel request');
     try {
       return decodeChannelReply<TReply>(reply);
     } finally {

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

@@ -0,0 +1,55 @@
+import type {
+  BaseSocket,
+  PollEventFlagValue,
+  Socket
+} from '@zlink-systems/zlink';
+import { zlink } from './node-backend-adapter-support';
+
+/**
+ * Owns one binding public Poller and drives it from the socket's libuv
+ * readiness callback. PollCompletion is drained only by Poller.wait; the
+ * socket callback itself is only the event-loop wakeup.
+ */
+export class ZLinkNodeEventLoopPoller {
+  private readonly poller = zlink.createPoller();
+  private readonly events = zlink.createPollEvents(1);
+  private readableHandler: () => void;
+  private disposed = false;
+
+  constructor(
+    socket: Socket,
+    pollCompletion: boolean,
+    readableHandler: () => void
+  ) {
+    this.readableHandler = readableHandler;
+    try {
+      const pollEvents: PollEventFlagValue[] = [zlink.PollEventFlag.PollIn];
+      if (pollCompletion) pollEvents.push(zlink.PollEventFlag.PollCompletion);
+      this.poller.add(socket as BaseSocket, pollEvents, 0);
+      socket.setReadableHandler(this.onReady);
+    } catch (error) {
+      this.events.close();
+      this.poller.close();
+      throw error;
+    }
+  }
+
+  setReadableHandler(handler: () => void): void {
+    this.readableHandler = handler;
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.events.close();
+    this.poller.close();
+  }
+
+  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();
+    }
+  };
+}

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

@@ -5,11 +5,9 @@ import {
   RoutingId as BindingRoutingId,
   createContext,
   createDealerSocket,
-  createPollEvents,
-  createPoller,
   createRouterSocket,
-  PollEventFlag,
   ReceiveFlowState,
+  SubmitResult,
   type Context,
   type DealerSocket,
   type MonitorEvent,
@@ -24,8 +22,9 @@ import {
   type SendSubmitOperation,
   type Socket
 } from '@zlink-systems/zlink';
-import { isPollerInterruptedError, translateBindingResultError } from './node-backend-adapter-support';
+import { translateBindingResultError } from './node-backend-adapter-support';
 import { isEndpointCloseIgnorableError } from './node-socket-backend-adapter';
+import { ZLinkNodeEventLoopPoller } from './node-event-loop-poller';
 import type {
   ZLinkRawBindingPort,
   ZLinkRawDealerPort,
@@ -122,12 +121,20 @@ class NodeRawHostPort implements ZLinkRawHostPort {
 abstract class NodeRawSocketPort<TSocket extends Socket> implements ZLinkRawSocketPort {
   private readonly endpoints = new Set<string>();
   private readonly monitors = new Set<NodeRawMonitorPort>();
-  private readonly readablePoller = createPoller();
-  private readonly readableEvents = createPollEvents(1);
+  private readonly eventLoopPoller: ZLinkNodeEventLoopPoller;
   private closed = false;
 
   protected constructor(protected readonly socket: TSocket) {
-    this.readablePoller.add(socket as never, [PollEventFlag.PollIn], 0);
+    this.eventLoopPoller = new ZLinkNodeEventLoopPoller(
+      socket,
+      true,
+      () => {}
+    );
+  }
+
+  setReadableHandler(handler: () => void): void {
+    this.requireOpen();
+    this.eventLoopPoller.setReadableHandler(handler);
   }
 
   bind(endpoint: string): void {
@@ -172,6 +179,11 @@ abstract class NodeRawSocketPort<TSocket extends Socket> implements ZLinkRawSock
   close(): void {
     if (this.closed) return;
     const failures: unknown[] = [];
+    try {
+      this.eventLoopPoller.dispose();
+    } catch (error) {
+      failures.push(error);
+    }
     for (const monitor of [...this.monitors].reverse()) {
       try {
         monitor.close();
@@ -192,21 +204,6 @@ abstract class NodeRawSocketPort<TSocket extends Socket> implements ZLinkRawSock
       }
     }
     this.endpoints.clear();
-    try {
-      this.readablePoller.remove(this.socket as never);
-    } catch (error) {
-      failures.push(error);
-    }
-    try {
-      this.readableEvents.close();
-    } catch (error) {
-      failures.push(error);
-    }
-    try {
-      this.readablePoller.close();
-    } catch (error) {
-      failures.push(error);
-    }
     try {
       this.socket.close();
     } catch (error) {
@@ -222,24 +219,6 @@ abstract class NodeRawSocketPort<TSocket extends Socket> implements ZLinkRawSock
   protected requireOpen(): void {
     if (this.closed) throw new Error('Raw socket is closed.');
   }
-
-  protected receiveRecord(
-    dontWait: boolean
-  ): ZLinkRawReceivedRecord | undefined {
-    const timeoutMs = dontWait ? 0 : -1;
-    try {
-      if (
-        this.readablePoller.wait(this.readableEvents, timeoutMs) <= 0
-        || !this.readableEvents.hasEvent(0, PollEventFlag.PollIn)
-      ) {
-        return undefined;
-      }
-    } catch (error) {
-      if (isPollerInterruptedError(error)) return undefined;
-      throw error;
-    }
-    return receiveRecord(this.socket as never, true);
-  }
 }
 
 class NodeRawRouterPort extends NodeRawSocketPort<RouterSocket> implements ZLinkRawRouterPort {
@@ -276,10 +255,13 @@ class NodeRawRouterPort extends NodeRawSocketPort<RouterSocket> implements ZLink
 
   async send(targetRid: string, parts: readonly Uint8Array[]): Promise<void> {
     this.requireOpen();
-    await appendSendParts(
+    const submission = appendSendParts(
       this.socket.send(bindingRoutingId(targetRid)),
       parts
     ).submit();
+    if (submission.result === SubmitResult.Backpressured) {
+      await submission.admitted;
+    }
   }
 
   async request(
@@ -291,7 +273,7 @@ class NodeRawRouterPort extends NodeRawSocketPort<RouterSocket> implements ZLink
     try {
       const replies = await appendRequestParts(this.socket.request(bindingRoutingId(targetRid)), parts)
         .timeout(timeoutMs)
-        .submit();
+        .submit().reply;
       return copyAndClose(replies);
     } catch (error) {
       throw translateBindingResultError(error);
@@ -332,18 +314,21 @@ class NodeRawDealerPort extends NodeRawSocketPort<DealerSocket> implements ZLink
 
   async send(parts: readonly Uint8Array[]): Promise<void> {
     this.requireOpen();
-    await appendSendParts(this.socket.send(), parts).submit();
+    const submission = appendSendParts(this.socket.send(), parts).submit();
+    if (submission.result === SubmitResult.Backpressured) {
+      await submission.admitted;
+    }
   }
 
   async request(parts: readonly Uint8Array[], timeoutMs: number): Promise<readonly Buffer[]> {
     this.requireOpen();
-    const replies = await appendRequestParts(this.socket.request(), parts).timeout(timeoutMs).submit();
+    const replies = await appendRequestParts(this.socket.request(), parts).timeout(timeoutMs).submit().reply;
     return copyAndClose(replies);
   }
 
   receive(dontWait = false): ZLinkRawReceivedRecord | undefined {
     this.requireOpen();
-    return this.receiveRecord(dontWait);
+    return receiveRecord(this.socket, dontWait);
   }
 }