@whogoes/server 1.0.0

package/README.md

@@ -0,0 +1,66 @@
+# @whogoes/server
+
+The backend service for Whogoes, built with Fastify, WebSocket, and Redis.
+
+## Architecture
+
+- **Fastify**: Web framework and WebSocket support.
+- **ioredis**: Redis client for Pub/Sub and state management.
+- **WebSocket**: Real-time communication with clients.
+
+## Configuration
+
+Environment variables can be set in a `.env` file or the system environment.
+
+| Variable | Description | Default |
+|Link |---|---| (sic)
+| `PORT` | The port the server listens on | `3000` |
+| `REDIS_URL` | Connection string for Redis | (local default) |
+| `USE_MOCK_REDIS` | Set to `true` to use in-memory Redis | `false` |
+
+## Running
+
+### Development
+
+Run the server with hot-reloading.
+
+```bash
+npm run dev
+```
+
+### Mock Mode
+
+Run without a real Redis instance (useful for local development).
+
+```bash
+npm run dev:mock
+```
+
+### Production
+
+Build and start the server.
+
+```bash
+npm run build
+npm run start
+```
+
+## API
+
+### WebSocket `/ws`
+
+The primary endpoint for client connections. Clients should upgrade to this endpoint to establish a WebSocket connection.
+
+**Query Parameters:**
+- `token`: Authentication token (currently mocked/placeholder).
+- `roomId`: The ID of the room to join.
+
+### Messages
+
+The server handles the following message types:
+
+- `ping` / `pong`: Heartbeat.
+- `presence.update`: Updates a user's state.
+- `presence.snapshot`: Sent to client on join with full room state.
+- `presence.join`: Broadcast when a user joins.
+- `presence.leave`: Broadcast when a user leaves.

package/dist/index.js

@@ -0,0 +1,254 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/index.ts
+var import_config = require("dotenv/config");
+
+// src/app.ts
+var import_fastify = __toESM(require("fastify"));
+var import_websocket = __toESM(require("@fastify/websocket"));
+
+// src/websocket.ts
+var import_uuid = require("uuid");
+
+// src/redis.ts
+var import_ioredis = __toESM(require("ioredis"));
+var import_ioredis_mock = __toESM(require("ioredis-mock"));
+var redisUrl = process.env.REDIS_URL || "redis://localhost:6379";
+var useMock = process.env.USE_MOCK_REDIS === "true";
+console.log(`Initializing Redis (Mock: ${useMock})`);
+var redisClient;
+var subRedisClient;
+if (useMock) {
+  const sharedData = {};
+  redisClient = new import_ioredis_mock.default({ data: sharedData });
+  subRedisClient = new import_ioredis_mock.default({ data: sharedData });
+} else {
+  redisClient = new import_ioredis.default(redisUrl);
+  subRedisClient = new import_ioredis.default(redisUrl);
+  redisClient.on("error", (err) => console.error("Redis Client Error", err));
+  subRedisClient.on("error", (err) => console.error("Redis Subscriber Error", err));
+  redisClient.on("connect", () => console.log("Redis connected"));
+  subRedisClient.on("connect", () => console.log("Redis subscriber connected"));
+}
+var redis = redisClient;
+var subRedis = subRedisClient;
+
+// src/roomManager.ts
+var RoomManager = class {
+  constructor() {
+    this.subscriptionMap = /* @__PURE__ */ new Map();
+    subRedis.on("message", (channel, message) => {
+      this.handleMessage(channel, message);
+    });
+  }
+  handleMessage(channel, message) {
+    if (channel.startsWith("presence:room:")) {
+      const handlers = this.subscriptionMap.get(channel);
+      if (handlers) {
+        const parsed = JSON.parse(message);
+        handlers.forEach((handler) => handler(parsed));
+      }
+    }
+  }
+  getRoomKey(roomId) {
+    return `presence:room:${roomId}`;
+  }
+  getRoomChannel(roomId) {
+    return `presence:room:${roomId}:channel`;
+  }
+  async joinRoom(roomId, sessionId, payload) {
+    const key = this.getRoomKey(roomId);
+    await redis.hset(key, sessionId, JSON.stringify(payload));
+    await redis.expire(key, 300);
+    await this.broadcast(roomId, { type: "presence.join", sessionId, payload });
+  }
+  async leaveRoom(roomId, sessionId) {
+    const key = this.getRoomKey(roomId);
+    await redis.hdel(key, sessionId);
+    await this.broadcast(roomId, { type: "presence.leave", sessionId });
+  }
+  async updatePresence(roomId, sessionId, payload) {
+    const key = this.getRoomKey(roomId);
+    const currentData = await redis.hget(key, sessionId);
+    if (currentData) {
+      const current = JSON.parse(currentData);
+      const updated = { ...current, ...payload, lastActiveAt: Date.now() };
+      console.log("RoomManager.updatePresence", { roomId, sessionId, payload });
+      await redis.hset(key, sessionId, JSON.stringify(updated));
+      await this.broadcast(roomId, { type: "presence.update", sessionId, payload: updated });
+    }
+  }
+  async getSnapshot(roomId) {
+    const key = this.getRoomKey(roomId);
+    const data = await redis.hgetall(key);
+    return Object.values(data).map((s) => JSON.parse(s));
+  }
+  async subscribeToRoom(roomId, callback) {
+    const channel = this.getRoomChannel(roomId);
+    let handlers = this.subscriptionMap.get(channel);
+    if (!handlers) {
+      handlers = /* @__PURE__ */ new Set();
+      this.subscriptionMap.set(channel, handlers);
+      await subRedis.subscribe(channel);
+    }
+    handlers.add(callback);
+    return () => {
+      handlers?.delete(callback);
+      if (handlers?.size === 0) {
+        this.subscriptionMap.delete(channel);
+        subRedis.unsubscribe(channel);
+      }
+    };
+  }
+  async broadcast(roomId, message) {
+    const channel = this.getRoomChannel(roomId);
+    await redis.publish(channel, JSON.stringify(message));
+  }
+};
+var roomManager = new RoomManager();
+
+// src/websocket.ts
+var websocketHandler = async (connection, req) => {
+  const socket = connection && connection.socket ? connection.socket : connection;
+  const { roomId, token } = req.query;
+  if (!roomId || !token) {
+    socket.close(1008, "Missing roomId or token");
+    return;
+  }
+  const userId = "user-" + (0, import_uuid.v4)().slice(0, 8);
+  const sessionId = (0, import_uuid.v4)();
+  const initialPayload = {
+    sessionId,
+    user: { id: userId, name: "Anonymous" },
+    status: "active",
+    lastActiveAt: Date.now()
+  };
+  let unsubscribe;
+  try {
+    unsubscribe = await roomManager.subscribeToRoom(roomId, (message) => {
+      if (message.sessionId !== sessionId) {
+        socket.send(JSON.stringify(message));
+      }
+    });
+    const snapshot = await roomManager.getSnapshot(roomId);
+    socket.send(JSON.stringify({ type: "presence.snapshot", sessions: snapshot }));
+    await roomManager.joinRoom(roomId, sessionId, initialPayload);
+    socket.on("message", async (message) => {
+      console.log("WS message received raw:", message && message.toString && message.toString());
+      try {
+        const data = JSON.parse(message.toString());
+        switch (data.type) {
+          case "presence.update":
+            await roomManager.updatePresence(roomId, sessionId, data.payload);
+            break;
+          case "ping":
+            socket.send(JSON.stringify({ type: "pong" }));
+            await roomManager.updatePresence(roomId, sessionId, { lastActiveAt: Date.now() });
+            break;
+        }
+      } catch (e) {
+        console.error("Error handling message", e);
+      }
+    });
+    socket.on("close", async () => {
+      if (unsubscribe) unsubscribe();
+      await roomManager.leaveRoom(roomId, sessionId);
+    });
+  } catch (err) {
+    console.error("WebSocket connection error:", err);
+    try {
+      socket.close(1011, "Internal Server Error");
+    } catch (e) {
+    }
+    if (unsubscribe) unsubscribe();
+  }
+};
+
+// src/routes.ts
+var routes = async (fastify) => {
+  fastify.get("/health", async () => {
+    return { status: "ok" };
+  });
+  fastify.get("/v1/rooms/:roomId/stats", async (request, reply) => {
+    const { roomId } = request.params;
+    const sessions = await roomManager.getSnapshot(roomId);
+    let lastActivity = 0;
+    if (sessions.length > 0) {
+      lastActivity = Math.max(...sessions.map((s) => s.lastActiveAt || 0));
+    }
+    return {
+      roomId,
+      activeSessions: sessions.length,
+      lastActivity: lastActivity > 0 ? new Date(lastActivity).toISOString() : null
+    };
+  });
+  fastify.get("/v1/rooms/:roomId/sessions", async (request, reply) => {
+    const { roomId } = request.params;
+    const sessions = await roomManager.getSnapshot(roomId);
+    return { sessions };
+  });
+  fastify.get("/v1/rooms/:roomId/sessions/:userId", async (request, reply) => {
+    const { roomId, userId } = request.params;
+    const sessions = await roomManager.getSnapshot(roomId);
+    const userSessions = sessions.filter((s) => s.user.id === userId);
+    return { sessions: userSessions };
+  });
+};
+
+// src/app.ts
+var buildApp = async () => {
+  const app = (0, import_fastify.default)({
+    logger: true
+  });
+  await app.register(import_websocket.default);
+  app.register(async (fastify) => {
+    fastify.get("/ws", { websocket: true }, websocketHandler);
+  });
+  app.register(routes);
+  return app;
+};
+
+// src/index.ts
+var start = async () => {
+  const app = await buildApp();
+  const port = process.env.PORT ? parseInt(process.env.PORT) : 3e3;
+  try {
+    await app.listen({ port, host: "0.0.0.0" });
+    console.log(`Server listening on port ${port}`);
+  } catch (err) {
+    app.log.error(err);
+    process.exit(1);
+  }
+  const close = async () => {
+    console.log("Shutting down...");
+    await app.close();
+    await redis.quit();
+    await subRedis.quit();
+    process.exit(0);
+  };
+  process.on("SIGINT", close);
+  process.on("SIGTERM", close);
+};
+start();

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@whogoes/server",
+  "version": "1.0.0",
+  "description": "Self-hostable real-time presence server — Fastify + WebSocket + Redis",
+  "main": "dist/index.js",
+  "bin": {
+    "whogoes-server": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "ts-node-dev --respawn --transpile-only src/index.ts",
+    "dev:mock": "USE_MOCK_REDIS=true ts-node-dev --respawn --transpile-only src/index.ts",
+    "build": "tsup src/index.ts --external @fastify/websocket --external fastify --external ioredis --external ioredis-mock --external uuid --external zod --external @whogoes/shared --external dotenv",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "presence",
+    "realtime",
+    "websocket",
+    "fastify",
+    "redis",
+    "collaboration",
+    "whogoes"
+  ],
+  "author": "whogoes contributors",
+  "license": "MIT",
+  "dependencies": {
+    "@fastify/websocket": "^10.0.1",
+    "@whogoes/shared": "*",
+    "dotenv": "^16.4.5",
+    "fastify": "^4.26.2",
+    "ioredis": "^5.3.2",
+    "uuid": "^9.0.1",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.24",
+    "@types/uuid": "^9.0.8",
+    "ioredis-mock": "^8.13.1",
+    "ts-node-dev": "^2.0.0",
+    "tsup": "^8.0.2"
+  }
+}