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

package/src/MimicClusterServerEngine.ts

@@ -13,32 +13,30 @@ import {
   HashMap,
   Layer,
   Metric,
-  Option,
   PubSub,
   Ref,
+  Schedule,
   Schema,
-  Scope,
   Stream,
 } from "effect";
 import { Entity, Sharding } from "@effect/cluster";
 import { Rpc } from "@effect/rpc";
-import type { Presence, Primitive, Transaction } from "@voidhash/mimic";
-import { ServerDocument } from "@voidhash/mimic/server";
+import { type Primitive, type Transaction } from "@voidhash/mimic";
 import type {
   MimicClusterServerEngineConfig,
   PresenceEntry,
   PresenceEvent,
-  PresenceSnapshot,
   ResolvedClusterConfig,
-  StoredDocument,
-  WalEntry,
 } from "./Types";
 import type * as Protocol from "./Protocol";
 import { ColdStorageTag, type ColdStorage } from "./ColdStorage";
 import { HotStorageTag, type HotStorage } from "./HotStorage";
 import { MimicAuthServiceTag } from "./MimicAuthService";
 import { MimicServerEngineTag, type MimicServerEngine } from "./MimicServerEngine";
-import type { SubmitResult } from "./DocumentManager";
+import {
+  DocumentInstance,
+  type DocumentInstance as DocumentInstanceInterface,
+} from "./DocumentInstance";
 import * as Metrics from "./Metrics";
 
 // =============================================================================
@@ -49,6 +47,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);
 const DEFAULT_SHARD_GROUP = "mimic-documents";
 
 // =============================================================================
@@ -172,16 +171,12 @@ const MimicDocumentEntity = Entity.make("MimicDocument", [
 // =============================================================================
 
 /**
- * Document state managed by the entity
+ * Entity state that wraps DocumentInstance and adds presence management
  */
-interface EntityDocumentState<TSchema extends Primitive.AnyPrimitive> {
-  readonly document: ServerDocument.ServerDocument<TSchema>;
-  readonly broadcastPubSub: PubSub.PubSub<Protocol.ServerMessage>;
+interface EntityState<TSchema extends Primitive.AnyPrimitive> {
+  readonly instance: DocumentInstanceInterface<TSchema>;
   readonly presences: HashMap.HashMap<string, PresenceEntry>;
   readonly presencePubSub: PubSub.PubSub<PresenceEvent>;
-  readonly lastSnapshotVersion: number;
-  readonly lastSnapshotTime: number;
-  readonly transactionsSinceSnapshot: number;
 }
 
 // =============================================================================
@@ -216,6 +211,9 @@ const resolveClusterConfig = <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,
   },
   shardGroup: config.shardGroup ?? DEFAULT_SHARD_GROUP,
 });
@@ -257,258 +255,99 @@ const createEntityHandler = <TSchema extends Primitive.AnyPrimitive>(
   coldStorage: ColdStorage,
   hotStorage: HotStorage
 ) =>
-  Effect.gen(function* () {
+  Effect.fn("cluster.entity.handler.create")(function* () {
     // Get entity address to determine documentId
     const address = yield* Entity.CurrentAddress;
     const documentId = address.entityId;
 
-    // Current schema version (hard-coded to 1 for now)
-    const SCHEMA_VERSION = 1;
-
-    // Compute initial state
-    const computeInitialState = (): Effect.Effect<
-      Primitive.InferSetInput<TSchema> | undefined
-    > => {
-      if (config.initial === undefined) {
-        return Effect.succeed(undefined);
-      }
-
-      if (typeof config.initial === "function") {
-        return (
-          config.initial as (ctx: {
-            documentId: string;
-          }) => Effect.Effect<Primitive.InferSetInput<TSchema>>
-        )({ documentId });
-      }
-
-      return Effect.succeed(
-        config.initial as Primitive.InferSetInput<TSchema>
-      );
-    };
-
-    // Load snapshot from ColdStorage
-    const storedDoc = yield* Effect.catchAll(
-      coldStorage.load(documentId),
-      () => Effect.succeed(undefined)
-    );
-
-    let initialState: Primitive.InferSetInput<TSchema> | undefined;
-    let initialVersion = 0;
-
-    if (storedDoc) {
-      initialState =
-        storedDoc.state as Primitive.InferSetInput<TSchema>;
-      initialVersion = storedDoc.version;
-    } else {
-      initialState = yield* computeInitialState();
-    }
+    // Create DocumentInstance (fatal if unavailable - entity cannot start)
+    const instance = yield* DocumentInstance.make(
+      documentId,
+      {
+        schema: config.schema,
+        initial: config.initial,
+        maxTransactionHistory: config.maxTransactionHistory,
+        snapshot: config.snapshot,
+      },
+      coldStorage,
+      hotStorage
+    ).pipe(Effect.orDie);
 
-    // Create PubSubs for broadcasting
-    const broadcastPubSub = yield* PubSub.unbounded<Protocol.ServerMessage>();
+    // Create presence PubSub and state ref
     const presencePubSub = yield* PubSub.unbounded<PresenceEvent>();
-
-    // Create state ref
-    const stateRef = yield* Ref.make<EntityDocumentState<TSchema>>({
-      document: undefined as unknown as ServerDocument.ServerDocument<TSchema>,
-      broadcastPubSub,
+    const stateRef = yield* Ref.make<EntityState<TSchema>>({
+      instance,
       presences: HashMap.empty(),
       presencePubSub,
-      lastSnapshotVersion: initialVersion,
-      lastSnapshotTime: Date.now(),
-      transactionsSinceSnapshot: 0,
-    });
-
-    // Create ServerDocument with callbacks
-    const document = ServerDocument.make({
-      schema: config.schema,
-      initialState,
-      initialVersion,
-      maxTransactionHistory: config.maxTransactionHistory,
-      onBroadcast: (message: ServerDocument.TransactionMessage) => {
-        Effect.runSync(
-          PubSub.publish(broadcastPubSub, {
-            type: "transaction",
-            transaction: message.transaction,
-            version: message.version,
-          } as Protocol.ServerMessage)
-        );
-      },
-      onRejection: (transactionId: string, reason: string) => {
-        Effect.runSync(
-          PubSub.publish(broadcastPubSub, {
-            type: "error",
-            transactionId,
-            reason,
-          } as Protocol.ServerMessage)
-        );
-      },
-    });
-
-    // Update state with document
-    yield* Ref.update(stateRef, (s) => ({ ...s, document }));
-
-    // Replay WAL entries
-    const walEntries = yield* Effect.catchAll(
-      hotStorage.getEntries(documentId, initialVersion),
-      () => Effect.succeed([] as WalEntry[])
-    );
-
-    for (const entry of walEntries) {
-      const result = document.submit(entry.transaction);
-      if (!result.success) {
-        yield* Effect.logWarning("Skipping corrupted WAL entry", {
-          documentId,
-          version: entry.version,
-          reason: result.reason,
-        });
-      }
-    }
-
-    // Track metrics
-    if (storedDoc) {
-      yield* Metric.increment(Metrics.documentsRestored);
-    } else {
-      yield* Metric.increment(Metrics.documentsCreated);
-    }
-    yield* Metric.incrementBy(Metrics.documentsActive, 1);
-
-    /**
-     * Save snapshot to ColdStorage
-     */
-    const saveSnapshot = Effect.gen(function* () {
-      const state = yield* Ref.get(stateRef);
-      const docState = state.document.get();
-      const version = state.document.getVersion();
-
-      if (docState === undefined) {
-        return;
-      }
-
-      const storedDocument: StoredDocument = {
-        state: docState,
-        version,
-        schemaVersion: SCHEMA_VERSION,
-        savedAt: Date.now(),
-      };
-
-      const snapshotStartTime = Date.now();
-
-      yield* Effect.catchAll(
-        coldStorage.save(documentId, storedDocument),
-        (e) =>
-          Effect.logError("Failed to save snapshot", { documentId, error: e })
-      );
-
-      const snapshotDuration = Date.now() - snapshotStartTime;
-      yield* Metric.increment(Metrics.storageSnapshots);
-      yield* Metric.update(Metrics.storageSnapshotLatency, snapshotDuration);
-
-      yield* Effect.catchAll(hotStorage.truncate(documentId, version), (e) =>
-        Effect.logError("Failed to truncate WAL", { documentId, error: e })
-      );
-
-      yield* Ref.update(stateRef, (s) => ({
-        ...s,
-        lastSnapshotVersion: version,
-        lastSnapshotTime: Date.now(),
-        transactionsSinceSnapshot: 0,
-      }));
-    });
-
-    /**
-     * Check if snapshot should be triggered
-     */
-    const checkSnapshotTriggers = Effect.gen(function* () {
-      const state = yield* Ref.get(stateRef);
-      const now = Date.now();
-
-      const intervalMs = Duration.toMillis(config.snapshot.interval);
-      const threshold = config.snapshot.transactionThreshold;
-
-      if (state.transactionsSinceSnapshot >= threshold) {
-        yield* saveSnapshot;
-        return;
-      }
-
-      if (now - state.lastSnapshotTime >= intervalMs) {
-        yield* saveSnapshot;
-        return;
-      }
     });
 
     // Cleanup on entity finalization
     yield* Effect.addFinalizer(() =>
-      Effect.gen(function* () {
-        // Save final snapshot before entity is garbage collected
-        yield* saveSnapshot;
+      Effect.fn("cluster.entity.finalize")(function* () {
+        // Best effort save - don't fail shutdown if storage is unavailable
+        yield* Effect.catchAll(instance.saveSnapshot(), (e) =>
+          Effect.logError("Failed to save snapshot during entity finalization", {
+            documentId,
+            error: e,
+          })
+        );
         yield* Metric.incrementBy(Metrics.documentsActive, -1);
         yield* Metric.increment(Metrics.documentsEvicted);
         yield* Effect.logDebug("Entity finalized", { documentId });
-      })
+      })()
     );
 
-    // Return RPC handlers
-    return {
-      Submit: Effect.fnUntraced(function* ({ payload }) {
-        const submitStartTime = Date.now();
-        const state = yield* Ref.get(stateRef);
-
-        // Decode transaction
-        const transaction = decodeTransaction(payload.transaction);
-
-        // Submit to ServerDocument
-        const result = state.document.submit(transaction);
-
-        // Track latency
-        const latency = Date.now() - submitStartTime;
-        yield* Metric.update(Metrics.transactionsLatency, latency);
-
-        if (result.success) {
-          yield* Metric.increment(Metrics.transactionsProcessed);
-
-          // Append to WAL
-          const walEntry: WalEntry = {
-            transaction,
-            version: result.version,
-            timestamp: Date.now(),
-          };
-
-          yield* Effect.catchAll(hotStorage.append(documentId, walEntry), (e) =>
-            Effect.logError("Failed to append to WAL", {
+    // Start periodic snapshot fiber for this entity
+    const idleTimeoutMs = Duration.toMillis(config.snapshot.idleTimeout);
+    if (idleTimeoutMs > 0) {
+      const snapshotLoop = Effect.fn("cluster.entity.snapshot.loop")(function* () {
+        const needs = yield* instance.needsSnapshot();
+        if (needs) {
+          yield* Effect.catchAll(instance.saveSnapshot(), (e) =>
+            Effect.logWarning("Periodic snapshot failed in cluster entity", {
               documentId,
               error: e,
             })
           );
+          yield* Metric.increment(Metrics.storageIdleSnapshots);
+        }
+      });
 
-          yield* Metric.increment(Metrics.storageWalAppends);
-
-          // Increment transaction count
-          yield* Ref.update(stateRef, (s) => ({
-            ...s,
-            transactionsSinceSnapshot: s.transactionsSinceSnapshot + 1,
-          }));
+      // Run every idleTimeout
+      yield* snapshotLoop().pipe(
+        Effect.repeat(Schedule.spaced(config.snapshot.idleTimeout)),
+        Effect.fork
+      );
+    }
 
-          // Check snapshot triggers
-          yield* checkSnapshotTriggers;
-        } else {
-          yield* Metric.increment(Metrics.transactionsRejected);
-        }
+    // Return RPC handlers
+    return {
+      Submit: Effect.fn("cluster.document.transaction.submit")(function* ({
+        payload,
+      }) {
+        // Decode transaction
+        const transaction = decodeTransaction(payload.transaction);
 
-        return result;
+        // Use DocumentInstance's submit method, catching storage errors
+        return yield* instance.submit(transaction).pipe(
+          Effect.catchAll((error) =>
+            Effect.succeed({
+              success: false as const,
+              reason: `Storage error: ${String(error)}`,
+            })
+          )
+        );
       }),
 
-      GetSnapshot: Effect.fnUntraced(function* () {
-        const state = yield* Ref.get(stateRef);
-        return state.document.getSnapshot();
+      GetSnapshot: Effect.fn("cluster.document.snapshot.get")(function* () {
+        return instance.getSnapshot();
       }),
 
-      Touch: Effect.fnUntraced(function* () {
-        // Entity touch is handled automatically by the cluster framework
-        // Just update last activity time conceptually
-        return void 0;
+      Touch: Effect.fn("cluster.document.touch")(function* () {
+        yield* instance.touch();
       }),
 
-      SetPresence: Effect.fnUntraced(function* ({ payload }) {
+      SetPresence: Effect.fn("cluster.presence.set")(function* ({ payload }) {
         const { connectionId, entry } = payload;
 
         yield* Ref.update(stateRef, (s) => ({
@@ -529,7 +368,9 @@ const createEntityHandler = <TSchema extends Primitive.AnyPrimitive>(
         yield* PubSub.publish(state.presencePubSub, event);
       }),
 
-      RemovePresence: Effect.fnUntraced(function* ({ payload }) {
+      RemovePresence: Effect.fn("cluster.presence.remove")(function* ({
+        payload,
+      }) {
         const { connectionId } = payload;
         const state = yield* Ref.get(stateRef);
 
@@ -551,16 +392,18 @@ const createEntityHandler = <TSchema extends Primitive.AnyPrimitive>(
         yield* PubSub.publish(state.presencePubSub, event);
       }),
 
-      GetPresenceSnapshot: Effect.fnUntraced(function* () {
-        const state = yield* Ref.get(stateRef);
-        const presences: Record<string, PresenceEntry> = {};
-        for (const [id, entry] of state.presences) {
-          presences[id] = entry;
+      GetPresenceSnapshot: Effect.fn("cluster.presence.snapshot.get")(
+        function* () {
+          const state = yield* Ref.get(stateRef);
+          const presences: Record<string, PresenceEntry> = {};
+          for (const [id, entry] of state.presences) {
+            presences[id] = entry;
+          }
+          return { presences };
         }
-        return { presences };
-      }),
+      ),
     };
-  });
+  })();
 
 // =============================================================================
 // Subscription Store (for managing subscriptions at the gateway level)
@@ -585,7 +428,7 @@ class SubscriptionStoreTag extends Context.Tag(
 
 const subscriptionStoreLayer = Layer.effect(
   SubscriptionStoreTag,
-  Effect.gen(function* () {
+  Effect.fn("cluster.subscriptions.layer.create")(function* () {
     const documentPubSubs = yield* Ref.make(
       HashMap.empty<string, PubSub.PubSub<Protocol.ServerMessage>>()
     );
@@ -594,37 +437,39 @@ const subscriptionStoreLayer = Layer.effect(
     );
 
     return {
-      getOrCreatePubSub: (documentId: string) =>
-        Effect.gen(function* () {
-          const current = yield* Ref.get(documentPubSubs);
-          const existing = HashMap.get(current, documentId);
-          if (existing._tag === "Some") {
-            return existing.value;
-          }
+      getOrCreatePubSub: Effect.fn(
+        "cluster.subscriptions.pubsub.get-or-create"
+      )(function* (documentId: string) {
+        const current = yield* Ref.get(documentPubSubs);
+        const existing = HashMap.get(current, documentId);
+        if (existing._tag === "Some") {
+          return existing.value;
+        }
 
-          const pubsub = yield* PubSub.unbounded<Protocol.ServerMessage>();
-          yield* Ref.update(documentPubSubs, (map) =>
-            HashMap.set(map, documentId, pubsub)
-          );
-          return pubsub;
-        }),
-
-      getOrCreatePresencePubSub: (documentId: string) =>
-        Effect.gen(function* () {
-          const current = yield* Ref.get(presencePubSubs);
-          const existing = HashMap.get(current, documentId);
-          if (existing._tag === "Some") {
-            return existing.value;
-          }
+        const pubsub = yield* PubSub.unbounded<Protocol.ServerMessage>();
+        yield* Ref.update(documentPubSubs, (map) =>
+          HashMap.set(map, documentId, pubsub)
+        );
+        return pubsub;
+      }),
 
-          const pubsub = yield* PubSub.unbounded<PresenceEvent>();
-          yield* Ref.update(presencePubSubs, (map) =>
-            HashMap.set(map, documentId, pubsub)
-          );
-          return pubsub;
-        }),
+      getOrCreatePresencePubSub: Effect.fn(
+        "cluster.subscriptions.presence-pubsub.get-or-create"
+      )(function* (documentId: string) {
+        const current = yield* Ref.get(presencePubSubs);
+        const existing = HashMap.get(current, documentId);
+        if (existing._tag === "Some") {
+          return existing.value;
+        }
+
+        const pubsub = yield* PubSub.unbounded<PresenceEvent>();
+        yield* Ref.update(presencePubSubs, (map) =>
+          HashMap.set(map, documentId, pubsub)
+        );
+        return pubsub;
+      }),
     };
-  })
+  })()
 );
 
 // =============================================================================