lighthouse 12.0.0 → 12.1.0-dev.20240618

package/core/lib/lantern/simulation/TCPConnection.test.js

@@ -0,0 +1,374 @@
+/**
+ * @license
+ * Copyright 2017 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import assert from 'assert/strict';
+
+import * as Lantern from '../lantern.js';
+
+const {TcpConnection} = Lantern.Simulation;
+
+describe('DependencyGraph/Simulator/TcpConnection', () => {
+  describe('#constructor', () => {
+    it('should create the connection', () => {
+      const rtt = 150;
+      const throughput = 1600 * 1024;
+      const connection = new TcpConnection(rtt, throughput);
+      assert.ok(connection);
+      assert.equal(connection._rtt, rtt);
+    });
+  });
+
+  describe('#maximumSaturatedConnections', () => {
+    it('should compute number of supported simulated requests', () => {
+      const availableThroughput = 1460 * 8 * 10; // 10 TCP segments/second
+      assert.equal(TcpConnection.maximumSaturatedConnections(100, availableThroughput), 1);
+      assert.equal(TcpConnection.maximumSaturatedConnections(300, availableThroughput), 3);
+      assert.equal(TcpConnection.maximumSaturatedConnections(1000, availableThroughput), 10);
+    });
+  });
+
+  describe('.setWarmed', () => {
+    it('adjusts the time to download appropriately', () => {
+      const connection = new TcpConnection(100, Infinity);
+      assert.equal(connection.simulateDownloadUntil(0).timeElapsed, 300);
+      connection.setWarmed(true);
+      assert.equal(connection.simulateDownloadUntil(0).timeElapsed, 100);
+    });
+  });
+
+  describe('.setCongestionWindow', () => {
+    it('adjusts the time to download appropriately', () => {
+      const connection = new TcpConnection(100, Infinity);
+      assert.deepEqual(connection.simulateDownloadUntil(50000), {
+        bytesDownloaded: 50000,
+        extraBytesDownloaded: 0,
+        congestionWindow: 40,
+        roundTrips: 5,
+        timeElapsed: 500,
+        connectionTiming: {
+          connectionTime: 250,
+          dnsResolutionTime: 0,
+          sslTime: 100,
+          timeToFirstByte: 300,
+        },
+      });
+      connection.setCongestionWindow(40); // will download all in one round trip
+      assert.deepEqual(connection.simulateDownloadUntil(50000), {
+        bytesDownloaded: 50000,
+        extraBytesDownloaded: 0,
+        congestionWindow: 40,
+        roundTrips: 3,
+        timeElapsed: 300,
+        connectionTiming: {
+          connectionTime: 250,
+          dnsResolutionTime: 0,
+          sslTime: 100,
+          timeToFirstByte: 300,
+        },
+      });
+    });
+  });
+
+  describe('.setH2OverflowBytesDownloaded', () => {
+    it('adjusts the time to download appropriately for H2 connections', () => {
+      const connection = new TcpConnection(100, Infinity, 0, true, true);
+      connection.setWarmed(true);
+      assert.equal(connection.simulateDownloadUntil(30000).timeElapsed, 200);
+      connection.setH2OverflowBytesDownloaded(20000);
+      assert.equal(connection.simulateDownloadUntil(30000).timeElapsed, 100);
+      connection.setH2OverflowBytesDownloaded(50000);
+      assert.equal(connection.simulateDownloadUntil(30000).timeElapsed, 0);
+    });
+
+    it('does not adjust the time to download for non-H2 connections', () => {
+      const connection = new TcpConnection(100, Infinity, 0, true, false);
+      connection.setWarmed(true);
+      assert.equal(connection.simulateDownloadUntil(30000).timeElapsed, 200);
+      connection.setH2OverflowBytesDownloaded(20000);
+      assert.equal(connection.simulateDownloadUntil(30000).timeElapsed, 200);
+      connection.setH2OverflowBytesDownloaded(50000);
+      assert.equal(connection.simulateDownloadUntil(30000).timeElapsed, 200);
+    });
+  });
+
+  describe('.simulateDownloadUntil', () => {
+    describe('when maximumTime is not set', () => {
+      it('should provide the correct values small payload non-SSL', () => {
+        const connection = new TcpConnection(100, Infinity, 0, false);
+        assert.deepEqual(connection.simulateDownloadUntil(7300), {
+          bytesDownloaded: 7300,
+          extraBytesDownloaded: 0,
+          congestionWindow: 10,
+          roundTrips: 2,
+          timeElapsed: 200,
+          connectionTiming: {
+            connectionTime: 150,
+            dnsResolutionTime: 0,
+            sslTime: undefined, // non-SSL
+            timeToFirstByte: 200,
+          },
+        });
+      });
+
+      it('should provide the correct values small payload SSL', () => {
+        const connection = new TcpConnection(100, Infinity, 0, true);
+        assert.deepEqual(connection.simulateDownloadUntil(7300), {
+          bytesDownloaded: 7300,
+          extraBytesDownloaded: 0,
+          congestionWindow: 10,
+          roundTrips: 3,
+          timeElapsed: 300,
+          connectionTiming: {
+            connectionTime: 250,
+            dnsResolutionTime: 0,
+            sslTime: 100,
+            timeToFirstByte: 300,
+          },
+        });
+      });
+
+      it('should provide the correct values small payload H2', () => {
+        const connection = new TcpConnection(100, Infinity, 0, true, true);
+        assert.deepEqual(connection.simulateDownloadUntil(7300), {
+          bytesDownloaded: 7300,
+          extraBytesDownloaded: 7300,
+          congestionWindow: 10,
+          roundTrips: 3,
+          timeElapsed: 300,
+          connectionTiming: {
+            connectionTime: 250,
+            dnsResolutionTime: 0,
+            sslTime: 100,
+            timeToFirstByte: 300,
+          },
+        });
+      });
+
+      it('should provide the correct values response time', () => {
+        const responseTime = 78;
+        const connection = new TcpConnection(100, Infinity, responseTime, true);
+        assert.deepEqual(connection.simulateDownloadUntil(7300), {
+          bytesDownloaded: 7300,
+          extraBytesDownloaded: 0,
+          congestionWindow: 10,
+          roundTrips: 3,
+          timeElapsed: 300 + responseTime,
+          connectionTiming: {
+            connectionTime: 250,
+            dnsResolutionTime: 0,
+            sslTime: 100,
+            timeToFirstByte: 378,
+          },
+        });
+      });
+
+      it('should provide the correct values large payload', () => {
+        const connection = new TcpConnection(100, 8 * 1000 * 1000);
+        const bytesToDownload = 10 * 1000 * 1000; // 10 mb
+        assert.deepEqual(connection.simulateDownloadUntil(bytesToDownload), {
+          bytesDownloaded: bytesToDownload,
+          extraBytesDownloaded: 0,
+          congestionWindow: 68,
+          roundTrips: 105,
+          timeElapsed: 10500,
+          connectionTiming: {
+            connectionTime: 250,
+            dnsResolutionTime: 0,
+            sslTime: 100,
+            timeToFirstByte: 300,
+          },
+        });
+      });
+
+      it('should provide the correct values resumed small payload', () => {
+        const connection = new TcpConnection(100, Infinity, 0, true);
+        assert.deepEqual(connection.simulateDownloadUntil(7300, {timeAlreadyElapsed: 250}), {
+          bytesDownloaded: 7300,
+          extraBytesDownloaded: 0,
+          congestionWindow: 10,
+          roundTrips: 3,
+          timeElapsed: 50,
+          connectionTiming: {
+            connectionTime: 250,
+            dnsResolutionTime: 0,
+            sslTime: 100,
+            timeToFirstByte: 300,
+          },
+        });
+      });
+
+      it('should provide the correct values resumed small payload H2', () => {
+        const connection = new TcpConnection(100, Infinity, 0, true, true);
+        connection.setWarmed(true);
+        connection.setH2OverflowBytesDownloaded(10000);
+        assert.deepEqual(connection.simulateDownloadUntil(7300), {
+          bytesDownloaded: 0,
+          extraBytesDownloaded: 2700, // 10000 - 7300
+          congestionWindow: 10,
+          roundTrips: 0,
+          timeElapsed: 0,
+          connectionTiming: {
+            timeToFirstByte: 0,
+          },
+        });
+      });
+
+      it('should provide the correct values resumed large payload', () => {
+        const connection = new TcpConnection(100, 8 * 1000 * 1000);
+        const bytesToDownload = 5 * 1000 * 1000; // 5 mb
+        connection.setCongestionWindow(68);
+        assert.deepEqual(
+          connection.simulateDownloadUntil(bytesToDownload, {timeAlreadyElapsed: 5234}),
+          {
+            bytesDownloaded: bytesToDownload,
+            extraBytesDownloaded: 0,
+            congestionWindow: 68,
+            roundTrips: 51, // 5 mb / (1460 * 68)
+            timeElapsed: 5100,
+            connectionTiming: {
+              connectionTime: 250,
+              dnsResolutionTime: 0,
+              sslTime: 100,
+              timeToFirstByte: 300,
+            },
+          }
+        );
+      });
+    });
+
+    describe('when maximumTime is set', () => {
+      it('should provide the correct values less than TTFB', () => {
+        const connection = new TcpConnection(100, Infinity, 0, false);
+        assert.deepEqual(
+          connection.simulateDownloadUntil(7300, {timeAlreadyElapsed: 0, maximumTimeToElapse: 68}),
+          {
+            bytesDownloaded: 7300,
+            extraBytesDownloaded: 0,
+            congestionWindow: 10,
+            roundTrips: 2,
+            timeElapsed: 200,
+            connectionTiming: {
+              connectionTime: 150,
+              dnsResolutionTime: 0,
+              sslTime: undefined, // non-SSL
+              timeToFirstByte: 200,
+            },
+          }
+        );
+      });
+
+      it('should provide the correct values just over TTFB', () => {
+        const connection = new TcpConnection(100, Infinity, 0, false);
+        assert.deepEqual(
+          connection.simulateDownloadUntil(7300, {timeAlreadyElapsed: 0, maximumTimeToElapse: 250}),
+          {
+            bytesDownloaded: 7300,
+            extraBytesDownloaded: 0,
+            congestionWindow: 10,
+            roundTrips: 2,
+            timeElapsed: 200,
+            connectionTiming: {
+              connectionTime: 150,
+              dnsResolutionTime: 0,
+              sslTime: undefined, // non-SSL
+              timeToFirstByte: 200,
+            },
+          }
+        );
+      });
+
+      it('should provide the correct values with already elapsed', () => {
+        const connection = new TcpConnection(100, Infinity, 0, false);
+        assert.deepEqual(
+          connection.simulateDownloadUntil(7300, {
+            timeAlreadyElapsed: 75,
+            maximumTimeToElapse: 250,
+          }),
+          {
+            bytesDownloaded: 7300,
+            extraBytesDownloaded: 0,
+            congestionWindow: 10,
+            roundTrips: 2,
+            timeElapsed: 125,
+            connectionTiming: {
+              connectionTime: 150,
+              dnsResolutionTime: 0,
+              sslTime: undefined, // non-SSL
+              timeToFirstByte: 200,
+            },
+          }
+        );
+      });
+
+      it('should provide the correct values large payloads', () => {
+        const connection = new TcpConnection(100, 8 * 1000 * 1000);
+        const bytesToDownload = 10 * 1000 * 1000; // 10 mb
+        assert.deepEqual(
+          connection.simulateDownloadUntil(bytesToDownload, {
+            timeAlreadyElapsed: 500,
+            maximumTimeToElapse: 740,
+          }),
+          {
+            bytesDownloaded: 683280, // should be less than 68 * 1460 * 8
+            extraBytesDownloaded: 0,
+            congestionWindow: 68,
+            roundTrips: 8,
+            timeElapsed: 800, // skips the handshake because time already elapsed
+            connectionTiming: {
+              connectionTime: 250,
+              dnsResolutionTime: 0,
+              sslTime: 100,
+              timeToFirstByte: 300,
+            },
+          }
+        );
+      });
+
+      it('should all add up', () => {
+        const connection = new TcpConnection(100, 8 * 1000 * 1000);
+        const bytesToDownload = 10 * 1000 * 1000; // 10 mb
+        const firstStoppingPoint = 5234;
+        const secondStoppingPoint = 315;
+        const thirdStoppingPoint = 10500 - firstStoppingPoint - secondStoppingPoint;
+
+        const firstSegment = connection.simulateDownloadUntil(bytesToDownload, {
+          timeAlreadyElapsed: 0,
+          maximumTimeToElapse: firstStoppingPoint,
+        });
+        const firstOvershoot = firstSegment.timeElapsed - firstStoppingPoint;
+
+        connection.setCongestionWindow(firstSegment.congestionWindow);
+        const secondSegment = connection.simulateDownloadUntil(
+          bytesToDownload - firstSegment.bytesDownloaded,
+          {
+            timeAlreadyElapsed: firstSegment.timeElapsed,
+            maximumTimeToElapse: secondStoppingPoint - firstOvershoot,
+          }
+        );
+        const secondOvershoot = firstOvershoot + secondSegment.timeElapsed - secondStoppingPoint;
+
+        connection.setCongestionWindow(secondSegment.congestionWindow);
+        const thirdSegment = connection.simulateDownloadUntil(
+          bytesToDownload - firstSegment.bytesDownloaded - secondSegment.bytesDownloaded,
+          {timeAlreadyElapsed: firstSegment.timeElapsed + secondSegment.timeElapsed}
+        );
+        const thirdOvershoot = secondOvershoot + thirdSegment.timeElapsed - thirdStoppingPoint;
+
+        assert.equal(thirdOvershoot, 0);
+        assert.equal(
+          firstSegment.bytesDownloaded +
+            secondSegment.bytesDownloaded +
+            thirdSegment.bytesDownloaded,
+          bytesToDownload
+        );
+        assert.equal(
+          firstSegment.timeElapsed + secondSegment.timeElapsed + thirdSegment.timeElapsed,
+          10500
+        );
+      });
+    });
+  });
+});

package/core/lib/lantern/{simulator/tcp-connection.d.ts → simulation/TcpConnection.d.ts}

@@ -1,4 +1,4 @@
-export type ConnectionTiming = import('./simulator-timing-map.js').ConnectionTiming;
+export type ConnectionTiming = import('./SimulationTimingMap.js').ConnectionTiming;
 export type DownloadOptions = {
     dnsResolutionTime?: number | undefined;
     timeAlreadyElapsed?: number | undefined;
@@ -86,4 +86,4 @@ export class TcpConnection {
      */
     simulateDownloadUntil(bytesToDownload: number, options?: DownloadOptions | undefined): DownloadResults;
 }
-//# sourceMappingURL=tcp-connection.d.ts.map
+//# sourceMappingURL=TcpConnection.d.ts.map

package/core/lib/lantern/{simulator/tcp-connection.js → simulation/TcpConnection.js}

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-/** @typedef {import('./simulator-timing-map.js').ConnectionTiming} ConnectionTiming */
+/** @typedef {import('./SimulationTimingMap.js').ConnectionTiming} ConnectionTiming */
 
 const INITIAL_CONGESTION_WINDOW = 10;
 const TCP_SEGMENT_SIZE = 1460;

package/core/lib/lantern/simulation/simulation.d.ts

@@ -0,0 +1,21 @@
+export { ConnectionPool } from "./ConnectionPool.js";
+export { Constants } from "./Constants.js";
+export { DNSCache } from "./DNSCache.js";
+export { NetworkAnalyzer } from "./NetworkAnalyzer.js";
+export { Simulator } from "./Simulator.js";
+export { SimulatorTimingMap } from "./SimulationTimingMap.js";
+export { TcpConnection } from "./TcpConnection.js";
+export type GraphNetworkNode<T = any> = Lantern.Simulation.GraphNetworkNode<T>;
+export type GraphNode<T = any> = Lantern.Simulation.GraphNode<T>;
+export type Result<T = any> = Lantern.Simulation.Result<T>;
+export type GraphCPUNode = Lantern.Simulation.GraphCPUNode;
+export type MetricCoefficients = Lantern.Simulation.MetricCoefficients;
+export type MetricComputationDataInput = Lantern.Simulation.MetricComputationDataInput;
+export type NodeTiming = Lantern.Simulation.NodeTiming;
+export type Options = Lantern.Simulation.Options;
+export type PrecomputedLanternData = Lantern.Simulation.PrecomputedLanternData;
+export type ProcessedNavigation = Lantern.Simulation.ProcessedNavigation;
+export type Settings = Lantern.Simulation.Settings;
+export type URL = Lantern.Simulation.URL;
+import * as Lantern from '../types/lantern.js';
+//# sourceMappingURL=simulation.d.ts.map

package/core/lib/lantern/simulation/simulation.js

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as Lantern from '../types/lantern.js';
+
+export {ConnectionPool} from './ConnectionPool.js';
+export {Constants} from './Constants.js';
+export {DNSCache} from './DNSCache.js';
+export {NetworkAnalyzer} from './NetworkAnalyzer.js';
+export {Simulator} from './Simulator.js';
+export {SimulatorTimingMap} from './SimulationTimingMap.js';
+export {TcpConnection} from './TcpConnection.js';
+
+/** @template [T=any] @typedef {Lantern.Simulation.GraphNetworkNode<T>} GraphNetworkNode */
+/** @template [T=any] @typedef {Lantern.Simulation.GraphNode<T>} GraphNode */
+/** @template [T=any] @typedef {Lantern.Simulation.Result<T>} Result */
+/** @typedef {Lantern.Simulation.GraphCPUNode} GraphCPUNode */
+/** @typedef {Lantern.Simulation.MetricCoefficients} MetricCoefficients */
+/** @typedef {Lantern.Simulation.MetricComputationDataInput} MetricComputationDataInput */
+/** @typedef {Lantern.Simulation.NodeTiming} NodeTiming */
+/** @typedef {Lantern.Simulation.Options} Options */
+/** @typedef {Lantern.Simulation.PrecomputedLanternData} PrecomputedLanternData */
+/** @typedef {Lantern.Simulation.ProcessedNavigation} ProcessedNavigation */
+/** @typedef {Lantern.Simulation.Settings} Settings */
+/** @typedef {Lantern.Simulation.URL} URL */

package/core/lib/lantern/types/lantern.d.ts

@@ -4,7 +4,58 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import * as LH from '../../../../types/lh.js';
+import * as Protocol from '@paulirish/trace_engine/generated/protocol.js';
+
+declare module Util {
+    /** An object with the keys in the union K mapped to themselves as values. */
+    type SelfMap<K extends string> = {
+        [P in K]: P;
+    };
+}
+
+type TraceEvent = {
+    name: string;
+    cat: string;
+    args: {
+        name?: string;
+        fileName?: string;
+        snapshot?: string;
+        sync_id?: string;
+        beginData?: {
+            frame?: string;
+            startLine?: number;
+            url?: string;
+        };
+        data?: {
+            frame?: string;
+            readyState?: number;
+            stackTrace?: {
+                url: string
+            }[];
+            url?: string;
+        };
+    };
+    pid: number;
+    tid: number;
+    /** Timestamp of the event in microseconds. */
+    ts: number;
+    dur: number;
+}
+type Trace = {traceEvents: TraceEvent[]};
+type ResourcePriority = ('VeryLow' | 'Low' | 'Medium' | 'High' | 'VeryHigh');
+type ResourceType = ('Document' | 'Stylesheet' | 'Image' | 'Media' | 'Font' | 'Script' | 'TextTrack' | 'XHR' | 'Fetch' | 'Prefetch' | 'EventSource' | 'WebSocket' | 'Manifest' | 'SignedExchange' | 'Ping' | 'CSPViolationReport' | 'Preflight' | 'Other');
+type InitiatorType = ('parser' | 'script' | 'preload' | 'SignedExchange' | 'preflight' | 'other');
+type ResourceTiming = Protocol.Network.ResourceTiming;
+type CallStack = {
+    callFrames: Array<{
+        scriptId: string;
+        url: string;
+        lineNumber: number;
+        columnNumber: number;
+        functionName: string;
+    }>;
+    parent?: CallStack;
+}
 
 type ParsedURL = {
     /**
@@ -38,15 +89,16 @@ type LightriderStatistics = {
 
 export class NetworkRequest<T = any> {
     /**
-     * The canonical network record.
-     * Users of Lantern must create NetworkRequests matching this interface,
-     * but can store the source-of-truth for their network model in this `record`
-     * property. This is then accessible as a read-only property on NetworkNode.
+     * Implementation-specifc canoncial data structure that this Lantern NetworkRequest
+     * was derived from.
+     * Users of Lantern create a NetworkRequest matching this interface,
+     * but can store the source-of-truth for their network model in this property.
+     * This is then accessible as a read-only property on NetworkNode.
      */
-    record?: T;
+    rawRequest?: T;
 
     requestId: string;
-    connectionId: string;
+    connectionId: number;
     connectionReused: boolean;
     url: string;
     protocol: string;
@@ -59,7 +111,11 @@ export class NetworkRequest<T = any> {
      * HTTP cache or going to the network for DNS/connection setup, in milliseconds.
      */
     networkRequestTime: number;
-    /** When the last byte of the response headers is received, in milliseconds. */
+    /**
+     * When the last byte of the response headers is received, in milliseconds.
+     * Equal to networkRequestTime if no data is recieved over the
+     * network (ex: cached requests or data urls).
+     */
     responseHeadersEndTime: number;
     /** When the last byte of the response body is received, in milliseconds. */
     networkEndTime: number;
@@ -67,33 +123,57 @@ export class NetworkRequest<T = any> {
     resourceSize: number;
     fromDiskCache: boolean;
     fromMemoryCache: boolean;
+    isLinkPreload: boolean;
     finished: boolean;
+    failed: boolean;
     statusCode: number;
+    /** The network request that redirected to this one */
+    redirectSource: NetworkRequest<T> | undefined;
     /** The network request that this one redirected to */
     redirectDestination: NetworkRequest<T> | undefined;
-    failed: boolean;
-    initiator: LH.Crdp.Network.Initiator;
+    // TODO: can't use Protocol.Network.Initiator because of type mismatch in Lighthouse initiator.
+    initiator: {
+        type: InitiatorType;
+        url?: string;
+        stack?: CallStack;
+    };
     initiatorRequest: NetworkRequest<T> | undefined;
     /** The chain of network requests that redirected to this one */
     redirects: NetworkRequest[] | undefined;
-    timing: LH.Crdp.Network.ResourceTiming | undefined;
+    timing: Protocol.Network.ResourceTiming | undefined;
     /**
      * Optional value for how long the server took to respond to this request.
      * When not provided, the server response time is derived from the timing object.
      */
-    serverResponseTime: number | undefined;
-    resourceType: LH.Crdp.Network.ResourceType | undefined;
+    serverResponseTime?: number;
+    resourceType: ResourceType | undefined;
     mimeType: string;
-    priority: LH.Crdp.Network.ResourcePriority;
+    priority: ResourcePriority;
     frameId: string | undefined;
-    sessionTargetType: LH.Protocol.TargetType | undefined;
+    fromWorker: boolean;
+}
+
+interface MetricResult<T = any> {
+    timing: number;
+    timestamp?: never;
+    optimisticEstimate: Simulation.Result<T>;
+    pessimisticEstimate: Simulation.Result<T>;
+    optimisticGraph: Simulation.GraphNode<T>;
+    pessimisticGraph: Simulation.GraphNode<T>;
 }
 
 export namespace Simulation {
-    type GraphNode<T> = import('../base-node.js').Node<T>;
-    type GraphNetworkNode<T> = import('../network-node.js').NetworkNode<T>;
-    type GraphCPUNode = import('../cpu-node.js').CPUNode;
-    type Simulator<T> = import('../simulator/simulator.js').Simulator<T>;
+    type URL = {
+        /** URL of the initially requested URL */
+        requestedUrl?: string;
+        /** URL of the last document request */
+        mainDocumentUrl?: string;
+    };
+
+    type GraphNode<T> = import('../BaseNode.js').Node<T>;
+    type GraphNetworkNode<T> = import('../NetworkNode.js').NetworkNode<T>;
+    type GraphCPUNode = import('../CpuNode.js').CPUNode;
+    type Simulator<T> = import('../simulation/Simulator.js').Simulator<T>;
 
     interface MetricCoefficients {
         intercept: number;
@@ -101,6 +181,44 @@ export namespace Simulation {
         pessimistic: number;
     }
 
+    /** Simulation settings that control the amount of network & cpu throttling in the run. */
+    interface ThrottlingSettings {
+        /** The round trip time in milliseconds. */
+        rttMs?: number;
+        /** The network throughput in kilobits per second. */
+        throughputKbps?: number;
+        // devtools settings
+        /** The network request latency in milliseconds. */
+        requestLatencyMs?: number;
+        /** The network download throughput in kilobits per second. */
+        downloadThroughputKbps?: number;
+        /** The network upload throughput in kilobits per second. */
+        uploadThroughputKbps?: number;
+        // used by both
+        /** The amount of slowdown applied to the cpu (1/<cpuSlowdownMultiplier>). */
+        cpuSlowdownMultiplier?: number
+    }
+
+    interface PrecomputedLanternData {
+        additionalRttByOrigin: {[origin: string]: number};
+        serverResponseTimeByOrigin: {[origin: string]: number};
+    }
+
+    interface Settings {
+        networkAnalysis: {
+            rtt: number;
+            additionalRttByOrigin: Map<string, number>;
+            serverResponseTimeByOrigin: Map<string, number>;
+            throughput: number;
+        };
+        /** The method used to throttle the network. */
+        throttlingMethod: 'devtools'|'simulate'|'provided';
+        /** The throttling config settings. */
+        throttling: Required<ThrottlingSettings>;
+        /** Precomputed lantern estimates to use instead of observed analysis. */
+        precomputedLanternData?: PrecomputedLanternData | null;
+    }
+
     interface Options {
         rtt?: number;
         throughput?: number;
@@ -123,9 +241,16 @@ export namespace Simulation {
         nodeTimings: Map<GraphNode<T>, NodeTiming>;
     }
 
+    interface ProcessedNavigation {
+        timestamps: {
+            firstContentfulPaint: number;
+            largestContentfulPaint?: number;
+        };
+    }
+
     interface MetricComputationDataInput {
         simulator: Simulator<any>;
         graph: GraphNode<any>;
-        processedNavigation: LH.Artifacts.ProcessedNavigation;
+        processedNavigation: ProcessedNavigation;
     }
 }