Safari declarativeNetRequest Rule Priority Explained

This article provides a complete overview of how the Safari web browser resolves conflicts when multiple extensions use the declarativeNetRequest API to intercept the same network request. By understanding how WebKit evaluates action types, rule priorities, and extension states, developers and users can predict whether a network request will ultimately be blocked, redirected, or modified.

1. Action Type Precedence Across Extensions

When multiple extensions target the same network request, Safari first evaluates the rules based on the type of action being performed. Safari translates declarativeNetRequest rules into native WebKit content-blocking rules, which strictly enforce the following global hierarchy across all active extensions:

  1. Block (block): Blocking rules have the highest global priority. If any enabled extension instructs Safari to block a request, the request is terminated immediately. No other extension can override this block.
  2. Redirect and Upgrade (redirect, upgradeScheme): If no extension blocks the request, Safari evaluates redirects and scheme upgrades (such as forcing HTTPS). An upgradeScheme action is treated as a specialized redirect.
  3. Modify Headers (modifyHeaders): If the request is neither blocked nor redirected to a new destination, Safari processes rules that add, modify, or remove HTTP request and response headers.

2. The Scope of "Allow" Rules

A common point of confusion is how allow and allowAllRequests actions behave when multiple extensions are installed.

In Safari, allow rules only apply within the extension that defines them. If Extension A has a high-priority allow rule for a specific URL, it only prevents Extension A's own block or redirect rules from firing. It does not stop Extension B from blocking or redirecting that same URL.

3. How the priority Property Works

In the declarativeNetRequest API, developers assign a numeric priority to each rule. However, Safari only uses this number to resolve conflicts within a single extension.

For example, if Extension A has a redirect rule with a priority of 10 and a block rule with a priority of 1, Extension A will redirect the request rather than block it.

Safari does not compare rule priority numbers across different extensions. Extension A cannot set a rule priority of 999999 to override a rule with a priority of 1 in Extension B.

4. Resolving Ties Between Multiple Extensions

When two or more extensions attempt to perform the exact same category of action on a request—and neither is a block action—Safari must break the tie. This happens in two specific scenarios:

Competing Redirects

If Extension A wants to redirect a URL to example.com and Extension B wants to redirect the same URL to test.com, Safari cannot execute both. To resolve this, Safari prioritizes the most recently enabled extension. If both were enabled at the same time, the most recently installed or updated extension wins.

Competing Header Modifications

When multiple extensions use modifyHeaders on the same request, Safari attempts to merge the changes whenever possible:

  • Different Headers: If Extension A modifies the User-Agent header and Extension B modifies the Cookie header, both modifications are applied.
  • Appending Headers: If multiple extensions use the append operation on the same header, Safari combines the appended values.
  • Conflicting Operations: If Extension A tries to set (overwrite) a header while Extension B tries to remove that same header, or if both try to set the same header to different values, the conflict is resolved in favor of the most recently enabled extension.

Summary of the Evaluation Flow

When a network request is made in Safari with multiple extensions active, the browser follows this exact sequence:

  1. Internal Evaluation: Each extension independently determines its single winning action for the request using its own rules and numeric priority values (where internal allow rules can cancel out internal block rules).
  2. Global Block Check: Safari checks the winning actions from all extensions. If any extension outputs a block action, the request is blocked.
  3. Global Redirect Check: If there are no blocks, Safari checks for redirect or upgradeScheme actions. If multiple extensions output a redirect, the most recently enabled extension's redirect is executed.
  4. Header Modifications: Before the final request is sent (or when the response is received), Safari applies all modifyHeaders actions, giving precedence to the most recently enabled extension if two extensions directly conflict on the same header name.