@aegis-fluxion/core 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -5,6 +5,10 @@ interface SecureEnvelope<TData = unknown> {
     event: string;
     data: TData;
 }
+interface SecureAckOptions {
+    timeoutMs?: number;
+}
+type SecureAckCallback = (error: Error | null, response?: unknown) => void;
 interface SecureServerHeartbeatOptions {
     enabled?: boolean;
     intervalMs?: number;
@@ -31,6 +35,7 @@ interface SecureServerClient {
     id: string;
     socket: WebSocket;
     request: IncomingMessage;
+    emit: (event: string, data: unknown, callbackOrOptions?: SecureAckCallback | SecureAckOptions, maybeCallback?: SecureAckCallback) => boolean | Promise<unknown>;
     join: (room: string) => boolean;
     leave: (room: string) => boolean;
     leaveAll: () => number;
@@ -39,11 +44,11 @@ interface SecureServerRoomOperator {
     emit: (event: string, data: unknown) => SecureServer;
 }
 type SecureErrorHandler = (error: Error) => void;
-type SecureServerEventHandler = (data: unknown, client: SecureServerClient) => void;
+type SecureServerEventHandler = (data: unknown, client: SecureServerClient) => unknown | Promise<unknown>;
 type SecureServerConnectionHandler = (client: SecureServerClient) => void;
 type SecureServerDisconnectHandler = (client: SecureServerClient, code: number, reason: string) => void;
 type SecureServerReadyHandler = (client: SecureServerClient) => void;
-type SecureClientEventHandler = (data: unknown) => void;
+type SecureClientEventHandler = (data: unknown) => unknown | Promise<unknown>;
 type SecureClientConnectHandler = () => void;
 type SecureClientDisconnectHandler = (code: number, reason: string) => void;
 type SecureClientReadyHandler = () => void;
@@ -76,6 +81,7 @@ declare class SecureServer {
     private readonly sharedSecretBySocket;
     private readonly encryptionKeyBySocket;
     private readonly pendingPayloadsBySocket;
+    private readonly pendingRpcRequestsBySocket;
     private readonly heartbeatStateBySocket;
     private readonly roomMembersByName;
     private readonly roomNamesByClientId;
@@ -94,6 +100,9 @@ declare class SecureServer {
     off(event: string, handler: SecureServerEventHandler): this;
     emit(event: string, data: unknown): this;
     emitTo(clientId: string, event: string, data: unknown): boolean;
+    emitTo(clientId: string, event: string, data: unknown, callback: SecureAckCallback): boolean;
+    emitTo(clientId: string, event: string, data: unknown, options: SecureAckOptions): Promise<unknown>;
+    emitTo(clientId: string, event: string, data: unknown, options: SecureAckOptions, callback: SecureAckCallback): boolean;
     to(room: string): SecureServerRoomOperator;
     close(code?: number, reason?: string): void;
     private resolveHeartbeatConfig;
@@ -108,6 +117,11 @@ declare class SecureServer {
     private dispatchCustomEvent;
     private sendRaw;
     private sendEncryptedEnvelope;
+    private sendRpcRequest;
+    private handleRpcResponse;
+    private handleRpcRequest;
+    private executeRpcRequestHandler;
+    private rejectPendingRpcRequests;
     private notifyConnection;
     private notifyReady;
     private notifyError;
@@ -140,6 +154,7 @@ declare class SecureClient {
     private readonly errorHandlers;
     private handshakeState;
     private pendingPayloadQueue;
+    private readonly pendingRpcRequests;
     constructor(url: string, options?: SecureClientOptions);
     get readyState(): number | null;
     isConnected(): boolean;
@@ -156,6 +171,9 @@ declare class SecureClient {
     off(event: "error", handler: SecureErrorHandler): this;
     off(event: string, handler: SecureClientEventHandler): this;
     emit(event: string, data: unknown): boolean;
+    emit(event: string, data: unknown, callback: SecureAckCallback): boolean;
+    emit(event: string, data: unknown, options: SecureAckOptions): Promise<unknown>;
+    emit(event: string, data: unknown, options: SecureAckOptions, callback: SecureAckCallback): boolean;
     private resolveReconnectConfig;
     private scheduleReconnect;
     private computeReconnectDelay;
@@ -169,6 +187,11 @@ declare class SecureClient {
     private notifyReady;
     private notifyError;
     private sendEncryptedEnvelope;
+    private sendRpcRequest;
+    private handleRpcResponse;
+    private handleRpcRequest;
+    private executeRpcRequestHandler;
+    private rejectPendingRpcRequests;
     private createClientHandshakeState;
     private sendInternalHandshake;
     private handleInternalHandshake;
@@ -176,4 +199,4 @@ declare class SecureClient {
     private flushPendingPayloadQueue;
 }
 
-export { SecureClient, type SecureClientConnectHandler, type SecureClientDisconnectHandler, type SecureClientEventHandler, type SecureClientEventMap, type SecureClientLifecycleEvent, type SecureClientOptions, type SecureClientReadyHandler, type SecureClientReconnectOptions, type SecureEnvelope, type SecureErrorHandler, SecureServer, type SecureServerClient, type SecureServerConnectionHandler, type SecureServerDisconnectHandler, type SecureServerEventHandler, type SecureServerEventMap, type SecureServerHeartbeatOptions, type SecureServerLifecycleEvent, type SecureServerOptions, type SecureServerReadyHandler, type SecureServerRoomOperator };
+export { type SecureAckCallback, type SecureAckOptions, SecureClient, type SecureClientConnectHandler, type SecureClientDisconnectHandler, type SecureClientEventHandler, type SecureClientEventMap, type SecureClientLifecycleEvent, type SecureClientOptions, type SecureClientReadyHandler, type SecureClientReconnectOptions, type SecureEnvelope, type SecureErrorHandler, SecureServer, type SecureServerClient, type SecureServerConnectionHandler, type SecureServerDisconnectHandler, type SecureServerEventHandler, type SecureServerEventMap, type SecureServerHeartbeatOptions, type SecureServerLifecycleEvent, type SecureServerOptions, type SecureServerReadyHandler, type SecureServerRoomOperator };

package/dist/index.js

@@ -5,6 +5,8 @@ import WebSocket, { WebSocketServer } from 'ws';
 var DEFAULT_CLOSE_CODE = 1e3;
 var DEFAULT_CLOSE_REASON = "";
 var INTERNAL_HANDSHAKE_EVENT = "__handshake";
+var INTERNAL_RPC_REQUEST_EVENT = "__rpc:req";
+var INTERNAL_RPC_RESPONSE_EVENT = "__rpc:res";
 var READY_EVENT = "ready";
 var HANDSHAKE_CURVE = "prime256v1";
 var ENCRYPTION_ALGORITHM = "aes-256-gcm";
@@ -19,6 +21,7 @@ var DEFAULT_RECONNECT_INITIAL_DELAY_MS = 250;
 var DEFAULT_RECONNECT_MAX_DELAY_MS = 1e4;
 var DEFAULT_RECONNECT_FACTOR = 2;
 var DEFAULT_RECONNECT_JITTER_RATIO = 0.2;
+var DEFAULT_RPC_TIMEOUT_MS = 5e3;
 function normalizeToError(error, fallbackMessage) {
   if (error instanceof Error) {
     return error;
@@ -81,7 +84,88 @@ function decodeCloseReason(reason) {
   return reason.toString("utf8");
 }
 function isReservedEmitEvent(event) {
-  return event === INTERNAL_HANDSHAKE_EVENT || event === READY_EVENT;
+  return event === INTERNAL_HANDSHAKE_EVENT || event === INTERNAL_RPC_REQUEST_EVENT || event === INTERNAL_RPC_RESPONSE_EVENT || event === READY_EVENT;
+}
+function isPromiseLike(value) {
+  return typeof value === "object" && value !== null && "then" in value;
+}
+function normalizeRpcTimeout(timeoutMs) {
+  const resolvedTimeoutMs = timeoutMs ?? DEFAULT_RPC_TIMEOUT_MS;
+  if (!Number.isFinite(resolvedTimeoutMs) || resolvedTimeoutMs <= 0) {
+    throw new Error("ACK timeoutMs must be a positive number.");
+  }
+  return resolvedTimeoutMs;
+}
+function parseRpcRequestPayload(data) {
+  if (typeof data !== "object" || data === null) {
+    throw new Error("Invalid RPC request payload format.");
+  }
+  const payload = data;
+  if (typeof payload.id !== "string" || payload.id.trim().length === 0) {
+    throw new Error("RPC request payload must include a non-empty id.");
+  }
+  if (typeof payload.event !== "string" || payload.event.trim().length === 0) {
+    throw new Error("RPC request payload must include a non-empty event.");
+  }
+  return {
+    id: payload.id,
+    event: payload.event,
+    data: payload.data
+  };
+}
+function parseRpcResponsePayload(data) {
+  if (typeof data !== "object" || data === null) {
+    throw new Error("Invalid RPC response payload format.");
+  }
+  const payload = data;
+  if (typeof payload.id !== "string" || payload.id.trim().length === 0) {
+    throw new Error("RPC response payload must include a non-empty id.");
+  }
+  if (typeof payload.ok !== "boolean") {
+    throw new Error("RPC response payload must include a boolean ok field.");
+  }
+  if (payload.error !== void 0 && typeof payload.error !== "string") {
+    throw new Error("RPC response payload error must be a string when provided.");
+  }
+  const parsedPayload = {
+    id: payload.id,
+    ok: payload.ok,
+    data: payload.data
+  };
+  if (payload.error !== void 0) {
+    parsedPayload.error = payload.error;
+  }
+  return parsedPayload;
+}
+function resolveAckArguments(callbackOrOptions, maybeCallback) {
+  if (callbackOrOptions === void 0 && maybeCallback === void 0) {
+    return {
+      expectsAck: false,
+      timeoutMs: DEFAULT_RPC_TIMEOUT_MS
+    };
+  }
+  if (typeof callbackOrOptions === "function") {
+    if (maybeCallback !== void 0) {
+      throw new Error("ACK callback was provided more than once.");
+    }
+    return {
+      expectsAck: true,
+      callback: callbackOrOptions,
+      timeoutMs: DEFAULT_RPC_TIMEOUT_MS
+    };
+  }
+  const options = callbackOrOptions;
+  if (options !== void 0 && (typeof options !== "object" || options === null)) {
+    throw new Error("ACK options must be an object.");
+  }
+  if (maybeCallback !== void 0 && typeof maybeCallback !== "function") {
+    throw new Error("ACK callback must be a function.");
+  }
+  return {
+    ...maybeCallback ? { callback: maybeCallback } : {},
+    expectsAck: true,
+    timeoutMs: normalizeRpcTimeout(options?.timeoutMs)
+  };
 }
 function createEphemeralHandshakeState() {
   const ecdh = createECDH(HANDSHAKE_CURVE);
@@ -179,6 +263,7 @@ var SecureServer = class {
   sharedSecretBySocket = /* @__PURE__ */ new WeakMap();
   encryptionKeyBySocket = /* @__PURE__ */ new WeakMap();
   pendingPayloadsBySocket = /* @__PURE__ */ new WeakMap();
+  pendingRpcRequestsBySocket = /* @__PURE__ */ new WeakMap();
   heartbeatStateBySocket = /* @__PURE__ */ new WeakMap();
   roomMembersByName = /* @__PURE__ */ new Map();
   roomNamesByClientId = /* @__PURE__ */ new Map();
@@ -277,7 +362,8 @@ var SecureServer = class {
     }
     return this;
   }
-  emitTo(clientId, event, data) {
+  emitTo(clientId, event, data, callbackOrOptions, maybeCallback) {
+    const ackArgs = resolveAckArguments(callbackOrOptions, maybeCallback);
     try {
       if (isReservedEmitEvent(event)) {
         throw new Error(`The event "${event}" is reserved and cannot be emitted manually.`);
@@ -286,10 +372,37 @@ var SecureServer = class {
       if (!client) {
         throw new Error(`Client with id ${clientId} was not found.`);
       }
-      this.sendOrQueuePayload(client.socket, { event, data });
-      return true;
+      if (!ackArgs.expectsAck) {
+        this.sendOrQueuePayload(client.socket, { event, data });
+        return true;
+      }
+      const ackPromise = this.sendRpcRequest(
+        client.socket,
+        event,
+        data,
+        ackArgs.timeoutMs
+      );
+      if (ackArgs.callback) {
+        ackPromise.then((response) => {
+          ackArgs.callback?.(null, response);
+        }).catch((error) => {
+          ackArgs.callback?.(
+            normalizeToError(error, `ACK callback failed for client ${client.id}.`)
+          );
+        });
+        return true;
+      }
+      return ackPromise;
     } catch (error) {
-      this.notifyError(normalizeToError(error, "Failed to emit event to client."));
+      const normalizedError = normalizeToError(error, "Failed to emit event to client.");
+      this.notifyError(normalizedError);
+      if (ackArgs.callback) {
+        ackArgs.callback(normalizedError);
+        return false;
+      }
+      if (ackArgs.expectsAck) {
+        return Promise.reject(normalizedError);
+      }
       return false;
     }
   }
@@ -312,6 +425,10 @@ var SecureServer = class {
     try {
       this.stopHeartbeatLoop();
       for (const client of this.clientsById.values()) {
+        this.rejectPendingRpcRequests(
+          client.socket,
+          new Error("Server closed before ACK response was received.")
+        );
         if (client.socket.readyState === WebSocket.OPEN || client.socket.readyState === WebSocket.CONNECTING) {
           client.socket.close(code, reason);
         }
@@ -364,9 +481,14 @@ var SecureServer = class {
         lastPingAt: 0
       };
       if (heartbeatState.awaitingPong && now - heartbeatState.lastPingAt >= this.heartbeatConfig.timeoutMs) {
+        this.rejectPendingRpcRequests(
+          socket,
+          new Error(`Heartbeat timeout while waiting for client ${client.id} ACK response.`)
+        );
         this.sharedSecretBySocket.delete(socket);
         this.encryptionKeyBySocket.delete(socket);
         this.pendingPayloadsBySocket.delete(socket);
+        this.pendingRpcRequestsBySocket.delete(socket);
         this.handshakeStateBySocket.delete(socket);
         this.heartbeatStateBySocket.delete(socket);
         socket.terminate();
@@ -413,6 +535,7 @@ var SecureServer = class {
       this.clientIdBySocket.set(socket, clientId);
       this.handshakeStateBySocket.set(socket, handshakeState);
       this.pendingPayloadsBySocket.set(socket, []);
+      this.pendingRpcRequestsBySocket.set(socket, /* @__PURE__ */ new Map());
       this.heartbeatStateBySocket.set(socket, {
         awaitingPong: false,
         lastPingAt: 0
@@ -480,6 +603,14 @@ var SecureServer = class {
         return;
       }
       const decryptedEnvelope = parseEnvelopeFromText(decryptedPayload);
+      if (decryptedEnvelope.event === INTERNAL_RPC_RESPONSE_EVENT) {
+        this.handleRpcResponse(client.socket, decryptedEnvelope.data);
+        return;
+      }
+      if (decryptedEnvelope.event === INTERNAL_RPC_REQUEST_EVENT) {
+        void this.handleRpcRequest(client, decryptedEnvelope.data);
+        return;
+      }
       this.dispatchCustomEvent(decryptedEnvelope.event, decryptedEnvelope.data, client);
     } catch (error) {
       this.notifyError(normalizeToError(error, "Failed to process incoming server message."));
@@ -494,6 +625,11 @@ var SecureServer = class {
       this.sharedSecretBySocket.delete(client.socket);
       this.encryptionKeyBySocket.delete(client.socket);
       this.pendingPayloadsBySocket.delete(client.socket);
+      this.rejectPendingRpcRequests(
+        client.socket,
+        new Error(`Client ${client.id} disconnected before ACK response was received.`)
+      );
+      this.pendingRpcRequestsBySocket.delete(client.socket);
       this.heartbeatStateBySocket.delete(client.socket);
       const decodedReason = decodeCloseReason(reason);
       for (const handler of this.disconnectHandlers) {
@@ -519,7 +655,17 @@ var SecureServer = class {
     }
     for (const handler of handlers) {
       try {
-        handler(data, client);
+        const handlerResult = handler(data, client);
+        if (isPromiseLike(handlerResult)) {
+          void Promise.resolve(handlerResult).catch((error) => {
+            this.notifyError(
+              normalizeToError(
+                error,
+                `Server event handler failed for event ${event}.`
+              )
+            );
+          });
+        }
       } catch (error) {
         this.notifyError(
           normalizeToError(
@@ -558,6 +704,112 @@ var SecureServer = class {
       this.notifyError(normalizeToError(error, "Failed to send encrypted server payload."));
     }
   }
+  sendRpcRequest(socket, event, data, timeoutMs) {
+    if (socket.readyState !== WebSocket.OPEN && socket.readyState !== WebSocket.CONNECTING) {
+      throw new Error("Client socket is not connected for ACK request.");
+    }
+    const pendingRequests = this.pendingRpcRequestsBySocket.get(socket) ?? /* @__PURE__ */ new Map();
+    this.pendingRpcRequestsBySocket.set(socket, pendingRequests);
+    const requestId = randomUUID();
+    return new Promise((resolve, reject) => {
+      const timeoutHandle = setTimeout(() => {
+        pendingRequests.delete(requestId);
+        reject(new Error(`ACK response timed out after ${timeoutMs}ms for event "${event}".`));
+      }, timeoutMs);
+      timeoutHandle.unref?.();
+      pendingRequests.set(requestId, {
+        resolve,
+        reject,
+        timeoutHandle
+      });
+      this.sendOrQueuePayload(socket, {
+        event: INTERNAL_RPC_REQUEST_EVENT,
+        data: {
+          id: requestId,
+          event,
+          data
+        }
+      });
+    });
+  }
+  handleRpcResponse(socket, data) {
+    try {
+      const responsePayload = parseRpcResponsePayload(data);
+      const pendingRequests = this.pendingRpcRequestsBySocket.get(socket);
+      if (!pendingRequests) {
+        return;
+      }
+      const pendingRequest = pendingRequests.get(responsePayload.id);
+      if (!pendingRequest) {
+        return;
+      }
+      clearTimeout(pendingRequest.timeoutHandle);
+      pendingRequests.delete(responsePayload.id);
+      if (responsePayload.ok) {
+        pendingRequest.resolve(responsePayload.data);
+        return;
+      }
+      pendingRequest.reject(
+        new Error(responsePayload.error ?? "ACK request failed without an error message.")
+      );
+    } catch (error) {
+      this.notifyError(normalizeToError(error, "Failed to process server ACK response."));
+    }
+  }
+  async handleRpcRequest(client, data) {
+    let rpcRequestPayload;
+    try {
+      rpcRequestPayload = parseRpcRequestPayload(data);
+    } catch (error) {
+      this.notifyError(normalizeToError(error, "Invalid server ACK request payload."));
+      return;
+    }
+    try {
+      const ackResponse = await this.executeRpcRequestHandler(
+        rpcRequestPayload.event,
+        rpcRequestPayload.data,
+        client
+      );
+      this.sendEncryptedEnvelope(client.socket, {
+        event: INTERNAL_RPC_RESPONSE_EVENT,
+        data: {
+          id: rpcRequestPayload.id,
+          ok: true,
+          data: ackResponse
+        }
+      });
+    } catch (error) {
+      const normalizedError = normalizeToError(error, "Server ACK request handler failed.");
+      this.sendEncryptedEnvelope(client.socket, {
+        event: INTERNAL_RPC_RESPONSE_EVENT,
+        data: {
+          id: rpcRequestPayload.id,
+          ok: false,
+          error: normalizedError.message
+        }
+      });
+      this.notifyError(normalizedError);
+    }
+  }
+  async executeRpcRequestHandler(event, data, client) {
+    const handlers = this.customEventHandlers.get(event);
+    if (!handlers || handlers.size === 0) {
+      throw new Error(`No handler is registered for ACK request event "${event}".`);
+    }
+    const firstHandler = handlers.values().next().value;
+    return Promise.resolve(firstHandler(data, client));
+  }
+  rejectPendingRpcRequests(socket, error) {
+    const pendingRequests = this.pendingRpcRequestsBySocket.get(socket);
+    if (!pendingRequests) {
+      return;
+    }
+    for (const pendingRequest of pendingRequests.values()) {
+      clearTimeout(pendingRequest.timeoutHandle);
+      pendingRequest.reject(error);
+    }
+    pendingRequests.clear();
+  }
   notifyConnection(client) {
     for (const handler of this.connectionHandlers) {
       try {
@@ -659,6 +911,24 @@ var SecureServer = class {
       id: clientId,
       socket,
       request,
+      emit: (event, data, callbackOrOptions, maybeCallback) => {
+        if (callbackOrOptions === void 0 && maybeCallback === void 0) {
+          return this.emitTo(clientId, event, data);
+        }
+        if (typeof callbackOrOptions === "function") {
+          return this.emitTo(clientId, event, data, callbackOrOptions);
+        }
+        if (maybeCallback) {
+          return this.emitTo(
+            clientId,
+            event,
+            data,
+            callbackOrOptions ?? {},
+            maybeCallback
+          );
+        }
+        return this.emitTo(clientId, event, data, callbackOrOptions ?? {});
+      },
       join: (room) => this.joinClientToRoom(clientId, room),
       leave: (room) => this.leaveClientFromRoom(clientId, room),
       leaveAll: () => this.leaveClientFromAllRooms(clientId)
@@ -770,6 +1040,7 @@ var SecureClient = class {
   errorHandlers = /* @__PURE__ */ new Set();
   handshakeState = null;
   pendingPayloadQueue = [];
+  pendingRpcRequests = /* @__PURE__ */ new Map();
   get readyState() {
     return this.socket?.readyState ?? null;
   }
@@ -878,7 +1149,8 @@ var SecureClient = class {
     }
     return this;
   }
-  emit(event, data) {
+  emit(event, data, callbackOrOptions, maybeCallback) {
+    const ackArgs = resolveAckArguments(callbackOrOptions, maybeCallback);
     try {
       if (isReservedEmitEvent(event)) {
         throw new Error(`The event "${event}" is reserved and cannot be emitted manually.`);
@@ -886,6 +1158,20 @@ var SecureClient = class {
       if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
         throw new Error("Client socket is not connected.");
       }
+      if (ackArgs.expectsAck) {
+        const ackPromise = this.sendRpcRequest(event, data, ackArgs.timeoutMs);
+        if (ackArgs.callback) {
+          ackPromise.then((response) => {
+            ackArgs.callback?.(null, response);
+          }).catch((error) => {
+            ackArgs.callback?.(
+              normalizeToError(error, `ACK callback failed for event "${event}".`)
+            );
+          });
+          return true;
+        }
+        return ackPromise;
+      }
       const envelope = { event, data };
       if (!this.isHandshakeReady()) {
         this.pendingPayloadQueue.push(envelope);
@@ -894,7 +1180,15 @@ var SecureClient = class {
       this.sendEncryptedEnvelope(envelope);
       return true;
     } catch (error) {
-      this.notifyError(normalizeToError(error, "Failed to emit client event."));
+      const normalizedError = normalizeToError(error, "Failed to emit client event.");
+      this.notifyError(normalizedError);
+      if (ackArgs.callback) {
+        ackArgs.callback(normalizedError);
+        return false;
+      }
+      if (ackArgs.expectsAck) {
+        return Promise.reject(normalizedError);
+      }
       return false;
     }
   }
@@ -1036,6 +1330,14 @@ var SecureClient = class {
         return;
       }
       const decryptedEnvelope = parseEnvelopeFromText(decryptedPayload);
+      if (decryptedEnvelope.event === INTERNAL_RPC_RESPONSE_EVENT) {
+        this.handleRpcResponse(decryptedEnvelope.data);
+        return;
+      }
+      if (decryptedEnvelope.event === INTERNAL_RPC_REQUEST_EVENT) {
+        void this.handleRpcRequest(decryptedEnvelope.data);
+        return;
+      }
       this.dispatchCustomEvent(decryptedEnvelope.event, decryptedEnvelope.data);
     } catch (error) {
       this.notifyError(normalizeToError(error, "Failed to process incoming client message."));
@@ -1046,6 +1348,9 @@ var SecureClient = class {
       this.socket = null;
       this.handshakeState = null;
       this.pendingPayloadQueue = [];
+      this.rejectPendingRpcRequests(
+        new Error("Client disconnected before ACK response was received.")
+      );
       const decodedReason = decodeCloseReason(reason);
       for (const handler of this.disconnectHandlers) {
         try {
@@ -1071,7 +1376,17 @@ var SecureClient = class {
     }
     for (const handler of handlers) {
       try {
-        handler(data);
+        const handlerResult = handler(data);
+        if (isPromiseLike(handlerResult)) {
+          void Promise.resolve(handlerResult).catch((error) => {
+            this.notifyError(
+              normalizeToError(
+                error,
+                `Client event handler failed for event ${event}.`
+              )
+            );
+          });
+        }
       } catch (error) {
         this.notifyError(
           normalizeToError(error, `Client event handler failed for event ${event}.`)
@@ -1126,6 +1441,106 @@ var SecureClient = class {
       this.notifyError(normalizeToError(error, "Failed to send encrypted client payload."));
     }
   }
+  sendRpcRequest(event, data, timeoutMs) {
+    if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
+      throw new Error("Client socket is not connected for ACK request.");
+    }
+    const requestId = randomUUID();
+    return new Promise((resolve, reject) => {
+      const timeoutHandle = setTimeout(() => {
+        this.pendingRpcRequests.delete(requestId);
+        reject(new Error(`ACK response timed out after ${timeoutMs}ms for event "${event}".`));
+      }, timeoutMs);
+      timeoutHandle.unref?.();
+      this.pendingRpcRequests.set(requestId, {
+        resolve,
+        reject,
+        timeoutHandle
+      });
+      const rpcRequestEnvelope = {
+        event: INTERNAL_RPC_REQUEST_EVENT,
+        data: {
+          id: requestId,
+          event,
+          data
+        }
+      };
+      if (!this.isHandshakeReady()) {
+        this.pendingPayloadQueue.push(rpcRequestEnvelope);
+        return;
+      }
+      this.sendEncryptedEnvelope(rpcRequestEnvelope);
+    });
+  }
+  handleRpcResponse(data) {
+    try {
+      const responsePayload = parseRpcResponsePayload(data);
+      const pendingRequest = this.pendingRpcRequests.get(responsePayload.id);
+      if (!pendingRequest) {
+        return;
+      }
+      clearTimeout(pendingRequest.timeoutHandle);
+      this.pendingRpcRequests.delete(responsePayload.id);
+      if (responsePayload.ok) {
+        pendingRequest.resolve(responsePayload.data);
+        return;
+      }
+      pendingRequest.reject(
+        new Error(responsePayload.error ?? "ACK request failed without an error message.")
+      );
+    } catch (error) {
+      this.notifyError(normalizeToError(error, "Failed to process client ACK response."));
+    }
+  }
+  async handleRpcRequest(data) {
+    let rpcRequestPayload;
+    try {
+      rpcRequestPayload = parseRpcRequestPayload(data);
+    } catch (error) {
+      this.notifyError(normalizeToError(error, "Invalid client ACK request payload."));
+      return;
+    }
+    try {
+      const ackResponse = await this.executeRpcRequestHandler(
+        rpcRequestPayload.event,
+        rpcRequestPayload.data
+      );
+      this.sendEncryptedEnvelope({
+        event: INTERNAL_RPC_RESPONSE_EVENT,
+        data: {
+          id: rpcRequestPayload.id,
+          ok: true,
+          data: ackResponse
+        }
+      });
+    } catch (error) {
+      const normalizedError = normalizeToError(error, "Client ACK request handler failed.");
+      this.sendEncryptedEnvelope({
+        event: INTERNAL_RPC_RESPONSE_EVENT,
+        data: {
+          id: rpcRequestPayload.id,
+          ok: false,
+          error: normalizedError.message
+        }
+      });
+      this.notifyError(normalizedError);
+    }
+  }
+  async executeRpcRequestHandler(event, data) {
+    const handlers = this.customEventHandlers.get(event);
+    if (!handlers || handlers.size === 0) {
+      throw new Error(`No handler is registered for ACK request event "${event}".`);
+    }
+    const firstHandler = handlers.values().next().value;
+    return Promise.resolve(firstHandler(data));
+  }
+  rejectPendingRpcRequests(error) {
+    for (const pendingRequest of this.pendingRpcRequests.values()) {
+      clearTimeout(pendingRequest.timeoutHandle);
+      pendingRequest.reject(error);
+    }
+    this.pendingRpcRequests.clear();
+  }
   createClientHandshakeState() {
     const { ecdh, localPublicKey } = createEphemeralHandshakeState();
     return {