@sylphx/lens-server 1.11.2 → 2.0.1

package/src/index.ts

@@ -2,7 +2,35 @@
  * @sylphx/lens-server
  *
  * Server runtime for Lens API framework.
- * Operations-based server with GraphStateManager for reactive updates.
+ *
+ * Architecture:
+ * - App = Executor with optional plugin support
+ *   - Stateless (default): Pure executor
+ *   - Stateful (with opLog): Cursor-based state synchronization
+ * - Handlers = Pure protocol handlers (HTTP, WebSocket, SSE)
+ *   - No business logic - just translate protocol to app calls
+ * - Plugins = App-level middleware (opLog, auth, logger)
+ *   - Configured at app level, not handler level
+ *
+ * @example
+ * ```typescript
+ * // Stateless mode (default)
+ * const app = createApp({ router });
+ * const wsHandler = createWSHandler(app);
+ *
+ * // With opLog plugin (cursor-based state sync)
+ * const app = createApp({
+ *   router,
+ *   plugins: [opLog()],
+ * });
+ *
+ * // With external storage for serverless (install @sylphx/lens-storage-upstash)
+ * import { upstashStorage } from "@sylphx/lens-storage-upstash";
+ * const app = createApp({
+ *   router,
+ *   plugins: [opLog({ storage: upstashStorage({ redis }) })],
+ * });
+ * ```
  */
 
 // =============================================================================
@@ -25,21 +53,34 @@ export {
 } from "@sylphx/lens-core";
 
 // =============================================================================
-// Server
+// Context System (Server-side implementation)
+// =============================================================================
+
+export {
+	createContext,
+	extendContext,
+	hasContext,
+	runWithContext,
+	runWithContextAsync,
+	tryUseContext,
+	useContext,
+} from "./context/index.js";
+
+// =============================================================================
+// Server (Pure Executor)
 // =============================================================================
 
 export {
+	// Types
+	type ClientSendFn,
 	// Factory
-	createServer,
+	createApp,
 	type EntitiesMap,
-	// Type inference utilities (tRPC-style)
 	type InferApi,
 	type InferInput,
 	type InferOutput,
-	// In-process transport types
 	type LensOperation,
 	type LensResult,
-	// Types
 	type LensServer,
 	type LensServerConfig as ServerConfig,
 	type MutationsMap,
@@ -47,39 +88,101 @@ export {
 	type OperationsMap,
 	type QueriesMap,
 	type SelectionObject,
-	// Metadata types (for transport handshake)
 	type ServerMetadata,
 	type WebSocketLike,
 } from "./server/create.js";
 
 // =============================================================================
-// State Management
+// Protocol Handlers
+// =============================================================================
+
+export {
+	// Framework Handler Utilities
+	createFrameworkHandler,
+	// Unified Handler (HTTP + SSE)
+	createHandler,
+	// HTTP Handler
+	createHTTPHandler,
+	createServerClientProxy,
+	// SSE Handler
+	createSSEHandler,
+	// WebSocket Handler
+	createWSHandler,
+	type FrameworkHandlerOptions,
+	type Handler,
+	type HandlerOptions,
+	type HTTPHandler,
+	type HTTPHandlerOptions,
+	handleWebMutation,
+	handleWebQuery,
+	handleWebSSE,
+	type SSEHandlerOptions,
+	type WSHandler,
+	type WSHandlerOptions,
+} from "./handlers/index.js";
+
+// =============================================================================
+// Plugin System
+// =============================================================================
+
+export {
+	// Context types
+	type AfterMutationContext,
+	type AfterSendContext,
+	type BeforeMutationContext,
+	type BeforeSendContext,
+	// Operation Log Plugin (cursor-based state management)
+	type BroadcastResult,
+	type ConnectContext,
+	// Plugin manager
+	createPluginManager,
+	type DisconnectContext,
+	type EnhanceOperationMetaContext,
+	isOpLogPlugin,
+	// Optimistic Plugin
+	isOptimisticPlugin,
+	type OpLogOptions,
+	type OpLogPlugin,
+	type OptimisticPluginOptions,
+	opLog,
+	optimisticPlugin,
+	PluginManager,
+	// Plugin interface
+	type ServerPlugin,
+	type SubscribeContext,
+	type UnsubscribeContext,
+} from "./plugin/index.js";
+
+// =============================================================================
+// Storage (for opLog plugin)
 // =============================================================================
 
 export {
-	// Factory
-	createGraphStateManager,
 	// Types
-	type EntityKey,
-	// Class
-	GraphStateManager,
-	type GraphStateManagerConfig,
-	type StateClient,
-	type StateFullMessage,
-	type StateUpdateMessage,
-	type Subscription,
-} from "./state/index.js";
+	DEFAULT_STORAGE_CONFIG,
+	type EmitResult,
+	// In-memory (default)
+	memoryStorage,
+	type OpLogStorage,
+	type OpLogStorageConfig,
+	type StoredEntityState,
+	type StoredPatchEntry,
+} from "./storage/index.js";
 
 // =============================================================================
-// SSE Transport Adapter
+// SSE Handler (additional exports not in handlers/index.js)
 // =============================================================================
 
 export {
-	// Factory
-	createSSEHandler,
-	type SSEClientInfo,
+	// Types
+	type SSEClient,
 	// Class
 	SSEHandler,
-	// Types
 	type SSEHandlerConfig,
 } from "./sse/handler.js";
+
+// =============================================================================
+// Reconnection (Server-side)
+// =============================================================================
+
+export { coalescePatches, estimatePatchSize, OperationLog } from "./reconnect/index.js";

package/src/plugin/index.ts

@@ -0,0 +1,41 @@
+/**
+ * @sylphx/lens-server - Plugin System
+ *
+ * Export all plugin-related types and utilities.
+ */
+
+// Operation Log Plugin (cursor-based state management)
+export {
+	type BroadcastResult,
+	isOpLogPlugin,
+	type OpLogOptions,
+	type OpLogPlugin,
+	opLog,
+} from "./op-log.js";
+
+// Optimistic Updates Plugin
+export {
+	isOptimisticPlugin,
+	type OptimisticPlugin,
+	type OptimisticPluginOptions,
+	optimisticPlugin,
+} from "./optimistic.js";
+
+export {
+	// Context types
+	type AfterMutationContext,
+	type AfterSendContext,
+	type BeforeMutationContext,
+	type BeforeSendContext,
+	type BroadcastContext,
+	type ConnectContext,
+	// Plugin manager
+	createPluginManager,
+	type DisconnectContext,
+	type EnhanceOperationMetaContext,
+	PluginManager,
+	// Plugin interface
+	type ServerPlugin,
+	type SubscribeContext,
+	type UnsubscribeContext,
+} from "./types.js";

package/src/plugin/op-log.ts

@@ -0,0 +1,286 @@
+/**
+ * @sylphx/lens-server - Operation Log Plugin
+ *
+ * Server-side plugin for cursor-based state synchronization.
+ * Provides:
+ * - Canonical state per entity (server truth)
+ * - Version tracking (cursor-based)
+ * - Operation log for efficient reconnection
+ * - Patch computation
+ *
+ * This plugin ONLY handles state management.
+ * Subscription routing is handled by the handler layer.
+ *
+ * Memory: O(entities × history) - does not scale with client count
+ *
+ * @example
+ * ```typescript
+ * // Default (in-memory storage)
+ * const server = createApp({
+ *   router: appRouter,
+ *   plugins: [opLog()],
+ * });
+ *
+ * // With external storage for serverless
+ * const server = createApp({
+ *   router: appRouter,
+ *   plugins: [opLog({
+ *     storage: redisStorage({ url: process.env.REDIS_URL }),
+ *   })],
+ * });
+ * ```
+ */
+
+import type { PatchOperation } from "@sylphx/lens-core";
+import { memoryStorage, type OpLogStorage, type OpLogStorageConfig } from "../storage/index.js";
+import type {
+	BroadcastContext,
+	ReconnectContext,
+	ReconnectHookResult,
+	ServerPlugin,
+} from "./types.js";
+
+/**
+ * Operation log plugin configuration.
+ */
+export interface OpLogOptions extends OpLogStorageConfig {
+	/**
+	 * Storage adapter for state/version/patches.
+	 * Defaults to in-memory storage.
+	 *
+	 * @example
+	 * ```typescript
+	 * // In-memory (default)
+	 * opLog()
+	 *
+	 * // Redis for serverless
+	 * opLog({ storage: redisStorage({ url: REDIS_URL }) })
+	 * ```
+	 */
+	storage?: OpLogStorage;
+
+	/**
+	 * Whether to enable debug logging.
+	 * @default false
+	 */
+	debug?: boolean;
+}
+
+/**
+ * Broadcast result returned by the plugin.
+ * Handler uses this to send updates to subscribers.
+ */
+export interface BroadcastResult {
+	/** Current version after update */
+	version: number;
+	/** Patch operations (null if first emit or log evicted) */
+	patch: PatchOperation[] | null;
+	/** Full data (for initial sends or when patch unavailable) */
+	data: Record<string, unknown>;
+}
+
+/**
+ * OpLog plugin instance type.
+ */
+export interface OpLogPlugin extends ServerPlugin {
+	/** Get the storage adapter */
+	getStorage(): OpLogStorage;
+	/** Get version for an entity (async) */
+	getVersion(entity: string, entityId: string): Promise<number>;
+	/** Get current canonical state for an entity (async) */
+	getState(entity: string, entityId: string): Promise<Record<string, unknown> | null>;
+	/** Get latest patch for an entity (async) */
+	getLatestPatch(entity: string, entityId: string): Promise<PatchOperation[] | null>;
+}
+
+/**
+ * Create an operation log plugin.
+ *
+ * This plugin provides cursor-based state synchronization:
+ * - Canonical state per entity (server truth)
+ * - Version tracking for cursor-based sync
+ * - Operation log for efficient reconnection (patches or snapshot)
+ *
+ * This plugin does NOT handle subscription routing - that's the handler's job.
+ * Memory: O(entities × history) - does not scale with client count.
+ *
+ * @example
+ * ```typescript
+ * // Default (in-memory)
+ * const server = createApp({
+ *   router: appRouter,
+ *   plugins: [opLog()],
+ * });
+ *
+ * // With Redis for serverless
+ * const server = createApp({
+ *   router: appRouter,
+ *   plugins: [opLog({
+ *     storage: redisStorage({ url: process.env.REDIS_URL }),
+ *   })],
+ * });
+ * ```
+ */
+export function opLog(options: OpLogOptions = {}): OpLogPlugin {
+	const storage = options.storage ?? memoryStorage(options);
+	const debug = options.debug ?? false;
+
+	const log = (...args: unknown[]) => {
+		if (debug) {
+			console.log("[opLog]", ...args);
+		}
+	};
+
+	return {
+		name: "opLog",
+
+		/**
+		 * Get the storage adapter.
+		 */
+		getStorage(): OpLogStorage {
+			return storage;
+		},
+
+		/**
+		 * Get version for an entity.
+		 */
+		async getVersion(entity: string, entityId: string): Promise<number> {
+			return storage.getVersion(entity, entityId);
+		},
+
+		/**
+		 * Get current canonical state for an entity.
+		 */
+		async getState(entity: string, entityId: string): Promise<Record<string, unknown> | null> {
+			return storage.getState(entity, entityId);
+		},
+
+		/**
+		 * Get latest patch for an entity.
+		 */
+		async getLatestPatch(entity: string, entityId: string): Promise<PatchOperation[] | null> {
+			return storage.getLatestPatch(entity, entityId);
+		},
+
+		/**
+		 * Handle broadcast - update canonical state and return patch info.
+		 * Handler is responsible for routing to subscribers.
+		 */
+		async onBroadcast(ctx: BroadcastContext): Promise<BroadcastResult> {
+			const { entity, entityId, data } = ctx;
+
+			log("onBroadcast:", entity, entityId);
+
+			// Update canonical state (computes and logs patch)
+			const result = await storage.emit(entity, entityId, data);
+
+			log("  Version:", result.version, "Patch ops:", result.patch?.length ?? 0);
+
+			return {
+				version: result.version,
+				patch: result.patch,
+				data,
+			};
+		},
+
+		/**
+		 * Handle reconnection - return patches or snapshot based on client's version.
+		 */
+		async onReconnect(ctx: ReconnectContext): Promise<ReconnectHookResult[]> {
+			log("Reconnect:", ctx.clientId, "subscriptions:", ctx.subscriptions.length);
+
+			const results: ReconnectHookResult[] = [];
+
+			for (const sub of ctx.subscriptions) {
+				const currentVersion = await storage.getVersion(sub.entity, sub.entityId);
+				const currentState = await storage.getState(sub.entity, sub.entityId);
+
+				// Entity doesn't exist (might have been deleted)
+				if (currentState === null) {
+					results.push({
+						id: sub.id,
+						entity: sub.entity,
+						entityId: sub.entityId,
+						status: "deleted",
+						version: 0,
+					});
+					log("  Subscription", sub.id, `${sub.entity}:${sub.entityId}`, "status: deleted");
+					continue;
+				}
+
+				// Client is already at latest version
+				if (sub.version >= currentVersion) {
+					results.push({
+						id: sub.id,
+						entity: sub.entity,
+						entityId: sub.entityId,
+						status: "current",
+						version: currentVersion,
+					});
+					log(
+						"  Subscription",
+						sub.id,
+						`${sub.entity}:${sub.entityId}`,
+						"status: current",
+						"version:",
+						currentVersion,
+					);
+					continue;
+				}
+
+				// Try to get patches from operation log
+				const patches = await storage.getPatchesSince(sub.entity, sub.entityId, sub.version);
+
+				if (patches !== null && patches.length > 0) {
+					// Can patch - return patches
+					results.push({
+						id: sub.id,
+						entity: sub.entity,
+						entityId: sub.entityId,
+						status: "patched",
+						version: currentVersion,
+						patches,
+					});
+					log(
+						"  Subscription",
+						sub.id,
+						`${sub.entity}:${sub.entityId}`,
+						"status: patched",
+						"version:",
+						currentVersion,
+						"patches:",
+						patches.length,
+					);
+					continue;
+				}
+
+				// Patches not available - send full snapshot
+				results.push({
+					id: sub.id,
+					entity: sub.entity,
+					entityId: sub.entityId,
+					status: "snapshot",
+					version: currentVersion,
+					data: currentState,
+				});
+				log(
+					"  Subscription",
+					sub.id,
+					`${sub.entity}:${sub.entityId}`,
+					"status: snapshot",
+					"version:",
+					currentVersion,
+				);
+			}
+
+			return results;
+		},
+	};
+}
+
+/**
+ * Check if a plugin is an opLog plugin.
+ */
+export function isOpLogPlugin(plugin: ServerPlugin): plugin is OpLogPlugin {
+	return plugin.name === "opLog" && "getStorage" in plugin;
+}