@voidhash/mimic-effect 0.0.1-alpha.1

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@voidhash/mimic-effect",
+  "version": "0.0.1-alpha.1",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/voidhashcom/mimic",
+    "directory": "packages/mimic-server-effect"
+  },
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./DocumentManager": "./src/DocumentManager.ts",
+    "./DocumentProtocol": "./src/DocumentProtocol.ts",
+    "./WebSocketHandler": "./src/WebSocketHandler.ts",
+    "./MimicServer": "./src/MimicServer.ts",
+    "./MimicConfig": "./src/MimicConfig.ts"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "lint": "biome check .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run -c vitest.mts"
+  },
+  "dependencies": {
+    "@effect/platform": "^0.93.8"
+  },
+  "devDependencies": {
+    "@effect/vitest": "^0.26.0",
+    "@voidhash/tsconfig": "workspace:*",
+    "tsdown": "^0.18.2",
+    "typescript": "5.8.3",
+    "vite-tsconfig-paths": "^5.1.4",
+    "vitest": "^3.2.4"
+  },
+  "peerDependencies": {
+    "effect": "catalog:",
+    "@voidhash/mimic": "workspace:*"
+  }
+}

package/src/DocumentManager.ts

@@ -0,0 +1,252 @@
+/**
+ * @since 0.0.1
+ * Document manager that handles multiple document instances.
+ */
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as PubSub from "effect/PubSub";
+import * as Ref from "effect/Ref";
+import * as HashMap from "effect/HashMap";
+import * as Context from "effect/Context";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import type { Primitive, Transaction } from "@voidhash/mimic";
+import { ServerDocument } from "@voidhash/mimic/server";
+
+import * as Protocol from "./DocumentProtocol.js";
+import { MimicServerConfigTag } from "./MimicConfig.js";
+import { MimicDataStorageTag } from "./MimicDataStorage.js";
+import { DocumentNotFoundError } from "./errors.js";
+
+// =============================================================================
+// Document Instance
+// =============================================================================
+
+/**
+ * A managed document instance that holds state and manages subscribers.
+ */
+interface DocumentInstance {
+  /** The underlying ServerDocument */
+  readonly document: ServerDocument.ServerDocument<Primitive.AnyPrimitive>;
+  /** PubSub for broadcasting messages to subscribers */
+  readonly pubsub: PubSub.PubSub<Protocol.ServerBroadcast>;
+  /** Reference count for cleanup */
+  readonly refCount: Ref.Ref<number>;
+}
+
+// =============================================================================
+// Document Manager Service
+// =============================================================================
+
+/**
+ * Service interface for the DocumentManager.
+ */
+export interface DocumentManager {
+  /**
+   * Submit a transaction to a document.
+   */
+  readonly submit: (
+    documentId: string,
+    transaction: Transaction.Transaction
+  ) => Effect.Effect<Protocol.SubmitResult>;
+
+  /**
+   * Get a snapshot of a document.
+   */
+  readonly getSnapshot: (
+    documentId: string
+  ) => Effect.Effect<Protocol.SnapshotMessage>;
+
+  /**
+   * Subscribe to broadcasts for a document.
+   * Returns a Stream of server broadcasts.
+   */
+  readonly subscribe: (
+    documentId: string
+  ) => Effect.Effect<
+    Stream.Stream<Protocol.ServerBroadcast>,
+    never,
+    Scope.Scope
+  >;
+}
+
+/**
+ * Context tag for DocumentManager.
+ */
+export class DocumentManagerTag extends Context.Tag(
+  "@voidhash/mimic-server-effect/DocumentManager"
+)<DocumentManagerTag, DocumentManager>() {}
+
+// =============================================================================
+// Document Manager Implementation
+// =============================================================================
+
+/**
+ * Create the DocumentManager service.
+ */
+const makeDocumentManager = Effect.gen(function* () {
+  const config = yield* MimicServerConfigTag;
+  const storage = yield* MimicDataStorageTag;
+  
+  // Map of document ID to document instance
+  const documents = yield* Ref.make(
+    HashMap.empty<string, DocumentInstance>()
+  );
+
+  // Get or create a document instance
+  const getOrCreateDocument = (
+    documentId: string
+  ): Effect.Effect<DocumentInstance> =>
+    Effect.gen(function* () {
+      const current = yield* Ref.get(documents);
+      const existing = HashMap.get(current, documentId);
+
+      if (existing._tag === "Some") {
+        // Increment ref count
+        yield* Ref.update(existing.value.refCount, (n) => n + 1);
+        return existing.value;
+      }
+
+      // Load initial state from storage
+      const rawState = yield* Effect.catchAll(
+        storage.load(documentId),
+        () => Effect.succeed(undefined)
+      );
+
+      // Transform loaded state with onLoad hook
+      const initialState = rawState !== undefined
+        ? yield* storage.onLoad(rawState)
+        : undefined;
+
+      // Create PubSub for broadcasting
+      const pubsub = yield* PubSub.unbounded<Protocol.ServerBroadcast>();
+
+      // Create ServerDocument with broadcast callback
+      const serverDocument = ServerDocument.make({
+        schema: config.schema,
+        initialState: initialState as Primitive.InferState<typeof config.schema> | undefined,
+        maxTransactionHistory: config.maxTransactionHistory,
+        onBroadcast: (transactionMessage) => {
+          // Get current state and save to storage
+          const currentState = serverDocument.get();
+          
+          // Run save in background (fire-and-forget with error logging)
+          Effect.runFork(
+            Effect.gen(function* () {
+              if (currentState !== undefined) {
+                const transformedState = yield* storage.onSave(currentState);
+                yield* Effect.catchAll(
+                  storage.save(documentId, transformedState),
+                  (error) => Effect.logError("Failed to save document", error)
+                );
+              }
+            })
+          );
+
+          // Broadcast to subscribers
+          Effect.runSync(
+            PubSub.publish(pubsub, {
+              type: "transaction",
+              transaction: transactionMessage.transaction as Protocol.Transaction,
+              version: transactionMessage.version,
+            })
+          );
+        },
+        onRejection: (transactionId, reason) => {
+          Effect.runSync(
+            PubSub.publish(pubsub, {
+              type: "error",
+              transactionId,
+              reason,
+            })
+          );
+        },
+      });
+
+      const refCount = yield* Ref.make(1);
+
+      const instance: DocumentInstance = {
+        document: serverDocument,
+        pubsub,
+        refCount,
+      };
+
+      // Store in map
+      yield* Ref.update(documents, (map) =>
+        HashMap.set(map, documentId, instance)
+      );
+
+      return instance;
+    });
+
+  // Submit a transaction
+  const submit = (
+    documentId: string,
+    transaction: Transaction.Transaction
+  ): Effect.Effect<Protocol.SubmitResult> =>
+    Effect.gen(function* () {
+      const instance = yield* getOrCreateDocument(documentId);
+      const result = instance.document.submit(transaction);
+      return result;
+    });
+
+  // Get a snapshot
+  const getSnapshot = (
+    documentId: string
+  ): Effect.Effect<Protocol.SnapshotMessage> =>
+    Effect.gen(function* () {
+      const instance = yield* getOrCreateDocument(documentId);
+      const snapshot = instance.document.getSnapshot();
+      return snapshot;
+    });
+
+  // Subscribe to broadcasts
+  const subscribe = (
+    documentId: string
+  ): Effect.Effect<
+    Stream.Stream<Protocol.ServerBroadcast>,
+    never,
+    Scope.Scope
+  > =>
+    Effect.gen(function* () {
+      const instance = yield* getOrCreateDocument(documentId);
+
+      // Subscribe to the PubSub
+      const queue = yield* PubSub.subscribe(instance.pubsub);
+
+      // Ensure cleanup on scope close
+      yield* Effect.addFinalizer(() =>
+        Effect.gen(function* () {
+          // Decrement ref count
+          const count = yield* Ref.updateAndGet(
+            instance.refCount,
+            (n) => n - 1
+          );
+
+          // If no more subscribers, we could clean up the document
+          // For now, we keep it alive (could add idle timeout)
+        })
+      );
+
+      // Convert queue to stream
+      return Stream.fromQueue(queue);
+    });
+
+  const manager: DocumentManager = {
+    submit,
+    getSnapshot,
+    subscribe,
+  };
+
+  return manager;
+});
+
+/**
+ * Layer that provides DocumentManager.
+ * Requires MimicServerConfigTag and MimicDataStorageTag.
+ */
+export const layer: Layer.Layer<
+  DocumentManagerTag,
+  never,
+  MimicServerConfigTag | MimicDataStorageTag
+> = Layer.effect(DocumentManagerTag, makeDocumentManager);

package/src/DocumentProtocol.ts

@@ -0,0 +1,112 @@
+/**
+ * @since 0.0.1
+ * Protocol and schema definitions for document communication.
+ */
+import * as Schema from "effect/Schema";
+
+// =============================================================================
+// Schema Definitions
+// =============================================================================
+
+/**
+ * Schema for a transaction operation.
+ */
+export const OperationSchema = Schema.Struct({
+  kind: Schema.String,
+  path: Schema.Unknown, // OperationPath is complex, treat as unknown
+  payload: Schema.Unknown,
+});
+
+/**
+ * Schema for a transaction.
+ */
+export const TransactionSchema = Schema.Struct({
+  id: Schema.String,
+  ops: Schema.Array(OperationSchema),
+  timestamp: Schema.Number,
+});
+
+export type Transaction = Schema.Schema.Type<typeof TransactionSchema>;
+
+/**
+ * Schema for a server message that broadcasts a committed transaction.
+ */
+export const TransactionMessageSchema = Schema.Struct({
+  type: Schema.Literal("transaction"),
+  transaction: TransactionSchema,
+  version: Schema.Number,
+});
+
+export type TransactionMessage = Schema.Schema.Type<typeof TransactionMessageSchema>;
+
+/**
+ * Schema for a server message containing a snapshot.
+ */
+export const SnapshotMessageSchema = Schema.Struct({
+  type: Schema.Literal("snapshot"),
+  state: Schema.Unknown,
+  version: Schema.Number,
+});
+
+export type SnapshotMessage = Schema.Schema.Type<typeof SnapshotMessageSchema>;
+
+/**
+ * Schema for a server error message.
+ */
+export const ErrorMessageSchema = Schema.Struct({
+  type: Schema.Literal("error"),
+  transactionId: Schema.String,
+  reason: Schema.String,
+});
+
+export type ErrorMessage = Schema.Schema.Type<typeof ErrorMessageSchema>;
+
+/**
+ * Schema for a pong message.
+ */
+export const PongMessageSchema = Schema.Struct({
+  type: Schema.Literal("pong"),
+});
+
+export type PongMessage = Schema.Schema.Type<typeof PongMessageSchema>;
+
+/**
+ * Schema for authentication result message.
+ */
+export const AuthResultMessageSchema = Schema.Struct({
+  type: Schema.Literal("auth_result"),
+  success: Schema.Boolean,
+  error: Schema.optional(Schema.String),
+});
+
+export type AuthResultMessage = Schema.Schema.Type<typeof AuthResultMessageSchema>;
+
+/**
+ * Union of all server broadcast messages.
+ */
+export const ServerBroadcastSchema = Schema.Union(
+  TransactionMessageSchema,
+  ErrorMessageSchema
+);
+
+export type ServerBroadcast = Schema.Schema.Type<typeof ServerBroadcastSchema>;
+
+// =============================================================================
+// Submit Result
+// =============================================================================
+
+/**
+ * Result of submitting a transaction.
+ */
+export const SubmitResultSchema = Schema.Union(
+  Schema.Struct({
+    success: Schema.Literal(true),
+    version: Schema.Number,
+  }),
+  Schema.Struct({
+    success: Schema.Literal(false),
+    reason: Schema.String,
+  })
+);
+
+export type SubmitResult = Schema.Schema.Type<typeof SubmitResultSchema>;

package/src/MimicAuthService.ts

@@ -0,0 +1,103 @@
+/**
+ * @since 0.0.1
+ * Authentication service interface for Mimic connections.
+ * Provides pluggable authentication adapters.
+ */
+import * as Effect from "effect/Effect";
+import * as Context from "effect/Context";
+import * as Layer from "effect/Layer";
+
+// =============================================================================
+// Authentication Types
+// =============================================================================
+
+/**
+ * Result of an authentication attempt.
+ */
+export type AuthResult =
+  | { readonly success: true; readonly userId?: string }
+  | { readonly success: false; readonly error: string };
+
+/**
+ * Authentication handler function type.
+ * Can be synchronous or return a Promise.
+ */
+export type AuthHandler = (token: string) => Promise<AuthResult> | AuthResult;
+
+// =============================================================================
+// Auth Service Interface
+// =============================================================================
+
+/**
+ * Authentication service interface.
+ * Implementations can authenticate connections using various methods (JWT, API keys, etc.)
+ */
+export interface MimicAuthService {
+  /**
+   * Authenticate a connection using the provided token.
+   * @param token - The authentication token provided by the client
+   * @returns The authentication result
+   */
+  readonly authenticate: (token: string) => Effect.Effect<AuthResult>;
+}
+
+// =============================================================================
+// Context Tag
+// =============================================================================
+
+/**
+ * Context tag for MimicAuthService service.
+ */
+export class MimicAuthServiceTag extends Context.Tag(
+  "@voidhash/mimic-server-effect/MimicAuthService"
+)<MimicAuthServiceTag, MimicAuthService>() {}
+
+// =============================================================================
+// Layer Constructors
+// =============================================================================
+
+/**
+ * Create a MimicAuthService layer from an auth handler function.
+ */
+export const layer = (options: {
+  readonly authHandler: AuthHandler;
+}): Layer.Layer<MimicAuthServiceTag> =>
+  Layer.succeed(MimicAuthServiceTag, {
+    authenticate: (token: string) =>
+      Effect.promise(() => Promise.resolve(options.authHandler(token))),
+  });
+
+/**
+ * Create a MimicAuthService layer from an auth service implementation.
+ */
+export const layerService = (service: MimicAuthService): Layer.Layer<MimicAuthServiceTag> =>
+  Layer.succeed(MimicAuthServiceTag, service);
+
+/**
+ * Create a MimicAuthService layer from an Effect that produces an auth service.
+ */
+export const layerEffect = <E, R>(
+  effect: Effect.Effect<MimicAuthService, E, R>
+): Layer.Layer<MimicAuthServiceTag, E, R> =>
+  Layer.effect(MimicAuthServiceTag, effect);
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Create an auth service from an auth handler function.
+ */
+export const make = (authHandler: AuthHandler): MimicAuthService => ({
+  authenticate: (token: string) =>
+    Effect.promise(() => Promise.resolve(authHandler(token))),
+});
+
+/**
+ * Create an auth service from an Effect-based authenticate function.
+ */
+export const makeEffect = (
+  authenticate: (token: string) => Effect.Effect<AuthResult>
+): MimicAuthService => ({
+  authenticate,
+});

package/src/MimicConfig.ts

@@ -0,0 +1,131 @@
+/**
+ * @since 0.0.1
+ * Configuration types for the Mimic server.
+ */
+import * as Context from "effect/Context";
+import * as Duration from "effect/Duration";
+import type { DurationInput } from "effect/Duration";
+import * as Layer from "effect/Layer";
+import type { Primitive, Presence } from "@voidhash/mimic";
+
+// =============================================================================
+// Mimic Server Configuration
+// =============================================================================
+
+/**
+ * Configuration for the Mimic server.
+ * 
+ * Note: Authentication and persistence are now handled by injectable services
+ * (MimicAuthService and MimicDataStorage) rather than config options.
+ */
+export interface MimicServerConfig<TSchema extends Primitive.AnyPrimitive = Primitive.AnyPrimitive> {
+  /**
+   * The schema defining the document structure.
+   */
+  readonly schema: TSchema;
+
+  /**
+   * Maximum idle time for a document before it is cleaned up.
+   * @default "5 minutes"
+   */
+  readonly maxIdleTime: Duration.Duration;
+
+  /**
+   * Maximum number of processed transaction IDs to track for deduplication.
+   * @default 1000
+   */
+  readonly maxTransactionHistory: number;
+
+  /**
+   * Heartbeat interval for WebSocket connections.
+   * @default "30 seconds"
+   */
+  readonly heartbeatInterval: Duration.Duration;
+
+  /**
+   * Timeout for heartbeat responses before considering connection dead.
+   * @default "10 seconds"
+   */
+  readonly heartbeatTimeout: Duration.Duration;
+
+  /**
+   * Optional presence schema for ephemeral per-user data.
+   * When provided, enables presence features on WebSocket connections.
+   * @default undefined (presence disabled)
+   */
+  readonly presence: Presence.AnyPresence | undefined;
+}
+
+/**
+ * Options for creating a MimicServerConfig.
+ */
+export interface MimicServerConfigOptions<TSchema extends Primitive.AnyPrimitive = Primitive.AnyPrimitive> {
+  /**
+   * The schema defining the document structure.
+   */
+  readonly schema: TSchema;
+
+  /**
+   * Maximum idle time for a document before it is cleaned up.
+   * @default "5 minutes"
+   */
+  readonly maxIdleTime?: DurationInput;
+
+  /**
+   * Maximum number of processed transaction IDs to track for deduplication.
+   * @default 1000
+   */
+  readonly maxTransactionHistory?: number;
+
+  /**
+   * Heartbeat interval for WebSocket connections.
+   * @default "30 seconds"
+   */
+  readonly heartbeatInterval?: DurationInput;
+
+  /**
+   * Timeout for heartbeat responses.
+   * @default "10 seconds"
+   */
+  readonly heartbeatTimeout?: DurationInput;
+
+  /**
+   * Optional presence schema for ephemeral per-user data.
+   * When provided, enables presence features on WebSocket connections.
+   * @default undefined (presence disabled)
+   */
+  readonly presence?: Presence.AnyPresence;
+}
+
+/**
+ * Create a MimicServerConfig from options.
+ */
+export const make = <TSchema extends Primitive.AnyPrimitive>(
+  options: MimicServerConfigOptions<TSchema>
+): MimicServerConfig<TSchema> => ({
+  schema: options.schema,
+  maxIdleTime: Duration.decode(options.maxIdleTime ?? "5 minutes"),
+  maxTransactionHistory: options.maxTransactionHistory ?? 1000,
+  heartbeatInterval: Duration.decode(options.heartbeatInterval ?? "30 seconds"),
+  heartbeatTimeout: Duration.decode(options.heartbeatTimeout ?? "10 seconds"),
+  presence: options.presence,
+});
+
+// =============================================================================
+// Context Tag
+// =============================================================================
+
+/**
+ * Context tag for MimicServerConfig.
+ */
+export class MimicServerConfigTag extends Context.Tag(
+  "@voidhash/mimic-server-effect/MimicServerConfig"
+)<MimicServerConfigTag, MimicServerConfig>() {}
+
+/**
+ * Create a Layer that provides MimicServerConfig.
+ */
+export const layer = <TSchema extends Primitive.AnyPrimitive>(
+  options: MimicServerConfigOptions<TSchema>
+): Layer.Layer<MimicServerConfigTag> =>
+  Layer.succeed(MimicServerConfigTag, make(options));