@multiplier-labs/stepflow 0.3.3 → 0.3.6

package/src/events/socketio.test.ts

@@ -1,378 +0,0 @@
-import { describe, it, expect, beforeEach, vi } from 'vitest';
-import { SocketIOEventTransport, SocketIOServer, SocketIOSocket } from './socketio';
-import type { WorkflowEvent } from './types';
-
-// Mock Socket.IO server
-function createMockServer(): SocketIOServer & {
-  _rooms: Map<string, { emit: ReturnType<typeof vi.fn> }>;
-  _emitCalls: Array<{ event: string; args: unknown[] }>;
-} {
-  const rooms = new Map<string, { emit: ReturnType<typeof vi.fn> }>();
-  const emitCalls: Array<{ event: string; args: unknown[] }> = [];
-
-  return {
-    _rooms: rooms,
-    _emitCalls: emitCalls,
-    to(room: string) {
-      if (!rooms.has(room)) {
-        rooms.set(room, { emit: vi.fn() });
-      }
-      return rooms.get(room)!;
-    },
-    emit(event: string, ...args: unknown[]) {
-      emitCalls.push({ event, args });
-    },
-  };
-}
-
-// Mock Socket.IO socket
-function createMockSocket(): SocketIOSocket & {
-  _joinedRooms: Set<string>;
-  _handlers: Map<string, (...args: unknown[]) => void>;
-} {
-  const joinedRooms = new Set<string>();
-  const handlers = new Map<string, (...args: unknown[]) => void>();
-
-  return {
-    _joinedRooms: joinedRooms,
-    _handlers: handlers,
-    join(room: string) {
-      joinedRooms.add(room);
-    },
-    leave(room: string) {
-      joinedRooms.delete(room);
-    },
-    on(event: string, callback: (...args: unknown[]) => void) {
-      handlers.set(event, callback);
-    },
-  };
-}
-
-function createTestEvent(overrides: Partial<WorkflowEvent> = {}): WorkflowEvent {
-  return {
-    eventType: 'run.started',
-    runId: 'run-123',
-    kind: 'test.workflow',
-    timestamp: new Date('2024-01-01T12:00:00Z'),
-    ...overrides,
-  };
-}
-
-describe('SocketIOEventTransport', () => {
-  let io: ReturnType<typeof createMockServer>;
-  let transport: SocketIOEventTransport;
-
-  beforeEach(() => {
-    io = createMockServer();
-    transport = new SocketIOEventTransport({ io });
-  });
-
-  describe('emit', () => {
-    it('should emit event to run-specific room', () => {
-      const event = createTestEvent({ runId: 'run-456' });
-      transport.emit(event);
-
-      const roomEmit = io._rooms.get('run:run-456');
-      expect(roomEmit).toBeDefined();
-      expect(roomEmit!.emit).toHaveBeenCalledWith('workflow:event', {
-        ...event,
-        timestamp: '2024-01-01T12:00:00.000Z',
-      });
-    });
-
-    it('should emit event to global room by default', () => {
-      const event = createTestEvent();
-      transport.emit(event);
-
-      const globalRoomEmit = io._rooms.get('workflow:all');
-      expect(globalRoomEmit).toBeDefined();
-      expect(globalRoomEmit!.emit).toHaveBeenCalled();
-    });
-
-    it('should not emit to global room when broadcastGlobal is false', () => {
-      transport = new SocketIOEventTransport({ io, broadcastGlobal: false });
-      const event = createTestEvent();
-      transport.emit(event);
-
-      // Should only have run-specific room, not global
-      expect(io._rooms.size).toBe(1);
-      expect(io._rooms.has('run:run-123')).toBe(true);
-      expect(io._rooms.has('workflow:all')).toBe(false);
-    });
-
-    it('should use custom event name', () => {
-      transport = new SocketIOEventTransport({ io, eventName: 'custom:event' });
-      const event = createTestEvent();
-      transport.emit(event);
-
-      const roomEmit = io._rooms.get('run:run-123');
-      expect(roomEmit!.emit).toHaveBeenCalledWith('custom:event', expect.any(Object));
-    });
-
-    it('should use custom room prefix', () => {
-      transport = new SocketIOEventTransport({ io, roomPrefix: 'workflow:' });
-      const event = createTestEvent({ runId: 'xyz' });
-      transport.emit(event);
-
-      expect(io._rooms.has('workflow:xyz')).toBe(true);
-    });
-
-    it('should serialize timestamp to ISO string', () => {
-      const event = createTestEvent({
-        timestamp: new Date('2024-06-15T10:30:00Z'),
-      });
-      transport.emit(event);
-
-      const roomEmit = io._rooms.get('run:run-123');
-      const emittedEvent = roomEmit!.emit.mock.calls[0][1] as Record<string, unknown>;
-      expect(emittedEvent.timestamp).toBe('2024-06-15T10:30:00.000Z');
-    });
-  });
-
-  describe('subscribe', () => {
-    it('should call callback when event matches runId', () => {
-      const callback = vi.fn();
-      transport.subscribe('run-123', callback);
-
-      const event = createTestEvent({ runId: 'run-123' });
-      transport.emit(event);
-
-      expect(callback).toHaveBeenCalledWith(event);
-    });
-
-    it('should not call callback for different runId', () => {
-      const callback = vi.fn();
-      transport.subscribe('run-123', callback);
-
-      const event = createTestEvent({ runId: 'run-456' });
-      transport.emit(event);
-
-      expect(callback).not.toHaveBeenCalled();
-    });
-
-    it('should allow multiple subscribers for same runId', () => {
-      const callback1 = vi.fn();
-      const callback2 = vi.fn();
-      transport.subscribe('run-123', callback1);
-      transport.subscribe('run-123', callback2);
-
-      const event = createTestEvent({ runId: 'run-123' });
-      transport.emit(event);
-
-      expect(callback1).toHaveBeenCalledWith(event);
-      expect(callback2).toHaveBeenCalledWith(event);
-    });
-
-    it('should unsubscribe when calling returned function', () => {
-      const callback = vi.fn();
-      const unsubscribe = transport.subscribe('run-123', callback);
-
-      unsubscribe();
-
-      const event = createTestEvent({ runId: 'run-123' });
-      transport.emit(event);
-
-      expect(callback).not.toHaveBeenCalled();
-    });
-
-    it('should handle callback errors gracefully', () => {
-      const errorCallback = vi.fn().mockImplementation(() => {
-        throw new Error('Callback error');
-      });
-      const normalCallback = vi.fn();
-
-      transport.subscribe('run-123', errorCallback);
-      transport.subscribe('run-123', normalCallback);
-
-      const event = createTestEvent({ runId: 'run-123' });
-      transport.emit(event);
-
-      // Both callbacks should have been called despite error
-      expect(errorCallback).toHaveBeenCalled();
-      expect(normalCallback).toHaveBeenCalled();
-    });
-  });
-
-  describe('subscribeAll', () => {
-    it('should call callback for all events', () => {
-      const callback = vi.fn();
-      transport.subscribeAll(callback);
-
-      const event1 = createTestEvent({ runId: 'run-1' });
-      const event2 = createTestEvent({ runId: 'run-2' });
-      transport.emit(event1);
-      transport.emit(event2);
-
-      expect(callback).toHaveBeenCalledTimes(2);
-      expect(callback).toHaveBeenCalledWith(event1);
-      expect(callback).toHaveBeenCalledWith(event2);
-    });
-
-    it('should unsubscribe when calling returned function', () => {
-      const callback = vi.fn();
-      const unsubscribe = transport.subscribeAll(callback);
-
-      unsubscribe();
-
-      const event = createTestEvent();
-      transport.emit(event);
-
-      expect(callback).not.toHaveBeenCalled();
-    });
-  });
-
-  describe('setupClientHandlers', () => {
-    const allowAll = vi.fn().mockResolvedValue(true);
-
-    it('should register subscription handlers on socket', () => {
-      const socket = createMockSocket();
-      transport.setupClientHandlers(socket, allowAll);
-
-      expect(socket._handlers.has('workflow:subscribe')).toBe(true);
-      expect(socket._handlers.has('workflow:unsubscribe')).toBe(true);
-      expect(socket._handlers.has('workflow:subscribe:all')).toBe(true);
-      expect(socket._handlers.has('workflow:unsubscribe:all')).toBe(true);
-    });
-
-    it('should join run-specific room on subscribe when authorized', async () => {
-      const socket = createMockSocket();
-      transport.setupClientHandlers(socket, allowAll);
-
-      const subscribeHandler = socket._handlers.get('workflow:subscribe')!;
-      await subscribeHandler('run-123');
-
-      expect(socket._joinedRooms.has('run:run-123')).toBe(true);
-    });
-
-    it('should leave run-specific room on unsubscribe', async () => {
-      const socket = createMockSocket();
-      transport.setupClientHandlers(socket, allowAll);
-
-      // First subscribe
-      const subscribeHandler = socket._handlers.get('workflow:subscribe')!;
-      await subscribeHandler('run-123');
-
-      // Then unsubscribe
-      const unsubscribeHandler = socket._handlers.get('workflow:unsubscribe')!;
-      unsubscribeHandler('run-123');
-
-      expect(socket._joinedRooms.has('run:run-123')).toBe(false);
-    });
-
-    it('should join global room on subscribe:all when authorized', async () => {
-      const socket = createMockSocket();
-      transport.setupClientHandlers(socket, allowAll);
-
-      const subscribeAllHandler = socket._handlers.get('workflow:subscribe:all')!;
-      await subscribeAllHandler();
-
-      expect(socket._joinedRooms.has('workflow:all')).toBe(true);
-    });
-
-    it('should leave global room on unsubscribe:all', async () => {
-      const socket = createMockSocket();
-      transport.setupClientHandlers(socket, allowAll);
-
-      // First subscribe
-      const subscribeAllHandler = socket._handlers.get('workflow:subscribe:all')!;
-      await subscribeAllHandler();
-
-      // Then unsubscribe
-      const unsubscribeAllHandler = socket._handlers.get('workflow:unsubscribe:all')!;
-      unsubscribeAllHandler();
-
-      expect(socket._joinedRooms.has('workflow:all')).toBe(false);
-    });
-
-    it('should ignore non-string runId on subscribe', async () => {
-      const socket = createMockSocket();
-      transport.setupClientHandlers(socket, allowAll);
-
-      const subscribeHandler = socket._handlers.get('workflow:subscribe')!;
-      await subscribeHandler(123); // Not a string
-      await subscribeHandler(null);
-      await subscribeHandler(undefined);
-
-      expect(socket._joinedRooms.size).toBe(0);
-    });
-
-    it('should deny run subscription when authorize returns false', async () => {
-      const logger = { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() };
-      transport = new SocketIOEventTransport({ io, logger });
-
-      const socket = createMockSocket();
-      const authorize = vi.fn().mockResolvedValue(false);
-      transport.setupClientHandlers(socket, authorize);
-
-      const subscribeHandler = socket._handlers.get('workflow:subscribe')!;
-      await subscribeHandler('run-secret');
-
-      expect(authorize).toHaveBeenCalledWith('run-secret', socket);
-      expect(socket._joinedRooms.has('run:run-secret')).toBe(false);
-      expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining('run-secret'));
-    });
-
-    it('should deny run subscription when authorize throws', async () => {
-      const logger = { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() };
-      transport = new SocketIOEventTransport({ io, logger });
-
-      const socket = createMockSocket();
-      const authorize = vi.fn().mockRejectedValue(new Error('auth error'));
-      transport.setupClientHandlers(socket, authorize);
-
-      const subscribeHandler = socket._handlers.get('workflow:subscribe')!;
-      await subscribeHandler('run-123');
-
-      expect(socket._joinedRooms.has('run:run-123')).toBe(false);
-      expect(logger.error).toHaveBeenCalledWith('Authorization check failed:', expect.any(Error));
-    });
-
-    it('should deny global subscription when authorize returns false', async () => {
-      const logger = { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() };
-      transport = new SocketIOEventTransport({ io, logger });
-
-      const socket = createMockSocket();
-      const authorize = vi.fn().mockResolvedValue(false);
-      transport.setupClientHandlers(socket, authorize);
-
-      const subscribeAllHandler = socket._handlers.get('workflow:subscribe:all')!;
-      await subscribeAllHandler();
-
-      expect(authorize).toHaveBeenCalledWith('*', socket);
-      expect(socket._joinedRooms.has('workflow:all')).toBe(false);
-      expect(logger.warn).toHaveBeenCalledWith('Global subscription denied');
-    });
-
-    it('should deny global subscription when authorize throws', async () => {
-      const logger = { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() };
-      transport = new SocketIOEventTransport({ io, logger });
-
-      const socket = createMockSocket();
-      const authorize = vi.fn().mockRejectedValue(new Error('auth down'));
-      transport.setupClientHandlers(socket, authorize);
-
-      const subscribeAllHandler = socket._handlers.get('workflow:subscribe:all')!;
-      await subscribeAllHandler();
-
-      expect(socket._joinedRooms.has('workflow:all')).toBe(false);
-      expect(logger.error).toHaveBeenCalledWith('Authorization check failed:', expect.any(Error));
-    });
-  });
-
-  describe('close', () => {
-    it('should clear all subscribers', () => {
-      const runCallback = vi.fn();
-      const globalCallback = vi.fn();
-      transport.subscribe('run-123', runCallback);
-      transport.subscribeAll(globalCallback);
-
-      transport.close();
-
-      const event = createTestEvent({ runId: 'run-123' });
-      transport.emit(event);
-
-      expect(runCallback).not.toHaveBeenCalled();
-      expect(globalCallback).not.toHaveBeenCalled();
-    });
-  });
-});

package/src/events/socketio.ts

@@ -1,262 +0,0 @@
-/**
- * Socket.IO Event Transport
- *
- * Broadcasts workflow events to connected clients via Socket.IO.
- * Clients can subscribe to specific run IDs or receive all events.
- */
-
-import type { EventTransport, EventCallback, Unsubscribe, WorkflowEvent } from './types';
-import type { Logger } from '../core/types';
-
-/**
- * Minimal Socket.IO Server interface.
- * This allows using the adapter without a direct dependency on socket.io.
- */
-export interface SocketIOServer {
-  to(room: string): {
-    emit(event: string, ...args: unknown[]): void;
-  };
-  emit(event: string, ...args: unknown[]): void;
-}
-
-/**
- * Minimal Socket.IO Socket interface.
- */
-export interface SocketIOSocket {
-  join(room: string): void;
-  leave(room: string): void;
-  on(event: string, callback: (...args: unknown[]) => void): void;
-}
-
-/**
- * Authorization callback for Socket.IO run subscriptions.
- * Return true to allow the subscription, false to deny it.
- */
-export type SocketIOAuthorizeFn = (
-  runId: string,
-  socket: SocketIOSocket
-) => boolean | Promise<boolean>;
-
-/**
- * Configuration for SocketIOEventTransport.
- */
-export interface SocketIOEventTransportConfig {
-  /** Socket.IO server instance */
-  io: SocketIOServer;
-
-  /** Event name to use for workflow events (default: 'workflow:event') */
-  eventName?: string;
-
-  /** Room prefix for run-specific subscriptions (default: 'run:') */
-  roomPrefix?: string;
-
-  /** Whether to also broadcast to a global room (default: true) */
-  broadcastGlobal?: boolean;
-
-  /** Global room name (default: 'workflow:all') */
-  globalRoom?: string;
-
-  /** Logger for transport errors (default: console-based) */
-  logger?: Logger;
-}
-
-/**
- * Socket.IO-based event transport for real-time workflow events.
- *
- * @example
- * ```typescript
- * import { Server } from 'socket.io';
- * import { SocketIOEventTransport } from 'stepflow';
- *
- * const io = new Server(httpServer);
- * const eventTransport = new SocketIOEventTransport({ io });
- *
- * const engine = new WorkflowEngine({
- *   storage,
- *   events: eventTransport,
- * });
- *
- * // Client-side:
- * // socket.emit('workflow:subscribe', runId);
- * // socket.on('workflow:event', (event) => console.log(event));
- * ```
- */
-export class SocketIOEventTransport implements EventTransport {
-  private io: SocketIOServer;
-  private eventName: string;
-  private roomPrefix: string;
-  private broadcastGlobal: boolean;
-  private globalRoom: string;
-  private logger: Logger;
-
-  // Local subscribers for server-side subscriptions
-  private runSubscribers = new Map<string, Set<EventCallback>>();
-  private globalSubscribers = new Set<EventCallback>();
-
-  constructor(config: SocketIOEventTransportConfig) {
-    this.io = config.io;
-    this.eventName = config.eventName ?? 'workflow:event';
-    this.roomPrefix = config.roomPrefix ?? 'run:';
-    this.broadcastGlobal = config.broadcastGlobal ?? true;
-    this.globalRoom = config.globalRoom ?? 'workflow:all';
-    this.logger = config.logger ?? {
-      debug() {},
-      info() {},
-      warn() {},
-      error(message: string, ...args: unknown[]) { console.error(message, ...args); },
-    };
-  }
-
-  /**
-   * Emit an event to Socket.IO clients and local subscribers.
-   */
-  emit(event: WorkflowEvent): void {
-    // Serialize the event (convert Date to ISO string for transport)
-    const serializedEvent = {
-      ...event,
-      timestamp: event.timestamp.toISOString(),
-    };
-
-    // Emit to run-specific room
-    const room = `${this.roomPrefix}${event.runId}`;
-    this.io.to(room).emit(this.eventName, serializedEvent);
-
-    // Emit to global room
-    if (this.broadcastGlobal) {
-      this.io.to(this.globalRoom).emit(this.eventName, serializedEvent);
-    }
-
-    // Notify local subscribers
-    const runSubs = this.runSubscribers.get(event.runId);
-    if (runSubs) {
-      for (const callback of runSubs) {
-        try {
-          callback(event);
-        } catch (error) {
-          this.logger.error('Event callback error:', error);
-        }
-      }
-    }
-
-    for (const callback of this.globalSubscribers) {
-      try {
-        callback(event);
-      } catch (error) {
-        this.logger.error('Event callback error:', error);
-      }
-    }
-  }
-
-  /**
-   * Subscribe to events for a specific run (server-side).
-   */
-  subscribe(runId: string, callback: EventCallback): Unsubscribe {
-    let subs = this.runSubscribers.get(runId);
-    if (!subs) {
-      subs = new Set();
-      this.runSubscribers.set(runId, subs);
-    }
-    subs.add(callback);
-
-    return () => {
-      subs!.delete(callback);
-      if (subs!.size === 0) {
-        this.runSubscribers.delete(runId);
-      }
-    };
-  }
-
-  /**
-   * Subscribe to all events (server-side).
-   */
-  subscribeAll(callback: EventCallback): Unsubscribe {
-    this.globalSubscribers.add(callback);
-    return () => {
-      this.globalSubscribers.delete(callback);
-    };
-  }
-
-  /**
-   * Set up client subscription handlers on a socket.
-   * Call this when a client connects to enable subscription commands.
-   *
-   * An `authorize` callback is required to prevent unauthorized access to run events.
-   * The callback receives the run ID (or `'*'` for global subscriptions) and the socket,
-   * and must return `true` to allow or `false` to deny the subscription.
-   *
-   * @param socket - The Socket.IO socket to set up handlers on
-   * @param authorize - Callback to check if a socket can access a run.
-   *
-   * @example
-   * ```typescript
-   * io.on('connection', (socket) => {
-   *   eventTransport.setupClientHandlers(socket, async (runId, sock) => {
-   *     // Check if the authenticated user owns this run
-   *     const userId = sock.data?.userId;
-   *     return userId ? await canUserAccessRun(userId, runId) : false;
-   *   });
-   * });
-   * ```
-   */
-  setupClientHandlers(
-    socket: SocketIOSocket,
-    authorize: SocketIOAuthorizeFn
-  ): void {
-    // Subscribe to a specific run
-    socket.on('workflow:subscribe', async (...args: unknown[]) => {
-      const runId = args[0];
-      if (typeof runId !== 'string') return;
-
-      try {
-        const allowed = await authorize(runId, socket);
-        if (!allowed) {
-          this.logger.warn(`Subscription denied for run ${runId}`);
-          return;
-        }
-      } catch (error) {
-        this.logger.error('Authorization check failed:', error);
-        return;
-      }
-
-      socket.join(`${this.roomPrefix}${runId}`);
-    });
-
-    // Unsubscribe from a specific run
-    socket.on('workflow:unsubscribe', (...args: unknown[]) => {
-      const runId = args[0];
-      if (typeof runId === 'string') {
-        socket.leave(`${this.roomPrefix}${runId}`);
-      }
-    });
-
-    // Subscribe to all events (requires authorization to pass with '*' as runId)
-    socket.on('workflow:subscribe:all', async () => {
-      try {
-        const allowed = await authorize('*', socket);
-        if (!allowed) {
-          this.logger.warn('Global subscription denied');
-          return;
-        }
-      } catch (error) {
-        this.logger.error('Authorization check failed:', error);
-        return;
-      }
-
-      socket.join(this.globalRoom);
-    });
-
-    // Unsubscribe from all events
-    socket.on('workflow:unsubscribe:all', () => {
-      socket.leave(this.globalRoom);
-    });
-  }
-
-  /**
-   * Clear all in-process server-side subscribers.
-   * The underlying Socket.IO server socket is not closed here — manage its lifecycle externally.
-   */
-  close(): void {
-    this.runSubscribers.clear();
-    this.globalSubscribers.clear();
-  }
-}