@enbox/dwn-server 0.0.2 → 0.0.4

package/dist/esm/src/connection/flow-controller.js

@@ -0,0 +1,101 @@
+import log from 'loglevel';
+import { createJsonRpcSuccessResponse } from '@enbox/dwn-clients';
+/** Default maximum number of unacknowledged events before pausing delivery. */
+export const DEFAULT_MAX_IN_FLIGHT = 32;
+/** Maximum buffer size before the subscription is force-closed to prevent OOM. */
+export const MAX_BUFFER_SIZE = 1000;
+/**
+ * Per-subscription flow controller that enforces a sliding window of
+ * unacknowledged events. When the window is full, incoming events are
+ * buffered. When the client sends `rpc.ack` with a cursor, events up
+ * to that cursor are acknowledged and buffered events are flushed.
+ *
+ * If the buffer exceeds {@link MAX_BUFFER_SIZE}, the subscription is
+ * closed via the provided `onOverflow` callback to prevent unbounded
+ * memory growth.
+ */
+export class FlowController {
+    subscriptionId;
+    maxInFlight;
+    send;
+    onOverflow;
+    /** Ordered list of cursors for events that have been sent but not yet acknowledged. */
+    unacked = [];
+    /** Buffer of events waiting to be sent once the window opens. */
+    buffer = [];
+    /** Whether the controller has been closed due to overflow. */
+    closed = false;
+    constructor(subscriptionId, maxInFlight, send, onOverflow) {
+        this.subscriptionId = subscriptionId;
+        this.maxInFlight = maxInFlight;
+        this.send = send;
+        this.onOverflow = onOverflow;
+    }
+    /**
+     * Accept an incoming {@link SubscriptionMessage} from the EventLog listener.
+     * If the window has room, send immediately. Otherwise buffer.
+     */
+    push(message) {
+        if (this.closed) {
+            return;
+        }
+        if (this.unacked.length < this.maxInFlight) {
+            this.sendMessage(message);
+        }
+        else {
+            this.buffer.push(message);
+            if (this.buffer.length > MAX_BUFFER_SIZE) {
+                log.warn(`FlowController: buffer overflow for subscription ${String(this.subscriptionId)}, ` +
+                    `closing subscription (buffer=${this.buffer.length}, unacked=${this.unacked.length})`);
+                this.closed = true;
+                this.buffer = [];
+                this.unacked = [];
+                this.onOverflow();
+            }
+        }
+    }
+    /**
+     * Process an `rpc.ack` for this subscription. Acknowledges all events up
+     * to and including the given cursor, then flushes buffered events into the
+     * newly opened window slots.
+     */
+    ack(cursor) {
+        if (this.closed) {
+            return;
+        }
+        const idx = this.unacked.lastIndexOf(cursor);
+        if (idx === -1) {
+            // Unknown cursor — could be a stale or duplicate ack. Ignore silently.
+            log.debug(`FlowController: unknown cursor in ack for subscription ${String(this.subscriptionId)}: ${cursor}`);
+            return;
+        }
+        // Remove all entries up to and including the acked cursor.
+        this.unacked.splice(0, idx + 1);
+        // Flush buffered messages into the freed window slots.
+        while (this.buffer.length > 0 && this.unacked.length < this.maxInFlight) {
+            const buffered = this.buffer.shift();
+            this.sendMessage(buffered);
+        }
+    }
+    /**
+     * Returns the number of events currently in flight (sent but unacknowledged).
+     */
+    get inFlightCount() {
+        return this.unacked.length;
+    }
+    /**
+     * Returns the number of events currently buffered (waiting to be sent).
+     */
+    get bufferCount() {
+        return this.buffer.length;
+    }
+    /**
+     * Sends a single message over the wire and tracks its cursor.
+     */
+    sendMessage(message) {
+        const response = createJsonRpcSuccessResponse(this.subscriptionId, { subscription: message });
+        this.send(response);
+        this.unacked.push(message.cursor);
+    }
+}
+//# sourceMappingURL=flow-controller.js.map

package/dist/esm/src/connection/flow-controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-controller.js","sourceRoot":"","sources":["../../../../src/connection/flow-controller.ts"],"names":[],"mappings":"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"}

package/dist/esm/src/connection/socket-connection.d.ts

@@ -1,18 +1,46 @@
-import type { Dwn } from "@enbox/dwn-sdk-js";
-import type { WebSocket } from "ws";
-import type { JsonRpcId, JsonRpcSubscription } from "../lib/json-rpc.js";
+import type { ActivityLog } from '../admin/activity-log.js';
+import type { AdminConnectionSnapshot } from '../admin/types.js';
+import type { AdminStore } from '../admin/admin-store.js';
+import type { DwnServerConfig } from '../config.js';
+import type { MessageProcessedHook } from '../message-processed-hook.js';
+import type { RateLimiter } from '../rate-limiter.js';
+import type { RegistrationStore } from '../registration/registration-store.js';
+import type { ServerWebSocket } from 'bun';
+import type { WsData } from '../http-api.js';
+import type { Dwn } from '@enbox/dwn-sdk-js';
+import type { JsonRpcId, JsonRpcSubscription } from '@enbox/dwn-clients';
 /**
  * SocketConnection handles a WebSocket connection to a DWN using JSON RPC.
  * It also manages references to the long running RPC subscriptions for the connection.
+ *
+ * With Bun's native WebSocket, the message/close/error events are dispatched by the
+ * Bun.serve() websocket handlers in http-api.ts, which delegate to the public `message()`
+ * and `close()` methods on this class.
  */
 export declare class SocketConnection {
     private socket;
     private dwn;
-    private onClose?;
+    private onCloseCallback?;
+    private maxInFlight;
+    private activityLog?;
+    private adminStore?;
+    private registrationStore?;
+    private serverConfig?;
+    private tenantRateLimiter?;
+    private messageProcessedHooks?;
+    /** Unique identifier for this connection (for admin introspection). */
+    readonly id: string;
+    /** Timestamp when the connection was established (for admin introspection). */
+    readonly connectedAt: number;
     private heartbeatInterval;
     private subscriptions;
+    private flowControllers;
     private isAlive;
-    constructor(socket: WebSocket, dwn: Dwn, onClose?: () => void);
+    constructor(socket: ServerWebSocket<WsData>, dwn: Dwn, onCloseCallback?: () => void, maxInFlight?: number, activityLog?: ActivityLog, adminStore?: AdminStore, registrationStore?: RegistrationStore, serverConfig?: DwnServerConfig, tenantRateLimiter?: RateLimiter, messageProcessedHooks?: MessageProcessedHook[]);
+    /**
+     * Called when a pong is received (triggered by Bun's built-in ping/pong handling).
+     */
+    pong(): void;
     /**
      * Checks to see if the incoming `JsonRpcId` is already in use for a subscription.
      */
@@ -29,36 +57,44 @@ export declare class SocketConnection {
      */
     closeSubscription(id: JsonRpcId): Promise<void>;
     /**
-     * Closes the existing connection and cleans up any listeners or subscriptions.
+     * Acknowledges subscription events up to the given cursor, advancing the
+     * flow-control window for the subscription.
      */
-    close(): Promise<void>;
+    ackSubscription(id: JsonRpcId, cursor: string): void;
     /**
-     * Pong messages are automatically sent in response to ping messages as required by
-     * the websocket spec. So, no need to send explicit pongs.
+     * Closes the existing connection and cleans up any listeners or subscriptions.
      */
-    private pong;
+    close(): Promise<void>;
     /**
      * Log the error and close the connection.
      */
-    private error;
+    error(error: Error): Promise<void>;
     /**
      * Handles a `JSON RPC 2.0` encoded message.
+     * This is called by Bun's websocket message handler via http-api.ts.
      */
-    private message;
+    message(dataBuffer: Buffer): Promise<void>;
     /**
-     * Sends a JSON encoded Buffer through the Websocket.
+     * Returns the number of active subscriptions on this connection.
+     */
+    get subscriptionCount(): number;
+    /**
+     * Returns a serializable snapshot of this connection for the admin inspector.
+     */
+    toSnapshot(): AdminConnectionSnapshot;
+    /**
+     * Sends a JSON encoded string through the WebSocket.
      */
     private send;
     /**
-     * Creates a subscription handler to send messages matching the subscription requested.
-     *
-     * Wraps the incoming `message` in a `JSON RPC Success Response` using the original subscription`JSON RPC Id` to send through the WebSocket.
+     * Creates a flow-controlled subscription handler that enforces the
+     * `maxInFlight` window. Returns a `SubscriptionListener` to be passed
+     * to the EventLog, and stores the `FlowController` for later `rpc.ack`
+     * processing.
      */
     private createSubscriptionHandler;
     /**
      * Builds a `RequestContext` object to use with the `JSON RPC API`.
-     *
-     * Adds a `subscriptionHandler` for `Subscribe` messages.
      */
     private buildRequestContext;
 }

package/dist/esm/src/connection/socket-connection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"socket-connection.d.ts","sourceRoot":"","sources":["../../../../src/connection/socket-connection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAgC,MAAM,mBAAmB,CAAC;AAG3E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAKpC,OAAO,KAAK,EAAwB,SAAS,EAAmC,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAShI;;;GAGG;AACH,qBAAa,gBAAgB;IAMzB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,GAAG;IACX,OAAO,CAAC,OAAO,CAAC;IAPlB,OAAO,CAAC,iBAAiB,CAAe;IACxC,OAAO,CAAC,aAAa,CAAkD;IACvE,OAAO,CAAC,OAAO,CAAU;gBAGf,MAAM,EAAE,SAAS,EACjB,GAAG,EAAE,GAAG,EACR,OAAO,CAAC,EAAE,MAAM,IAAI;IAsB9B;;OAEG;IACH,eAAe,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO;IAIvC;;;OAGG;IACG,eAAe,CAAC,YAAY,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAWvE;;;;OAIG;IACG,iBAAiB,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAarD;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAwB5B;;;OAGG;IACH,OAAO,CAAC,IAAI;IAIZ;;OAEG;YACW,KAAK;IAMnB;;OAEG;YACW,OAAO;IAmCrB;;OAEG;IACH,OAAO,CAAC,IAAI;IAIZ;;;;OAIG;IACH,OAAO,CAAC,yBAAyB;IAOjC;;;;OAIG;YACW,mBAAmB;CAuBlC"}
+{"version":3,"file":"socket-connection.d.ts","sourceRoot":"","sources":["../../../../src/connection/socket-connection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAE/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,KAAK,CAAC;AAC3C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,KAAK,EAAE,GAAG,EAAuC,MAAM,mBAAmB,CAAC;AAClF,OAAO,KAAK,EAAwB,SAAS,EAAmC,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAchI;;;;;;;GAOG;AACH,qBAAa,gBAAgB;IAazB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,GAAG;IACX,OAAO,CAAC,eAAe,CAAC;IACxB,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,WAAW,CAAC;IACpB,OAAO,CAAC,UAAU,CAAC;IACnB,OAAO,CAAC,iBAAiB,CAAC;IAC1B,OAAO,CAAC,YAAY,CAAC;IACrB,OAAO,CAAC,iBAAiB,CAAC;IAC1B,OAAO,CAAC,qBAAqB,CAAC;IArBhC,uEAAuE;IACvE,SAAgB,EAAE,EAAE,MAAM,CAAY;IAEtC,+EAA+E;IAC/E,SAAgB,WAAW,EAAE,MAAM,CAAc;IAEjD,OAAO,CAAC,iBAAiB,CAAiC;IAC1D,OAAO,CAAC,aAAa,CAAkD;IACvE,OAAO,CAAC,eAAe,CAA6C;IACpE,OAAO,CAAC,OAAO,CAAU;gBAGf,MAAM,EAAE,eAAe,CAAC,MAAM,CAAC,EAC/B,GAAG,EAAE,GAAG,EACR,eAAe,CAAC,EAAE,MAAM,IAAI,EAC5B,WAAW,GAAE,MAA8B,EAC3C,WAAW,CAAC,EAAE,WAAW,EACzB,UAAU,CAAC,EAAE,UAAU,EACvB,iBAAiB,CAAC,EAAE,iBAAiB,EACrC,YAAY,CAAC,EAAE,eAAe,EAC9B,iBAAiB,CAAC,EAAE,WAAW,EAC/B,qBAAqB,CAAC,EAAE,oBAAoB,EAAE;IAexD;;OAEG;IACH,IAAI,IAAI,IAAI;IAIZ;;OAEG;IACH,eAAe,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO;IAIvC;;;OAGG;IACG,eAAe,CAAC,YAAY,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAWvE;;;;OAIG;IACG,iBAAiB,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAcrD;;;OAGG;IACH,eAAe,CAAC,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAOpD;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAwB5B;;OAEG;IACG,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;IAMxC;;;OAGG;IACG,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmChD;;OAEG;IACH,IAAI,iBAAiB,IAAI,MAAM,CAE9B;IAED;;OAEG;IACH,UAAU,IAAI,uBAAuB;IAiBrC;;OAEG;IACH,OAAO,CAAC,IAAI;IAIZ;;;;;OAKG;IACH,OAAO,CAAC,yBAAyB;IAsBjC;;OAEG;YACW,mBAAmB;CA4BlC"}

package/dist/esm/src/connection/socket-connection.js

@@ -1,44 +1,68 @@
-import { DwnMethodName } from "@enbox/dwn-sdk-js";
 import log from 'loglevel';
+import { DwnMethodName } from '@enbox/dwn-sdk-js';
+import { jsonRpcRouter } from '../json-rpc-api.js';
+import { requestCounter } from '../metrics.js';
 import { v4 as uuidv4 } from 'uuid';
-import { requestCounter } from "../metrics.js";
-import { jsonRpcRouter } from "../json-rpc-api.js";
-import { JsonRpcErrorCodes, createJsonRpcErrorResponse, createJsonRpcSuccessResponse } from "../lib/json-rpc.js";
-import { DwnServerError, DwnServerErrorCode } from "../dwn-error.js";
+import { createJsonRpcErrorResponse, JsonRpcErrorCodes } from '@enbox/dwn-clients';
+import { DEFAULT_MAX_IN_FLIGHT, FlowController } from './flow-controller.js';
+import { DwnServerError, DwnServerErrorCode } from '../dwn-error.js';
 const HEARTBEAT_INTERVAL = 30_000;
 /**
  * SocketConnection handles a WebSocket connection to a DWN using JSON RPC.
  * It also manages references to the long running RPC subscriptions for the connection.
+ *
+ * With Bun's native WebSocket, the message/close/error events are dispatched by the
+ * Bun.serve() websocket handlers in http-api.ts, which delegate to the public `message()`
+ * and `close()` methods on this class.
  */
 export class SocketConnection {
     socket;
     dwn;
-    onClose;
+    onCloseCallback;
+    maxInFlight;
+    activityLog;
+    adminStore;
+    registrationStore;
+    serverConfig;
+    tenantRateLimiter;
+    messageProcessedHooks;
+    /** Unique identifier for this connection (for admin introspection). */
+    id = uuidv4();
+    /** Timestamp when the connection was established (for admin introspection). */
+    connectedAt = Date.now();
     heartbeatInterval;
     subscriptions = new Map();
+    flowControllers = new Map();
     isAlive;
-    constructor(socket, dwn, onClose) {
+    constructor(socket, dwn, onCloseCallback, maxInFlight = DEFAULT_MAX_IN_FLIGHT, activityLog, adminStore, registrationStore, serverConfig, tenantRateLimiter, messageProcessedHooks) {
         this.socket = socket;
         this.dwn = dwn;
-        this.onClose = onClose;
-        socket.on('message', this.message.bind(this));
-        socket.on('close', this.close.bind(this));
-        socket.on('error', this.error.bind(this));
-        socket.on('pong', this.pong.bind(this));
-        // Sometimes connections between client <-> server can get borked in such a way that
-        // leaves both unaware of the borkage. ping messages can be used as a means to verify
-        // that the remote endpoint is still responsive. Server will ping each socket every 30s
-        // if a pong hasn't received from a socket by the next ping, the server will terminate
-        // the socket connection
+        this.onCloseCallback = onCloseCallback;
+        this.maxInFlight = maxInFlight;
+        this.activityLog = activityLog;
+        this.adminStore = adminStore;
+        this.registrationStore = registrationStore;
+        this.serverConfig = serverConfig;
+        this.tenantRateLimiter = tenantRateLimiter;
+        this.messageProcessedHooks = messageProcessedHooks;
+        // Bun handles ping/pong automatically at the protocol level, but we still
+        // want an application-level heartbeat to detect dead connections.
         this.isAlive = true;
         this.heartbeatInterval = setInterval(() => {
             if (this.isAlive === false) {
                 this.close();
+                return;
             }
             this.isAlive = false;
             this.socket.ping();
         }, HEARTBEAT_INTERVAL);
     }
+    /**
+     * Called when a pong is received (triggered by Bun's built-in ping/pong handling).
+     */
+    pong() {
+        this.isAlive = true;
+    }
     /**
      * Checks to see if the incoming `JsonRpcId` is already in use for a subscription.
      */
@@ -67,14 +91,23 @@ export class SocketConnection {
         const connection = this.subscriptions.get(id);
         await connection.close();
         this.subscriptions.delete(id);
+        this.flowControllers.delete(id);
+    }
+    /**
+     * Acknowledges subscription events up to the given cursor, advancing the
+     * flow-control window for the subscription.
+     */
+    ackSubscription(id, cursor) {
+        const fc = this.flowControllers.get(id);
+        if (fc) {
+            fc.ack(cursor);
+        }
     }
     /**
      * Closes the existing connection and cleans up any listeners or subscriptions.
      */
     async close() {
         clearInterval(this.heartbeatInterval);
-        // clean up all socket event listeners
-        this.socket.removeAllListeners();
         const closePromises = [];
         for (const [id, subscription] of this.subscriptions) {
             closePromises.push(subscription.close());
@@ -82,30 +115,26 @@ export class SocketConnection {
         }
         // close all of the associated subscriptions
         await Promise.all(closePromises);
+        // clear all flow controllers
+        this.flowControllers.clear();
         // close the socket.
         this.socket.close();
         // if there was a close handler passed call it after the connection has been closed
-        if (this.onClose !== undefined) {
-            this.onClose();
+        if (this.onCloseCallback !== undefined) {
+            this.onCloseCallback();
         }
     }
-    /**
-     * Pong messages are automatically sent in response to ping messages as required by
-     * the websocket spec. So, no need to send explicit pongs.
-     */
-    pong() {
-        this.isAlive = true;
-    }
     /**
      * Log the error and close the connection.
      */
     async error(error) {
         log.error(`SocketConnection error, terminating connection`, error);
-        this.socket.terminate();
+        this.socket.close();
         await this.close();
     }
     /**
      * Handles a `JSON RPC 2.0` encoded message.
+     * This is called by Bun's websocket message handler via http-api.ts.
      */
     async message(dataBuffer) {
         const requestData = dataBuffer.toString();
@@ -120,7 +149,6 @@ export class SocketConnection {
             const errorResponse = createJsonRpcErrorResponse(uuidv4(), JsonRpcErrorCodes.BadRequest, error.message);
             return this.send(errorResponse);
         }
-        ;
         const requestContext = await this.buildRequestContext(jsonRequest);
         const { jsonRpcResponse } = await jsonRpcRouter.handle(jsonRequest, requestContext);
         if (jsonRpcResponse.error) {
@@ -135,26 +163,55 @@ export class SocketConnection {
         this.send(jsonRpcResponse);
     }
     /**
-     * Sends a JSON encoded Buffer through the Websocket.
+     * Returns the number of active subscriptions on this connection.
+     */
+    get subscriptionCount() {
+        return this.subscriptions.size;
+    }
+    /**
+     * Returns a serializable snapshot of this connection for the admin inspector.
+     */
+    toSnapshot() {
+        const subscriptions = Array.from(this.flowControllers.entries()).map(([id, fc]) => ({
+            id: id,
+            inflight: fc.inFlightCount,
+            buffered: fc.bufferCount,
+        }));
+        return {
+            id: this.id,
+            connectedAt: new Date(this.connectedAt).toISOString(),
+            subscriptionCount: this.subscriptions.size,
+            subscriptions,
+        };
+    }
+    /**
+     * Sends a JSON encoded string through the WebSocket.
      */
     send(response) {
         this.socket.send(JSON.stringify(response));
     }
     /**
-     * Creates a subscription handler to send messages matching the subscription requested.
-     *
-     * Wraps the incoming `message` in a `JSON RPC Success Response` using the original subscription`JSON RPC Id` to send through the WebSocket.
+     * Creates a flow-controlled subscription handler that enforces the
+     * `maxInFlight` window. Returns a `SubscriptionListener` to be passed
+     * to the EventLog, and stores the `FlowController` for later `rpc.ack`
+     * processing.
      */
     createSubscriptionHandler(id) {
-        return (event) => {
-            const response = createJsonRpcSuccessResponse(id, { event });
+        const fc = new FlowController(id, this.maxInFlight, (response) => {
             this.send(response);
+        }, () => {
+            // overflow: close the subscription to prevent OOM
+            this.closeSubscription(id).catch((err) => {
+                log.error(`FlowController: error closing subscription ${String(id)} on overflow`, err);
+            });
+        });
+        this.flowControllers.set(id, fc);
+        return (message) => {
+            fc.push(message);
         };
     }
     /**
      * Builds a `RequestContext` object to use with the `JSON RPC API`.
-     *
-     * Adds a `subscriptionHandler` for `Subscribe` messages.
      */
     async buildRequestContext(request) {
         const { params, method, subscription } = request;
@@ -162,15 +219,20 @@ export class SocketConnection {
             transport: 'ws',
             dwn: this.dwn,
             socketConnection: this,
+            activityLog: this.activityLog,
+            adminStore: this.adminStore,
+            registrationStore: this.registrationStore,
+            config: this.serverConfig,
+            tenantRateLimiter: this.tenantRateLimiter,
+            messageProcessedHooks: this.messageProcessedHooks,
         };
         // methods that expect a long-running subscription begin with `rpc.subscribe.`
         if (method.startsWith('rpc.subscribe.') && subscription) {
             const { message } = params;
             if (message?.descriptor.method === DwnMethodName.Subscribe) {
-                const handlerFunc = this.createSubscriptionHandler(subscription.id);
                 requestContext.subscriptionRequest = {
                     id: subscription.id,
-                    subscriptionHandler: (message) => handlerFunc(message),
+                    subscriptionHandler: this.createSubscriptionHandler(subscription.id),
                 };
             }
         }

package/dist/esm/src/connection/socket-connection.js.map

@@ -1 +1 @@
-{"version":3,"file":"socket-connection.js","sourceRoot":"","sources":["../../../../src/connection/socket-connection.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"socket-connection.js","sourceRoot":"","sources":["../../../../src/connection/socket-connection.ts"],"names":[],"mappings":"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"}

package/dist/esm/src/delivery-service.d.ts

@@ -0,0 +1,43 @@
+import type { DwnServerConfig } from './config.js';
+import type { DidResolver } from '@enbox/dids';
+import type { Dwn, GenericMessage } from '@enbox/dwn-sdk-js';
+import type { MessageProcessedContext, MessageProcessedHook } from './message-processed-hook.js';
+/**
+ * Server-side service that handles two complementary features:
+ *
+ * 1. **Endpoint forwarding** — When a RecordsWrite/RecordsDelete is processed,
+ *    forwards the original signed message to the tenant's *other* DWN service
+ *    endpoints (peer replication without the agent mediating).
+ *
+ * 2. **Record delivery** — When a RecordsWrite/RecordsDelete is processed at a
+ *    protocol path with `$delivery`, proactively delivers to participants' DWN
+ *    endpoints determined from protocol `$actions` role records.
+ *
+ * Both operations are fire-and-forget: failures are logged but never propagate
+ * to the original request handler.
+ */
+export declare class DeliveryService implements MessageProcessedHook {
+    #private;
+    private constructor();
+    /**
+     * Factory method following the established server service pattern.
+     */
+    static create(dwn: Dwn, didResolver: DidResolver, config: DwnServerConfig): DeliveryService;
+    /**
+     * Hook entry point invoked by the hooks runner after `dwn.processMessage()`.
+     */
+    onMessageProcessed(context: MessageProcessedContext): void;
+    /**
+     * Evaluates whether forwarding or delivery should occur for a successfully
+     * processed message, and dispatches outbound requests asynchronously.
+     *
+     * This method does NOT await the outbound requests — it returns immediately
+     * after scheduling them.
+     *
+     * @param tenant   - The tenant DID that owns the DWN.
+     * @param message  - The original signed DWN message.
+     * @param statusCode - The reply status code from `dwn.processMessage()`.
+     */
+    dispatchIfNeeded(tenant: string, message: GenericMessage, statusCode: number): void;
+}
+//# sourceMappingURL=delivery-service.d.ts.map

package/dist/esm/src/delivery-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery-service.d.ts","sourceRoot":"","sources":["../../../src/delivery-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAe,WAAW,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,KAAK,EAAE,GAAG,EAAE,cAAc,EAAuC,MAAM,mBAAmB,CAAC;AAClG,OAAO,KAAK,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAkCjG;;;;;;;;;;;;;GAaG;AACH,qBAAa,eAAgB,YAAW,oBAAoB;;IAwB1D,OAAO;IAOP;;OAEG;WACW,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,EAAE,eAAe,GAAG,eAAe;IAQlG;;OAEG;IACI,kBAAkB,CAAC,OAAO,EAAE,uBAAuB,GAAG,IAAI;IAQjE;;;;;;;;;;OAUG;IACI,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;CAgnB3F"}