@agentxjs/node-platform 2.0.0

package/src/mq/SqliteMessageQueue.ts

@@ -0,0 +1,240 @@
+/**
+ * SqliteMessageQueue - RxJS-based message queue with SQLite persistence
+ *
+ * - In-memory pub/sub using RxJS Subject (real-time)
+ * - SQLite persistence for recovery guarantee
+ * - Consumer offset tracking for at-least-once delivery
+ */
+
+import { Subject } from "rxjs";
+import { filter } from "rxjs/operators";
+import type { MessageQueue, QueueEntry, QueueConfig, Unsubscribe } from "@agentxjs/core/mq";
+import { createLogger } from "commonxjs/logger";
+import { openDatabase, type Database } from "commonxjs/sqlite";
+import { OffsetGenerator } from "./OffsetGenerator";
+
+const logger = createLogger("node-platform/SqliteMessageQueue");
+
+interface ResolvedConfig {
+  path: string;
+  retentionMs: number;
+  cleanupIntervalMs: number;
+}
+
+/**
+ * SqliteMessageQueue implementation
+ */
+export class SqliteMessageQueue implements MessageQueue {
+  private readonly subject = new Subject<QueueEntry>();
+  private readonly offsetGen = new OffsetGenerator();
+  private readonly config: ResolvedConfig;
+  private readonly db: Database;
+  private cleanupTimer?: ReturnType<typeof setInterval>;
+  private isClosed = false;
+
+  private constructor(db: Database, config: ResolvedConfig) {
+    this.db = db;
+    this.config = config;
+
+    if (this.config.cleanupIntervalMs > 0) {
+      this.cleanupTimer = setInterval(() => {
+        this.cleanup();
+      }, this.config.cleanupIntervalMs);
+    }
+  }
+
+  /**
+   * Create a new SqliteMessageQueue instance
+   */
+  static create(path: string, config?: QueueConfig): SqliteMessageQueue {
+    const resolvedConfig: ResolvedConfig = {
+      path,
+      retentionMs: config?.retentionMs ?? 86400000, // 24 hours
+      cleanupIntervalMs: 300000, // 5 minutes
+    };
+
+    const db = openDatabase(resolvedConfig.path);
+    initializeSchema(db);
+
+    logger.info("SqliteMessageQueue created", { path: resolvedConfig.path });
+    return new SqliteMessageQueue(db, resolvedConfig);
+  }
+
+  async publish(topic: string, event: unknown): Promise<string> {
+    if (this.isClosed) {
+      logger.warn("Attempted to publish to closed queue", { topic });
+      return "";
+    }
+
+    const offset = this.offsetGen.generate();
+    const timestamp = Date.now();
+
+    const entry: QueueEntry = {
+      offset,
+      topic,
+      event,
+      timestamp,
+    };
+
+    // 1. Persist to SQLite (sync, fast)
+    try {
+      const eventJson = JSON.stringify(entry.event);
+      this.db
+        .prepare("INSERT INTO queue_entries (offset, topic, event, timestamp) VALUES (?, ?, ?, ?)")
+        .run(entry.offset, entry.topic, eventJson, entry.timestamp);
+    } catch (err) {
+      logger.error("Failed to persist entry", {
+        offset: entry.offset,
+        topic: entry.topic,
+        error: (err as Error).message,
+      });
+    }
+
+    // 2. Broadcast to subscribers (in-memory)
+    this.subject.next(entry);
+
+    return offset;
+  }
+
+  subscribe(topic: string, handler: (entry: QueueEntry) => void): Unsubscribe {
+    const subscription = this.subject.pipe(filter((entry) => entry.topic === topic)).subscribe({
+      next: (entry) => {
+        try {
+          handler(entry);
+        } catch (err) {
+          logger.error("Subscriber handler error", {
+            topic,
+            offset: entry.offset,
+            error: (err as Error).message,
+          });
+        }
+      },
+    });
+
+    logger.debug("Subscribed to topic", { topic });
+
+    return () => {
+      subscription.unsubscribe();
+      logger.debug("Unsubscribed from topic", { topic });
+    };
+  }
+
+  async ack(consumerId: string, topic: string, offset: string): Promise<void> {
+    const now = Date.now();
+
+    // Check if consumer exists
+    const existing = this.db
+      .prepare("SELECT 1 FROM queue_consumers WHERE consumer_id = ? AND topic = ?")
+      .get(consumerId, topic);
+
+    if (existing) {
+      this.db
+        .prepare(
+          "UPDATE queue_consumers SET offset = ?, updated_at = ? WHERE consumer_id = ? AND topic = ?"
+        )
+        .run(offset, now, consumerId, topic);
+    } else {
+      this.db
+        .prepare(
+          "INSERT INTO queue_consumers (consumer_id, topic, offset, updated_at) VALUES (?, ?, ?, ?)"
+        )
+        .run(consumerId, topic, offset, now);
+    }
+
+    logger.debug("Consumer acknowledged", { consumerId, topic, offset });
+  }
+
+  async getOffset(consumerId: string, topic: string): Promise<string | null> {
+    const row = this.db
+      .prepare("SELECT offset FROM queue_consumers WHERE consumer_id = ? AND topic = ?")
+      .get(consumerId, topic) as { offset: string } | undefined;
+
+    return row?.offset ?? null;
+  }
+
+  async recover(topic: string, afterOffset?: string, limit: number = 1000): Promise<QueueEntry[]> {
+    let rows: { offset: string; topic: string; event: string; timestamp: number }[];
+
+    if (afterOffset) {
+      rows = this.db
+        .prepare(
+          "SELECT offset, topic, event, timestamp FROM queue_entries WHERE topic = ? AND offset > ? ORDER BY offset ASC LIMIT ?"
+        )
+        .all(topic, afterOffset, limit) as typeof rows;
+    } else {
+      rows = this.db
+        .prepare(
+          "SELECT offset, topic, event, timestamp FROM queue_entries WHERE topic = ? ORDER BY offset ASC LIMIT ?"
+        )
+        .all(topic, limit) as typeof rows;
+    }
+
+    return rows.map((row) => ({
+      offset: row.offset,
+      topic: row.topic,
+      event: JSON.parse(row.event),
+      timestamp: row.timestamp,
+    }));
+  }
+
+  async close(): Promise<void> {
+    if (this.isClosed) return;
+    this.isClosed = true;
+
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+    }
+    this.subject.complete();
+    this.db.close();
+    logger.info("SqliteMessageQueue closed");
+  }
+
+  /**
+   * Cleanup old entries based on retention policy
+   */
+  private cleanup(): void {
+    try {
+      const cutoff = Date.now() - this.config.retentionMs;
+      const result = this.db.prepare("DELETE FROM queue_entries WHERE timestamp < ?").run(cutoff);
+
+      if (result.changes > 0) {
+        logger.debug("Cleaned up old entries", {
+          count: result.changes,
+          retentionMs: this.config.retentionMs,
+        });
+      }
+    } catch (err) {
+      logger.error("Cleanup failed", { error: (err as Error).message });
+    }
+  }
+}
+
+/**
+ * Initialize database schema
+ */
+function initializeSchema(db: Database): void {
+  db.exec(`
+    PRAGMA journal_mode=WAL;
+
+    CREATE TABLE IF NOT EXISTS queue_entries (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      offset TEXT NOT NULL UNIQUE,
+      topic TEXT NOT NULL,
+      event TEXT NOT NULL,
+      timestamp INTEGER NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_queue_topic_offset ON queue_entries(topic, offset);
+    CREATE INDEX IF NOT EXISTS idx_queue_timestamp ON queue_entries(timestamp);
+
+    CREATE TABLE IF NOT EXISTS queue_consumers (
+      consumer_id TEXT NOT NULL,
+      topic TEXT NOT NULL,
+      offset TEXT NOT NULL,
+      updated_at INTEGER NOT NULL,
+      PRIMARY KEY (consumer_id, topic)
+    );
+  `);
+
+  logger.debug("Queue database schema initialized");
+}

package/src/mq/index.ts

@@ -0,0 +1,30 @@
+/**
+ * MessageQueue Module
+ *
+ * SQLite-based message queue for Node.js.
+ *
+ * @example
+ * ```typescript
+ * import { SqliteMessageQueue } from "@agentxjs/node-platform/mq";
+ *
+ * const queue = SqliteMessageQueue.create("./data/queue.db");
+ *
+ * // Subscribe to topic
+ * queue.subscribe("session-123", (entry) => {
+ *   console.log(entry.event);
+ * });
+ *
+ * // Publish event
+ * const offset = await queue.publish("session-123", { type: "message", data: "hello" });
+ *
+ * // ACK after processing
+ * await queue.ack("connection-1", "session-123", offset);
+ *
+ * // Recover missed events
+ * const lastOffset = await queue.getOffset("connection-1", "session-123");
+ * const missed = await queue.recover("session-123", lastOffset);
+ * ```
+ */
+
+export { SqliteMessageQueue } from "./SqliteMessageQueue";
+export { OffsetGenerator } from "./OffsetGenerator";

package/src/network/WebSocketConnection.ts

@@ -0,0 +1,206 @@
+/**
+ * WebSocket Connection - Server-side connection wrapper
+ *
+ * Handles:
+ * - Heartbeat (ping/pong)
+ * - Reliable message delivery with ACK
+ * - Message routing
+ */
+
+import type { WebSocket as WS } from "ws";
+import type {
+  ChannelConnection,
+  ChannelServerOptions,
+  Unsubscribe,
+  SendReliableOptions,
+} from "@agentxjs/core/network";
+import { isAckMessage, type ReliableWrapper } from "@agentxjs/core/network";
+import { createLogger } from "commonxjs/logger";
+
+const logger = createLogger("node-platform/WebSocketConnection");
+
+/**
+ * WebSocket connection implementation
+ */
+export class WebSocketConnection implements ChannelConnection {
+  public readonly id: string;
+  private ws: WS;
+  private messageHandlers = new Set<(message: string) => void>();
+  private closeHandlers = new Set<() => void>();
+  private errorHandlers = new Set<(error: Error) => void>();
+  private heartbeatInterval?: ReturnType<typeof setInterval>;
+  private isAlive = true;
+  private pendingAcks = new Map<
+    string,
+    { resolve: () => void; timer: ReturnType<typeof setTimeout> }
+  >();
+  private msgIdCounter = 0;
+
+  constructor(ws: WS, options: ChannelServerOptions) {
+    this.ws = ws;
+    this.id = `conn_${Date.now()}_${Math.random().toString(36).substring(2, 8)}`;
+
+    this.setupHeartbeat(options);
+    this.setupMessageHandler();
+    this.setupCloseHandler();
+    this.setupErrorHandler();
+  }
+
+  private setupHeartbeat(options: ChannelServerOptions): void {
+    if (options.heartbeat === false) return;
+
+    const interval = options.heartbeatInterval || 30000;
+
+    this.ws.on("pong", () => {
+      this.isAlive = true;
+      logger.debug("Heartbeat pong received", { id: this.id });
+    });
+
+    this.heartbeatInterval = setInterval(() => {
+      if (!this.isAlive) {
+        logger.warn("Client heartbeat timeout, terminating connection", { id: this.id });
+        clearInterval(this.heartbeatInterval);
+        this.ws.terminate();
+        return;
+      }
+      this.isAlive = false;
+      this.ws.ping();
+      logger.debug("Heartbeat ping sent", { id: this.id });
+    }, interval);
+  }
+
+  private setupMessageHandler(): void {
+    this.ws.on("message", (data: Buffer) => {
+      const message = data.toString();
+
+      // Try to parse as JSON to check for ACK messages
+      try {
+        const parsed = JSON.parse(message);
+
+        // Handle ACK response from client
+        if (isAckMessage(parsed)) {
+          const pending = this.pendingAcks.get(parsed.__ack);
+          if (pending) {
+            clearTimeout(pending.timer);
+            pending.resolve();
+            this.pendingAcks.delete(parsed.__ack);
+            logger.debug("ACK received", { msgId: parsed.__ack, connectionId: this.id });
+          }
+          return; // Don't pass ACK messages to application layer
+        }
+      } catch {
+        // Not JSON, pass through as normal message
+      }
+
+      // Pass message to handlers
+      for (const handler of this.messageHandlers) {
+        handler(message);
+      }
+    });
+  }
+
+  private setupCloseHandler(): void {
+    this.ws.on("close", () => {
+      if (this.heartbeatInterval) {
+        clearInterval(this.heartbeatInterval);
+      }
+      for (const handler of this.closeHandlers) {
+        handler();
+      }
+    });
+  }
+
+  private setupErrorHandler(): void {
+    this.ws.on("error", (err: Error) => {
+      if (this.heartbeatInterval) {
+        clearInterval(this.heartbeatInterval);
+      }
+      for (const handler of this.errorHandlers) {
+        handler(err);
+      }
+    });
+  }
+
+  send(message: string): void {
+    if (this.ws.readyState === 1) {
+      // WebSocket.OPEN
+      this.ws.send(message);
+    }
+  }
+
+  sendReliable(message: string, options?: SendReliableOptions): void {
+    if (this.ws.readyState !== 1) {
+      // WebSocket not open, trigger timeout immediately if callback provided
+      options?.onTimeout?.();
+      return;
+    }
+
+    // If no ACK callback needed, just send normally
+    if (!options?.onAck) {
+      this.send(message);
+      return;
+    }
+
+    // Generate unique message ID
+    const msgId = `${this.id}_${++this.msgIdCounter}`;
+
+    // Wrap message with msgId
+    const wrapped: ReliableWrapper = {
+      __msgId: msgId,
+      __payload: message,
+    };
+
+    // Set up timeout
+    const timeout = options.timeout ?? 5000;
+    const timer = setTimeout(() => {
+      if (this.pendingAcks.has(msgId)) {
+        this.pendingAcks.delete(msgId);
+        logger.warn("ACK timeout", { msgId, connectionId: this.id, timeout });
+        options.onTimeout?.();
+      }
+    }, timeout);
+
+    // Store pending ACK
+    this.pendingAcks.set(msgId, {
+      resolve: options.onAck,
+      timer,
+    });
+
+    // Send wrapped message
+    this.ws.send(JSON.stringify(wrapped));
+    logger.debug("Sent reliable message", { msgId, connectionId: this.id });
+  }
+
+  onMessage(handler: (message: string) => void): Unsubscribe {
+    this.messageHandlers.add(handler);
+    return () => {
+      this.messageHandlers.delete(handler);
+    };
+  }
+
+  onClose(handler: () => void): Unsubscribe {
+    this.closeHandlers.add(handler);
+    return () => {
+      this.closeHandlers.delete(handler);
+    };
+  }
+
+  onError(handler: (error: Error) => void): Unsubscribe {
+    this.errorHandlers.add(handler);
+    return () => {
+      this.errorHandlers.delete(handler);
+    };
+  }
+
+  close(): void {
+    if (this.heartbeatInterval) {
+      clearInterval(this.heartbeatInterval);
+    }
+    // Clean up pending ACKs
+    for (const pending of this.pendingAcks.values()) {
+      clearTimeout(pending.timer);
+    }
+    this.pendingAcks.clear();
+    this.ws.close();
+  }
+}

package/src/network/WebSocketFactory.ts

@@ -0,0 +1,17 @@
+/**
+ * Node.js WebSocket factory using the ws library
+ *
+ * Provides WebSocketFactory implementation for @agentxjs/core RpcClient.
+ * Browser environments use native WebSocket (the default in RpcClient).
+ */
+
+import type { WebSocketFactory } from "@agentxjs/core/network";
+
+/**
+ * Create a WebSocket instance using the ws library (Node.js)
+ */
+export const createNodeWebSocket: WebSocketFactory = (url: string): WebSocket => {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const { default: WS } = require("ws");
+  return new WS(url) as unknown as WebSocket;
+};

package/src/network/WebSocketServer.ts

@@ -0,0 +1,156 @@
+/**
+ * WebSocket Server - Manages WebSocket connections
+ *
+ * Supports:
+ * - Standalone mode (listen on port)
+ * - Attached mode (attach to existing HTTP server)
+ */
+
+import type { WebSocket as WS, WebSocketServer as WSS } from "ws";
+import type {
+  ChannelServer,
+  ChannelConnection,
+  ChannelServerOptions,
+  MinimalHTTPServer,
+  Unsubscribe,
+} from "@agentxjs/core/network";
+import { createLogger } from "commonxjs/logger";
+import { WebSocketConnection } from "./WebSocketConnection";
+
+const logger = createLogger("node-platform/WebSocketServer");
+
+/**
+ * WebSocket Server
+ */
+export class WebSocketServer implements ChannelServer {
+  private wss: WSS | null = null;
+  private connections = new Set<WebSocketConnection>();
+  private connectionHandlers = new Set<(connection: ChannelConnection) => void>();
+  private options: ChannelServerOptions;
+  private attachedToServer = false;
+
+  constructor(options: ChannelServerOptions = {}) {
+    this.options = options;
+  }
+
+  async listen(port: number, host: string = "0.0.0.0"): Promise<void> {
+    if (this.wss) {
+      throw new Error("Server already listening");
+    }
+    if (this.attachedToServer) {
+      throw new Error(
+        "Cannot listen when attached to existing server. The server should call listen() instead."
+      );
+    }
+
+    const { WebSocketServer: WSS } = await import("ws");
+    this.wss = new WSS({ port, host });
+
+    this.wss.on("connection", (ws: WS) => {
+      this.handleConnection(ws);
+    });
+
+    logger.info("WebSocket server listening", { port, host });
+  }
+
+  attach(server: MinimalHTTPServer, path: string = "/ws"): void {
+    if (this.wss) {
+      throw new Error("Server already initialized");
+    }
+
+    import("ws").then(({ WebSocketServer: WSS }) => {
+      this.wss = new WSS({ noServer: true });
+
+      // Handle WebSocket upgrade on the HTTP server
+      server.on("upgrade", (request, socket, head) => {
+        const url = new URL(
+          (request as { url?: string }).url || "",
+          `http://${(request as { headers: { host?: string } }).headers.host}`
+        );
+        if (url.pathname === path) {
+          this.wss!.handleUpgrade(request as never, socket as never, head as never, (ws: WS) => {
+            this.wss!.emit("connection", ws, request);
+          });
+        } else {
+          (socket as { destroy: () => void }).destroy();
+        }
+      });
+
+      this.wss.on("connection", (ws: WS) => {
+        this.handleConnection(ws);
+      });
+
+      this.attachedToServer = true;
+      logger.info("WebSocket attached to existing HTTP server", { path });
+    });
+  }
+
+  private handleConnection(ws: WS): void {
+    const connection = new WebSocketConnection(ws, this.options);
+    this.connections.add(connection);
+
+    logger.info("Client connected", {
+      connectionId: connection.id,
+      totalConnections: this.connections.size,
+    });
+
+    connection.onClose(() => {
+      this.connections.delete(connection);
+
+      logger.info("Client disconnected", {
+        connectionId: connection.id,
+        totalConnections: this.connections.size,
+      });
+    });
+
+    // Notify handlers
+    for (const handler of this.connectionHandlers) {
+      handler(connection);
+    }
+  }
+
+  onConnection(handler: (connection: ChannelConnection) => void): Unsubscribe {
+    this.connectionHandlers.add(handler);
+    return () => {
+      this.connectionHandlers.delete(handler);
+    };
+  }
+
+  broadcast(message: string): void {
+    for (const connection of this.connections) {
+      connection.send(message);
+    }
+  }
+
+  async close(): Promise<void> {
+    if (!this.wss) return;
+
+    for (const connection of this.connections) {
+      connection.close();
+    }
+    this.connections.clear();
+
+    // Don't close the server if attached to existing HTTP server
+    if (!this.attachedToServer) {
+      await new Promise<void>((resolve) => {
+        // Add timeout to prevent hanging
+        const timeout = setTimeout(() => {
+          logger.warn("WebSocket server close timeout, forcing close");
+          resolve();
+        }, 1000);
+
+        this.wss!.close(() => {
+          clearTimeout(timeout);
+          resolve();
+        });
+      });
+    }
+    this.wss = null;
+    logger.info("WebSocket server closed");
+  }
+
+  async dispose(): Promise<void> {
+    await this.close();
+    this.connectionHandlers.clear();
+  }
+}

package/src/network/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Network Module
+ *
+ * WebSocket server and connection for Node.js.
+ *
+ * @example
+ * ```typescript
+ * import { WebSocketServer } from "@agentxjs/node-platform/network";
+ *
+ * const server = new WebSocketServer();
+ * await server.listen(5200);
+ *
+ * server.onConnection((connection) => {
+ *   console.log("Client connected:", connection.id);
+ *
+ *   connection.onMessage((message) => {
+ *     console.log("Received:", message);
+ *   });
+ *
+ *   // Reliable delivery with ACK
+ *   connection.sendReliable(JSON.stringify({ type: "event" }), {
+ *     onAck: () => console.log("Client confirmed receipt"),
+ *     timeout: 5000,
+ *     onTimeout: () => console.log("Client did not ACK"),
+ *   });
+ * });
+ * ```
+ */
+
+export { WebSocketServer } from "./WebSocketServer";
+export { WebSocketConnection } from "./WebSocketConnection";
+export { createNodeWebSocket } from "./WebSocketFactory";