@aegis-fluxion/core 0.9.0 → 0.10.0

package/README.md

@@ -2,7 +2,7 @@
 
 Low-level encrypted WebSocket primitives for the `aegis-fluxion` ecosystem.
 
-Version: **0.9.0**
+Version: **0.10.0**
 
 ---
 
@@ -10,6 +10,7 @@ Version: **0.9.0**
 
 - Ephemeral ECDH handshake (`prime256v1`)
 - AES-256-GCM encrypted envelopes
+- Built-in telemetry via `getMetrics()` and `getMetricsPrometheus()`
 - ACK request/response (Promise + callback styles)
 - Encrypted chunked streaming for large `Buffer`/`Readable` payloads
 - Secure room routing (`join`, `leave`, `leaveAll`, `to(room).emit(...)`)
@@ -28,6 +29,122 @@ npm install @aegis-fluxion/core ws
 
 ---
 
+## Observability & telemetry (new in 0.10.0)
+
+`SecureServer` exposes real-time metrics for operational visibility:
+
+- active secure connections
+- successful/failed handshakes (including resume attempts)
+- encrypted message and byte throughput (ingress/egress)
+- DDoS/rate-limit counters (blocked, throttled, disconnected)
+
+### JSON metrics snapshot
+
+```ts
+import { SecureServer } from "@aegis-fluxion/core";
+
+const server = new SecureServer({ host: "127.0.0.1", port: 8080 });
+
+const snapshot = server.getMetrics();
+console.log(snapshot.activeConnections);
+console.log(snapshot.encryptedMessagesReceivedTotal);
+```
+
+### Prometheus endpoint integration
+
+```ts
+import { createServer } from "node:http";
+import { SecureServer } from "@aegis-fluxion/core";
+
+const secureServer = new SecureServer({ host: "127.0.0.1", port: 8080 });
+
+createServer((request, response) => {
+  if (request.url === "/metrics") {
+    response.setHeader("Content-Type", "text/plain; version=0.0.4; charset=utf-8");
+    response.end(secureServer.getMetricsPrometheus());
+    return;
+  }
+
+  response.statusCode = 404;
+  response.end("Not Found");
+}).listen(9100, "127.0.0.1");
+```
+
+---
+
+## Frontend integration (React)
+
+`@aegis-fluxion/core` is server/runtime focused. For browser clients, pair it with
+`@aegis-fluxion/browser-client`.
+
+### Node backend (`SecureServer`)
+
+```ts
+import { SecureServer } from "@aegis-fluxion/core";
+
+const server = new SecureServer({ host: "127.0.0.1", port: 8080 });
+
+server.on("feed:publish", async (payload) => {
+  server.emit("feed:message", payload);
+  return { ok: true };
+});
+```
+
+### React frontend (`BrowserSecureClient`)
+
+```tsx
+import { useEffect, useMemo, useState } from "react";
+import { BrowserSecureClient } from "@aegis-fluxion/browser-client";
+
+export function SecureFeedPanel() {
+  const [status, setStatus] = useState("connecting");
+  const [messages, setMessages] = useState<string[]>([]);
+
+  const client = useMemo(() => {
+    return new BrowserSecureClient("ws://127.0.0.1:8080", {
+      autoConnect: false,
+      reconnect: true
+    });
+  }, []);
+
+  useEffect(() => {
+    const onReady = () => setStatus("ready");
+    const onDisconnect = () => setStatus("disconnected");
+    const onFeedMessage = (payload: unknown) => {
+      const data = payload as { text?: string };
+      if (typeof data.text === "string") {
+        setMessages((prev) => [data.text, ...prev]);
+      }
+    };
+
+    client.on("ready", onReady);
+    client.on("disconnect", onDisconnect);
+    client.on("feed:message", onFeedMessage);
+    client.connect();
+
+    return () => {
+      client.off("ready", onReady);
+      client.off("disconnect", onDisconnect);
+      client.off("feed:message", onFeedMessage);
+      client.disconnect();
+    };
+  }, [client]);
+
+  return (
+    <section>
+      <p>Status: {status}</p>
+      <ul>
+        {messages.map((message) => (
+          <li key={message}>{message}</li>
+        ))}
+      </ul>
+    </section>
+  );
+}
+```
+
+---
+
 ## Chunked streaming (new in 0.9.0)
 
 `@aegis-fluxion/core@0.9.0` adds secure chunked stream transport for large payloads.

package/dist/index.cjs

@@ -259,6 +259,9 @@ 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 === INTERNAL_STREAM_FRAME_EVENT || event === READY_EVENT;
 }
@@ -793,6 +796,7 @@ function decryptSerializedEnvelope(rawData, encryptionKey) {
 }
 var SecureServer = class {
   instanceId = crypto.randomUUID();
+  startedAtMs = Date.now();
   socketServer;
   adapter = null;
   heartbeatConfig;
@@ -822,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);
@@ -845,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) {
@@ -1153,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;
@@ -1582,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);
       });
@@ -1610,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}.`
@@ -1624,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.`
@@ -1667,6 +1791,7 @@ var SecureServer = class {
         return;
       }
       let decryptedPayload;
+      const encryptedPayloadByteLength = rawDataToBuffer(rawData).length;
       try {
         decryptedPayload = decryptSerializedEnvelope(rawData, encryptionKey);
       } catch {
@@ -1674,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;
@@ -2032,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.");
@@ -2230,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."
@@ -2238,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."
@@ -2264,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."
@@ -2284,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,
@@ -2293,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."
@@ -2323,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."));
     }
   }