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

package/src/Errors.ts

@@ -0,0 +1,100 @@
+/**
+ * @voidhash/mimic-effect - Error Types
+ *
+ * All error types used throughout the mimic-effect package.
+ */
+import { Data } from "effect";
+
+// =============================================================================
+// Storage Errors
+// =============================================================================
+
+/**
+ * Error when ColdStorage (snapshot storage) operations fail
+ */
+export class ColdStorageError extends Data.TaggedError("ColdStorageError")<{
+  readonly documentId: string;
+  readonly operation: "load" | "save" | "delete";
+  readonly cause: unknown;
+}> {}
+
+/**
+ * Error when HotStorage (WAL storage) operations fail
+ */
+export class HotStorageError extends Data.TaggedError("HotStorageError")<{
+  readonly documentId: string;
+  readonly operation: "append" | "getEntries" | "truncate";
+  readonly cause: unknown;
+}> {}
+
+// =============================================================================
+// Auth Errors
+// =============================================================================
+
+/**
+ * Error when authentication fails (invalid token, expired, etc.)
+ */
+export class AuthenticationError extends Data.TaggedError(
+  "AuthenticationError"
+)<{
+  readonly reason: string;
+}> {}
+
+/**
+ * Error when authorization fails (user doesn't have required permission)
+ */
+export class AuthorizationError extends Data.TaggedError("AuthorizationError")<{
+  readonly reason: string;
+  readonly required: "read" | "write";
+  readonly actual: "read" | "write";
+}> {}
+
+// =============================================================================
+// Connection Errors
+// =============================================================================
+
+/**
+ * Error when document ID is missing from WebSocket request path
+ */
+export class MissingDocumentIdError extends Data.TaggedError(
+  "MissingDocumentIdError"
+)<{
+  readonly path: string;
+}> {}
+
+/**
+ * Error when WebSocket message cannot be parsed
+ */
+export class MessageParseError extends Data.TaggedError("MessageParseError")<{
+  readonly cause: unknown;
+}> {}
+
+// =============================================================================
+// Transaction Errors
+// =============================================================================
+
+/**
+ * Error when a transaction is rejected by the document
+ */
+export class TransactionRejectedError extends Data.TaggedError(
+  "TransactionRejectedError"
+)<{
+  readonly transactionId: string;
+  readonly reason: string;
+}> {}
+
+// =============================================================================
+// Union Type
+// =============================================================================
+
+/**
+ * Union of all mimic-effect errors
+ */
+export type MimicError =
+  | ColdStorageError
+  | HotStorageError
+  | AuthenticationError
+  | AuthorizationError
+  | MissingDocumentIdError
+  | MessageParseError
+  | TransactionRejectedError;

package/src/HotStorage.ts

@@ -0,0 +1,165 @@
+/**
+ * @voidhash/mimic-effect - HotStorage
+ *
+ * Interface and implementations for Write-Ahead Log (WAL) storage.
+ */
+import { Context, Effect, HashMap, Layer, Ref } from "effect";
+import type { WalEntry } from "./Types";
+import { HotStorageError } from "./Errors";
+
+// =============================================================================
+// HotStorage Interface
+// =============================================================================
+
+/**
+ * HotStorage interface for storing Write-Ahead Log entries.
+ *
+ * This is the "hot" tier of the two-tier storage system.
+ * It stores every transaction as a WAL entry for durability between snapshots.
+ * WAL entries are small (just the transaction) and writes are append-only.
+ */
+export interface HotStorage {
+  /**
+   * Append a WAL entry for a document.
+   */
+  readonly append: (
+    documentId: string,
+    entry: WalEntry
+  ) => Effect.Effect<void, HotStorageError>;
+
+  /**
+   * Get all WAL entries for a document since a given version.
+   * Returns entries with version > sinceVersion, ordered by version.
+   */
+  readonly getEntries: (
+    documentId: string,
+    sinceVersion: number
+  ) => Effect.Effect<WalEntry[], HotStorageError>;
+
+  /**
+   * Truncate WAL entries up to (and including) a given version.
+   * Called after a snapshot is saved to remove entries that are now in the snapshot.
+   */
+  readonly truncate: (
+    documentId: string,
+    upToVersion: number
+  ) => Effect.Effect<void, HotStorageError>;
+}
+
+// =============================================================================
+// Context Tag
+// =============================================================================
+
+/**
+ * Context tag for HotStorage service
+ */
+export class HotStorageTag extends Context.Tag("@voidhash/mimic-effect/HotStorage")<
+  HotStorageTag,
+  HotStorage
+>() {}
+
+// =============================================================================
+// Factory
+// =============================================================================
+
+/**
+ * Create a HotStorage layer from an Effect that produces a HotStorage service.
+ *
+ * This allows you to access other Effect services when implementing custom storage.
+ *
+ * @example
+ * ```typescript
+ * const Hot = HotStorage.make(
+ *   Effect.gen(function*() {
+ *     const redis = yield* RedisService
+ *
+ *     return {
+ *       append: (documentId, entry) =>
+ *         redis.rpush(`wal:${documentId}`, JSON.stringify(entry)),
+ *       getEntries: (documentId, sinceVersion) =>
+ *         redis.lrange(`wal:${documentId}`, 0, -1).pipe(
+ *           Effect.map(entries =>
+ *             entries
+ *               .map(e => JSON.parse(e))
+ *               .filter(e => e.version > sinceVersion)
+ *               .sort((a, b) => a.version - b.version)
+ *           )
+ *         ),
+ *       truncate: (documentId, upToVersion) =>
+ *         // Implementation depends on Redis data structure
+ *         Effect.void,
+ *     }
+ *   })
+ * )
+ * ```
+ */
+export const make = <E, R>(
+  effect: Effect.Effect<HotStorage, E, R>
+): Layer.Layer<HotStorageTag, E, R> =>
+  Layer.effect(HotStorageTag, effect);
+
+// =============================================================================
+// InMemory Implementation
+// =============================================================================
+
+/**
+ * In-memory HotStorage implementation.
+ *
+ * Useful for testing and development. Not suitable for production
+ * as data is lost when the process restarts.
+ */
+export namespace InMemory {
+  /**
+   * Create an in-memory HotStorage layer.
+   */
+  export const make = (): Layer.Layer<HotStorageTag> =>
+    Layer.effect(
+      HotStorageTag,
+      Effect.gen(function* () {
+        const store = yield* Ref.make(HashMap.empty<string, WalEntry[]>());
+
+        return {
+          append: (documentId, entry) =>
+            Ref.update(store, (map) => {
+              const existing = HashMap.get(map, documentId);
+              const entries =
+                existing._tag === "Some" ? existing.value : [];
+              return HashMap.set(map, documentId, [...entries, entry]);
+            }),
+
+          getEntries: (documentId, sinceVersion) =>
+            Effect.gen(function* () {
+              const current = yield* Ref.get(store);
+              const existing = HashMap.get(current, documentId);
+              const entries =
+                existing._tag === "Some" ? existing.value : [];
+              return entries
+                .filter((e) => e.version > sinceVersion)
+                .sort((a, b) => a.version - b.version);
+            }),
+
+          truncate: (documentId, upToVersion) =>
+            Ref.update(store, (map) => {
+              const existing = HashMap.get(map, documentId);
+              if (existing._tag === "None") {
+                return map;
+              }
+              const filtered = existing.value.filter(
+                (e) => e.version > upToVersion
+              );
+              return HashMap.set(map, documentId, filtered);
+            }),
+        };
+      })
+    );
+}
+
+// =============================================================================
+// Re-export namespace
+// =============================================================================
+
+export const HotStorage = {
+  Tag: HotStorageTag,
+  make,
+  InMemory,
+};

package/src/Metrics.ts

@@ -0,0 +1,163 @@
+/**
+ * @voidhash/mimic-effect - Metrics
+ *
+ * Observability metrics using Effect's Metric API.
+ */
+import { Metric, MetricBoundaries } from "effect";
+
+// =============================================================================
+// Connection Metrics
+// =============================================================================
+
+/**
+ * Current active WebSocket connections
+ */
+export const connectionsActive = Metric.gauge("mimic.connections.active");
+
+/**
+ * Total connections over lifetime
+ */
+export const connectionsTotal = Metric.counter("mimic.connections.total");
+
+/**
+ * Connection duration histogram (milliseconds)
+ */
+export const connectionsDuration = Metric.histogram(
+  "mimic.connections.duration_ms",
+  MetricBoundaries.exponential({
+    start: 100,
+    factor: 2,
+    count: 15, // Up to ~3.2 million ms (~53 minutes)
+  })
+);
+
+/**
+ * Connection errors (auth failures, etc.)
+ */
+export const connectionsErrors = Metric.counter("mimic.connections.errors");
+
+// =============================================================================
+// Document Metrics
+// =============================================================================
+
+/**
+ * Documents currently in memory
+ */
+export const documentsActive = Metric.gauge("mimic.documents.active");
+
+/**
+ * New documents created
+ */
+export const documentsCreated = Metric.counter("mimic.documents.created");
+
+/**
+ * Documents restored from storage
+ */
+export const documentsRestored = Metric.counter("mimic.documents.restored");
+
+/**
+ * Documents garbage collected (evicted)
+ */
+export const documentsEvicted = Metric.counter("mimic.documents.evicted");
+
+// =============================================================================
+// Transaction Metrics
+// =============================================================================
+
+/**
+ * Successfully processed transactions
+ */
+export const transactionsProcessed = Metric.counter(
+  "mimic.transactions.processed"
+);
+
+/**
+ * Rejected transactions
+ */
+export const transactionsRejected = Metric.counter(
+  "mimic.transactions.rejected"
+);
+
+/**
+ * Transaction processing latency histogram (milliseconds)
+ */
+export const transactionsLatency = Metric.histogram(
+  "mimic.transactions.latency_ms",
+  MetricBoundaries.exponential({
+    start: 0.1,
+    factor: 2,
+    count: 15, // Up to ~1638 ms
+  })
+);
+
+// =============================================================================
+// Storage Metrics
+// =============================================================================
+
+/**
+ * Snapshots saved to ColdStorage
+ */
+export const storageSnapshots = Metric.counter("mimic.storage.snapshots");
+
+/**
+ * Snapshot save duration histogram (milliseconds)
+ */
+export const storageSnapshotLatency = Metric.histogram(
+  "mimic.storage.snapshot_latency_ms",
+  MetricBoundaries.exponential({
+    start: 1,
+    factor: 2,
+    count: 12, // Up to ~4 seconds
+  })
+);
+
+/**
+ * WAL entries written to HotStorage
+ */
+export const storageWalAppends = Metric.counter("mimic.storage.wal_appends");
+
+// =============================================================================
+// Presence Metrics
+// =============================================================================
+
+/**
+ * Presence set operations
+ */
+export const presenceUpdates = Metric.counter("mimic.presence.updates");
+
+/**
+ * Active presence entries
+ */
+export const presenceActive = Metric.gauge("mimic.presence.active");
+
+// =============================================================================
+// Export namespace
+// =============================================================================
+
+export const MimicMetrics = {
+  // Connection
+  connectionsActive,
+  connectionsTotal,
+  connectionsDuration,
+  connectionsErrors,
+
+  // Document
+  documentsActive,
+  documentsCreated,
+  documentsRestored,
+  documentsEvicted,
+
+  // Transaction
+  transactionsProcessed,
+  transactionsRejected,
+  transactionsLatency,
+
+  // Storage
+  storageSnapshots,
+  storageSnapshotLatency,
+  storageWalAppends,
+
+  // Presence
+  presenceUpdates,
+  presenceActive,
+};

package/src/MimicAuthService.ts

@@ -1,44 +1,39 @@
 /**
- * @since 0.0.1
- * Authentication service interface for Mimic connections.
- * Provides pluggable authentication adapters.
+ * @voidhash/mimic-effect - MimicAuthService
+ *
+ * Authentication and authorization service interface and implementations.
  */
-import * as Effect from "effect/Effect";
-import * as Context from "effect/Context";
-import * as Layer from "effect/Layer";
+import { Context, Effect, Layer } from "effect";
+import type { AuthContext, Permission } from "./Types";
+import { AuthenticationError } from "./Errors";
 
 // =============================================================================
-// Authentication Types
+// MimicAuthService Interface
 // =============================================================================
 
 /**
- * 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.)
+ * MimicAuthService interface for authentication and authorization.
+ *
+ * The `authenticate` method receives the token from the client's auth message
+ * and the document ID being accessed. It should return an AuthContext on success
+ * or fail with AuthenticationError on failure.
+ *
+ * The permission in AuthContext determines what the user can do:
+ * - "read": Can subscribe, receive transactions, get snapshots
+ * - "write": All of the above, plus can submit transactions and set presence
  */
 export interface MimicAuthService {
   /**
-   * Authenticate a connection using the provided token.
-   * @param token - The authentication token provided by the client
-   * @returns The authentication result
+   * Authenticate a connection and return authorization context.
+   *
+   * @param token - The token provided by the client
+   * @param documentId - The document ID being accessed
+   * @returns AuthContext with userId and permission level
    */
-  readonly authenticate: (token: string) => Effect.Effect<AuthResult>;
+  readonly authenticate: (
+    token: string,
+    documentId: string
+  ) => Effect.Effect<AuthContext, AuthenticationError>;
 }
 
 // =============================================================================
@@ -46,58 +41,125 @@ export interface MimicAuthService {
 // =============================================================================
 
 /**
- * Context tag for MimicAuthService service.
+ * Context tag for MimicAuthService
  */
 export class MimicAuthServiceTag extends Context.Tag(
-  "@voidhash/mimic-server-effect/MimicAuthService"
+  "@voidhash/mimic-effect/MimicAuthService"
 )<MimicAuthServiceTag, MimicAuthService>() {}
 
 // =============================================================================
-// Layer Constructors
+// Factory
 // =============================================================================
 
 /**
- * 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.
+ * Create a MimicAuthService layer from an Effect that produces the service.
+ *
+ * This allows you to access other Effect services when implementing authentication.
+ *
+ * @example
+ * ```typescript
+ * const Auth = MimicAuthService.make(
+ *   Effect.gen(function*() {
+ *     const db = yield* DatabaseService
+ *     const jwt = yield* JwtService
+ *
+ *     return {
+ *       authenticate: (token, documentId) =>
+ *         Effect.gen(function*() {
+ *           const payload = yield* jwt.verify(token).pipe(
+ *             Effect.mapError(() => new AuthenticationError({ reason: "Invalid token" }))
+ *           )
+ *
+ *           const permission = yield* db.getDocumentPermission(payload.userId, documentId)
+ *
+ *           return { userId: payload.userId, permission }
+ *         })
+ *     }
+ *   })
+ * )
+ * ```
  */
-export const layerEffect = <E, R>(
+export const make = <E, R>(
   effect: Effect.Effect<MimicAuthService, E, R>
 ): Layer.Layer<MimicAuthServiceTag, E, R> =>
   Layer.effect(MimicAuthServiceTag, effect);
 
 // =============================================================================
-// Helper Functions
+// NoAuth Implementation
 // =============================================================================
 
 /**
- * Create an auth service from an auth handler function.
+ * No-authentication implementation.
+ *
+ * Everyone gets write access with userId "anonymous".
+ * ONLY USE FOR DEVELOPMENT/TESTING.
  */
-export const make = (authHandler: AuthHandler): MimicAuthService => ({
-  authenticate: (token: string) =>
-    Effect.promise(() => Promise.resolve(authHandler(token))),
-});
+export namespace NoAuth {
+  /**
+   * Create a NoAuth layer.
+   * All connections are authenticated with write permission.
+   */
+  export const make = (): Layer.Layer<MimicAuthServiceTag> =>
+    Layer.succeed(MimicAuthServiceTag, {
+      authenticate: (_token, _documentId) =>
+        Effect.succeed({
+          userId: "anonymous",
+          permission: "write" as const,
+        }),
+    });
+}
+
+// =============================================================================
+// Static Implementation
+// =============================================================================
 
 /**
- * Create an auth service from an Effect-based authenticate function.
+ * Static permissions implementation.
+ *
+ * Permissions are defined at configuration time.
+ * The token is treated as the userId.
  */
-export const makeEffect = (
-  authenticate: (token: string) => Effect.Effect<AuthResult>
-): MimicAuthService => ({
-  authenticate,
-});
+export namespace Static {
+  export interface Options {
+    /**
+     * Map of userId (token) to permission level
+     */
+    readonly permissions: Record<string, Permission>;
+    /**
+     * Default permission for users not in the permissions map.
+     * If undefined, unknown users will fail authentication.
+     */
+    readonly defaultPermission?: Permission;
+  }
+
+  /**
+   * Create a Static auth layer.
+   * The token is treated as the userId, and permissions are looked up from the config.
+   */
+  export const make = (options: Options): Layer.Layer<MimicAuthServiceTag> =>
+    Layer.succeed(MimicAuthServiceTag, {
+      authenticate: (token, _documentId) => {
+        const permission = options.permissions[token] ?? options.defaultPermission;
+        if (permission === undefined) {
+          return Effect.fail(
+            new AuthenticationError({ reason: "Unknown user" })
+          );
+        }
+        return Effect.succeed({
+          userId: token,
+          permission,
+        });
+      },
+    });
+}
+
+// =============================================================================
+// Re-export namespace
+// =============================================================================
+
+export const MimicAuthService = {
+  Tag: MimicAuthServiceTag,
+  make,
+  NoAuth,
+  Static,
+};