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

package/src/MimicServer.ts

@@ -1,239 +1,500 @@
 /**
- * @since 0.0.1
- * Mimic server layer composition.
+ * @voidhash/mimic-effect - MimicServer
+ *
+ * WebSocket route layer for MimicServerEngine.
+ * Creates routes compatible with HttpLayerRouter.
  */
-import * as Effect from "effect/Effect";
-import * as Layer from "effect/Layer";
-import * as Context from "effect/Context";
+import {
+  Duration,
+  Effect,
+  Fiber,
+  Layer,
+  Metric,
+  Stream,
+} from "effect";
+import {
+  HttpLayerRouter,
+  HttpServerRequest,
+  HttpServerResponse,
+} from "@effect/platform";
 import type * as Socket from "@effect/platform/Socket";
-import { SocketServer } from "@effect/platform/SocketServer";
-import type { Primitive, Presence } from "@voidhash/mimic";
-
-import * as DocumentManager from "./DocumentManager.js";
-import * as WebSocketHandler from "./WebSocketHandler.js";
-import * as MimicConfig from "./MimicConfig.js";
-import { MimicDataStorageTag } from "./MimicDataStorage.js";
-import { MimicAuthServiceTag } from "./MimicAuthService.js";
-import * as PresenceManager from "./PresenceManager.js";
-import * as InMemoryDataStorage from "./storage/InMemoryDataStorage.js";
-import * as NoAuth from "./auth/NoAuth.js";
-import { HttpLayerRouter, HttpServerRequest, HttpServerResponse } from "@effect/platform";
-import { PathInput } from "@effect/platform/HttpRouter";
+import { Presence } from "@voidhash/mimic";
+import type { MimicServerRouteConfig, ResolvedRouteConfig } from "./Types";
+import * as Protocol from "./Protocol";
+import { MissingDocumentIdError } from "./Errors";
+import { MimicServerEngineTag, type MimicServerEngine } from "./MimicServerEngine";
+import { MimicAuthServiceTag, type MimicAuthService } from "./MimicAuthService";
+import * as Metrics from "./Metrics";
+import type { AuthContext } from "./Types";
 
 // =============================================================================
-// Layer Composition Options
+// Default Configuration
 // =============================================================================
 
+const DEFAULT_PATH = "/mimic";
+const DEFAULT_HEARTBEAT_INTERVAL = Duration.seconds(30);
+const DEFAULT_HEARTBEAT_TIMEOUT = Duration.seconds(10);
+
 /**
- * Options for creating a Mimic server layer.
+ * Resolve route configuration with defaults
  */
-export interface MimicLayerOptions<
-  TSchema extends Primitive.AnyPrimitive,
-> {
-  /**
-   * Base path for document routes (used for path matching).
-   * @example "/mimic/todo" - documents accessed at "/mimic/todo/:documentId"
-   */
-  readonly basePath?: PathInput;
-  /**
-   * The schema defining the document structure.
-   */
-  readonly schema: TSchema;
-  /**
-   * Maximum number of processed transaction IDs to track for deduplication.
-   * @default 1000
-   */
-  readonly maxTransactionHistory?: number;
-  /**
-   * Optional presence schema for ephemeral per-user data.
-   * When provided, enables presence features on WebSocket connections.
-   */
-  readonly presence?: Presence.AnyPresence;
-  /**
-   * Initial state for new documents.
-   * Can be either:
-   * - A plain object with the initial state values
-   * - A function that receives context (with documentId) and returns an Effect producing the initial state
-   *
-   * When using a function that requires Effect services (has R requirements),
-   * you must also provide `initialLayer` to supply those dependencies.
-   *
-   * Type-safe: required fields (without defaults) must be provided,
-   * while optional fields and fields with defaults can be omitted.
-   *
-   * @default undefined (documents start empty or use schema defaults)
-   */
-  readonly initial?: Primitive.InferSetInput<TSchema> | MimicConfig.InitialFn<TSchema>;
-}
+const resolveRouteConfig = (
+  config?: MimicServerRouteConfig
+): ResolvedRouteConfig => ({
+  path: config?.path ?? DEFAULT_PATH,
+  heartbeatInterval: config?.heartbeatInterval
+    ? Duration.decode(config.heartbeatInterval)
+    : DEFAULT_HEARTBEAT_INTERVAL,
+  heartbeatTimeout: config?.heartbeatTimeout
+    ? Duration.decode(config.heartbeatTimeout)
+    : DEFAULT_HEARTBEAT_TIMEOUT,
+});
 
+// =============================================================================
+// URL Path Parsing
+// =============================================================================
 
 /**
- * Create the document manager layer.
+ * Extract document ID from URL path.
+ * Expected format: /basePath/doc/{documentId}
  */
-export const documentManagerLayer = <TSchema extends Primitive.AnyPrimitive>(
-  options: MimicConfig.MimicServerConfigOptions<TSchema>
-): Layer.Layer<DocumentManager.DocumentManagerTag> =>
-  DocumentManager.layer.pipe(
-    Layer.provide(MimicConfig.layer(options)),
-    // Provide defaults
-    Layer.provide(InMemoryDataStorage.layerDefault),
-    Layer.provide(NoAuth.layerDefault)
-  );
+const extractDocumentId = (
+  path: string
+): Effect.Effect<string, MissingDocumentIdError> => {
+  // Remove leading slash and split
+  const parts = path.replace(/^\/+/, "").split("/");
+
+  // Find the last occurrence of 'doc' in the path
+  const docIndex = parts.lastIndexOf("doc");
+  const part = parts[docIndex + 1];
+  if (docIndex !== -1 && part) {
+    return Effect.succeed(decodeURIComponent(part));
+  }
+  return Effect.fail(new MissingDocumentIdError({ path }));
+};
+
+// =============================================================================
+// Connection State
+// =============================================================================
+
+interface ConnectionState {
+  readonly documentId: string;
+  readonly connectionId: string;
+  authenticated: boolean;
+  authContext?: AuthContext;
+  hasPresence: boolean;
+}
+
+// =============================================================================
+// WebSocket Connection Handler
+// =============================================================================
 
 /**
- * Create the HTTP handler effect for WebSocket upgrade.
- * This handler:
- * 1. Extracts the document ID from the URL path
- * 2. Upgrades the HTTP connection to WebSocket
- * 3. Delegates to the WebSocketHandler for document sync
+ * Handle a WebSocket connection for a document.
  */
-const makeMimicHandler = Effect.gen(function* () {
-  const config = yield* MimicConfig.MimicServerConfigTag;
-  const authService = yield* MimicAuthServiceTag;
-  const documentManager = yield* DocumentManager.DocumentManagerTag;
-  const presenceManager = yield* PresenceManager.PresenceManagerTag;
-
-  return Effect.gen(function* () {
-    const request = yield* HttpServerRequest.HttpServerRequest;
-
-    // Extract document ID from the URL path
-    // Expected format: /basePath/doc/{documentId}
-    const documentId = yield* WebSocketHandler.extractDocumentId(request.url);
-
-    // Upgrade to WebSocket
-    const socket = yield* request.upgrade;
-
-    // Handle the WebSocket connection
-    yield* WebSocketHandler.handleConnection(socket, request.url).pipe(
-      Effect.provideService(MimicConfig.MimicServerConfigTag, config),
-      Effect.provideService(MimicAuthServiceTag, authService),
-      Effect.provideService(DocumentManager.DocumentManagerTag, documentManager),
-      Effect.provideService(PresenceManager.PresenceManagerTag, presenceManager),
-      Effect.scoped,
-      Effect.catchAll((error) =>
-        Effect.logError("WebSocket connection error", error)
-      )
+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();
+
+    // Track connection metrics
+    yield* Metric.increment(Metrics.connectionsTotal);
+    yield* Metric.incrementBy(Metrics.connectionsActive, 1);
+
+    // Track connection state (mutable for simplicity)
+    const state: ConnectionState = {
+      documentId,
+      connectionId,
+      authenticated: false,
+      hasPresence: false,
+    };
+
+    // Get the socket writer
+    const write = yield* socket.writer;
+
+    // Helper to send a message to the client
+    const sendMessage = (message: Protocol.ServerMessage) =>
+      write(Protocol.encodeServerMessage(message));
+
+    // Send presence snapshot after auth
+    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)
+        );
+      }
     );
 
-    // Return empty response - the WebSocket upgrade handles the connection
-    return HttpServerResponse.empty();
-  }).pipe(
-    Effect.catchAll((error) =>
-      Effect.gen(function* () {
-        yield* Effect.logWarning("WebSocket upgrade failed", error);
-        return HttpServerResponse.text("WebSocket upgrade failed", {
-          status: 400,
+    // Send document snapshot after auth
+    const sendDocumentSnapshot = Effect.fn("document.snapshot.send")(
+      function* () {
+        const snapshot = yield* engine.getSnapshot(documentId);
+        yield* sendMessage(
+          Protocol.snapshotMessage(snapshot.state, snapshot.version)
+        );
+      }
+    );
+
+    // Handle authentication
+    const handleAuth = Effect.fn("auth.handle")(function* (token: string) {
+      const result = yield* Effect.either(
+        authService.authenticate(token, documentId)
+      );
+
+      if (result._tag === "Right") {
+        state.authenticated = true;
+        state.authContext = result.right;
+
+        yield* sendMessage(
+          Protocol.authResultSuccess(
+            result.right.userId,
+            result.right.permission
+          )
+        );
+
+        // 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 = Effect.fn("presence.set.handle")(
+      function* (data: unknown) {
+        if (!state.authenticated) return;
+        if (!state.authContext) return;
+        if (!engine.config.presence) return;
+
+        // Check write permission
+        if (state.authContext.permission !== "write") {
+          yield* Effect.logWarning("Presence set rejected - read-only user", {
+            connectionId,
+          });
+          return;
+        }
+
+        // Validate presence data against schema
+        const validated = Presence.validateSafe(engine.config.presence, data);
+        if (validated === undefined) {
+          yield* Effect.logWarning("Invalid presence data received", {
+            connectionId,
+            data,
+          });
+          return;
+        }
+
+        // Store in engine
+        yield* engine.setPresence(documentId, connectionId, {
+          data: validated,
+          userId: state.authContext.userId,
         });
-      })
-    )
-  );
-});
 
+        state.hasPresence = true;
+      }
+    );
 
+    // Handle presence clear
+    const handlePresenceClear = Effect.fn("presence.clear.handle")(
+      function* () {
+        if (!state.authenticated) return;
+        if (!engine.config.presence) return;
 
-/**
- * Options for layerHttpLayerRouter including optional custom layers.
- */
-export interface MimicLayerRouterOptions<TSchema extends Primitive.AnyPrimitive>
-  extends MimicLayerOptions<TSchema> {
-  /** Custom auth layer. Defaults to NoAuth (all connections allowed). */
-  readonly authLayer?: Layer.Layer<MimicAuthServiceTag>;
-  /** Custom storage layer. Defaults to InMemoryDataStorage. */
-  readonly storageLayer?: Layer.Layer<MimicDataStorageTag>;
-}
+        yield* engine.removePresence(documentId, connectionId);
+        state.hasPresence = false;
+      }
+    );
+
+    // Handle a client message
+    const handleMessage = Effect.fn("message.handle")(
+      function* (message: Protocol.ClientMessage) {
+        // Touch document on any activity (prevents idle GC)
+        yield* engine.touch(documentId);
+
+        switch (message.type) {
+          case "auth":
+            yield* handleAuth(message.token);
+            break;
+
+          case "ping":
+            yield* sendMessage(Protocol.pong());
+            break;
+
+          case "submit":
+            if (!state.authenticated) {
+              yield* sendMessage(
+                Protocol.errorMessage(
+                  message.transaction.id,
+                  "Not authenticated"
+                )
+              );
+              return;
+            }
+
+            // Check write permission
+            if (state.authContext?.permission !== "write") {
+              yield* sendMessage(
+                Protocol.errorMessage(
+                  message.transaction.id,
+                  "Write permission required"
+                )
+              );
+              return;
+            }
+
+            // Submit to the engine
+            const submitResult = yield* engine.submit(
+              documentId,
+              message.transaction
+            );
+
+            // If rejected, send error (success is broadcast to all)
+            if (!submitResult.success) {
+              yield* sendMessage(
+                Protocol.errorMessage(message.transaction.id, submitResult.reason)
+              );
+            }
+            break;
+
+          case "request_snapshot":
+            if (!state.authenticated) {
+              return;
+            }
+            const snapshot = yield* engine.getSnapshot(documentId);
+            yield* sendMessage(
+              Protocol.snapshotMessage(snapshot.state, snapshot.version)
+            );
+            break;
+
+          case "presence_set":
+            yield* handlePresenceSet(message.data);
+            break;
+
+          case "presence_clear":
+            yield* handlePresenceClear();
+            break;
+        }
+      }
+    );
+
+    // Subscribe to document broadcasts
+    const subscribeFiber = yield* Effect.fork(
+      Effect.fn("subscriptions.document.start")(function* () {
+        // Wait until authenticated before subscribing
+        while (!state.authenticated) {
+          yield* Effect.sleep(Duration.millis(100));
+        }
+
+        // Subscribe to the document
+        const broadcastStream = yield* engine.subscribe(documentId);
+
+        // Forward broadcasts to the WebSocket
+        yield* Stream.runForEach(broadcastStream, (broadcast) =>
+          sendMessage(broadcast as Protocol.ServerMessage)
+        );
+      })().pipe(Effect.scoped)
+    );
+
+    // Subscribe to presence events (if presence is enabled)
+    const presenceFiber = yield* Effect.fork(
+      Effect.fn("subscriptions.presence.start")(function* () {
+        if (!engine.config.presence) return;
+
+        // Wait until authenticated before subscribing
+        while (!state.authenticated) {
+          yield* Effect.sleep(Duration.millis(100));
+        }
+
+        // Subscribe to presence events
+        const presenceStream = yield* engine.subscribePresence(documentId);
+
+        // Forward presence events to the WebSocket, filtering out our own events (no-echo)
+        yield* Stream.runForEach(presenceStream, (event) =>
+          Effect.gen(function* () {
+            // Don't echo our own presence events
+            if (event.id === connectionId) return;
+
+            if (event.type === "presence_update") {
+              yield* sendMessage(
+                Protocol.presenceUpdateMessage(event.id, event.data, event.userId)
+              );
+            } else if (event.type === "presence_remove") {
+              yield* sendMessage(Protocol.presenceRemoveMessage(event.id));
+            }
+          })
+        );
+      })().pipe(Effect.scoped)
+    );
+
+    // Ensure cleanup on disconnect
+    yield* Effect.addFinalizer(() =>
+      Effect.fn("connection.cleanup")(function* () {
+        // Calculate connection duration
+        const duration = Date.now() - connectionStartTime;
+
+        // Interrupt the subscribe fibers
+        yield* Fiber.interrupt(subscribeFiber);
+        yield* Fiber.interrupt(presenceFiber);
+
+        // Remove presence if we had any
+        if (state.hasPresence && engine.config.presence) {
+          yield* engine.removePresence(documentId, connectionId);
+        }
+
+        // Update connection metrics
+        yield* Metric.incrementBy(Metrics.connectionsActive, -1);
+        yield* Metric.update(Metrics.connectionsDuration, duration);
+
+        yield* Effect.logDebug("WebSocket connection closed", {
+          connectionId,
+          documentId,
+          durationMs: duration,
+        });
+      })()
+    );
+
+    // Process incoming messages
+    yield* socket.runRaw((data) =>
+      Effect.fn("message.process")(function* () {
+        const message = yield* Protocol.parseClientMessage(data);
+        yield* handleMessage(message);
+      })().pipe(
+        Effect.catchAll((error) =>
+          Effect.logError("Message handling error", error)
+        )
+      )
+    );
+  }
+);
+
+// =============================================================================
+// Factory
+// =============================================================================
 
 /**
- * Create a Mimic server layer that integrates with HttpLayerRouter.
- *
- * This function creates a layer that:
- * 1. Registers a WebSocket route at the specified base path
- * 2. Handles WebSocket upgrades for document sync
- * 3. Provides all required dependencies (config, auth, storage, document manager)
+ * Create a route layer for MimicServerEngine.
  *
- * By default, uses in-memory storage and no authentication.
- * To override these defaults, provide custom layers before the defaults:
+ * This creates a WebSocket route that connects to the engine.
+ * Use Layer.mergeAll to compose with other routes.
  *
  * @example
  * ```typescript
- * import { MimicServer, MimicAuthService } from "@voidhash/mimic-effect";
- * import { HttpLayerRouter } from "@effect/platform";
- * import { Primitive } from "@voidhash/mimic";
+ * // 1. Create the engine
+ * const Engine = MimicServerEngine.make({
+ *   schema: DocSchema,
+ *   initial: { title: "Untitled" },
+ * })
  *
- * const TodoSchema = Primitive.Struct({
- *   title: Primitive.String(),
- *   completed: Primitive.Boolean(),
- * });
- *
- * // Create the Mimic route layer with defaults
+ * // 2. Create the WebSocket route
  * const MimicRoute = MimicServer.layerHttpLayerRouter({
- *   basePath: "/mimic/todo",
- *   schema: TodoSchema
- * });
+ *   path: "/mimic",
+ * })
+ *
+ * // 3. Wire together
+ * const MimicLive = MimicRoute.pipe(
+ *   Layer.provide(Engine),
+ *   Layer.provide(ColdStorage.InMemory.make()),
+ *   Layer.provide(HotStorage.InMemory.make()),
+ *   Layer.provide(MimicAuthService.NoAuth.make()),
+ * )
  *
- * // Or with custom auth - use Layer.provide to inject before defaults
- * const MimicRouteWithAuth = MimicServer.layerHttpLayerRouter({
- *   basePath: "/mimic/todo",
- *   schema: TodoSchema,
- *   authLayer: MimicAuthService.layer({
- *     authHandler: (token) => ({ success: true, userId: token })
- *   })
- * });
+ * // 4. Compose with other routes
+ * const AllRoutes = Layer.mergeAll(MimicLive, DocsRoute, OtherRoutes)
  *
- * // Merge with other routes and serve
- * const AllRoutes = Layer.mergeAll(MimicRoute, OtherRoutes);
+ * // 5. Serve
  * HttpLayerRouter.serve(AllRoutes).pipe(
- *   Layer.provide(BunHttpServer.layer({ port: 3000 })),
+ *   Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })),
  *   Layer.launch,
- *   BunRuntime.runMain
- * );
+ *   NodeRuntime.runMain
+ * )
  * ```
  */
-export const layerHttpLayerRouter = <
-  TSchema extends Primitive.AnyPrimitive,
-  TError,
-  TRequirements
->(
-  optionsEf: Effect.Effect<MimicLayerRouterOptions<TSchema>, TError, TRequirements>
-): Layer.Layer<never, TError, TRequirements | HttpLayerRouter.HttpRouter> => {
-  return Layer.unwrapScoped(
+export const layerHttpLayerRouter = (
+  options?: MimicServerRouteConfig
+) => {
+  const routeConfig = resolveRouteConfig(options);
+
+  // Build the route path pattern: {path}/doc/:documentId
+  const routePath =
+    `${routeConfig.path}/doc/:documentId` as HttpLayerRouter.PathInput;
+
+  return Layer.scopedDiscard(
     Effect.gen(function* () {
-      const options = yield* optionsEf;
-
-      // Build the base path pattern for WebSocket routes
-      // Append /doc/* to match /basePath/doc/{documentId}
-      const basePath = options.basePath ?? "/mimic";
-      const wsPath: PathInput = `${basePath}/doc/*` as PathInput;
-
-      // Create the config layer with properly typed initial function
-      const configLayer = MimicConfig.layer<TSchema>({
-        schema: options.schema,
-        maxTransactionHistory: options.maxTransactionHistory,
-        presence: options.presence,
-        initial: options.initial,
-      });
-
-      // Use provided layers or defaults
-      const authLayer = options.authLayer ?? NoAuth.layerDefault;
-      const storageLayer = options.storageLayer ?? InMemoryDataStorage.layerDefault;
-
-      // Combine all dependency layers
-      const depsLayer = Layer.mergeAll(configLayer, authLayer, storageLayer);
-
-      // Create the route registration layer
-      const routeLayer = Layer.scopedDiscard(
-        Effect.gen(function* () {
-          const router = yield* HttpLayerRouter.HttpRouter;
-          const handler = yield* makeMimicHandler;
-          yield* router.add("GET", wsPath, handler);
-        })
-      );
+      const router = yield* HttpLayerRouter.HttpRouter;
+      // Capture engine and auth service at layer creation time
+      const engine = yield* MimicServerEngineTag;
+      const authService = yield* MimicAuthServiceTag;
+
+      // Create the handler that receives the request
+      // Engine and authService are captured in closure, not yielded per-request
+      const handler = Effect.fn("websocket.route.handler")(
+        function* (request: HttpServerRequest.HttpServerRequest) {
+          // Extract document ID from path
+          const documentIdResult = yield* Effect.either(
+            extractDocumentId(request.url)
+          );
+          if (documentIdResult._tag === "Left") {
+            return HttpServerResponse.text(
+              `Missing document ID in path: ${request.url}`,
+              { status: 400 }
+            );
+          }
+          const documentId = documentIdResult.right;
 
-      // Build the complete layer with all dependencies provided
-      return routeLayer.pipe(
-        Layer.provide(DocumentManager.layer),
-        Layer.provide(PresenceManager.layer),
-        Layer.provide(depsLayer),
+          // Upgrade to WebSocket
+          const socket = yield* request.upgrade;
+
+          // Handle the WebSocket connection
+          yield* handleWebSocketConnection(
+            socket,
+            documentId,
+            engine,
+            authService,
+            routeConfig
+          ).pipe(
+            Effect.scoped,
+            Effect.catchAll((error) =>
+              Effect.logError("WebSocket connection error", error)
+            )
+          );
+
+          // Return empty response - the WebSocket upgrade handles the connection
+          return HttpServerResponse.empty();
+        }
       );
+
+      yield* router.add("GET", routePath, handler);
     })
   );
-};
+};
+
+// =============================================================================
+// Re-export namespace
+// =============================================================================
+
+export const MimicServer = {
+  layerHttpLayerRouter,
+};
+
+// =============================================================================
+// Re-export types
+// =============================================================================
+
+export type { MimicServerRouteConfig };