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

package/src/Errors.ts

@@ -0,0 +1,114 @@
+/**
+ * @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" | "appendWithCheck";
+  readonly cause: unknown;
+}> {}
+
+/**
+ * Error when WAL append detects a version gap.
+ * This indicates either:
+ * - A bug in the application (skipped a version)
+ * - Concurrent writes to the same document
+ * - Data corruption in WAL storage
+ */
+export class WalVersionGapError extends Data.TaggedError("WalVersionGapError")<{
+  readonly documentId: string;
+  readonly expectedVersion: number;
+  readonly actualPreviousVersion: number | undefined;
+}> {}
+
+// =============================================================================
+// 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
+  | WalVersionGapError
+  | AuthenticationError
+  | AuthorizationError
+  | MissingDocumentIdError
+  | MessageParseError
+  | TransactionRejectedError;

package/src/HotStorage.ts

@@ -0,0 +1,239 @@
+/**
+ * @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, WalVersionGapError } 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>;
+
+  /**
+   * Append a WAL entry with version gap checking.
+   *
+   * This is an atomic operation that:
+   * 1. Verifies the previous entry has version = expectedVersion - 1
+   *    (or this is the first entry if expectedVersion === 1)
+   * 2. Appends the entry if check passes
+   *
+   * Use this for two-phase commit to guarantee WAL ordering at write time.
+   *
+   * @param documentId - Document ID
+   * @param entry - WAL entry to append
+   * @param expectedVersion - The version this entry should have (entry.version)
+   * @returns Effect that fails with WalVersionGapError if gap detected
+   */
+  readonly appendWithCheck: (
+    documentId: string,
+    entry: WalEntry,
+    expectedVersion: number
+  ) => Effect.Effect<void, HotStorageError | WalVersionGapError>;
+
+  /**
+   * 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]);
+            }),
+
+          appendWithCheck: (documentId, entry, expectedVersion) =>
+            Effect.gen(function* () {
+              type CheckResult =
+                | { type: "ok" }
+                | { type: "gap"; lastVersion: number | undefined };
+
+              // Use Ref.modify for atomic check + update
+              const result: CheckResult = yield* Ref.modify(store, (map): [CheckResult, HashMap.HashMap<string, WalEntry[]>] => {
+                const existing = HashMap.get(map, documentId);
+                const entries = existing._tag === "Some" ? existing.value : [];
+
+                // Find the highest version in existing entries
+                const lastVersion = entries.length > 0
+                  ? Math.max(...entries.map((e) => e.version))
+                  : 0;
+
+                // Gap check
+                if (expectedVersion === 1) {
+                  // First entry: should have no entries with version >= 1
+                  if (lastVersion >= 1) {
+                    return [
+                      { type: "gap", lastVersion },
+                      map,
+                    ];
+                  }
+                } else {
+                  // Not first: last entry should have version = expectedVersion - 1
+                  if (lastVersion !== expectedVersion - 1) {
+                    return [
+                      { type: "gap", lastVersion: lastVersion > 0 ? lastVersion : undefined },
+                      map,
+                    ];
+                  }
+                }
+
+                // No gap: append and return success
+                return [
+                  { type: "ok" },
+                  HashMap.set(map, documentId, [...entries, entry]),
+                ];
+              });
+
+              if (result.type === "gap") {
+                return yield* Effect.fail(
+                  new WalVersionGapError({
+                    documentId,
+                    expectedVersion,
+                    actualPreviousVersion: result.lastVersion,
+                  })
+                );
+              }
+            }),
+
+          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,187 @@
+/**
+ * @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");
+
+/**
+ * Version gaps detected during WAL replay
+ */
+export const storageVersionGaps = Metric.counter("mimic.storage.version_gaps");
+
+/**
+ * Failed WAL appends causing transaction rollback
+ */
+export const walAppendFailures = Metric.counter("mimic.storage.wal_append_failures");
+
+/**
+ * ColdStorage load failures during document restore
+ */
+export const coldStorageLoadFailures = Metric.counter("mimic.storage.cold_load_failures");
+
+/**
+ * HotStorage getEntries failures during document restore
+ */
+export const hotStorageLoadFailures = Metric.counter("mimic.storage.hot_load_failures");
+
+// =============================================================================
+// 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,
+  storageVersionGaps,
+  walAppendFailures,
+  coldStorageLoadFailures,
+  hotStorageLoadFailures,
+
+  // Presence
+  presenceUpdates,
+  presenceActive,
+};