Bug 275158 – [DNR] Rule condition to match on response headers

• Status: NEW
• Component: WebKit Extensions

[Daniel Jacobs]

DNR will soon have an API to match requests by response header. As noted in the corresponding Mozilla bug, this is a deviation from before: previously all matched rules could be determined at the start of the request, now rules also need to be evaluated at the onHeadersReceived stage. This is already implemented in Chrome Canary, so it's clear the design is near-stable.

This includes a dictionary as defined below:

  dictionary HeaderInfo {
    // The name of the header. This condition matches on the name
    // only if both `values` and `excludedValues` are not specified.
    DOMString header;
    // If specified, this condition matches if the header's value
    // contains at least one element in this list.
    DOMString[]? values;
    // If specified, this condition is not matched if the header
    // exists but its value contains at least one element in this list.
    DOMString[]? excludedValues;
  };

Alongside a two new RuleConditions defined below:

    // Rule matches if the request matches any response header condition in this
    // list (if specified).
    HeaderInfo[]? responseHeaders;

    // Rule does not match if the request matches any response header
    // condition in this list (if specified). If both `excludedResponseHeaders`
    // and `responseHeaders` are specified, then the `excludedResponseHeaders`
    // property takes precedence.
    HeaderInfo[]? excludedResponseHeaders;

W3C Proposal: https://github.com/w3c/webextensions/issues/460
Chrome Bug: https://issues.chromium.org/issues/40727004
Chrome Internal Documentation for the API: https://source.chromium.org/chromium/chromium/src/+/main:extensions/common/api/declarative_net_request.idl
Firefox Bug: https://bugzilla.mozilla.org/show_bug.cgi?id=1877486

[Radar WebKit Bug Importer]

<rdar://problem/129282566>

[Daniel Jacobs]

I tried to add https://issues.chromium.org/issues/40727004 to See Also but it gives an error message, saying it needs to be at bugs.chromium.org instead.

[Daniel Jacobs]

Bug added to See Also by adding the outdated format of URL that redirects to https://issues.chromium.org/issues/40727004. Opened https://bugs.webkit.org/show_bug.cgi?id=275174 as a meta-bug for that issue.

[Daniel Jacobs]

It appears that the proposal at https://github.com/w3c/webextensions/issues/460 is now basically settled. According to https://github.com/w3c/webextensions/blob/main/_minutes/2024-06-20-wecg.md, "ways of matching substrings" was "the last major thing to resolve", and there was a thought that "globs would offer the balance between functionality and performance". Subsequently, Rob noted in https://github.com/w3c/webextensions/issues/460#issuecomment-2198661058 "Since the expected number of header matching rules is low, I don't expect a significant performance impact with the use of globs for matching headers." Since then, globs were added to Chromium's in-progress implementation, and more recently, response header matching was enabled on stable: https://issues.chromium.org/issues/40727004#comment66.

[Daniel Jacobs]

This is now feature-complete in Chromium: https://issues.chromium.org/issues/40727004#comment69

You can find the internal documentation on the new HeaderInfo dictionary here:

https://source.chromium.org/chromium/chromium/src/+/0e7b854de08540505da2688660ed40fe1dad990e:extensions/common/api/declarative_net_request.idl;l=173-191

The two new RuleCondition types are here, and they are optional arrays of HeaderInfo, named responseHeaders and excludedResponseHeaders: https://source.chromium.org/chromium/chromium/src/+/0e7b854de08540505da2688660ed40fe1dad990e:extensions/common/api/declarative_net_request.idl;l=363-371

[Daniel Jacobs]

Official docs: https://developer.chrome.com/docs/extensions/reference/api/declarativeNetRequest#type-HeaderInfo and https://developer.chrome.com/docs/extensions/reference/api/declarativeNetRequest#property-RuleCondition-excludedResponseHeaders and https://developer.chrome.com/docs/extensions/reference/api/declarativeNetRequest#property-RuleCondition-responseHeaders