webRequest.StreamFilter

A StreamFilter is an object you can use to monitor and modify HTTP responses.

To create a StreamFilter, call webRequest.filterResponseData(), passing it the ID of the web request that you want to filter.

You can imagine the stream filter sitting between the networking stack and browser's rendering engine. The filter is passed HTTP response data as it is received from the network, and can examine and modify the data before passing it along to the rendering engine, where it will be parsed and rendered.

The filter generates four different events:

  • onstart when the filter is about to start receiving response data.
  • ondata when some response data has been received by the filter and is available to be examined or modified.
  • onstop when the filter has finished receiving response data.
  • onerror if an error has occurred in initializing and operating the filter.

You can listen to each event by assigning a listener function to its attribute:

filter.onstart = event => {
  console.log("started");
}

Note that the request is blocked during the execution of any event listeners.

The filter provides a write() function. At any time from the onstart event onwards you can use this function to write data to the output stream.

If you assign listeners to any of the filter's events, then all the response data passed to the rendering engine will be supplied through calls you make to write(): so if you add a listener but don't call write(), then the rendered page will be blank.

Once you have finished interacting with the response you call either of the following:

  • disconnect(): This disconnects the filter from the request, so the rest of the response is processed normally.
  • close(): This closes the request, so no additional response data will be processed.

The filter also provides functions to suspend() and resume() the request.

Methods

webRequest.StreamFilter.close()
Closes the request.
webRequest.StreamFilter.disconnect()
Disconnects the filter from the request.
webRequest.StreamFilter.resume()
Resumes processing of the request.
webRequest.StreamFilter.suspend()
Suspends processing of the request.
webRequest.StreamFilter.write()
Writes some data to the output stream.

Properties

webRequest.StreamFilter.ondata
Event handler which is called when incoming data is available.
webRequest.StreamFilter.onerror
Event handler which is called when an error has occurred.
webRequest.StreamFilter.onstart
Event handler which is called when the stream is about to start receiving data.
webRequest.StreamFilter.onstop
Event handler which is called when the stream has no more data to deliver and has closed.
webRequest.StreamFilter.error
When webRequest.StreamFilter.onerror is called, this will describe the error.
webRequest.StreamFilter.status
Describes the current status of the stream.

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxOperaFirefox for Android
Basic supportChrome No support NoEdge No support NoFirefox Full support 57Opera No support NoFirefox Android Full support 57
closeChrome No support NoEdge No support NoFirefox Full support 57Opera No support NoFirefox Android Full support 57
disconnectChrome No support NoEdge No support NoFirefox Full support 57Opera No support NoFirefox Android Full support 57
errorChrome No support NoEdge No support NoFirefox Full support 57Opera No support NoFirefox Android Full support 57
ondataChrome No support NoEdge No support NoFirefox Full support 57Opera No support NoFirefox Android Full support 57
onerrorChrome No support NoEdge No support NoFirefox Full support 57Opera No support NoFirefox Android Full support 57
onstartChrome No support NoEdge No support NoFirefox Full support 57Opera No support NoFirefox Android Full support 57
onstopChrome No support NoEdge No support NoFirefox Full support 57Opera No support NoFirefox Android Full support 57
resumeChrome No support NoEdge No support NoFirefox Full support 57Opera No support NoFirefox Android Full support 57
statusChrome No support NoEdge No support NoFirefox Full support 57Opera No support NoFirefox Android Full support 57
suspendChrome No support NoEdge No support NoFirefox Full support 57Opera No support NoFirefox Android Full support 57
writeChrome No support NoEdge No support NoFirefox Full support 57Opera No support NoFirefox Android Full support 57

Legend

Full support  
Full support
No support  
No support

Examples

This code listens for onstart, ondata, and onstop. It simply logs those events, and the response data itself:

function listener(details) {
  let filter = browser.webRequest.filterResponseData(details.requestId);

  filter.onstart = event => {
    console.log("started");
  }
 
  filter.ondata = event => {
    console.log(event.data);
    filter.write(event.data);
  }

  filter.onstop = event => {
    console.log("finished");
    filter.disconnect();
  }

  //return {}; // not needed
}

browser.webRequest.onBeforeRequest.addListener(
  listener,
  {urls: ["https://example.org/"], types: ["main_frame"]},
  ["blocking"]
);

Document Tags and Contributors

Contributors to this page: kernp, Watz, wbamberg
Last updated by: kernp,