@hypen-space/core 0.2.12 → 0.3.0

package/src/remote/client.ts

@@ -1,6 +1,30 @@
 /**
  * RemoteEngine - Connect to a remote Hypen app over WebSocket
  * Platform-agnostic client (uses standard WebSocket API)
+ *
+ * Usage:
+ * ```typescript
+ * const engine = new RemoteEngine("ws://localhost:3000", {
+ *   session: {
+ *     id: localStorage.getItem("sessionId") ?? undefined,
+ *     props: { platform: "web", version: "1.0" }
+ *   }
+ * });
+ *
+ * engine.onSessionEstablished(({ sessionId, isNew, isRestored }) => {
+ *   localStorage.setItem("sessionId", sessionId);
+ *   console.log(isRestored ? "Welcome back!" : "New session");
+ * });
+ *
+ * engine.onSessionExpired((reason) => {
+ *   localStorage.removeItem("sessionId");
+ * });
+ *
+ * const result = await engine.connect();
+ * if (!result.ok) {
+ *   console.error("Connection failed:", result.error);
+ * }
+ * ```
  */
 
 import type {
@@ -8,37 +32,95 @@ import type {
   InitialTreeMessage,
   PatchMessage,
   DispatchActionMessage,
+  HelloMessage,
+  SessionAckMessage,
+  SessionExpiredMessage,
 } from "./types.js";
 import type { Patch } from "../engine.js";
+import {
+  type Result,
+  Ok,
+  Err,
+  ConnectionError,
+} from "../result.js";
+import {
+  type Disposable,
+  DisposableStack,
+  disposableTimeout,
+  disposableWebSocket,
+  disposableListener,
+} from "../disposable.js";
+import { retry, type RetryOptions } from "../retry.js";
+
+export type RemoteConnectionState =
+  | "disconnected"
+  | "connecting"
+  | "connected"
+  | "error";
 
-export type RemoteConnectionState = "disconnected" | "connecting" | "connected" | "error";
+/**
+ * Session configuration for the client
+ */
+export interface SessionOptions {
+  /** Session ID to resume (omit for new session) */
+  id?: string;
+  /** Client metadata (platform, version, userId, etc.) */
+  props?: Record<string, unknown>;
+}
+
+/**
+ * Session information received from server
+ */
+export interface SessionInfo {
+  sessionId: string;
+  isNew: boolean;
+  isRestored: boolean;
+}
 
 export interface RemoteEngineOptions {
   autoReconnect?: boolean;
   reconnectInterval?: number;
   maxReconnectAttempts?: number;
+  /** Session configuration */
+  session?: SessionOptions;
+}
+
+interface RequiredOptions {
+  autoReconnect: boolean;
+  reconnectInterval: number;
+  maxReconnectAttempts: number;
+  session?: SessionOptions;
 }
 
 /**
  * Client-side engine that connects to a remote Hypen app
  */
-export class RemoteEngine {
+export class RemoteEngine implements Disposable {
   private ws: WebSocket | null = null;
-  private url: string;
+  private readonly url: string;
   private state: RemoteConnectionState = "disconnected";
-  private options: Required<RemoteEngineOptions>;
+  private readonly options: RequiredOptions;
   private reconnectAttempts = 0;
-  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+
+  // Resource management
+  private readonly disposables = new DisposableStack();
+  private reconnectDisposable: Disposable | null = null;
+
+  // Session state
+  private currentSessionId: string | null = null;
+  private readonly sessionOptions?: SessionOptions;
 
   // Callbacks
-  private patchCallbacks: Array<(patches: Patch[]) => void> = [];
-  private stateCallbacks: Array<(state: any) => void> = [];
-  private connectionCallbacks: Array<() => void> = [];
-  private disconnectionCallbacks: Array<() => void> = [];
-  private errorCallbacks: Array<(error: Error) => void> = [];
+  private readonly patchCallbacks: Array<(patches: Patch[]) => void> = [];
+  private readonly stateCallbacks: Array<(state: unknown) => void> = [];
+  private readonly connectionCallbacks: Array<() => void> = [];
+  private readonly disconnectionCallbacks: Array<() => void> = [];
+  private readonly errorCallbacks: Array<(error: Error) => void> = [];
+  private readonly sessionEstablishedCallbacks: Array<(info: SessionInfo) => void> = [];
+  private readonly sessionExpiredCallbacks: Array<(reason: string) => void> = [];
 
   // State
-  private currentState: any = null;
+  private currentState: unknown = null;
   private currentRevision = 0;
   private moduleName: string = "";
 
@@ -48,74 +130,136 @@ export class RemoteEngine {
       autoReconnect: options.autoReconnect ?? true,
       reconnectInterval: options.reconnectInterval ?? 3000,
       maxReconnectAttempts: options.maxReconnectAttempts ?? 10,
+      session: options.session,
     };
+    this.sessionOptions = options.session;
+
+    // If session ID was provided, use it as current
+    if (options.session?.id) {
+      this.currentSessionId = options.session.id;
+    }
   }
 
   /**
    * Connect to the remote server
+   * Returns a Result indicating success or failure
    */
-  async connect(): Promise<void> {
+  async connect(): Promise<Result<void, ConnectionError>> {
     if (this.state === "connected" || this.state === "connecting") {
-      return;
+      return Ok(undefined);
     }
 
     this.state = "connecting";
 
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve) => {
       try {
         this.ws = new WebSocket(this.url);
 
-        this.ws.onopen = () => {
-          this.state = "connected";
-          this.reconnectAttempts = 0;
-          this.connectionCallbacks.forEach((cb) => cb());
-          resolve();
-        };
+        // Track the WebSocket for cleanup
+        this.disposables.add(disposableWebSocket(this.ws));
 
-        this.ws.onmessage = (event) => {
+        // Set up message handler
+        const messageHandler = (event: MessageEvent) => {
           this.handleMessage(event.data);
         };
+        this.disposables.add(
+          disposableListener(this.ws, "message", messageHandler as EventListener)
+        );
 
-        this.ws.onerror = () => {
+        // Set up error handler
+        const errorHandler = () => {
           this.state = "error";
-          const error = new Error("WebSocket error");
+          const error = new ConnectionError(this.url, new Error("WebSocket error"));
           this.errorCallbacks.forEach((cb) => cb(error));
-          reject(error);
+          resolve(Err(error));
         };
+        this.disposables.add(
+          disposableListener(this.ws, "error", errorHandler)
+        );
 
-        this.ws.onclose = () => {
+        // Set up close handler
+        const closeHandler = () => {
           this.state = "disconnected";
           this.disconnectionCallbacks.forEach((cb) => cb());
           this.attemptReconnect();
         };
-      } catch (error) {
+        this.disposables.add(
+          disposableListener(this.ws, "close", closeHandler)
+        );
+
+        // Set up open handler
+        this.ws.onopen = () => {
+          this.state = "connected";
+          this.reconnectAttempts = 0;
+
+          // Cancel any pending reconnect
+          if (this.reconnectDisposable) {
+            this.reconnectDisposable.dispose();
+            this.reconnectDisposable = null;
+          }
+
+          // Send hello message with session info
+          this.sendHello();
+
+          this.connectionCallbacks.forEach((cb) => cb());
+          resolve(Ok(undefined));
+        };
+      } catch (e) {
         this.state = "error";
-        reject(error);
+        const error = new ConnectionError(this.url, e);
+        resolve(Err(error));
       }
     });
   }
 
   /**
-   * Disconnect from the remote server
+   * Send hello message to establish session
+   */
+  private sendHello(): void {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
+
+    const hello: HelloMessage = {
+      type: "hello",
+      sessionId: this.currentSessionId ?? this.sessionOptions?.id,
+      props: this.sessionOptions?.props,
+    };
+
+    this.ws.send(JSON.stringify(hello));
+  }
+
+  /**
+   * Disconnect from the remote server and clean up resources
    */
   disconnect(): void {
-    if (this.reconnectTimer) {
-      clearTimeout(this.reconnectTimer);
-      this.reconnectTimer = null;
+    // Cancel any pending reconnect
+    if (this.reconnectDisposable) {
+      this.reconnectDisposable.dispose();
+      this.reconnectDisposable = null;
     }
 
+    // Close WebSocket if open
     if (this.ws) {
-      this.ws.close();
+      if (this.ws.readyState === WebSocket.OPEN || this.ws.readyState === WebSocket.CONNECTING) {
+        this.ws.close();
+      }
       this.ws = null;
     }
 
     this.state = "disconnected";
   }
 
+  /**
+   * Dispose all resources (alias for disconnect)
+   */
+  dispose(): void {
+    this.disconnect();
+    this.disposables.dispose();
+  }
+
   /**
    * Dispatch an action to the remote server
    */
-  dispatchAction(action: string, payload?: any): void {
+  dispatchAction(action: string, payload?: unknown): void {
     if (this.state !== "connected" || !this.ws) {
       console.warn("Cannot dispatch action: not connected");
       return;
@@ -142,7 +286,7 @@ export class RemoteEngine {
   /**
    * Register callback for state updates
    */
-  onStateUpdate(callback: (state: any) => void): this {
+  onStateUpdate(callback: (state: unknown) => void): this {
     this.stateCallbacks.push(callback);
     return this;
   }
@@ -171,6 +315,24 @@ export class RemoteEngine {
     return this;
   }
 
+  /**
+   * Register callback for session establishment
+   * Called when server confirms session (new or resumed)
+   */
+  onSessionEstablished(callback: (info: SessionInfo) => void): this {
+    this.sessionEstablishedCallbacks.push(callback);
+    return this;
+  }
+
+  /**
+   * Register callback for session expiration
+   * Called when session is kicked or expires
+   */
+  onSessionExpired(callback: (reason: string) => void): this {
+    this.sessionExpiredCallbacks.push(callback);
+    return this;
+  }
+
   /**
    * Get current connection state
    */
@@ -181,7 +343,7 @@ export class RemoteEngine {
   /**
    * Get current app state
    */
-  getCurrentState(): any {
+  getCurrentState(): unknown {
     return this.currentState;
   }
 
@@ -192,11 +354,26 @@ export class RemoteEngine {
     return this.currentRevision;
   }
 
+  /**
+   * Get current session ID
+   */
+  getSessionId(): string | null {
+    return this.currentSessionId;
+  }
+
   private handleMessage(data: string): void {
     try {
       const message = JSON.parse(data) as RemoteMessage;
 
       switch (message.type) {
+        case "sessionAck":
+          this.handleSessionAck(message as SessionAckMessage);
+          break;
+
+        case "sessionExpired":
+          this.handleSessionExpired(message as SessionExpiredMessage);
+          break;
+
         case "initialTree":
           this.handleInitialTree(message as InitialTreeMessage);
           break;
@@ -206,18 +383,34 @@ export class RemoteEngine {
           break;
 
         case "stateUpdate":
-          this.currentState = message.state;
-          this.stateCallbacks.forEach((cb) => cb(message.state));
+          this.currentState = (message as { state: unknown }).state;
+          this.stateCallbacks.forEach((cb) => cb(this.currentState));
           break;
       }
-    } catch (error) {
-      console.error("Error handling remote message:", error);
-      this.errorCallbacks.forEach((cb) =>
-        cb(error instanceof Error ? error : new Error(String(error)))
-      );
+    } catch (e) {
+      console.error("Error handling remote message:", e);
+      const error = e instanceof Error ? e : new Error(String(e));
+      this.errorCallbacks.forEach((cb) => cb(error));
     }
   }
 
+  private handleSessionAck(message: SessionAckMessage): void {
+    this.currentSessionId = message.sessionId;
+
+    const info: SessionInfo = {
+      sessionId: message.sessionId,
+      isNew: message.isNew,
+      isRestored: message.isRestored,
+    };
+
+    this.sessionEstablishedCallbacks.forEach((cb) => cb(info));
+  }
+
+  private handleSessionExpired(message: SessionExpiredMessage): void {
+    this.currentSessionId = null;
+    this.sessionExpiredCallbacks.forEach((cb) => cb(message.reason));
+  }
+
   private handleInitialTree(message: InitialTreeMessage): void {
     this.moduleName = message.module;
     this.currentState = message.state;
@@ -254,20 +447,34 @@ export class RemoteEngine {
       return;
     }
 
-    if (this.reconnectAttempts >= this.options.maxReconnectAttempts) {
-      console.error("Max reconnection attempts reached");
-      return;
-    }
-
-    this.reconnectAttempts++;
-
-    console.log(
-      `Attempting to reconnect (${this.reconnectAttempts}/${this.options.maxReconnectAttempts})...`
-    );
-
-    this.reconnectTimer = setTimeout(() => {
-      this.connect().catch((error) => {
-        console.error("Reconnection failed:", error);
+    // Use disposable timeout to start reconnection after initial delay
+    this.reconnectDisposable = disposableTimeout(() => {
+      this.reconnectDisposable = null;
+
+      retry(
+        async () => {
+          const result = await this.connect();
+          if (!result.ok) {
+            throw result.error;
+          }
+        },
+        {
+          maxAttempts: this.options.maxReconnectAttempts,
+          delayMs: this.options.reconnectInterval,
+          backoff: "exponential",
+          maxDelayMs: 30000,
+          jitter: 0.1,
+          onRetry: (attempt, error) => {
+            console.log(
+              `Reconnection attempt ${attempt}/${this.options.maxReconnectAttempts} failed: ${error.message}`
+            );
+          },
+        }
+      ).catch((error) => {
+        console.error("Max reconnection attempts reached:", error.message);
+        this.errorCallbacks.forEach((cb) =>
+          cb(new ConnectionError(this.url, error, this.options.maxReconnectAttempts))
+        );
       });
     }, this.options.reconnectInterval);
   }

package/src/remote/index.ts

@@ -2,16 +2,40 @@
  * Remote UI streaming for Hypen
  *
  * Client-side: Connect to remote Hypen apps
+ * Server-side: Stream Hypen apps over WebSocket
  */
 
+// Client
 export { RemoteEngine } from "./client.js";
+export type {
+  RemoteConnectionState,
+  RemoteEngineOptions,
+  SessionOptions,
+  SessionInfo,
+} from "./client.js";
+
+// Server
+export { RemoteServer, serve } from "./server.js";
+
+// Session Management
+export { SessionManager } from "./session.js";
+export type { SessionExpireCallback } from "./session.js";
+
+// Types
 export type {
   RemoteMessage,
   InitialTreeMessage,
   PatchMessage,
   DispatchActionMessage,
   StateUpdateMessage,
+  HelloMessage,
+  SessionAckMessage,
+  SessionExpiredMessage,
+  Session,
+  SessionConfig,
   RemoteClient,
   RemoteServerConfig,
 } from "./types.js";
-export type { RemoteConnectionState, RemoteEngineOptions } from "./client.js";
+
+// Re-export Patch type from engine
+export type { Patch } from "../engine.js";