@lastshotlabs/bunshot 0.0.21 → 0.0.27

package/docs/sections/websocket/full.md

@@ -81,6 +81,101 @@ await createServer({
 
 You can supply any subset of `open`, `message`, `close`, `drain` — unset handlers fall back to the defaults.
 
+### Heartbeat / Ping-Pong Keepalive
+
+Opt-in via `ws.heartbeat`. Detects and closes stale connections via ping/pong:
+
+```ts
+await createServer({
+  ws: {
+    heartbeat: true, // 30s interval, 10s timeout
+    // or fine-tune:
+    heartbeat: { intervalMs: 15_000, timeoutMs: 5_000 },
+  },
+});
+```
+
+Every `intervalMs`, the server pings all connected sockets. If a socket hasn't responded within `timeoutMs`, it's closed with code `1001` ("Heartbeat timeout"). `stopHeartbeat()` is called automatically on SIGTERM/SIGINT and is also exported for custom shutdown logic.
+
+### Presence Tracking
+
+Opt-in via `ws.presence`. Tracks which authenticated users are online in each room (multi-tab aware):
+
+```ts
+await createServer({
+  ws: {
+    presence: true,
+  },
+});
+```
+
+When a user's first socket subscribes to a room, all room members receive `{ event: "presence_join", room, userId }`. When the user's last socket leaves (unsubscribe or disconnect), `{ event: "presence_leave", room, userId }` is broadcast.
+
+**Query presence:**
+
+```ts
+import { getRoomPresence, getUserPresence } from "@lastshotlabs/bunshot";
+
+getRoomPresence("chat:general"); // ["user1", "user2"] — deduplicated userIds
+getUserPresence("user1");        // ["chat:general", "chat:vip"] — rooms where user is present
+```
+
+### Message Persistence
+
+Opt-in via `ws.persistence`. Persists messages for late joiners. Rooms must be individually opted in via `configureRoom()`:
+
+```ts
+import { configureRoom, persistMessage, getMessageHistory } from "@lastshotlabs/bunshot";
+
+await createServer({
+  ws: {
+    persistence: {
+      store: "memory", // "redis" | "mongo" | "sqlite" | "memory"
+      defaults: { maxCount: 100, ttlSeconds: 86_400 }, // 24h
+    },
+  },
+});
+
+// Opt rooms in
+configureRoom("chat:general", { persist: true });
+configureRoom("chat:vip", { persist: true, maxCount: 50, ttlSeconds: 3600 });
+
+// Persist from your custom message handler
+await createServer({
+  ws: {
+    handler: {
+      async message(ws, message) {
+        const data = JSON.parse(message as string);
+        if (data.type === "chat") {
+          await persistMessage(data.room, {
+            senderId: ws.data.userId,
+            payload: data,
+          });
+        }
+      },
+    },
+  },
+});
+
+// Retrieve history (cursor-based pagination)
+const history = await getMessageHistory("chat:general", { limit: 50 });
+const older = await getMessageHistory("chat:general", { limit: 50, before: history[0].id });
+```
+
+Messages for non-configured rooms are silently ignored. Store errors are caught and logged (non-blocking) — message delivery is never interrupted by a persistence failure.
+
+### Room Name Validation
+
+Room names sent by clients via `subscribe` and `unsubscribe` actions are validated before any action is taken. Invalid room names are silently dropped — no error is sent to the client.
+
+**Valid room name rules:**
+- Characters: `a–z`, `A–Z`, `0–9`, `_`, `:`, `.`, `/`, `-`
+- Length: 1–128 characters
+
+Examples of valid names: `chat:general`, `user:123`, `tenant/room-1`, `notifications`
+
+Room names containing characters outside this set (e.g. spaces, `@`, `#`, or Unicode) are silently ignored. This prevents injection of arbitrary pub/sub topic names from untrusted client input.
+
 ### Overriding the upgrade / auth handler
 
 Replace the default cookie-JWT handshake entirely via `ws.upgradeHandler`. You must call `server.upgrade()` yourself and include `rooms: new Set()` in data:

package/docs/sections/websocket-rooms/full.md

@@ -13,6 +13,11 @@ Rooms are built on Bun's native pub/sub. `createServer` always intercepts room a
 | `getRooms()` | Returns `string[]` of all rooms with at least one active subscriber |
 | `getRoomSubscribers(room)` | Returns `string[]` of socket IDs currently subscribed to `room` |
 | `handleRoomActions(ws, message, onSubscribe?)` | Parses and dispatches subscribe/unsubscribe actions. Returns `true` if the message was a room action (consumed), `false` otherwise. Pass an optional async guard as the third argument. |
+| `getRoomPresence(room)` | Returns deduplicated `string[]` of userIds present in room (requires `ws.presence` enabled) |
+| `getUserPresence(userId)` | Returns `string[]` of rooms where user is present (requires `ws.presence` enabled) |
+| `persistMessage(room, data)` | Store a message for a room (requires `ws.persistence` + `configureRoom`). Returns `StoredMessage \| null` |
+| `getMessageHistory(room, opts?)` | Cursor-based retrieval. `opts`: `{ limit?, before?, after? }` (cursors are message IDs) |
+| `configureRoom(room, opts)` | Opt a room into persistence: `{ persist: true, maxCount?, ttlSeconds? }` |
 
 ### Client → server: join or leave a room
 
@@ -94,4 +99,4 @@ await createServer({
     },
   },
 });
-```
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lastshotlabs/bunshot",
-  "version": "0.0.21",
+  "version": "0.0.27",
   "description": "Batteries-included Bun + Hono API framework — auth, sessions, rate limiting, WebSocket, queues, and OpenAPI docs out of the box",
   "repository": {
     "type": "git",
@@ -52,8 +52,8 @@
     "start": "bun src/index.ts",
     "readme": "bun docs/build-readme.ts",
     "readme:npm": "bun docs/build-readme.ts npm",
-    "test": "bun test tests/unit tests/integration && bun test tests/isolated",
-    "test:isolated": "bun test tests/isolated",
+    "test": "bun test tests/unit tests/integration && bun test tests/isolated/optional-deps.test.ts && bun test tests/isolated/jwt-secret.test.ts && bun test tests/isolated/queue.test.ts tests/isolated/jobs-router.test.ts && bun test tests/isolated/queued-deletion.test.ts",
+    "test:isolated": "bun test tests/isolated/optional-deps.test.ts && bun test tests/isolated/jwt-secret.test.ts && bun test tests/isolated/queue.test.ts tests/isolated/jobs-router.test.ts && bun test tests/isolated/queued-deletion.test.ts",
     "test:coverage": "bun test --coverage tests/unit tests/integration",
     "test:docker:up": "docker compose -f docker-compose.test.yml up -d --wait",
     "test:docker:down": "docker compose -f docker-compose.test.yml down",
@@ -66,7 +66,8 @@
     "@hono/zod-openapi": "1.2.2",
     "@scalar/hono-api-reference": "0.10.0",
     "arctic": "^3.7.0",
-    "jose": "6.2.0"
+    "jose": "6.2.0",
+    "samlify": "^2.8"
   },
   "peerDependencies": {
     "hono": ">=4.12 <5",
@@ -75,7 +76,10 @@
     "ioredis": ">=5.0 <6",
     "bullmq": ">=5.0 <6",
     "otpauth": ">=9.0 <10",
-    "@simplewebauthn/server": ">=10.0.0"
+    "@simplewebauthn/server": ">=10.0.0",
+    "@aws-sdk/client-s3": ">=3.0",
+    "@aws-sdk/s3-request-presigner": ">=3.0",
+    "@aws-sdk/lib-storage": ">=3.0"
   },
   "peerDependenciesMeta": {
     "mongoose": {
@@ -92,6 +96,15 @@
     },
     "@simplewebauthn/server": {
       "optional": true
+    },
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "@aws-sdk/s3-request-presigner": {
+      "optional": true
+    },
+    "@aws-sdk/lib-storage": {
+      "optional": true
     }
   },
   "devDependencies": {