misc: document where network timings come from

core/lib/network-request.js

@@ -9,6 +9,48 @@
  * @fileoverview Fills most of the role of NetworkManager and NetworkRequest classes from DevTools.
  * @see https://cs.chromium.org/chromium/src/third_party/blink/renderer/devtools/front_end/sdk/NetworkRequest.js
  * @see https://cs.chromium.org/chromium/src/third_party/blink/renderer/devtools/front_end/sdk/NetworkManager.js
+
+ A detailed overview of the Chromium networking layer can be found here:
+    https://github.com/raw/GoogleChrome/lighthouse/master/docs/Network-Timing.svg
+
+  Below is a simplified model.
+
+  DevTools box-whisker
+
+    |-------[xxxxxXXXXXX]-|
+       (1)    (2)    (3) (4)
+
+  (1) leading whisker
+
+      Covers various stages:
+
+      - Queuing (delta between renderer knowing about request and network manager knowing about it)
+      - DNS
+      - Connection setup cost (TCP, TLS, SSL, etc.)
+
+      CDP: left whisker edge is Network.requestWillBeSent timestamp
+
+  (2) light shaded region
+
+      browser network manager has initiated the request, hasn't recieved any bytes back yet
+      Note: even with early-hint response, only the "real" response is considered here
+
+      CDP: Network.requestWillBeSentExtraInfo timing.requestTime + timing.sendStart
+
+  (3) dark shaded region
+
+      browser network manager has recieved the very first header byte
+
+      CDP:   Network.requestWillBeSentExtraInfo timing.requestTime + timing.recievedHeadersEnd
+      CDP:   (right edge of box) Network.finished/Network.failed timestamp
+      Trace: ResourceFinish.finishedTime
+
+  (4) trailing whisker
+
+      Marks time when render process main thread is available to use the resource. Could be long
+      if main thread is busy. Currently don't use this anywhere.
+
+      Trace: ResourceFinish.ts
  */
 
 import URL from './url-shim.js';
@@ -322,6 +364,7 @@ class NetworkRequest {
     if (timing.requestTime === 0 || timing.receiveHeadersEnd === -1) return;
     // Take startTime and responseReceivedTime from timing data for better accuracy.
     // Timing's requestTime is a baseline in seconds, rest of the numbers there are ticks in millis.
+    // TODO: This skips the "queuing time" before the netstack has taken over ... is this a mistake?
     this.startTime = timing.requestTime;
     const headersReceivedTime = timing.requestTime + timing.receiveHeadersEnd / 1000;
     if (!this.responseReceivedTime || this.responseReceivedTime < 0) {