@vuer-ai/vuer-rtc-server 0.2.0 → 0.2.2

package/src/serve.ts

@@ -13,6 +13,8 @@
  *   GET /api/documents/:id/sessions
  *   GET /api/rooms/:roomId/state
  *   DELETE /api/rooms/:roomId
+ *   POST /api/documents/:id/compact — trigger journal compaction
+ *   POST /api/documents/:id/coalesce — operation coalescing (placeholder)
  */
 
 import { createServer, type IncomingMessage, type ServerResponse } from 'http';
@@ -21,12 +23,16 @@ import { InMemoryBroker } from './broker/index.js';
 import { RTCServer } from './transport/index.js';
 import { createPrismaClient } from './persistence/PrismaClient.js';
 import { JournalService } from './journal/index.js';
+import { SessionRepository } from './persistence/SessionRepository.js';
+import { CoalescingService } from './journal/CoalescingService.js';
 
 const PORT = Number(process.env.PORT) || 8080;
 const prisma = createPrismaClient();
 
 const broker = new InMemoryBroker();
 const journalService = new JournalService(prisma);
+const sessionRepo = new SessionRepository(prisma);
+const coalescingService = new CoalescingService(prisma);
 
 // Wire the broker's member clocks into the journal service so compaction
 // only folds entries that all connected clients have acknowledged.
@@ -42,6 +48,99 @@ journalService.setMemberClockProvider(async (docId: string) => {
 
 journalService.startCompactionLoop();
 
+// ── Session TTL cleanup loop ──
+// Automatically removes disconnected sessions after TTL expires.
+const SESSION_TTL_MS = 2 * 60 * 1000; // 2 minutes
+const SESSION_CLEANUP_INTERVAL_MS = 30_000; // Run every 30 seconds
+const SESSION_DB_RETENTION_MS = SESSION_TTL_MS; // Match broker TTL for demo visibility
+let sessionCleanupTimer: NodeJS.Timeout | null = null;
+
+async function cleanupStaleSessions() {
+  try {
+    const now = Date.now();
+    const roomIds = broker.getAllRoomIds();
+    let totalRemoved = 0;
+
+    // Clean up stale sessions from broker memory
+    for (const roomId of roomIds) {
+      const members = await broker.getMembers(roomId);
+      for (const [sessionId, member] of members) {
+        if (!member.connected && (now - member.lastSeen) > SESSION_TTL_MS) {
+          broker.removeMember(roomId, sessionId);
+          totalRemoved++;
+        }
+      }
+    }
+
+    // Clean up stale sessions from MongoDB
+    // Keep disconnected sessions for auditing period, then delete
+    const deleteOlderThan = new Date(now - SESSION_DB_RETENTION_MS);
+    const deletedCount = await sessionRepo.deleteDisconnected(deleteOlderThan);
+
+    if (totalRemoved > 0 || deletedCount > 0) {
+      console.log(`[session-ttl] cleaned up ${totalRemoved} stale sessions from broker, ${deletedCount} old sessions from DB`);
+    }
+  } catch (err) {
+    console.error('[session-ttl] cleanup failed:', err);
+  }
+}
+
+function startSessionCleanupLoop() {
+  sessionCleanupTimer = setInterval(cleanupStaleSessions, SESSION_CLEANUP_INTERVAL_MS);
+}
+
+function stopSessionCleanupLoop() {
+  if (sessionCleanupTimer) {
+    clearInterval(sessionCleanupTimer);
+    sessionCleanupTimer = null;
+  }
+}
+
+startSessionCleanupLoop();
+
+// ── Session heartbeat sync ──
+// Periodically sync session state from broker to database.
+// This updates lastSeen timestamps and vector clocks for connected sessions.
+const SESSION_SYNC_INTERVAL_MS = 30_000; // 30 seconds
+let sessionSyncTimer: NodeJS.Timeout | null = null;
+
+async function syncSessionHeartbeats() {
+  try {
+    // Iterate through all tracked sessions
+    for (const [clientId, dbSessionId] of sessionIdMap.entries()) {
+      // Find the room/document for this session
+      for (const [roomId, docPromise] of roomDocPromises.entries()) {
+        const docId = await docPromise;
+        const members = await broker.getMembers(roomId);
+        const member = members.get(clientId);
+
+        if (member && member.connected) {
+          // Update last seen and clock value
+          const clockValue = Object.values(member.vectorClock).reduce((sum, v) => sum + v, 0);
+          await sessionRepo.updateLastSeen(dbSessionId);
+          // Could also update clock value here if needed
+          break; // Found the member, no need to check other rooms
+        }
+      }
+    }
+  } catch (err) {
+    console.error('[session-sync] heartbeat sync failed:', err);
+  }
+}
+
+function startSessionHeartbeatSync() {
+  sessionSyncTimer = setInterval(syncSessionHeartbeats, SESSION_SYNC_INTERVAL_MS);
+}
+
+function stopSessionHeartbeatSync() {
+  if (sessionSyncTimer) {
+    clearInterval(sessionSyncTimer);
+    sessionSyncTimer = null;
+  }
+}
+
+startSessionHeartbeatSync();
+
 // ── Room → Document mapping ──
 // RTCServer uses roomId strings, but MongoDB documents have ObjectId IDs.
 // This adapter auto-creates a Document per room and maps between them.
@@ -49,6 +148,10 @@ journalService.startCompactionLoop();
 // Promise-based dedup: concurrent calls for the same roomId share one promise.
 const roomDocPromises = new Map<string, Promise<string>>();
 
+// Session ID mapping: clientId (from query param) -> DB session ObjectId
+// This allows us to track which database session corresponds to each WebSocket connection
+const sessionIdMap = new Map<string, string>();
+
 function ensureRoomDocument(roomId: string): Promise<string> {
   if (!roomDocPromises.has(roomId)) {
     roomDocPromises.set(roomId, (async () => {
@@ -82,8 +185,9 @@ function json(res: ServerResponse, data: unknown, status = 200) {
 
 function cors(res: ServerResponse) {
   res.setHeader('Access-Control-Allow-Origin', '*');
-  res.setHeader('Access-Control-Allow-Methods', 'GET, DELETE, OPTIONS');
-  res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS, PUT, PATCH');
+  res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-Requested-With, Accept');
+  res.setHeader('Access-Control-Max-Age', '86400'); // 24 hours
 }
 
 // ── REST API router ──
@@ -113,6 +217,183 @@ async function handleApi(req: IncomingMessage, res: ServerResponse): Promise<voi
       return;
     }
 
+    // GET /api/stats/sizes — detailed size breakdown
+    if (path === '/api/stats/sizes') {
+      // Use MongoDB aggregation to compute sizes directly in database
+      // This avoids loading all records into memory
+
+      // Compute document state sizes using aggregation
+      const docSizesPipeline: any = [
+        {
+          $project: {
+            _id: 1,
+            name: 1,
+            stateSize: {
+              $cond: [
+                { $ne: ['$currentState', null] },
+                { $strLenBytes: { $toString: '$currentState' } },
+                0
+              ]
+            }
+          }
+        }
+      ];
+
+      const docSizesResult = await (db as any).document.aggregateRaw({
+        pipeline: docSizesPipeline
+      });
+
+      // Aggregate journal batch sizes by document
+      const journalPipeline: any = [
+        {
+          $project: {
+            documentId: 1,
+            opSize: {
+              $cond: [
+                { $ne: ['$operations', null] },
+                { $strLenBytes: { $toString: '$operations' } },
+                0
+              ]
+            }
+          }
+        },
+        {
+          $group: {
+            _id: '$documentId',
+            count: { $sum: 1 },
+            totalSize: { $sum: '$opSize' }
+          }
+        }
+      ];
+
+      const journalSizesResult = await (db as any).journalBatch.aggregateRaw({
+        pipeline: journalPipeline
+      });
+
+      // Aggregate operation sizes by document
+      const opPipeline: any = [
+        {
+          $project: {
+            documentId: 1,
+            dataSize: {
+              $cond: [
+                { $ne: ['$data', null] },
+                { $strLenBytes: { $toString: '$data' } },
+                0
+              ]
+            },
+            clockSize: {
+              $cond: [
+                { $ne: ['$vectorClock', null] },
+                { $strLenBytes: { $toString: '$vectorClock' } },
+                0
+              ]
+            }
+          }
+        },
+        {
+          $group: {
+            _id: '$documentId',
+            count: { $sum: 1 },
+            totalSize: { $sum: { $add: ['$dataSize', '$clockSize'] } }
+          }
+        }
+      ];
+
+      const opSizesResult = await (db as any).operation.aggregateRaw({
+        pipeline: opPipeline
+      });
+
+      // Aggregate session sizes by document
+      const sessionPipeline: any = [
+        {
+          $project: {
+            documentId: 1,
+            presenceSize: {
+              $cond: [
+                { $ne: ['$presence', null] },
+                { $strLenBytes: { $toString: '$presence' } },
+                0
+              ]
+            }
+          }
+        },
+        {
+          $group: {
+            _id: '$documentId',
+            count: { $sum: 1 },
+            totalSize: { $sum: '$presenceSize' }
+          }
+        }
+      ];
+
+      const sessionSizesResult = await (db as any).session.aggregateRaw({
+        pipeline: sessionPipeline
+      });
+
+      // Convert aggregation results to lookup maps
+      const journalSizesByDoc: Record<string, { count: number; totalSize: number }> = {};
+      for (const item of journalSizesResult) {
+        journalSizesByDoc[item._id] = { count: item.count, totalSize: item.totalSize };
+      }
+
+      const opSizesByDoc: Record<string, { count: number; totalSize: number }> = {};
+      for (const item of opSizesResult) {
+        opSizesByDoc[item._id] = { count: item.count, totalSize: item.totalSize };
+      }
+
+      const sessionSizesByDoc: Record<string, { count: number; totalSize: number }> = {};
+      for (const item of sessionSizesResult) {
+        sessionSizesByDoc[item._id] = { count: item.count, totalSize: item.totalSize };
+      }
+
+      // Build per-document summary
+      const documents = docSizesResult.map((d: any) => {
+        const id = d._id;
+        const stateSize = d.stateSize ?? 0;
+        const journalSize = journalSizesByDoc[id]?.totalSize ?? 0;
+        const operationsSize = opSizesByDoc[id]?.totalSize ?? 0;
+        const sessionsSize = sessionSizesByDoc[id]?.totalSize ?? 0;
+
+        return {
+          id,
+          name: d.name,
+          stateSize,
+          journalBatches: journalSizesByDoc[id]?.count ?? 0,
+          journalSize,
+          operations: opSizesByDoc[id]?.count ?? 0,
+          operationsSize,
+          sessions: sessionSizesByDoc[id]?.count ?? 0,
+          sessionsSize,
+          totalSize: stateSize + journalSize + operationsSize + sessionsSize,
+        };
+      });
+
+      // Compute aggregate totals
+      const totalStateSize = docSizesResult.reduce((sum: number, d: any) => sum + (d.stateSize ?? 0), 0);
+      const totalJournalSize = Object.values(journalSizesByDoc).reduce((sum, j) => sum + j.totalSize, 0);
+      const totalOpSize = Object.values(opSizesByDoc).reduce((sum, o) => sum + o.totalSize, 0);
+      const totalSessionSize = Object.values(sessionSizesByDoc).reduce((sum, s) => sum + s.totalSize, 0);
+      const totalSize = totalStateSize + totalJournalSize + totalOpSize + totalSessionSize;
+
+      const journalBatchCount = Object.values(journalSizesByDoc).reduce((sum, j) => sum + j.count, 0);
+      const operationsCount = Object.values(opSizesByDoc).reduce((sum, o) => sum + o.count, 0);
+      const sessionsCount = Object.values(sessionSizesByDoc).reduce((sum, s) => sum + s.count, 0);
+
+      json(res, {
+        totalSize,
+        totalStateSize,
+        totalJournalSize,
+        totalOpSize,
+        totalSessionSize,
+        journalBatchCount,
+        operationsCount,
+        sessionsCount,
+        documents,
+      });
+      return;
+    }
+
     // GET /api/documents
     if (path === '/api/documents') {
       const docs = await db.document.findMany({
@@ -125,7 +406,7 @@ async function handleApi(req: IncomingMessage, res: ServerResponse): Promise<voi
 
     // GET /api/documents/:id[/sub]
     const docMatch = path.match(/^\/api\/documents\/([^/]+)(\/.*)?$/);
-    if (docMatch) {
+    if (docMatch && req.method === 'GET') {
       const docId = docMatch[1];
       const sub = docMatch[2] ?? '';
 
@@ -137,28 +418,108 @@ async function handleApi(req: IncomingMessage, res: ServerResponse): Promise<voi
       }
 
       if (sub === '/journal') {
-        const batches = await db.journalBatch.findMany({
-          where: { documentId: docId },
-          orderBy: { persistedAt: 'asc' },
-        });
-        json(res, batches);
+        // Parse query params: order (asc/desc), limit, offset
+        const order = url.searchParams.get('order') === 'asc' ? 'asc' : 'desc';
+        const limit = Math.min(Math.max(1, Number(url.searchParams.get('limit')) || 100), 1000);
+        const offset = Math.max(0, Number(url.searchParams.get('offset')) || 0);
+
+        const [batches, total] = await Promise.all([
+          db.journalBatch.findMany({
+            where: { documentId: docId },
+            orderBy: { persistedAt: order },
+            take: limit,
+            skip: offset,
+          }),
+          db.journalBatch.count({ where: { documentId: docId } }),
+        ]);
+        json(res, { batches, total, limit, offset, order });
         return;
       }
 
       if (sub === '/operations') {
-        const ops = await db.operation.findMany({
+        // Operations are embedded in JournalBatch.operations[], not in a separate collection
+        // Extract and flatten all operations from journal batches
+        const order = url.searchParams.get('order') === 'asc' ? 'asc' : 'desc';
+        const limit = Math.min(parseInt(url.searchParams.get('limit') ?? '100', 10), 1000);
+        const offset = parseInt(url.searchParams.get('offset') ?? '0', 10);
+
+        const batches = await db.journalBatch.findMany({
           where: { documentId: docId },
-          orderBy: { lamportTime: 'asc' },
+          orderBy: { lamportTime: order },
         });
-        json(res, ops);
+
+        // Flatten operations from all batches
+        const allOps: any[] = [];
+        for (const batch of batches) {
+          const ops = Array.isArray(batch.operations) ? batch.operations : [];
+          for (const op of ops) {
+            allOps.push({
+              ...(op as object),
+              sessionId: batch.sessionId,
+              batchId: batch.batchId,
+              lamportTime: batch.lamportTime,
+              persistedAt: batch.persistedAt,
+            });
+          }
+        }
+
+        // Sort by lamport time
+        if (order === 'desc') {
+          allOps.sort((a, b) => (b.lamportTime ?? 0) - (a.lamportTime ?? 0));
+        } else {
+          allOps.sort((a, b) => (a.lamportTime ?? 0) - (b.lamportTime ?? 0));
+        }
+
+        const total = allOps.length;
+        const paginatedOps = allOps.slice(offset, offset + limit);
+
+        json(res, { operations: paginatedOps, total, limit, offset, order });
         return;
       }
 
       if (sub === '/sessions') {
-        const sessions = await db.session.findMany({
+        // Sessions are derived from JournalBatch sessionIds since Session collection isn't used
+        const batches = await db.journalBatch.findMany({
           where: { documentId: docId },
-          orderBy: { connectedAt: 'desc' },
+          orderBy: { persistedAt: 'desc' },
         });
+
+        // Aggregate session info from batches
+        const sessionMap = new Map<string, {
+          sessionId: string;
+          batchCount: number;
+          operationCount: number;
+          firstSeen: Date;
+          lastSeen: Date;
+          lastLamportTime: number;
+        }>();
+
+        for (const batch of batches) {
+          const sid = batch.sessionId;
+          const ops = Array.isArray(batch.operations) ? batch.operations : [];
+          const existing = sessionMap.get(sid);
+          if (existing) {
+            existing.batchCount++;
+            existing.operationCount += ops.length;
+            if (batch.persistedAt < existing.firstSeen) existing.firstSeen = batch.persistedAt;
+            if (batch.persistedAt > existing.lastSeen) existing.lastSeen = batch.persistedAt;
+            existing.lastLamportTime = Math.max(existing.lastLamportTime, batch.lamportTime ?? 0);
+          } else {
+            sessionMap.set(sid, {
+              sessionId: sid,
+              batchCount: 1,
+              operationCount: ops.length,
+              firstSeen: batch.persistedAt,
+              lastSeen: batch.persistedAt,
+              lastLamportTime: batch.lamportTime ?? 0,
+            });
+          }
+        }
+
+        const sessions = Array.from(sessionMap.values()).sort((a, b) =>
+          b.lastSeen.getTime() - a.lastSeen.getTime()
+        );
+
         json(res, sessions);
         return;
       }
@@ -198,6 +559,301 @@ async function handleApi(req: IncomingMessage, res: ServerResponse): Promise<voi
       return;
     }
 
+    // POST /api/documents/:id/compact — manually trigger compaction
+    const compactMatch = path.match(/^\/api\/documents\/([^/]+)\/compact$/);
+    if (compactMatch && req.method === 'POST') {
+      const docId = compactMatch[1];
+
+      try {
+        // Get before stats (count ops from journal batches, not empty Operation collection)
+        const beforeBatches = await db.journalBatch.findMany({ where: { documentId: docId } });
+        const beforeOpsCount = beforeBatches.reduce((sum, b) => {
+          const ops = Array.isArray(b.operations) ? b.operations : [];
+          return sum + ops.length;
+        }, 0);
+
+        console.log(`[compact] Starting compaction for doc ${docId}: ${beforeBatches.length} batches, ${beforeOpsCount} ops`);
+
+        // Run compaction (no watermark = compact everything)
+        await journalService.compact(docId);
+
+        // Get after stats
+        const afterBatches = await db.journalBatch.findMany({ where: { documentId: docId } });
+        const afterOpsCount = afterBatches.reduce((sum, b) => {
+          const ops = Array.isArray(b.operations) ? b.operations : [];
+          return sum + ops.length;
+        }, 0);
+
+        console.log(`[compact] Completed compaction for doc ${docId}: ${afterBatches.length} batches, ${afterOpsCount} ops`);
+
+        json(res, {
+          ok: true,
+          before: { journalBatches: beforeBatches.length, operations: beforeOpsCount },
+          after: { journalBatches: afterBatches.length, operations: afterOpsCount },
+          reduction: {
+            journalBatches: beforeBatches.length - afterBatches.length,
+            operations: beforeOpsCount - afterOpsCount,
+          },
+        });
+      } catch (e: any) {
+        console.error(`[compact] Error compacting doc ${docId}:`, e);
+        json(res, { ok: false, error: e.message, stack: e.stack }, 500);
+      }
+      return;
+    }
+
+    // POST /api/documents/:id/coalesce — operation coalescing
+    const coalesceMatch = path.match(/^\/api\/documents\/([^/]+)\/coalesce$/);
+    if (coalesceMatch && req.method === 'POST') {
+      const docId = coalesceMatch[1];
+
+      try {
+        // Parse optional config from request body
+        let config: { setThresholdMs?: number; enableTextCoalesce?: boolean; enableSetCoalesce?: boolean; enableVectorCoalesce?: boolean } = {};
+        if (req.headers['content-length'] && parseInt(req.headers['content-length']) > 0) {
+          const body = await new Promise<string>((resolve) => {
+            let data = '';
+            req.on('data', chunk => data += chunk);
+            req.on('end', () => resolve(data));
+          });
+          if (body) {
+            try {
+              config = JSON.parse(body);
+            } catch {
+              // Ignore parse errors, use defaults
+            }
+          }
+        }
+
+        const result = await coalescingService.coalesce(docId, config);
+        json(res, result);
+      } catch (e: any) {
+        json(res, { ok: false, error: e.message }, 500);
+      }
+      return;
+    }
+
+    // DELETE /api/documents/:id — permanently delete a document and all its data
+    const docDeleteMatch = path.match(/^\/api\/documents\/([^/]+)$/);
+    if (docDeleteMatch && req.method === 'DELETE') {
+      const docId = docDeleteMatch[1];
+
+      try {
+        // Delete in order: sessions -> journal batches -> operations -> document
+        const sessionsDeleted = await db.session.deleteMany({ where: { documentId: docId } });
+        const batchesDeleted = await db.journalBatch.deleteMany({ where: { documentId: docId } });
+        const opsDeleted = await db.operation.deleteMany({ where: { documentId: docId } });
+        const doc = await db.document.delete({ where: { id: docId } });
+
+        // Also clear any in-memory state for the room
+        const roomId = doc.name;
+        rtcServer.clearRoom(roomId);
+        await broker.clearRoom(roomId);
+        roomDocPromises.delete(roomId);
+
+        json(res, {
+          ok: true,
+          deleted: {
+            document: doc.name,
+            sessions: sessionsDeleted.count,
+            journalBatches: batchesDeleted.count,
+            operations: opsDeleted.count,
+          },
+        });
+      } catch (e: any) {
+        json(res, { ok: false, error: e.message }, 404);
+      }
+      return;
+    }
+
+    // POST /api/rooms/:id/cleanup-sessions — remove stale disconnected sessions
+    const cleanupMatch = path.match(/^\/api\/rooms\/([^/]+)\/cleanup-sessions$/);
+    if (cleanupMatch && req.method === 'POST') {
+      const roomId = cleanupMatch[1];
+      const maxAge = 60_000; // Remove sessions disconnected > 1 minute ago
+      const now = Date.now();
+
+      const members = await broker.getMembers(roomId);
+      let removed = 0;
+      for (const [sessionId, member] of members) {
+        if (!member.connected && (now - member.lastSeen) > maxAge) {
+          broker.removeMember(roomId, sessionId);
+          removed++;
+        }
+      }
+
+      json(res, { ok: true, removed, remaining: members.size - removed });
+      return;
+    }
+
+    // POST /api/rooms/:id/leave — immediate session cleanup (for beforeunload beacon)
+    const leaveMatch = path.match(/^\/api\/rooms\/([^/]+)\/leave$/);
+    if (leaveMatch && req.method === 'POST') {
+      const roomId = leaveMatch[1];
+
+      // Parse body for sessionId
+      let body = '';
+      for await (const chunk of req) {
+        body += chunk;
+      }
+
+      let sessionId: string | undefined;
+      try {
+        const data = JSON.parse(body);
+        sessionId = data.sessionId;
+      } catch {
+        // Ignore parse errors - beacon may send empty body
+      }
+
+      if (sessionId) {
+        // Mark as disconnected and remove immediately
+        const members = await broker.getMembers(roomId);
+        if (members.has(sessionId)) {
+          broker.removeMember(roomId, sessionId);
+          json(res, { ok: true, removed: true, sessionId });
+          return;
+        }
+      }
+
+      json(res, { ok: true, removed: false });
+      return;
+    }
+
+    // GET /api/documents/:id/metrics — performance metrics inspection
+    const metricsMatch = path.match(/^\/api\/documents\/([^/]+)\/metrics$/);
+    if (metricsMatch) {
+      const docId = metricsMatch[1];
+
+      // Import compression utilities
+      const { getCompressionStats } = await import('./compression/CompressionUtils.js');
+      const { encodeRLE } = await import('./journal/RLECompression.js');
+
+      // Fetch document and journal batches
+      const doc = await db.document.findUnique({ where: { id: docId } });
+      if (!doc) { json(res, { error: 'Not found' }, 404); return; }
+
+      const batches = await db.journalBatch.findMany({
+        where: { documentId: docId },
+        orderBy: { persistedAt: 'asc' },
+      });
+
+      // Calculate storage metrics
+      const rawSize = JSON.stringify(batches.map(b => b.operations)).length;
+
+      // Convert batches to CRDTMessage format for RLE encoding
+      const allMessages: any[] = batches.map(batch => ({
+        sessionId: batch.sessionId,
+        lamportTime: batch.lamportTime ?? 0,
+        timestamp: new Date(batch.persistedAt).getTime(),
+        ops: Array.isArray(batch.operations) ? batch.operations : [],
+      }));
+
+      const rleEncoded = encodeRLE(allMessages);
+      const rleSize = JSON.stringify(rleEncoded).length;
+
+      // Calculate gzip compression
+      const gzipStats = getCompressionStats(batches.map(b => b.operations));
+      const gzipSize = gzipStats.compressedSize;
+      const compressionRatio = rawSize > 0 ? (rawSize - gzipSize) / rawSize : 0;
+
+      // Calculate batching metrics
+      const uniqueSessions = new Set(allMessages.map(m => m.sessionId)).size;
+      const totalOps = allMessages.reduce((sum, m) => sum + (m.ops?.length ?? 1), 0);
+      const avgOpsPerBatch = batches.length > 0 ? totalOps / batches.length : 0;
+      const batchingEfficiency = allMessages.length > 0 ? batches.length / allMessages.length : 0;
+
+      // Calculate sync metrics
+      const snapshotSize = JSON.stringify(doc.currentState ?? {}).length;
+      const journalSize = rawSize;
+      const totalTransferSize = snapshotSize + journalSize;
+      const estimatedSyncMs = {
+        mobile1Mbps: Math.round((totalTransferSize * 8) / (1024 * 1024) * 1000),
+        desktop10Mbps: Math.round((totalTransferSize * 8) / (10 * 1024 * 1024) * 1000),
+      };
+
+      // Calculate compaction metrics
+      const journalLength = batches.length;
+      const threshold = 500; // COMPACTION_THRESHOLD_ENTRIES from JournalService
+      const lastCompactedBatch = batches.length > 0 ? batches[0] : null;
+      const lastCompactedAt = lastCompactedBatch?.persistedAt ?? doc.updatedAt;
+
+      // Estimate compaction candidates (entries older than 1 hour)
+      const oneHourAgo = new Date(Date.now() - 3600000);
+      const compactionCandidates = batches.filter(
+        b => new Date(b.persistedAt) < oneHourAgo
+      ).length;
+
+      // Flatten all operations from journal batches for metrics
+      const flatOps: any[] = [];
+      for (const batch of batches) {
+        const ops = Array.isArray(batch.operations) ? batch.operations : [];
+        for (const op of ops) {
+          flatOps.push({
+            ...(op as object),
+            lamportTime: batch.lamportTime,
+            vectorClock: batch.vectorClock,
+          });
+        }
+      }
+
+      // Calculate operation type distribution from journal ops
+      const typeDistribution: Record<string, number> = {};
+      for (const op of flatOps) {
+        const otype = op.otype ?? op.type ?? 'unknown';
+        typeDistribution[otype] = (typeDistribution[otype] ?? 0) + 1;
+      }
+
+      // Calculate lamport range from batches
+      const lamportTimes = batches.map(b => b.lamportTime ?? 0);
+      const lamportRange = lamportTimes.length > 0
+        ? [Math.min(...lamportTimes), Math.max(...lamportTimes)]
+        : [0, 0];
+
+      // Calculate vector clock complexity from batches
+      const uniqueSessionsInClocks = new Set<string>();
+      for (const batch of batches) {
+        const clock = batch.vectorClock as Record<string, number> | null;
+        if (clock && typeof clock === 'object') {
+          Object.keys(clock).forEach(sessionId => uniqueSessionsInClocks.add(sessionId));
+        }
+      }
+      const vectorClockComplexity = uniqueSessionsInClocks.size;
+
+      json(res, {
+        storage: {
+          rawSize,
+          rleSize,
+          gzipSize,
+          compressionRatio,
+          totalBatches: batches.length,
+          totalOperations: flatOps.length,
+        },
+        coalescing: {
+          uniqueSessions,
+          avgOpsPerBatch,
+          batchingEfficiency,
+        },
+        sync: {
+          snapshotSize,
+          journalSize,
+          totalTransferSize,
+          estimatedSyncMs,
+        },
+        compaction: {
+          journalLength,
+          threshold,
+          lastCompactedAt,
+          compactionCandidates,
+        },
+        operations: {
+          typeDistribution,
+          lamportRange,
+          vectorClockComplexity,
+        },
+      });
+      return;
+    }
+
     json(res, { error: 'Not found' }, 404);
   } catch (err: any) {
     console.error('[api]', err);
@@ -243,10 +899,39 @@ wss.on('connection', (ws, req) => {
   // The journalAdapter handles room creation lazily inside processMessage.
   rtcServer.handleConnection(ws, roomId, sessionId);
 
-  // Send stored state (if any) once the room document is ready.
+  // Create session record in database after ensuring document exists
   ensureRoomDocument(roomId)
-    .then(() => rtcServer.handleStateTransfer(ws, roomId))
+    .then(async (docId) => {
+      // Create session in database
+      try {
+        const dbSession = await sessionRepo.create({
+          documentId: docId,
+          userId: url.searchParams.get('userId') ?? 'anonymous',
+          clientId: sessionId,
+        });
+        sessionIdMap.set(sessionId, dbSession.id);
+        // console.log(`[session] created session ${dbSession.id} for client ${sessionId} in doc ${docId}`);
+      } catch (err) {
+        console.error(`[session] failed to create session for ${sessionId}:`, err);
+      }
+
+      // Send stored state
+      return rtcServer.handleStateTransfer(ws, roomId);
+    })
     .catch((err) => console.error(`[state-transfer] room="${roomId}":`, err));
+
+  // Handle disconnect — mark session as disconnected
+  ws.on('close', () => {
+    const dbSessionId = sessionIdMap.get(sessionId);
+    if (dbSessionId) {
+      sessionRepo.disconnect(dbSessionId)
+        .then(() => {
+          // console.log(`[session] disconnected session ${dbSessionId} for client ${sessionId}`);
+          sessionIdMap.delete(sessionId);
+        })
+        .catch((err) => console.error(`[session] failed to disconnect session ${dbSessionId}:`, err));
+    }
+  });
 });
 
 server.listen(PORT, () => {
@@ -257,6 +942,8 @@ server.listen(PORT, () => {
 
 function shutdown() {
   journalService.stopCompactionLoop();
+  stopSessionHeartbeatSync();
+  stopSessionCleanupLoop();
   server.close(() => {
     prisma.$disconnect().catch(() => {});
   });