@hypen-space/core 0.2.11 → 0.3.0

package/src/remote/session.ts

@@ -0,0 +1,256 @@
+/**
+ * Session Management for Remote UI
+ *
+ * Manages session lifecycle including:
+ * - Creating new sessions
+ * - Suspending sessions on disconnect (pending reconnection)
+ * - Resuming sessions on reconnect
+ * - Expiring sessions after TTL
+ * - Handling concurrent connections
+ */
+
+import type { Session, SessionConfig } from "./types.js";
+
+/**
+ * Internal representation of a pending (disconnected) session
+ */
+interface PendingSession {
+  session: Session;
+  savedState: unknown;
+  expiryTimer: ReturnType<typeof setTimeout>;
+}
+
+/**
+ * Callback invoked when a session expires
+ */
+export type SessionExpireCallback = (session: Session) => void | Promise<void>;
+
+/**
+ * Manages session lifecycle for remote UI connections
+ */
+export class SessionManager {
+  /** Active sessions (currently connected) */
+  private activeSessions = new Map<string, Session>();
+
+  /** Pending sessions (disconnected, waiting for reconnect within TTL) */
+  private pendingSessions = new Map<string, PendingSession>();
+
+  /** Maps session ID to connected WebSocket(s) for concurrent handling */
+  private sessionConnections = new Map<string, Set<unknown>>();
+
+  /** Resolved configuration with defaults */
+  private config: Required<SessionConfig>;
+
+  constructor(config: SessionConfig = {}) {
+    this.config = {
+      ttl: config.ttl ?? 3600, // 1 hour default
+      concurrent: config.concurrent ?? "kick-old",
+      generateId: config.generateId ?? (() => crypto.randomUUID()),
+    };
+  }
+
+  /**
+   * Get the configured TTL in seconds
+   */
+  getTtl(): number {
+    return this.config.ttl;
+  }
+
+  /**
+   * Get the concurrent connection policy
+   */
+  getConcurrentPolicy(): "kick-old" | "reject-new" | "allow-multiple" {
+    return this.config.concurrent;
+  }
+
+  /**
+   * Create a new session
+   */
+  createSession(props?: Record<string, any>): Session {
+    const now = new Date();
+    const session: Session = {
+      id: this.config.generateId(),
+      ttl: this.config.ttl,
+      createdAt: now,
+      lastConnectedAt: now,
+      props,
+    };
+    this.activeSessions.set(session.id, session);
+    return session;
+  }
+
+  /**
+   * Get an active (connected) session by ID
+   */
+  getActiveSession(id: string): Session | null {
+    return this.activeSessions.get(id) ?? null;
+  }
+
+  /**
+   * Get a pending (disconnected) session by ID
+   */
+  getPendingSession(id: string): PendingSession | null {
+    return this.pendingSessions.get(id) ?? null;
+  }
+
+  /**
+   * Check if a session exists (either active or pending)
+   */
+  hasSession(id: string): boolean {
+    return this.activeSessions.has(id) || this.pendingSessions.has(id);
+  }
+
+  /**
+   * Suspend a session when client disconnects
+   * Moves from active to pending with a TTL timer
+   *
+   * @param sessionId - The session to suspend
+   * @param savedState - State snapshot to restore on reconnect
+   * @param onExpire - Callback when TTL expires
+   */
+  suspendSession(
+    sessionId: string,
+    savedState: unknown,
+    onExpire: SessionExpireCallback
+  ): void {
+    const session = this.activeSessions.get(sessionId);
+    if (!session) return;
+
+    // Remove from active
+    this.activeSessions.delete(sessionId);
+
+    // Set up expiry timer
+    const expiryTimer = setTimeout(async () => {
+      const pending = this.pendingSessions.get(sessionId);
+      if (pending) {
+        this.pendingSessions.delete(sessionId);
+        await onExpire(pending.session);
+      }
+    }, session.ttl * 1000);
+
+    // Add to pending
+    this.pendingSessions.set(sessionId, {
+      session,
+      savedState,
+      expiryTimer,
+    });
+  }
+
+  /**
+   * Resume a pending session when client reconnects
+   *
+   * @param sessionId - The session to resume
+   * @returns Session and saved state, or null if not found/expired
+   */
+  resumeSession(
+    sessionId: string
+  ): { session: Session; savedState: unknown } | null {
+    const pending = this.pendingSessions.get(sessionId);
+    if (!pending) return null;
+
+    // Clear expiry timer
+    clearTimeout(pending.expiryTimer);
+    this.pendingSessions.delete(sessionId);
+
+    // Update last connected time
+    pending.session.lastConnectedAt = new Date();
+
+    // Move back to active
+    this.activeSessions.set(sessionId, pending.session);
+
+    return {
+      session: pending.session,
+      savedState: pending.savedState,
+    };
+  }
+
+  /**
+   * Destroy a session completely (both active and pending)
+   */
+  destroySession(sessionId: string): void {
+    this.activeSessions.delete(sessionId);
+
+    const pending = this.pendingSessions.get(sessionId);
+    if (pending) {
+      clearTimeout(pending.expiryTimer);
+      this.pendingSessions.delete(sessionId);
+    }
+
+    this.sessionConnections.delete(sessionId);
+  }
+
+  /**
+   * Track a WebSocket connection for a session
+   * Used for concurrent connection handling
+   */
+  trackConnection(sessionId: string, ws: unknown): void {
+    let connections = this.sessionConnections.get(sessionId);
+    if (!connections) {
+      connections = new Set();
+      this.sessionConnections.set(sessionId, connections);
+    }
+    connections.add(ws);
+  }
+
+  /**
+   * Untrack a WebSocket connection
+   */
+  untrackConnection(sessionId: string, ws: unknown): void {
+    const connections = this.sessionConnections.get(sessionId);
+    if (connections) {
+      connections.delete(ws);
+      if (connections.size === 0) {
+        this.sessionConnections.delete(sessionId);
+      }
+    }
+  }
+
+  /**
+   * Get all connections for a session
+   */
+  getConnections(sessionId: string): Set<unknown> | undefined {
+    return this.sessionConnections.get(sessionId);
+  }
+
+  /**
+   * Get connection count for a session
+   */
+  getConnectionCount(sessionId: string): number {
+    return this.sessionConnections.get(sessionId)?.size ?? 0;
+  }
+
+  /**
+   * Get stats about current sessions
+   */
+  getStats(): {
+    activeSessions: number;
+    pendingSessions: number;
+    totalConnections: number;
+  } {
+    let totalConnections = 0;
+    for (const connections of this.sessionConnections.values()) {
+      totalConnections += connections.size;
+    }
+
+    return {
+      activeSessions: this.activeSessions.size,
+      pendingSessions: this.pendingSessions.size,
+      totalConnections,
+    };
+  }
+
+  /**
+   * Clean up all sessions and timers
+   * Call this when shutting down the server
+   */
+  destroy(): void {
+    // Clear all pending session timers
+    for (const pending of this.pendingSessions.values()) {
+      clearTimeout(pending.expiryTimer);
+    }
+
+    this.activeSessions.clear();
+    this.pendingSessions.clear();
+    this.sessionConnections.clear();
+  }
+}

package/src/remote/types.ts

@@ -8,7 +8,10 @@ export type RemoteMessage =
   | InitialTreeMessage
   | PatchMessage
   | StateUpdateMessage
-  | DispatchActionMessage;
+  | DispatchActionMessage
+  | HelloMessage
+  | SessionAckMessage
+  | SessionExpiredMessage;
 
 export interface InitialTreeMessage {
   type: "initialTree";
@@ -39,6 +42,70 @@ export interface DispatchActionMessage {
   payload?: any;
 }
 
+/**
+ * Client → Server: First message after WebSocket opens
+ * Used to establish or resume a session
+ */
+export interface HelloMessage {
+  type: "hello";
+  /** Session ID to resume (omit for new session) */
+  sessionId?: string;
+  /** Client metadata (platform, version, userId, etc.) */
+  props?: Record<string, any>;
+}
+
+/**
+ * Server → Client: Response to HelloMessage
+ * Confirms session establishment
+ */
+export interface SessionAckMessage {
+  type: "sessionAck";
+  /** The session ID (generated or resumed) */
+  sessionId: string;
+  /** True if this is a new session */
+  isNew: boolean;
+  /** True if state was restored from a previous session */
+  isRestored: boolean;
+}
+
+/**
+ * Server → Client: Session termination notification
+ * Sent when session is kicked or expires
+ */
+export interface SessionExpiredMessage {
+  type: "sessionExpired";
+  sessionId: string;
+  reason: "ttl" | "kicked" | "manual";
+}
+
+/**
+ * Session information passed to lifecycle hooks
+ */
+export interface Session {
+  /** Unique session identifier */
+  id: string;
+  /** Time-to-live in seconds */
+  ttl: number;
+  /** When the session was first created */
+  createdAt: Date;
+  /** When the client last connected */
+  lastConnectedAt: Date;
+  /** Client-provided metadata */
+  props?: Record<string, any>;
+}
+
+/**
+ * Configuration for session management
+ */
+export interface SessionConfig {
+  /** Session TTL in seconds (default: 3600 = 1 hour) */
+  ttl?: number;
+  /** How to handle concurrent connections with same sessionId */
+  concurrent?: "kick-old" | "reject-new" | "allow-multiple";
+  /** Custom session ID generator */
+  generateId?: () => string;
+}
+
 export interface RemoteClient {
   id: string;
   socket: any;

package/src/result.ts

@@ -0,0 +1,260 @@
+/**
+ * Result Type for Error Handling
+ *
+ * A lightweight Result type for explicit error handling without exceptions.
+ * Provides type-safe error propagation and composition.
+ */
+
+/**
+ * Represents either a successful value or an error
+ */
+export type Result<T, E = Error> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: E };
+
+/**
+ * Create a successful Result
+ */
+export function Ok<T>(value: T): Result<T, never> {
+  return { ok: true, value };
+}
+
+/**
+ * Create a failed Result
+ */
+export function Err<E>(error: E): Result<never, E> {
+  return { ok: false, error };
+}
+
+/**
+ * Check if a Result is Ok
+ */
+export function isOk<T, E>(result: Result<T, E>): result is { ok: true; value: T } {
+  return result.ok;
+}
+
+/**
+ * Check if a Result is Err
+ */
+export function isErr<T, E>(result: Result<T, E>): result is { ok: false; error: E } {
+  return !result.ok;
+}
+
+/**
+ * Wrap a Promise in a Result, catching any thrown errors
+ */
+export async function fromPromise<T, E = Error>(
+  promise: Promise<T>,
+  mapError?: (e: unknown) => E
+): Promise<Result<T, E>> {
+  try {
+    const value = await promise;
+    return Ok(value);
+  } catch (e) {
+    if (mapError) {
+      return Err(mapError(e));
+    }
+    return Err(e as E);
+  }
+}
+
+/**
+ * Wrap a synchronous function in a Result, catching any thrown errors
+ */
+export function fromTry<T, E = Error>(
+  fn: () => T,
+  mapError?: (e: unknown) => E
+): Result<T, E> {
+  try {
+    return Ok(fn());
+  } catch (e) {
+    if (mapError) {
+      return Err(mapError(e));
+    }
+    return Err(e as E);
+  }
+}
+
+/**
+ * Map over a successful Result value
+ */
+export function map<T, U, E>(
+  result: Result<T, E>,
+  fn: (value: T) => U
+): Result<U, E> {
+  if (result.ok) {
+    return Ok(fn(result.value));
+  }
+  return result;
+}
+
+/**
+ * Map over a failed Result error
+ */
+export function mapErr<T, E, F>(
+  result: Result<T, E>,
+  fn: (error: E) => F
+): Result<T, F> {
+  if (!result.ok) {
+    return Err(fn(result.error));
+  }
+  return result;
+}
+
+/**
+ * Chain Results together (flatMap)
+ */
+export function flatMap<T, U, E>(
+  result: Result<T, E>,
+  fn: (value: T) => Result<U, E>
+): Result<U, E> {
+  if (result.ok) {
+    return fn(result.value);
+  }
+  return result;
+}
+
+/**
+ * Unwrap a Result, throwing if it's an error
+ */
+export function unwrap<T, E>(result: Result<T, E>): T {
+  if (result.ok) {
+    return result.value;
+  }
+  throw result.error;
+}
+
+/**
+ * Unwrap a Result with a default value
+ */
+export function unwrapOr<T, E>(result: Result<T, E>, defaultValue: T): T {
+  if (result.ok) {
+    return result.value;
+  }
+  return defaultValue;
+}
+
+/**
+ * Unwrap a Result with a lazy default value
+ */
+export function unwrapOrElse<T, E>(result: Result<T, E>, fn: (error: E) => T): T {
+  if (result.ok) {
+    return result.value;
+  }
+  return fn(result.error);
+}
+
+/**
+ * Match on a Result, providing handlers for both cases
+ */
+export function match<T, E, U>(
+  result: Result<T, E>,
+  handlers: {
+    ok: (value: T) => U;
+    err: (error: E) => U;
+  }
+): U {
+  if (result.ok) {
+    return handlers.ok(result.value);
+  }
+  return handlers.err(result.error);
+}
+
+/**
+ * Combine multiple Results into a single Result containing an array
+ * Returns the first error encountered, or Ok with all values
+ */
+export function all<T, E>(results: Result<T, E>[]): Result<T[], E> {
+  const values: T[] = [];
+  for (const result of results) {
+    if (!result.ok) {
+      return result;
+    }
+    values.push(result.value);
+  }
+  return Ok(values);
+}
+
+/**
+ * Base class for typed errors with context
+ */
+export class HypenError extends Error {
+  readonly code: string;
+  readonly context?: Record<string, unknown>;
+  override readonly cause?: Error;
+
+  constructor(
+    code: string,
+    message: string,
+    options?: { context?: Record<string, unknown>; cause?: Error }
+  ) {
+    super(message);
+    this.name = 'HypenError';
+    this.code = code;
+    this.context = options?.context;
+    this.cause = options?.cause;
+
+    // Maintain proper prototype chain
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+/**
+ * Error thrown when an action handler fails
+ */
+export class ActionError extends HypenError {
+  readonly actionName: string;
+
+  constructor(actionName: string, cause?: unknown) {
+    super(
+      'ACTION_ERROR',
+      `Action handler "${actionName}" failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+      {
+        context: { actionName },
+        cause: cause instanceof Error ? cause : undefined,
+      }
+    );
+    this.name = 'ActionError';
+    this.actionName = actionName;
+  }
+}
+
+/**
+ * Error thrown when a connection fails
+ */
+export class ConnectionError extends HypenError {
+  readonly url: string;
+  readonly attempt?: number;
+
+  constructor(url: string, cause?: unknown, attempt?: number) {
+    super(
+      'CONNECTION_ERROR',
+      `Connection to "${url}" failed${attempt ? ` (attempt ${attempt})` : ''}: ${
+        cause instanceof Error ? cause.message : String(cause)
+      }`,
+      {
+        context: { url, attempt },
+        cause: cause instanceof Error ? cause : undefined,
+      }
+    );
+    this.name = 'ConnectionError';
+    this.url = url;
+    this.attempt = attempt;
+  }
+}
+
+/**
+ * Error thrown when state operations fail
+ */
+export class StateError extends HypenError {
+  readonly path?: string;
+
+  constructor(message: string, path?: string, cause?: unknown) {
+    super('STATE_ERROR', message, {
+      context: { path },
+      cause: cause instanceof Error ? cause : undefined,
+    });
+    this.name = 'StateError';
+    this.path = path;
+  }
+}