@aegis-fluxion/core 0.3.0 → 0.5.0

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";
@@ -13,12 +15,15 @@ var GCM_AUTH_TAG_LENGTH = 16;
 var ENCRYPTION_KEY_LENGTH = 32;
 var ENCRYPTED_PACKET_VERSION = 1;
 var ENCRYPTED_PACKET_PREFIX_LENGTH = 1 + GCM_IV_LENGTH + GCM_AUTH_TAG_LENGTH;
+var BINARY_PAYLOAD_MARKER = "__afxBinaryPayload";
+var BINARY_PAYLOAD_VERSION = 1;
 var DEFAULT_HEARTBEAT_INTERVAL_MS = 15e3;
 var DEFAULT_HEARTBEAT_TIMEOUT_MS = 15e3;
 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;
@@ -52,7 +57,103 @@ function rawDataToBuffer(rawData) {
   }
   return Buffer.from(rawData);
 }
-function serializeEnvelope(event, data) {
+function isBlobValue(value) {
+  return typeof Blob !== "undefined" && value instanceof Blob;
+}
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function encodeBinaryPayload(kind, payloadBuffer, mimeType) {
+  const encodedPayload = {
+    [BINARY_PAYLOAD_MARKER]: BINARY_PAYLOAD_VERSION,
+    kind,
+    base64: payloadBuffer.toString("base64")
+  };
+  if (mimeType !== void 0 && mimeType.length > 0) {
+    encodedPayload.mimeType = mimeType;
+  }
+  return encodedPayload;
+}
+async function encodeEnvelopeData(value) {
+  if (Buffer.isBuffer(value)) {
+    return encodeBinaryPayload("buffer", value);
+  }
+  if (value instanceof Uint8Array) {
+    const typedArrayBuffer = Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+    return encodeBinaryPayload("uint8array", typedArrayBuffer);
+  }
+  if (isBlobValue(value)) {
+    const blobBuffer = Buffer.from(await value.arrayBuffer());
+    return encodeBinaryPayload("blob", blobBuffer, value.type);
+  }
+  if (Array.isArray(value)) {
+    return Promise.all(value.map((item) => encodeEnvelopeData(item)));
+  }
+  if (isPlainObject(value)) {
+    const encodedEntries = await Promise.all(
+      Object.entries(value).map(async ([key, entryValue]) => {
+        return [key, await encodeEnvelopeData(entryValue)];
+      })
+    );
+    return Object.fromEntries(encodedEntries);
+  }
+  return value;
+}
+function isEncodedBinaryPayload(value) {
+  if (!isPlainObject(value)) {
+    return false;
+  }
+  if (value[BINARY_PAYLOAD_MARKER] !== BINARY_PAYLOAD_VERSION) {
+    return false;
+  }
+  if (value.kind !== "buffer" && value.kind !== "uint8array" && value.kind !== "blob") {
+    return false;
+  }
+  if (typeof value.base64 !== "string") {
+    return false;
+  }
+  if (value.mimeType !== void 0 && typeof value.mimeType !== "string") {
+    return false;
+  }
+  return true;
+}
+function decodeEnvelopeData(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => decodeEnvelopeData(item));
+  }
+  if (isEncodedBinaryPayload(value)) {
+    const binaryBuffer = Buffer.from(value.base64, "base64");
+    if (value.kind === "buffer") {
+      return binaryBuffer;
+    }
+    if (value.kind === "uint8array") {
+      return Uint8Array.from(binaryBuffer);
+    }
+    if (typeof Blob === "undefined") {
+      return binaryBuffer;
+    }
+    return new Blob([binaryBuffer], {
+      type: value.mimeType ?? ""
+    });
+  }
+  if (isPlainObject(value)) {
+    const decodedEntries = Object.entries(value).map(([key, entryValue]) => {
+      return [key, decodeEnvelopeData(entryValue)];
+    });
+    return Object.fromEntries(decodedEntries);
+  }
+  return value;
+}
+async function serializeEnvelope(event, data) {
+  const encodedData = await encodeEnvelopeData(data);
+  const envelope = { event, data: encodedData };
+  return JSON.stringify(envelope);
+}
+function serializePlainEnvelope(event, data) {
   const envelope = { event, data };
   return JSON.stringify(envelope);
 }
@@ -64,7 +165,7 @@ function parseEnvelope(rawData) {
   }
   return {
     event: parsed.event,
-    data: parsed.data
+    data: decodeEnvelopeData(parsed.data)
   };
 }
 function parseEnvelopeFromText(decodedPayload) {
@@ -74,14 +175,95 @@ function parseEnvelopeFromText(decodedPayload) {
   }
   return {
     event: parsed.event,
-    data: parsed.data
+    data: decodeEnvelopeData(parsed.data)
   };
 }
 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 +361,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();
@@ -270,14 +453,17 @@ var SecureServer = class {
       }
       const envelope = { event, data };
       for (const client of this.clientsById.values()) {
-        this.sendOrQueuePayload(client.socket, envelope);
+        void this.sendOrQueuePayload(client.socket, envelope).catch(() => {
+          return void 0;
+        });
       }
     } catch (error) {
       this.notifyError(normalizeToError(error, "Failed to emit server event."));
     }
     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 +472,39 @@ 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) {
+        void this.sendOrQueuePayload(client.socket, { event, data }).catch(() => {
+          return void 0;
+        });
+        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 +527,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 +583,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 +637,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 +705,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 +727,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 +757,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(
@@ -540,24 +788,138 @@ var SecureServer = class {
       this.notifyError(normalizeToError(error, "Failed to send server payload."));
     }
   }
-  sendEncryptedEnvelope(socket, envelope) {
+  async sendEncryptedEnvelope(socket, envelope) {
+    if (socket.readyState !== WebSocket.OPEN) {
+      return;
+    }
+    const encryptionKey = this.encryptionKeyBySocket.get(socket);
+    if (!encryptionKey) {
+      const missingKeyError = new Error("Missing encryption key for connected socket.");
+      this.notifyError(missingKeyError);
+      throw missingKeyError;
+    }
     try {
-      if (socket.readyState !== WebSocket.OPEN) {
+      const serializedEnvelope = await serializeEnvelope(envelope.event, envelope.data);
+      const encryptedPayload = encryptSerializedEnvelope(serializedEnvelope, encryptionKey);
+      socket.send(encryptedPayload);
+    } catch (error) {
+      const normalizedError = normalizeToError(error, "Failed to send encrypted server payload.");
+      this.notifyError(normalizedError);
+      throw normalizedError;
+    }
+  }
+  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
+      });
+      void this.sendOrQueuePayload(socket, {
+        event: INTERNAL_RPC_REQUEST_EVENT,
+        data: {
+          id: requestId,
+          event,
+          data
+        }
+      }).catch((error) => {
+        clearTimeout(timeoutHandle);
+        pendingRequests.delete(requestId);
+        reject(
+          normalizeToError(error, `Failed to dispatch ACK request for event "${event}".`)
+        );
+      });
+    });
+  }
+  handleRpcResponse(socket, data) {
+    try {
+      const responsePayload = parseRpcResponsePayload(data);
+      const pendingRequests = this.pendingRpcRequestsBySocket.get(socket);
+      if (!pendingRequests) {
         return;
       }
-      const encryptionKey = this.encryptionKeyBySocket.get(socket);
-      if (!encryptionKey) {
-        throw new Error("Missing encryption key for connected socket.");
+      const pendingRequest = pendingRequests.get(responsePayload.id);
+      if (!pendingRequest) {
+        return;
       }
-      const encryptedPayload = encryptSerializedEnvelope(
-        serializeEnvelope(envelope.event, envelope.data),
-        encryptionKey
+      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.")
       );
-      socket.send(encryptedPayload);
     } catch (error) {
-      this.notifyError(normalizeToError(error, "Failed to send encrypted server payload."));
+      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
+      );
+      await 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.");
+      await 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 {
@@ -602,7 +964,7 @@ var SecureServer = class {
   sendInternalHandshake(socket, localPublicKey) {
     this.sendRaw(
       socket,
-      serializeEnvelope(INTERNAL_HANDSHAKE_EVENT, {
+      serializePlainEnvelope(INTERNAL_HANDSHAKE_EVENT, {
         publicKey: localPublicKey
       })
     );
@@ -635,23 +997,23 @@ var SecureServer = class {
   sendOrQueuePayload(socket, envelope) {
     if (!this.isClientHandshakeReady(socket)) {
       this.queuePayload(socket, envelope);
-      return;
+      return Promise.resolve();
     }
-    this.sendEncryptedEnvelope(socket, envelope);
+    return this.sendEncryptedEnvelope(socket, envelope);
   }
   queuePayload(socket, envelope) {
     const pendingPayloads = this.pendingPayloadsBySocket.get(socket) ?? [];
     pendingPayloads.push(envelope);
     this.pendingPayloadsBySocket.set(socket, pendingPayloads);
   }
-  flushQueuedPayloads(socket) {
+  async flushQueuedPayloads(socket) {
     const pendingPayloads = this.pendingPayloadsBySocket.get(socket);
     if (!pendingPayloads || pendingPayloads.length === 0) {
       return;
     }
     this.pendingPayloadsBySocket.delete(socket);
     for (const envelope of pendingPayloads) {
-      this.sendEncryptedEnvelope(socket, envelope);
+      await this.sendEncryptedEnvelope(socket, envelope);
     }
   }
   createSecureServerClient(clientId, socket, request) {
@@ -659,6 +1021,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)
@@ -743,7 +1123,9 @@ var SecureServer = class {
       if (!client) {
         continue;
       }
-      this.sendOrQueuePayload(client.socket, envelope);
+      void this.sendOrQueuePayload(client.socket, envelope).catch(() => {
+        return void 0;
+      });
     }
   }
 };
@@ -770,6 +1152,7 @@ var SecureClient = class {
   errorHandlers = /* @__PURE__ */ new Set();
   handshakeState = null;
   pendingPayloadQueue = [];
+  pendingRpcRequests = /* @__PURE__ */ new Map();
   get readyState() {
     return this.socket?.readyState ?? null;
   }
@@ -878,7 +1261,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,15 +1270,39 @@ 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);
         return true;
       }
-      this.sendEncryptedEnvelope(envelope);
+      void this.sendEncryptedEnvelope(envelope).catch(() => {
+        return void 0;
+      });
       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 +1444,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 +1462,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 +1490,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}.`)
@@ -1108,23 +1537,133 @@ var SecureClient = class {
       }
     }
   }
-  sendEncryptedEnvelope(envelope) {
+  async sendEncryptedEnvelope(envelope) {
+    if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
+      const socketStateError = new Error("Client socket is not connected.");
+      this.notifyError(socketStateError);
+      throw socketStateError;
+    }
+    const encryptionKey = this.handshakeState?.encryptionKey;
+    if (!encryptionKey) {
+      const missingKeyError = new Error("Missing encryption key for client payload encryption.");
+      this.notifyError(missingKeyError);
+      throw missingKeyError;
+    }
     try {
-      if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
-        throw new Error("Client socket is not connected.");
+      const serializedEnvelope = await serializeEnvelope(envelope.event, envelope.data);
+      const encryptedPayload = encryptSerializedEnvelope(serializedEnvelope, encryptionKey);
+      this.socket.send(encryptedPayload);
+    } catch (error) {
+      const normalizedError = normalizeToError(error, "Failed to send encrypted client payload.");
+      this.notifyError(normalizedError);
+      throw normalizedError;
+    }
+  }
+  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;
       }
-      const encryptionKey = this.handshakeState?.encryptionKey;
-      if (!encryptionKey) {
-        throw new Error("Missing encryption key for client payload encryption.");
+      void this.sendEncryptedEnvelope(rpcRequestEnvelope).catch((error) => {
+        clearTimeout(timeoutHandle);
+        this.pendingRpcRequests.delete(requestId);
+        reject(
+          normalizeToError(error, `Failed to dispatch ACK request for event "${event}".`)
+        );
+      });
+    });
+  }
+  handleRpcResponse(data) {
+    try {
+      const responsePayload = parseRpcResponsePayload(data);
+      const pendingRequest = this.pendingRpcRequests.get(responsePayload.id);
+      if (!pendingRequest) {
+        return;
       }
-      const encryptedPayload = encryptSerializedEnvelope(
-        serializeEnvelope(envelope.event, envelope.data),
-        encryptionKey
+      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.")
       );
-      this.socket.send(encryptedPayload);
     } catch (error) {
-      this.notifyError(normalizeToError(error, "Failed to send encrypted client payload."));
+      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
+      );
+      await 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.");
+      await 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();
@@ -1145,7 +1684,7 @@ var SecureClient = class {
         throw new Error("Missing client handshake state.");
       }
       this.socket.send(
-        serializeEnvelope(INTERNAL_HANDSHAKE_EVENT, {
+        serializePlainEnvelope(INTERNAL_HANDSHAKE_EVENT, {
           publicKey: this.handshakeState.localPublicKey
         })
       );
@@ -1167,7 +1706,7 @@ var SecureClient = class {
       this.handshakeState.sharedSecret = sharedSecret;
       this.handshakeState.encryptionKey = deriveEncryptionKey(sharedSecret);
       this.handshakeState.isReady = true;
-      this.flushPendingPayloadQueue();
+      void this.flushPendingPayloadQueue();
       this.notifyReady();
     } catch (error) {
       this.notifyError(normalizeToError(error, "Failed to complete client handshake."));
@@ -1176,14 +1715,14 @@ var SecureClient = class {
   isHandshakeReady() {
     return this.handshakeState?.isReady ?? false;
   }
-  flushPendingPayloadQueue() {
+  async flushPendingPayloadQueue() {
     if (!this.socket || this.socket.readyState !== WebSocket.OPEN || !this.isHandshakeReady()) {
       return;
     }
     const pendingPayloads = this.pendingPayloadQueue;
     this.pendingPayloadQueue = [];
     for (const envelope of pendingPayloads) {
-      this.sendEncryptedEnvelope(envelope);
+      await this.sendEncryptedEnvelope(envelope);
     }
   }
 };