@smoothglue/sync-whiteboard 0.1.0 → 1.0.0

package/README.md

@@ -1,6 +1,8 @@
-## Overview
+## @smoothglue/sync-whiteboard
+
+A real-time collaborative whiteboard server designed to provide a realtime, collaborative whiteboard experience for frontends integrated with [tldraw](https://tldraw.dev/). It functions as a microservice, handling websocket connections to sync shared whiteboard edits in real-time using tldraw's [sync-core](https://www.npmjs.com/package/@tldraw/sync-core) library.
 
-A simple standalone NodeJS-based sync server designed to provide a realtime, collaborative whiteboard experience for frontends integrated with tlDraw. It functions as a microservice, handling websocket connections to sync shared whiteboard edits in real-time using tlDraw's `sync-core` library.
+## Overview
 
 The core responsibilities of this service include:
 
@@ -16,49 +18,88 @@ The core responsibilities of this service include:
 
 ## Architecture
 
-This service is designed as a NodeJS microservice using Fastify . It connects to client applications using tlDraw via WebSockets for real-time data synchronization. It relies on external services (configurable via environment variables) for persisting snapshots and storing assets.
+This service is designed as a NodeJS microservice that connects to client applications using tldraw via WebSockets for real-time data synchronization. It relies on external services (configurable via environment variables) for persisting snapshots and storing assets.
+
+## Installation
+
+```bash
+npm install @smoothglue/sync-whiteboard
+# or
+yarn add @smoothglue/sync-whiteboard
+```
+
+## Configuration
+The @smoothglue/sync-whiteboard server is configured entirely through the environment variables listed below:
+
+| Environment Variable             | Description                                                                                                    | Default Value | Required |
+| :------------------------------- |:---------------------------------------------------------------------------------------------------------------| :------------ |:---------|
+| `SWB_PORT`                       | The port on which the server will listen.                                                                      | `5858`        | No       |
+| `SWB_HOST`                       | The host address the server will bind to.                                                                      | `0.0.0.0`     | No       |
+| `SWB_LOG_LEVEL`                  | The minimum log level for messages (e.g, `fatal`, `error`, `warn`, `info`, `debug`).                           | `info`        | No       |
+| `SWB_SNAPSHOT_STORAGE_URL`       | **Crucial:** The base URL for the service responsible for persisting tldraw room states.                       | (None)        | **Yes**  |
+| `SWB_ASSET_STORAGE_URL`          | **Crucial:** The base URL for the service responsible for storing and retrieving tldraw assets (e.g., images). | (None)        | **Yes**  |
+| `SWB_SAVE_INTERVAL_MS`           | The interval (in milliseconds) the server periodically checks for and saves updated room snapshots.            | `5000`        | No       |
+
+
+## Usage
+
+This package provides a server that can be integrated into your application or run as a standalone service.
+
+### Integrating with your Application
+You can `require`/`import` the package directly into your Node.js application. Upon import, the server will attempt to start, binding to the host and port configured via environment variables.
+
+```javascript
+// Example application's entry point: (e.g., app.js or index.js)
+// Imports the package, which initializes and starts the sync server.
+require('@smoothglue/sync-whiteboard');
+```
+
+### Running as a Standalone Service (e.g., in Docker)
+To run the `@smoothglue/sync-whiteboard` server as a standalone process, execute its main entry point. This is typically done within a Docker container where environment variables are easily managed.
+
+From your containerized Node.js environment with dependencies installed, your CMD or ENTRYPOINT in the Dockerfile would look like this:
+
+```dockerfile
+# Dockerfile snippet example
+# ... (setting up Node.js, copying package.json, running npm install)
+# The 'dist/server.js' file is the compiled entry point of the @smoothglue/sync-whiteboard package.
+CMD ["node", "node_modules/@smoothglue/sync-whiteboard/dist/server.js"]
+```
 
 ## Development Environment (Docker)
 
 This project includes a Docker-based development environment configured in `dev-env/docker-compose.yml`. This makes it easy to run the `sync-whiteboard` server along with its dependencies (mock backend API, database, object storage) and a mock frontend client.
 
-**Prerequisites:**
+### Prerequisites:
 
 - Docker ([https://www.docker.com/get-started](https://www.docker.com/get-started))
 - Docker Compose ([https://docs.docker.com/compose/install/](https://docs.docker.com/compose/install/))
 
-**Configuration:**
+### Configuration (Optional):
+
+If you wish to alter the default sync-whiteboard server configuration, refer to the following steps.
 
 1.  Navigate to the `dev-env` directory:
     ```bash
     cd sync-whiteboard/dev-env
     ```
-2.  Create a `.env` file by copying the example or using your own settings. This file is used by `docker-compose.yml` to configure services like the database and object storage. Key variables include:
-    - `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD` for the database.
-    - `MINIO_ROOT_USER`, `MINIO_ROOT_PASSWORD`, `MINIO_BUCKET` for the object storage.
-    - The `SNAPSHOT_STORAGE_URL` and `ASSET_STORAGE_URL` environment variables for the `sync-whiteboard` service itself are set within the `docker-compose.yml` to point to the `mock-backend` service.
+2.  Copy `env.example` to `.env` and adjust settings as needed. This file configures services like the database and object storage services expressed within `docker-compose.yml`. For `sync-whiteboard` specific settings, see the [Configuration](#configuration) section above.
 
-**Running the Environment:**
+### Running the Environment:
 
 1.  From the `dev-env` directory, run:
     ```bash
     docker-compose up --build
     ```
 
-**Services:**
+### Services:
 
 The Docker Compose setup starts the following services:
 
-- **`sync-whiteboard`**: The main NodeJS sync server.
-  - Accessible via WebSocket at `ws://localhost:5858`. Builds from the `Dockerfile` in the parent directory.
-- **`mock-backend`**: A Flask-based API simulating backend storage for snapshots (using PostgreSQL) and assets (using MinIO).
-  - Accessible at `http://localhost:5000`.
-- **`postgres`**: PostgreSQL database for the mock backend.
-  - Data is persisted in a Docker volume (`postgres_data`).
-  - Port `5433` on the host is mapped to `5432` in the container.
-- **`minio`**: MinIO object storage for the mock backend.
-  - Data is persisted in a Docker volume (`minio_data`).
-  - API accessible at `http://localhost:9000`.
-  - Console accessible at `http://localhost:9001`.
-- **`mock-frontend`**: A simple Vite+React frontend client for testing.
-  - Accessible at `http://localhost:8080`.
+| Service Name         | Description                                                          | Accessible At (Host)                            |
+| :------------------- | :------------------------------------------------------------------- |:------------------------------------------------|
+| `sync-whiteboard`    | The main Node.js sync server for real-time whiteboard collaboration. | `ws://localhost:5858`                           |
+| `mock-backend`       | A Flask-based API simulating backend storage for snapshots & assets. | [http://localhost:5001](http://localhost:5001) |
+| `postgres`           | PostgreSQL database for the mock backend's snapshot storage.         | `localhost:5433`                                |
+| `minio`              | MinIO object storage for the mock backend's asset storage.           | [http://localhost:9001](http://localhost:9001)  |
+| `mock-frontend`      | A simple Vite+React client for testing the whiteboard functionality. | [http://localhost:8080](http://localhost:8080)  |

package/dist/assets.js

@@ -1,16 +1,20 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.storeAsset = storeAsset;
 exports.loadAsset = loadAsset;
 const stream_1 = require("stream");
+const logger_1 = __importDefault(require("./logger"));
 // --- Configuration ---
-const ASSET_STORAGE_URL = process.env.ASSET_STORAGE_URL;
+const ASSET_STORAGE_URL = process.env.SWB_ASSET_STORAGE_URL;
 if (!ASSET_STORAGE_URL) {
     // Critical configuration missing, exit the process.
-    console.error("FATAL ERROR: ASSET_STORAGE_URL environment variable is not set.");
+    logger_1.default.fatal("FATAL ERROR: ASSET_STORAGE_URL environment variable is not set.");
     process.exit(1);
 }
-console.log(`[ASSETS] Using Asset Storage URL: ${ASSET_STORAGE_URL}`);
+logger_1.default.info({ assetStorageUrl: ASSET_STORAGE_URL }, `[ASSETS] Using Asset Storage URL`);
 // --- End Configuration ---
 /**
  * Stores an asset by proxying a PUT request to the configured asset storage backend.
@@ -23,10 +27,10 @@ console.log(`[ASSETS] Using Asset Storage URL: ${ASSET_STORAGE_URL}`);
  */
 async function storeAsset(id, fileStream, contentType = "application/octet-stream", originalFilename) {
     const url = `${ASSET_STORAGE_URL}/${id}`;
-    console.log(`[ASSETS] Storing asset id: ${id}, filename: ${originalFilename}. Target URL: ${url}`);
+    logger_1.default.debug({ assetId: id, filename: originalFilename, targetUrl: url }, `[ASSETS] Storing asset`);
     // Ensure we have a readable stream
     if (!(fileStream instanceof stream_1.Readable)) {
-        console.error("[ASSETS] Error: storeAsset received a non-readable stream type.");
+        logger_1.default.error({ assetId: id, receivedType: typeof fileStream }, "[ASSETS] Error: storeAsset received a non-readable stream type.");
         throw new Error("Invalid stream type provided to storeAsset.");
     }
     let webStream = null;
@@ -45,24 +49,26 @@ async function storeAsset(id, fileStream, contentType = "application/octet-strea
             // @ts-ignore - duplex: 'half' is required for streaming request bodies with Node fetch
             duplex: "half",
         });
-        console.log(`[ASSETS] Backend PUT response status for ${id}: ${response.status}`);
+        logger_1.default.debug({ assetId: id, status: response.status }, `[ASSETS] Backend PUT response status`);
         // Handle backend errors
         if (!response.ok) {
             const errorBody = await response.text();
-            console.error(`[ASSETS] Error response from backend storing asset ${id}: ${response.status} ${response.statusText}`, errorBody);
+            const err = new Error(`Backend failed to store asset ${id}. Status: ${response.status}. Body: ${errorBody}`);
+            logger_1.default.error({ err, assetId: id, responseStatus: response.status, responseStatusText: response.statusText, responseBody: errorBody }, `[ASSETS] Error response from backend storing asset`);
             // Ensure streams are closed on error
             if (webStream) {
                 await webStream
                     .cancel()
-                    .catch((err) => console.error(`[ASSETS] Error cancelling upload webStream for ${id} after failed fetch:`, err));
+                    .catch((cancelErr) => // Changed variable name to avoid shadowing
+                 logger_1.default.error({ err: cancelErr, assetId: id, stage: 'cancel_upload_after_failed_fetch' }, `[ASSETS] Error cancelling upload webStream`));
             }
-            throw new Error(`Backend failed to store asset ${id}. Status: ${response.status}. Body: ${errorBody}`);
+            throw err;
         }
-        console.log(`[ASSETS] Successfully proxied storage for asset ${id} to ${url}`);
+        logger_1.default.debug({ assetId: id, targetUrl: url }, `[ASSETS] Successfully proxied storage for asset`);
         return id; // Return the ID, confirming success
     }
     catch (error) {
-        console.error(`[ASSETS] Network or fetch error storing asset ${id} to ${url}:`, error);
+        logger_1.default.error({ err: error, assetId: id, targetUrl: url, operation: 'storeAsset' }, `[ASSETS] Network or fetch error storing asset`);
         // Clean up streams on error
         if (fileStream instanceof stream_1.Readable && !fileStream.destroyed) {
             fileStream.destroy(error instanceof Error ? error : new Error(String(error)));
@@ -70,7 +76,8 @@ async function storeAsset(id, fileStream, contentType = "application/octet-strea
         if (webStream) {
             await webStream
                 .cancel()
-                .catch((err) => console.error(`[ASSETS] Error cancelling upload webStream during error handling for ${id}:`, err));
+                .catch((cancelErr) => // Changed variable name
+             logger_1.default.error({ err: cancelErr, assetId: id, stage: 'cancel_upload_during_error_handling' }, `[ASSETS] Error cancelling upload webStream`));
         }
         throw error; // Re-throw error for the server handler
     }
@@ -83,34 +90,36 @@ async function storeAsset(id, fileStream, contentType = "application/octet-strea
  */
 async function loadAsset(id) {
     const url = `${ASSET_STORAGE_URL}/${id}`;
-    console.log(`[ASSETS] Loading asset id: ${id}. Target URL: ${url}`);
+    logger_1.default.debug({ assetId: id, targetUrl: url }, `[ASSETS] Loading asset`);
     try {
         // Make the GET request to the actual asset storage backend
         const response = await fetch(url, {
             method: "GET",
         });
-        console.log(`[ASSETS] Backend GET response status for ${id}: ${response.status}`);
+        logger_1.default.debug({ assetId: id, status: response.status }, `[ASSETS] Backend GET response status`);
         // Handle backend errors (like 404 Not Found)
         if (!response.ok) {
             if (response.status === 404) {
-                console.warn(`[ASSETS] Asset ${id} not found at backend ${url} (404)`);
+                logger_1.default.warn({ assetId: id, targetUrl: url, status: 404 }, `[ASSETS] Asset not found at backend (404)`);
                 const notFoundError = new Error(`Asset ${id} not found.`);
                 notFoundError.code = "ENOENT"; // Mimic filesystem error code
                 throw notFoundError;
             }
             // Handle other non-OK statuses
             const errorBody = await response.text();
-            console.error(`[ASSETS] Error response from backend loading asset ${id}: ${response.status} ${response.statusText}`, errorBody);
-            throw new Error(`Backend failed to load asset ${id}. Status: ${response.status}. Body: ${errorBody}`);
+            const err = new Error(// better logging context
+            `Backend failed to load asset ${id}. Status: ${response.status}. Body: ${errorBody}`);
+            logger_1.default.error({ err, assetId: id, responseStatus: response.status, responseStatusText: response.statusText, responseBody: errorBody }, `[ASSETS] Error response from backend loading asset`);
+            throw err;
         }
         // Ensure response body exists
         if (!response.body) {
-            console.error(`[ASSETS] No response body received from backend for asset ${id} from ${url}`);
+            logger_1.default.error({ assetId: id, targetUrl: url }, `[ASSETS] No response body received from backend for asset`);
             throw new Error(`No response body received for asset ${id}.`);
         }
         // Get the Content-Type header provided by the backend
         const contentType = response.headers.get("Content-Type") || "application/octet-stream";
-        console.log(`[ASSETS] Received Content-Type from backend for ${id}: ${contentType}`);
+        logger_1.default.debug({ assetId: id, contentType: contentType }, `[ASSETS] Received Content-Type from backend`);
         // Convert the Web Standard stream from fetch response to a Node.js stream
         const nodeStream = stream_1.Readable.fromWeb(response.body);
         // Return the stream and content type for the server handler to use
@@ -119,7 +128,7 @@ async function loadAsset(id) {
     catch (error) {
         // Avoid double-logging known 'Not Found' errors
         if (error.code !== "ENOENT") {
-            console.error(`[ASSETS] Network or fetch error loading asset ${id} from ${url}:`, error);
+            logger_1.default.error({ err: error, assetId: id, targetUrl: url, operation: 'loadAsset' }, `[ASSETS] Network or fetch error loading asset`);
         }
         throw error; // Re-throw error for the server handler
     }

package/dist/logger.js

@@ -0,0 +1,13 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loggerConfig = void 0;
+const pino_1 = __importDefault(require("pino"));
+exports.loggerConfig = {
+    level: process.env.SWB_LOG_LEVEL ?? "info",
+    timestamp: pino_1.default.stdTimeFunctions.isoTime,
+};
+const logger = (0, pino_1.default)(exports.loggerConfig);
+exports.default = logger;

package/dist/rooms.js

@@ -1,19 +1,21 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getOrCreateRoom = getOrCreateRoom;
 const sync_core_1 = require("@tldraw/sync-core");
 const schema_1 = require("./schema");
+const logger_1 = __importDefault(require("./logger"));
 // --- Configuration ---
-const SNAPSHOT_STORAGE_URL = process.env.SNAPSHOT_STORAGE_URL;
+const SNAPSHOT_STORAGE_URL = process.env.SWB_SNAPSHOT_STORAGE_URL;
 if (!SNAPSHOT_STORAGE_URL) {
-    console.error("FATAL ERROR: SNAPSHOT_STORAGE_URL environment variable is not set.");
+    logger_1.default.fatal("FATAL ERROR: SNAPSHOT_STORAGE_URL environment variable is not set.");
     process.exit(1);
 }
-console.log(`[ROOMS] Using Snapshot Storage URL: ${SNAPSHOT_STORAGE_URL}`);
-const SAVE_INTERVAL_MS = process.env.SAVE_INTERVAL_MS
-    ? parseInt(process.env.SAVE_INTERVAL_MS, 10)
-    : 5000;
-console.log(`[ROOMS] Snapshot save interval: ${SAVE_INTERVAL_MS}ms`);
+logger_1.default.info({ snapshotStorageUrl: SNAPSHOT_STORAGE_URL }, `[ROOMS] Using Snapshot Storage URL`);
+const SAVE_INTERVAL_MS = parseInt(process.env.SWB_SAVE_INTERVAL_MS || '5000', 10);
+logger_1.default.info({ saveIntervalMs: SAVE_INTERVAL_MS }, `[ROOMS] Snapshot save interval`);
 // In-memory map holding active room states, keyed by roomId
 const rooms = new Map();
 // Mutex to prevent race conditions when multiple requests try to create the same room simultaneously
@@ -27,7 +29,7 @@ let createRoomMutex = Promise.resolve(undefined);
  */
 async function readSnapshotFromBackend(roomId) {
     const url = `${SNAPSHOT_STORAGE_URL}/${roomId}`;
-    console.log(`[ROOMS] Loading snapshot for room ${roomId} from ${url}`);
+    logger_1.default.debug({ roomId, url }, `[ROOMS] Loading snapshot for room ${roomId} from ${url}`);
     try {
         const response = await fetch(url, {
             method: "GET",
@@ -37,22 +39,24 @@ async function readSnapshotFromBackend(roomId) {
         });
         if (response.ok) {
             const snapshot = await response.json();
-            console.log(`[ROOMS] Snapshot loaded successfully for room ${roomId}`);
+            logger_1.default.debug({ roomId, snapshotSize: JSON.stringify(snapshot).length }, `[ROOMS] Snapshot loaded successfully for room ${roomId}`);
             return snapshot;
         }
         else if (response.status === 404) {
-            console.log(`[ROOMS] No existing snapshot found for room ${roomId} (404)`);
+            logger_1.default.info({ roomId, url, status: 404 }, `[ROOMS] No existing snapshot found for room ${roomId} (404)`);
             return undefined; // Expected case for a new room
         }
         else {
             // Handle unexpected errors from the backend
             const errorBody = await response.text();
-            console.error(`[ROOMS] Error loading snapshot for room ${roomId}: ${response.status} ${response.statusText}`, errorBody);
-            throw new Error(`Backend failed to load snapshot for ${roomId}. Status: ${response.status}. Body: ${errorBody}`);
+            const err = new Error(// better logging context
+            `Backend failed to load snapshot for ${roomId}. Status: ${response.status}. Body: ${errorBody}`);
+            logger_1.default.error({ err, roomId, url, responseStatus: response.status, responseBody: errorBody }, `[ROOMS] Error loading snapshot for room ${roomId}`);
+            throw err;
         }
     }
     catch (error) {
-        console.error(`[ROOMS] Network or fetch error loading snapshot for room ${roomId} from ${url}:`, error);
+        logger_1.default.error({ err: error, roomId, url }, `[ROOMS] Network or fetch error loading snapshot for room ${roomId}`);
         throw error; // Propagate error to getOrCreateRoom
     }
 }
@@ -64,7 +68,7 @@ async function readSnapshotFromBackend(roomId) {
 async function saveSnapshotToBackend(roomId, room) {
     const url = `${SNAPSHOT_STORAGE_URL}/${roomId}`;
     const snapshot = room.getCurrentSnapshot();
-    console.log(`[ROOMS] Saving snapshot for room ${roomId} to ${url}`);
+    logger_1.default.debug({ roomId, url, snapshotSize: JSON.stringify(snapshot).length }, `[ROOMS] Saving snapshot for room ${roomId} to ${url}`);
     try {
         const response = await fetch(url, {
             method: "POST",
@@ -75,15 +79,16 @@ async function saveSnapshotToBackend(roomId, room) {
         });
         if (!response.ok) {
             const errorBody = await response.text();
-            console.error(`[ROOMS] Error saving snapshot for room ${roomId}: ${response.status} ${response.statusText}`, errorBody);
+            logger_1.default.warn({ roomId, url, responseStatus: response.status, responseBody: errorBody }, // No err: new Error() here, just context
+            `[ROOMS] Error saving snapshot for room ${roomId}: ${response.status} ${response.statusText}`);
             // Log error but don't throw, to avoid breaking the save interval
         }
         else {
-            console.log(`[ROOMS] Snapshot saved successfully for room ${roomId}`);
+            logger_1.default.debug({ roomId }, `[ROOMS] Snapshot saved successfully for room ${roomId}`);
         }
     }
     catch (error) {
-        console.error(`[ROOMS] Network or fetch error saving snapshot for room ${roomId} to ${url}:`, error);
+        logger_1.default.error({ err: error, roomId, url }, `[ROOMS] Network or fetch error saving snapshot for room ${roomId}`);
         // Log error but don't throw
     }
 }
@@ -102,20 +107,38 @@ async function getOrCreateRoom(roomId) {
         if (rooms.has(roomId)) {
             const existingRoomState = rooms.get(roomId);
             if (!existingRoomState.room.isClosed()) {
+                logger_1.default.debug({ roomId }, "[ROOMS] Active room instance found in memory.");
                 return; // Room exists and is active
             }
             else {
-                console.log(`[ROOMS] Found closed room ${roomId}, removing before creating new one.`);
+                logger_1.default.info({ roomId }, `[ROOMS] Found closed room ${roomId}, removing before creating new one.`);
                 rooms.delete(roomId); // Clean up closed room reference
             }
         }
-        console.log(`[ROOMS] Creating or recreating room: ${roomId}`);
+        logger_1.default.info({ roomId }, `[ROOMS] Creating or recreating room: ${roomId}`);
         // Fetch initial state from the backend API (can throw error)
         const initialSnapshot = await readSnapshotFromBackend(roomId);
-        // Define logger for the tldraw room instance
-        const logger = {
-            warn: (...args) => console.warn(`[TLDRAW ROOM ${roomId} WARN]`, ...args),
-            error: (...args) => console.error(`[TLDRAW ROOM ${roomId} ERROR]`, ...args),
+        // Define child logger for the tldraw room instance
+        const tldrawInstanceLogger = logger_1.default.child({ tldrawRoomId: roomId, component: 'tldraw-sync-core' });
+        const tldrawLogAdapter = {
+            warn: (...args) => {
+                const msg = args.find(arg => typeof arg === 'string') || 'tldraw room warning';
+                const details = args.filter(arg => typeof arg !== 'string');
+                tldrawInstanceLogger.warn(details.length ? { details } : {}, msg);
+            },
+            error: (...args) => {
+                const errorArg = args.find(arg => arg instanceof Error);
+                if (errorArg) {
+                    const msg = args.filter(arg => typeof arg === 'string' && arg !== errorArg.message).join(' ') || errorArg.message || 'tldraw room error';
+                    const details = args.filter(arg => arg !== errorArg && typeof arg !== 'string');
+                    tldrawInstanceLogger.error({ err: errorArg, details: details.length ? details : undefined }, msg);
+                }
+                else {
+                    const msg = args.find(arg => typeof arg === 'string') || 'tldraw room error (no Error instance)';
+                    const details = args.filter(arg => typeof arg !== 'string');
+                    tldrawInstanceLogger.error(details.length ? { details } : {}, msg);
+                }
+            }
         };
         // Create the new room state object
         const newRoomState = {
@@ -125,20 +148,20 @@ async function getOrCreateRoom(roomId) {
             room: new sync_core_1.TLSocketRoom({
                 schema: schema_1.whiteboardSchema, // Our defined tldraw schema
                 initialSnapshot, // Initial state from backend (or undefined)
-                log: logger, // Logger for internal tldraw messages
+                log: tldrawLogAdapter, // Logger for internal tldraw messages
                 /** Callback when a user session is removed (e.g., disconnects/times out) */
-                onSessionRemoved(room, args) {
-                    console.log(`[ROOMS] Session removed from room ${roomId}. Remaining: ${args.numSessionsRemaining}`);
+                onSessionRemoved(roomInstance, args) {
+                    logger_1.default.debug({ roomId, remainingSessions: args.numSessionsRemaining }, `[ROOMS] Session removed from room ${roomId}. Remaining: ${args.numSessionsRemaining}`);
                     // If last user leaves, trigger a final save and close the room
                     if (args.numSessionsRemaining === 0) {
-                        console.log(`[ROOMS] Last user left room ${roomId}. Triggering final save.`);
+                        logger_1.default.info({ roomId }, `[ROOMS] Last user left room ${roomId}. Triggering final save.`);
                         // Ensure any pending periodic save completes first
                         const savePromise = newRoomState.persistPromise ?? Promise.resolve();
                         savePromise.finally(() => {
-                            console.log(`[ROOMS] Performing final save for room ${roomId}...`);
-                            saveSnapshotToBackend(roomId, room).finally(() => {
-                                console.log(`[ROOMS] Closing room ${roomId} after final save.`);
-                                room.close(); // Mark the tldraw room as closed
+                            logger_1.default.info({ roomId }, `[ROOMS] Performing final save for room ${roomId}...`);
+                            saveSnapshotToBackend(roomId, roomInstance).finally(() => {
+                                logger_1.default.info({ roomId }, `[ROOMS] Closing room ${roomId} after final save.`);
+                                roomInstance.close(); // Mark the tldraw room as closed
                             });
                         });
                     }
@@ -152,7 +175,7 @@ async function getOrCreateRoom(roomId) {
         };
         // Store the new room state in our map
         rooms.set(roomId, newRoomState);
-        console.log(`[ROOMS] Room ${roomId} created successfully.`);
+        logger_1.default.info({ roomId }, `[ROOMS] Room ${roomId} created successfully.`);
     });
     // Wait for the mutex-protected operation (lookup/creation) to complete
     await createRoomMutex;
@@ -160,7 +183,7 @@ async function getOrCreateRoom(roomId) {
     const roomState = rooms.get(roomId);
     if (!roomState || roomState.room.isClosed()) {
         // Defensive check in case something went wrong
-        console.error(`[ROOMS] Failed to get or create a valid room instance for ${roomId} after mutex.`);
+        logger_1.default.error({ roomId }, `[ROOMS] Failed to get or create a valid room instance for ${roomId} after mutex.`);
         throw new Error(`Failed to retrieve valid room instance for ${roomId}`);
     }
     // Return the tldraw room object
@@ -169,27 +192,33 @@ async function getOrCreateRoom(roomId) {
 // --- Periodic Persistence ---
 // Saves snapshots for rooms marked as `needsPersist` at regular intervals.
 setInterval(() => {
+    logger_1.default.debug("[ROOMS] Periodic persistence check initiated.");
+    let updatedRoomCount = 0;
     for (const roomState of rooms.values()) {
         // Clean up closed rooms from memory
         if (roomState.room.isClosed()) {
-            console.log(`[ROOMS] Removing closed room ${roomState.id} during periodic check.`);
+            logger_1.default.info({ roomId: roomState.id }, `[ROOMS] Removing closed room ${roomState.id} during periodic check.`);
             rooms.delete(roomState.id);
             continue;
         }
         // If room has changes and isn't already saving, start a save operation
         if (roomState.needsPersist && !roomState.persistPromise) {
             roomState.needsPersist = false; // Reset flag
+            updatedRoomCount++;
             // Track the save operation promise
             roomState.persistPromise = saveSnapshotToBackend(roomState.id, roomState.room)
                 .catch((error) => {
                 // Log errors from periodic save but don't stop the interval
-                console.error(`[ROOMS] Periodic save failed for room ${roomState.id}:`, error);
+                logger_1.default.error({ err: error, roomId: roomState.id }, // Pass error object
+                `[ROOMS] Periodic save failed for room ${roomState.id}`);
             })
                 .finally(() => {
                 // Clear the promise tracker when done
                 roomState.persistPromise = null;
+                logger_1.default.debug({ roomId: roomState.id }, "[ROOMS] Persistence promise cleared.");
             });
         }
     }
+    logger_1.default.debug({ roomsChecked: rooms.size, roomsUpdatedThisInterval: updatedRoomCount }, "[ROOMS] Periodic persistence check completed.");
 }, SAVE_INTERVAL_MS);
 // --- End Periodic Persistence ---

package/dist/server.js

@@ -4,57 +4,61 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const fastify_1 = __importDefault(require("fastify"));
+const stream_1 = require("stream");
 const websocket_1 = __importDefault(require("@fastify/websocket"));
 const cors_1 = __importDefault(require("@fastify/cors"));
-const rooms_1 = require("./rooms");
 const assets_1 = require("./assets");
-const stream_1 = require("stream");
+const logger_1 = require("./logger");
+const rooms_1 = require("./rooms");
 // Configuration
-const PORT = parseInt(process.env.PORT || "5858", 10);
-const HOST = process.env.HOST || "0.0.0.0"; // Listen on all interfaces by default
+const parseCorsWhitelist = (cors) => {
+    const normalized = (cors || "").replace(/\s/g, '');
+    return normalized === "*" ? normalized : normalized.split(',').filter(x => x.length > 0);
+};
+const PORT = parseInt(process.env.SWB_PORT || "5858", 10);
+const HOST = process.env.SWB_HOST || "0.0.0.0"; // Listen on all interfaces by default
+const CORS_WHITELIST = parseCorsWhitelist(process.env.SWB_CORS_WHITELIST);
 // Initialize Fastify app with logging
-const app = (0, fastify_1.default)({ logger: { level: "info" } }); // Use 'info' level for less verbosity
+const app = (0, fastify_1.default)({ logger: logger_1.loggerConfig });
 // --- Register Plugins ---
 app.register(websocket_1.default); // Enable WebSocket support
 app.register(cors_1.default, {
     // Configure CORS
-    origin: "*", // Allow all origins (restrict in production)
+    origin: CORS_WHITELIST,
     methods: ["GET", "PUT", "POST", "DELETE", "OPTIONS"], // Allowed HTTP methods
     allowedHeaders: ["Content-Type", "Authorization", "X-Original-Filename"], // Allowed headers
 });
 // --- Define Routes ---
-app.register(async (app) => {
+app.register(async (svc) => {
     // Health check endpoint
-    app.get("/", async () => ({
+    svc.get("/", async () => ({
         status: "sync-whiteboard is running",
         time: new Date().toISOString(),
     }));
     // WebSocket connection endpoint for tldraw sync
-    app.get("/connect/:roomId", { websocket: true }, async (socket, req) => {
+    svc.get("/connect/:roomId", { websocket: true }, async (socket, req) => {
         const { roomId } = req.params;
         const sessionId = req.query?.sessionId;
         // Client provides sessionId via query param, handled by TLSocketRoom
         try {
             // Get or create the room instance (loads/creates state)
             const room = await (0, rooms_1.getOrCreateRoom)(roomId);
-            app.log.info(`[SERVER] Handling WebSocket connection for room ${roomId}`);
-            // Connect the client's socket to the tldraw room handler
+            req.log.debug(`[SERVER] Handling WebSocket connection for room ${roomId}`);
             room.handleSocketConnect({ sessionId, socket });
         }
         catch (error) {
-            app.log.error(`[SERVER] Error initializing room ${roomId}:`, error);
-            // Close socket with error code if room initialization fails
+            req.log.error({ err: error, roomId: roomId }, `[SERVER] Error initializing room`);
             socket.close(1011, "Internal server error during room initialization");
         }
     });
     // --- Asset Handling ---
     // Allow raw body parsing for asset uploads
-    app.addContentTypeParser("*", (_, __, done) => done(null));
+    svc.addContentTypeParser("*", (_, __, done) => done(null));
     /**
      * Handles asset uploads (PUT /assets/:id).
      * Proxies the request body stream to the asset storage backend via storeAsset.
      */
-    app.put("/assets/:id", async (req, reply) => {
+    svc.put("/assets/:id", async (req, reply) => {
         const { id } = req.params;
         const contentType = req.headers["content-type"] || "application/octet-stream";
         // Extract original filename from custom header
@@ -69,17 +73,21 @@ app.register(async (app) => {
                 originalFilename = decodeURIComponent(originalFilenameHeader);
             }
             catch (e) {
-                app.log.warn(`[SERVER] Failed to decode X-Original-Filename header: ${originalFilenameHeader}`);
+                req.log.warn({ headerValue: originalFilenameHeaderRaw }, `[SERVER] Failed to decode X-Original-Filename header`);
                 originalFilename = "decode_error";
             }
         }
         else {
-            app.log.warn(`[SERVER] X-Original-Filename header missing or invalid: ${originalFilenameHeaderRaw}`);
+            req.log.warn({ headerValue: originalFilenameHeaderRaw }, `[SERVER] X-Original-Filename header missing or invalid`);
         }
-        app.log.info(`[SERVER] PUT /assets/${id}, Content-Type: ${contentType}, Filename: ${originalFilename}`);
+        req.log.debug({
+            assetId: id,
+            contentType: contentType,
+            originalFilename: originalFilename,
+        }, `[SERVER] PUT /assets/:id`);
         // Validate request body is a stream
         if (!(req.raw instanceof stream_1.Readable)) {
-            app.log.error(`[SERVER] Error: Request raw body is not a Readable stream for asset ${id}`);
+            req.log.error({ assetId: id }, `[SERVER] Error: Request raw body is not a Readable stream`);
             return reply.code(500).send({
                 success: false,
                 error: "Internal server error: Invalid request body stream.",
@@ -88,12 +96,12 @@ app.register(async (app) => {
         try {
             // Call the asset storage logic (which proxies to the backend)
             await (0, assets_1.storeAsset)(id, req.raw, contentType, originalFilename);
-            app.log.info(`[SERVER] Asset ${id} stored successfully.`);
+            req.log.debug({ assetId: id }, `[SERVER] Asset stored successfully.`);
             reply.code(200).send({ success: true });
         }
         catch (error) {
-            app.log.error(`[SERVER] Error storing asset ${id}:`, error);
-            const statusCode = error?.code === "ENOENT" ? 404 : 500; // Check for specific errors if needed
+            req.log.error({ err: error, assetId: id }, `[SERVER] Error storing asset`);
+            const statusCode = error?.code === "ENOENT" ? 404 : 500;
             reply.code(statusCode).send({
                 success: false,
                 error: error.message || "Failed to store asset",
@@ -106,17 +114,17 @@ app.register(async (app) => {
      */
     app.get("/assets/:id", async (req, reply) => {
         const { id } = req.params;
-        app.log.info(`[SERVER] GET /assets/${id}`);
+        req.log.debug({ assetId: id }, `[SERVER] GET /assets/:id`);
         try {
             // Call the asset loading logic (which proxies to the backend)
             const { stream: dataStream, contentType } = await (0, assets_1.loadAsset)(id);
-            app.log.info(`[SERVER] Asset ${id} loaded. Content-Type: ${contentType}. Sending reply...`);
+            req.log.debug({ assetId: id, contentType: contentType }, `[SERVER] Asset loaded. Sending reply...`);
             // Set the correct Content-Type header and send the stream
             reply.header("Content-Type", contentType);
             reply.send(dataStream);
         }
         catch (error) {
-            app.log.error(`[SERVER] Error loading asset ${id}:`, error);
+            req.log.error({ err: error, assetId: id }, `[SERVER] Error loading asset`);
             if (error.code === "ENOENT") {
                 // Asset not found by the backend
                 reply.code(404).send({ success: false, error: "Asset not found" });
@@ -140,7 +148,7 @@ const start = async () => {
         app.log.info(`Sync Whiteboard server running on http://${HOST}:${PORT}`);
     }
     catch (err) {
-        app.log.error(err);
+        app.log.fatal({ err: err }, "Server failed to start");
         process.exit(1); // Exit if server fails to start
     }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smoothglue/sync-whiteboard",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "main": "dist/server.js",
   "scripts": {
     "dev": "ts-node-dev --respawn --transpile-only src/server.ts",
@@ -37,6 +37,7 @@
     "@tldraw/sync-core": "^3.12.0",
     "@tldraw/tlschema": "^3.12.0",
     "fastify": "^5.3.0",
+    "pino": "^9.7.0",
     "ws": "^8.18.1"
   }
 }