hookarmor 1.0.0

package/src/server.js

@@ -0,0 +1,365 @@
+const express = require('express');
+const cors = require('cors');
+const { randomUUID } = require('crypto');
+const path = require('path');
+const fs = require('fs');
+const http = require('http');
+const { WebSocketServer, WebSocket } = require('ws');
+
+const Storage = require('./storage');
+const Dispatcher = require('./dispatcher');
+const RetryWorker = require('./worker');
+
+function isPrivateOrMetadataUrl(urlString) {
+  try {
+    const parsed = new URL(urlString);
+    const hostname = parsed.hostname.toLowerCase();
+    if (
+      hostname === '169.254.169.254' ||
+      hostname === 'metadata.google.internal' ||
+      hostname === '100.100.100.200' ||
+      hostname.startsWith('169.254.')
+    ) {
+      return true;
+    }
+    return false;
+  } catch (e) {
+    return true;
+  }
+}
+
+function createServer(options = {}) {
+  const app = express();
+  const server = http.createServer(app);
+  const wss = new WebSocketServer({ server, path: '/ws' });
+
+  const storage = new Storage(options.dbPath);
+  const dispatcher = new Dispatcher(storage, {
+    defaultConcurrency: options.defaultConcurrency || 5,
+    defaultTimeoutMs: options.defaultTimeoutMs || 25000
+  });
+
+  const worker = new RetryWorker(storage, dispatcher, {
+    intervalMs: options.retryIntervalMs || 5000
+  });
+  if (options.autoStartWorker !== false) {
+    worker.start();
+  }
+
+  server.on('close', () => {
+    worker.stop();
+  });
+
+  // Broadcast helper for real-time WebSocket dashboard
+  function broadcast(type, data) {
+    const payload = JSON.stringify({ type, data });
+    wss.clients.forEach(client => {
+      if (client.readyState === WebSocket.OPEN) {
+        client.send(payload);
+      }
+    });
+  }
+
+  // Hook dispatcher events to WebSocket broadcasts
+  dispatcher.on('delivery', (res) => {
+    broadcast('delivery', res);
+  });
+
+  // Enable CORS
+  app.use(cors());
+
+  // Serve static UI assets
+  app.use('/static', express.static(path.join(__dirname, 'public')));
+
+  // Ingress endpoint for webhooks - uses raw body parser to preserve raw bytes
+  app.post('/in/:endpointId', express.raw({ type: '*/*', limit: '10mb' }), async (req, res) => {
+    const endpointId = req.params.endpointId;
+    const endpoint = storage.getEndpoint(endpointId);
+
+    if (!endpoint) {
+      return res.status(404).json({ error: `HookArmor endpoint not found: ${endpointId}` });
+    }
+
+    const rawBodyBuffer = req.body || Buffer.from('');
+    const rawBody = rawBodyBuffer.toString('utf8');
+    const headers = { ...req.headers };
+
+    // Detect provider & idempotency key
+    let provider = 'generic';
+    let eventType = null;
+    let idempotencyKey = headers['idempotency-key'] || headers['x-idempotency-key'] || null;
+
+    if (headers['stripe-signature']) {
+      provider = 'stripe';
+      try {
+        const parsed = JSON.parse(rawBody);
+        eventType = parsed.type;
+        if (parsed.id) idempotencyKey = parsed.id;
+      } catch (e) {}
+    } else if (headers['x-shopify-hmac-sha256'] || headers['x-shopify-topic']) {
+      provider = 'shopify';
+      eventType = headers['x-shopify-topic'];
+      if (headers['x-shopify-webhook-id']) idempotencyKey = headers['x-shopify-webhook-id'];
+    } else if (headers['x-github-event']) {
+      provider = 'github';
+      eventType = headers['x-github-event'];
+      if (headers['x-github-delivery']) idempotencyKey = headers['x-github-delivery'];
+    } else if (headers['clerk-signature'] || headers['svix-id']) {
+      provider = 'clerk/svix';
+      if (headers['svix-id']) idempotencyKey = headers['svix-id'];
+      try {
+        const parsed = JSON.parse(rawBody);
+        eventType = parsed.type;
+      } catch (e) {}
+    } else {
+      try {
+        const parsed = JSON.parse(rawBody);
+        eventType = parsed.event || parsed.type || parsed.action || null;
+        if (parsed.id) idempotencyKey = String(parsed.id);
+      } catch (e) {}
+    }
+
+    // 0. Verify signature on ingress if endpoint secret is configured
+    if (endpoint.secret) {
+      const verification = Dispatcher.verifyIngressSignature(provider, rawBody, headers, endpoint.secret);
+      if (!verification.valid) {
+        return res.status(400).json({
+          error: 'Webhook signature verification failed',
+          provider,
+          reason: verification.reason
+        });
+      }
+    }
+
+    // Deduplication check: if this event ID was already delivered, ack immediately without duplicating downstream side effects
+    if (idempotencyKey) {
+      const existing = storage.findEventByIdempotencyKey(endpoint.id, idempotencyKey);
+      if (existing && existing.status === 'delivered') {
+        return res.status(200).json({
+          received: true,
+          hookarmor_id: existing.id,
+          status: 'deduplicated',
+          message: `Idempotency key ${idempotencyKey} already delivered. Suppressed duplicate execution.`
+        });
+      }
+    }
+
+    const eventId = `evt_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+
+    // 1. Durably save event in SQLite
+    const savedEvent = storage.saveEvent({
+      id: eventId,
+      endpointId: endpoint.id,
+      idempotencyKey,
+      provider,
+      eventType,
+      headers,
+      rawBody,
+      status: 'pending'
+    });
+
+    broadcast('event:received', {
+      id: eventId,
+      endpointId: endpoint.id,
+      provider,
+      eventType,
+      createdAt: savedEvent.created_at
+    });
+
+    // 2. Respond immediately with 200 OK to the sender so Stripe never times out or backs off
+    res.status(200).json({
+      received: true,
+      hookarmor_id: eventId,
+      status: 'buffered'
+    });
+
+    // 3. Dispatch to target destination asynchronously
+    setImmediate(async () => {
+      try {
+        await dispatcher.dispatch(savedEvent, endpoint);
+      } catch (err) {
+        console.error(`[Ingress] Dispatch error for ${eventId}:`, err);
+      }
+    });
+  });
+
+  // REST API: JSON Body Parser for Dashboard / Management
+  app.use(express.json());
+
+  // Management API Authentication Middleware (optional, active when HOOKARMOR_API_KEY is configured)
+  const apiKey = options.apiKey || process.env.HOOKARMOR_API_KEY || null;
+  app.use('/api', (req, res, next) => {
+    // Keep public waitlist signup open for landing page
+    if (req.path === '/waitlist' && req.method === 'POST') return next();
+
+    // Allow public read-only demo access & replay simulation so prospective users can explore live
+    const isPublicDemo =
+      (req.method === 'GET' && (req.path === '/stats' || req.path === '/endpoints' || req.path === '/events' || /^\/events\/[^\/]+$/.test(req.path))) ||
+      (req.method === 'POST' && (req.path === '/events/replay-all' || /^\/events\/[^\/]+\/replay$/.test(req.path)));
+
+    if (isPublicDemo) return next();
+
+    if (!apiKey) return next();
+
+    // Accept API token strictly via Authorization or X-Api-Key headers (NEVER query string URL)
+    const authHeader = req.headers['authorization'] || '';
+    const token = authHeader.replace(/^Bearer\s+/i, '').trim() || req.headers['x-api-key'] || '';
+    if (!token || token !== apiKey) {
+      return res.status(401).json({ error: 'Unauthorized: valid HookArmor API key required in header' });
+    }
+    next();
+  });
+
+  // Get Stats
+  app.get('/api/stats', (req, res) => {
+    res.json(storage.getStats());
+  });
+
+  // List Endpoints
+  app.get('/api/endpoints', (req, res) => {
+    res.json(storage.listEndpoints());
+  });
+
+  // Create or Update Endpoint
+  app.post('/api/endpoints', (req, res) => {
+    const { id, name, targetUrl, secret, alertWebhookUrl, autoRetry, maxRetries, concurrencyLimit, concurrency_limit } = req.body;
+    if (!id || !name || !targetUrl) {
+      return res.status(400).json({ error: 'id, name, and targetUrl are required' });
+    }
+    if (isPrivateOrMetadataUrl(targetUrl)) {
+      return res.status(400).json({ error: 'targetUrl cannot target cloud metadata or link-local addresses (SSRF blocked)' });
+    }
+    const endpoint = storage.createEndpoint({
+      id,
+      name,
+      targetUrl,
+      secret,
+      alertWebhookUrl,
+      autoRetry: autoRetry !== undefined ? autoRetry : 1,
+      maxRetries: maxRetries || 5,
+      concurrencyLimit: concurrencyLimit || concurrency_limit || 5
+    });
+    res.json(endpoint);
+  });
+
+  // List Events
+  app.get('/api/events', (req, res) => {
+    const { endpointId, status, limit, offset } = req.query;
+    const events = storage.listEvents({
+      endpointId,
+      status,
+      limit: parseInt(limit, 10) || 50,
+      offset: parseInt(offset, 10) || 0
+    });
+    res.json(events);
+  });
+
+  // Get single event with attempts
+  app.get('/api/events/:id', (req, res) => {
+    const event = storage.getEvent(req.params.id);
+    if (!event) return res.status(404).json({ error: 'Event not found' });
+    const attempts = storage.getAttempts(req.params.id);
+    res.json({ ...event, attempts });
+  });
+
+  // Replay a specific event
+  app.post('/api/events/:id/replay', async (req, res) => {
+    try {
+      const result = await dispatcher.replayEvent(req.params.id);
+      res.json(result);
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // Replay all failed events (optionally filtered by endpoint)
+  app.post('/api/events/replay-all', async (req, res) => {
+    try {
+      const { endpointId } = req.body || {};
+      const results = await dispatcher.replayAllFailed(endpointId);
+      res.json({ replayedCount: results.length, results });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // Waitlist Registration
+  app.post('/api/waitlist', (req, res) => {
+    const { email, source } = req.body || {};
+    if (!email || !email.includes('@')) {
+      return res.status(400).json({ error: 'Valid email required' });
+    }
+    const result = storage.addWaitlist(email.trim().toLowerCase(), source || 'landing_page');
+    res.json({ success: true, message: 'Added to HookArmor Cloud beta waitlist!', email: result.email });
+  });
+
+  app.get('/api/waitlist', (req, res) => {
+    res.json(storage.listWaitlist());
+  });
+
+  // Mock Target Receiver (for self-testing and local simulation)
+  let mockTargetBehavior = {
+    statusCode: 200,
+    delayMs: 15,
+    responseBody: { status: 'mock_processed' }
+  };
+
+  app.post('/mock/target', (req, res) => {
+    setTimeout(() => {
+      res.status(mockTargetBehavior.statusCode).json(mockTargetBehavior.responseBody);
+    }, mockTargetBehavior.delayMs);
+  });
+
+  app.post('/mock/config', (req, res) => {
+    mockTargetBehavior = { ...mockTargetBehavior, ...req.body };
+    res.json({ message: 'Mock target configuration updated', config: mockTargetBehavior });
+  });
+
+  app.get('/mock/config', (req, res) => {
+    res.json(mockTargetBehavior);
+  });
+
+  // SEO & Web Crawler Discovery
+  app.get('/robots.txt', (req, res) => {
+    res.type('text/plain');
+    res.sendFile(path.join(__dirname, 'public', 'robots.txt'));
+  });
+
+  app.get('/sitemap.xml', (req, res) => {
+    res.type('application/xml');
+    res.sendFile(path.join(__dirname, 'public', 'sitemap.xml'));
+  });
+
+  app.get('/og-preview.png', (req, res) => {
+    res.type('image/png');
+    res.sendFile(path.join(__dirname, 'public', 'og-preview.png'));
+  });
+
+  // Landing Page Route
+  app.get('/', (req, res) => {
+    res.sendFile(path.join(__dirname, 'public', 'landing.html'));
+  });
+
+  // Interactive Dashboard Routes
+  app.get(['/dashboard', '/app'], (req, res) => {
+    res.sendFile(path.join(__dirname, 'public', 'index.html'));
+  });
+
+  // Engineering Blog Routes
+  app.get('/blog', (req, res) => {
+    res.sendFile(path.join(__dirname, 'public', 'blog', 'index.html'));
+  });
+
+  app.get('/blog/:slug', (req, res) => {
+    const slug = req.params.slug.replace(/[^a-zA-Z0-9-_]/g, '');
+    const filePath = path.join(__dirname, 'public', 'blog', `${slug}.html`);
+    if (fs.existsSync(filePath)) {
+      return res.sendFile(filePath);
+    }
+    res.redirect('/blog');
+  });
+
+  return { app, server, storage, dispatcher, worker };
+}
+
+module.exports = { createServer };

package/src/storage.js

@@ -0,0 +1,266 @@
+const Database = require('better-sqlite3');
+const path = require('path');
+const fs = require('fs');
+
+class Storage {
+  constructor(dbPath) {
+    if (!dbPath) {
+      const dataDir = path.join(__dirname, '..', 'data');
+      if (!fs.existsSync(dataDir)) {
+        fs.mkdirSync(dataDir, { recursive: true });
+      }
+      dbPath = path.join(dataDir, 'hookarmor.db');
+    }
+    this.db = new Database(dbPath);
+    this.init();
+  }
+
+  init() {
+    try {
+      this.db.pragma('journal_mode = WAL');
+      this.db.pragma('synchronous = NORMAL');
+    } catch (e) {}
+
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS endpoints (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        target_url TEXT NOT NULL,
+        secret TEXT,
+        alert_webhook_url TEXT,
+        auto_retry INTEGER DEFAULT 1,
+        max_retries INTEGER DEFAULT 5,
+        concurrency_limit INTEGER DEFAULT 5,
+        created_at TEXT DEFAULT (datetime('now'))
+      );
+
+      CREATE TABLE IF NOT EXISTS events (
+        id TEXT PRIMARY KEY,
+        endpoint_id TEXT NOT NULL,
+        idempotency_key TEXT,
+        provider TEXT DEFAULT 'generic',
+        event_type TEXT,
+        headers TEXT NOT NULL,
+        raw_body TEXT NOT NULL,
+        status TEXT NOT NULL, -- 'pending', 'delivered', 'failed', 'replaying'
+        attempts INTEGER DEFAULT 0,
+        last_status_code INTEGER,
+        last_error TEXT,
+        last_latency_ms INTEGER,
+        next_retry_at TEXT,
+        created_at TEXT DEFAULT (datetime('now')),
+        updated_at TEXT DEFAULT (datetime('now')),
+        FOREIGN KEY (endpoint_id) REFERENCES endpoints(id)
+      );
+
+      CREATE TABLE IF NOT EXISTS delivery_attempts (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        event_id TEXT NOT NULL,
+        status_code INTEGER,
+        response_body TEXT,
+        error_message TEXT,
+        latency_ms INTEGER,
+        attempted_at TEXT DEFAULT (datetime('now')),
+        FOREIGN KEY (event_id) REFERENCES events(id)
+      );
+
+      CREATE TABLE IF NOT EXISTS waitlist (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        email TEXT UNIQUE NOT NULL,
+        source TEXT DEFAULT 'website',
+        created_at TEXT DEFAULT (datetime('now'))
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_events_status ON events(status);
+      CREATE INDEX IF NOT EXISTS idx_events_endpoint ON events(endpoint_id);
+      CREATE INDEX IF NOT EXISTS idx_events_idempotency ON events(endpoint_id, idempotency_key);
+      CREATE INDEX IF NOT EXISTS idx_events_retry ON events(status, next_retry_at);
+      CREATE INDEX IF NOT EXISTS idx_events_created ON events(created_at);
+    `);
+  }
+
+  createEndpoint({ id, name, targetUrl, secret = '', alertWebhookUrl = '', autoRetry = 1, maxRetries = 5, concurrencyLimit = 5 }) {
+    const stmt = this.db.prepare(`
+      INSERT OR REPLACE INTO endpoints (id, name, target_url, secret, alert_webhook_url, auto_retry, max_retries, concurrency_limit)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+    stmt.run(id, name, targetUrl, secret, alertWebhookUrl, autoRetry ? 1 : 0, maxRetries, concurrencyLimit || 5);
+    return this.getEndpoint(id);
+  }
+
+  getEndpoint(id) {
+    return this.db.prepare('SELECT * FROM endpoints WHERE id = ?').get(id);
+  }
+
+  listEndpoints() {
+    return this.db.prepare('SELECT * FROM endpoints ORDER BY created_at DESC').all();
+  }
+
+  findEventByIdempotencyKey(endpointId, idempotencyKey) {
+    if (!idempotencyKey) return null;
+    const row = this.db.prepare('SELECT * FROM events WHERE endpoint_id = ? AND idempotency_key = ?').get(endpointId, idempotencyKey);
+    if (!row) return null;
+    return { ...row, headers: JSON.parse(row.headers) };
+  }
+
+  saveEvent({ id, endpointId, idempotencyKey = null, provider, eventType, headers, rawBody, status = 'pending' }) {
+    const stmt = this.db.prepare(`
+      INSERT INTO events (id, endpoint_id, idempotency_key, provider, event_type, headers, raw_body, status, attempts, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, 0, datetime('now'), datetime('now'))
+    `);
+    stmt.run(
+      id,
+      endpointId,
+      idempotencyKey,
+      provider,
+      eventType,
+      JSON.stringify(headers),
+      rawBody,
+      status
+    );
+    return this.getEvent(id);
+  }
+
+  recordAttempt({ eventId, statusCode, responseBody = '', errorMessage = '', latencyMs = 0, nextRetryAt = null }) {
+    const insertAttempt = this.db.prepare(`
+      INSERT INTO delivery_attempts (event_id, status_code, response_body, error_message, latency_ms, attempted_at)
+      VALUES (?, ?, ?, ?, ?, datetime('now'))
+    `);
+    insertAttempt.run(eventId, statusCode, responseBody.slice(0, 4000), errorMessage.slice(0, 1000), latencyMs);
+
+    const isSuccess = statusCode >= 200 && statusCode < 300;
+    const newStatus = isSuccess ? 'delivered' : 'failed';
+
+    const updateEvent = this.db.prepare(`
+      UPDATE events
+      SET status = ?,
+          attempts = attempts + 1,
+          last_status_code = ?,
+          last_error = ?,
+          last_latency_ms = ?,
+          next_retry_at = ?,
+          updated_at = datetime('now')
+      WHERE id = ?
+    `);
+    updateEvent.run(newStatus, statusCode, errorMessage || (isSuccess ? null : `HTTP ${statusCode}`), latencyMs, nextRetryAt, eventId);
+
+    return this.getEvent(eventId);
+  }
+
+  getEvent(id) {
+    const row = this.db.prepare('SELECT * FROM events WHERE id = ?').get(id);
+    if (!row) return null;
+    return {
+      ...row,
+      headers: JSON.parse(row.headers)
+    };
+  }
+
+  getAttempts(eventId) {
+    return this.db.prepare('SELECT * FROM delivery_attempts WHERE event_id = ? ORDER BY attempted_at DESC').all(eventId);
+  }
+
+  listEvents({ endpointId = null, status = null, limit = 50, offset = 0 } = {}) {
+    let sql = 'SELECT * FROM events WHERE 1=1';
+    const params = [];
+
+    if (endpointId) {
+      sql += ' AND endpoint_id = ?';
+      params.push(endpointId);
+    }
+    if (status) {
+      sql += ' AND status = ?';
+      params.push(status);
+    }
+    sql += ' ORDER BY created_at DESC LIMIT ? OFFSET ?';
+    params.push(limit, offset);
+
+    const rows = this.db.prepare(sql).all(...params);
+    return rows.map(r => ({
+      ...r,
+      headers: JSON.parse(r.headers)
+    }));
+  }
+
+  getStats() {
+    const total = this.db.prepare('SELECT count(*) as count FROM events').get().count;
+    const delivered = this.db.prepare("SELECT count(*) as count FROM events WHERE status = 'delivered'").get().count;
+    const failed = this.db.prepare("SELECT count(*) as count FROM events WHERE status = 'failed'").get().count;
+    const pending = this.db.prepare("SELECT count(*) as count FROM events WHERE status = 'pending'").get().count;
+    const avgLatency = this.db.prepare('SELECT avg(last_latency_ms) as avg_lat FROM events WHERE last_latency_ms IS NOT NULL').get().avg_lat || 0;
+
+    return {
+      total,
+      delivered,
+      failed,
+      pending,
+      avgLatencyMs: Math.round(avgLatency)
+    };
+  }
+
+  getFailedEventsToRetry(endpointId = null) {
+    let sql = `
+      SELECT e.*, ep.max_retries, ep.target_url, ep.secret, ep.alert_webhook_url
+      FROM events e
+      JOIN endpoints ep ON e.endpoint_id = ep.id
+      WHERE e.status = 'failed' AND ep.auto_retry = 1 AND e.attempts < ep.max_retries
+    `;
+    const params = [];
+    if (endpointId) {
+      sql += ' AND e.endpoint_id = ?';
+      params.push(endpointId);
+    }
+    sql += ' ORDER BY e.created_at ASC';
+    const rows = this.db.prepare(sql).all(...params);
+    return rows.map(r => ({
+      ...r,
+      headers: JSON.parse(r.headers)
+    }));
+  }
+
+  getEventsDueForRetry(limit = 25) {
+    const sql = `
+      SELECT e.*, ep.max_retries, ep.target_url, ep.secret, ep.alert_webhook_url
+      FROM events e
+      JOIN endpoints ep ON e.endpoint_id = ep.id
+      WHERE (
+        (e.status = 'failed' AND ep.auto_retry = 1 AND e.attempts < ep.max_retries AND e.next_retry_at IS NOT NULL AND e.next_retry_at <= datetime('now'))
+        OR
+        (e.status = 'pending' AND ep.auto_retry = 1 AND e.created_at <= datetime('now', '-20 seconds'))
+      )
+      ORDER BY e.created_at ASC
+      LIMIT ?
+    `;
+    const rows = this.db.prepare(sql).all(limit);
+    return rows.map(r => ({
+      ...r,
+      headers: JSON.parse(r.headers)
+    }));
+  }
+
+  claimEventForRetry(eventId) {
+    const stmt = this.db.prepare(`
+      UPDATE events
+      SET status = 'replaying', updated_at = datetime('now')
+      WHERE id = ? AND status IN ('failed', 'pending')
+    `);
+    const info = stmt.run(eventId);
+    return info.changes > 0;
+  }
+
+  addWaitlist(email, source = 'website') {
+    const stmt = this.db.prepare(`
+      INSERT INTO waitlist (email, source, created_at)
+      VALUES (?, ?, datetime('now'))
+      ON CONFLICT(email) DO UPDATE SET created_at = datetime('now')
+    `);
+    stmt.run(email, source);
+    return { email, source, status: 'registered' };
+  }
+
+  listWaitlist() {
+    return this.db.prepare('SELECT * FROM waitlist ORDER BY created_at DESC').all();
+  }
+}
+
+module.exports = Storage;

package/src/worker.js

@@ -0,0 +1,62 @@
+const EventEmitter = require('events');
+
+class RetryWorker extends EventEmitter {
+  constructor(storage, dispatcher, options = {}) {
+    super();
+    this.storage = storage;
+    this.dispatcher = dispatcher;
+    this.intervalMs = options.intervalMs || 5000;
+    this.timer = null;
+    this.isProcessing = false;
+  }
+
+  start() {
+    if (this.timer) return;
+    this.timer = setInterval(() => this.tick(), this.intervalMs);
+    // Unref timer so it doesn't hold Node process open during graceful shutdown or tests if desired
+    if (this.timer.unref) this.timer.unref();
+    this.emit('started');
+  }
+
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+      this.emit('stopped');
+    }
+  }
+
+  async tick() {
+    if (this.isProcessing) return;
+    this.isProcessing = true;
+
+    try {
+      const eventsDue = this.storage.getEventsDueForRetry(25);
+      if (!eventsDue || eventsDue.length === 0) {
+        this.isProcessing = false;
+        return;
+      }
+
+      for (const event of eventsDue) {
+        const claimed = this.storage.claimEventForRetry(event.id);
+        if (!claimed) continue; // Another process or manual replay already claimed it
+
+        const endpoint = this.storage.getEndpoint(event.endpoint_id);
+        if (!endpoint) continue;
+
+        this.emit('retry:claimed', { eventId: event.id, endpointId: endpoint.id });
+
+        // Dispatch asynchronously without blocking next iterations
+        this.dispatcher.dispatch(event, endpoint).catch((err) => {
+          this.emit('retry:error', { eventId: event.id, error: err.message });
+        });
+      }
+    } catch (err) {
+      this.emit('error', err);
+    } finally {
+      this.isProcessing = false;
+    }
+  }
+}
+
+module.exports = RetryWorker;