@voidhash/mimic-effect 1.0.0-beta.1 → 1.0.0-beta.10

package/src/MimicServer.ts

@@ -10,7 +10,6 @@ import {
   Fiber,
   Layer,
   Metric,
-  Scope,
   Stream,
 } from "effect";
 import {
@@ -93,14 +92,14 @@ interface ConnectionState {
 /**
  * Handle a WebSocket connection for a document.
  */
-const handleWebSocketConnection = (
-  socket: Socket.Socket,
-  documentId: string,
-  engine: MimicServerEngine,
-  authService: MimicAuthService,
-  _routeConfig: ResolvedRouteConfig
-): Effect.Effect<void, Socket.SocketError, Scope.Scope> =>
-  Effect.gen(function* () {
+const handleWebSocketConnection = Effect.fn("websocket.connection.handle")(
+  function* (
+    socket: Socket.Socket,
+    documentId: string,
+    engine: MimicServerEngine,
+    authService: MimicAuthService,
+    _routeConfig: ResolvedRouteConfig
+  ) {
     const connectionId = crypto.randomUUID();
     const connectionStartTime = Date.now();
 
@@ -124,59 +123,62 @@ const handleWebSocketConnection = (
       write(Protocol.encodeServerMessage(message));
 
     // Send presence snapshot after auth
-    const sendPresenceSnapshot = Effect.gen(function* () {
-      if (!engine.config.presence) return;
+    const sendPresenceSnapshot = Effect.fn("presence.snapshot.send")(
+      function* () {
+        if (!engine.config.presence) return;
 
-      const snapshot = yield* engine.getPresenceSnapshot(documentId);
-      yield* sendMessage(
-        Protocol.presenceSnapshotMessage(connectionId, snapshot.presences)
-      );
-    });
+        const snapshot = yield* engine.getPresenceSnapshot(documentId);
+        yield* sendMessage(
+          Protocol.presenceSnapshotMessage(connectionId, snapshot.presences)
+        );
+      }
+    );
 
     // Send document snapshot after auth
-    const sendDocumentSnapshot = Effect.gen(function* () {
-      const snapshot = yield* engine.getSnapshot(documentId);
-      yield* sendMessage(
-        Protocol.snapshotMessage(snapshot.state, snapshot.version)
-      );
-    });
-
-    // Handle authentication
-    const handleAuth = (token: string) =>
-      Effect.gen(function* () {
-        const result = yield* Effect.either(
-          authService.authenticate(token, documentId)
+    const sendDocumentSnapshot = Effect.fn("document.snapshot.send")(
+      function* () {
+        const snapshot = yield* engine.getSnapshot(documentId);
+        yield* sendMessage(
+          Protocol.snapshotMessage(snapshot.state, snapshot.version)
         );
+      }
+    );
 
-        if (result._tag === "Right") {
-          state.authenticated = true;
-          state.authContext = result.right;
+    // Handle authentication
+    const handleAuth = Effect.fn("auth.handle")(function* (token: string) {
+      const result = yield* Effect.either(
+        authService.authenticate(token, documentId)
+      );
 
-          yield* sendMessage(
-            Protocol.authResultSuccess(
-              result.right.userId,
-              result.right.permission
-            )
-          );
+      if (result._tag === "Right") {
+        state.authenticated = true;
+        state.authContext = result.right;
 
-          // Send document snapshot after successful auth
-          yield* sendDocumentSnapshot;
+        yield* sendMessage(
+          Protocol.authResultSuccess(
+            result.right.userId,
+            result.right.permission
+          )
+        );
 
-          // Send presence snapshot after successful auth
-          yield* sendPresenceSnapshot;
-        } else {
-          yield* Metric.increment(Metrics.connectionsErrors);
-          yield* sendMessage(
-            Protocol.authResultFailure(
-              result.left.reason ?? "Authentication failed"
-            )
-          );
-        }
-      });
+        // Send document snapshot after successful auth
+        yield* sendDocumentSnapshot();
+
+        // Send presence snapshot after successful auth
+        yield* sendPresenceSnapshot();
+      } else {
+        yield* Metric.increment(Metrics.connectionsErrors);
+        yield* sendMessage(
+          Protocol.authResultFailure(
+            result.left.reason ?? "Authentication failed"
+          )
+        );
+      }
+    });
 
     // Handle presence set
-    const handlePresenceSet = (data: unknown) =>
-      Effect.gen(function* () {
+    const handlePresenceSet = Effect.fn("presence.set.handle")(
+      function* (data: unknown) {
         if (!state.authenticated) return;
         if (!state.authContext) return;
         if (!engine.config.presence) return;
@@ -206,20 +208,23 @@ const handleWebSocketConnection = (
         });
 
         state.hasPresence = true;
-      });
+      }
+    );
 
     // Handle presence clear
-    const handlePresenceClear = Effect.gen(function* () {
-      if (!state.authenticated) return;
-      if (!engine.config.presence) return;
+    const handlePresenceClear = Effect.fn("presence.clear.handle")(
+      function* () {
+        if (!state.authenticated) return;
+        if (!engine.config.presence) return;
 
-      yield* engine.removePresence(documentId, connectionId);
-      state.hasPresence = false;
-    });
+        yield* engine.removePresence(documentId, connectionId);
+        state.hasPresence = false;
+      }
+    );
 
     // Handle a client message
-    const handleMessage = (message: Protocol.ClientMessage) =>
-      Effect.gen(function* () {
+    const handleMessage = Effect.fn("message.handle")(
+      function* (message: Protocol.ClientMessage) {
         // Touch document on any activity (prevents idle GC)
         yield* engine.touch(documentId);
 
@@ -283,14 +288,15 @@ const handleWebSocketConnection = (
             break;
 
           case "presence_clear":
-            yield* handlePresenceClear;
+            yield* handlePresenceClear();
             break;
         }
-      });
+      }
+    );
 
     // Subscribe to document broadcasts
     const subscribeFiber = yield* Effect.fork(
-      Effect.gen(function* () {
+      Effect.fn("subscriptions.document.start")(function* () {
         // Wait until authenticated before subscribing
         while (!state.authenticated) {
           yield* Effect.sleep(Duration.millis(100));
@@ -303,12 +309,12 @@ const handleWebSocketConnection = (
         yield* Stream.runForEach(broadcastStream, (broadcast) =>
           sendMessage(broadcast as Protocol.ServerMessage)
         );
-      }).pipe(Effect.scoped)
+      })().pipe(Effect.scoped)
     );
 
     // Subscribe to presence events (if presence is enabled)
     const presenceFiber = yield* Effect.fork(
-      Effect.gen(function* () {
+      Effect.fn("subscriptions.presence.start")(function* () {
         if (!engine.config.presence) return;
 
         // Wait until authenticated before subscribing
@@ -334,12 +340,12 @@ const handleWebSocketConnection = (
             }
           })
         );
-      }).pipe(Effect.scoped)
+      })().pipe(Effect.scoped)
     );
 
     // Ensure cleanup on disconnect
     yield* Effect.addFinalizer(() =>
-      Effect.gen(function* () {
+      Effect.fn("connection.cleanup")(function* () {
         // Calculate connection duration
         const duration = Date.now() - connectionStartTime;
 
@@ -361,21 +367,22 @@ const handleWebSocketConnection = (
           documentId,
           durationMs: duration,
         });
-      })
+      })()
     );
 
     // Process incoming messages
     yield* socket.runRaw((data) =>
-      Effect.gen(function* () {
+      Effect.fn("message.process")(function* () {
         const message = yield* Protocol.parseClientMessage(data);
         yield* handleMessage(message);
-      }).pipe(
+      })().pipe(
         Effect.catchAll((error) =>
           Effect.logError("Message handling error", error)
         )
       )
     );
-  });
+  }
+);
 
 // =============================================================================
 // Factory
@@ -437,8 +444,8 @@ export const layerHttpLayerRouter = (
 
       // Create the handler that receives the request
       // Engine and authService are captured in closure, not yielded per-request
-      const handler = (request: HttpServerRequest.HttpServerRequest) =>
-        Effect.gen(function* () {
+      const handler = Effect.fn("websocket.route.handler")(
+        function* (request: HttpServerRequest.HttpServerRequest) {
           // Extract document ID from path
           const documentIdResult = yield* Effect.either(
             extractDocumentId(request.url)
@@ -470,7 +477,8 @@ export const layerHttpLayerRouter = (
 
           // Return empty response - the WebSocket upgrade handles the connection
           return HttpServerResponse.empty();
-        });
+        }
+      );
 
       yield* router.add("GET", routePath, handler);
     })

package/src/MimicServerEngine.ts

@@ -10,11 +10,15 @@ import {
   Context,
   Duration,
   Effect,
+  HashMap,
   Layer,
+  Metric,
+  Ref,
+  Schedule,
   Scope,
   Stream,
 } from "effect";
-import type { Presence, Primitive, Transaction } from "@voidhash/mimic";
+import type { Primitive, Transaction } from "@voidhash/mimic";
 import type {
   MimicServerEngineConfig,
   PresenceEntry,
@@ -27,15 +31,25 @@ import { ColdStorageTag } from "./ColdStorage";
 import { HotStorageTag } from "./HotStorage";
 import { MimicAuthServiceTag } from "./MimicAuthService";
 import {
-  DocumentManagerTag,
-  DocumentManagerConfigTag,
-  layer as documentManagerLayer,
+  DocumentInstance,
   type SubmitResult,
-} from "./DocumentManager";
+  type DocumentInstance as DocumentInstanceType,
+} from "./DocumentInstance";
 import {
   PresenceManagerTag,
   layer as presenceManagerLayer,
 } from "./PresenceManager";
+import * as Metrics from "./Metrics";
+import type { ColdStorageError, HotStorageError } from "./Errors";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Error type for MimicServerEngine operations
+ */
+export type MimicServerEngineError = ColdStorageError | HotStorageError;
 
 // =============================================================================
 // MimicServerEngine Interface
@@ -51,27 +65,30 @@ export interface MimicServerEngine {
   /**
    * Submit a transaction to a document.
    * Authorization is checked against the auth service.
+   * May fail with MimicServerEngineError if storage is unavailable.
    */
   readonly submit: (
     documentId: string,
     transaction: Transaction.Transaction
-  ) => Effect.Effect<SubmitResult, never>;
+  ) => Effect.Effect<SubmitResult, MimicServerEngineError>;
 
   /**
    * Get document snapshot (current state and version).
+   * May fail with MimicServerEngineError if storage is unavailable.
    */
   readonly getSnapshot: (
     documentId: string
-  ) => Effect.Effect<{ state: unknown; version: number }, never>;
+  ) => Effect.Effect<{ state: unknown; version: number }, MimicServerEngineError>;
 
   /**
    * Subscribe to document broadcasts (transactions).
    * Returns a stream of server messages.
    * Requires a Scope for cleanup when the subscription ends.
+   * May fail with MimicServerEngineError if storage is unavailable.
    */
   readonly subscribe: (
     documentId: string
-  ) => Effect.Effect<Stream.Stream<Protocol.ServerMessage, never, never>, never, Scope.Scope>;
+  ) => Effect.Effect<Stream.Stream<Protocol.ServerMessage, never, never>, MimicServerEngineError, Scope.Scope>;
 
   /**
    * Touch document to prevent idle garbage collection.
@@ -136,6 +153,7 @@ const DEFAULT_MAX_IDLE_TIME = Duration.minutes(5);
 const DEFAULT_MAX_TRANSACTION_HISTORY = 1000;
 const DEFAULT_SNAPSHOT_INTERVAL = Duration.minutes(5);
 const DEFAULT_SNAPSHOT_THRESHOLD = 100;
+const DEFAULT_SNAPSHOT_IDLE_TIMEOUT = Duration.seconds(30);
 
 /**
  * Resolve configuration with defaults
@@ -157,9 +175,24 @@ const resolveConfig = <TSchema extends Primitive.AnyPrimitive>(
       : DEFAULT_SNAPSHOT_INTERVAL,
     transactionThreshold:
       config.snapshot?.transactionThreshold ?? DEFAULT_SNAPSHOT_THRESHOLD,
+    idleTimeout: config.snapshot?.idleTimeout
+      ? Duration.decode(config.snapshot.idleTimeout)
+      : DEFAULT_SNAPSHOT_IDLE_TIMEOUT,
   },
 });
 
+// =============================================================================
+// Internal Types
+// =============================================================================
+
+/**
+ * Store entry for a document instance with last activity time
+ */
+interface StoreEntry<TSchema extends Primitive.AnyPrimitive> {
+  readonly instance: DocumentInstanceType<TSchema>;
+  readonly lastActivityTime: Ref.Ref<number>;
+}
+
 // =============================================================================
 // Factory
 // =============================================================================
@@ -204,37 +237,204 @@ export const make = <TSchema extends Primitive.AnyPrimitive>(
 > => {
   const resolvedConfig = resolveConfig(config);
 
-  // Create config layer for DocumentManager
-  const configLayer = Layer.succeed(
-    DocumentManagerConfigTag,
-    resolvedConfig as ResolvedConfig<Primitive.AnyPrimitive>
-  );
-
-  // Create internal layers
-  const internalLayers = Layer.mergeAll(
-    documentManagerLayer.pipe(Layer.provide(configLayer)),
-    presenceManagerLayer
-  );
-
   return Layer.scoped(
     MimicServerEngineTag,
     Effect.gen(function* () {
-      const documentManager = yield* DocumentManagerTag;
+      const coldStorage = yield* ColdStorageTag;
+      const hotStorage = yield* HotStorageTag;
       const presenceManager = yield* PresenceManagerTag;
 
+      // Store: documentId -> StoreEntry
+      const store = yield* Ref.make(
+        HashMap.empty<string, StoreEntry<TSchema>>()
+      );
+
+      /**
+       * Get or create a document instance
+       */
+      const getOrCreateDocument = Effect.fn("engine.document.get-or-create")(
+        function* (documentId: string) {
+          const current = yield* Ref.get(store);
+          const existing = HashMap.get(current, documentId);
+
+          if (existing._tag === "Some") {
+            // Update activity time
+            yield* Ref.set(existing.value.lastActivityTime, Date.now());
+            return existing.value.instance;
+          }
+
+          // Create new document instance
+          const instance = yield* DocumentInstance.make(
+            documentId,
+            {
+              schema: config.schema,
+              initial: config.initial,
+              maxTransactionHistory: resolvedConfig.maxTransactionHistory,
+              snapshot: resolvedConfig.snapshot,
+            },
+            coldStorage,
+            hotStorage
+          );
+
+          const lastActivityTime = yield* Ref.make(Date.now());
+
+          // Store it
+          yield* Ref.update(store, (map) =>
+            HashMap.set(map, documentId, { instance, lastActivityTime })
+          );
+
+          return instance;
+        }
+      );
+
+      /**
+       * Start background GC fiber
+       */
+      const startGCFiber = Effect.fn("engine.gc.start")(function* () {
+        const gcLoop = Effect.fn("engine.gc.loop")(function* () {
+          const current = yield* Ref.get(store);
+          const now = Date.now();
+          const maxIdleMs = Duration.toMillis(resolvedConfig.maxIdleTime);
+
+          for (const [documentId, entry] of current) {
+            const lastActivity = yield* Ref.get(entry.lastActivityTime);
+            if (now - lastActivity >= maxIdleMs) {
+              // Save final snapshot before eviction (best effort)
+              yield* Effect.catchAll(entry.instance.saveSnapshot(), (e) =>
+                Effect.logError("Failed to save snapshot during eviction", {
+                  documentId,
+                  error: e,
+                })
+              );
+
+              // Remove from store
+              yield* Ref.update(store, (map) => HashMap.remove(map, documentId));
+
+              // Track eviction metrics
+              yield* Metric.increment(Metrics.documentsEvicted);
+              yield* Metric.incrementBy(Metrics.documentsActive, -1);
+
+              yield* Effect.logInfo("Document evicted due to idle timeout", {
+                documentId,
+              });
+            }
+          }
+        });
+
+        // Run GC every minute
+        yield* gcLoop().pipe(
+          Effect.repeat(Schedule.spaced("1 minute")),
+          Effect.fork
+        );
+      });
+
+      // Start GC fiber
+      yield* startGCFiber();
+
+      /**
+       * Start background snapshot fiber for idle documents.
+       * This ensures documents with unsnapshot transactions get persisted
+       * even without new transaction activity.
+       */
+      const startSnapshotFiber = Effect.fn("engine.snapshot.fiber.start")(function* () {
+        const idleTimeoutMs = Duration.toMillis(resolvedConfig.snapshot.idleTimeout);
+
+        // Skip if idle snapshots are disabled
+        if (idleTimeoutMs <= 0) {
+          return;
+        }
+
+        const snapshotLoop = Effect.fn("engine.snapshot.loop")(function* () {
+          const current = yield* Ref.get(store);
+          const now = Date.now();
+
+          for (const [documentId, entry] of current) {
+            // Check if document has been idle long enough
+            const lastActivity = yield* Ref.get(entry.lastActivityTime);
+            const idleDuration = now - lastActivity;
+
+            if (idleDuration < idleTimeoutMs) {
+              // Document not idle long enough, skip
+              continue;
+            }
+
+            // Check if document has unsnapshot transactions
+            const needs = yield* entry.instance.needsSnapshot();
+            if (!needs) {
+              continue;
+            }
+
+            // Save snapshot (with error handling)
+            yield* Effect.catchAll(entry.instance.saveSnapshot(), (e) =>
+              Effect.logWarning("Periodic snapshot save failed", {
+                documentId,
+                error: e,
+              })
+            );
+
+            // Track metric
+            yield* Metric.increment(Metrics.storageIdleSnapshots);
+          }
+        });
+
+        // Run snapshot check every 10 seconds
+        yield* snapshotLoop().pipe(
+          Effect.repeat(Schedule.spaced("10 seconds")),
+          Effect.fork
+        );
+      });
+
+      // Start snapshot fiber
+      yield* startSnapshotFiber();
+
+      // Cleanup on shutdown
+      yield* Effect.addFinalizer(() =>
+        Effect.fn("engine.shutdown")(function* () {
+          const current = yield* Ref.get(store);
+          for (const [documentId, entry] of current) {
+            // Best effort save - don't fail shutdown if storage is unavailable
+            yield* Effect.catchAll(entry.instance.saveSnapshot(), (e) =>
+              Effect.logError("Failed to save snapshot during shutdown", {
+                documentId,
+                error: e,
+              })
+            );
+          }
+          yield* Effect.logInfo("MimicServerEngine shutdown complete");
+        })()
+      );
+
       const engine: MimicServerEngine = {
         submit: (documentId, transaction) =>
-          documentManager.submit(documentId, transaction),
+          Effect.gen(function* () {
+            const instance = yield* getOrCreateDocument(documentId);
+            return yield* instance.submit(transaction);
+          }),
 
-        getSnapshot: (documentId) => documentManager.getSnapshot(documentId),
+        getSnapshot: (documentId) =>
+          Effect.gen(function* () {
+            const instance = yield* getOrCreateDocument(documentId);
+            return instance.getSnapshot();
+          }),
 
         subscribe: (documentId) =>
-          documentManager.subscribe(documentId) as Effect.Effect<
-            Stream.Stream<Protocol.ServerMessage, never, never>,
-            never
-          >,
-
-        touch: (documentId) => documentManager.touch(documentId),
+          Effect.gen(function* () {
+            const instance = yield* getOrCreateDocument(documentId);
+            return Stream.fromPubSub(instance.pubsub) as Stream.Stream<
+              Protocol.ServerMessage,
+              never,
+              never
+            >;
+          }),
+
+        touch: (documentId) =>
+          Effect.gen(function* () {
+            const current = yield* Ref.get(store);
+            const existing = HashMap.get(current, documentId);
+            if (existing._tag === "Some") {
+              yield* Ref.set(existing.value.lastActivityTime, Date.now());
+            }
+          }),
 
         getPresenceSnapshot: (documentId) =>
           presenceManager.getSnapshot(documentId),
@@ -253,7 +453,7 @@ export const make = <TSchema extends Primitive.AnyPrimitive>(
 
       return engine;
     })
-  ).pipe(Layer.provide(internalLayers));
+  ).pipe(Layer.provide(presenceManagerLayer));
 };
 
 // =============================================================================