freesail 0.0.1 → 0.1.0

package/packages/server/src/stream.ts

@@ -0,0 +1,329 @@
+/**
+ * SSE Stream Implementation
+ * 
+ * Manages Server-Sent Events connections with backpressure handling.
+ */
+
+import type { ServerResponse } from 'http';
+import type { ServerToClientMessage } from '@freesail/core';
+
+export interface StreamOptions {
+  /** Response object to write to */
+  response: ServerResponse;
+  /** Session/connection identifier */
+  sessionId?: string;
+  /** Keep-alive interval in ms (default: 15000) */
+  keepAliveInterval?: number;
+  /** Enable debug logging */
+  debug?: boolean;
+}
+
+export interface StreamStats {
+  messagesSent: number;
+  bytesWritten: number;
+  createdAt: number;
+  lastMessageAt: number | null;
+}
+
+/**
+ * FreesailStream manages an SSE connection with a client.
+ * It handles message serialization, backpressure, and keep-alive.
+ */
+export class FreesailStream {
+  private res: ServerResponse;
+  private sessionId: string;
+  private keepAliveTimer: ReturnType<typeof setInterval> | null = null;
+  private debug: boolean;
+  private _closed: boolean = false;
+  private _stats: StreamStats;
+
+  constructor(options: StreamOptions) {
+    this.res = options.response;
+    this.sessionId = options.sessionId ?? this.generateId();
+    this.debug = options.debug ?? false;
+    
+    this._stats = {
+      messagesSent: 0,
+      bytesWritten: 0,
+      createdAt: Date.now(),
+      lastMessageAt: null,
+    };
+
+    // Initialize SSE headers
+    this.initializeSSE();
+
+    // Start keep-alive
+    if (options.keepAliveInterval !== 0) {
+      this.startKeepAlive(options.keepAliveInterval ?? 15000);
+    }
+
+    // Handle connection close
+    this.res.on('close', () => {
+      this.close();
+    });
+  }
+
+  /**
+   * Send an A2UX message to the client
+   */
+  send(message: ServerToClientMessage): boolean {
+    if (this._closed) {
+      this.log('Cannot send to closed stream');
+      return false;
+    }
+
+    try {
+      const data = JSON.stringify(message);
+      const payload = `data: ${data}\n\n`;
+      
+      this.res.write(payload);
+      
+      this._stats.messagesSent++;
+      this._stats.bytesWritten += payload.length;
+      this._stats.lastMessageAt = Date.now();
+      
+      this.log(`Sent: ${Object.keys(message)[0]}`);
+      return true;
+    } catch (error) {
+      this.log(`Send error: ${error}`);
+      return false;
+    }
+  }
+
+  /**
+   * Send a createSurface message
+   */
+  createSurface(surfaceId: string, catalogId: string): boolean {
+    return this.send({
+      createSurface: { surfaceId, catalogId }
+    });
+  }
+
+  /**
+   * Send an updateComponents message
+   */
+  updateComponents(
+    surfaceId: string, 
+    components: ServerToClientMessage extends { updateComponents: infer U } 
+      ? U extends { components: infer C } ? C : never 
+      : never
+  ): boolean {
+    return this.send({
+      updateComponents: { surfaceId, components }
+    });
+  }
+
+  /**
+   * Send an updateDataModel message
+   */
+  updateDataModel(
+    surfaceId: string,
+    value: unknown,
+    path?: string,
+    op?: 'add' | 'replace' | 'remove'
+  ): boolean {
+    return this.send({
+      updateDataModel: { 
+        surfaceId, 
+        path: path ?? '/',
+        op: op ?? 'replace',
+        value 
+      }
+    });
+  }
+
+  /**
+   * Send a deleteSurface message
+   */
+  deleteSurface(surfaceId: string): boolean {
+    return this.send({
+      deleteSurface: { surfaceId }
+    });
+  }
+
+  /**
+   * Send a watchSurface message
+   */
+  watchSurface(surfaceId: string, interval?: number, expiresIn?: number): boolean {
+    return this.send({
+      watchSurface: { surfaceId, interval, expiresIn }
+    });
+  }
+
+  /**
+   * Send an unwatchSurface message
+   */
+  unwatchSurface(surfaceId: string): boolean {
+    return this.send({
+      unwatchSurface: { surfaceId }
+    });
+  }
+
+  /**
+   * Send raw data (for custom events)
+   */
+  sendRaw(event: string, data: unknown): boolean {
+    if (this._closed) return false;
+
+    try {
+      const payload = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+      this.res.write(payload);
+      this._stats.bytesWritten += payload.length;
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Send done signal and close stream
+   */
+  done(): void {
+    if (this._closed) return;
+    
+    this.res.write('data: [DONE]\n\n');
+    this.close();
+  }
+
+  /**
+   * Close the stream
+   */
+  close(): void {
+    if (this._closed) return;
+    
+    this._closed = true;
+    this.stopKeepAlive();
+    
+    if (!this.res.writableEnded) {
+      this.res.end();
+    }
+    
+    this.log('Stream closed');
+  }
+
+  /**
+   * Check if stream is closed
+   */
+  get closed(): boolean {
+    return this._closed;
+  }
+
+  /**
+   * Get session ID
+   */
+  get id(): string {
+    return this.sessionId;
+  }
+
+  /**
+   * Get stream statistics
+   */
+  get stats(): StreamStats {
+    return { ...this._stats };
+  }
+
+  // ===========================================================================
+  // Private Methods
+  // ===========================================================================
+
+  private initializeSSE(): void {
+    this.res.setHeader('Content-Type', 'text/event-stream');
+    this.res.setHeader('Cache-Control', 'no-cache');
+    this.res.setHeader('Connection', 'keep-alive');
+    this.res.setHeader('X-Accel-Buffering', 'no'); // Disable nginx buffering
+    this.res.flushHeaders();
+    
+    this.log('SSE initialized');
+  }
+
+  private startKeepAlive(interval: number): void {
+    this.keepAliveTimer = setInterval(() => {
+      if (!this._closed) {
+        this.res.write(': keep-alive\n\n');
+      }
+    }, interval);
+  }
+
+  private stopKeepAlive(): void {
+    if (this.keepAliveTimer) {
+      clearInterval(this.keepAliveTimer);
+      this.keepAliveTimer = null;
+    }
+  }
+
+  private generateId(): string {
+    return `fs_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`;
+  }
+
+  private log(message: string): void {
+    if (this.debug) {
+      console.log(`[FreesailStream:${this.sessionId}] ${message}`);
+    }
+  }
+}
+
+// =============================================================================
+// Stream Store (for managing multiple connections)
+// =============================================================================
+
+/**
+ * StreamStore manages multiple SSE connections
+ */
+export class StreamStore {
+  private streams: Map<string, FreesailStream> = new Map();
+
+  /**
+   * Create and register a new stream
+   */
+  create(options: StreamOptions): FreesailStream {
+    const stream = new FreesailStream(options);
+    this.streams.set(stream.id, stream);
+    
+    // Auto-remove on close
+    options.response.on('close', () => {
+      this.streams.delete(stream.id);
+    });
+    
+    return stream;
+  }
+
+  /**
+   * Get a stream by ID
+   */
+  get(streamId: string): FreesailStream | undefined {
+    return this.streams.get(streamId);
+  }
+
+  /**
+   * Get all active streams
+   */
+  getAll(): FreesailStream[] {
+    return Array.from(this.streams.values());
+  }
+
+  /**
+   * Get stream count
+   */
+  get count(): number {
+    return this.streams.size;
+  }
+
+  /**
+   * Broadcast message to all streams
+   */
+  broadcast(message: ServerToClientMessage): void {
+    for (const stream of this.streams.values()) {
+      stream.send(message);
+    }
+  }
+
+  /**
+   * Close all streams
+   */
+  closeAll(): void {
+    for (const stream of this.streams.values()) {
+      stream.close();
+    }
+    this.streams.clear();
+  }
+}

package/packages/server/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "composite": true,
+    "lib": ["ES2022"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}

package/tsconfig.base.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "noImplicitAny": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "experimentalDecorators": true,
+    "useDefineForClassFields": false
+  }
+}

package/index.js

@@ -1,3 +0,0 @@
-// index.js
-console.log("Freesail is currently in Alpha. Please check back later.");
-module.exports = {};