devtools-tracing 1.0.0

package/lib/front_end/models/trace/handlers/types.ts

@@ -0,0 +1,75 @@
+
+// Copyright 2022 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+import type * as Types from './../types/types.js';
+import type * as ModelHandlers from './ModelHandlers.js';
+
+export type FinalizeOptions = Types.Configuration.ParseOptions&{
+  allTraceEvents: readonly Types.Events.Event[],
+};
+
+export interface Handler {
+  reset(): void;
+  handleEvent(data: object): void;
+  finalize(options?: FinalizeOptions): Promise<void>;
+  data(): unknown;
+  deps?(): HandlerName[];
+  handleUserConfig?(config: Types.Configuration.Configuration): void;
+}
+
+export type HandlerName = keyof typeof ModelHandlers;
+
+/**
+ * This type maps Handler names to the return type of their data
+ * function. So, for example, if we are given an object with a key of 'foo'
+ * and a value which is a TraceHandler containing a data() function that
+ * returns a string, this type will be { foo: string }.
+ *
+ * This allows us to model the behavior of the TraceProcessor in the model,
+ * which takes an object with Handlers as part of its config, and
+ * which ultimately returns an object keyed off the names of the
+ * Handlers, and with values that are derived from each
+ * Handler's data function.
+ *
+ * So, concretely, we provide a Handler for calculating the #time
+ * bounds of a trace called TraceBounds, whose data() function returns a
+ * TraceWindow. The HandlerData, therefore, would determine that the
+ * TraceProcessor would contain a key called 'TraceBounds' whose value is
+ * a TraceWindow.
+ **/
+export type EnabledHandlerDataWithMeta<T extends Record<string, Handler>> = {
+  // We allow the user to configure which handlers are created by passing them
+  // in when constructing a model instance. However, we then ensure that the
+  // Meta handler is added to that, as the Model relies on some of the data
+  // from the Meta handler when creating the file. Therefore, this type
+  // explicitly defines that the Meta data is present, before then extending it
+  // with the index type to represent all the other handlers.
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  Meta: Readonly<ReturnType<typeof ModelHandlers['Meta']['data']>>,
+}&{
+  // For every key in the object, look up the Handler's data function
+  // and use its return type as the value for the object.
+  [K in keyof T]: Readonly<ReturnType<T[K]['data']>>;
+};
+
+export type HandlersWithMeta<T extends Record<string, Handler>> = {
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  Meta: typeof ModelHandlers.Meta,
+}&{
+  [K in keyof T]: T[K];
+};
+
+/**
+ * Represents the final data from all of the handlers. If you instantiate a
+ * TraceProcessor with a subset of handlers, you should instead use
+ * `EnabledHandlerDataWithMeta<>`.
+ **/
+export type HandlerData = Readonly<EnabledHandlerDataWithMeta<typeof ModelHandlers>>;
+
+type DeepWriteable<T> = {
+  -readonly[P in keyof T]: DeepWriteable<T[P]>
+};
+export type HandlerDataMutable = DeepWriteable<HandlerData>;
+
+export type Handlers = typeof ModelHandlers;

package/lib/front_end/models/trace/helpers/Extensions.ts

@@ -0,0 +1,54 @@
+// Copyright 2024 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import * as Platform from '../../../core/platform/platform.js';
+import type * as Types from '../types/types.js';
+
+import {sortTraceEventsInPlace} from './Trace.js';
+import {canBuildTreesFromEvents, type TraceEntryNode, treify} from './TreeHelpers.js';
+
+export function buildTrackDataFromExtensionEntries(
+    extensionEntries: Types.Extensions.SyntheticExtensionTrackEntry[],
+    extensionTrackData: Types.Extensions.ExtensionTrackData[],
+    entryToNode: Map<Types.Events.Event, TraceEntryNode>,
+    ): {
+  extensionTrackData: Types.Extensions.ExtensionTrackData[],
+  entryToNode?: Map<Types.Events.Event, TraceEntryNode>,
+} {
+  const dataByTrack = new Map<string, Types.Extensions.ExtensionTrackData>();
+  for (const entry of extensionEntries) {
+    // Batch data by track group. For each batch, add the data of every
+    // track in the group. In cases where no track group is provided,
+    // we use the standalone track data, but use a fixed prefix in the
+    // batch key to prevent collisions where a track group has the
+    // same name as a standalone track.
+    const key = entry.devtoolsObj.trackGroup || `track-name-${entry.devtoolsObj.track}`;
+    const batchedData = Platform.MapUtilities.getWithDefault(
+        dataByTrack, key, () => ({
+                            name: entry.devtoolsObj.trackGroup || entry.devtoolsObj.track,
+                            isTrackGroup: Boolean(entry.devtoolsObj.trackGroup),
+                            entriesByTrack: {[entry.devtoolsObj.track]: []},
+                          }));
+
+    if (!batchedData.entriesByTrack[entry.devtoolsObj.track]) {
+      batchedData.entriesByTrack[entry.devtoolsObj.track] = [];
+    }
+    const entriesInTrack = batchedData.entriesByTrack[entry.devtoolsObj.track];
+    entriesInTrack.push(entry);
+  }
+  // Calculate self time if possible for track entries, on a track
+  // by track basis.
+  for (const trackData of dataByTrack.values()) {
+    for (const entries of Object.values(trackData.entriesByTrack)) {
+      sortTraceEventsInPlace(entries);
+      if (canBuildTreesFromEvents(entries)) {
+        for (const [entry, node] of treify(entries).entryToNode) {
+          entryToNode.set(entry, node);
+        }
+      }
+    }
+    extensionTrackData.push(trackData);
+  }
+  return {extensionTrackData, entryToNode};
+}

package/lib/front_end/models/trace/helpers/Network.ts

@@ -0,0 +1,129 @@
+// Copyright 2024 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+import * as Protocol from '../../../generated/protocol.js';
+import type {RenderBlocking, SyntheticNetworkRequest} from '../types/TraceEvents.js';
+
+// Important: we purposefully treat `potentially_blocking` as
+// non-render-blocking here because:
+// 1. An async script can run on the main thread at any point, including before
+//    the page is loaded
+// 2. An async script will never block the parsing and rendering process of the
+//    browser.
+// 3. Therefore, from a developer's point of view, there is nothing more they
+//    can do if they've put `async` on, and within the context of Insights, we
+//    shouldn't report an async script as render blocking.
+// In the future we may want to consider suggesting the use of `defer` over
+// `async`, as it doesn't have this concern, but for now we'll allow `async`
+// and not report it as an issue.
+const NON_RENDER_BLOCKING_VALUES = new Set<RenderBlocking>([
+  'non_blocking',
+  'dynamically_injected_non_blocking',
+  'potentially_blocking',
+]);
+
+export function isSyntheticNetworkRequestEventRenderBlocking(event: SyntheticNetworkRequest): boolean {
+  return !NON_RENDER_BLOCKING_VALUES.has(event.args.data.renderBlocking);
+}
+
+const HIGH_NETWORK_PRIORITIES = new Set<Protocol.Network.ResourcePriority>([
+  Protocol.Network.ResourcePriority.VeryHigh,
+  Protocol.Network.ResourcePriority.High,
+  Protocol.Network.ResourcePriority.Medium,
+]);
+
+export function isSyntheticNetworkRequestHighPriority(event: SyntheticNetworkRequest): boolean {
+  return HIGH_NETWORK_PRIORITIES.has(event.args.data.priority);
+}
+
+export interface CacheControl {
+  'max-age'?: number;
+  'no-cache'?: boolean;
+  'no-store'?: boolean;
+  'must-revalidate'?: boolean;
+  // eslint-disable-next-line @stylistic/quote-props
+  'private'?: boolean;
+}
+
+export const CACHEABLE_STATUS_CODES = new Set([200, 203, 206]);
+
+/** @type {Set<LH.Crdp.Network.ResourceType>} */
+export const STATIC_RESOURCE_TYPES = new Set([
+  Protocol.Network.ResourceType.Font,
+  Protocol.Network.ResourceType.Image,
+  Protocol.Network.ResourceType.Media,
+  Protocol.Network.ResourceType.Script,
+  Protocol.Network.ResourceType.Stylesheet,
+]);
+
+export const NON_NETWORK_SCHEMES = [
+  'blob',        // @see https://developer.mozilla.org/en-US/docs/Web/API/URL/createObjectURL
+  'data',        // @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs
+  'intent',      // @see https://developer.chrome.com/docs/multidevice/android/intents/
+  'file',        // @see https://en.wikipedia.org/wiki/File_URI_scheme
+  'filesystem',  // @see https://developer.mozilla.org/en-US/docs/Web/API/FileSystem
+  'chrome-extension',
+];
+
+/**
+ * Parses Cache-Control directives based on https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control
+ * eg. 'no-cache, no-store, max-age=0, no-transform, private' will return
+ * {no-cache: true, no-store: true, max-age: 0, no-transform: true, private: true}
+ */
+export function parseCacheControl(header: string|null): CacheControl|null {
+  if (!header) {
+    return null;
+  }
+
+  const directives = header.split(',').map(directive => directive.trim());
+  const cacheControlOptions: CacheControl = {};
+
+  for (const directive of directives) {
+    const [key, value] = directive.split('=').map(part => part.trim());
+
+    switch (key) {
+      case 'max-age': {
+        const maxAge = parseInt(value, 10);
+        if (!isNaN(maxAge)) {
+          cacheControlOptions['max-age'] = maxAge;
+        }
+        break;
+      }
+      case 'no-cache':
+        cacheControlOptions['no-cache'] = true;
+        break;
+      case 'no-store':
+        cacheControlOptions['no-store'] = true;
+        break;
+      case 'must-revalidate':
+        cacheControlOptions['must-revalidate'] = true;
+        break;
+      case 'private':
+        cacheControlOptions['private'] = true;
+        break;
+      default:
+        // Ignore unknown directives
+        break;
+    }
+  }
+
+  return cacheControlOptions;
+}
+
+const SECURE_LOCALHOST_DOMAINS = ['localhost', '127.0.0.1'];
+
+/**
+ * Is the host localhost-enough to satisfy the "secure context" definition
+ * https://github.com/GoogleChrome/lighthouse/pull/11766#discussion_r582340683
+ */
+export function isSyntheticNetworkRequestLocalhost(event: SyntheticNetworkRequest): boolean {
+  try {
+    const hostname = new URL(event.args.data.url).hostname;
+    // Any hostname terminating in `.localhost` is considered to be local.
+    // https://w3c.github.io/webappsec-secure-contexts/#localhost
+    // This method doesn't consider IPs that resolve to loopback, IPv6 or other loopback edgecases
+    return SECURE_LOCALHOST_DOMAINS.includes(hostname) || hostname.endsWith('.localhost');
+  } catch {
+    return false;
+  }
+}