Add navigationId to PerformanceEntry (#192)

Add id and navigationId fields to PerformanceEntry. These are integers, used to uniquely identify timeline entries,
so that they can be referred to in other entries. The initial use case for this is to track navigation-like events within
a page's lifetime. For this, the navigationId field is used, in each entry, to refer to the most recent navigation (or
back-forward-cache restoration, or soft navigation) which had occurred in the page.

---------

Co-authored-by: Marcos Cáceres <marcos@marcosc.com>

Author: clelland

explainer.md

@@ -55,10 +55,12 @@ In order to prevent the user agent from storing too much performance data in mem
 This specification defines the `PerformanceEntry` interface, which is used to host performance data of the web application.
 A single `PerformanceEntry` object corresponds to one nugget of information about the performance of the website.
 The entry has the following attributes:
+* `id`: an integer identifying this `PerformanceEntry` object.
 * `name`: a string identifier for the object, also used to filter entries in the `getEntriesByName()` method.
 * `entryType`: a string representing the type of performance data being exposed. It is also used to filter entries in the `getEntriesByType()` method and in the `PerformanceObserver`.
 * `startTime`: a timestamp representing the starting point for the performance data being recorded. The semantics of this attribute depend on the `entryType`.
 * `duration`: a time duration representing the duration of the performance data being recorded. The semantics of this one also depend on the `entryType`.
+* `navigationId`: an integer identifying (by `id`)  the `PerformanceEntry` object corresponding to last navigation or navigation-like event that had occurred in the document at the time that this `PerformanceEntry` object was recorded.
 
 If these sound abstract, it’s because they are.
 A specification whose goal is to expose new measurements to web developers will define a new interface which extends `PerformanceEntry`.
@@ -150,6 +152,20 @@ For entryTypes with a fixed amount of entries, like Paint Timing, using the poll
 At the same time, the callback is more useful for cases where there is varying amount of entries of the given entryType, like in Resource Timing.
 The web performance monitoring service can process all the performance information while the page is still running and only has to do very minimal work when the data needs to be reported.
 
+## Page lifetime issues
+When this API was originally designed, documents had a relatively simple lifecycle: they were
+loaded when the user navigated to them, and unloaded when the user navigated away, with the
+JavaScript environment being torn down at that time. Since then, the sitution has become more
+complex, with many browsers introducing a back-forward cache, with which a user can return to
+a document which they have previously navigated away from. The web has also seen a rise in
+popularity of Single Page Apps, where what appears to the user to be a navigation is actually
+just a change in state of a running page. In both of these situations, a navigation (or what
+appears to the user as a navigation) can occur without the performance timeline being reset.
+In order to allow developers to reason about such events during the life of a page, some
+PerformanceEntry objects mark navigations, or navigation-like events. All PerformanceEntry
+objects include a navigation ID field, which ties each PerformanceEntry to the most recent
+navigation entry which had occurred before the entry was generated.
+
 # Standards Status
 The Performance Timeline specification is widely approved.
 There are differences in what kinds of performance data is exposed on different user agents, but this specification does not concern itself with that, and that is delegated to the new specifications that describe new data.

index.html

@@ -67,6 +67,9 @@
       </li>
       <li>Exposes {{PerformanceEntry}} in Web Workers [[WORKERS]];
       </li>
+      <li>Formalizes support for multiple navigation events over a document's
+      lifetime.
+      </li>
       <li>Adds support for {{PerformanceObserver}}.
       </li>
     </ul>
@@ -243,6 +246,15 @@ <h2><dfn>Performance Timeline</dfn></h2>
           <li>An integer <dfn>dropped entries count</dfn> that is initially 0.</li>
         </ul>
       </li>
+      <li>An integer <dfn>last performance entry id</dfn> that is initially set
+      to a random integer between 100 and 10000.
+      </li>
+    </ul>
+    <p>Each <a>Document</a> has:</p>
+    <ul>
+      <li>A <dfn>most recent navigation</dfn>, which is a <a>PerformanceEntry</a>,
+      initially unset.
+      </li>
     </ul>
     <p>In order to get the <dfn>relevant performance entry tuple</dfn>, given
     <var>entryType</var> and <var>globalObject</var> as input, run the
@@ -301,13 +313,19 @@ <h2>The <dfn>PerformanceEntry</dfn> interface</h2>
     <pre class='idl'>
       [Exposed=(Window,Worker)]
       interface PerformanceEntry {
+        readonly    attribute unsigned long long  id;
         readonly    attribute DOMString           name;
         readonly    attribute DOMString           entryType;
         readonly    attribute DOMHighResTimeStamp startTime;
         readonly    attribute DOMHighResTimeStamp duration;
+        readonly    attribute unsigned long long  navigationId;
         [Default] object toJSON();
       };</pre>
     <dl>
+      <dt><dfn>id</dfn></dt>
+      <dd>
+        This attribute MUST return the value of <a>this</a>'s <a>id</a>.
+      </dd>
       <dt><dfn>name</dfn></dt>
       <dd>
         This attribute MUST return an identifier for this
@@ -341,6 +359,10 @@ <h2>The <dfn>PerformanceEntry</dfn> interface</h2>
         duration concept doesn't apply, a performance metric may choose to
         return a `duration` of <code>0</code>.
       </dd>
+      <dt><dfn>navigationId</dfn></dt>
+      <dd>
+        This attribute MUST return the value of <a>this</a>'s <a>navigationId</a>.
+      </dd>
     </dl>
     <p>When <dfn>toJSON</dfn> is called, run [[WebIDL]]'s <a>default toJSON
     steps</a>.</p>
@@ -660,6 +682,12 @@ <h2>Queue a <code>PerformanceEntry</code></h2>
       <p>To <dfn class="export">queue a PerformanceEntry</dfn> (<var>newEntry</var>), run
       these steps:</p>
       <ol>
+        <li>If <var>newEntry</var>'s {{PerformanceEntry/id}} is unset:
+          <ol>
+            <li>Let <var>id</var> be the result of running <a>generate an id</a> for <var>newEntry</var>.</li>
+            <li>Set <var>newEntry</var>'s {{PerformanceEntry/id}} to <var>id</var>.</li>
+          </ol>
+        </li>
         <li>Let <var>interested observers</var> be an initially empty set of
         <a>PerformanceObserver</a> objects.
         </li>
@@ -669,6 +697,15 @@ <h2>Queue a <code>PerformanceEntry</code></h2>
         <li>Let <var>relevantGlobal</var> be <var>newEntry</var>'s <a>relevant
         global object</a>.
         </li>
+        <li>If <var>relevantGlobal</var> has an [=associated document=]:
+          <ol>
+            <li>Set <var>newEntry</var>'s <a
+            data-lt="PerformanceEntry.navigationId">navigationId</a> to the value of
+            <var>relevantGlobal</var>'s [=associated document=]'s [=most recent navigation=]'s {{PerformanceEntry/id}}.</li>
+          </ol>
+        </li>
+        <li>Otherwise, set <var>newEntry</var>'s <a
+        data-lt="PerformanceEntry.navigationId">navigationId</a> to null.</li>
         <li>For each <a>registered performance observer</a> <var>regObs</var> in
         <var>relevantGlobal</var>'s <a>list of registered performance observer objects</a>:
           <ol>
@@ -714,6 +751,25 @@ <h2>Queue a <code>PerformanceEntry</code></h2>
         </li>
       </ol>
     </section>
+    <section data-link-for="PerformanceObserver">
+      <h2>Queue a navigation <code>PerformanceEntry</code></h2>
+      <p>To <dfn class="export">queue a navigation PerformanceEntry</dfn> (<var>newEntry</var>), run
+      these steps:</p>
+      <ol>
+        <li>Let <var>id</var> be the result of running <a>generate an id</a> for <var>newEntry</var>.</li>
+        <li>Let <var>relevantGlobal</var> be <var>newEntry</var>'s <a>relevant
+        global object</a>.
+        </li>
+        <li>Set <var>newEntry</var>'s {{PerformanceEntry/id}} to <var>id</var>.</li>
+        <li>Set <var>newEntry</var>'s {{PerformanceEntry/navigationId}} to <var>id</var>.</li>
+        <li>If <var>relevantGlobal</var> has an [=associated document=]:
+          <ol>
+            <li>Set <var>relevantGlobal</var>'s [=associated document=]'s [=most recent navigation=] to <var>newEntry</var>.</li>
+          </ol>
+        </li>
+        <li><a>Queue a PerformanceEntry</a> with <var>newEntry</var> as input.</li>
+      </ol>
+    </section>
     <section data-link-for="PerformanceObserver">
       <h2>Queue the PerformanceObserver task</h2>
       <p>When asked to <dfn>queue the PerformanceObserver task</dfn>, given
@@ -883,6 +939,28 @@ <h2>Determine if a performance entry buffer is full</h2>
         <li>Return true.</li>
       </ol>
     </section>
+    <section data-link-for="PerformanceEntry">
+      <h2>Generate a Performance Entry id</h2>
+      <p>When asked to <dfn class="export">generate an id</dfn> for a
+      <a>PerformanceEntry</a> <var>entry</a>, run the following steps:</p>
+      <ol>
+        <li>Let <var>relevantGlobal</var> be <var>entry</var>'s <a>relevant
+        global object</a>.
+        <li>Increase <var>relevantGlobal</var>'s <a>last performance entry
+        id</a> by a small number chosen by the user agent.</li>
+        <li>Return <var>relevantGlobal</var>'s <a>last performance entry id</a>.
+      </ol>
+      <p>A user agent may choose to increase the <a>last performance entry
+      id</a>it by a small random integer every time. A user agent must not pick
+      a single global random integer and increase the <a>last performance entry
+      id</a> of all global objects by that amount because this could introduce
+      cross origin leaks.
+      </p>
+      <p class="note">The <a>last performance entry id</a> has an initial random
+      value, and is increased by a small number chosen by the user agent instead
+      of 1 to discourage developers from considering it as a counter of the
+      number of entries that have been generated in the web application.</p>
+    </section>
   </section>
   <section id="privacy">
     <h3>Privacy Considerations</h3>
@@ -891,6 +969,15 @@ <h3>Privacy Considerations</h3>
       refer to [[HR-TIME-3]] for privacy considerations of exposing high-resoluting timing
       information. Each new specification introducing new performance entries should have its own
       privacy considerations as well.</p>
+    <p>The <a>last performance entry id</a> is deliberately initialized to a
+      random value, and is incremented by another small value every time a new
+      {{PerformanceEntry}} is queued. User agents may choose to use a consistent
+      increment for all users, or may pick a different increment for each
+      <a>global object</a>, or may choose a new random increment for each
+      {{PerformanceEntry}}. However, in order to prevent cross-origin leaks, and
+      ensure that this does not enable fingerprinting, user agents must not just
+      pick a unique random integer, and use it as a consistent increment for all
+      {{PerformanceEntry}} objects across all <a>global objects</a>.
   </section>
   <section id="security">
     <h3>Security Considerations</h3>