lighthouse 12.0.0-dev.20240610 → 12.0.0-dev.20240612

package/core/lib/lantern/{simulator/connection-pool.d.ts → simulation/ConnectionPool.d.ts}

@@ -4,7 +4,7 @@ export class ConnectionPool {
      * @param {Required<Lantern.Simulation.Options>} options
      */
     constructor(records: Lantern.NetworkRequest[], options: Required<Lantern.Simulation.Options>);
-    _options: Required<Lantern.Simulation.Options>;
+    _options: Required<import("../types/lantern.js").Simulation.Options>;
     _records: Lantern.NetworkRequest<any>[];
     /** @type {Map<string, TcpConnection[]>} */
     _connectionsByOrigin: Map<string, TcpConnection[]>;
@@ -20,7 +20,7 @@ export class ConnectionPool {
     /**
      * @param {Array<TcpConnection>} connections
      */
-    _findAvailableConnectionWithLargestCongestionWindow(connections: Array<TcpConnection>): TcpConnection | null;
+    _findAvailableConnectionWithLargestCongestionWindow(connections: Array<TcpConnection>): Lantern.Simulation.TcpConnection | null;
     /**
      * This method finds an available connection to the origin specified by the network request or null
      * if no connection was available. If returned, connection will not be available for other network
@@ -43,6 +43,6 @@ export class ConnectionPool {
      */
     release(request: Lantern.NetworkRequest): void;
 }
-import * as Lantern from '../types/lantern.js';
-import { TcpConnection } from './tcp-connection.js';
-//# sourceMappingURL=connection-pool.d.ts.map
+import * as Lantern from '../lantern.js';
+import { TcpConnection } from './TcpConnection.js';
+//# sourceMappingURL=ConnectionPool.d.ts.map

package/core/lib/lantern/{simulator/connection-pool.js → simulation/ConnectionPool.js}

@@ -4,9 +4,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import * as Lantern from '../types/lantern.js';
-import {NetworkAnalyzer} from './network-analyzer.js';
-import {TcpConnection} from './tcp-connection.js';
+import * as Lantern from '../lantern.js';
+import {NetworkAnalyzer} from './NetworkAnalyzer.js';
+import {TcpConnection} from './TcpConnection.js';
 
 const DEFAULT_SERVER_RESPONSE_TIME = 30;
 const TLS_SCHEMES = ['https', 'wss'];

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

@@ -0,0 +1,195 @@
+/**
+ * @license
+ * Copyright 2018 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import assert from 'assert/strict';
+import {URL} from 'url';
+
+import * as Lantern from '../lantern.js';
+
+const {ConnectionPool} = Lantern.Simulation;
+
+describe('ConnectionPool', () => {
+  const rtt = 100;
+  const throughput = 10000 * 1024;
+  let requestId;
+
+  function request(data = {}) {
+    const url = data.url || 'http://example.com';
+    const origin = new URL(url).origin;
+    const scheme = url.split(':')[0];
+
+    return Object.assign({
+      requestId: requestId++,
+      url,
+      protocol: 'http/1.1',
+      parsedURL: {scheme, securityOrigin: origin},
+    }, data);
+  }
+
+  function simulationOptions(options) {
+    return Object.assign(
+      {
+        rtt: 150,
+        throughput: 1024,
+        additionalRttByOrigin: new Map(),
+        serverResponseTimeByOrigin: new Map(),
+      },
+      options
+    );
+  }
+
+  beforeEach(() => {
+    requestId = 1;
+  });
+
+  describe('#constructor', () => {
+    it('should create the pool', () => {
+      const pool = new ConnectionPool([request()], simulationOptions({rtt, throughput}));
+      // Make sure 6 connections are created for each origin
+      assert.equal(pool._connectionsByOrigin.get('http://example.com').length, 6);
+      // Make sure it populates connectionWasReused
+      assert.equal(pool._connectionReusedByRequestId.get(1), false);
+
+      const connection = pool._connectionsByOrigin.get('http://example.com')[0];
+      assert.equal(connection._rtt, rtt);
+      assert.equal(connection._throughput, throughput);
+      assert.equal(connection._serverLatency, 30); // sets to default value
+    });
+
+    it('should set TLS properly', () => {
+      const recordA = request({url: 'https://example.com'});
+      const pool = new ConnectionPool([recordA], simulationOptions({rtt, throughput}));
+      const connection = pool._connectionsByOrigin.get('https://example.com')[0];
+      assert.ok(connection._ssl, 'should have set connection TLS');
+    });
+
+    it('should set H2 properly', () => {
+      const recordA = request({protocol: 'h2'});
+      const pool = new ConnectionPool([recordA], simulationOptions({rtt, throughput}));
+      const connection = pool._connectionsByOrigin.get('http://example.com')[0];
+      assert.ok(connection.isH2(), 'should have set HTTP/2');
+      assert.equal(pool._connectionsByOrigin.get('http://example.com').length, 1);
+    });
+
+    it('should set origin-specific RTT properly', () => {
+      const additionalRttByOrigin = new Map([['http://example.com', 63]]);
+      const pool = new ConnectionPool([request()],
+          simulationOptions({rtt, throughput, additionalRttByOrigin}));
+      const connection = pool._connectionsByOrigin.get('http://example.com')[0];
+      assert.ok(connection._rtt, rtt + 63);
+    });
+
+    it('should set origin-specific server latency properly', () => {
+      const serverResponseTimeByOrigin = new Map([['http://example.com', 63]]);
+      const pool = new ConnectionPool([request()],
+          simulationOptions({rtt, throughput, serverResponseTimeByOrigin}));
+      const connection = pool._connectionsByOrigin.get('http://example.com')[0];
+      assert.ok(connection._serverLatency, 63);
+    });
+  });
+
+  describe('.acquire', () => {
+    it('should remember the connection associated with each request', () => {
+      const requestA = request();
+      const requestB = request();
+      const pool = new ConnectionPool([requestA, requestB], simulationOptions({rtt, throughput}));
+
+      const connectionForA = pool.acquire(requestA);
+      const connectionForB = pool.acquire(requestB);
+      for (let i = 0; i < 10; i++) {
+        assert.equal(pool.acquireActiveConnectionFromRequest(requestA), connectionForA);
+        assert.equal(pool.acquireActiveConnectionFromRequest(requestB), connectionForB);
+      }
+
+      assert.deepStrictEqual(pool.connectionsInUse(), [connectionForA, connectionForB]);
+    });
+
+    it('should allocate at least 6 connections', () => {
+      const pool = new ConnectionPool([request()], simulationOptions({rtt, throughput}));
+      for (let i = 0; i < 6; i++) {
+        assert.ok(pool.acquire(request()), `did not find connection for ${i}th request`);
+      }
+    });
+
+    it('should allocate all connections', () => {
+      const records = new Array(7).fill(undefined, 0, 7).map(() => request());
+      const pool = new ConnectionPool(records, simulationOptions({rtt, throughput}));
+      const connections = records.map(request => pool.acquire(request));
+      assert.ok(connections[0], 'did not find connection for 1st request');
+      assert.ok(connections[5], 'did not find connection for 6th request');
+      assert.ok(connections[6], 'did not find connection for 7th request');
+    });
+
+    it('should be oblivious to connection reuse', () => {
+      const coldRecord = request();
+      const warmRecord = request();
+      const pool = new ConnectionPool([coldRecord, warmRecord],
+          simulationOptions({rtt, throughput}));
+      pool._connectionReusedByRequestId.set(warmRecord.requestId, true);
+
+      assert.ok(pool.acquire(coldRecord), 'should have acquired connection');
+      assert.ok(pool.acquire(warmRecord), 'should have acquired connection');
+      pool.release(coldRecord);
+
+      for (const connection of pool._connectionsByOrigin.get('http://example.com')) {
+        connection.setWarmed(true);
+      }
+
+      assert.ok(pool.acquire(coldRecord), 'should have acquired connection');
+      assert.ok(pool.acquireActiveConnectionFromRequest(warmRecord),
+        'should have acquired connection');
+    });
+
+    it('should acquire in order of warmness', () => {
+      const recordA = request();
+      const recordB = request();
+      const recordC = request();
+      const pool = new ConnectionPool([recordA, recordB, recordC],
+          simulationOptions({rtt, throughput}));
+      pool._connectionReusedByRequestId.set(recordA.requestId, true);
+      pool._connectionReusedByRequestId.set(recordB.requestId, true);
+      pool._connectionReusedByRequestId.set(recordC.requestId, true);
+
+      const [connectionWarm, connectionWarmer, connectionWarmest] =
+        pool._connectionsByOrigin.get('http://example.com');
+      connectionWarm.setWarmed(true);
+      connectionWarm.setCongestionWindow(10);
+      connectionWarmer.setWarmed(true);
+      connectionWarmer.setCongestionWindow(100);
+      connectionWarmest.setWarmed(true);
+      connectionWarmest.setCongestionWindow(1000);
+
+      assert.equal(pool.acquire(recordA), connectionWarmest);
+      assert.equal(pool.acquire(recordB), connectionWarmer);
+      assert.equal(pool.acquire(recordC), connectionWarm);
+    });
+  });
+
+  describe('.release', () => {
+    it('noop for request without connection', () => {
+      const requestA = request();
+      const pool = new ConnectionPool([requestA], simulationOptions({rtt, throughput}));
+      assert.equal(pool.release(requestA), undefined);
+    });
+
+    it('frees the connection for reissue', () => {
+      const requests = new Array(6).fill(undefined, 0, 7).map(() => request());
+      const pool = new ConnectionPool(requests, simulationOptions({rtt, throughput}));
+      requests.push(request());
+
+      requests.forEach(request => pool.acquire(request));
+
+      assert.equal(pool.connectionsInUse().length, 6);
+      assert.ok(!pool.acquire(requests[6]), 'had connection that is in use');
+
+      pool.release(requests[0]);
+      assert.equal(pool.connectionsInUse().length, 5);
+
+      assert.ok(pool.acquire(requests[6]), 'could not reissue released connection');
+      assert.ok(!pool.acquire(requests[0]), 'had connection that is in use');
+    });
+  });
+});

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

@@ -0,0 +1,52 @@
+export namespace Constants {
+    export { throttling };
+}
+declare namespace throttling {
+    export { DEVTOOLS_RTT_ADJUSTMENT_FACTOR };
+    export { DEVTOOLS_THROUGHPUT_ADJUSTMENT_FACTOR };
+    export namespace mobileSlow4G {
+        const rttMs: number;
+        const throughputKbps: number;
+        const requestLatencyMs: number;
+        const downloadThroughputKbps: number;
+        const uploadThroughputKbps: number;
+        const cpuSlowdownMultiplier: number;
+    }
+    export namespace mobileRegular3G {
+        const rttMs_1: number;
+        export { rttMs_1 as rttMs };
+        const throughputKbps_1: number;
+        export { throughputKbps_1 as throughputKbps };
+        const requestLatencyMs_1: number;
+        export { requestLatencyMs_1 as requestLatencyMs };
+        const downloadThroughputKbps_1: number;
+        export { downloadThroughputKbps_1 as downloadThroughputKbps };
+        const uploadThroughputKbps_1: number;
+        export { uploadThroughputKbps_1 as uploadThroughputKbps };
+        const cpuSlowdownMultiplier_1: number;
+        export { cpuSlowdownMultiplier_1 as cpuSlowdownMultiplier };
+    }
+    export namespace desktopDense4G {
+        const rttMs_2: number;
+        export { rttMs_2 as rttMs };
+        const throughputKbps_2: number;
+        export { throughputKbps_2 as throughputKbps };
+        const cpuSlowdownMultiplier_2: number;
+        export { cpuSlowdownMultiplier_2 as cpuSlowdownMultiplier };
+        const requestLatencyMs_2: number;
+        export { requestLatencyMs_2 as requestLatencyMs };
+        const downloadThroughputKbps_2: number;
+        export { downloadThroughputKbps_2 as downloadThroughputKbps };
+        const uploadThroughputKbps_2: number;
+        export { uploadThroughputKbps_2 as uploadThroughputKbps };
+    }
+}
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+declare const DEVTOOLS_RTT_ADJUSTMENT_FACTOR: 3.75;
+declare const DEVTOOLS_THROUGHPUT_ADJUSTMENT_FACTOR: 0.9;
+export {};
+//# sourceMappingURL=Constants.d.ts.map

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

@@ -0,0 +1,48 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+const DEVTOOLS_RTT_ADJUSTMENT_FACTOR = 3.75;
+const DEVTOOLS_THROUGHPUT_ADJUSTMENT_FACTOR = 0.9;
+
+const throttling = {
+  DEVTOOLS_RTT_ADJUSTMENT_FACTOR,
+  DEVTOOLS_THROUGHPUT_ADJUSTMENT_FACTOR,
+  // These values align with WebPageTest's definition of "Fast 3G"
+  // But offer similar characteristics to roughly the 75th percentile of 4G connections.
+  mobileSlow4G: {
+    rttMs: 150,
+    throughputKbps: 1.6 * 1024,
+    requestLatencyMs: 150 * DEVTOOLS_RTT_ADJUSTMENT_FACTOR,
+    downloadThroughputKbps: 1.6 * 1024 * DEVTOOLS_THROUGHPUT_ADJUSTMENT_FACTOR,
+    uploadThroughputKbps: 750 * DEVTOOLS_THROUGHPUT_ADJUSTMENT_FACTOR,
+    cpuSlowdownMultiplier: 4,
+  },
+  // These values partially align with WebPageTest's definition of "Regular 3G".
+  // These values are meant to roughly align with Chrome UX report's 3G definition which are based
+  // on HTTP RTT of 300-1400ms and downlink throughput of <700kbps.
+  mobileRegular3G: {
+    rttMs: 300,
+    throughputKbps: 700,
+    requestLatencyMs: 300 * DEVTOOLS_RTT_ADJUSTMENT_FACTOR,
+    downloadThroughputKbps: 700 * DEVTOOLS_THROUGHPUT_ADJUSTMENT_FACTOR,
+    uploadThroughputKbps: 700 * DEVTOOLS_THROUGHPUT_ADJUSTMENT_FACTOR,
+    cpuSlowdownMultiplier: 4,
+  },
+  // Using a "broadband" connection type
+  // Corresponds to "Dense 4G 25th percentile" in https://docs.google.com/document/d/1Ft1Bnq9-t4jK5egLSOc28IL4TvR-Tt0se_1faTA4KTY/edit#heading=h.bb7nfy2x9e5v
+  desktopDense4G: {
+    rttMs: 40,
+    throughputKbps: 10 * 1024,
+    cpuSlowdownMultiplier: 1,
+    requestLatencyMs: 0, // 0 means unset
+    downloadThroughputKbps: 0,
+    uploadThroughputKbps: 0,
+  },
+};
+
+const Constants = {throttling};
+
+export {Constants};

package/core/lib/lantern/{simulator/dns-cache.d.ts → simulation/DNSCache.d.ts}

@@ -36,7 +36,7 @@ export class DNSCache {
 export namespace DNSCache {
     export { DNS_RESOLUTION_RTT_MULTIPLIER as RTT_MULTIPLIER };
 }
-import * as Lantern from '../types/lantern.js';
+import * as Lantern from '../lantern.js';
 declare const DNS_RESOLUTION_RTT_MULTIPLIER: 2;
 export {};
-//# sourceMappingURL=dns-cache.d.ts.map
+//# sourceMappingURL=DNSCache.d.ts.map

package/core/lib/lantern/{simulator/dns-cache.js → simulation/DNSCache.js}

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import * as Lantern from '../types/lantern.js';
+import * as Lantern from '../lantern.js';
 
 // A DNS lookup will usually take ~1-2 roundtrips of connection latency plus the extra DNS routing time.
 // Example: https://www.webpagetest.org/result/180703_3A_e33ec79747c002ed4d7bcbfc81462203/1/details/#waterfall_view_step1

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

@@ -0,0 +1,72 @@
+/**
+ * @license
+ * Copyright 2018 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as Lantern from '../lantern.js';
+
+const {DNSCache} = Lantern.Simulation;
+
+const MULTIPLIER = DNSCache.RTT_MULTIPLIER;
+
+describe('DNSCache', () => {
+  let dns;
+  let request;
+
+  beforeEach(() => {
+    dns = new DNSCache({rtt: 100});
+    request = {parsedURL: {host: 'example.com'}};
+  });
+
+  describe('.getTimeUntilResolution', () => {
+    it('should return the RTT multiplied', () => {
+      const resolutionTime = dns.getTimeUntilResolution(request);
+      expect(resolutionTime).toBe(100 * MULTIPLIER);
+    });
+
+    it('should return time with requestedAt', () => {
+      const resolutionTime = dns.getTimeUntilResolution(request, {requestedAt: 1500});
+      expect(resolutionTime).toBe(100 * MULTIPLIER);
+    });
+
+    it('should not cache by default', () => {
+      dns.getTimeUntilResolution(request, {requestedAt: 0});
+      const resolutionTime = dns.getTimeUntilResolution(request, {requestedAt: 1000});
+      expect(resolutionTime).toBe(100 * MULTIPLIER);
+    });
+
+    it('should cache when told', () => {
+      dns.getTimeUntilResolution(request, {requestedAt: 0, shouldUpdateCache: true});
+      const resolutionTime = dns.getTimeUntilResolution(request, {requestedAt: 1000});
+      expect(resolutionTime).toBe(0);
+    });
+
+    it('should cache by domain', () => {
+      dns.getTimeUntilResolution(request, {requestedAt: 0, shouldUpdateCache: true});
+      const otherRequest = {parsedURL: {host: 'other-example.com'}};
+      const resolutionTime = dns.getTimeUntilResolution(otherRequest, {requestedAt: 1000});
+      expect(resolutionTime).toBe(100 * MULTIPLIER);
+    });
+
+    it('should not update cache with later times', () => {
+      dns.getTimeUntilResolution(request, {requestedAt: 1000, shouldUpdateCache: true});
+      dns.getTimeUntilResolution(request, {requestedAt: 1500, shouldUpdateCache: true});
+      dns.getTimeUntilResolution(request, {requestedAt: 500, shouldUpdateCache: true});
+      dns.getTimeUntilResolution(request, {requestedAt: 5000, shouldUpdateCache: true});
+
+      expect(dns.getTimeUntilResolution(request, {requestedAt: 0})).toBe(100 * MULTIPLIER);
+      expect(dns.getTimeUntilResolution(request, {requestedAt: 550})).toBe(100 * MULTIPLIER - 50);
+      expect(dns.getTimeUntilResolution(request, {requestedAt: 1000})).toBe(0);
+      expect(dns.getTimeUntilResolution(request, {requestedAt: 2000})).toBe(0);
+    });
+  });
+
+  describe('.setResolvedAt', () => {
+    it('should set the DNS resolution time for a request', () => {
+      dns.setResolvedAt(request.parsedURL.host, 123);
+      const resolutionTime = dns.getTimeUntilResolution(request);
+      expect(resolutionTime).toEqual(123);
+    });
+  });
+});

package/core/lib/lantern/{simulator/network-analyzer.d.ts → simulation/NetworkAnalyzer.d.ts}

@@ -46,7 +46,7 @@ export class NetworkAnalyzer {
      * @return {Map<string, Summary>}
      */
     static summarize(values: Map<string, number[]>): Map<string, Summary>;
-    /** @typedef {{request: Lantern.NetworkRequest, timing: LH.Crdp.Network.ResourceTiming, connectionReused?: boolean}} RequestInfo */
+    /** @typedef {{request: Lantern.NetworkRequest, timing: Lantern.ResourceTiming, connectionReused?: boolean}} RequestInfo */
     /**
      * @param {Lantern.NetworkRequest[]} requests
      * @param {(e: RequestInfo) => number | number[] | undefined} iteratee
@@ -54,7 +54,7 @@ export class NetworkAnalyzer {
      */
     static _estimateValueByOrigin(requests: Lantern.NetworkRequest[], iteratee: (e: {
         request: Lantern.NetworkRequest;
-        timing: LH.Crdp.Network.ResourceTiming;
+        timing: Lantern.ResourceTiming;
         connectionReused?: boolean | undefined;
     }) => number | number[] | undefined): Map<string, number[]>;
     /**
@@ -70,7 +70,7 @@ export class NetworkAnalyzer {
      */
     static _estimateRTTViaConnectionTiming(info: {
         request: Lantern.NetworkRequest;
-        timing: LH.Crdp.Network.ResourceTiming;
+        timing: Lantern.ResourceTiming;
         connectionReused?: boolean | undefined;
     }): number[] | number | undefined;
     /**
@@ -83,7 +83,7 @@ export class NetworkAnalyzer {
      */
     static _estimateRTTViaDownloadTiming(info: {
         request: Lantern.NetworkRequest;
-        timing: LH.Crdp.Network.ResourceTiming;
+        timing: Lantern.ResourceTiming;
         connectionReused?: boolean | undefined;
     }): number | undefined;
     /**
@@ -97,7 +97,7 @@ export class NetworkAnalyzer {
      */
     static _estimateRTTViaSendStartTiming(info: {
         request: Lantern.NetworkRequest;
-        timing: LH.Crdp.Network.ResourceTiming;
+        timing: Lantern.ResourceTiming;
         connectionReused?: boolean | undefined;
     }): number | undefined;
     /**
@@ -111,7 +111,7 @@ export class NetworkAnalyzer {
      */
     static _estimateRTTViaHeadersEndTiming(info: {
         request: Lantern.NetworkRequest;
-        timing: LH.Crdp.Network.ResourceTiming;
+        timing: Lantern.ResourceTiming;
         connectionReused?: boolean | undefined;
     }): number | undefined;
     /**
@@ -205,5 +205,5 @@ export class NetworkAnalyzer {
      */
     static resolveRedirects<T_2 extends Lantern.NetworkRequest<any>>(request: T_2): T_2;
 }
-import * as Lantern from '../types/lantern.js';
-//# sourceMappingURL=network-analyzer.d.ts.map
+import * as Lantern from '../lantern.js';
+//# sourceMappingURL=NetworkAnalyzer.d.ts.map

package/core/lib/lantern/{simulator/network-analyzer.js → simulation/NetworkAnalyzer.js}

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import * as Lantern from '../types/lantern.js';
+import * as Lantern from '../lantern.js';
 import UrlUtils from '../../url-utils.js';
 
 const INITIAL_CWD = 14 * 1024;
@@ -15,7 +15,7 @@ const DEFAULT_SERVER_RESPONSE_PERCENTAGE = 0.4;
 /**
  * For certain resource types, server response time takes up a greater percentage of TTFB (dynamic
  * assets like HTML documents, XHR/API calls, etc)
- * @type {Partial<Record<LH.Crdp.Network.ResourceType, number>>}
+ * @type {Partial<Record<Lantern.ResourceType, number>>}
  */
 const SERVER_RESPONSE_PERCENTAGE_OF_TTFB = {
   Document: 0.9,
@@ -88,7 +88,7 @@ class NetworkAnalyzer {
     return summaryByKey;
   }
 
-  /** @typedef {{request: Lantern.NetworkRequest, timing: LH.Crdp.Network.ResourceTiming, connectionReused?: boolean}} RequestInfo */
+  /** @typedef {{request: Lantern.NetworkRequest, timing: Lantern.ResourceTiming, connectionReused?: boolean}} RequestInfo */
 
   /**
    * @param {Lantern.NetworkRequest[]} requests