@aegis-fluxion/core 0.8.0 → 0.10.0

package/dist/index.cjs

@@ -1,6 +1,7 @@
 'use strict';
 
 var crypto = require('crypto');
+var stream = require('stream');
 var WebSocket = require('ws');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
@@ -16,6 +17,7 @@ var INTERNAL_HANDSHAKE_EVENT = "__handshake";
 var INTERNAL_SESSION_TICKET_EVENT = "__session:ticket";
 var INTERNAL_RPC_REQUEST_EVENT = "__rpc:req";
 var INTERNAL_RPC_RESPONSE_EVENT = "__rpc:res";
+var INTERNAL_STREAM_FRAME_EVENT = "__stream:frame";
 var READY_EVENT = "ready";
 var HANDSHAKE_CURVE = "prime256v1";
 var HANDSHAKE_PROTOCOL_VERSION = 1;
@@ -33,6 +35,9 @@ var DEFAULT_HEARTBEAT_TIMEOUT_MS = 15e3;
 var DEFAULT_SESSION_RESUMPTION_ENABLED = true;
 var DEFAULT_SESSION_TICKET_TTL_MS = 10 * 6e4;
 var DEFAULT_SESSION_TICKET_MAX_CACHE_SIZE = 1e4;
+var STREAM_FRAME_VERSION = 1;
+var DEFAULT_STREAM_CHUNK_SIZE_BYTES = 64 * 1024;
+var MAX_STREAM_CHUNK_SIZE_BYTES = 1024 * 1024;
 var RESUMPTION_NONCE_LENGTH = 16;
 var DEFAULT_RECONNECT_INITIAL_DELAY_MS = 250;
 var DEFAULT_RECONNECT_MAX_DELAY_MS = 1e4;
@@ -254,8 +259,11 @@ function parseEnvelopeFromText(decodedPayload) {
 function decodeCloseReason(reason) {
   return reason.toString("utf8");
 }
+function escapePrometheusLabelValue(value) {
+  return value.replace(/\\/g, "\\\\").replace(/\n/g, "\\n").replace(/"/g, '\\"');
+}
 function isReservedEmitEvent(event) {
-  return event === INTERNAL_HANDSHAKE_EVENT || event === INTERNAL_SESSION_TICKET_EVENT || event === INTERNAL_RPC_REQUEST_EVENT || event === INTERNAL_RPC_RESPONSE_EVENT || event === READY_EVENT;
+  return event === INTERNAL_HANDSHAKE_EVENT || event === INTERNAL_SESSION_TICKET_EVENT || event === INTERNAL_RPC_REQUEST_EVENT || event === INTERNAL_RPC_RESPONSE_EVENT || event === INTERNAL_STREAM_FRAME_EVENT || event === READY_EVENT;
 }
 function isPromiseLike(value) {
   return typeof value === "object" && value !== null && "then" in value;
@@ -267,6 +275,240 @@ function normalizeRpcTimeout(timeoutMs) {
   }
   return resolvedTimeoutMs;
 }
+function normalizeStreamChunkSize(chunkSizeBytes) {
+  const resolvedChunkSize = chunkSizeBytes ?? DEFAULT_STREAM_CHUNK_SIZE_BYTES;
+  if (!Number.isInteger(resolvedChunkSize) || resolvedChunkSize <= 0) {
+    throw new Error("Stream chunkSizeBytes must be a positive integer.");
+  }
+  if (resolvedChunkSize > MAX_STREAM_CHUNK_SIZE_BYTES) {
+    throw new Error(
+      `Stream chunkSizeBytes cannot exceed ${MAX_STREAM_CHUNK_SIZE_BYTES} bytes.`
+    );
+  }
+  return resolvedChunkSize;
+}
+function resolveKnownStreamSourceSize(source, hint) {
+  if (hint !== void 0) {
+    if (!Number.isInteger(hint) || hint < 0) {
+      throw new Error("Stream totalBytes must be a non-negative integer.");
+    }
+    return hint;
+  }
+  if (Buffer.isBuffer(source)) {
+    return source.length;
+  }
+  if (source instanceof Uint8Array) {
+    return source.byteLength;
+  }
+  return void 0;
+}
+function normalizeChunkSourceValue(value) {
+  if (Buffer.isBuffer(value)) {
+    return value;
+  }
+  if (value instanceof Uint8Array) {
+    return Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+  }
+  if (value instanceof ArrayBuffer) {
+    return Buffer.from(value);
+  }
+  if (typeof value === "string") {
+    return Buffer.from(value, "utf8");
+  }
+  throw new Error("Stream source yielded an unsupported chunk value.");
+}
+function isAsyncIterableValue(value) {
+  return typeof value === "object" && value !== null && Symbol.asyncIterator in value;
+}
+function isReadableSource(value) {
+  return value instanceof stream.Readable;
+}
+function splitChunkBuffer(chunk, chunkSizeBytes) {
+  if (chunk.length <= chunkSizeBytes) {
+    return [chunk];
+  }
+  const splitChunks = [];
+  for (let offset = 0; offset < chunk.length; offset += chunkSizeBytes) {
+    splitChunks.push(chunk.subarray(offset, offset + chunkSizeBytes));
+  }
+  return splitChunks;
+}
+async function* createChunkStreamIterator(source, chunkSizeBytes) {
+  if (Buffer.isBuffer(source)) {
+    yield* splitChunkBuffer(source, chunkSizeBytes);
+    return;
+  }
+  if (source instanceof Uint8Array) {
+    yield* splitChunkBuffer(
+      Buffer.from(source.buffer, source.byteOffset, source.byteLength),
+      chunkSizeBytes
+    );
+    return;
+  }
+  if (isReadableSource(source) || isAsyncIterableValue(source)) {
+    for await (const chunkValue of source) {
+      const normalizedChunk = normalizeChunkSourceValue(chunkValue);
+      if (normalizedChunk.length === 0) {
+        continue;
+      }
+      yield* splitChunkBuffer(normalizedChunk, chunkSizeBytes);
+    }
+    return;
+  }
+  throw new Error("Unsupported stream source type.");
+}
+function parseStreamFramePayload(data) {
+  if (typeof data !== "object" || data === null) {
+    throw new Error("Invalid stream frame payload format.");
+  }
+  const payload = data;
+  if (payload.version !== STREAM_FRAME_VERSION) {
+    throw new Error(`Unsupported stream frame version: ${String(payload.version)}.`);
+  }
+  if (typeof payload.streamId !== "string" || payload.streamId.trim().length === 0) {
+    throw new Error("Stream frame streamId must be a non-empty string.");
+  }
+  if (payload.type === "start") {
+    if (typeof payload.event !== "string" || payload.event.trim().length === 0) {
+      throw new Error("Stream start frame event must be a non-empty string.");
+    }
+    if (payload.totalBytes !== void 0 && (!Number.isInteger(payload.totalBytes) || payload.totalBytes < 0)) {
+      throw new Error("Stream start frame totalBytes must be a non-negative integer.");
+    }
+    if (payload.metadata !== void 0 && !isPlainObject(payload.metadata)) {
+      throw new Error("Stream start frame metadata must be a plain object when provided.");
+    }
+    return {
+      version: STREAM_FRAME_VERSION,
+      type: "start",
+      streamId: payload.streamId.trim(),
+      event: payload.event.trim(),
+      ...payload.metadata ? { metadata: payload.metadata } : {},
+      ...payload.totalBytes !== void 0 ? { totalBytes: payload.totalBytes } : {}
+    };
+  }
+  if (payload.type === "chunk") {
+    const { index, byteLength } = payload;
+    if (typeof index !== "number" || !Number.isInteger(index) || index < 0) {
+      throw new Error("Stream chunk frame index must be a non-negative integer.");
+    }
+    if (typeof payload.payload !== "string" || payload.payload.length === 0) {
+      throw new Error("Stream chunk frame payload must be a non-empty base64 string.");
+    }
+    if (typeof byteLength !== "number" || !Number.isInteger(byteLength) || byteLength <= 0) {
+      throw new Error("Stream chunk frame byteLength must be a positive integer.");
+    }
+    return {
+      version: STREAM_FRAME_VERSION,
+      type: "chunk",
+      streamId: payload.streamId.trim(),
+      index,
+      payload: payload.payload,
+      byteLength
+    };
+  }
+  if (payload.type === "end") {
+    const { chunkCount, totalBytes } = payload;
+    if (typeof chunkCount !== "number" || !Number.isInteger(chunkCount) || chunkCount < 0) {
+      throw new Error("Stream end frame chunkCount must be a non-negative integer.");
+    }
+    if (typeof totalBytes !== "number" || !Number.isInteger(totalBytes) || totalBytes < 0) {
+      throw new Error("Stream end frame totalBytes must be a non-negative integer.");
+    }
+    return {
+      version: STREAM_FRAME_VERSION,
+      type: "end",
+      streamId: payload.streamId.trim(),
+      chunkCount,
+      totalBytes
+    };
+  }
+  if (payload.type === "abort") {
+    if (typeof payload.reason !== "string" || payload.reason.trim().length === 0) {
+      throw new Error("Stream abort frame reason must be a non-empty string.");
+    }
+    return {
+      version: STREAM_FRAME_VERSION,
+      type: "abort",
+      streamId: payload.streamId.trim(),
+      reason: payload.reason.trim()
+    };
+  }
+  throw new Error("Unsupported stream frame type.");
+}
+async function transmitChunkedStreamFrames(event, source, options, sendFrame) {
+  const chunkSizeBytes = normalizeStreamChunkSize(options?.chunkSizeBytes);
+  const totalBytesHint = resolveKnownStreamSourceSize(source, options?.totalBytes);
+  if (options?.metadata !== void 0 && !isPlainObject(options.metadata)) {
+    throw new Error("Stream metadata must be a plain object when provided.");
+  }
+  if (options?.signal?.aborted) {
+    throw new Error("Stream transfer aborted before dispatch.");
+  }
+  const streamId = crypto.randomUUID();
+  let chunkCount = 0;
+  let totalBytes = 0;
+  await sendFrame({
+    version: STREAM_FRAME_VERSION,
+    type: "start",
+    streamId,
+    event,
+    ...options?.metadata ? { metadata: options.metadata } : {},
+    ...totalBytesHint !== void 0 ? { totalBytes: totalBytesHint } : {}
+  });
+  try {
+    for await (const chunkBuffer of createChunkStreamIterator(source, chunkSizeBytes)) {
+      if (options?.signal?.aborted) {
+        throw new Error("Stream transfer aborted by caller signal.");
+      }
+      if (chunkBuffer.length === 0) {
+        continue;
+      }
+      await sendFrame({
+        version: STREAM_FRAME_VERSION,
+        type: "chunk",
+        streamId,
+        index: chunkCount,
+        payload: chunkBuffer.toString("base64"),
+        byteLength: chunkBuffer.length
+      });
+      chunkCount += 1;
+      totalBytes += chunkBuffer.length;
+    }
+    if (totalBytesHint !== void 0 && totalBytes !== totalBytesHint) {
+      throw new Error(
+        `Stream totalBytes mismatch. Expected ${totalBytesHint}, received ${totalBytes}.`
+      );
+    }
+    await sendFrame({
+      version: STREAM_FRAME_VERSION,
+      type: "end",
+      streamId,
+      chunkCount,
+      totalBytes
+    });
+    return {
+      streamId,
+      chunkCount,
+      totalBytes
+    };
+  } catch (error) {
+    const normalizedError = normalizeToError(
+      error,
+      `Chunked stream transfer failed for event "${event}".`
+    );
+    try {
+      await sendFrame({
+        version: STREAM_FRAME_VERSION,
+        type: "abort",
+        streamId,
+        reason: normalizedError.message
+      });
+    } catch {
+    }
+    throw normalizedError;
+  }
+}
 function parseRpcRequestPayload(data) {
   if (typeof data !== "object" || data === null) {
     throw new Error("Invalid RPC request payload format.");
@@ -554,6 +796,7 @@ function decryptSerializedEnvelope(rawData, encryptionKey) {
 }
 var SecureServer = class {
   instanceId = crypto.randomUUID();
+  startedAtMs = Date.now();
   socketServer;
   adapter = null;
   heartbeatConfig;
@@ -563,6 +806,7 @@ var SecureServer = class {
   clientsById = /* @__PURE__ */ new Map();
   clientIdBySocket = /* @__PURE__ */ new Map();
   customEventHandlers = /* @__PURE__ */ new Map();
+  streamEventHandlers = /* @__PURE__ */ new Map();
   connectionHandlers = /* @__PURE__ */ new Set();
   disconnectHandlers = /* @__PURE__ */ new Set();
   readyHandlers = /* @__PURE__ */ new Set();
@@ -573,6 +817,7 @@ var SecureServer = class {
   sharedSecretBySocket = /* @__PURE__ */ new WeakMap();
   encryptionKeyBySocket = /* @__PURE__ */ new WeakMap();
   pendingPayloadsBySocket = /* @__PURE__ */ new WeakMap();
+  incomingStreamsBySocket = /* @__PURE__ */ new WeakMap();
   pendingRpcRequestsBySocket = /* @__PURE__ */ new WeakMap();
   heartbeatStateBySocket = /* @__PURE__ */ new WeakMap();
   roomMembersByName = /* @__PURE__ */ new Map();
@@ -581,6 +826,20 @@ var SecureServer = class {
   rateLimitBucketsByClientId = /* @__PURE__ */ new Map();
   rateLimitBucketsByIp = /* @__PURE__ */ new Map();
   sessionTicketStore = /* @__PURE__ */ new Map();
+  telemetryCounters = {
+    totalConnections: 0,
+    handshakeSuccessTotal: 0,
+    handshakeFailureTotal: 0,
+    resumeHandshakeSuccessTotal: 0,
+    resumeHandshakeFailureTotal: 0,
+    encryptedMessagesSentTotal: 0,
+    encryptedMessagesReceivedTotal: 0,
+    encryptedBytesSentTotal: 0,
+    encryptedBytesReceivedTotal: 0,
+    ddosBlockedTotal: 0,
+    ddosThrottledTotal: 0,
+    ddosDisconnectedTotal: 0
+  };
   constructor(options) {
     const { heartbeat, rateLimit, sessionResumption, adapter, ...socketServerOptions } = options;
     this.heartbeatConfig = this.resolveHeartbeatConfig(heartbeat);
@@ -604,6 +863,79 @@ var SecureServer = class {
   get clients() {
     return this.clientsById;
   }
+  getMetrics() {
+    const now = Date.now();
+    const uptimeSeconds = Math.max(0, (now - this.startedAtMs) / 1e3);
+    return {
+      serverId: this.instanceId,
+      timestampMs: now,
+      uptimeSeconds,
+      activeConnections: this.clientCount,
+      totalConnections: this.telemetryCounters.totalConnections,
+      handshakeSuccessTotal: this.telemetryCounters.handshakeSuccessTotal,
+      handshakeFailureTotal: this.telemetryCounters.handshakeFailureTotal,
+      resumeHandshakeSuccessTotal: this.telemetryCounters.resumeHandshakeSuccessTotal,
+      resumeHandshakeFailureTotal: this.telemetryCounters.resumeHandshakeFailureTotal,
+      encryptedMessagesSentTotal: this.telemetryCounters.encryptedMessagesSentTotal,
+      encryptedMessagesReceivedTotal: this.telemetryCounters.encryptedMessagesReceivedTotal,
+      encryptedBytesSentTotal: this.telemetryCounters.encryptedBytesSentTotal,
+      encryptedBytesReceivedTotal: this.telemetryCounters.encryptedBytesReceivedTotal,
+      ddosBlockedTotal: this.telemetryCounters.ddosBlockedTotal,
+      ddosThrottledTotal: this.telemetryCounters.ddosThrottledTotal,
+      ddosDisconnectedTotal: this.telemetryCounters.ddosDisconnectedTotal
+    };
+  }
+  getMetricsPrometheus() {
+    const metrics = this.getMetrics();
+    const labelValue = escapePrometheusLabelValue(metrics.serverId);
+    const labels = `{server_id="${labelValue}"}`;
+    const lines = [
+      "# HELP aegis_fluxion_server_active_connections Number of currently active secure connections.",
+      "# TYPE aegis_fluxion_server_active_connections gauge",
+      `aegis_fluxion_server_active_connections${labels} ${metrics.activeConnections}`,
+      "# HELP aegis_fluxion_server_total_connections_total Total number of accepted secure connections since process start.",
+      "# TYPE aegis_fluxion_server_total_connections_total counter",
+      `aegis_fluxion_server_total_connections_total${labels} ${metrics.totalConnections}`,
+      "# HELP aegis_fluxion_server_uptime_seconds Process uptime in seconds.",
+      "# TYPE aegis_fluxion_server_uptime_seconds gauge",
+      `aegis_fluxion_server_uptime_seconds${labels} ${metrics.uptimeSeconds}`,
+      "# HELP aegis_fluxion_server_handshake_success_total Total successful secure handshakes.",
+      "# TYPE aegis_fluxion_server_handshake_success_total counter",
+      `aegis_fluxion_server_handshake_success_total${labels} ${metrics.handshakeSuccessTotal}`,
+      "# HELP aegis_fluxion_server_handshake_failure_total Total failed secure handshake attempts.",
+      "# TYPE aegis_fluxion_server_handshake_failure_total counter",
+      `aegis_fluxion_server_handshake_failure_total${labels} ${metrics.handshakeFailureTotal}`,
+      "# HELP aegis_fluxion_server_resume_handshake_success_total Total successful session-resume handshakes.",
+      "# TYPE aegis_fluxion_server_resume_handshake_success_total counter",
+      `aegis_fluxion_server_resume_handshake_success_total${labels} ${metrics.resumeHandshakeSuccessTotal}`,
+      "# HELP aegis_fluxion_server_resume_handshake_failure_total Total failed session-resume handshakes.",
+      "# TYPE aegis_fluxion_server_resume_handshake_failure_total counter",
+      `aegis_fluxion_server_resume_handshake_failure_total${labels} ${metrics.resumeHandshakeFailureTotal}`,
+      "# HELP aegis_fluxion_server_encrypted_messages_sent_total Total encrypted messages sent by the server.",
+      "# TYPE aegis_fluxion_server_encrypted_messages_sent_total counter",
+      `aegis_fluxion_server_encrypted_messages_sent_total${labels} ${metrics.encryptedMessagesSentTotal}`,
+      "# HELP aegis_fluxion_server_encrypted_messages_received_total Total encrypted messages received by the server.",
+      "# TYPE aegis_fluxion_server_encrypted_messages_received_total counter",
+      `aegis_fluxion_server_encrypted_messages_received_total${labels} ${metrics.encryptedMessagesReceivedTotal}`,
+      "# HELP aegis_fluxion_server_encrypted_bytes_sent_total Total encrypted bytes sent by the server.",
+      "# TYPE aegis_fluxion_server_encrypted_bytes_sent_total counter",
+      `aegis_fluxion_server_encrypted_bytes_sent_total${labels} ${metrics.encryptedBytesSentTotal}`,
+      "# HELP aegis_fluxion_server_encrypted_bytes_received_total Total encrypted bytes received by the server.",
+      "# TYPE aegis_fluxion_server_encrypted_bytes_received_total counter",
+      `aegis_fluxion_server_encrypted_bytes_received_total${labels} ${metrics.encryptedBytesReceivedTotal}`,
+      "# HELP aegis_fluxion_server_ddos_blocked_total Total DDoS/flood attempts blocked by rate limiting.",
+      "# TYPE aegis_fluxion_server_ddos_blocked_total counter",
+      `aegis_fluxion_server_ddos_blocked_total${labels} ${metrics.ddosBlockedTotal}`,
+      "# HELP aegis_fluxion_server_ddos_throttled_total Total requests slowed down by adaptive throttling.",
+      "# TYPE aegis_fluxion_server_ddos_throttled_total counter",
+      `aegis_fluxion_server_ddos_throttled_total${labels} ${metrics.ddosThrottledTotal}`,
+      "# HELP aegis_fluxion_server_ddos_disconnected_total Total sockets disconnected due to severe rate limit violations.",
+      "# TYPE aegis_fluxion_server_ddos_disconnected_total counter",
+      `aegis_fluxion_server_ddos_disconnected_total${labels} ${metrics.ddosDisconnectedTotal}`
+    ];
+    return `${lines.join("\n")}
+`;
+  }
   async setAdapter(adapter) {
     const previousAdapter = this.adapter;
     if (previousAdapter === adapter) {
@@ -721,6 +1053,38 @@ var SecureServer = class {
     }
     return this;
   }
+  onStream(event, handler) {
+    try {
+      if (isReservedEmitEvent(event)) {
+        throw new Error(`The event "${event}" is reserved and cannot be used as a stream event.`);
+      }
+      const listeners = this.streamEventHandlers.get(event) ?? /* @__PURE__ */ new Set();
+      listeners.add(handler);
+      this.streamEventHandlers.set(event, listeners);
+    } catch (error) {
+      this.notifyError(
+        normalizeToError(error, "Failed to register server stream handler.")
+      );
+    }
+    return this;
+  }
+  offStream(event, handler) {
+    try {
+      const listeners = this.streamEventHandlers.get(event);
+      if (!listeners) {
+        return this;
+      }
+      listeners.delete(handler);
+      if (listeners.size === 0) {
+        this.streamEventHandlers.delete(event);
+      }
+    } catch (error) {
+      this.notifyError(
+        normalizeToError(error, "Failed to remove server stream handler.")
+      );
+    }
+    return this;
+  }
   use(middleware) {
     try {
       if (typeof middleware !== "function") {
@@ -796,6 +1160,40 @@ var SecureServer = class {
       return false;
     }
   }
+  async emitStreamTo(clientId, event, source, options) {
+    try {
+      if (isReservedEmitEvent(event)) {
+        throw new Error(`The event "${event}" is reserved and cannot be emitted manually.`);
+      }
+      const client = this.clientsById.get(clientId);
+      if (!client) {
+        throw new Error(`Client with id ${clientId} was not found.`);
+      }
+      if (!this.isClientHandshakeReady(client.socket)) {
+        throw new Error(
+          `Cannot stream event "${event}" before secure handshake completion for client ${client.id}.`
+        );
+      }
+      return await transmitChunkedStreamFrames(
+        event,
+        source,
+        options,
+        async (framePayload) => {
+          await this.sendEncryptedEnvelope(client.socket, {
+            event: INTERNAL_STREAM_FRAME_EVENT,
+            data: framePayload
+          });
+        }
+      );
+    } catch (error) {
+      const normalizedError = normalizeToError(
+        error,
+        `Failed to emit chunked stream event "${event}" to client ${clientId}.`
+      );
+      this.notifyError(normalizedError);
+      throw normalizedError;
+    }
+  }
   to(room) {
     const normalizedRoom = this.normalizeRoomName(room);
     return {
@@ -828,6 +1226,10 @@ var SecureServer = class {
           client.socket,
           new Error("Server closed before ACK response was received.")
         );
+        this.cleanupIncomingStreamsForSocket(
+          client.socket,
+          "Server closed before stream transfer completed."
+        );
         this.middlewareMetadataBySocket.delete(client.socket);
         if (client.socket.readyState === WebSocket__default.default.OPEN || client.socket.readyState === WebSocket__default.default.CONNECTING) {
           client.socket.close(code, reason);
@@ -842,6 +1244,35 @@ var SecureServer = class {
       this.notifyError(normalizeToError(error, "Failed to close server."));
     }
   }
+  recordHandshakeSuccess(resumed) {
+    this.telemetryCounters.handshakeSuccessTotal += 1;
+    if (resumed) {
+      this.telemetryCounters.resumeHandshakeSuccessTotal += 1;
+    }
+  }
+  recordHandshakeFailure(resumed) {
+    this.telemetryCounters.handshakeFailureTotal += 1;
+    if (resumed) {
+      this.telemetryCounters.resumeHandshakeFailureTotal += 1;
+    }
+  }
+  recordEncryptedMessageSent(byteLength) {
+    this.telemetryCounters.encryptedMessagesSentTotal += 1;
+    this.telemetryCounters.encryptedBytesSentTotal += Math.max(0, byteLength);
+  }
+  recordEncryptedMessageReceived(byteLength) {
+    this.telemetryCounters.encryptedMessagesReceivedTotal += 1;
+    this.telemetryCounters.encryptedBytesReceivedTotal += Math.max(0, byteLength);
+  }
+  recordDdosBlocked(disconnected) {
+    this.telemetryCounters.ddosBlockedTotal += 1;
+    if (disconnected) {
+      this.telemetryCounters.ddosDisconnectedTotal += 1;
+    }
+  }
+  recordDdosThrottled() {
+    this.telemetryCounters.ddosThrottledTotal += 1;
+  }
   resolveHeartbeatConfig(heartbeatOptions) {
     const intervalMs = heartbeatOptions?.intervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
     const timeoutMs = heartbeatOptions?.timeoutMs ?? DEFAULT_HEARTBEAT_TIMEOUT_MS;
@@ -1271,6 +1702,7 @@ var SecureServer = class {
         lastPingAt: 0
       });
       this.roomNamesByClientId.set(clientId, /* @__PURE__ */ new Set());
+      this.telemetryCounters.totalConnections += 1;
       socket.on("message", (rawData) => {
         void this.handleIncomingMessage(client, rawData);
       });
@@ -1299,6 +1731,7 @@ var SecureServer = class {
     try {
       const rateLimitDecision = this.evaluateIncomingRateLimit(client);
       if (rateLimitDecision.shouldDisconnect) {
+        this.recordDdosBlocked(true);
         this.notifyError(
           new Error(
             `Rate limit disconnect triggered for client ${client.id}.`
@@ -1313,9 +1746,11 @@ var SecureServer = class {
         return;
       }
       if (rateLimitDecision.shouldDrop) {
+        this.recordDdosBlocked(false);
         return;
       }
       if (rateLimitDecision.throttleDelayMs > 0) {
+        this.recordDdosThrottled();
         this.notifyError(
           new Error(
             `Rate limit throttle applied to client ${client.id} for ${rateLimitDecision.throttleDelayMs}ms.`
@@ -1356,6 +1791,7 @@ var SecureServer = class {
         return;
       }
       let decryptedPayload;
+      const encryptedPayloadByteLength = rawDataToBuffer(rawData).length;
       try {
         decryptedPayload = decryptSerializedEnvelope(rawData, encryptionKey);
       } catch {
@@ -1363,6 +1799,7 @@ var SecureServer = class {
         return;
       }
       const decryptedEnvelope = parseEnvelopeFromText(decryptedPayload);
+      this.recordEncryptedMessageReceived(encryptedPayloadByteLength);
       if (decryptedEnvelope.event === INTERNAL_RPC_RESPONSE_EVENT) {
         this.handleRpcResponse(client.socket, decryptedEnvelope.data);
         return;
@@ -1371,6 +1808,10 @@ var SecureServer = class {
         await this.handleRpcRequest(client, decryptedEnvelope.data);
         return;
       }
+      if (decryptedEnvelope.event === INTERNAL_STREAM_FRAME_EVENT) {
+        this.handleIncomingStreamFrame(client, decryptedEnvelope.data);
+        return;
+      }
       if (decryptedEnvelope.event === INTERNAL_SESSION_TICKET_EVENT) {
         this.notifyError(
           new Error(
@@ -1412,6 +1853,10 @@ var SecureServer = class {
       this.pendingRpcRequestsBySocket.delete(client.socket);
       this.heartbeatStateBySocket.delete(client.socket);
       this.middlewareMetadataBySocket.delete(client.socket);
+      this.cleanupIncomingStreamsForSocket(
+        client.socket,
+        `Client ${client.id} disconnected before stream transfer completed.`
+      );
       const decodedReason = decodeCloseReason(reason);
       for (const handler of this.disconnectHandlers) {
         try {
@@ -1457,6 +1902,197 @@ var SecureServer = class {
       }
     }
   }
+  getOrCreateIncomingServerStreams(socket) {
+    const existingStreams = this.incomingStreamsBySocket.get(socket);
+    if (existingStreams) {
+      return existingStreams;
+    }
+    const streamMap = /* @__PURE__ */ new Map();
+    this.incomingStreamsBySocket.set(socket, streamMap);
+    return streamMap;
+  }
+  cleanupIncomingStreamsForSocket(socket, reason) {
+    const streamMap = this.incomingStreamsBySocket.get(socket);
+    if (!streamMap) {
+      return;
+    }
+    for (const streamState of streamMap.values()) {
+      streamState.stream.destroy(new Error(reason));
+    }
+    streamMap.clear();
+    this.incomingStreamsBySocket.delete(socket);
+  }
+  abortIncomingServerStream(socket, streamId, reason) {
+    const streamMap = this.incomingStreamsBySocket.get(socket);
+    if (!streamMap) {
+      return;
+    }
+    const streamState = streamMap.get(streamId);
+    if (!streamState) {
+      return;
+    }
+    streamState.stream.destroy(new Error(reason));
+    streamMap.delete(streamId);
+    if (streamMap.size === 0) {
+      this.incomingStreamsBySocket.delete(socket);
+    }
+  }
+  dispatchServerStreamEvent(event, stream, info, client) {
+    const handlers = this.streamEventHandlers.get(event);
+    if (!handlers || handlers.size === 0) {
+      stream.resume();
+      this.notifyError(
+        new Error(
+          `No stream handler is registered for event "${event}" on server client ${client.id}.`
+        )
+      );
+      return;
+    }
+    for (const handler of handlers) {
+      try {
+        const handlerResult = handler(stream, info, client);
+        if (isPromiseLike(handlerResult)) {
+          void Promise.resolve(handlerResult).catch((error) => {
+            this.notifyError(
+              normalizeToError(
+                error,
+                `Server stream handler failed for event ${event}.`
+              )
+            );
+          });
+        }
+      } catch (error) {
+        this.notifyError(
+          normalizeToError(
+            error,
+            `Server stream handler failed for event ${event}.`
+          )
+        );
+      }
+    }
+  }
+  handleIncomingStreamStartFrame(client, framePayload) {
+    if (isReservedEmitEvent(framePayload.event)) {
+      throw new Error(
+        `Reserved event "${framePayload.event}" cannot be used for stream transport.`
+      );
+    }
+    const incomingStreams = this.getOrCreateIncomingServerStreams(client.socket);
+    if (incomingStreams.has(framePayload.streamId)) {
+      throw new Error(
+        `Stream ${framePayload.streamId} already exists for client ${client.id}.`
+      );
+    }
+    const stream$1 = new stream.PassThrough();
+    const streamInfo = {
+      streamId: framePayload.streamId,
+      event: framePayload.event,
+      startedAt: Date.now(),
+      ...framePayload.metadata !== void 0 ? { metadata: framePayload.metadata } : {},
+      ...framePayload.totalBytes !== void 0 ? { totalBytes: framePayload.totalBytes } : {}
+    };
+    incomingStreams.set(framePayload.streamId, {
+      info: streamInfo,
+      stream: stream$1,
+      expectedChunkIndex: 0,
+      receivedBytes: 0
+    });
+    this.dispatchServerStreamEvent(framePayload.event, stream$1, streamInfo, client);
+  }
+  handleIncomingStreamChunkFrame(client, framePayload) {
+    const incomingStreams = this.incomingStreamsBySocket.get(client.socket);
+    const streamState = incomingStreams?.get(framePayload.streamId);
+    if (!incomingStreams || !streamState) {
+      throw new Error(
+        `Stream ${framePayload.streamId} is unknown for client ${client.id}.`
+      );
+    }
+    if (framePayload.index !== streamState.expectedChunkIndex) {
+      throw new Error(
+        `Out-of-order chunk index for stream ${framePayload.streamId}. Expected ${streamState.expectedChunkIndex}, received ${framePayload.index}.`
+      );
+    }
+    const chunkBuffer = decodeBase64ToBuffer(
+      framePayload.payload,
+      `Stream chunk payload (${framePayload.streamId})`
+    );
+    if (chunkBuffer.length !== framePayload.byteLength) {
+      throw new Error(
+        `Stream ${framePayload.streamId} byteLength mismatch. Expected ${framePayload.byteLength}, received ${chunkBuffer.length}.`
+      );
+    }
+    streamState.expectedChunkIndex += 1;
+    streamState.receivedBytes += chunkBuffer.length;
+    streamState.stream.write(chunkBuffer);
+  }
+  handleIncomingStreamEndFrame(client, framePayload) {
+    const incomingStreams = this.incomingStreamsBySocket.get(client.socket);
+    const streamState = incomingStreams?.get(framePayload.streamId);
+    if (!incomingStreams || !streamState) {
+      throw new Error(
+        `Stream ${framePayload.streamId} is unknown for client ${client.id}.`
+      );
+    }
+    if (framePayload.chunkCount !== streamState.expectedChunkIndex) {
+      throw new Error(
+        `Stream ${framePayload.streamId} chunkCount mismatch. Expected ${streamState.expectedChunkIndex}, received ${framePayload.chunkCount}.`
+      );
+    }
+    if (framePayload.totalBytes !== streamState.receivedBytes) {
+      throw new Error(
+        `Stream ${framePayload.streamId} totalBytes mismatch. Expected ${streamState.receivedBytes}, received ${framePayload.totalBytes}.`
+      );
+    }
+    if (streamState.info.totalBytes !== void 0 && streamState.info.totalBytes !== streamState.receivedBytes) {
+      throw new Error(
+        `Stream ${framePayload.streamId} violated announced totalBytes (${streamState.info.totalBytes}).`
+      );
+    }
+    streamState.stream.end();
+    incomingStreams.delete(framePayload.streamId);
+    if (incomingStreams.size === 0) {
+      this.incomingStreamsBySocket.delete(client.socket);
+    }
+  }
+  handleIncomingStreamAbortFrame(client, framePayload) {
+    this.abortIncomingServerStream(
+      client.socket,
+      framePayload.streamId,
+      framePayload.reason
+    );
+  }
+  handleIncomingStreamFrame(client, data) {
+    let framePayload = null;
+    try {
+      framePayload = parseStreamFramePayload(data);
+      if (framePayload.type === "start") {
+        this.handleIncomingStreamStartFrame(client, framePayload);
+        return;
+      }
+      if (framePayload.type === "chunk") {
+        this.handleIncomingStreamChunkFrame(client, framePayload);
+        return;
+      }
+      if (framePayload.type === "end") {
+        this.handleIncomingStreamEndFrame(client, framePayload);
+        return;
+      }
+      this.handleIncomingStreamAbortFrame(client, framePayload);
+    } catch (error) {
+      const normalizedError = normalizeToError(
+        error,
+        `Failed to process incoming stream frame for client ${client.id}.`
+      );
+      if (framePayload) {
+        this.abortIncomingServerStream(
+          client.socket,
+          framePayload.streamId,
+          normalizedError.message
+        );
+      }
+      this.notifyError(normalizedError);
+    }
+  }
   async executeServerMiddleware(context) {
     if (this.middlewareHandlers.length === 0) {
       return;
@@ -1522,6 +2158,7 @@ var SecureServer = class {
     try {
       const serializedEnvelope = await serializeEnvelope(envelope.event, envelope.data);
       const encryptedPayload = encryptSerializedEnvelope(serializedEnvelope, encryptionKey);
+      this.recordEncryptedMessageSent(encryptedPayload.length);
       socket.send(encryptedPayload);
     } catch (error) {
       const normalizedError = normalizeToError(error, "Failed to send encrypted server payload.");
@@ -1720,6 +2357,7 @@ var SecureServer = class {
   }
   handleResumeHandshake(client, payload) {
     if (!this.sessionResumptionConfig.enabled) {
+      this.recordHandshakeFailure(true);
       this.sendResumeAck(client.socket, {
         ok: false,
         reason: "Session resumption is disabled."
@@ -1728,6 +2366,7 @@ var SecureServer = class {
     }
     const ticketRecord = this.getSessionTicket(payload.sessionId);
     if (!ticketRecord) {
+      this.recordHandshakeFailure(true);
       this.sendResumeAck(client.socket, {
         ok: false,
         reason: "Session ticket is unknown or expired."
@@ -1754,6 +2393,7 @@ var SecureServer = class {
         clientNonce
       );
       if (!equalsConstantTime(receivedProof, expectedProof)) {
+        this.recordHandshakeFailure(true);
         this.sendResumeAck(client.socket, {
           ok: false,
           reason: "Session resumption proof validation failed."
@@ -1774,6 +2414,7 @@ var SecureServer = class {
       this.sharedSecretBySocket.set(client.socket, resumedKey);
       this.encryptionKeyBySocket.set(client.socket, resumedKey);
       handshakeState.isReady = true;
+      this.recordHandshakeSuccess(true);
       this.sendResumeAck(client.socket, {
         ok: true,
         sessionId: ticketRecord.sessionId,
@@ -1783,6 +2424,7 @@ var SecureServer = class {
       this.notifyReady(client);
       this.issueSessionTicket(client.socket, resumedKey);
     } catch (error) {
+      this.recordHandshakeFailure(true);
       this.sendResumeAck(client.socket, {
         ok: false,
         reason: "Session resumption payload was invalid."
@@ -1813,10 +2455,12 @@ var SecureServer = class {
       this.sharedSecretBySocket.set(client.socket, sharedSecret);
       this.encryptionKeyBySocket.set(client.socket, encryptionKey);
       handshakeState.isReady = true;
+      this.recordHandshakeSuccess(false);
       void this.flushQueuedPayloads(client.socket);
       this.notifyReady(client);
       this.issueSessionTicket(client.socket, encryptionKey);
     } catch (error) {
+      this.recordHandshakeFailure(false);
       this.notifyError(normalizeToError(error, "Failed to complete server handshake."));
     }
   }
@@ -1885,6 +2529,9 @@ var SecureServer = class {
         }
         return this.emitTo(clientId, event, data, callbackOrOptions ?? {});
       },
+      emitStream: (event, source, options) => {
+        return this.emitStreamTo(clientId, event, source, options);
+      },
       join: (room) => this.joinClientToRoom(clientId, room),
       leave: (room) => this.leaveClientFromRoom(clientId, room),
       leaveAll: () => this.leaveClientFromAllRooms(clientId)
@@ -2045,6 +2692,7 @@ var SecureClient = class {
   reconnectTimer = null;
   isManualDisconnectRequested = false;
   customEventHandlers = /* @__PURE__ */ new Map();
+  streamEventHandlers = /* @__PURE__ */ new Map();
   connectHandlers = /* @__PURE__ */ new Set();
   disconnectHandlers = /* @__PURE__ */ new Set();
   readyHandlers = /* @__PURE__ */ new Set();
@@ -2052,6 +2700,7 @@ var SecureClient = class {
   handshakeState = null;
   pendingPayloadQueue = [];
   pendingRpcRequests = /* @__PURE__ */ new Map();
+  incomingStreams = /* @__PURE__ */ new Map();
   sessionTicket = null;
   get readyState() {
     return this.socket?.readyState ?? null;
@@ -2161,6 +2810,38 @@ var SecureClient = class {
     }
     return this;
   }
+  onStream(event, handler) {
+    try {
+      if (isReservedEmitEvent(event)) {
+        throw new Error(`The event "${event}" is reserved and cannot be used as a stream event.`);
+      }
+      const listeners = this.streamEventHandlers.get(event) ?? /* @__PURE__ */ new Set();
+      listeners.add(handler);
+      this.streamEventHandlers.set(event, listeners);
+    } catch (error) {
+      this.notifyError(
+        normalizeToError(error, "Failed to register client stream handler.")
+      );
+    }
+    return this;
+  }
+  offStream(event, handler) {
+    try {
+      const listeners = this.streamEventHandlers.get(event);
+      if (!listeners) {
+        return this;
+      }
+      listeners.delete(handler);
+      if (listeners.size === 0) {
+        this.streamEventHandlers.delete(event);
+      }
+    } catch (error) {
+      this.notifyError(
+        normalizeToError(error, "Failed to remove client stream handler.")
+      );
+    }
+    return this;
+  }
   emit(event, data, callbackOrOptions, maybeCallback) {
     const ackArgs = resolveAckArguments(callbackOrOptions, maybeCallback);
     try {
@@ -2206,6 +2887,39 @@ var SecureClient = class {
       return false;
     }
   }
+  async emitStream(event, source, options) {
+    try {
+      if (isReservedEmitEvent(event)) {
+        throw new Error(`The event "${event}" is reserved and cannot be emitted manually.`);
+      }
+      if (!this.socket || this.socket.readyState !== WebSocket__default.default.OPEN) {
+        throw new Error("Client socket is not connected.");
+      }
+      if (!this.isHandshakeReady()) {
+        throw new Error(
+          `Cannot stream event "${event}" before secure handshake completion.`
+        );
+      }
+      return await transmitChunkedStreamFrames(
+        event,
+        source,
+        options,
+        async (framePayload) => {
+          await this.sendEncryptedEnvelope({
+            event: INTERNAL_STREAM_FRAME_EVENT,
+            data: framePayload
+          });
+        }
+      );
+    } catch (error) {
+      const normalizedError = normalizeToError(
+        error,
+        `Failed to emit chunked stream event "${event}".`
+      );
+      this.notifyError(normalizedError);
+      throw normalizedError;
+    }
+  }
   resolveReconnectConfig(reconnectOptions) {
     if (typeof reconnectOptions === "boolean") {
       return {
@@ -2369,6 +3083,10 @@ var SecureClient = class {
         void this.handleRpcRequest(decryptedEnvelope.data);
         return;
       }
+      if (decryptedEnvelope.event === INTERNAL_STREAM_FRAME_EVENT) {
+        this.handleIncomingStreamFrame(decryptedEnvelope.data);
+        return;
+      }
       if (decryptedEnvelope.event === INTERNAL_SESSION_TICKET_EVENT) {
         this.handleSessionTicket(decryptedEnvelope.data);
         return;
@@ -2383,6 +3101,9 @@ var SecureClient = class {
       this.socket = null;
       this.handshakeState = null;
       this.pendingPayloadQueue = [];
+      this.cleanupIncomingStreams(
+        "Client disconnected before stream transfer completed."
+      );
       this.rejectPendingRpcRequests(
         new Error("Client disconnected before ACK response was received.")
       );
@@ -2429,6 +3150,151 @@ var SecureClient = class {
       }
     }
   }
+  cleanupIncomingStreams(reason) {
+    for (const streamState of this.incomingStreams.values()) {
+      streamState.stream.destroy(new Error(reason));
+    }
+    this.incomingStreams.clear();
+  }
+  abortIncomingClientStream(streamId, reason) {
+    const streamState = this.incomingStreams.get(streamId);
+    if (!streamState) {
+      return;
+    }
+    streamState.stream.destroy(new Error(reason));
+    this.incomingStreams.delete(streamId);
+  }
+  dispatchClientStreamEvent(event, stream, info) {
+    const handlers = this.streamEventHandlers.get(event);
+    if (!handlers || handlers.size === 0) {
+      stream.resume();
+      this.notifyError(
+        new Error(`No stream handler is registered for event "${event}" on client.`)
+      );
+      return;
+    }
+    for (const handler of handlers) {
+      try {
+        const handlerResult = handler(stream, info);
+        if (isPromiseLike(handlerResult)) {
+          void Promise.resolve(handlerResult).catch((error) => {
+            this.notifyError(
+              normalizeToError(
+                error,
+                `Client stream handler failed for event ${event}.`
+              )
+            );
+          });
+        }
+      } catch (error) {
+        this.notifyError(
+          normalizeToError(error, `Client stream handler failed for event ${event}.`)
+        );
+      }
+    }
+  }
+  handleIncomingClientStreamStartFrame(framePayload) {
+    if (isReservedEmitEvent(framePayload.event)) {
+      throw new Error(
+        `Reserved event "${framePayload.event}" cannot be used for stream transport.`
+      );
+    }
+    if (this.incomingStreams.has(framePayload.streamId)) {
+      throw new Error(`Stream ${framePayload.streamId} already exists on client.`);
+    }
+    const stream$1 = new stream.PassThrough();
+    const streamInfo = {
+      streamId: framePayload.streamId,
+      event: framePayload.event,
+      startedAt: Date.now(),
+      ...framePayload.metadata !== void 0 ? { metadata: framePayload.metadata } : {},
+      ...framePayload.totalBytes !== void 0 ? { totalBytes: framePayload.totalBytes } : {}
+    };
+    this.incomingStreams.set(framePayload.streamId, {
+      info: streamInfo,
+      stream: stream$1,
+      expectedChunkIndex: 0,
+      receivedBytes: 0
+    });
+    this.dispatchClientStreamEvent(framePayload.event, stream$1, streamInfo);
+  }
+  handleIncomingClientStreamChunkFrame(framePayload) {
+    const streamState = this.incomingStreams.get(framePayload.streamId);
+    if (!streamState) {
+      throw new Error(`Stream ${framePayload.streamId} is unknown on client.`);
+    }
+    if (framePayload.index !== streamState.expectedChunkIndex) {
+      throw new Error(
+        `Out-of-order chunk index for stream ${framePayload.streamId}. Expected ${streamState.expectedChunkIndex}, received ${framePayload.index}.`
+      );
+    }
+    const chunkBuffer = decodeBase64ToBuffer(
+      framePayload.payload,
+      `Stream chunk payload (${framePayload.streamId})`
+    );
+    if (chunkBuffer.length !== framePayload.byteLength) {
+      throw new Error(
+        `Stream ${framePayload.streamId} byteLength mismatch. Expected ${framePayload.byteLength}, received ${chunkBuffer.length}.`
+      );
+    }
+    streamState.expectedChunkIndex += 1;
+    streamState.receivedBytes += chunkBuffer.length;
+    streamState.stream.write(chunkBuffer);
+  }
+  handleIncomingClientStreamEndFrame(framePayload) {
+    const streamState = this.incomingStreams.get(framePayload.streamId);
+    if (!streamState) {
+      throw new Error(`Stream ${framePayload.streamId} is unknown on client.`);
+    }
+    if (framePayload.chunkCount !== streamState.expectedChunkIndex) {
+      throw new Error(
+        `Stream ${framePayload.streamId} chunkCount mismatch. Expected ${streamState.expectedChunkIndex}, received ${framePayload.chunkCount}.`
+      );
+    }
+    if (framePayload.totalBytes !== streamState.receivedBytes) {
+      throw new Error(
+        `Stream ${framePayload.streamId} totalBytes mismatch. Expected ${streamState.receivedBytes}, received ${framePayload.totalBytes}.`
+      );
+    }
+    if (streamState.info.totalBytes !== void 0 && streamState.info.totalBytes !== streamState.receivedBytes) {
+      throw new Error(
+        `Stream ${framePayload.streamId} violated announced totalBytes (${streamState.info.totalBytes}).`
+      );
+    }
+    streamState.stream.end();
+    this.incomingStreams.delete(framePayload.streamId);
+  }
+  handleIncomingClientStreamAbortFrame(framePayload) {
+    this.abortIncomingClientStream(framePayload.streamId, framePayload.reason);
+  }
+  handleIncomingStreamFrame(data) {
+    let framePayload = null;
+    try {
+      framePayload = parseStreamFramePayload(data);
+      if (framePayload.type === "start") {
+        this.handleIncomingClientStreamStartFrame(framePayload);
+        return;
+      }
+      if (framePayload.type === "chunk") {
+        this.handleIncomingClientStreamChunkFrame(framePayload);
+        return;
+      }
+      if (framePayload.type === "end") {
+        this.handleIncomingClientStreamEndFrame(framePayload);
+        return;
+      }
+      this.handleIncomingClientStreamAbortFrame(framePayload);
+    } catch (error) {
+      const normalizedError = normalizeToError(
+        error,
+        "Failed to process incoming stream frame on client."
+      );
+      if (framePayload) {
+        this.abortIncomingClientStream(framePayload.streamId, normalizedError.message);
+      }
+      this.notifyError(normalizedError);
+    }
+  }
   notifyConnect() {
     for (const handler of this.connectHandlers) {
       try {