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

package/src/Protocol.ts

@@ -0,0 +1,350 @@
+/**
+ * @voidhash/mimic-effect - WebSocket Protocol
+ *
+ * Message types and encoding/decoding for WebSocket communication.
+ */
+import { Effect } from "effect";
+import { Transaction } from "@voidhash/mimic";
+import type { Permission, PresenceEntry } from "./Types";
+import { MessageParseError } from "./Errors";
+
+// =============================================================================
+// Client -> Server Messages
+// =============================================================================
+
+/**
+ * Authentication request
+ */
+export interface AuthMessage {
+  readonly type: "auth";
+  readonly token: string;
+}
+
+/**
+ * Heartbeat ping
+ */
+export interface PingMessage {
+  readonly type: "ping";
+}
+
+/**
+ * Submit a transaction
+ */
+export interface SubmitMessage {
+  readonly type: "submit";
+  readonly transaction: Transaction.Transaction;
+}
+
+/**
+ * Request current document snapshot
+ */
+export interface RequestSnapshotMessage {
+  readonly type: "request_snapshot";
+}
+
+/**
+ * Set presence data
+ */
+export interface PresenceSetMessage {
+  readonly type: "presence_set";
+  readonly data: unknown;
+}
+
+/**
+ * Clear presence data
+ */
+export interface PresenceClearMessage {
+  readonly type: "presence_clear";
+}
+
+/**
+ * Union of all client messages
+ */
+export type ClientMessage =
+  | AuthMessage
+  | PingMessage
+  | SubmitMessage
+  | RequestSnapshotMessage
+  | PresenceSetMessage
+  | PresenceClearMessage;
+
+// =============================================================================
+// Server -> Client Messages
+// =============================================================================
+
+/**
+ * Authentication result
+ */
+export interface AuthResultMessage {
+  readonly type: "auth_result";
+  readonly success: boolean;
+  readonly error?: string;
+  readonly userId?: string;
+  readonly permission?: Permission;
+}
+
+/**
+ * Heartbeat pong
+ */
+export interface PongMessage {
+  readonly type: "pong";
+}
+
+/**
+ * Transaction broadcast
+ */
+export interface TransactionMessage {
+  readonly type: "transaction";
+  readonly transaction: Transaction.Transaction;
+  readonly version: number;
+}
+
+/**
+ * Document snapshot
+ */
+export interface SnapshotMessage {
+  readonly type: "snapshot";
+  readonly state: unknown;
+  readonly version: number;
+}
+
+/**
+ * Transaction error
+ */
+export interface ErrorMessage {
+  readonly type: "error";
+  readonly transactionId: string;
+  readonly reason: string;
+}
+
+/**
+ * Presence update broadcast
+ */
+export interface PresenceUpdateMessage {
+  readonly type: "presence_update";
+  readonly id: string;
+  readonly data: unknown;
+  readonly userId?: string;
+}
+
+/**
+ * Presence removal broadcast
+ */
+export interface PresenceRemoveMessage {
+  readonly type: "presence_remove";
+  readonly id: string;
+}
+
+/**
+ * Presence snapshot (sent after auth)
+ */
+export interface PresenceSnapshotMessage {
+  readonly type: "presence_snapshot";
+  readonly selfId: string;
+  readonly presences: Record<string, PresenceEntry>;
+}
+
+/**
+ * Union of all server messages
+ */
+export type ServerMessage =
+  | AuthResultMessage
+  | PongMessage
+  | TransactionMessage
+  | SnapshotMessage
+  | ErrorMessage
+  | PresenceUpdateMessage
+  | PresenceRemoveMessage
+  | PresenceSnapshotMessage;
+
+/**
+ * Server broadcast messages (transaction or error)
+ */
+export type ServerBroadcast = TransactionMessage | ErrorMessage;
+
+// =============================================================================
+// Encoded Types (for wire format)
+// =============================================================================
+
+/**
+ * Encoded client message (with encoded transaction)
+ */
+export interface EncodedClientMessage {
+  readonly type: string;
+  readonly token?: string;
+  readonly transaction?: Transaction.EncodedTransaction;
+  readonly data?: unknown;
+}
+
+/**
+ * Encoded server message (with encoded transaction)
+ */
+export interface EncodedServerMessage {
+  readonly type: string;
+  readonly success?: boolean;
+  readonly error?: string;
+  readonly userId?: string;
+  readonly permission?: Permission;
+  readonly transaction?: Transaction.EncodedTransaction;
+  readonly version?: number;
+  readonly state?: unknown;
+  readonly transactionId?: string;
+  readonly reason?: string;
+  readonly id?: string;
+  readonly data?: unknown;
+  readonly selfId?: string;
+  readonly presences?: Record<string, PresenceEntry>;
+}
+
+// =============================================================================
+// Encoding/Decoding Functions
+// =============================================================================
+
+/**
+ * Decode an encoded client message to a ClientMessage
+ */
+export const decodeClientMessage = (
+  encoded: EncodedClientMessage
+): ClientMessage => {
+  if (encoded.type === "submit" && encoded.transaction) {
+    return {
+      type: "submit",
+      transaction: Transaction.decode(encoded.transaction),
+    };
+  }
+  return encoded as ClientMessage;
+};
+
+/**
+ * Encode a server message for wire format
+ */
+export const encodeServerMessage = (message: ServerMessage): string => {
+  if (message.type === "transaction") {
+    const encoded: EncodedServerMessage = {
+      type: "transaction",
+      transaction: Transaction.encode(message.transaction),
+      version: message.version,
+    };
+    return JSON.stringify(encoded);
+  }
+  return JSON.stringify(message);
+};
+
+/**
+ * Parse a raw WebSocket message to a ClientMessage
+ */
+export const parseClientMessage = (
+  data: string | ArrayBuffer | Uint8Array
+): Effect.Effect<ClientMessage, MessageParseError> =>
+  Effect.try({
+    try: () => {
+      const text =
+        typeof data === "string"
+          ? data
+          : new TextDecoder().decode(
+              data instanceof ArrayBuffer ? new Uint8Array(data) : data
+            );
+      const encoded = JSON.parse(text) as EncodedClientMessage;
+      return decodeClientMessage(encoded);
+    },
+    catch: (cause) => new MessageParseError({ cause }),
+  });
+
+/**
+ * Create an auth result success message
+ */
+export const authResultSuccess = (
+  userId: string,
+  permission: Permission
+): AuthResultMessage => ({
+  type: "auth_result",
+  success: true,
+  userId,
+  permission,
+});
+
+/**
+ * Create an auth result failure message
+ */
+export const authResultFailure = (error: string): AuthResultMessage => ({
+  type: "auth_result",
+  success: false,
+  error,
+});
+
+/**
+ * Create a pong message
+ */
+export const pong = (): PongMessage => ({ type: "pong" });
+
+/**
+ * Create a transaction message
+ */
+export const transactionMessage = (
+  transaction: Transaction.Transaction,
+  version: number
+): TransactionMessage => ({
+  type: "transaction",
+  transaction,
+  version,
+});
+
+/**
+ * Create a snapshot message
+ */
+export const snapshotMessage = (
+  state: unknown,
+  version: number
+): SnapshotMessage => ({
+  type: "snapshot",
+  state,
+  version,
+});
+
+/**
+ * Create an error message
+ */
+export const errorMessage = (
+  transactionId: string,
+  reason: string
+): ErrorMessage => ({
+  type: "error",
+  transactionId,
+  reason,
+});
+
+/**
+ * Create a presence update message
+ */
+export const presenceUpdateMessage = (
+  id: string,
+  data: unknown,
+  userId?: string
+): PresenceUpdateMessage => ({
+  type: "presence_update",
+  id,
+  data,
+  userId,
+});
+
+/**
+ * Create a presence remove message
+ */
+export const presenceRemoveMessage = (
+  id: string
+): PresenceRemoveMessage => ({
+  type: "presence_remove",
+  id,
+});
+
+/**
+ * Create a presence snapshot message
+ */
+export const presenceSnapshotMessage = (
+  selfId: string,
+  presences: Record<string, PresenceEntry>
+): PresenceSnapshotMessage => ({
+  type: "presence_snapshot",
+  selfId,
+  presences,
+});

package/src/Types.ts

@@ -0,0 +1,231 @@
+/**
+ * @voidhash/mimic-effect - Common Types
+ *
+ * Shared types used throughout the mimic-effect package.
+ */
+import type { Duration, Effect } from "effect";
+import type { Presence, Primitive, Transaction } from "@voidhash/mimic";
+
+// =============================================================================
+// Permission Types
+// =============================================================================
+
+/**
+ * Permission level for document access
+ * - "read": Can subscribe, receive transactions, get snapshots
+ * - "write": All of the above, plus can submit transactions and set presence
+ */
+export type Permission = "read" | "write";
+
+/**
+ * Authentication context returned after successful authentication
+ */
+export interface AuthContext {
+  readonly userId: string;
+  readonly permission: Permission;
+  readonly metadata?: Record<string, unknown>;
+}
+
+// =============================================================================
+// Storage Types
+// =============================================================================
+
+/**
+ * Document state stored in ColdStorage (snapshots)
+ */
+export interface StoredDocument {
+  /** Document state */
+  readonly state: unknown;
+  /** Current version number */
+  readonly version: number;
+  /** Schema version for future migration support */
+  readonly schemaVersion: number;
+  /** Unix timestamp (ms) when saved */
+  readonly savedAt: number;
+}
+
+/**
+ * WAL entry stored in HotStorage
+ */
+export interface WalEntry {
+  /** The transaction data */
+  readonly transaction: Transaction.Transaction;
+  /** Version after this transaction */
+  readonly version: number;
+  /** Unix timestamp (ms) */
+  readonly timestamp: number;
+}
+
+// =============================================================================
+// Presence Types
+// =============================================================================
+
+/**
+ * Presence entry for a connection
+ */
+export interface PresenceEntry {
+  /** Presence data (schema-validated) */
+  readonly data: unknown;
+  /** User ID from authentication (optional) */
+  readonly userId?: string;
+}
+
+/**
+ * Snapshot of all presences for a document
+ */
+export interface PresenceSnapshot {
+  readonly presences: Record<string, PresenceEntry>;
+}
+
+/**
+ * Presence update event
+ */
+export interface PresenceUpdateEvent {
+  readonly type: "presence_update";
+  readonly id: string;
+  readonly data: unknown;
+  readonly userId?: string;
+}
+
+/**
+ * Presence remove event
+ */
+export interface PresenceRemoveEvent {
+  readonly type: "presence_remove";
+  readonly id: string;
+}
+
+/**
+ * Union of presence events
+ */
+export type PresenceEvent = PresenceUpdateEvent | PresenceRemoveEvent;
+
+// =============================================================================
+// Config Types
+// =============================================================================
+
+/**
+ * Duration input type - matches Effect's DurationInput
+ */
+export type DurationInput = Duration.DurationInput;
+
+/**
+ * Snapshot configuration
+ */
+export interface SnapshotConfig {
+  /** Time-based snapshot interval */
+  readonly interval: DurationInput;
+  /** Transaction count threshold for snapshots */
+  readonly transactionThreshold: number;
+}
+
+/**
+ * Context passed to initial state function
+ */
+export interface InitialContext {
+  readonly documentId: string;
+}
+
+/**
+ * Initial state function type
+ */
+export type InitialFn<TSchema extends Primitive.AnyPrimitive> = (
+  context: InitialContext
+) => Effect.Effect<Primitive.InferSetInput<TSchema>>;
+
+/**
+ * Initial state - either a static value or a function
+ */
+export type Initial<TSchema extends Primitive.AnyPrimitive> =
+  | Primitive.InferSetInput<TSchema>
+  | InitialFn<TSchema>;
+
+/**
+ * MimicServerEngine configuration
+ */
+export interface MimicServerEngineConfig<
+  TSchema extends Primitive.AnyPrimitive,
+> {
+  /** Document schema (required) */
+  readonly schema: TSchema;
+
+  /** Initial state for new documents (optional) */
+  readonly initial?: Initial<TSchema>;
+
+  /** Presence schema (optional) */
+  readonly presence?: Presence.AnyPresence;
+
+  /** Document idle timeout before GC (default: 5 minutes) */
+  readonly maxIdleTime?: DurationInput;
+
+  /** Maximum transaction history for deduplication (default: 1000) */
+  readonly maxTransactionHistory?: number;
+
+  /** Snapshot configuration */
+  readonly snapshot?: SnapshotConfig;
+}
+
+/**
+ * MimicClusterServerEngine configuration (extends MimicServerEngineConfig)
+ */
+export interface MimicClusterServerEngineConfig<
+  TSchema extends Primitive.AnyPrimitive,
+> extends MimicServerEngineConfig<TSchema> {
+  /** Shard group name for cluster distribution (default: "mimic-documents") */
+  readonly shardGroup?: string;
+}
+
+// =============================================================================
+// Route Config Types
+// =============================================================================
+
+/**
+ * MimicServer route configuration
+ */
+export interface MimicServerRouteConfig {
+  /** WebSocket route path prefix (default: "/mimic") */
+  readonly path?: `/${string}`;
+
+  /** Heartbeat ping interval (default: 30 seconds) */
+  readonly heartbeatInterval?: DurationInput;
+
+  /** Heartbeat timeout - disconnect if no activity (default: 10 seconds) */
+  readonly heartbeatTimeout?: DurationInput;
+}
+
+// =============================================================================
+// Internal Config with Defaults Applied
+// =============================================================================
+
+/**
+ * Resolved engine configuration with all defaults applied
+ */
+export interface ResolvedConfig<TSchema extends Primitive.AnyPrimitive> {
+  readonly schema: TSchema;
+  readonly initial: Initial<TSchema> | undefined;
+  readonly presence: Presence.AnyPresence | undefined;
+  readonly maxIdleTime: Duration.Duration;
+  readonly maxTransactionHistory: number;
+  readonly snapshot: {
+    readonly interval: Duration.Duration;
+    readonly transactionThreshold: number;
+  };
+}
+
+/**
+ * Resolved route configuration with all defaults applied
+ */
+export interface ResolvedRouteConfig {
+  readonly path: string;
+  readonly heartbeatInterval: Duration.Duration;
+  readonly heartbeatTimeout: Duration.Duration;
+}
+
+/**
+ * Resolved cluster engine configuration with all defaults applied
+ */
+export interface ResolvedClusterConfig<TSchema extends Primitive.AnyPrimitive>
+  extends ResolvedConfig<TSchema> {
+  /** Shard group name for cluster distribution */
+  readonly shardGroup: string;
+}

package/src/index.ts

@@ -1,48 +1,82 @@
 /**
- * @voidhash/mimic-server-effect
+ * @voidhash/mimic-effect
  *
- * Effect-based server implementation for Mimic sync engine.
+ * Server-side Effect integration for Mimic real-time collaboration.
  *
- * @since 0.0.1
+ * @since 0.0.9
  */
 
 // =============================================================================
-// Main Server
+// Main Exports
 // =============================================================================
 
-export * as MimicServer from "./MimicServer.js";
+export { MimicServerEngine, MimicServerEngineTag } from "./MimicServerEngine";
+export { MimicClusterServerEngine } from "./MimicClusterServerEngine";
+export { MimicServer, type MimicServerRouteConfig } from "./MimicServer";
+export { ColdStorage, ColdStorageTag } from "./ColdStorage";
+export { HotStorage, HotStorageTag } from "./HotStorage";
+export { MimicAuthService, MimicAuthServiceTag } from "./MimicAuthService";
+export { MimicMetrics } from "./Metrics";
 
 // =============================================================================
-// Service Interfaces
+// Types
 // =============================================================================
 
-export * as MimicDataStorage from "./MimicDataStorage.js";
-export * as MimicAuthService from "./MimicAuthService.js";
+export type {
+  Permission,
+  AuthContext,
+  StoredDocument,
+  WalEntry,
+  PresenceEntry,
+  PresenceSnapshot,
+  PresenceEvent,
+  PresenceUpdateEvent,
+  PresenceRemoveEvent,
+  DurationInput,
+  SnapshotConfig,
+  InitialContext,
+  InitialFn,
+  Initial,
+  MimicServerEngineConfig,
+  MimicClusterServerEngineConfig,
+  ResolvedConfig,
+  ResolvedClusterConfig,
+  ResolvedRouteConfig,
+} from "./Types";
 
 // =============================================================================
-// Default Implementations
+// Errors
 // =============================================================================
 
-export * as MimicInMemoryDataStorage from "./storage/InMemoryDataStorage.js";
-export * as MimicNoAuth from "./auth/NoAuth.js";
+export {
+  ColdStorageError,
+  HotStorageError,
+  AuthenticationError,
+  AuthorizationError,
+  MissingDocumentIdError,
+  MessageParseError,
+  TransactionRejectedError,
+  type MimicError,
+} from "./Errors";
 
 // =============================================================================
-// Configuration
+// Protocol (for custom implementations)
 // =============================================================================
 
-export * as MimicConfig from "./MimicConfig.js";
+export * as Protocol from "./Protocol";
 
 // =============================================================================
-// Internal Components (for advanced usage)
+// Internal Exports (for advanced use cases)
 // =============================================================================
 
-export * as DocumentManager from "./DocumentManager.js";
-export * as PresenceManager from "./PresenceManager.js";
-export * as WebSocketHandler from "./WebSocketHandler.js";
-export * as DocumentProtocol from "./DocumentProtocol.js";
-
-// =============================================================================
-// Errors
-// =============================================================================
+export {
+  DocumentManager,
+  DocumentManagerTag,
+  DocumentManagerConfigTag,
+  type SubmitResult,
+} from "./DocumentManager";
 
-export * from "./errors.js";
+export {
+  PresenceManager,
+  PresenceManagerTag,
+} from "./PresenceManager";