DRY puppeteer-worker: consolidate file-capture lifecycle and event flush behavior

[cawalch]

Problem

The puppeteer-worker has repeated error handling, retry, and flush patterns across multiple modules:

Repeated patterns

1. File capture lifecycle (file-capture.ts): Memory and Redis providers both implement the same store/retrieve/delete/cleanup cycle with identical error logging (console.error("Failed to ...")).

2. Event shipping (event-shipper.ts, puppeteer-runner.ts): Both contain flush/backoff logic for batching events. Retry logic, timeout handling, and "flush on shutdown" are duplicated between the two files.

3. Page event handlers (puppeteer-runner.ts): page.on("console") and page.on("pageerror") both wrap identical try/catch + logging patterns.

Impact

• Shutdown safety: If flush behavior changes (e.g., adding a final drain step), it must be updated in multiple places.
• Error visibility: Different modules log errors differently, making debugging inconsistent.
• Test coverage: Each module's cleanup path is tested separately but shares the same failure modes.

Proposed fix

1. Extract a SafeAsync helper: wraps async ops with standardized error logging and swallowed shutdown errors.

2. Consolidate flush/backoff into EventShipper and have PuppeteerRunner delegate to it rather than duplicating retry logic.

3. Extract page event handler wrapper:

function onPageEvent(page, event, handler) {
  page.on(event, (...args) => {
    try {
      handler(...args);
    } catch (err) {
      console.error(`Error in ${event} handler`, err);
    }
  });
}

Files to change

• services/puppeteer-worker/src/file-capture.ts
• services/puppeteer-worker/src/puppeteer-runner.ts
• services/puppeteer-worker/src/event-shipper.ts
• New: services/puppeteer-worker/src/helpers.ts (for shared utilities)

Acceptance criteria

• Single source of truth for flush/backoff behavior
• Consistent error logging across file capture providers
• Page event handlers wrapped with standardized try/catch
• Lint + tests pass