Project Fission/DocShell Tree Replace

Overview

This wiki page tracks the work required to audit and fix all usage of the `nsIDocShellTreeItem` structure in Gecko, to update it to accommodate Fission semantics.

A large part of the Fission workload involves usage of information contained in docshells, windows, and documents - via the nsIDocShellTreeItem interface: [1]

In pre-fission semantics, the nsIDocShellTreeItem establishes the tree of nested documents, each of which may come from a different security context (origin). As all content data relevant to a given page lives in the same process in pre-Fission Firefox, the entire tree for a given page would be in process memory. This tree is traversed directly by a lot of gecko code: [2].

In post-Fission semantics, this tree will no longer be completely in process for a given top-level document. Only contiguous fragments of the tree from the same origin are held in the same process:

```

       a.com
         |
 +-------+-------+
 |               |
b.com/1        a.com/foo
 |
 +---------+
 |         |
 b.com/2   b.com/3
             |
             |
           a.com/bar

```

In pre-fission semantics, the prior tree would be entirely contained in a single process. Post-fission, this tree will be split across two processes, with three tree fragments across them:

1. A tree fragment (a.com -> a.com/foo) in process A 2. A tree fragment (b.com/1 -> (b.com/2 | b.com/3)) in process B 3. A singleton tree fragment (a.com/bar) in process A

The current usages of `nsIDocShellTreeItem` assume that DocShell trees are in-process. These usages need to be fixed, using various fission-related support infrastructure such as `BrowsingContext`s, `WindowContext`s, and `TabContext`s - or using IPC to remote processes where necessary.

The usage of nsIDocShellTreeItem can be broken down into a few major categories.

Traverse of Tree Structure Only

These uses involve simply using the child and parent pointers within `nsIDocShellTreeItem` to determine certain properties of a document - such as whether it's a root document, or whether it is the child of a root, or whether it has the same type (content vs. chrome) as its parent, etc.

These traversals are typically trivial to fix and form a large proportion of the usage of this structure. The fix typically involves changing the offending code to use `BrowsingContext` traversals instead of the DocShell tree.

As `BrowsingContext` is a cross-process, replicated tree, it fulfills expectations of having the full tree for a document within the querying process.

- TODO: Put link to simple traversal bugs here.**

Existing valid uses

Existing uses of nsIDocShellTreeItem may be valid even in post-fission semantics. For example, some uses of nsIDocShellTreeItem may retrieve a same-origin parent, or null if the parent is not same-origin.

In these cases, the post-Fission behaviour will be consistent with the program logic. I am not explicitly documenting these cases with bugs.