@smoothglue/sync-whiteboard 1.0.3-79290.0 → 1.1.0

package/dist/assets.js

@@ -0,0 +1,170 @@
+"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.SWB_ASSET_STORAGE_URL;
+if (!ASSET_STORAGE_URL) {
+    // Critical configuration missing, exit the process.
+    logger_1.default.fatal("FATAL ERROR: ASSET_STORAGE_URL environment variable is not set.");
+    process.exit(1);
+}
+logger_1.default.info({ assetStorageUrl: ASSET_STORAGE_URL }, `[ASSETS] Using Asset Storage URL`);
+/**
+ * Stores an asset by proxying a PUT request to the configured asset storage backend.
+ * @param id - The unique identifier for the asset (generated by the client).
+ * @param fileStream - The readable stream containing the asset data (from the client request).
+ * @param contentType - The MIME type of the asset.
+ * @param originalFilename - The original filename provided by the client.
+ * @returns The asset ID upon successful storage.
+ * @throws Throws an error if the request to the backend fails.
+ */
+async function storeAsset(id, fileStream, contentType = "application/octet-stream", originalFilename, credentials) {
+    const url = `${ASSET_STORAGE_URL}/${id}`;
+    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)) {
+        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;
+    try {
+        // Convert Node.js stream to Web Standard stream for fetch body
+        webStream = stream_1.Readable.toWeb(fileStream);
+        // Sanitize the filename for use in the Content-Disposition header
+        // This removes non-ASCII characters that can crash the fetch call.
+        const sanitizedFilename = originalFilename.replace(/[^\x00-\x7F]/g, "");
+        const headers = {
+            "Content-Type": contentType,
+            "X-Original-Filename": encodeURIComponent(originalFilename), // Pass the original filename (properly encoded) for the backend to use
+            "Content-Disposition": `attachment; filename="${sanitizedFilename}"`, // Use the sanitized filename in the Content-Disposition header to avoid errors
+        };
+        // forward auth headers if included from client
+        // Prioritize Authorization header, but fall back to Cookie
+        if (credentials?.authorization) {
+            headers["Authorization"] = credentials.authorization;
+        }
+        if (credentials?.cookie) {
+            headers["Cookie"] = credentials.cookie;
+        }
+        // Make the PUT request to the asset storage backend
+        const response = await fetch(url, {
+            method: "PUT",
+            headers: headers,
+            body: webStream, // Cast is necessary due to type mismatches
+            // @ts-ignore - duplex: 'half' is required for streaming request bodies with Node fetch
+            duplex: "half",
+        });
+        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();
+            const err = new Error(`Backend failed to store asset ${id}. Status: ${response.status}. Body: ${errorBody}. Headers ${headers}`);
+            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((cancelErr) => logger_1.default.error({
+                    err: cancelErr,
+                    assetId: id,
+                    stage: "cancel_upload_after_failed_fetch",
+                }, `[ASSETS] Error cancelling upload webStream`));
+            }
+            throw err;
+        }
+        logger_1.default.debug({ assetId: id, targetUrl: url }, `[ASSETS] Successfully proxied storage for asset`);
+        return id; // Return the ID, confirming success
+    }
+    catch (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)));
+        }
+        if (webStream) {
+            await webStream.cancel().catch((cancelErr) => 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
+    }
+}
+/**
+ * Loads an asset by proxying a GET request to the configured asset storage backend.
+ * @param id - The unique identifier for the asset.
+ * @returns An object containing the asset's data as a Readable stream and its Content-Type.
+ * @throws Throws an error if the request to the backend fails or the asset is not found.
+ */
+async function loadAsset(id, credentials) {
+    const url = `${ASSET_STORAGE_URL}/${id}`;
+    logger_1.default.debug({ assetId: id, targetUrl: url }, `[ASSETS] Loading asset`);
+    const headers = {};
+    // Pass auth headers from client to backend call
+    // Prioritize Authorization header, but fall back to Cookie
+    if (credentials?.authorization) {
+        headers["Authorization"] = credentials.authorization;
+    }
+    else if (credentials?.cookie) {
+        headers["Cookie"] = credentials.cookie;
+    }
+    try {
+        // Make the GET request to the actual asset storage backend
+        const response = await fetch(url, {
+            method: "GET",
+            headers,
+        });
+        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) {
+                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();
+            const err = new Error(// better logging context
+            `Backend failed to load asset ${id}. Status: ${response.status}. Body: ${errorBody}. Headers ${headers}`);
+            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) {
+            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";
+        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
+        return { stream: nodeStream, contentType: contentType };
+    }
+    catch (error) {
+        // Avoid double-logging known 'Not Found' errors
+        if (error.code !== "ENOENT") {
+            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

@@ -0,0 +1,279 @@
+"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;
+/**
+ * @file Manages tldraw room instances, including creation, persistence, and lifecycle.
+ * This module handles loading snapshots from a backend, saving them periodically,
+ * and cleaning up inactive rooms from memory.
+ */
+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.SWB_SNAPSHOT_STORAGE_URL;
+if (!SNAPSHOT_STORAGE_URL) {
+    logger_1.default.fatal("FATAL ERROR: SNAPSHOT_STORAGE_URL environment variable is not set.");
+    process.exit(1);
+}
+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
+let createRoomMutex = Promise.resolve(undefined);
+// --- End Room State Tracking ---
+/**
+ * Reads the latest snapshot for a room from the backend API via HTTP GET.
+ * @param roomId - The ID of the room.
+ * @returns The snapshot data, or undefined if the backend returns 404.
+ * @throws Throws an error for non-404 HTTP errors or network issues.
+ */
+async function readSnapshotFromBackend(roomId, credentials) {
+    const url = `${SNAPSHOT_STORAGE_URL}/${roomId}`;
+    logger_1.default.debug({ roomId, url }, `[ROOMS] Loading snapshot for room ${roomId} from ${url}`);
+    const headers = new Headers();
+    headers.append("Accept", "application/json");
+    // Prioritize Authorization header, but fall back to Cookie
+    if (credentials?.authorization) {
+        headers.append("Authorization", credentials.authorization);
+    }
+    else if (credentials?.cookie) {
+        headers.append("Cookie", credentials.cookie);
+    }
+    try {
+        const response = await fetch(url, {
+            method: "GET",
+            headers: headers,
+        });
+        if (response.ok) {
+            const snapshot = await response.json();
+            // Validate the snapshot structure before returning
+            if (snapshot &&
+                typeof snapshot === "object" &&
+                !("documents" in snapshot)) {
+                logger_1.default.warn({ roomId, snapshotReceived: snapshot }, `[ROOMS] Invalid snapshot received from backend for room ${roomId}. Missing 'documents' property.`);
+                return undefined;
+            }
+            logger_1.default.debug({ roomId, snapshotSize: JSON.stringify(snapshot).length }, `[ROOMS] Snapshot loaded successfully for room ${roomId}`);
+            return snapshot;
+        }
+        else if (response.status === 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();
+            const err = new Error(`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) {
+        logger_1.default.error({ err: error, roomId, url }, `[ROOMS] Network or fetch error loading snapshot for room ${roomId}`);
+        throw error; // Propagate error to getOrCreateRoom
+    }
+}
+/**
+ * Saves the current room snapshot to the backend API via HTTP POST.
+ * @param roomId - The ID of the room.
+ * @param room - The TLSocketRoom instance containing the state to save.
+ */
+async function saveSnapshotToBackend(roomId, room, credentials) {
+    const url = `${SNAPSHOT_STORAGE_URL}/${roomId}`;
+    const snapshot = room.getCurrentSnapshot();
+    const headers = new Headers();
+    headers.append("Content-Type", "application/json");
+    // Prioritize Authorization header, but fall back to Cookie
+    if (credentials?.authorization) {
+        headers.append("Authorization", credentials.authorization);
+    }
+    else if (credentials?.cookie) {
+        headers.append("Cookie", credentials.cookie);
+    }
+    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",
+            headers: headers,
+            body: JSON.stringify(snapshot),
+        });
+        if (!response.ok) {
+            const errorBody = await response.text();
+            logger_1.default.warn({
+                roomId,
+                url,
+                responseStatus: response.status,
+                responseBody: errorBody,
+            }, `[ROOMS] Error saving snapshot for room ${roomId}: ${response.status} ${response.statusText}`);
+        }
+        else {
+            logger_1.default.debug({ roomId }, `[ROOMS] Snapshot saved successfully for room ${roomId}`);
+        }
+    }
+    catch (error) {
+        logger_1.default.error({ err: error, roomId, url }, `[ROOMS] Network or fetch error saving snapshot for room ${roomId}`);
+    }
+}
+/**
+ * Retrieves an existing active room instance from memory or creates a new one.
+ * If creating, it loads the initial state from the backend.
+ * Uses a mutex to handle concurrent requests safely.
+ * @param roomId - The ID of the room to get or create.
+ * @returns A promise resolving to the TLSocketRoom instance.
+ * @throws Throws an error if backend interaction fails during creation.
+ */
+async function getOrCreateRoom(roomId, credentials) {
+    createRoomMutex = createRoomMutex.then(async () => {
+        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;
+            }
+            else {
+                logger_1.default.info({ roomId }, `[ROOMS] Found closed room ${roomId}, removing before creating new one.`);
+                rooms.delete(roomId);
+            }
+        }
+        logger_1.default.info({ roomId }, `[ROOMS] Creating or recreating room: ${roomId}`);
+        const initialSnapshot = await readSnapshotFromBackend(roomId, credentials);
+        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);
+                }
+            },
+        };
+        const newRoomState = {
+            id: roomId,
+            needsPersist: false,
+            persistPromise: null,
+            credentials,
+            room: null,
+        };
+        const roomInstance = new sync_core_1.TLSocketRoom({
+            schema: schema_1.whiteboardSchema,
+            initialSnapshot: undefined,
+            log: tldrawLogAdapter,
+            onSessionRemoved(roomInstance, args) {
+                logger_1.default.debug({ roomId, remainingSessions: args.numSessionsRemaining }, `[ROOMS] Session removed. Remaining: ${args.numSessionsRemaining}`);
+                if (args.numSessionsRemaining === 0) {
+                    logger_1.default.info({ roomId }, `[ROOMS] Last user left. Triggering final save.`);
+                    const savePromise = newRoomState.persistPromise ?? Promise.resolve();
+                    savePromise.finally(() => {
+                        logger_1.default.info({ roomId }, `[ROOMS] Performing final save...`);
+                        saveSnapshotToBackend(roomId, roomInstance, newRoomState.credentials).finally(() => {
+                            logger_1.default.info({ roomId }, `[ROOMS] Closing room after final save.`);
+                            roomInstance.close();
+                        });
+                    });
+                }
+            },
+            onDataChange() {
+                newRoomState.needsPersist = true;
+            },
+        });
+        newRoomState.room = roomInstance;
+        rooms.set(roomId, newRoomState);
+        logger_1.default.info({ roomId }, `[ROOMS] Room created successfully.`);
+        if (rooms.size > 0) {
+            startPersistenceInterval();
+        }
+        // Load the REAL snapshot in the background, AFTER the room has been created.
+        readSnapshotFromBackend(roomId, credentials)
+            .then((snapshot) => {
+            if (snapshot && !roomInstance.isClosed()) {
+                logger_1.default.info({ roomId }, `Snapshot loaded in background. Hydrating room.`);
+                // Once loaded, push the full snapshot to all connected clients.
+                roomInstance.loadSnapshot(snapshot);
+                newRoomState.needsPersist = false; // Reset flag after initial load
+            }
+        })
+            .catch((err) => {
+            logger_1.default.error({ err, roomId }, "Failed to load snapshot in background");
+            roomInstance.close();
+            rooms.delete(roomId);
+        });
+    });
+    await createRoomMutex;
+    const roomState = rooms.get(roomId);
+    if (!roomState || roomState.room.isClosed()) {
+        logger_1.default.error({ roomId }, `[ROOMS] Failed to get or create a valid room instance after mutex.`);
+        throw new Error(`Failed to retrieve valid room instance for ${roomId}`);
+    }
+    return roomState.room;
+}
+// --- Smart Periodic Persistence ---
+let persistenceInterval = null;
+function stopPersistenceInterval() {
+    if (persistenceInterval) {
+        logger_1.default.info("[ROOMS] No active rooms. Stopping periodic persistence.");
+        clearInterval(persistenceInterval);
+        persistenceInterval = null;
+    }
+}
+function startPersistenceInterval() {
+    if (persistenceInterval)
+        return;
+    logger_1.default.info("[ROOMS] First active room created. Starting periodic persistence.");
+    persistenceInterval = setInterval(() => {
+        logger_1.default.debug("[ROOMS] Periodic persistence check initiated.");
+        let updatedRoomCount = 0;
+        for (const roomState of rooms.values()) {
+            if (roomState.room.isClosed()) {
+                logger_1.default.info({ roomId: roomState.id }, `[ROOMS] Removing closed room during periodic check.`);
+                rooms.delete(roomState.id);
+                continue;
+            }
+            if (roomState.needsPersist && !roomState.persistPromise) {
+                roomState.needsPersist = false;
+                updatedRoomCount++;
+                roomState.persistPromise = saveSnapshotToBackend(roomState.id, roomState.room, roomState.credentials)
+                    .catch((error) => {
+                    logger_1.default.error({ err: error, roomId: roomState.id }, `[ROOMS] Periodic save failed.`);
+                })
+                    .finally(() => {
+                    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.");
+        if (rooms.size === 0) {
+            stopPersistenceInterval();
+        }
+    }, SAVE_INTERVAL_MS);
+}

package/dist/schema.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.whiteboardSchema = void 0;
+const tlschema_1 = require("@tldraw/tlschema");
+exports.whiteboardSchema = (0, tlschema_1.createTLSchema)({
+    shapes: {
+        ...tlschema_1.defaultShapeSchemas,
+        //TODO: add custom shapes here
+    },
+    bindings: tlschema_1.defaultBindingSchemas,
+});

package/dist/server.js

@@ -0,0 +1,202 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": 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 assets_1 = require("./assets");
+const logger_1 = require("./logger");
+const rooms_1 = require("./rooms");
+// Configuration
+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: logger_1.loggerConfig });
+// --- Register Plugins ---
+app.register(websocket_1.default); // Enable WebSocket support
+app.register(cors_1.default, {
+    // Configure CORS
+    origin: CORS_WHITELIST,
+    methods: ["GET", "PUT", "POST", "DELETE", "OPTIONS"], // Allowed HTTP methods
+    allowedHeaders: [
+        "Content-Type",
+        "Authorization",
+        "X-Original-Filename",
+        "Content-Disposition",
+    ],
+});
+// --- Define Routes ---
+app.register(async (svc) => {
+    // Health check endpoint
+    svc.get("/", async () => ({
+        status: "sync-whiteboard is running",
+        time: new Date().toISOString(),
+    }));
+    // WebSocket connection endpoint for tldraw sync
+    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
+        // Capture the Authorization header from the incoming request
+        // Capture both potential auth headers
+        const credentials = {
+            authorization: req.headers.authorization,
+            cookie: req.headers.cookie,
+        };
+        if (!credentials) {
+            req.log.warn({ roomId }, `[SERVER] Connection attempt without Authorization header.`);
+        }
+        try {
+            // Get or create the room instance (loads/creates state)
+            const room = await (0, rooms_1.getOrCreateRoom)(roomId, credentials);
+            req.log.debug(`[SERVER] Handling WebSocket connection for room ${roomId}`);
+            room.handleSocketConnect({ sessionId, socket });
+        }
+        catch (error) {
+            req.log.error({ err: error, roomId: roomId }, `[SERVER] Error initializing room`);
+            socket.close(1011, "Internal server error during room initialization");
+        }
+    });
+    /**
+     * Pre-warms a room by loading its snapshot into memory from the backend.
+     * This is called by the client before it attempts a WebSocket connection
+     * to avoid a long wait time on initial ("cold") loads.
+     */
+    svc.post("/warm-room/:roomId", async (req, reply) => {
+        const { roomId } = req.params;
+        const credentials = {
+            authorization: req.headers.authorization,
+            cookie: req.headers.cookie,
+        };
+        try {
+            req.log.info({ roomId }, `[SERVER] Warming up room`);
+            // This will trigger the slow readSnapshotFromBackend if the room is cold
+            await (0, rooms_1.getOrCreateRoom)(roomId, credentials);
+            reply.code(200).send({ success: true, message: "Room is warm." });
+        }
+        catch (error) {
+            req.log.error({ err: error, roomId }, `[SERVER] Error warming up room`);
+            reply.code(500).send({ success: false, error: "Failed to warm up room" });
+        }
+    });
+    // --- Asset Handling ---
+    // Allow raw body parsing for asset uploads
+    svc.addContentTypeParser("*", (_, __, done) => done(null));
+    /**
+     * Handles asset uploads (PUT /assets/:id).
+     * Proxies the request body stream to the asset storage backend via storeAsset.
+     */
+    svc.put("/assets/:id", async (req, reply) => {
+        const { id } = req.params;
+        const contentType = req.headers["content-type"] || "application/octet-stream";
+        const credentials = {
+            authorization: req.headers.authorization,
+            cookie: req.headers.cookie,
+        };
+        // Extract original filename from custom header
+        const originalFilenameHeaderRaw = req.headers["x-original-filename"];
+        const originalFilenameHeader = Array.isArray(originalFilenameHeaderRaw)
+            ? originalFilenameHeaderRaw[0]
+            : originalFilenameHeaderRaw;
+        let originalFilename = "unknown_asset";
+        if (typeof originalFilenameHeader === "string" &&
+            originalFilenameHeader.length > 0) {
+            try {
+                originalFilename = decodeURIComponent(originalFilenameHeader);
+            }
+            catch (e) {
+                req.log.warn({ headerValue: originalFilenameHeaderRaw }, `[SERVER] Failed to decode X-Original-Filename header`);
+                originalFilename = "decode_error";
+            }
+        }
+        else {
+            req.log.warn({ headerValue: originalFilenameHeaderRaw }, `[SERVER] X-Original-Filename header missing or invalid`);
+        }
+        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)) {
+            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.",
+            });
+        }
+        try {
+            // Call the asset storage logic (which proxies to the backend)
+            await (0, assets_1.storeAsset)(id, req.raw, contentType, originalFilename, credentials);
+            req.log.debug({ assetId: id }, `[SERVER] Asset stored successfully.`);
+            reply.code(200).send({ success: true });
+        }
+        catch (error) {
+            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",
+            });
+        }
+    });
+    /**
+     * Handles asset retrieval (GET /assets/:id).
+     * Proxies the request to the asset storage backend via loadAsset and streams the response.
+     */
+    svc.get("/assets/:id", async (req, reply) => {
+        const { id } = req.params;
+        req.log.debug({ assetId: id }, `[SERVER] GET /assets/:id`);
+        // Capture the credentials if included from client
+        const credentials = {
+            authorization: req.headers.authorization,
+            cookie: req.headers.cookie,
+        };
+        try {
+            // Call the asset loading logic (which proxies to the backend)
+            const { stream: dataStream, contentType } = await (0, assets_1.loadAsset)(id, credentials);
+            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) {
+            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" });
+            }
+            else {
+                // Other errors during load
+                reply.code(500).send({
+                    success: false,
+                    error: error.message || "Failed to load asset",
+                });
+            }
+        }
+    });
+    // --- End Asset Handling ---
+});
+// --- End Define Routes ---
+// --- Start Server ---
+const start = async () => {
+    try {
+        await app.listen({ port: PORT, host: HOST });
+        app.log.info(`Sync Whiteboard server running on http://${HOST}:${PORT}`);
+    }
+    catch (err) {
+        app.log.fatal({ err: err }, "Server failed to start");
+        process.exit(1); // Exit if server fails to start
+    }
+};
+start();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smoothglue/sync-whiteboard",
-  "version": "1.0.3-79290.0",
+  "version": "1.1.0",
   "main": "dist/server.js",
   "scripts": {
     "dev": "ts-node-dev --respawn --transpile-only src/server.ts",
@@ -25,11 +25,11 @@
     "url": "https://code.build.smoothglue.io/braingu/smoothglue/frontend/sync-whiteboard.git"
   },
   "devDependencies": {
-    "@types/node": "^22.14.1",
+    "@types/node": "^22.18.0",
     "@types/ws": "^8.18.1",
     "ts-node": "^10.9.2",
     "ts-node-dev": "^2.0.0",
-    "typescript": "^5.8.3"
+    "typescript": "^5.9.2"
   },
   "dependencies": {
     "@fastify/cors": "^11.0.1",