tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

resource_tailing.md (13708B)

Firefox Resource Tailing Documentation

Overview

Resource tailing is a network optimization mechanism in Firefox that delays the loading of certain low-priority resources (typically third-party tracking resources) until higher-priority resources have finished loading. This helps improve page load performance by prioritizing resources that are critical for rendering and user interaction.

For information about how resource tailing integrates with Firefox's overall network scheduling and prioritization system, see Firefox Network Scheduling and Prioritization.

How Resource Tailing Works

The Mechanism

  1. Tailing A Resource is Eligible for Tailing When: 1.
  1. Tailing A Resource is Eligible for Tailing When: 1.

- Non-tailed requests are regular resources that load immediately - Tailed requests are delayed resources that are queued until certain conditions are met - The request context maintains a count of active non-tailed requests via AddNonTailRequest() and RemoveNonTailRequest()

  1. Tailing A Resource is Eligible for Tailing When: 1.

- When a channel marked as "tailable" attempts to open, it calls IsContextTailBlocked() - If the context is in tail-blocked state (has active non-tailed requests), the channel is queued - The channel implements nsIRequestTailUnblockCallback and its OnTailUnblock() method is called when unblocked

  1. Tailing A Resource is Eligible for Tailing When: 1.

- Time-based: A timer schedules when to unblock tailed requests. The delay is calculated as: - delay = quantum * mNonTailRequests (with maximum limits) - Default quantum decreases after DOMContentLoaded - The delay decreases progressively with time since page load began - Load completion: When non-tailed request count drops to zero after DOMContentLoaded - Forced unblocking: When the request context is canceled (e.g., navigation away)

  1. Tailing A Resource is Eligible for Tailing When: 1.

` AsyncOpen() or Connect() → WaitingForTailUnblock() checks if channel should be tailed → If yes: queued via IsContextTailBlocked() → mOnTailUnblock callback is set → Later: OnTailUnblock() is called → Executes the saved callback to continue operation `

Eligibility for Tailing

A Resource is Eligible for Tailing When:

  1. Tailing A Resource is Eligible for Tailing When: 1.
  2. Tailing A Resource is Eligible for Tailing When: 1.

- UrgentStart - User-initiated or high-priority requests - Leader - Blocking resources in document head - TailForbidden - Explicitly forbidden from tailing

  1. Tailing A Resource is Eligible for Tailing When: 1.
  2. Tailing A Resource is Eligible for Tailing When: 1.

Resources That Are Tailed

Primary Case: Third-Party Tracking Resources

Secondary Case: Async Scripts with TailAllowed

Resources That Are NEVER Tailed

1. Navigation Requests

2. Leader Resources (Critical Render-Blocking)

- Non-deferred stylesheets (see Loader::LoadSheetAsyncInternal) - Synchronous scripts in document <head> that block loading (see ScriptLoader::PrepareRequestPriorityAndRequestDependencies)

3. UrgentStart Resources (User-Initiated)

- Fetches triggered during user input events (see FetchDriver::HttpFetch()) - Images loaded with urgent flag during interactions (see ImageLoadTask::mUseUrgentStartForChannel) - Top-level document loads

4. TailForbidden Resources

- Deferred scripts when tailing is disabled (see ScriptLoader::PrepareRequestPriorityAndRequestDependencies) - Resources explicitly marked to never be tailed

5. Other Unblocked Resources (without TailAllowed)

- Body synchronous scripts and head/body async scripts (see ScriptLoader::PrepareRequestPriorityAndRequestDependencies) - Other resources that shouldn't be blocked by Leaders but also shouldn't be tailed

6. Resources with TailForbidden Override

Key Files and Interfaces

Core Interfaces

Implementation

- WaitingForTailUnblock(): Checks if channel should be tailed - EligibleForTailing(): Determines tailing eligibility - OnTailUnblock(): Callback when channel is unblocked - Connect() / AsyncOpen(): Entry points that check for tailing

Resource-Specific Code

Classification

HTTP/2 Priority Mapping

For HTTP/2 connections (see urgency calculation in nsHttpHandler::UrgencyFromCoSFlags():

Configuration Preferences

Child Process Handling

Summary

Resource tailing intelligently delays low-priority resources (primarily third-party trackers) to improve page load performance. The system uses:

  1. Actual tail blocking only occurs in the parent process
  2. Actual tail blocking only occurs in the parent process
  3. Actual tail blocking only occurs in the parent process
  4. Actual tail blocking only occurs in the parent process

This creates a more responsive browsing experience by prioritizing resources that matter most to the user while still allowing tracking and analytics resources to eventually load.

Note that on some pages tailing can actually make the pageload slower. See bug 1962817 where the page hides the content until the tracking content loads.