@webblackbox/recorder

@webblackbox/recorder

Event recording engine with normalization, ring buffer, redaction, and plugin system.

The event recording engine for WebBlackbox. Collects raw events from multiple sources (Chrome DevTools Protocol, content scripts, system), normalizes them into the unified WebBlackboxEvent format, and manages a time-windowed ring buffer for memory-efficient session recording.

Overview

• WebBlackboxRecorder — Main entry point for ingesting and processing raw events
• EventRingBuffer — Time-windowed circular buffer with configurable duration
• DefaultEventNormalizer — Maps CDP and content script events to normalized payloads
• ActionSpanTracker — Links related events within user action time windows
• FreezePolicy — Evaluates auto-freeze conditions (errors, network failures, long tasks)
• Redaction — Privacy-preserving payload scrubbing with pattern matching and hashing
• Plugin System — Extensible event processing pipeline

Usage

Basic Recording

import { WebBlackboxRecorder } from "@webblackbox/recorder";
import { DEFAULT_RECORDER_CONFIG } from "@webblackbox/protocol";

const recorder = new WebBlackboxRecorder(DEFAULT_RECORDER_CONFIG, {
  onEvent: (event) => {
    // Forward normalized events to pipeline
    pipeline.ingest(event);
  },
  onFreeze: (reason, event) => {
    // Handle freeze (e.g., export ring buffer)
    console.log(`Session frozen: ${reason}`);
  }
});

// Ingest raw events from various sources
const result = recorder.ingest({
  source: "cdp",
  rawType: "Network.requestWillBeSent",
  tabId: 123,
  sid: "S-1706000000000-abc",
  t: Date.now(),
  mono: performance.now(),
  payload: {
    /* CDP event params */
  }
});

if (result.event) {
  console.log("Normalized event:", result.event.type);
}

if (result.freezeReason) {
  console.log("Freeze triggered:", result.freezeReason);
}

Ring Buffer

// Snapshot all buffered events
const events = recorder.snapshotRingBuffer();

// Get count of buffered events
const count = recorder.getBufferedEventCount();

// Clear the ring buffer
recorder.clearRingBuffer();

Using the Ring Buffer Directly

import { EventRingBuffer } from "@webblackbox/recorder";

const buffer = new EventRingBuffer(10); // 10-minute window

buffer.push(event);
const snapshot = buffer.snapshot(); // Returns events within the window
const size = buffer.size();
buffer.clear();

Event Normalization

The DefaultEventNormalizer handles mapping from raw source events to WebBlackboxEvent types:

CDP Events

CDP Method	WebBlackbox Event
Network.requestWillBeSent	network.request
Network.responseReceived	network.response
Network.loadingFinished	network.finished
Network.loadingFailed	network.failed
Network.webSocketCreated	network.ws.open
Network.webSocketFrameReceived / Network.webSocketFrameSent	network.ws.frame
Network.webSocketClosed	network.ws.close
Runtime.exceptionThrown	error.exception
Runtime.consoleAPICalled	console.entry
Log.entryAdded	console.entry
Page.frameNavigated	nav.commit
Page.navigatedWithinDocument	nav.hash

Content Script Events

Raw Type	WebBlackbox Event
click / dblclick	user.click / user.dblclick
keydown	user.keydown
input	user.input
submit	user.submit
scroll	user.scroll
mousemove	user.mousemove
focus / blur	user.focus / user.blur
resize	user.resize
marker	user.marker
visibilitychange	user.visibility
mutation	dom.mutation.batch
snapshot	dom.snapshot
screenshot	screen.screenshot
console	console.entry
fetch / xhr	network.request / network.response
fetchError	network.failed
pageError / unhandledrejection / resourceError	error.exception / error.unhandledrejection / error.resource
localStorageOp / localStorageSnapshot	storage.local.op / storage.local.snapshot
sessionStorageOp	storage.session.op
indexedDbOp / indexedDbSnapshot	storage.idb.op / storage.idb.snapshot
cookieSnapshot	storage.cookie.snapshot
longtask / vitals	perf.longtask / perf.vitals

dom.rrweb.event is emitted when raw rrweb payloads are ingested (for example, lite mutation-summary events produced by the webblackbox capture agent).

Action Span Tracking

The ActionSpanTracker groups related events into action spans:

import { ActionSpanTracker } from "@webblackbox/recorder";

const tracker = new ActionSpanTracker(1500); // 1500ms action window

// Track user actions (click, submit, marker, nav)
// Related events within the time window are linked via ref.act

Action types: click, submit, marker, nav

Events within the action window receive a ref.act reference linking them to the action span. Network requests initiated during an action are also tracked.

Freeze Policy

The FreezePolicy evaluates conditions that should pause recording:

import { FreezePolicy } from "@webblackbox/recorder";

const policy = new FreezePolicy({
  freezeOnError: true,
  freezeOnNetworkFailure: true,
  freezeOnLongTaskSpike: true
});

const reason = policy.evaluate(event);
// Returns: "error" | "network" | "marker" | "perf" | null

Freeze conditions:

• Error — Uncaught exceptions or unhandled rejections (error.resource is recorded but does not auto-freeze)
• Network failure — Network request failures exceeding threshold (emits freeze reason "network")
• Performance — Long tasks exceeding 200ms
• Marker — User-triggered markers

Redaction

import { redactPayload } from "@webblackbox/recorder";

const redacted = redactPayload(payload, {
  redactHeaders: ["authorization", "cookie", "set-cookie"],
  redactCookieNames: ["token", "session"],
  redactBodyPatterns: ["password", "secret"],
  blockedSelectors: [".secret", "input[type='password']"],
  hashSensitiveValues: true // SHA-256 hash instead of [REDACTED]
});

Redaction is applied recursively through nested objects and supports:

• HTTP header value masking by header name
• Cookie value masking by cookie name
• Body content masking by regex pattern
• DOM element masking by CSS selector
• Optional SHA-256 hashing for value correlation

Plugins

Extend the recorder with custom plugins:

import type { RecorderPlugin, RecorderPluginContext } from "@webblackbox/recorder";

const myPlugin: RecorderPlugin = {
  name: "my-plugin",

  onRawEvent(raw, ctx: RecorderPluginContext) {
    // Process raw events before normalization
    // Return modified raw event or null to drop
    return raw;
  },

  onEvent(event, ctx: RecorderPluginContext) {
    // Process normalized events after recording
    // Can annotate, transform, or filter events
    return event;
  }
};

const recorder = new WebBlackboxRecorder(config, hooks, normalizer, [myPlugin]);

Built-in Plugins

import {
  createRouteContextPlugin,
  createErrorFingerprintPlugin,
  createAiRootCausePlugin,
  createDefaultRecorderPlugins
} from "@webblackbox/recorder";

// Route context tracking per stream
const routePlugin = createRouteContextPlugin();

// Error fingerprint generation
const errorPlugin = createErrorFingerprintPlugin();

// AI-assisted root cause analysis
const aiPlugin = createAiRootCausePlugin(5000); // 5s analysis window

// Bundle of all default plugins
const plugins = createDefaultRecorderPlugins();

License

MIT