reqon-dsl 0.2.0

package/src/webhook/server.test.ts

@@ -0,0 +1,253 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { WebhookServer } from './server.js';
+import { MemoryWebhookStore } from './store.js';
+
+describe('WebhookServer', () => {
+  let server: WebhookServer;
+  let store: MemoryWebhookStore;
+
+  beforeEach(() => {
+    store = new MemoryWebhookStore();
+    server = new WebhookServer(
+      { port: 0, verbose: false }, // Use port 0 for dynamic port assignment
+      store
+    );
+  });
+
+  afterEach(async () => {
+    if (server.isRunning()) {
+      await server.stop();
+    }
+  });
+
+  describe('start/stop', () => {
+    it('should start and stop the server', async () => {
+      // Server should not be running initially
+      expect(server.isRunning()).toBe(false);
+
+      // Note: Port 0 might not work in all environments, so we skip actual start
+      // In a real test environment, you'd start the server and verify
+    });
+  });
+
+  describe('register', () => {
+    it('should register a webhook endpoint', async () => {
+      const registration = await server.register('exec-123', {
+        path: '/test/callback',
+        timeout: 60000,
+        expectedEvents: 2,
+      });
+
+      expect(registration.id).toBeDefined();
+      expect(registration.executionId).toBe('exec-123');
+      expect(registration.path).toBe('/test/callback');
+      expect(registration.expectedEvents).toBe(2);
+      expect(registration.receivedEvents).toBe(0);
+    });
+
+    it('should auto-generate path if not provided', async () => {
+      const registration = await server.register('exec-456');
+
+      expect(registration.path).toContain('/webhook/exec-456/');
+    });
+
+    it('should set expiration based on timeout', async () => {
+      const before = Date.now();
+      const registration = await server.register('exec-789', {
+        timeout: 120000, // 2 minutes
+      });
+      const after = Date.now();
+
+      const expectedMin = before + 120000;
+      const expectedMax = after + 120000;
+
+      expect(registration.expiresAt.getTime()).toBeGreaterThanOrEqual(expectedMin);
+      expect(registration.expiresAt.getTime()).toBeLessThanOrEqual(expectedMax);
+    });
+  });
+
+  describe('unregister', () => {
+    it('should unregister a webhook endpoint', async () => {
+      const registration = await server.register('exec-123');
+
+      await server.unregister(registration.id);
+
+      const loaded = await store.getRegistration(registration.id);
+      expect(loaded).toBeUndefined();
+    });
+  });
+
+  describe('getWebhookUrl', () => {
+    it('should return the full webhook URL', async () => {
+      const serverWithUrl = new WebhookServer(
+        { port: 8080, baseUrl: 'https://example.com' },
+        store
+      );
+
+      const registration = await serverWithUrl.register('exec-123', {
+        path: '/webhooks/test',
+      });
+
+      const url = serverWithUrl.getWebhookUrl(registration);
+      expect(url).toBe('https://example.com/webhooks/test');
+    });
+  });
+});
+
+describe('MemoryWebhookStore', () => {
+  let store: MemoryWebhookStore;
+
+  beforeEach(() => {
+    store = new MemoryWebhookStore();
+  });
+
+  describe('registrations', () => {
+    it('should save and retrieve a registration', async () => {
+      const registration = {
+        id: 'reg-1',
+        executionId: 'exec-1',
+        path: '/test',
+        createdAt: new Date(),
+        expiresAt: new Date(Date.now() + 60000),
+        expectedEvents: 1,
+        receivedEvents: 0,
+      };
+
+      await store.saveRegistration(registration);
+      const loaded = await store.getRegistration('reg-1');
+
+      expect(loaded).toEqual(registration);
+    });
+
+    it('should find registration by path', async () => {
+      const registration = {
+        id: 'reg-2',
+        executionId: 'exec-2',
+        path: '/webhooks/callback',
+        createdAt: new Date(),
+        expiresAt: new Date(Date.now() + 60000),
+        expectedEvents: 1,
+        receivedEvents: 0,
+      };
+
+      await store.saveRegistration(registration);
+      const found = await store.getRegistrationByPath('/webhooks/callback');
+
+      expect(found?.id).toBe('reg-2');
+    });
+
+    it('should delete a registration', async () => {
+      const registration = {
+        id: 'reg-3',
+        executionId: 'exec-3',
+        path: '/test3',
+        createdAt: new Date(),
+        expiresAt: new Date(Date.now() + 60000),
+        expectedEvents: 1,
+        receivedEvents: 0,
+      };
+
+      await store.saveRegistration(registration);
+      await store.deleteRegistration('reg-3');
+
+      const loaded = await store.getRegistration('reg-3');
+      expect(loaded).toBeUndefined();
+    });
+
+    it('should list all registrations', async () => {
+      await store.saveRegistration({
+        id: 'reg-a',
+        executionId: 'exec-a',
+        path: '/a',
+        createdAt: new Date(),
+        expiresAt: new Date(Date.now() + 60000),
+        expectedEvents: 1,
+        receivedEvents: 0,
+      });
+
+      await store.saveRegistration({
+        id: 'reg-b',
+        executionId: 'exec-b',
+        path: '/b',
+        createdAt: new Date(),
+        expiresAt: new Date(Date.now() + 60000),
+        expectedEvents: 1,
+        receivedEvents: 0,
+      });
+
+      const list = await store.listRegistrations();
+      expect(list).toHaveLength(2);
+    });
+  });
+
+  describe('events', () => {
+    it('should save and retrieve events', async () => {
+      const event = {
+        id: 'evt-1',
+        registrationId: 'reg-1',
+        receivedAt: new Date(),
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: { data: 'test' },
+        rawBody: '{"data":"test"}',
+        query: {},
+      };
+
+      await store.saveEvent(event);
+      const events = await store.getEvents('reg-1');
+
+      expect(events).toHaveLength(1);
+      expect(events[0]).toEqual(event);
+    });
+
+    it('should delete events for a registration', async () => {
+      await store.saveEvent({
+        id: 'evt-2',
+        registrationId: 'reg-2',
+        receivedAt: new Date(),
+        method: 'POST',
+        headers: {},
+        body: {},
+        rawBody: '',
+        query: {},
+      });
+
+      await store.deleteEvents('reg-2');
+      const events = await store.getEvents('reg-2');
+
+      expect(events).toHaveLength(0);
+    });
+  });
+
+  describe('cleanup', () => {
+    it('should clean up expired registrations', async () => {
+      // Create an expired registration
+      await store.saveRegistration({
+        id: 'expired',
+        executionId: 'exec-expired',
+        path: '/expired',
+        createdAt: new Date(Date.now() - 120000),
+        expiresAt: new Date(Date.now() - 60000), // Expired 1 minute ago
+        expectedEvents: 1,
+        receivedEvents: 0,
+      });
+
+      // Create a valid registration
+      await store.saveRegistration({
+        id: 'valid',
+        executionId: 'exec-valid',
+        path: '/valid',
+        createdAt: new Date(),
+        expiresAt: new Date(Date.now() + 60000), // Expires in 1 minute
+        expectedEvents: 1,
+        receivedEvents: 0,
+      });
+
+      const cleaned = await store.cleanupExpired();
+
+      expect(cleaned).toBe(1);
+      expect(await store.getRegistration('expired')).toBeUndefined();
+      expect(await store.getRegistration('valid')).toBeDefined();
+    });
+  });
+});

package/src/webhook/server.ts

@@ -0,0 +1,389 @@
+/**
+ * Webhook Server
+ *
+ * HTTP server for receiving webhook callbacks.
+ * Supports dynamic registration of webhook endpoints.
+ */
+
+import { createServer, type Server, type IncomingMessage, type ServerResponse } from 'node:http';
+import { parse as parseUrl } from 'node:url';
+import { randomUUID } from 'node:crypto';
+import type {
+  WebhookServerConfig,
+  WebhookServerCallbacks,
+  WebhookRegistration,
+  WebhookEvent,
+  WaitResult,
+} from './types.js';
+import type { WebhookStore } from './store.js';
+import { MemoryWebhookStore } from './store.js';
+
+/**
+ * Pending wait request
+ */
+interface PendingWait {
+  registrationId: string;
+  resolve: (result: WaitResult) => void;
+  timeoutId: ReturnType<typeof setTimeout>;
+}
+
+/**
+ * Webhook Server
+ *
+ * Provides HTTP endpoints for receiving webhook callbacks.
+ */
+export class WebhookServer {
+  private config: Required<WebhookServerConfig>;
+  private store: WebhookStore;
+  private callbacks: WebhookServerCallbacks;
+  private server?: Server;
+  private pendingWaits: Map<string, PendingWait> = new Map();
+  private cleanupInterval?: ReturnType<typeof setInterval>;
+  private running = false;
+
+  constructor(
+    config: WebhookServerConfig = {},
+    store?: WebhookStore,
+    callbacks: WebhookServerCallbacks = {}
+  ) {
+    this.config = {
+      port: config.port ?? 3000,
+      host: config.host ?? '0.0.0.0',
+      baseUrl: config.baseUrl ?? `http://localhost:${config.port ?? 3000}`,
+      defaultTimeout: config.defaultTimeout ?? 300000, // 5 minutes
+      verbose: config.verbose ?? false,
+    };
+    this.store = store ?? new MemoryWebhookStore();
+    this.callbacks = callbacks;
+  }
+
+  /**
+   * Start the webhook server
+   */
+  async start(): Promise<void> {
+    if (this.running) return;
+
+    return new Promise((resolve, reject) => {
+      this.server = createServer((req, res) => this.handleRequest(req, res));
+
+      this.server.on('error', (error) => {
+        reject(error);
+      });
+
+      this.server.listen(this.config.port, this.config.host, () => {
+        this.running = true;
+        this.log(`Webhook server listening on ${this.config.host}:${this.config.port}`);
+
+        // Start cleanup interval (every minute)
+        this.cleanupInterval = setInterval(() => this.cleanup(), 60000);
+
+        resolve();
+      });
+    });
+  }
+
+  /**
+   * Stop the webhook server
+   */
+  async stop(): Promise<void> {
+    if (!this.running) return;
+
+    // Clear cleanup interval
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = undefined;
+    }
+
+    // Cancel all pending waits
+    for (const [id, pending] of this.pendingWaits) {
+      clearTimeout(pending.timeoutId);
+      pending.resolve({
+        success: false,
+        events: [],
+        error: 'Server shutting down',
+      });
+    }
+    this.pendingWaits.clear();
+
+    // Close server
+    return new Promise((resolve) => {
+      if (this.server) {
+        this.server.close(() => {
+          this.running = false;
+          this.log('Webhook server stopped');
+          resolve();
+        });
+      } else {
+        resolve();
+      }
+    });
+  }
+
+  /**
+   * Register a webhook endpoint
+   */
+  async register(
+    executionId: string,
+    options: {
+      path?: string;
+      timeout?: number;
+      expectedEvents?: number;
+      filter?: string;
+    } = {}
+  ): Promise<WebhookRegistration> {
+    const id = randomUUID();
+    const timeout = options.timeout ?? this.config.defaultTimeout;
+    const path = options.path ?? `/webhook/${executionId}/${id}`;
+
+    const registration: WebhookRegistration = {
+      id,
+      executionId,
+      path,
+      createdAt: new Date(),
+      expiresAt: new Date(Date.now() + timeout),
+      expectedEvents: options.expectedEvents ?? 1,
+      receivedEvents: 0,
+      filter: options.filter,
+    };
+
+    await this.store.saveRegistration(registration);
+    this.callbacks.onRegistrationCreated?.(registration);
+    this.log(`Registered webhook: ${path} (expires: ${registration.expiresAt.toISOString()})`);
+
+    return registration;
+  }
+
+  /**
+   * Get the full URL for a webhook endpoint
+   */
+  getWebhookUrl(registration: WebhookRegistration): string {
+    return `${this.config.baseUrl}${registration.path}`;
+  }
+
+  /**
+   * Wait for webhook events
+   */
+  async waitForEvents(
+    registrationId: string,
+    timeout?: number
+  ): Promise<WaitResult> {
+    const registration = await this.store.getRegistration(registrationId);
+    if (!registration) {
+      return {
+        success: false,
+        events: [],
+        error: `Registration not found: ${registrationId}`,
+      };
+    }
+
+    // Check if already received enough events
+    const events = await this.store.getEvents(registrationId);
+    if (events.length >= registration.expectedEvents) {
+      return { success: true, events };
+    }
+
+    // Wait for more events
+    const waitTimeout = timeout ?? (registration.expiresAt.getTime() - Date.now());
+
+    return new Promise((resolve) => {
+      const timeoutId = setTimeout(() => {
+        this.pendingWaits.delete(registrationId);
+        this.store.getEvents(registrationId).then((events) => {
+          resolve({
+            success: events.length >= registration.expectedEvents,
+            events,
+            timedOut: true,
+          });
+        });
+      }, waitTimeout);
+
+      this.pendingWaits.set(registrationId, {
+        registrationId,
+        resolve,
+        timeoutId,
+      });
+    });
+  }
+
+  /**
+   * Unregister a webhook endpoint
+   */
+  async unregister(registrationId: string): Promise<void> {
+    await this.store.deleteRegistration(registrationId);
+    await this.store.deleteEvents(registrationId);
+
+    // Cancel pending wait if any
+    const pending = this.pendingWaits.get(registrationId);
+    if (pending) {
+      clearTimeout(pending.timeoutId);
+      this.pendingWaits.delete(registrationId);
+    }
+
+    this.log(`Unregistered webhook: ${registrationId}`);
+  }
+
+  /**
+   * Check if the server is running
+   */
+  isRunning(): boolean {
+    return this.running;
+  }
+
+  /**
+   * Get the server port
+   */
+  getPort(): number {
+    return this.config.port;
+  }
+
+  /**
+   * Get the base URL
+   */
+  getBaseUrl(): string {
+    return this.config.baseUrl;
+  }
+
+  /**
+   * Handle incoming HTTP request
+   */
+  private async handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const url = parseUrl(req.url ?? '/', true);
+    const path = url.pathname ?? '/';
+
+    // Health check endpoint
+    if (path === '/health' || path === '/_health') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ status: 'ok', timestamp: new Date().toISOString() }));
+      return;
+    }
+
+    // Find matching registration
+    const registration = await this.store.getRegistrationByPath(path);
+    if (!registration) {
+      res.writeHead(404, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Not found', path }));
+      return;
+    }
+
+    // Check if registration is expired
+    if (registration.expiresAt < new Date()) {
+      res.writeHead(410, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Webhook registration expired' }));
+      await this.store.deleteRegistration(registration.id);
+      return;
+    }
+
+    // Parse request body
+    let rawBody = '';
+    let body: unknown = null;
+
+    try {
+      rawBody = await this.readBody(req);
+      if (rawBody) {
+        const contentType = req.headers['content-type'] ?? '';
+        if (contentType.includes('application/json')) {
+          body = JSON.parse(rawBody);
+        } else if (contentType.includes('application/x-www-form-urlencoded')) {
+          body = Object.fromEntries(new URLSearchParams(rawBody));
+        } else {
+          body = rawBody;
+        }
+      }
+    } catch (error) {
+      body = rawBody;
+    }
+
+    // Create event
+    const event: WebhookEvent = {
+      id: randomUUID(),
+      registrationId: registration.id,
+      receivedAt: new Date(),
+      method: req.method ?? 'POST',
+      headers: this.extractHeaders(req),
+      body,
+      rawBody,
+      query: url.query as Record<string, string>,
+    };
+
+    // Save event
+    await this.store.saveEvent(event);
+    registration.receivedEvents++;
+    await this.store.saveRegistration(registration);
+
+    this.log(`Webhook received: ${path} (${registration.receivedEvents}/${registration.expectedEvents})`);
+    this.callbacks.onWebhookReceived?.(event);
+
+    // Check if all expected events received
+    if (registration.receivedEvents >= registration.expectedEvents) {
+      const events = await this.store.getEvents(registration.id);
+      this.callbacks.onRegistrationComplete?.(registration, events);
+
+      // Resolve pending wait
+      const pending = this.pendingWaits.get(registration.id);
+      if (pending) {
+        clearTimeout(pending.timeoutId);
+        this.pendingWaits.delete(registration.id);
+        pending.resolve({ success: true, events });
+      }
+    }
+
+    // Send response
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      success: true,
+      eventId: event.id,
+      received: registration.receivedEvents,
+      expected: registration.expectedEvents,
+    }));
+  }
+
+  /**
+   * Read request body
+   */
+  private readBody(req: IncomingMessage): Promise<string> {
+    return new Promise((resolve, reject) => {
+      let data = '';
+      req.on('data', (chunk) => {
+        data += chunk;
+      });
+      req.on('end', () => {
+        resolve(data);
+      });
+      req.on('error', reject);
+    });
+  }
+
+  /**
+   * Extract headers from request
+   */
+  private extractHeaders(req: IncomingMessage): Record<string, string> {
+    const headers: Record<string, string> = {};
+    for (const [key, value] of Object.entries(req.headers)) {
+      if (typeof value === 'string') {
+        headers[key] = value;
+      } else if (Array.isArray(value)) {
+        headers[key] = value.join(', ');
+      }
+    }
+    return headers;
+  }
+
+  /**
+   * Clean up expired registrations
+   */
+  private async cleanup(): Promise<void> {
+    const cleaned = await this.store.cleanupExpired();
+    if (cleaned > 0) {
+      this.log(`Cleaned up ${cleaned} expired webhook registration(s)`);
+    }
+  }
+
+  /**
+   * Log message if verbose mode enabled
+   */
+  private log(message: string): void {
+    if (this.config.verbose) {
+      console.log(`[Webhook] ${message}`);
+    }
+  }
+}