What Is the Buffered Event Queue in Ego-Browser? 10K CDP Event Handling Explained

The buffered event queue in ego-browser is an in-memory FIFO buffer that stores Chrome DevTools Protocol (CDP) events with a hard capacity of 10,000 entries, automatically discarding the oldest events when the limit is exceeded to prevent memory exhaustion.

The ego-browser runtime maintains this bounded buffer to capture raw CDP messages from the embedded Chromium instance. As implemented in citrolabs/ego-lite, the buffered event queue ensures that high-frequency browser telemetry is temporarily preserved without allowing unbounded memory growth that could destabilize long-running automation scripts.

Core Implementation of the Buffered Event Queue

Queue Declaration and Capacity Limit

The queue infrastructure is defined in package/ego-browser/src/browser-runtime.ts using a simple array initialized at module load time. To protect against memory exhaustion, the implementation enforces a strict 10,000-entry ceiling:

const MAX_BUFFERED_EVENTS = 10000   // src/browser-runtime.ts#L8

const events = []               // src/browser-runtime.ts#L20

This constant governs the maximum number of CDP events retained during any browser session.

Enqueuing CDP Events with Automatic Truncation

Every incoming CDP message triggers an immediate push to the events array. Immediately after insertion, the runtime validates the length and truncates from the front if necessary:

events.push(data)                                    // src/browser-runtime.ts#L287
if (events.length > MAX_BUFFERED_EVENTS) {          // src/browser-runtime.ts#L288
  events.splice(0, events.length - MAX_BUFFERED_EVENTS) // src/browser-runtime.ts#L289
}

This keep-only-latest-N strategy guarantees that the most recent 10,000 CDP events remain available for debugging while older, potentially irrelevant telemetry is silently discarded.

Atomic Event Retrieval via drainBrowserEvents()

To consume buffered data, the runtime exposes the drainBrowserEvents() helper. This function atomically removes all queued events and returns them as an array:

export function drainBrowserEvents() {               // src/browser-runtime.ts#L164
  const out = events.splice(0, events.length)        // src/browser-runtime.ts#L165
  return out
}

Because splice() modifies the underlying array in-place, the operation is safe even when multiple drains occur in rapid succession. After execution, the events array resets to zero length, ready to accumulate the next batch of CDP messages.

Working with the Buffered Event Queue

The following pattern demonstrates how to periodically flush CDP events in production automation scripts:

import { drainBrowserEvents } from 'ego-browser/src/browser-runtime.js'

// Periodically flush the buffered CDP events (e.g., every second)
setInterval(() => {
  const recentEvents = drainBrowserEvents()
  if (recentEvents.length) {
    console.log(`Flushed ${recentEvents.length} CDP events`)
    // Process or forward the events as needed
  }
}, 1000)

When the buffer reaches its 10,000-event limit, the oldest events are dropped before the next drain cycle, ensuring the returned array contains only the most recent telemetry.

Summary

• The buffered event queue is defined in package/ego-browser/src/browser-runtime.ts as a simple array capped at 10,000 entries via MAX_BUFFERED_EVENTS.
• When capacity is exceeded, the runtime automatically truncates the oldest events using splice(0, events.length - MAX_BUFFERED_EVENTS) to maintain the latest 10,000 CDP messages.
• The drainBrowserEvents() function atomically removes and returns all queued events, leaving the buffer empty for subsequent operations.
• This bounded FIFO strategy protects the host process from memory exhaustion while preserving recent browser telemetry for analysis and debugging.

Frequently Asked Questions

What happens when the buffered event queue exceeds 10,000 events?

When the events array length surpasses MAX_BUFFERED_EVENTS, the runtime immediately executes splice(0, events.length - MAX_BUFFERED_EVENTS) to remove the oldest surplus entries. This ensures the buffer never grows beyond the configured limit, silently dropping stale events while retaining the most recent 10,000 CDP telemetry entries.

How do I retrieve events from the buffered event queue?

Import drainBrowserEvents() from package/ego-browser/src/browser-runtime.ts and invoke it to receive an array of all queued CDP events. This function atomically clears the buffer by splicing all elements from the underlying array, ensuring that subsequent calls receive only new events captured after the previous drain.

Is the buffered event queue safe for concurrent access?

Yes. The drainBrowserEvents() function uses splice(0, events.length), which modifies the array in-place atomically. Even if multiple drain operations occur in rapid succession, JavaScript's single-threaded event loop guarantees that each call receives a distinct batch of events without duplication or race conditions.

Where is the buffered event queue capacity configured?

The 10,000-entry capacity is hardcoded as the constant MAX_BUFFERED_EVENTS = 10000 at line 8 of package/ego-browser/src/browser-runtime.ts. This value is evaluated every time a new CDP event is enqueued at line 288, ensuring consistent enforcement of the memory boundary.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}