Per-window Private Browsing

Rationale

The current Private Browsing (PB) implementation in Firefox is very disruptive, because it closes all of your open tabs and windows. Although we do a relatively good job at restoring everything back to the state before initiating the PB session, we should really not require the user to give up their existing session.

This page summarizes the design which can lead to a per-window Private Browsing implementation for Desktop Firefox.

Global Private Browsing Mode Design

The global mode PB implementation is basically an application wide boolean flag which designates whether the PB mode is on or off. The private browsing service manages this global flag, and sends a bunch of notifications when the global mode is changing (for example, when the user invokes the Private Browsing flag). Each module which needs to store data which can identify the websites that a user has previously visited needs to handle these notifications in order to adjust its behavior depending on the PB mode flag, and refrain from storing such data inside this mode. For more information on how the existing API works, see this document.

Per-window Private Browsing Mode Design

In order to move towards a per-window PB design, we can't represent the PB state as a global flag any more. At a birds-eye view, we need to store a per-window boolean flag and each module which needs to handle its storage needs based on the PB status should somehow be able to know which window is ultimately responsible for the request at hand.

The per-window flag is going to be handled by a Gecko object called a docshell. A docshell is simply an object which stores the information associated which every document that Gecko loads which has a presentation. Each docshell can either be a content or a chrome docshell. A chrome docshell represents a document which has chrome privileges, such as browser.xul which renders Firefox's main window, or about:addons. A content docshell represents a document which does not have chrome privileges, which is most often used to load a website inside the browser.

The docshells are arranged in a tree. For example, in a simple browser window rendering Google's homepage, there is a chrome docshell representing the browser window, and a content docshell rendering the google.com homepage (plus another content docshell as its child reprenting an iframe inside Google's home page).

We will leverage this structure in order to provide a per-tab Private Browsing API. Firefox is probably not going to expose per-tab PB mode, as it will be too confusing to users, but we can have a more flexible API which add-ons can leverage.