@sylphx/lens-server 1.11.3 → 2.1.0

package/src/handlers/index.ts

@@ -0,0 +1,55 @@
+/**
+ * @sylphx/lens-server - Handlers
+ *
+ * Protocol handlers for bridging the Lens app to various transports.
+ */
+
+// =============================================================================
+// Unified Handler (HTTP + SSE)
+// =============================================================================
+
+export { createHandler, type Handler, type HandlerOptions } from "./unified.js";
+
+// =============================================================================
+// Framework Handler Utilities
+// =============================================================================
+
+export {
+	createFrameworkHandler,
+	createServerClientProxy,
+	type FrameworkHandlerOptions,
+	handleWebMutation,
+	handleWebQuery,
+	handleWebSSE,
+} from "./framework.js";
+
+// =============================================================================
+// SSE Handler
+// =============================================================================
+
+export {
+	createSSEHandler,
+	type SSEClient,
+	SSEHandler,
+	type SSEHandlerConfig as SSEHandlerOptions,
+} from "../sse/handler.js";
+
+// =============================================================================
+// HTTP Handler
+// =============================================================================
+
+export {
+	createHTTPHandler,
+	type HTTPHandler,
+	type HTTPHandlerOptions,
+} from "./http.js";
+
+// =============================================================================
+// WebSocket Handler
+// =============================================================================
+
+export {
+	createWSHandler,
+	type WSHandler,
+	type WSHandlerOptions,
+} from "./ws.js";

package/src/handlers/unified.ts

@@ -0,0 +1,114 @@
+/**
+ * @sylphx/lens-server - Unified Handler
+ *
+ * Creates a combined HTTP + SSE handler from a Lens app.
+ * Pure routing - no state management.
+ */
+
+import type { LensServer } from "../server/create.js";
+import { type SSEClient, SSEHandler } from "../sse/handler.js";
+import { createHTTPHandler, type HTTPHandlerOptions } from "./http.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface HandlerOptions extends HTTPHandlerOptions {
+	/**
+	 * SSE endpoint path.
+	 * Default: "/__lens/sse"
+	 */
+	ssePath?: string;
+
+	/**
+	 * Heartbeat interval for SSE connections in ms.
+	 * Default: 30000
+	 */
+	heartbeatInterval?: number;
+}
+
+export interface Handler {
+	/**
+	 * Handle HTTP/SSE request.
+	 * Compatible with fetch API (Bun, Cloudflare Workers, Vercel).
+	 */
+	(request: Request): Promise<Response>;
+
+	/**
+	 * Alternative method-style call.
+	 */
+	handle(request: Request): Promise<Response>;
+
+	/**
+	 * Access the SSE handler for manual operations.
+	 */
+	sse: SSEHandler;
+}
+
+// =============================================================================
+// Unified Handler Factory
+// =============================================================================
+
+/**
+ * Create a unified HTTP + SSE handler from a Lens app.
+ *
+ * Automatically routes:
+ * - GET {ssePath} → SSE connection
+ * - Other requests → HTTP handler
+ *
+ * @example
+ * ```typescript
+ * import { createApp, createHandler } from '@sylphx/lens-server'
+ *
+ * const app = createApp({ router })
+ * const handler = createHandler(app)
+ *
+ * // Bun
+ * Bun.serve({ port: 3000, fetch: handler })
+ *
+ * // SSE endpoint: GET /__lens/sse
+ * // HTTP endpoints: POST /, GET /__lens/metadata
+ * ```
+ */
+export function createHandler(server: LensServer, options: HandlerOptions = {}): Handler {
+	const { ssePath = "/__lens/sse", heartbeatInterval, ...httpOptions } = options;
+
+	const pathPrefix = httpOptions.pathPrefix ?? "";
+	const fullSsePath = `${pathPrefix}${ssePath}`;
+
+	// Create HTTP handler
+	const httpHandler = createHTTPHandler(server, httpOptions);
+
+	// Create SSE handler with plugin integration
+	const pluginManager = server.getPluginManager();
+	const sseHandler = new SSEHandler({
+		...(heartbeatInterval !== undefined && { heartbeatInterval }),
+		onConnect: (client: SSEClient) => {
+			// Notify plugins of connection
+			pluginManager.runOnConnect({ clientId: client.id });
+		},
+		onDisconnect: (clientId: string) => {
+			// Notify plugins of disconnection
+			pluginManager.runOnDisconnect({ clientId, subscriptionCount: 0 });
+		},
+	});
+
+	const handler = async (request: Request): Promise<Response> => {
+		const url = new URL(request.url);
+
+		// Route SSE requests
+		if (request.method === "GET" && url.pathname === fullSsePath) {
+			return sseHandler.handleConnection(request);
+		}
+
+		// All other requests go to HTTP handler
+		return httpHandler(request);
+	};
+
+	// Make it callable as both function and object
+	const result = handler as Handler;
+	result.handle = handler;
+	result.sse = sseHandler;
+
+	return result;
+}

package/src/handlers/ws-types.ts

@@ -0,0 +1,126 @@
+/**
+ * @sylphx/lens-server - WebSocket Handler Types
+ *
+ * Type definitions for WebSocket protocol handling.
+ */
+
+import type { ReconnectMessage } from "@sylphx/lens-core";
+import type { SelectionObject, WebSocketLike } from "../server/create.js";
+
+// =============================================================================
+// Handler Types
+// =============================================================================
+
+export interface WSHandlerOptions {
+	/**
+	 * Logger for debugging.
+	 */
+	logger?: {
+		info?: (message: string, ...args: unknown[]) => void;
+		warn?: (message: string, ...args: unknown[]) => void;
+		error?: (message: string, ...args: unknown[]) => void;
+	};
+}
+
+/**
+ * WebSocket adapter for Bun's websocket handler.
+ */
+export interface WSHandler {
+	/**
+	 * Handle a new WebSocket connection.
+	 * Call this when a WebSocket connection is established.
+	 */
+	handleConnection(ws: WebSocketLike): void;
+
+	/**
+	 * Bun-compatible websocket handler object.
+	 * Use directly with Bun.serve({ websocket: wsHandler.handler })
+	 */
+	handler: {
+		message(ws: unknown, message: string | Buffer): void;
+		close(ws: unknown): void;
+		open?(ws: unknown): void;
+	};
+
+	/**
+	 * Close all connections and cleanup.
+	 */
+	close(): Promise<void>;
+}
+
+// =============================================================================
+// Protocol Messages
+// =============================================================================
+
+export interface SubscribeMessage {
+	type: "subscribe";
+	id: string;
+	operation: string;
+	input?: unknown;
+	fields: string[] | "*";
+	select?: SelectionObject;
+}
+
+export interface UpdateFieldsMessage {
+	type: "updateFields";
+	id: string;
+	addFields?: string[];
+	removeFields?: string[];
+	setFields?: string[];
+}
+
+export interface UnsubscribeMessage {
+	type: "unsubscribe";
+	id: string;
+}
+
+export interface QueryMessage {
+	type: "query";
+	id: string;
+	operation: string;
+	input?: unknown;
+	fields?: string[] | "*";
+	select?: SelectionObject;
+}
+
+export interface MutationMessage {
+	type: "mutation";
+	id: string;
+	operation: string;
+	input: unknown;
+}
+
+export interface HandshakeMessage {
+	type: "handshake";
+	id: string;
+	clientVersion?: string;
+}
+
+export type ClientMessage =
+	| SubscribeMessage
+	| UpdateFieldsMessage
+	| UnsubscribeMessage
+	| QueryMessage
+	| MutationMessage
+	| HandshakeMessage
+	| ReconnectMessage;
+
+// =============================================================================
+// Client Connection
+// =============================================================================
+
+export interface ClientConnection {
+	id: string;
+	ws: WebSocketLike;
+	subscriptions: Map<string, ClientSubscription>;
+}
+
+export interface ClientSubscription {
+	id: string;
+	operation: string;
+	input: unknown;
+	fields: string[] | "*";
+	entityKeys: Set<string>;
+	cleanups: (() => void)[];
+	lastData: unknown;
+}