lighthouse 12.0.0 → 12.1.0

package/core/lib/lantern/{simulator/simulator.js → simulation/Simulator.js}

@@ -4,21 +4,20 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import * as Lantern from '../types/lantern.js';
-import {BaseNode} from '../base-node.js';
-import {TcpConnection} from './tcp-connection.js';
-import {ConnectionPool} from './connection-pool.js';
-import {DNSCache} from './dns-cache.js';
-import {SimulatorTimingMap} from './simulator-timing-map.js';
-import * as constants from '../../../config/constants.js';
-
-const mobileSlow4G = constants.throttling.mobileSlow4G;
-
-/** @typedef {import('../base-node.js').Node} Node */
-/** @typedef {import('../network-node.js').NetworkNode} NetworkNode */
-/** @typedef {import('../cpu-node.js').CPUNode} CpuNode */
-/** @typedef {import('./simulator-timing-map.js').CpuNodeTimingComplete | import('./simulator-timing-map.js').NetworkNodeTimingComplete} CompleteNodeTiming */
-/** @typedef {import('./simulator-timing-map.js').ConnectionTiming} ConnectionTiming */
+import * as Lantern from '../lantern.js';
+import {TcpConnection} from './TcpConnection.js';
+import {ConnectionPool} from './ConnectionPool.js';
+import {DNSCache} from './DNSCache.js';
+import {SimulatorTimingMap} from './SimulationTimingMap.js';
+
+const Constants = Lantern.Simulation.Constants;
+const defaultThrottling = Constants.throttling.mobileSlow4G;
+
+/** @typedef {import('../BaseNode.js').Node} Node */
+/** @typedef {import('../NetworkNode.js').NetworkNode} NetworkNode */
+/** @typedef {import('../CpuNode.js').CPUNode} CpuNode */
+/** @typedef {import('./SimulationTimingMap.js').CpuNodeTimingComplete | import('./SimulationTimingMap.js').NetworkNodeTimingComplete} CompleteNodeTiming */
+/** @typedef {import('./SimulationTimingMap.js').ConnectionTiming} ConnectionTiming */
 
 // see https://cs.chromium.org/search/?q=kDefaultMaxNumDelayableRequestsPerClient&sq=package:chromium&type=cs
 const DEFAULT_MAXIMUM_CONCURRENT_REQUESTS = 10;
@@ -34,7 +33,7 @@ const NodeState = {
   Complete: 3,
 };
 
-/** @type {Record<NetworkNode['record']['priority'], number>} */
+/** @type {Record<NetworkNode['request']['priority'], number>} */
 const PriorityStartTimePenalty = {
   VeryHigh: 0,
   High: 0.25,
@@ -50,6 +49,62 @@ const ALL_SIMULATION_NODE_TIMINGS = new Map();
  * @template [T=any]
  */
 class Simulator {
+  /**
+   * @param {Lantern.Simulation.Settings} settings
+   */
+  static createSimulator(settings) {
+    const {throttlingMethod, throttling, precomputedLanternData, networkAnalysis} = settings;
+
+    /** @type {Lantern.Simulation.Options} */
+    const options = {
+      additionalRttByOrigin: networkAnalysis.additionalRttByOrigin,
+      serverResponseTimeByOrigin: networkAnalysis.serverResponseTimeByOrigin,
+      observedThroughput: networkAnalysis.throughput,
+    };
+
+    // If we have precomputed lantern data, overwrite our observed estimates and use precomputed instead
+    // for increased stability.
+    if (precomputedLanternData) {
+      options.additionalRttByOrigin = new Map(Object.entries(
+        precomputedLanternData.additionalRttByOrigin));
+      options.serverResponseTimeByOrigin = new Map(Object.entries(
+        precomputedLanternData.serverResponseTimeByOrigin));
+    }
+
+    switch (throttlingMethod) {
+      case 'provided':
+        options.rtt = networkAnalysis.rtt;
+        options.throughput = networkAnalysis.throughput;
+        options.cpuSlowdownMultiplier = 1;
+        options.layoutTaskMultiplier = 1;
+        break;
+      case 'devtools':
+        if (throttling) {
+          options.rtt =
+            throttling.requestLatencyMs / Constants.throttling.DEVTOOLS_RTT_ADJUSTMENT_FACTOR;
+          options.throughput =
+            throttling.downloadThroughputKbps * 1024 /
+            Constants.throttling.DEVTOOLS_THROUGHPUT_ADJUSTMENT_FACTOR;
+        }
+
+        options.cpuSlowdownMultiplier = 1;
+        options.layoutTaskMultiplier = 1;
+        break;
+      case 'simulate':
+        if (throttling) {
+          options.rtt = throttling.rttMs;
+          options.throughput = throttling.throughputKbps * 1024;
+          options.cpuSlowdownMultiplier = throttling.cpuSlowdownMultiplier;
+        }
+        break;
+      default:
+        // intentionally fallback to simulator defaults
+        break;
+    }
+
+    return new Simulator(options);
+  }
+
   /**
    * @param {Lantern.Simulation.Options} [options]
    */
@@ -57,10 +112,10 @@ class Simulator {
     /** @type {Required<Lantern.Simulation.Options>} */
     this._options = Object.assign(
       {
-        rtt: mobileSlow4G.rttMs,
-        throughput: mobileSlow4G.throughputKbps * 1024,
+        rtt: defaultThrottling.rttMs,
+        throughput: defaultThrottling.throughputKbps * 1024,
         maximumConcurrentRequests: DEFAULT_MAXIMUM_CONCURRENT_REQUESTS,
-        cpuSlowdownMultiplier: mobileSlow4G.cpuSlowdownMultiplier,
+        cpuSlowdownMultiplier: defaultThrottling.cpuSlowdownMultiplier,
         layoutTaskMultiplier: DEFAULT_LAYOUT_TASK_MULTIPLIER,
         additionalRttByOrigin: new Map(),
         serverResponseTimeByOrigin: new Map(),
@@ -106,7 +161,7 @@ class Simulator {
     /** @type {Lantern.NetworkRequest[]} */
     const records = [];
     graph.getRootNode().traverse(node => {
-      if (node.type === BaseNode.TYPES.NETWORK) {
+      if (node.type === Lantern.BaseNode.TYPES.NETWORK) {
         records.push(node.request);
       }
     });
@@ -192,11 +247,11 @@ class Simulator {
   }
 
   /**
-   * @param {Lantern.NetworkRequest} record
+   * @param {Lantern.NetworkRequest} request
    * @return {?TcpConnection}
    */
-  _acquireConnection(record) {
-    return this._connectionPool.acquire(record);
+  _acquireConnection(request) {
+    return this._connectionPool.acquire(request);
   }
 
   /**
@@ -212,7 +267,7 @@ class Simulator {
    * @param {number} totalElapsedTime
    */
   _startNodeIfPossible(node, totalElapsedTime) {
-    if (node.type === BaseNode.TYPES.CPU) {
+    if (node.type === Lantern.BaseNode.TYPES.CPU) {
       // Start a CPU task if there's no other CPU task in process
       if (this._numberInProgress(node.type) === 0) {
         this._markNodeAsInProgress(node, totalElapsedTime);
@@ -221,7 +276,7 @@ class Simulator {
       return;
     }
 
-    if (node.type !== BaseNode.TYPES.NETWORK) throw new Error('Unsupported');
+    if (node.type !== Lantern.BaseNode.TYPES.NETWORK) throw new Error('Unsupported');
 
     // If a network request is connectionless, we can always start it, so skip the connection checks
     if (!node.isConnectionless) {
@@ -240,7 +295,7 @@ class Simulator {
    * currently in flight.
    */
   _updateNetworkCapacity() {
-    const inFlight = this._numberInProgress(BaseNode.TYPES.NETWORK);
+    const inFlight = this._numberInProgress(Lantern.BaseNode.TYPES.NETWORK);
     if (inFlight === 0) return;
 
     for (const connection of this._connectionPool.connectionsInUse()) {
@@ -254,9 +309,9 @@ class Simulator {
    * @return {number}
    */
   _estimateTimeRemaining(node) {
-    if (node.type === BaseNode.TYPES.CPU) {
+    if (node.type === Lantern.BaseNode.TYPES.CPU) {
       return this._estimateCPUTimeRemaining(node);
-    } else if (node.type === BaseNode.TYPES.NETWORK) {
+    } else if (node.type === Lantern.BaseNode.TYPES.NETWORK) {
       return this._estimateNetworkTimeRemaining(node);
     } else {
       throw new Error('Unsupported');
@@ -286,7 +341,7 @@ class Simulator {
    * @return {number}
    */
   _estimateNetworkTimeRemaining(networkNode) {
-    const record = networkNode.request;
+    const request = networkNode.request;
     const timingData = this._nodeTimings.getNetworkStarted(networkNode);
 
     let timeElapsed = 0;
@@ -294,23 +349,23 @@ class Simulator {
       // Rough access time for seeking to location on disk and reading sequentially.
       // 8ms per seek + 20ms/MB
       // @see http://norvig.com/21-days.html#answers
-      const sizeInMb = (record.resourceSize || 0) / 1024 / 1024;
+      const sizeInMb = (request.resourceSize || 0) / 1024 / 1024;
       timeElapsed = 8 + 20 * sizeInMb - timingData.timeElapsed;
     } else if (networkNode.isNonNetworkProtocol) {
       // Estimates for the overhead of a data URL in Chromium and the decoding time for base64-encoded data.
       // 2ms per request + 10ms/MB
       // @see traces on https://dopiaza.org/tools/datauri/examples/index.php
-      const sizeInMb = (record.resourceSize || 0) / 1024 / 1024;
+      const sizeInMb = (request.resourceSize || 0) / 1024 / 1024;
       timeElapsed = 2 + 10 * sizeInMb - timingData.timeElapsed;
     } else {
-      const connection = this._connectionPool.acquireActiveConnectionFromRecord(record);
-      const dnsResolutionTime = this._dns.getTimeUntilResolution(record, {
+      const connection = this._connectionPool.acquireActiveConnectionFromRequest(request);
+      const dnsResolutionTime = this._dns.getTimeUntilResolution(request, {
         requestedAt: timingData.startTime,
         shouldUpdateCache: true,
       });
       const timeAlreadyElapsed = timingData.timeElapsed;
       const calculation = connection.simulateDownloadUntil(
-        record.transferSize - timingData.bytesDownloaded,
+        request.transferSize - timingData.bytesDownloaded,
         {timeAlreadyElapsed, dnsResolutionTime, maximumTimeToElapse: Infinity}
       );
 
@@ -345,23 +400,23 @@ class Simulator {
     const timingData = this._nodeTimings.getInProgress(node);
     const isFinished = timingData.estimatedTimeElapsed === timePeriodLength;
 
-    if (node.type === BaseNode.TYPES.CPU || node.isConnectionless) {
+    if (node.type === Lantern.BaseNode.TYPES.CPU || node.isConnectionless) {
       return isFinished
         ? this._markNodeAsComplete(node, totalElapsedTime)
         : (timingData.timeElapsed += timePeriodLength);
     }
 
-    if (node.type !== BaseNode.TYPES.NETWORK) throw new Error('Unsupported');
+    if (node.type !== Lantern.BaseNode.TYPES.NETWORK) throw new Error('Unsupported');
     if (!('bytesDownloaded' in timingData)) throw new Error('Invalid timing data');
 
-    const record = node.request;
-    const connection = this._connectionPool.acquireActiveConnectionFromRecord(record);
-    const dnsResolutionTime = this._dns.getTimeUntilResolution(record, {
+    const request = node.request;
+    const connection = this._connectionPool.acquireActiveConnectionFromRequest(request);
+    const dnsResolutionTime = this._dns.getTimeUntilResolution(request, {
       requestedAt: timingData.startTime,
       shouldUpdateCache: true,
     });
     const calculation = connection.simulateDownloadUntil(
-      record.transferSize - timingData.bytesDownloaded,
+      request.transferSize - timingData.bytesDownloaded,
       {
         dnsResolutionTime,
         timeAlreadyElapsed: timingData.timeElapsed,
@@ -374,7 +429,7 @@ class Simulator {
 
     if (isFinished) {
       connection.setWarmed(true);
-      this._connectionPool.release(record);
+      this._connectionPool.release(request);
       this._markNodeAsComplete(node, totalElapsedTime, calculation.connectionTiming);
     } else {
       timingData.timeElapsed += calculation.timeElapsed;
@@ -424,7 +479,7 @@ class Simulator {
    *
    * Simulator/connection pool are allowed to deviate from what was
    * observed in the trace/devtoolsLog and start requests as soon as they are queued (i.e. do not
-   * wait around for a warm connection to be available if the original record was fetched on a warm
+   * wait around for a warm connection to be available if the original request was fetched on a warm
    * connection).
    *
    * @param {Node} graph
@@ -432,7 +487,7 @@ class Simulator {
    * @return {Lantern.Simulation.Result<T>}
    */
   simulate(graph, options) {
-    if (BaseNode.hasCycle(graph)) {
+    if (Lantern.BaseNode.hasCycle(graph)) {
       throw new Error('Cannot simulate graph with cycle');
     }
 
@@ -477,7 +532,7 @@ class Simulator {
       const minimumTime = this._findNextNodeCompletionTime();
       totalElapsedTime += minimumTime;
 
-      // While this is no longer strictly necessary, it's always better than LH hanging
+      // While this is no longer strictly necessary, it's always better than hanging
       if (!Number.isFinite(minimumTime) || iteration > 100000) {
         throw new Error('Simulation failed, depth exceeded');
       }
@@ -524,7 +579,7 @@ class Simulator {
   }
 
   /**
-   * We attempt to start nodes by their observed start time using the record priority as a tie breaker.
+   * We attempt to start nodes by their observed start time using the request priority as a tie breaker.
    * When simulating, just because a low priority image started 5ms before a high priority image doesn't mean
    * it would have happened like that when the network was slower.
    * @param {Node} node