reqon-dsl 0.2.0

package/src/webhook/store.ts

@@ -0,0 +1,239 @@
+/**
+ * Webhook Store
+ *
+ * Stores webhook registrations and received events.
+ * Supports both in-memory and file-based persistence.
+ */
+
+import { mkdir, readFile, writeFile, readdir, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { WebhookRegistration, WebhookEvent } from './types.js';
+
+/**
+ * Interface for webhook storage
+ */
+export interface WebhookStore {
+  /** Save a webhook registration */
+  saveRegistration(registration: WebhookRegistration): Promise<void>;
+  /** Get a registration by ID */
+  getRegistration(id: string): Promise<WebhookRegistration | undefined>;
+  /** Get a registration by path */
+  getRegistrationByPath(path: string): Promise<WebhookRegistration | undefined>;
+  /** Delete a registration */
+  deleteRegistration(id: string): Promise<void>;
+  /** List all registrations */
+  listRegistrations(): Promise<WebhookRegistration[]>;
+  /** Save a webhook event */
+  saveEvent(event: WebhookEvent): Promise<void>;
+  /** Get events for a registration */
+  getEvents(registrationId: string): Promise<WebhookEvent[]>;
+  /** Delete events for a registration */
+  deleteEvents(registrationId: string): Promise<void>;
+  /** Clean up expired registrations */
+  cleanupExpired(): Promise<number>;
+}
+
+/**
+ * In-memory webhook store
+ */
+export class MemoryWebhookStore implements WebhookStore {
+  private registrations: Map<string, WebhookRegistration> = new Map();
+  private events: Map<string, WebhookEvent[]> = new Map();
+  private pathIndex: Map<string, string> = new Map(); // path -> registrationId
+
+  async saveRegistration(registration: WebhookRegistration): Promise<void> {
+    this.registrations.set(registration.id, registration);
+    this.pathIndex.set(registration.path, registration.id);
+  }
+
+  async getRegistration(id: string): Promise<WebhookRegistration | undefined> {
+    return this.registrations.get(id);
+  }
+
+  async getRegistrationByPath(path: string): Promise<WebhookRegistration | undefined> {
+    const id = this.pathIndex.get(path);
+    if (!id) return undefined;
+    return this.registrations.get(id);
+  }
+
+  async deleteRegistration(id: string): Promise<void> {
+    const reg = this.registrations.get(id);
+    if (reg) {
+      this.pathIndex.delete(reg.path);
+    }
+    this.registrations.delete(id);
+  }
+
+  async listRegistrations(): Promise<WebhookRegistration[]> {
+    return Array.from(this.registrations.values());
+  }
+
+  async saveEvent(event: WebhookEvent): Promise<void> {
+    const events = this.events.get(event.registrationId) ?? [];
+    events.push(event);
+    this.events.set(event.registrationId, events);
+  }
+
+  async getEvents(registrationId: string): Promise<WebhookEvent[]> {
+    return this.events.get(registrationId) ?? [];
+  }
+
+  async deleteEvents(registrationId: string): Promise<void> {
+    this.events.delete(registrationId);
+  }
+
+  async cleanupExpired(): Promise<number> {
+    const now = new Date();
+    let cleaned = 0;
+
+    for (const [id, reg] of this.registrations) {
+      if (reg.expiresAt < now) {
+        await this.deleteRegistration(id);
+        await this.deleteEvents(id);
+        cleaned++;
+      }
+    }
+
+    return cleaned;
+  }
+}
+
+/**
+ * File-based webhook store for persistence across restarts
+ */
+export class FileWebhookStore implements WebhookStore {
+  private baseDir: string;
+  private registrationsDir: string;
+  private eventsDir: string;
+  private initialized = false;
+
+  constructor(baseDir = '.reqon-data/webhooks') {
+    this.baseDir = baseDir;
+    this.registrationsDir = join(baseDir, 'registrations');
+    this.eventsDir = join(baseDir, 'events');
+  }
+
+  private async ensureInit(): Promise<void> {
+    if (this.initialized) return;
+    await mkdir(this.registrationsDir, { recursive: true });
+    await mkdir(this.eventsDir, { recursive: true });
+    this.initialized = true;
+  }
+
+  async saveRegistration(registration: WebhookRegistration): Promise<void> {
+    await this.ensureInit();
+    const filePath = join(this.registrationsDir, `${registration.id}.json`);
+    await writeFile(filePath, JSON.stringify(registration, null, 2));
+  }
+
+  async getRegistration(id: string): Promise<WebhookRegistration | undefined> {
+    await this.ensureInit();
+    try {
+      const filePath = join(this.registrationsDir, `${id}.json`);
+      const content = await readFile(filePath, 'utf-8');
+      const data = JSON.parse(content);
+      return {
+        ...data,
+        createdAt: new Date(data.createdAt),
+        expiresAt: new Date(data.expiresAt),
+      };
+    } catch {
+      return undefined;
+    }
+  }
+
+  async getRegistrationByPath(path: string): Promise<WebhookRegistration | undefined> {
+    const registrations = await this.listRegistrations();
+    return registrations.find((r) => r.path === path);
+  }
+
+  async deleteRegistration(id: string): Promise<void> {
+    await this.ensureInit();
+    try {
+      const filePath = join(this.registrationsDir, `${id}.json`);
+      await unlink(filePath);
+    } catch {
+      // Ignore if file doesn't exist
+    }
+  }
+
+  async listRegistrations(): Promise<WebhookRegistration[]> {
+    await this.ensureInit();
+    try {
+      const files = await readdir(this.registrationsDir);
+      const registrations: WebhookRegistration[] = [];
+
+      for (const file of files) {
+        if (!file.endsWith('.json')) continue;
+        const id = file.replace('.json', '');
+        const reg = await this.getRegistration(id);
+        if (reg) registrations.push(reg);
+      }
+
+      return registrations;
+    } catch {
+      return [];
+    }
+  }
+
+  async saveEvent(event: WebhookEvent): Promise<void> {
+    await this.ensureInit();
+    const eventDir = join(this.eventsDir, event.registrationId);
+    await mkdir(eventDir, { recursive: true });
+    const filePath = join(eventDir, `${event.id}.json`);
+    await writeFile(filePath, JSON.stringify(event, null, 2));
+  }
+
+  async getEvents(registrationId: string): Promise<WebhookEvent[]> {
+    await this.ensureInit();
+    try {
+      const eventDir = join(this.eventsDir, registrationId);
+      const files = await readdir(eventDir);
+      const events: WebhookEvent[] = [];
+
+      for (const file of files) {
+        if (!file.endsWith('.json')) continue;
+        const filePath = join(eventDir, file);
+        const content = await readFile(filePath, 'utf-8');
+        const data = JSON.parse(content);
+        events.push({
+          ...data,
+          receivedAt: new Date(data.receivedAt),
+        });
+      }
+
+      return events.sort((a, b) => a.receivedAt.getTime() - b.receivedAt.getTime());
+    } catch {
+      return [];
+    }
+  }
+
+  async deleteEvents(registrationId: string): Promise<void> {
+    await this.ensureInit();
+    try {
+      const eventDir = join(this.eventsDir, registrationId);
+      const files = await readdir(eventDir);
+      for (const file of files) {
+        await unlink(join(eventDir, file));
+      }
+    } catch {
+      // Ignore if directory doesn't exist
+    }
+  }
+
+  async cleanupExpired(): Promise<number> {
+    const now = new Date();
+    const registrations = await this.listRegistrations();
+    let cleaned = 0;
+
+    for (const reg of registrations) {
+      if (reg.expiresAt < now) {
+        await this.deleteRegistration(reg.id);
+        await this.deleteEvents(reg.id);
+        cleaned++;
+      }
+    }
+
+    return cleaned;
+  }
+}

package/src/webhook/types.ts

@@ -0,0 +1,93 @@
+/**
+ * Webhook Module Types
+ *
+ * Types for webhook server and storage components.
+ */
+
+/**
+ * Represents a pending webhook registration
+ */
+export interface WebhookRegistration {
+  /** Unique ID for this webhook registration */
+  id: string;
+  /** Execution ID that registered this webhook */
+  executionId: string;
+  /** Path for the webhook endpoint */
+  path: string;
+  /** When the registration was created */
+  createdAt: Date;
+  /** When the registration expires */
+  expiresAt: Date;
+  /** Number of events expected */
+  expectedEvents: number;
+  /** Number of events received so far */
+  receivedEvents: number;
+  /** Filter expression (serialized) */
+  filter?: string;
+}
+
+/**
+ * Represents a received webhook event
+ */
+export interface WebhookEvent {
+  /** Unique ID for this event */
+  id: string;
+  /** Registration ID this event belongs to */
+  registrationId: string;
+  /** Received timestamp */
+  receivedAt: Date;
+  /** HTTP method used */
+  method: string;
+  /** Request headers */
+  headers: Record<string, string>;
+  /** Request body (parsed if JSON) */
+  body: unknown;
+  /** Raw body string */
+  rawBody: string;
+  /** Query parameters */
+  query: Record<string, string>;
+}
+
+/**
+ * Configuration for the webhook server
+ */
+export interface WebhookServerConfig {
+  /** Port to listen on (default: 3000) */
+  port?: number;
+  /** Host to bind to (default: '0.0.0.0') */
+  host?: string;
+  /** Base URL for webhook endpoints (e.g., 'https://example.com/webhooks') */
+  baseUrl?: string;
+  /** Default timeout for webhook registrations in ms (default: 300000 = 5 min) */
+  defaultTimeout?: number;
+  /** Enable verbose logging */
+  verbose?: boolean;
+}
+
+/**
+ * Callbacks for webhook server events
+ */
+export interface WebhookServerCallbacks {
+  /** Called when a webhook is received */
+  onWebhookReceived?: (event: WebhookEvent) => void;
+  /** Called when a registration is created */
+  onRegistrationCreated?: (registration: WebhookRegistration) => void;
+  /** Called when a registration expires */
+  onRegistrationExpired?: (registration: WebhookRegistration) => void;
+  /** Called when all expected events are received */
+  onRegistrationComplete?: (registration: WebhookRegistration, events: WebhookEvent[]) => void;
+}
+
+/**
+ * Result of waiting for webhook events
+ */
+export interface WaitResult {
+  /** Whether the wait was successful */
+  success: boolean;
+  /** Events received */
+  events: WebhookEvent[];
+  /** Error message if failed */
+  error?: string;
+  /** Whether timed out */
+  timedOut?: boolean;
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "src/benchmark/**/*", "src/**/*.test.ts"]
+}

package/vitest.config.ts

@@ -0,0 +1,39 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    // Test file patterns
+    include: ['src/**/*.test.ts'],
+
+    // Coverage configuration
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'text-summary', 'html'],
+      reportsDirectory: './coverage',
+
+      // Include all source files
+      include: ['src/**/*.ts'],
+
+      // Exclude test files and index re-exports
+      exclude: [
+        'src/**/*.test.ts',
+        'src/**/index.ts',
+        'src/cli.ts', // CLI is hard to test
+      ],
+
+      // Thresholds (can be made stricter over time)
+      thresholds: {
+        statements: 50,
+        branches: 40,
+        functions: 50,
+        lines: 50,
+      },
+    },
+
+    // Global test timeout
+    testTimeout: 10000,
+
+    // Environment
+    environment: 'node',
+  },
+});