@rlanz/socket 0.0.1-3 → 0.0.1-4

package/README.md

@@ -23,26 +23,39 @@ Create a socket config file and tune the WebSocket path or heartbeat.
 
 ```ts
 // config/socket.ts
-import { defineConfig } from '@adonisjs/core/config'
+import { defineConfig } from '@rlanz/socket'
 
 export default defineConfig({
   websocket: {
     path: '/socket',
-    pingInterval: 25_000,
-    pingTimeout: 5_000,
+    pingInterval: '25s',
+    pingTimeout: '5s',
+    maxBufferedAmount: 16 * 1024 * 1024,
   },
 })
 ```
 
 - `websocket.path` defaults to `/socket`.
-- `websocket.pingInterval` sends a WebSocket ping every configured number of milliseconds.
+- `websocket.middleware` runs AdonisJS HTTP middleware for the WebSocket upgrade request.
+- `websocket.pingInterval` sends a WebSocket ping every configured duration.
 - `websocket.pingTimeout` closes connections that do not answer in time.
 - If only one heartbeat value is configured, the other one uses the default shown above.
+- `websocket.maxPayload` limits inbound message payloads; it defaults to 1 MiB.
+- `websocket.maxQueuedMessages` limits unresolved non-ping protocol messages per socket; it defaults
+  to `100`.
+- `websocket.maxMessagesPerInterval` limits inbound protocol messages per
+  `websocket.messageRateInterval`; they default to `1000` messages per `1s`.
+- `websocket.maxBufferedAmount` closes slow outbound sockets whose WebSocket buffer is already above
+  the configured byte limit before an event is sent; it defaults to 16 MiB.
+
+`websocket.middleware` is different from channel middleware. Use it to prepare request-scoped
+services such as sessions or auth during the initial HTTP upgrade; use `static middlewares` on a
+channel class to authorize or enrich individual channel subscriptions.
 
 ### Authentication
 
-Authenticate sockets during the HTTP upgrade with `websocket.authenticate`. The hook receives the
-upgrade request, the parsed client auth payload, and an AdonisJS HTTP context.
+Authenticate sockets during the HTTP upgrade with `websocket.authenticate`. The hook receives an
+AdonisJS HTTP context and returns the authenticated user.
 
 Define `websocket.middleware` when your WebSocket upgrade authentication depends on AdonisJS
 middleware such as sessions or auth initialization. These middleware run only for the HTTP upgrade
@@ -54,34 +67,34 @@ channel itself through `static middlewares`.
 
 ```ts
 // config/socket.ts
-import { defineConfig } from '@adonisjs/core/config'
+import type { HttpContext } from '@adonisjs/core/http'
+import { authenticateWithAdonisAuth, defineConfig } from '@rlanz/socket'
 
-export default defineConfig({
+type User = { id: string | number; name: string }
+
+export default defineConfig<User, HttpContext>({
   websocket: {
     middleware: [
       () => import('@adonisjs/session/session_middleware'),
       () => import('@adonisjs/auth/initialize_auth_middleware'),
     ],
 
-    async authenticate({ auth, httpContext }) {
-      await httpContext!.auth.authenticateUsing()
-      const user = httpContext!.auth.getUserOrFail()
-
-      return {
-        user,
-        auth,
-        data: {
-          connectedAt: new Date(),
-        },
-      }
-    },
+    authenticate: authenticateWithAdonisAuth<User, HttpContext>(),
   },
 })
 ```
 
-Return `false`, `null`, or throw to reject the upgrade with `401 Unauthorized`. The returned `user`
-is available as `socket.user`, `data` is stored on `socket.raw.data`, and the HTTP context remains
-available as `socket.raw.httpContext`.
+Return `false`, `null`, or throw to reject the upgrade with `401 Unauthorized`. The returned user is
+available as `socket.user`, and the HTTP context remains available as `socket.raw.httpContext`.
+
+Override `websocket.authenticate` when you need custom behavior:
+
+```ts
+async authenticate({ httpContext }) {
+  await httpContext!.auth.authenticateUsing()
+  return httpContext!.auth.getUserOrFail()
+}
+```
 
 ### Horizontal Sync
 
@@ -89,8 +102,8 @@ Configure an [`@boringnode/bus`](https://github.com/boringnode/bus) transport to
 
 ```ts
 // config/socket.ts
-import { defineConfig } from '@adonisjs/core/config'
 import { redis } from '@boringnode/bus/transports/redis'
+import { defineConfig } from '@rlanz/socket'
 
 export default defineConfig({
   transport: {
@@ -99,14 +112,14 @@ export default defineConfig({
       port: 6379,
     }),
     channel: 'socket::broadcast',
-    presenceTimeout: 100,
+    presenceTimeout: '100ms',
   },
 })
 ```
 
 When configured, `socket.to(channel).emit(...)`, `socket.to(channel).except(socketId).emit(...)`, `socket.toUser(userId).emit(...)`, and `socket.broadcast(...)` are delivered locally and published to the bus so other instances can deliver them to their own connected sockets.
 
-The default bus channel is `socket::broadcast`. Presence channels also use the bus to build distributed snapshots during subscribe, duplicate subscribe, join, and leave updates. `presenceTimeout` controls how long an instance waits for other instances to answer a presence snapshot request; it defaults to `100` milliseconds.
+The default bus channel is `socket::broadcast`. Presence channels also use the bus to build distributed snapshots during subscribe, duplicate subscribe, join, and leave updates. `presenceTimeout` controls how long an instance waits for other instances to answer a presence snapshot request; it defaults to `100ms`.
 
 ### Health Checks
 
@@ -337,7 +350,6 @@ import { Socket } from '@rlanz/socket/client'
 const socket = new Socket({
   url: 'http://localhost:3333',
   path: '/socket',
-  auth: { token: 'secret' },
   autoReconnect: true,
   reconnectDelay: 250,
   reconnectMaxDelay: 5000,
@@ -399,7 +411,11 @@ Set `autoReconnect: false` to disable reconnect attempts.
 import { BaseChannel, ChannelRouter, PresenceManager, SocketService } from '@rlanz/socket'
 import type { AuthenticatedSocket, SocketConfig } from '@rlanz/socket/types'
 import SocketProvider from '@rlanz/socket/provider'
+import socket from '@rlanz/socket/services/main'
 import { onMessage } from '@rlanz/socket/decorators'
+import { SocketHealthCheck } from '@rlanz/socket/health_check'
+import { SocketInstrumentation } from '@rlanz/socket/otel'
+import { SocketFake } from '@rlanz/socket/testing'
 import { Socket, Channel } from '@rlanz/socket/client'
 import type { SocketOptions, PresenceData } from '@rlanz/socket/client/types'
 ```
@@ -408,7 +424,12 @@ Available exports:
 
 - `@rlanz/socket`
 - `@rlanz/socket/provider`
+- `@rlanz/socket/services/main`
 - `@rlanz/socket/decorators`
+- `@rlanz/socket/health_check`
+- `@rlanz/socket/otel`
+- `@rlanz/socket/testing`
 - `@rlanz/socket/types`
+- `@rlanz/socket/types/tracing_channels`
 - `@rlanz/socket/client`
 - `@rlanz/socket/client/types`

package/build/{chunk-NRWRLZAO.js → chunk-ILDK672E.js}

@@ -797,22 +797,37 @@ function isClientMessageType(value) {
 // src/message_queue.ts
 var MessageQueue = class {
   #queues = /* @__PURE__ */ new Map();
-  enqueue(key, task) {
+  #depths = /* @__PURE__ */ new Map();
+  enqueue(key, task, options = {}) {
+    const depth = this.#depths.get(key) ?? 0;
+    if (options.maxDepth !== void 0 && depth >= options.maxDepth) {
+      return false;
+    }
+    this.#depths.set(key, depth + 1);
     const previous = this.#queues.get(key) ?? Promise.resolve();
     const next = previous.catch(() => {
     }).then(task).catch(() => {
     }).finally(() => {
+      const nextDepth = (this.#depths.get(key) ?? 1) - 1;
+      if (nextDepth <= 0) {
+        this.#depths.delete(key);
+      } else {
+        this.#depths.set(key, nextDepth);
+      }
       if (this.#queues.get(key) === next) {
         this.#queues.delete(key);
       }
     });
     this.#queues.set(key, next);
+    return true;
   }
   delete(key) {
     this.#queues.delete(key);
+    this.#depths.delete(key);
   }
   clear() {
     this.#queues.clear();
+    this.#depths.clear();
   }
 };
 
@@ -824,13 +839,28 @@ function userRoom(userId) {
 // src/socket_bus.ts
 import { randomUUID } from "crypto";
 import { Bus } from "@boringnode/bus";
+
+// src/duration.ts
+import { parse as parseDurationExpression } from "@lukeed/ms";
+function parseDuration(name, duration) {
+  if (duration === void 0) {
+    return void 0;
+  }
+  const milliseconds = typeof duration === "number" ? duration : parseDurationExpression(duration);
+  if (typeof milliseconds === "undefined" || !Number.isFinite(milliseconds) || milliseconds <= 0) {
+    throw new Error(`${name} must be a positive duration`);
+  }
+  return milliseconds;
+}
+
+// src/socket_bus.ts
 var DEFAULT_CHANNEL = "socket::broadcast";
 var DEFAULT_PRESENCE_TIMEOUT = 100;
 var SocketBus = class {
   constructor(transport, handlers) {
     this.handlers = handlers;
     this.#channel = transport.channel ?? DEFAULT_CHANNEL;
-    this.#presenceTimeout = transport.presenceTimeout ?? DEFAULT_PRESENCE_TIMEOUT;
+    this.#presenceTimeout = parseDuration("transport.presenceTimeout", transport.presenceTimeout) ?? DEFAULT_PRESENCE_TIMEOUT;
     this.#bus = new Bus(transport.driver(), { retryQueue: { enabled: true } });
   }
   #origin = randomUUID();
@@ -999,23 +1029,20 @@ var SocketUpgrader = class _SocketUpgrader {
     return url.pathname === this.#path;
   }
   async #authenticate(request) {
-    const auth = this.#parseAuth(request);
     const config = this.config;
     if (!config) {
-      return { auth };
+      return {};
     }
     if (!config.authenticate && !config.createContextOnUpgrade) {
-      return { auth };
+      return {};
     }
     let httpContext;
     try {
       httpContext = await config.createContext?.(request);
       if (!config.authenticate) {
-        return { auth, httpContext };
+        return { httpContext };
       }
       const ctx = {
-        request,
-        auth,
         httpContext
       };
       const result = await config.authenticate(ctx);
@@ -1023,51 +1050,62 @@ var SocketUpgrader = class _SocketUpgrader {
         return null;
       }
       return {
-        auth: result.auth ?? auth,
-        data: result.data,
         httpContext,
-        user: result.user
+        user: result
       };
     } catch {
       return null;
     }
   }
-  #parseAuth(request) {
-    const url = new URL(request.url ?? "/", "ws://localhost");
-    const auth = url.searchParams.get("auth");
-    if (!auth) {
-      return void 0;
-    }
-    try {
-      const parsed = JSON.parse(auth);
-      return parsed && typeof parsed === "object" ? parsed : void 0;
-    } catch {
-      return void 0;
-    }
-  }
 };
 
 // src/socket_service.ts
 var DEFAULT_PING_INTERVAL = 25e3;
 var DEFAULT_PING_TIMEOUT = 5e3;
+var DEFAULT_MAX_PAYLOAD = 1024 * 1024;
+var DEFAULT_MAX_QUEUED_MESSAGES = 100;
+var DEFAULT_MAX_MESSAGES_PER_INTERVAL = 1e3;
+var DEFAULT_MESSAGE_RATE_INTERVAL = 1e3;
+var DEFAULT_MAX_BUFFERED_AMOUNT = 16 * 1024 * 1024;
+var CLOSE_POLICY_VIOLATION = 1008;
+var CLOSE_MESSAGE_TOO_BIG = 1009;
+var CLOSE_OUTBOUND_BUFFER_LIMIT = "Socket outbound buffer limit exceeded";
+function serializeFrame(frame) {
+  return JSON.stringify(frame);
+}
+function sendSerializedFrame(connection, serializedFrame) {
+  if (connection.readyState !== WebSocket.OPEN) {
+    return false;
+  }
+  connection.send(serializedFrame);
+  return true;
+}
 function sendFrame(connection, frame) {
+  return sendSerializedFrame(connection, serializeFrame(frame));
+}
+function sendSerializedFrameWithBackpressure(connection, serializedFrame, config) {
   if (connection.readyState !== WebSocket.OPEN) {
-    return;
+    return false;
   }
-  connection.send(JSON.stringify(frame));
+  if (connection.bufferedAmount > config.maxBufferedAmount) {
+    closeConnection(connection, CLOSE_POLICY_VIOLATION, CLOSE_OUTBOUND_BUFFER_LIMIT);
+    return false;
+  }
+  connection.send(serializedFrame);
+  return true;
 }
-function validateDuration(name, value) {
+function parsePositiveInteger(name, value, fallback) {
   if (value === void 0) {
-    return void 0;
+    return fallback;
   }
-  if (!Number.isFinite(value) || value <= 0) {
-    throw new Error(`websocket.${name} must be a positive number of milliseconds`);
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new Error(`${name} must be a positive integer`);
   }
   return value;
 }
 function resolveHeartbeatConfig(config) {
-  const pingInterval = validateDuration("pingInterval", config?.pingInterval);
-  const pingTimeout = validateDuration("pingTimeout", config?.pingTimeout);
+  const pingInterval = parseDuration("websocket.pingInterval", config?.pingInterval);
+  const pingTimeout = parseDuration("websocket.pingTimeout", config?.pingTimeout);
   if (pingInterval === void 0 && pingTimeout === void 0) {
     return null;
   }
@@ -1076,6 +1114,47 @@ function resolveHeartbeatConfig(config) {
     timeout: pingTimeout ?? DEFAULT_PING_TIMEOUT
   };
 }
+function resolveInboundMessageConfig(config) {
+  const messageRateInterval = parseDuration("websocket.messageRateInterval", config?.messageRateInterval) ?? DEFAULT_MESSAGE_RATE_INTERVAL;
+  return {
+    maxPayload: parsePositiveInteger(
+      "websocket.maxPayload",
+      config?.maxPayload,
+      DEFAULT_MAX_PAYLOAD
+    ),
+    maxQueuedMessages: parsePositiveInteger(
+      "websocket.maxQueuedMessages",
+      config?.maxQueuedMessages,
+      DEFAULT_MAX_QUEUED_MESSAGES
+    ),
+    maxMessagesPerInterval: parsePositiveInteger(
+      "websocket.maxMessagesPerInterval",
+      config?.maxMessagesPerInterval,
+      DEFAULT_MAX_MESSAGES_PER_INTERVAL
+    ),
+    messageRateInterval
+  };
+}
+function resolveOutboundMessageConfig(config) {
+  return {
+    maxBufferedAmount: parsePositiveInteger(
+      "websocket.maxBufferedAmount",
+      config?.maxBufferedAmount,
+      DEFAULT_MAX_BUFFERED_AMOUNT
+    )
+  };
+}
+function getRawDataByteLength(data) {
+  if (Array.isArray(data)) {
+    return data.reduce((total, chunk) => total + chunk.byteLength, 0);
+  }
+  return data.byteLength;
+}
+function closeConnection(connection, code, reason) {
+  if (connection.readyState === WebSocket.OPEN) {
+    connection.close(code, reason);
+  }
+}
 var SocketService = class extends Emittery {
   #server = null;
   #httpServer = null;
@@ -1098,6 +1177,8 @@ var SocketService = class extends Emittery {
   #heartbeatInterval = null;
   #heartbeatTimeouts = /* @__PURE__ */ new Map();
   #messageQueue = new MessageQueue();
+  #messageRates = /* @__PURE__ */ new Map();
+  #outboundMessageConfig = resolveOutboundMessageConfig(void 0);
   /**
    * Accesses the underlying ws server.
    */
@@ -1123,6 +1204,8 @@ var SocketService = class extends Emittery {
     );
     const websocketConfig = config.websocket;
     const heartbeatConfig = resolveHeartbeatConfig(websocketConfig);
+    const inboundMessageConfig = resolveInboundMessageConfig(websocketConfig);
+    this.#outboundMessageConfig = resolveOutboundMessageConfig(websocketConfig);
     try {
       if (config.transport) {
         this.#bus = new SocketBus(config.transport, {
@@ -1163,14 +1246,15 @@ var SocketService = class extends Emittery {
         this.#configurePresenceFetcher();
       }
       const websocketServer = new WebSocketServer({
-        noServer: true
+        noServer: true,
+        maxPayload: inboundMessageConfig.maxPayload
       });
       this.#server = websocketServer;
       this.#httpServer = httpServer;
       const upgrader = new SocketUpgrader(websocketServer, websocketConfig);
       this.#upgradeHandler = (request, socket, head) => {
         upgrader.handle(request, socket, head, (connection, upgradeRequest, accepted) => {
-          this.#handleConnection(connection, upgradeRequest, accepted);
+          this.#handleConnection(connection, upgradeRequest, accepted, inboundMessageConfig);
         }).catch((error) => {
           logger.warn("failed to upgrade socket connection: %s", error);
           SocketUpgrader.reject(socket, 500, "Internal Server Error");
@@ -1186,7 +1270,7 @@ var SocketService = class extends Emittery {
       throw error;
     }
   }
-  #handleConnection(connection, request, upgrade) {
+  #handleConnection(connection, request, upgrade, inboundMessageConfig) {
     const socket = this.#wrapSocket(connection, request, upgrade);
     connectChannel.traceSync(
       () => {
@@ -1195,20 +1279,37 @@ var SocketService = class extends Emittery {
       },
       { socketId: socket.id }
     );
+    connection.on("error", () => {
+    });
     connection.on("message", (data) => {
+      if (getRawDataByteLength(data) > inboundMessageConfig.maxPayload) {
+        closeConnection(connection, CLOSE_MESSAGE_TOO_BIG, "Message too big");
+        return;
+      }
+      if (!this.#acceptMessageRate(socket.id, inboundMessageConfig)) {
+        closeConnection(connection, CLOSE_POLICY_VIOLATION, "Socket message rate limit exceeded");
+        return;
+      }
       const message = Message.fromTransport(data.toString());
       if (message.type === "ping") {
         sendFrame(socket.raw.connection, { id: message.id, type: "pong" });
         return;
       }
-      this.#messageQueue.enqueue(socket.id, async () => {
-        await this.#handleMessage(socket, message).catch((error) => {
-          sendFrame(connection, {
-            type: "error",
-            error: error instanceof Error ? error.message : "Unexpected socket error"
+      const enqueued = this.#messageQueue.enqueue(
+        socket.id,
+        async () => {
+          await this.#handleMessage(socket, message).catch((error) => {
+            sendFrame(connection, {
+              type: "error",
+              error: error instanceof Error ? error.message : "Unexpected socket error"
+            });
           });
-        });
-      });
+        },
+        { maxDepth: inboundMessageConfig.maxQueuedMessages }
+      );
+      if (!enqueued) {
+        closeConnection(connection, CLOSE_POLICY_VIOLATION, "Socket message queue limit exceeded");
+      }
     });
     connection.on("pong", () => {
       this.#clearHeartbeatTimeout(socket.id);
@@ -1222,6 +1323,7 @@ var SocketService = class extends Emittery {
       await disconnectChannel.tracePromise(async () => {
         this.#clearHeartbeatTimeout(socket.id);
         this.#messageQueue.delete(socket.id);
+        this.#messageRates.delete(socket.id);
         await this.#channelSubscriptions?.leaveAll(socket);
         this.#channelSubscriptions?.deleteSocket(socket.id);
         this.#sockets.delete(socket.id);
@@ -1306,8 +1408,7 @@ var SocketService = class extends Emittery {
   #wrapSocket(connection, request, upgrade) {
     const raw = {
       id: randomUUID2(),
-      data: upgrade.data ?? {},
-      auth: upgrade.auth,
+      data: {},
       connection,
       request,
       httpContext: upgrade.httpContext
@@ -1316,8 +1417,8 @@ var SocketService = class extends Emittery {
       id: raw.id,
       user: upgrade.user,
       channels: /* @__PURE__ */ new Set(),
-      emit(event, data) {
-        sendFrame(connection, { type: "event", event, data });
+      emit: (event, data) => {
+        this.#sendEventFrame(connection, { type: "event", event, data });
       },
       joinUserRoom: (userId) => {
         this.#joinUserRoom(raw.id, userRoom(userId));
@@ -1424,15 +1525,25 @@ var SocketService = class extends Emittery {
       message.delivered = deliver();
     }, message);
   }
+  #sendEventFrame(connection, frame) {
+    return this.#sendSerializedEventFrame(connection, serializeFrame(frame));
+  }
+  #sendSerializedEventFrame(connection, serializedFrame) {
+    return sendSerializedFrameWithBackpressure(
+      connection,
+      serializedFrame,
+      this.#outboundMessageConfig
+    );
+  }
   #emitToChannelLocally(channel, event, data, except = []) {
     let delivered = 0;
+    const serializedFrame = serializeFrame({ type: "event", channel, event, data });
     for (const socketId of this.#channelSubscriptions?.getSocketIds(channel) ?? []) {
       if (except.includes(socketId)) {
         continue;
       }
       const socket = this.#sockets.get(socketId);
-      if (socket) {
-        sendFrame(socket.raw.connection, { type: "event", channel, event, data });
+      if (socket && this.#sendSerializedEventFrame(socket.raw.connection, serializedFrame)) {
         delivered += 1;
       }
     }
@@ -1440,10 +1551,10 @@ var SocketService = class extends Emittery {
   }
   #emitToUserRoomLocally(room, event, data) {
     let delivered = 0;
+    const serializedFrame = serializeFrame({ type: "event", event, data });
     for (const socketId of this.#userRooms.get(room) ?? []) {
       const socket = this.#sockets.get(socketId);
-      if (socket) {
-        sendFrame(socket.raw.connection, { type: "event", event, data });
+      if (socket && this.#sendSerializedEventFrame(socket.raw.connection, serializedFrame)) {
         delivered += 1;
       }
     }
@@ -1451,9 +1562,11 @@ var SocketService = class extends Emittery {
   }
   #broadcastLocally(event, data) {
     let delivered = 0;
+    const serializedFrame = serializeFrame({ type: "event", event, data });
     for (const socket of this.#sockets.values()) {
-      sendFrame(socket.raw.connection, { type: "event", event, data });
-      delivered += 1;
+      if (this.#sendSerializedEventFrame(socket.raw.connection, serializedFrame)) {
+        delivered += 1;
+      }
     }
     return delivered;
   }
@@ -1576,6 +1689,19 @@ var SocketService = class extends Emittery {
     }
     this.#heartbeatTimeouts.clear();
   }
+  #acceptMessageRate(socketId, config) {
+    const now = Date.now();
+    const rate = this.#messageRates.get(socketId);
+    if (!rate || now - rate.intervalStartedAt >= config.messageRateInterval) {
+      this.#messageRates.set(socketId, { count: 1, intervalStartedAt: now });
+      return true;
+    }
+    if (rate.count >= config.maxMessagesPerInterval) {
+      return false;
+    }
+    rate.count += 1;
+    return true;
+  }
   #cleanup() {
     this.#stopHeartbeat();
     for (const socket of this.#sockets.values()) {
@@ -1585,6 +1711,7 @@ var SocketService = class extends Emittery {
     this.#userRooms.clear();
     this.#socketUserRoom.clear();
     this.#messageQueue.clear();
+    this.#messageRates.clear();
     this.#channelSubscriptions?.clear();
   }
   async close() {
@@ -1791,4 +1918,4 @@ export {
   SocketService,
   ChannelRouter
 };
-//# sourceMappingURL=chunk-NRWRLZAO.js.map
+//# sourceMappingURL=chunk-ILDK672E.js.map