WebSocket DevTools Extension Architecture: Communication Flow Between Injected, Content, and Background Scripts

The extension operates as a three-stage pipeline that bridges the page’s JavaScript context, the extension’s isolated content script, and the background service worker to intercept, enrich, and relay WebSocket events.

The law-chain-hot/websocket-devtools repository implements a browser extension that monitors live WebSocket traffic by coordinating three distinct execution contexts. Understanding the WebSocket DevTools extension architecture requires tracing how data flows from the web page’s native WebSocket constructor through to the DevTools panel.

Injected Script: The Page-Level Proxy

The injected script runs directly inside the web page’s JavaScript context, not in the extension’s isolated world. This positioning is critical because it allows direct access to the page’s global scope.

Intercepting Native WebSocket in src/content/injected.js

In src/content/injected.js (lines ≈15‑90), the script replaces the native WebSocket constructor with a proxy implementation. This proxy records every connection attempt, message transmission, and event lifecycle. When the proxy intercepts an event—such as an incoming message—it immediately serializes the data for transmission.

Transmitting Events to the Content Script

For each intercepted WebSocket event, the injected script calls window.postMessage with a specific payload structure. At line ≈439 of src/content/injected.js, the code posts messages using the identifier source: "websocket-proxy-injected":

// src/content/injected.js – inside the message listener
window.postMessage({
  source: "websocket-proxy-injected",
  type: "websocket-event",
  payload: {
    id: connectionId,
    url: wsUrl,
    type: "message",
    data: event.data,
    direction: "incoming",
    timestamp: Date.now(),
    // binary detection metadata
  }
}, "*");

The postMessage target is set to "*" to ensure the content script (running in the same browsing context but in an isolated JavaScript world) can receive the event.

Content Script: The Isolated Bridge Layer

The content script (src/content/content.js) acts as a bidirectional bridge between the untrusted page context and the privileged extension background. It runs in the extension’s isolated world, meaning it shares the DOM but not the JavaScript global scope with the page.

Receiving Messages from the Injected Context

At lines ≈54‑80, the content script attaches a window.addEventListener("message") handler to capture events from the injected script. It filters incoming messages by checking event.data.source === "websocket-proxy-injected" to ignore unrelated postMessage traffic.

Enriching and Forwarding to the Background

Before relaying events, the content script enriches the payload with metadata unavailable to the page script. It generates a unique messageId, captures the current timestamp, and builds a frameContext object containing the page URL, a stable frame identifier, and an isIframe flag. The enriched message is then transmitted to the background script via chrome.runtime.sendMessage (lines ≈44‑52):

// src/content/content.js – message forwarding logic
const messageWithId = {
  type: "websocket-event",
  data: event.data.payload,
  messageId: generateMessageId(),
  timestamp: Date.now(),
  source: "content-script",
  frameContext: {
    url: window.location.href,
    stableId: getFrameId(),
    isIframe: window !== window.top
  }
};
chrome.runtime.sendMessage(messageWithId);

Handling Control Commands from the Background

The content script also listens for control commands from the background, such as "start-monitoring", "stop-monitoring", "block-outgoing", or "reset-proxy-state". When received via chrome.runtime.onMessage, it forwards these instructions back to the injected script using window.postMessage with source: "websocket-proxy-content" (see the command dispatch switch starting at line 73):

// src/content/content.js – command forwarding
window.postMessage({
  source: "websocket-proxy-content",
  type: commandType, // e.g., "stop-monitoring"
  payload: commandData
}, "*");

Background Script: Central Aggregation and Relay

The background script (src/background/background.js) serves as the central hub that persists connection state, manages DevTools panel communication, and handles browser-level events like navigation.

Receiving and Storing WebSocket Events

At line 82, the background script registers a chrome.runtime.onMessage listener that receives the enriched events from content scripts across all tabs. Each "websocket-event" message is pushed into an in-memory websocketData.connections array (defined at lines 4‑7), maintaining a live history of all WebSocket traffic.

Forwarding to DevTools Panels

The background script maintains a devtoolsPorts collection of long-lived Port objects connected to open DevTools panels. When new WebSocket data arrives, the forwardToDevTools function (lines 31‑47) broadcasts the event via port.postMessage to ensure the UI reflects real-time activity:

// src/background/background.js – DevTools relay
function forwardToDevTools(message) {
  devtoolsPorts.forEach(port => {
    try {
      port.postMessage(message);
    } catch (e) {
      // Handle disconnected ports
    }
  });
}

Managing Global State and Navigation

The background script handles keep-alive pings to prevent service worker suspension and implements circuit-breaker logic for errant connections. It also listens to chrome.tabs.onUpdated (lines 52‑80) to detect real navigation events and clears the corresponding websocketData.connections array when a tab navigates to a new origin, preventing stale data from persisting across page loads.

When a DevTools panel disconnects or sends a control command, the background script uses chrome.tabs.sendMessage to target specific tabs. For example, when a panel disables monitoring, it sends "stop-monitoring" to the content script, which then propagates the command to the injected script.

Complete Bidirectional Communication Flow

The WebSocket DevTools extension architecture implements a closed-loop communication system:

1. Injected script observes native WebSocket activity and emits window.postMessage events with source: "websocket-proxy-injected"
2. Content script captures these events, adds messageId and frameContext metadata, and forwards them via chrome.runtime.sendMessage
3. Background script stores events in websocketData.connections and broadcasts them to DevTools panels via port.postMessage
4. Background script sends control commands (e.g., "reset-proxy-state") via chrome.tabs.sendMessage
5. Content script receives background commands and relays them to the injected script via window.postMessage with source: "websocket-proxy-content"
6. Injected script executes the command (e.g., toggling the proxy on/off)

This pipeline ensures that only the injected script touches the page’s native WebSocket, while the background script maintains global state and the DevTools panel receives frame-aware, enriched telemetry.

Summary

• The injected script (src/content/injected.js) replaces the native WebSocket constructor and intercepts all traffic using a proxy pattern.
• Content scripts (src/content/content.js) bridge the isolated worlds by translating window.postMessage events into Chrome extension runtime.sendMessage calls, adding unique identifiers and frame context.
• The background script (src/background/background.js) aggregates events in websocketData.connections and relays them to DevTools panels via long-lived ports.
• Control commands flow downward from the background script through the content script to the injected script using tabs.sendMessage and postMessage.
• Navigation handling and keep-alive logic reside exclusively in the background script to maintain state consistency across page lifecycles.

Frequently Asked Questions

How does the injected script access the page's native WebSocket?

The injected script runs directly in the page’s JavaScript context by being injected via a <script> tag, allowing it to capture and replace the native WebSocket constructor before page scripts execute. This is the only component that can directly observe unproxied WebSocket traffic because content scripts run in an isolated JavaScript world that cannot access the page’s global variables.

Why does the extension use window.postMessage between the injected and content scripts?

Chrome’s extension architecture isolates content scripts from the page’s JavaScript global scope for security reasons. Since the injected script lives in the page context and the content script lives in the extension context, window.postMessage serves as the only available channel for cross-context communication. The protocol uses the source field ("websocket-proxy-injected" and "websocket-proxy-content") to filter legitimate extension traffic from other page messages.

What happens to WebSocket data when the user navigates to a new page?

The background script listens for chrome.tabs.onUpdated events (lines 52‑80 in src/background/background.js). When detecting a real navigation (as opposed to a hash change), it clears the websocketData.connections array for that specific tab ID. This ensures that the DevTools panel does not display stale connection data from the previous page, while the injected script automatically re-injects into the new page to begin monitoring fresh connections.

How does the background script communicate with the DevTools panel?

The background script maintains a Map or collection of devtoolsPorts representing long-lived connections to open DevTools panels. When WebSocket events arrive from content scripts, the forwardToDevTools function iterates through these ports and calls port.postMessage() to push real-time updates. This port-based architecture allows bidirectional communication, enabling the panel to send control commands (like "block-outgoing") back through the background script to the specific content and injected scripts.

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