@aegis-fluxion/core 0.7.0 → 0.7.2

package/dist/index.js

@@ -26,6 +26,59 @@ 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;
+var DEFAULT_RATE_LIMIT_WINDOW_MS = 1e3;
+var DEFAULT_RATE_LIMIT_MAX_EVENTS_PER_CONNECTION = 120;
+var DEFAULT_RATE_LIMIT_MAX_EVENTS_PER_IP = 300;
+var DEFAULT_RATE_LIMIT_THROTTLE_MS = 150;
+var DEFAULT_RATE_LIMIT_MAX_THROTTLE_MS = 2e3;
+var DEFAULT_RATE_LIMIT_DISCONNECT_AFTER_VIOLATIONS = 4;
+var DEFAULT_RATE_LIMIT_CLOSE_CODE = 1013;
+var DEFAULT_RATE_LIMIT_CLOSE_REASON = "Rate limit exceeded. Please retry later.";
+var SECURE_SERVER_ADAPTER_MESSAGE_VERSION = 1;
+function normalizeSecureServerAdapterMessage(value) {
+  if (!isPlainObject(value)) {
+    throw new Error("SecureServer adapter message must be a plain object.");
+  }
+  if (value.version !== SECURE_SERVER_ADAPTER_MESSAGE_VERSION) {
+    throw new Error(
+      `Unsupported SecureServer adapter message version: ${String(value.version)}.`
+    );
+  }
+  if (typeof value.originServerId !== "string" || value.originServerId.trim().length === 0) {
+    throw new Error("SecureServer adapter message originServerId must be a non-empty string.");
+  }
+  if (value.scope !== "broadcast" && value.scope !== "room") {
+    throw new Error('SecureServer adapter message scope must be either "broadcast" or "room".');
+  }
+  if (typeof value.event !== "string" || value.event.trim().length === 0) {
+    throw new Error("SecureServer adapter message event must be a non-empty string.");
+  }
+  if (typeof value.emittedAt !== "number" || !Number.isFinite(value.emittedAt)) {
+    throw new Error("SecureServer adapter message emittedAt must be a finite number.");
+  }
+  if (value.scope === "room") {
+    if (typeof value.room !== "string" || value.room.trim().length === 0) {
+      throw new Error("SecureServer adapter message room must be a non-empty string.");
+    }
+    return {
+      version: SECURE_SERVER_ADAPTER_MESSAGE_VERSION,
+      originServerId: value.originServerId,
+      scope: value.scope,
+      event: value.event,
+      data: value.data,
+      emittedAt: value.emittedAt,
+      room: value.room.trim()
+    };
+  }
+  return {
+    version: SECURE_SERVER_ADAPTER_MESSAGE_VERSION,
+    originServerId: value.originServerId,
+    scope: value.scope,
+    event: value.event,
+    data: value.data,
+    emittedAt: value.emittedAt
+  };
+}
 function normalizeToError(error, fallbackMessage) {
   if (error instanceof Error) {
     return error;
@@ -59,6 +112,11 @@ function rawDataToBuffer(rawData) {
   }
   return Buffer.from(rawData);
 }
+function delay(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
 function isBlobValue(value) {
   return typeof Blob !== "undefined" && value instanceof Blob;
 }
@@ -349,8 +407,11 @@ function decryptSerializedEnvelope(rawData, encryptionKey) {
   return plaintext.toString("utf8");
 }
 var SecureServer = class {
+  instanceId = randomUUID();
   socketServer;
+  adapter = null;
   heartbeatConfig;
+  rateLimitConfig;
   heartbeatIntervalHandle = null;
   clientsById = /* @__PURE__ */ new Map();
   clientIdBySocket = /* @__PURE__ */ new Map();
@@ -369,19 +430,80 @@ var SecureServer = class {
   heartbeatStateBySocket = /* @__PURE__ */ new WeakMap();
   roomMembersByName = /* @__PURE__ */ new Map();
   roomNamesByClientId = /* @__PURE__ */ new Map();
+  clientIpByClientId = /* @__PURE__ */ new Map();
+  rateLimitBucketsByClientId = /* @__PURE__ */ new Map();
+  rateLimitBucketsByIp = /* @__PURE__ */ new Map();
   constructor(options) {
-    const { heartbeat, ...socketServerOptions } = options;
+    const { heartbeat, rateLimit, adapter, ...socketServerOptions } = options;
     this.heartbeatConfig = this.resolveHeartbeatConfig(heartbeat);
+    this.rateLimitConfig = this.resolveRateLimitConfig(rateLimit);
     this.socketServer = new WebSocketServer(socketServerOptions);
     this.bindSocketServerEvents();
     this.startHeartbeatLoop();
+    if (adapter) {
+      void this.setAdapter(adapter).catch(() => {
+        return void 0;
+      });
+    }
   }
   get clientCount() {
     return this.clientsById.size;
   }
+  get serverId() {
+    return this.instanceId;
+  }
   get clients() {
     return this.clientsById;
   }
+  async setAdapter(adapter) {
+    const previousAdapter = this.adapter;
+    if (previousAdapter === adapter) {
+      return;
+    }
+    try {
+      if (previousAdapter?.detach) {
+        await Promise.resolve(previousAdapter.detach(this));
+      }
+      this.adapter = null;
+      if (!adapter) {
+        return;
+      }
+      await Promise.resolve(adapter.attach(this));
+      this.adapter = adapter;
+    } catch (error) {
+      const normalizedError = normalizeToError(
+        error,
+        "Failed to set SecureServer adapter."
+      );
+      this.notifyError(normalizedError);
+      throw normalizedError;
+    }
+  }
+  async handleAdapterMessage(message) {
+    try {
+      const normalizedMessage = normalizeSecureServerAdapterMessage(message);
+      if (normalizedMessage.originServerId === this.instanceId) {
+        return;
+      }
+      if (normalizedMessage.scope === "broadcast") {
+        this.emitLocally(normalizedMessage.event, normalizedMessage.data);
+        return;
+      }
+      if (!normalizedMessage.room) {
+        return;
+      }
+      this.emitToRoom(
+        normalizedMessage.room,
+        normalizedMessage.event,
+        normalizedMessage.data,
+        false
+      );
+    } catch (error) {
+      this.notifyError(
+        normalizeToError(error, "Failed to process SecureServer adapter message.")
+      );
+    }
+  }
   on(event, handler) {
     try {
       if (event === "connection") {
@@ -468,12 +590,12 @@ var SecureServer = class {
       if (isReservedEmitEvent(event)) {
         throw new Error(`The event "${event}" is reserved and cannot be emitted manually.`);
       }
-      const envelope = { event, data };
-      for (const client of this.clientsById.values()) {
-        void this.sendOrQueuePayload(client.socket, envelope).catch(() => {
-          return void 0;
-        });
-      }
+      this.emitLocally(event, data);
+      this.publishAdapterMessage({
+        scope: "broadcast",
+        event,
+        data
+      });
     } catch (error) {
       this.notifyError(normalizeToError(error, "Failed to emit server event."));
     }
@@ -530,7 +652,7 @@ var SecureServer = class {
     return {
       emit: (event, data) => {
         try {
-          this.emitToRoom(normalizedRoom, event, data);
+          this.emitToRoom(normalizedRoom, event, data, true);
         } catch (error) {
           this.notifyError(
             normalizeToError(error, `Failed to emit event to room ${normalizedRoom}.`)
@@ -543,6 +665,15 @@ var SecureServer = class {
   close(code = DEFAULT_CLOSE_CODE, reason = DEFAULT_CLOSE_REASON) {
     try {
       this.stopHeartbeatLoop();
+      const activeAdapter = this.adapter;
+      this.adapter = null;
+      if (activeAdapter?.detach) {
+        void Promise.resolve(activeAdapter.detach(this)).catch((error) => {
+          this.notifyError(
+            normalizeToError(error, "Failed to detach SecureServer adapter during close.")
+          );
+        });
+      }
       for (const client of this.clientsById.values()) {
         this.rejectPendingRpcRequests(
           client.socket,
@@ -553,6 +684,9 @@ var SecureServer = class {
           client.socket.close(code, reason);
         }
       }
+      this.rateLimitBucketsByClientId.clear();
+      this.rateLimitBucketsByIp.clear();
+      this.clientIpByClientId.clear();
       this.socketServer.close();
     } catch (error) {
       this.notifyError(normalizeToError(error, "Failed to close server."));
@@ -573,6 +707,211 @@ var SecureServer = class {
       timeoutMs
     };
   }
+  resolveRateLimitConfig(rateLimitOptions) {
+    const windowMs = rateLimitOptions?.windowMs ?? DEFAULT_RATE_LIMIT_WINDOW_MS;
+    const maxEventsPerConnection = rateLimitOptions?.maxEventsPerConnection ?? DEFAULT_RATE_LIMIT_MAX_EVENTS_PER_CONNECTION;
+    const maxEventsPerIp = rateLimitOptions?.maxEventsPerIp ?? DEFAULT_RATE_LIMIT_MAX_EVENTS_PER_IP;
+    const action = rateLimitOptions?.action ?? "throttle";
+    const throttleMs = rateLimitOptions?.throttleMs ?? DEFAULT_RATE_LIMIT_THROTTLE_MS;
+    const maxThrottleMs = rateLimitOptions?.maxThrottleMs ?? DEFAULT_RATE_LIMIT_MAX_THROTTLE_MS;
+    const disconnectAfterViolations = rateLimitOptions?.disconnectAfterViolations ?? DEFAULT_RATE_LIMIT_DISCONNECT_AFTER_VIOLATIONS;
+    const disconnectCode = rateLimitOptions?.disconnectCode ?? DEFAULT_RATE_LIMIT_CLOSE_CODE;
+    const disconnectReason = rateLimitOptions?.disconnectReason ?? DEFAULT_RATE_LIMIT_CLOSE_REASON;
+    if (!Number.isFinite(windowMs) || windowMs <= 0) {
+      throw new Error("Server rateLimit windowMs must be a positive number.");
+    }
+    if (!Number.isFinite(maxEventsPerConnection) || maxEventsPerConnection <= 0) {
+      throw new Error(
+        "Server rateLimit maxEventsPerConnection must be a positive number."
+      );
+    }
+    if (!Number.isFinite(maxEventsPerIp) || maxEventsPerIp <= 0) {
+      throw new Error("Server rateLimit maxEventsPerIp must be a positive number.");
+    }
+    if (action !== "throttle" && action !== "disconnect") {
+      throw new Error('Server rateLimit action must be either "throttle" or "disconnect".');
+    }
+    if (!Number.isFinite(throttleMs) || throttleMs <= 0) {
+      throw new Error("Server rateLimit throttleMs must be a positive number.");
+    }
+    if (!Number.isFinite(maxThrottleMs) || maxThrottleMs <= 0) {
+      throw new Error("Server rateLimit maxThrottleMs must be a positive number.");
+    }
+    if (maxThrottleMs < throttleMs) {
+      throw new Error(
+        "Server rateLimit maxThrottleMs must be greater than or equal to throttleMs."
+      );
+    }
+    if (!Number.isInteger(disconnectAfterViolations) || disconnectAfterViolations <= 0) {
+      throw new Error(
+        "Server rateLimit disconnectAfterViolations must be a positive integer."
+      );
+    }
+    if (!Number.isInteger(disconnectCode) || disconnectCode < 1e3 || disconnectCode > 4999) {
+      throw new Error("Server rateLimit disconnectCode must be a valid WebSocket close code.");
+    }
+    return {
+      enabled: rateLimitOptions?.enabled ?? true,
+      windowMs,
+      maxEventsPerConnection,
+      maxEventsPerIp,
+      action,
+      throttleMs,
+      maxThrottleMs,
+      disconnectAfterViolations,
+      disconnectCode,
+      disconnectReason
+    };
+  }
+  createRateLimitBucket(now) {
+    return {
+      windowStartedAt: now,
+      count: 0,
+      violationCount: 0,
+      throttleUntil: 0,
+      lastSeenAt: now
+    };
+  }
+  getOrCreateRateLimitBucket(map, key, now) {
+    const existingBucket = map.get(key);
+    if (existingBucket) {
+      return existingBucket;
+    }
+    const bucket = this.createRateLimitBucket(now);
+    map.set(key, bucket);
+    return bucket;
+  }
+  updateRateLimitBucket(bucket, now) {
+    if (now - bucket.windowStartedAt >= this.rateLimitConfig.windowMs) {
+      bucket.windowStartedAt = now;
+      bucket.count = 0;
+      bucket.violationCount = 0;
+      bucket.throttleUntil = 0;
+    }
+    bucket.count += 1;
+    bucket.lastSeenAt = now;
+  }
+  pruneRateLimitBucketMap(map, now, maxIdleMs) {
+    for (const [key, bucket] of map.entries()) {
+      if (now - bucket.lastSeenAt >= maxIdleMs) {
+        map.delete(key);
+      }
+    }
+  }
+  pruneRateLimitBuckets(now) {
+    const maxIdleMs = this.rateLimitConfig.windowMs * 4;
+    this.pruneRateLimitBucketMap(this.rateLimitBucketsByClientId, now, maxIdleMs);
+    this.pruneRateLimitBucketMap(this.rateLimitBucketsByIp, now, maxIdleMs);
+  }
+  normalizeIpAddress(ipAddress) {
+    let normalized = ipAddress.trim().toLowerCase();
+    if (normalized.startsWith("::ffff:")) {
+      normalized = normalized.slice(7);
+    }
+    if (normalized.startsWith("[") && normalized.endsWith("]")) {
+      normalized = normalized.slice(1, -1);
+    }
+    const zoneIndex = normalized.indexOf("%");
+    if (zoneIndex >= 0) {
+      normalized = normalized.slice(0, zoneIndex);
+    }
+    return normalized.length > 0 ? normalized : "unknown";
+  }
+  resolveClientIp(request) {
+    const forwardedHeader = request.headers["x-forwarded-for"];
+    const forwardedValue = Array.isArray(forwardedHeader) ? forwardedHeader[0] : forwardedHeader;
+    if (typeof forwardedValue === "string") {
+      const firstForwardedIp = forwardedValue.split(",").map((item) => item.trim()).find((item) => item.length > 0);
+      if (firstForwardedIp) {
+        return this.normalizeIpAddress(firstForwardedIp);
+      }
+    }
+    return this.normalizeIpAddress(request.socket.remoteAddress ?? "unknown");
+  }
+  isIpStillConnected(ipAddress) {
+    for (const connectedIp of this.clientIpByClientId.values()) {
+      if (connectedIp === ipAddress) {
+        return true;
+      }
+    }
+    return false;
+  }
+  evaluateIncomingRateLimit(client) {
+    const noLimitDecision = {
+      shouldDisconnect: false,
+      shouldDrop: false,
+      throttleDelayMs: 0
+    };
+    if (!this.rateLimitConfig.enabled) {
+      return noLimitDecision;
+    }
+    const now = Date.now();
+    const clientBucket = this.getOrCreateRateLimitBucket(
+      this.rateLimitBucketsByClientId,
+      client.id,
+      now
+    );
+    this.updateRateLimitBucket(clientBucket, now);
+    const clientIp = this.clientIpByClientId.get(client.id);
+    const ipBucket = clientIp ? this.getOrCreateRateLimitBucket(this.rateLimitBucketsByIp, clientIp, now) : null;
+    if (ipBucket) {
+      this.updateRateLimitBucket(ipBucket, now);
+    }
+    const activeThrottleUntil = Math.max(
+      clientBucket.throttleUntil,
+      ipBucket?.throttleUntil ?? 0
+    );
+    if (activeThrottleUntil > now) {
+      return {
+        shouldDisconnect: false,
+        shouldDrop: true,
+        throttleDelayMs: 0
+      };
+    }
+    const isConnectionLimitExceeded = clientBucket.count > this.rateLimitConfig.maxEventsPerConnection;
+    const isIpLimitExceeded = ipBucket ? ipBucket.count > this.rateLimitConfig.maxEventsPerIp : false;
+    if (!isConnectionLimitExceeded && !isIpLimitExceeded) {
+      if (this.rateLimitBucketsByClientId.size > 1024 || this.rateLimitBucketsByIp.size > 1024) {
+        this.pruneRateLimitBuckets(now);
+      }
+      return noLimitDecision;
+    }
+    if (isConnectionLimitExceeded) {
+      clientBucket.violationCount += 1;
+    }
+    if (ipBucket && isIpLimitExceeded) {
+      ipBucket.violationCount += 1;
+    }
+    const violationCount = Math.max(
+      clientBucket.violationCount,
+      ipBucket?.violationCount ?? 0
+    );
+    const shouldDisconnect = this.rateLimitConfig.action === "disconnect" || violationCount >= this.rateLimitConfig.disconnectAfterViolations;
+    if (shouldDisconnect) {
+      return {
+        shouldDisconnect: true,
+        shouldDrop: true,
+        throttleDelayMs: 0
+      };
+    }
+    const throttleDelayMs = Math.min(
+      this.rateLimitConfig.maxThrottleMs,
+      Math.max(
+        this.rateLimitConfig.throttleMs,
+        this.rateLimitConfig.throttleMs * violationCount
+      )
+    );
+    const throttleUntil = now + throttleDelayMs;
+    clientBucket.throttleUntil = throttleUntil;
+    if (ipBucket) {
+      ipBucket.throttleUntil = throttleUntil;
+    }
+    return {
+      shouldDisconnect: false,
+      shouldDrop: false,
+      throttleDelayMs
+    };
+  }
   startHeartbeatLoop() {
     if (!this.heartbeatConfig.enabled || this.heartbeatIntervalHandle) {
       return;
@@ -675,6 +1014,8 @@ var SecureServer = class {
     try {
       const clientId = randomUUID();
       const handshakeState = this.createServerHandshakeState();
+      const clientIp = this.resolveClientIp(request);
+      connectionMetadata.set("network.ip", clientIp);
       const client = this.createSecureServerClient(
         clientId,
         socket,
@@ -683,6 +1024,7 @@ var SecureServer = class {
       );
       this.clientsById.set(clientId, client);
       this.clientIdBySocket.set(socket, clientId);
+      this.clientIpByClientId.set(clientId, clientIp);
       this.handshakeStateBySocket.set(socket, handshakeState);
       this.pendingPayloadsBySocket.set(socket, []);
       this.pendingRpcRequestsBySocket.set(socket, /* @__PURE__ */ new Map());
@@ -717,6 +1059,35 @@ var SecureServer = class {
   }
   async handleIncomingMessage(client, rawData) {
     try {
+      const rateLimitDecision = this.evaluateIncomingRateLimit(client);
+      if (rateLimitDecision.shouldDisconnect) {
+        this.notifyError(
+          new Error(
+            `Rate limit disconnect triggered for client ${client.id}.`
+          )
+        );
+        if (client.socket.readyState === WebSocket.OPEN || client.socket.readyState === WebSocket.CONNECTING) {
+          client.socket.close(
+            this.rateLimitConfig.disconnectCode,
+            this.rateLimitConfig.disconnectReason
+          );
+        }
+        return;
+      }
+      if (rateLimitDecision.shouldDrop) {
+        return;
+      }
+      if (rateLimitDecision.throttleDelayMs > 0) {
+        this.notifyError(
+          new Error(
+            `Rate limit throttle applied to client ${client.id} for ${rateLimitDecision.throttleDelayMs}ms.`
+          )
+        );
+        await delay(rateLimitDecision.throttleDelayMs);
+        if (client.socket.readyState !== WebSocket.OPEN) {
+          return;
+        }
+      }
       let envelope = null;
       try {
         envelope = parseEnvelope(rawData);
@@ -778,6 +1149,12 @@ var SecureServer = class {
       client.leaveAll();
       this.clientsById.delete(client.id);
       this.clientIdBySocket.delete(client.socket);
+      const disconnectedIp = this.clientIpByClientId.get(client.id);
+      this.clientIpByClientId.delete(client.id);
+      this.rateLimitBucketsByClientId.delete(client.id);
+      if (disconnectedIp && !this.isIpStillConnected(disconnectedIp)) {
+        this.rateLimitBucketsByIp.delete(disconnectedIp);
+      }
       this.handshakeStateBySocket.delete(client.socket);
       this.sharedSecretBySocket.delete(client.socket);
       this.encryptionKeyBySocket.delete(client.socket);
@@ -1165,6 +1542,48 @@ var SecureServer = class {
       leaveAll: () => this.leaveClientFromAllRooms(clientId)
     };
   }
+  emitLocally(event, data) {
+    const envelope = { event, data };
+    for (const client of this.clientsById.values()) {
+      void this.sendOrQueuePayload(client.socket, envelope).catch(() => {
+        return void 0;
+      });
+    }
+  }
+  publishAdapterMessage(message) {
+    if (!this.adapter) {
+      return;
+    }
+    let adapterMessage;
+    if (message.scope === "room") {
+      if (!message.room) {
+        return;
+      }
+      adapterMessage = {
+        version: SECURE_SERVER_ADAPTER_MESSAGE_VERSION,
+        originServerId: this.instanceId,
+        scope: "room",
+        event: message.event,
+        data: message.data,
+        emittedAt: Date.now(),
+        room: message.room
+      };
+    } else {
+      adapterMessage = {
+        version: SECURE_SERVER_ADAPTER_MESSAGE_VERSION,
+        originServerId: this.instanceId,
+        scope: "broadcast",
+        event: message.event,
+        data: message.data,
+        emittedAt: Date.now()
+      };
+    }
+    void Promise.resolve(this.adapter.publish(adapterMessage)).catch((error) => {
+      this.notifyError(
+        normalizeToError(error, "Failed to publish SecureServer adapter message.")
+      );
+    });
+  }
   normalizeRoomName(room) {
     if (typeof room !== "string") {
       throw new Error("Room name must be a string.");
@@ -1230,22 +1649,29 @@ var SecureServer = class {
     }
     return roomNames.length;
   }
-  emitToRoom(room, event, data) {
+  emitToRoom(room, event, data, replicate) {
     if (isReservedEmitEvent(event)) {
       throw new Error(`The event "${event}" is reserved and cannot be emitted manually.`);
     }
     const roomMembers = this.roomMembersByName.get(room);
-    if (!roomMembers || roomMembers.size === 0) {
-      return;
-    }
-    const envelope = { event, data };
-    for (const clientId of roomMembers) {
-      const client = this.clientsById.get(clientId);
-      if (!client) {
-        continue;
+    if (roomMembers && roomMembers.size > 0) {
+      const envelope = { event, data };
+      for (const clientId of roomMembers) {
+        const client = this.clientsById.get(clientId);
+        if (!client) {
+          continue;
+        }
+        void this.sendOrQueuePayload(client.socket, envelope).catch(() => {
+          return void 0;
+        });
       }
-      void this.sendOrQueuePayload(client.socket, envelope).catch(() => {
-        return void 0;
+    }
+    if (replicate) {
+      this.publishAdapterMessage({
+        scope: "room",
+        room,
+        event,
+        data
       });
     }
   }
@@ -1848,6 +2274,6 @@ var SecureClient = class {
   }
 };
 
-export { SecureClient, SecureServer };
+export { SecureClient, SecureServer, normalizeSecureServerAdapterMessage };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map