@voidhash/mimic-effect 1.0.0-beta.6 → 1.0.0-beta.8

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,16 +31,25 @@ import { ColdStorageTag } from "./ColdStorage";
 import { HotStorageTag } from "./HotStorage";
 import { MimicAuthServiceTag } from "./MimicAuthService";
 import {
-  DocumentManagerTag,
-  DocumentManagerConfigTag,
-  layer as documentManagerLayer,
+  DocumentInstance,
   type SubmitResult,
-  type DocumentManagerError,
-} 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
@@ -52,30 +65,30 @@ export interface MimicServerEngine {
   /**
    * Submit a transaction to a document.
    * Authorization is checked against the auth service.
-   * May fail with DocumentManagerError if storage is unavailable.
+   * May fail with MimicServerEngineError if storage is unavailable.
    */
   readonly submit: (
     documentId: string,
     transaction: Transaction.Transaction
-  ) => Effect.Effect<SubmitResult, DocumentManagerError>;
+  ) => Effect.Effect<SubmitResult, MimicServerEngineError>;
 
   /**
    * Get document snapshot (current state and version).
-   * May fail with DocumentManagerError if storage is unavailable.
+   * May fail with MimicServerEngineError if storage is unavailable.
    */
   readonly getSnapshot: (
     documentId: string
-  ) => Effect.Effect<{ state: unknown; version: number }, DocumentManagerError>;
+  ) => 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 DocumentManagerError if storage is unavailable.
+   * May fail with MimicServerEngineError if storage is unavailable.
    */
   readonly subscribe: (
     documentId: string
-  ) => Effect.Effect<Stream.Stream<Protocol.ServerMessage, never, never>, DocumentManagerError, Scope.Scope>;
+  ) => Effect.Effect<Stream.Stream<Protocol.ServerMessage, never, never>, MimicServerEngineError, Scope.Scope>;
 
   /**
    * Touch document to prevent idle garbage collection.
@@ -164,6 +177,18 @@ const resolveConfig = <TSchema extends Primitive.AnyPrimitive>(
   },
 });
 
+// =============================================================================
+// 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
 // =============================================================================
@@ -208,37 +233,148 @@ 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();
+
+      // 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),
@@ -257,7 +393,7 @@ export const make = <TSchema extends Primitive.AnyPrimitive>(
 
       return engine;
     })
-  ).pipe(Layer.provide(internalLayers));
+  ).pipe(Layer.provide(presenceManagerLayer));
 };
 
 // =============================================================================

package/src/PresenceManager.ts

@@ -106,30 +106,29 @@ export const layer: Layer.Layer<PresenceManagerTag> = Layer.effect(
     /**
      * Get or create presence state for a document
      */
-    const getOrCreateDocumentState = (
-      documentId: string
-    ): Effect.Effect<DocumentPresenceState> =>
-      Effect.gen(function* () {
-        const current = yield* Ref.get(store);
-        const existing = HashMap.get(current, documentId);
-        if (existing._tag === "Some") {
-          return existing.value;
-        }
-
-        // Create new state for this document
-        const pubsub = yield* PubSub.unbounded<PresenceEvent>();
-        const state: DocumentPresenceState = {
-          presences: HashMap.empty(),
-          pubsub,
-        };
-
-        yield* Ref.update(store, (map) => HashMap.set(map, documentId, state));
-        return state;
-      });
+    const getOrCreateDocumentState = Effect.fn(
+      "presence.document-state.get-or-create"
+    )(function* (documentId: string) {
+      const current = yield* Ref.get(store);
+      const existing = HashMap.get(current, documentId);
+      if (existing._tag === "Some") {
+        return existing.value;
+      }
+
+      // Create new state for this document
+      const pubsub = yield* PubSub.unbounded<PresenceEvent>();
+      const state: DocumentPresenceState = {
+        presences: HashMap.empty(),
+        pubsub,
+      };
+
+      yield* Ref.update(store, (map) => HashMap.set(map, documentId, state));
+      return state;
+    });
 
     return {
-      getSnapshot: (documentId) =>
-        Effect.gen(function* () {
+      getSnapshot: Effect.fn("presence.snapshot.get")(
+        function* (documentId: string) {
           const current = yield* Ref.get(store);
           const existing = HashMap.get(current, documentId);
           if (existing._tag === "None") {
@@ -142,10 +141,15 @@ export const layer: Layer.Layer<PresenceManagerTag> = Layer.effect(
             presences[id] = entry;
           }
           return { presences };
-        }),
-
-      set: (documentId, connectionId, entry) =>
-        Effect.gen(function* () {
+        }
+      ),
+
+      set: Effect.fn("presence.set")(
+        function* (
+          documentId: string,
+          connectionId: string,
+          entry: PresenceEntry
+        ) {
           const state = yield* getOrCreateDocumentState(documentId);
 
           // Update presence in store
@@ -174,16 +178,20 @@ export const layer: Layer.Layer<PresenceManagerTag> = Layer.effect(
             userId: entry.userId,
           };
           yield* PubSub.publish(state.pubsub, event);
-        }),
+        }
+      ),
 
-      remove: (documentId, connectionId) =>
-        Effect.gen(function* () {
+      remove: Effect.fn("presence.remove")(
+        function* (documentId: string, connectionId: string) {
           const current = yield* Ref.get(store);
           const existing = HashMap.get(current, documentId);
           if (existing._tag === "None") return;
 
           // Check if presence exists before removing
-          const hasPresence = HashMap.has(existing.value.presences, connectionId);
+          const hasPresence = HashMap.has(
+            existing.value.presences,
+            connectionId
+          );
           if (!hasPresence) return;
 
           // Remove presence from store
@@ -205,13 +213,15 @@ export const layer: Layer.Layer<PresenceManagerTag> = Layer.effect(
             id: connectionId,
           };
           yield* PubSub.publish(existing.value.pubsub, event);
-        }),
+        }
+      ),
 
-      subscribe: (documentId) =>
-        Effect.gen(function* () {
+      subscribe: Effect.fn("presence.subscribe")(
+        function* (documentId: string) {
           const state = yield* getOrCreateDocumentState(documentId);
           return Stream.fromPubSub(state.pubsub);
-        }),
+        }
+      ),
     };
   })
 );

package/src/index.ts

@@ -41,11 +41,10 @@ export * as Protocol from "./Protocol";
 // =============================================================================
 
 export {
-  DocumentManager,
-  DocumentManagerTag,
-  DocumentManagerConfigTag,
+  DocumentInstance,
+  type DocumentInstance as DocumentInstanceInterface,
   type SubmitResult,
-} from "./DocumentManager";
+} from "./DocumentInstance";
 
 export {
   PresenceManager,