lighthouse 10.2.0 → 10.3.0-dev.20230613

package/core/lib/lh-error.d.ts

@@ -8,20 +8,24 @@ export type LighthouseErrorDefinition = {
     lhrRuntimeError?: boolean | undefined;
 };
 export type SerializedLighthouseError = {
-    [p: string]: string | undefined;
     sentinel: '__LighthouseErrorSentinel';
     code: string;
     stack?: string | undefined;
+    cause?: unknown;
+    properties?: {
+        [p: string]: string | undefined;
+    } | undefined;
 };
 export type SerializedBaseError = {
     sentinel: '__ErrorSentinel';
     message: string;
     code?: string;
     stack?: string;
+    cause?: unknown;
 };
 /**
- * @typedef {{sentinel: '__LighthouseErrorSentinel', code: string, stack?: string, [p: string]: string|undefined}} SerializedLighthouseError
- * @typedef {{sentinel: '__ErrorSentinel', message: string, code?: string, stack?: string}} SerializedBaseError
+ * @typedef {{sentinel: '__LighthouseErrorSentinel', code: string, stack?: string, cause?: unknown, properties?: {[p: string]: string|undefined}}} SerializedLighthouseError
+ * @typedef {{sentinel: '__ErrorSentinel', message: string, code?: string, stack?: string, cause?: unknown}} SerializedBaseError
  */
 export class LighthouseError extends Error {
     /**
@@ -55,8 +59,9 @@ export class LighthouseError extends Error {
     /**
      * @param {LighthouseErrorDefinition} errorDefinition
      * @param {Record<string, string|undefined>=} properties
+     * @param {ErrorOptions=} options
      */
-    constructor(errorDefinition: LighthouseErrorDefinition, properties?: Record<string, string | undefined> | undefined);
+    constructor(errorDefinition: LighthouseErrorDefinition, properties?: Record<string, string | undefined> | undefined, options?: ErrorOptions | undefined);
     code: string;
     friendlyMessage: import("../index.js").IcuMessage;
     lhrRuntimeError: boolean;

package/core/lib/lh-error.js

@@ -107,17 +107,18 @@ const str_ = i18n.createIcuMessageFn(import.meta.url, UIStrings);
 const LHERROR_SENTINEL = '__LighthouseErrorSentinel';
 const ERROR_SENTINEL = '__ErrorSentinel';
 /**
- * @typedef {{sentinel: '__LighthouseErrorSentinel', code: string, stack?: string, [p: string]: string|undefined}} SerializedLighthouseError
- * @typedef {{sentinel: '__ErrorSentinel', message: string, code?: string, stack?: string}} SerializedBaseError
+ * @typedef {{sentinel: '__LighthouseErrorSentinel', code: string, stack?: string, cause?: unknown, properties?: {[p: string]: string|undefined}}} SerializedLighthouseError
+ * @typedef {{sentinel: '__ErrorSentinel', message: string, code?: string, stack?: string, cause?: unknown}} SerializedBaseError
  */
 
 class LighthouseError extends Error {
   /**
    * @param {LighthouseErrorDefinition} errorDefinition
    * @param {Record<string, string|undefined>=} properties
+   * @param {ErrorOptions=} options
    */
-  constructor(errorDefinition, properties) {
-    super(errorDefinition.code);
+  constructor(errorDefinition, properties, options) {
+    super(errorDefinition.code, options);
     this.name = 'LighthouseError';
     this.code = errorDefinition.code;
     // Add additional properties to be ICU replacements in the error string.
@@ -163,19 +164,20 @@ class LighthouseError extends Error {
     if (err instanceof LighthouseError) {
       // Remove class props so that remaining values were what was passed in as `properties`.
       // eslint-disable-next-line no-unused-vars
-      const {name, code, message, friendlyMessage, lhrRuntimeError, stack, ...properties} = err;
+      const {name, code, message, friendlyMessage, lhrRuntimeError, stack, cause, ...properties} = err;
 
       return {
         sentinel: LHERROR_SENTINEL,
         code,
         stack,
-        ...properties,
+        cause,
+        properties: /** @type {{ [p: string]: string | undefined }} */ (properties),
       };
     }
 
     // Unexpected errors won't be LighthouseErrors, but we want them serialized as well.
     if (err instanceof Error) {
-      const {message, stack} = err;
+      const {message, stack, cause} = err;
       // @ts-expect-error - code can be helpful for e.g. node errors, so preserve it if it's present.
       const code = err.code;
       return {
@@ -183,6 +185,7 @@ class LighthouseError extends Error {
         message,
         code,
         stack,
+        cause,
       };
     }
 
@@ -203,17 +206,18 @@ class LighthouseError extends Error {
       if (possibleError.sentinel === LHERROR_SENTINEL) {
         // Include sentinel in destructuring so it doesn't end up in `properties`.
         // eslint-disable-next-line no-unused-vars
-        const {sentinel, code, stack, ...properties} = /** @type {SerializedLighthouseError} */ (possibleError);
+        const {code, stack, cause, properties} = /** @type {SerializedLighthouseError} */ (possibleError);
         const errorDefinition = LighthouseError.errors[/** @type {keyof typeof ERRORS} */ (code)];
-        const lhError = new LighthouseError(errorDefinition, properties);
+        const lhError = new LighthouseError(errorDefinition, properties, {cause});
         lhError.stack = stack;
 
         return lhError;
       }
 
       if (possibleError.sentinel === ERROR_SENTINEL) {
-        const {message, code, stack} = /** @type {SerializedBaseError} */ (possibleError);
-        const error = new Error(message);
+        const {message, code, stack, cause} = /** @type {SerializedBaseError} */ (possibleError);
+        const opts = cause ? {cause} : undefined;
+        const error = new Error(message, opts);
         Object.assign(error, {code, stack});
         return error;
       }

package/core/lib/network-request.d.ts

@@ -13,22 +13,22 @@ export type ParsedURL = {
     host: string;
     securityOrigin: string;
 };
-/**
- * The difference in networkEndTime between the observed Lighthouse networkEndTime and Lightrider's derived networkEndTime.
- */
 export type LightriderStatistics = {
     /**
-     * The time spent making a TCP connection (connect + SSL).
+     * The difference in networkEndTime between the observed Lighthouse networkEndTime and Lightrider's derived networkEndTime.
      */
     endTimeDeltaMs: number;
     /**
-     * The time spent requesting a resource from a remote server, we use this to approx RTT.
+     * The time spent making a TCP connection (connect + SSL). Note: this is poorly named.
      */
     TCPMs: number;
     /**
-     * The time spent transferring a resource from a remote server.
+     * The time spent requesting a resource from a remote server, we use this to approx RTT. Note: this is poorly names, it really should be "server response time".
      */
     requestMs: number;
+    /**
+     * Time to receive the entire response payload starting the clock on receiving the first fragment (first non-header byte).
+     */
     responseMs: number;
 };
 export class NetworkRequest {
@@ -219,6 +219,13 @@ export class NetworkRequest {
      * LR loses protocol information.
      */
     _updateProtocolForLightrider(): void;
+    /**
+     * TODO(compat): remove M116.
+     * `timing.receiveHeadersStart` was added recently, and will be in M116. Until then,
+     * set it to receiveHeadersEnd, which is close enough, to allow consumers of NetworkRequest
+     * to use the new field without accounting for this backcompat.
+     */
+    _backfillReceiveHeaderStartTiming(): void;
     /**
      * LR gets additional, accurate timing information from its underlying fetch infrastructure.  This
      * is passed in via X-Headers similar to 'X-TotalFetchedSize'.

package/core/lib/network-request.js

@@ -57,7 +57,7 @@ import UrlUtils from './url-utils.js';
 
 // Lightrider X-Header names for timing information.
 // See: _updateTransferSizeForLightrider and _updateTimingsForLightrider.
-const HEADER_TCP = 'X-TCPMs';
+const HEADER_TCP = 'X-TCPMs'; // Note: this should have been called something like ConnectMs, as it includes SSL.
 const HEADER_SSL = 'X-SSLMs';
 const HEADER_REQ = 'X-RequestMs';
 const HEADER_RES = 'X-ResponseMs';
@@ -80,14 +80,10 @@ const HEADER_PROTOCOL_IS_H2 = 'X-ProtocolIsH2';
 
 /**
  * @typedef LightriderStatistics
- * The difference in networkEndTime between the observed Lighthouse networkEndTime and Lightrider's derived networkEndTime.
- * @property {number} endTimeDeltaMs
- * The time spent making a TCP connection (connect + SSL).
- * @property {number} TCPMs
- * The time spent requesting a resource from a remote server, we use this to approx RTT.
- * @property {number} requestMs
- * The time spent transferring a resource from a remote server.
- * @property {number} responseMs
+ * @property {number} endTimeDeltaMs The difference in networkEndTime between the observed Lighthouse networkEndTime and Lightrider's derived networkEndTime.
+ * @property {number} TCPMs The time spent making a TCP connection (connect + SSL). Note: this is poorly named.
+ * @property {number} requestMs The time spent requesting a resource from a remote server, we use this to approx RTT. Note: this is poorly names, it really should be "server response time".
+ * @property {number} responseMs Time to receive the entire response payload starting the clock on receiving the first fragment (first non-header byte).
  */
 
 /** @type {LH.Util.SelfMap<LH.Crdp.Network.ResourceType>} */
@@ -274,6 +270,7 @@ class NetworkRequest {
     }
 
     this._updateResponseHeadersEndTimeIfNecessary();
+    this._backfillReceiveHeaderStartTiming();
     this._updateTransferSizeForLightrider();
     this._updateTimingsForLightrider();
   }
@@ -293,6 +290,7 @@ class NetworkRequest {
     this.localizedFailDescription = data.errorText;
 
     this._updateResponseHeadersEndTimeIfNecessary();
+    this._backfillReceiveHeaderStartTiming();
     this._updateTransferSizeForLightrider();
     this._updateTimingsForLightrider();
   }
@@ -315,6 +313,7 @@ class NetworkRequest {
     this.networkEndTime = data.timestamp * 1000;
 
     this._updateResponseHeadersEndTimeIfNecessary();
+    this._backfillReceiveHeaderStartTiming();
   }
 
   /**
@@ -341,6 +340,7 @@ class NetworkRequest {
 
     if (response.protocol) this.protocol = response.protocol;
 
+    // This is updated in _recomputeTimesWithResourceTiming, if timings are present.
     this.responseHeadersEndTime = timestamp * 1000;
 
     this.transferSize = response.encodedDataLength;
@@ -372,16 +372,27 @@ class NetworkRequest {
     // Don't recompute times if the data is invalid. RequestTime should always be a thread timestamp.
     // If we don't have receiveHeadersEnd, we really don't have more accurate data.
     if (timing.requestTime === 0 || timing.receiveHeadersEnd === -1) return;
+
     // Take networkRequestTime and responseHeadersEndTime from timing data for better accuracy.
+    // Before this, networkRequestTime and responseHeadersEndTime were set to bogus values based on
+    // CDP event timestamps, though they should be somewhat close to the network timings.
+    // Note: requests served from cache never run this function, so they use the "bogus" values.
+
     // Timing's requestTime is a baseline in seconds, rest of the numbers there are ticks in millis.
+    // See https://raw.githubusercontent.com/GoogleChrome/lighthouse/main/docs/Network-Timings.svg
     this.networkRequestTime = timing.requestTime * 1000;
     const headersReceivedTime = this.networkRequestTime + timing.receiveHeadersEnd;
-    if (!this.responseHeadersEndTime || this.responseHeadersEndTime < 0) {
-      this.responseHeadersEndTime = headersReceivedTime;
-    }
-
-    this.responseHeadersEndTime = Math.min(this.responseHeadersEndTime, headersReceivedTime);
+    // This was set in `_onResponse` as that event's timestamp.
+    const responseTimestamp = this.responseHeadersEndTime;
+
+    // Update this.responseHeadersEndTime. All timing values from the netstack (timing) are well-ordered, and
+    // so are the timestamps from CDP (which this.responseHeadersEndTime belongs to). It shouldn't be possible
+    // that this timing from the netstack is greater than the onResponse timestamp, but just to ensure proper order
+    // is maintained we bound the new timing by the network request time and the response timestamp.
+    this.responseHeadersEndTime = headersReceivedTime;
+    this.responseHeadersEndTime = Math.min(this.responseHeadersEndTime, responseTimestamp);
     this.responseHeadersEndTime = Math.max(this.responseHeadersEndTime, this.networkRequestTime);
+
     // We're only at responseReceived (_onResponse) at this point.
     // This networkEndTime may be redefined again after onLoading is done.
     this.networkEndTime = Math.max(this.networkEndTime, this.responseHeadersEndTime);
@@ -437,6 +448,19 @@ class NetworkRequest {
     }
   }
 
+  /**
+   * TODO(compat): remove M116.
+   * `timing.receiveHeadersStart` was added recently, and will be in M116. Until then,
+   * set it to receiveHeadersEnd, which is close enough, to allow consumers of NetworkRequest
+   * to use the new field without accounting for this backcompat.
+   */
+  _backfillReceiveHeaderStartTiming() {
+    // Do nothing if a value is already present!
+    if (!this.timing || this.timing.receiveHeadersStart !== undefined) return;
+
+    this.timing.receiveHeadersStart = this.timing.receiveHeadersEnd;
+  }
+
   /**
    * LR gets additional, accurate timing information from its underlying fetch infrastructure.  This
    * is passed in via X-Headers similar to 'X-TotalFetchedSize'.
@@ -473,6 +497,7 @@ class NetworkRequest {
 
     // Make sure all times are initialized and are non-negative.
     const TCPMs = TCPMsHeader ? Math.max(0, parseInt(TCPMsHeader.value)) : 0;
+    // This is missing for h2 requests, but present for h1. See b/283843975
     const SSLMs = SSLMsHeader ? Math.max(0, parseInt(SSLMsHeader.value)) : 0;
     const requestMs = requestMsHeader ? Math.max(0, parseInt(requestMsHeader.value)) : 0;
     const responseMs = responseMsHeader ? Math.max(0, parseInt(responseMsHeader.value)) : 0;

package/core/lib/tracehouse/trace-processor.js

@@ -705,7 +705,7 @@ class TraceProcessor {
         return Boolean(
           evt.name === 'FrameCommittedInBrowser' &&
           evt.args.data?.frame &&
-          evt.args.data.url
+          evt.args.data.url !== undefined
         );
       }).forEach(evt => {
         framesById.set(evt.args.data.frame, {

package/core/lib/url-utils.js

@@ -87,6 +87,10 @@ class UrlUtils {
   static getOrigin(url) {
     try {
       const urlInfo = new URL(url);
+      if (urlInfo.protocol === 'chrome-extension:') {
+        // Chrome extensions return string "null" as origin, so we reconstruct the extension origin.
+        return Util.getChromeExtensionOrigin(url);
+      }
       // check for both host and origin since some URLs schemes like data and file set origin to the
       // string "null" instead of the object
       return (urlInfo.host && urlInfo.origin) || null;

package/core/runner.js

@@ -429,7 +429,7 @@ class Runner {
 
           // Create a friendlier display error and mark it as expected to avoid duplicates in Sentry
           const error = new LighthouseError(LighthouseError.errors.ERRORED_REQUIRED_ARTIFACT,
-              {artifactName, errorMessage: artifactError.message});
+              {artifactName, errorMessage: artifactError.message}, {cause: artifactError});
           // @ts-expect-error Non-standard property added to Error
           error.expected = true;
           throw error;
@@ -468,7 +468,9 @@ class Runner {
       Sentry.captureException(err, {tags: {audit: audit.meta.id}, level: 'error'});
       // Errors become error audit result.
       const errorMessage = err.friendlyMessage ? err.friendlyMessage : err.message;
-      auditResult = Audit.generateErrorAuditResult(audit, errorMessage);
+      // Prefer the stack trace closest to the error.
+      const stack = err.cause?.stack ?? err.stack;
+      auditResult = Audit.generateErrorAuditResult(audit, errorMessage, stack);
     }
 
     log.timeEnd(status);