devtools-tracing 1.1.0 → 1.2.0

package/lib/front_end/models/trace/insights/Cache.ts

@@ -1,269 +0,0 @@
-// Copyright 2025 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 i18n from '../../../core/i18n/i18n.js';
-import * as Protocol from '../../../generated/protocol.js';
-import type * as Handlers from '../handlers/handlers.js';
-import * as Helpers from '../helpers/helpers.js';
-import type * as Types from '../types/types.js';
-
-import {metricSavingsForWastedBytes} from './Common.js';
-import {linearInterpolation} from './Statistics.js';
-import {
-  InsightCategory,
-  InsightKeys,
-  type InsightModel,
-  type InsightSetContext,
-  type PartialInsightModel,
-} from './types.js';
-
-export const UIStrings = {
-  /**
-   * @description Title of an insight that provides information and suggestions of resources that could improve their caching.
-   */
-  title: 'Use efficient cache lifetimes',
-  /**
-   * @description Text to tell the user about how caching can help improve performance.
-   */
-  description:
-      'A long cache lifetime can speed up repeat visits to your page. [Learn more about caching](https://developer.chrome.com/docs/performance/insights/cache).',
-  /**
-   * @description Column for a font loaded by the page to render text.
-   */
-  requestColumn: 'Request',
-  /**
-   * @description Column for a resource cache's Time To Live.
-   */
-  cacheTTL: 'Cache TTL',
-  /**
-   * @description Text describing that there were no requests found that need caching.
-   */
-  noRequestsToCache: 'No requests with inefficient cache policies',
-  /**
-   * @description Table row value representing the remaining items not shown in the table due to size constraints. This row will always represent at least 2 items.
-   * @example {5} PH1
-   */
-  others: '{PH1} others',
-} as const;
-
-const str_ = i18n.i18n.registerUIStrings('models/trace/insights/Cache.ts', UIStrings);
-export const i18nString = i18n.i18n.getLocalizedString.bind(undefined, str_);
-
-export type CacheInsightModel = InsightModel<typeof UIStrings, {
-  requests: Array<{
-    request: Types.Events.SyntheticNetworkRequest,
-    ttl: number,
-    wastedBytes: number,
-  }>,
-}>;
-
-// Threshold for cache hits.
-const IGNORE_THRESHOLD_IN_PERCENT = 0.925;
-
-function finalize(partialModel: PartialInsightModel<CacheInsightModel>): CacheInsightModel {
-  return {
-    insightKey: InsightKeys.CACHE,
-    strings: UIStrings,
-    title: i18nString(UIStrings.title),
-    description: i18nString(UIStrings.description),
-    docs: 'https://developer.chrome.com/docs/performance/insights/cache',
-    category: InsightCategory.ALL,
-    state: partialModel.requests.length > 0 ? 'fail' : 'pass',
-    ...partialModel,
-  };
-}
-
-/**
- * Determines if a request is "cacheable".
- * A request is "cacheable" if it is of the appropriate protocol and resource type
- * (see Helpers.Network.NON_NETWORK_SCHEMES and Helpers.Network.STATIC_RESOURCE_TYPE)
- * and has the appropriate statusCodes.
- */
-export function isCacheable(request: Types.Events.SyntheticNetworkRequest): boolean {
-  // Caching doesn't make sense for requests not loaded over the network.
-  if (Helpers.Network.NON_NETWORK_SCHEMES.includes(request.args.data.protocol)) {
-    return false;
-  }
-  return Boolean(
-      Helpers.Network.CACHEABLE_STATUS_CODES.has(request.args.data.statusCode) &&
-      Helpers.Network.STATIC_RESOURCE_TYPES.has(request.args.data.resourceType || Protocol.Network.ResourceType.Other));
-}
-
-/**
- * Returns max-age if defined, otherwise expires header if defined, and null if not.
- */
-export function computeCacheLifetimeInSeconds(
-    headers: Array<{name: string, value: string}>, cacheControl: Helpers.Network.CacheControl|null): number|null {
-  if (cacheControl?.['max-age'] !== undefined) {
-    return cacheControl['max-age'];
-  }
-
-  const expiresHeaders = headers.find(h => h.name === 'expires')?.value ?? null;
-  if (expiresHeaders) {
-    const expires = new Date(expiresHeaders).getTime();
-    // Treat expires values as having already expired.
-    if (!expires) {
-      return 0;
-    }
-    return Math.ceil((expires - Date.now()) / 1000);
-  }
-  return null;
-}
-
-/**
- * Computes the percent likelihood that a return visit will be within the cache lifetime, based on
- * historical Chrome UMA stats (see RESOURCE_AGE_IN_HOURS_DECILES comment).
- *
- * This function returns values on this curve: https://www.desmos.com/calculator/eaqiszhugy (but using seconds, rather than hours)
- * See http://github.com/GoogleChrome/lighthouse/pull/3531 for history.
- */
-function getCacheHitProbability(maxAgeInSeconds: number): number {
-  // This array contains the hand wavy distribution of the age of a resource in hours at the time of
-  // cache hit at 0th, 10th, 20th, 30th, etc percentiles. This is used to compute `wastedMs` since there
-  // are clearly diminishing returns to cache duration i.e. 6 months is not 2x better than 3 months.
-  // Based on UMA stats for HttpCache.StaleEntry.Validated.Age. see https://www.desmos.com/calculator/jjwc5mzuwd
-  // This UMA data is from 2017 but the metric isn't tracked any longer in 2025.
-  const RESOURCE_AGE_IN_HOURS_DECILES = [0, 0.2, 1, 3, 8, 12, 24, 48, 72, 168, 8760, Infinity];
-
-  const maxAgeInHours = maxAgeInSeconds / 3600;
-  const upperDecileIndex = RESOURCE_AGE_IN_HOURS_DECILES.findIndex(decile => decile >= maxAgeInHours);
-
-  // Clip the likelihood between 0 and 1
-  if (upperDecileIndex === RESOURCE_AGE_IN_HOURS_DECILES.length - 1) {
-    return 1;
-  }
-  if (upperDecileIndex === 0) {
-    return 0;
-  }
-
-  // Use the two closest decile points as control points
-  const upperDecileValue = RESOURCE_AGE_IN_HOURS_DECILES[upperDecileIndex];
-  const lowerDecileValue = RESOURCE_AGE_IN_HOURS_DECILES[upperDecileIndex - 1];
-  const upperDecile = upperDecileIndex / 10;
-  const lowerDecile = (upperDecileIndex - 1) / 10;
-
-  // Approximate the real likelihood with linear interpolation
-  return linearInterpolation(lowerDecileValue, lowerDecile, upperDecileValue, upperDecile, maxAgeInHours);
-}
-
-export function getCombinedHeaders(responseHeaders: Array<{name: string, value: string}>): Map<string, string> {
-  const headers = new Map<string, string>();
-  for (const header of responseHeaders) {
-    const name = header.name.toLowerCase();
-    if (headers.get(name)) {
-      headers.set(name, `${headers.get(name)}, ${header.value}`);
-    } else {
-      headers.set(name, header.value);
-    }
-  }
-  return headers;
-}
-
-/**
- * Returns whether a request contains headers that disable caching.
- * Disabled caching is checked on the 'cache-control' and 'pragma' headers.
- */
-export function cachingDisabled(
-    headers: Map<string, string>|null, parsedCacheControl: Helpers.Network.CacheControl|null): boolean {
-  const cacheControl = headers?.get('cache-control') ?? null;
-  const pragma = headers?.get('pragma') ?? null;
-
-  // The HTTP/1.0 Pragma header can disable caching if cache-control is not set, see https://tools.ietf.org/html/rfc7234#section-5.4
-  if (!cacheControl && pragma?.includes('no-cache')) {
-    return true;
-  }
-
-  // If we have any of these, the user intentionally doesn't want to cache.
-  if (parsedCacheControl &&
-      (parsedCacheControl['must-revalidate'] || parsedCacheControl['no-cache'] || parsedCacheControl['no-store'] ||
-       parsedCacheControl['private'])) {
-    return true;
-  }
-
-  return false;
-}
-
-export interface CacheableRequest {
-  request: Types.Events.SyntheticNetworkRequest;
-  ttl: number;
-  wastedBytes: number;
-}
-
-export function isCacheInsight(model: InsightModel): model is CacheInsightModel {
-  return model.insightKey === InsightKeys.CACHE;
-}
-
-export function generateInsight(data: Handlers.Types.HandlerData, context: InsightSetContext): CacheInsightModel {
-  const isWithinContext = (event: Types.Events.Event): boolean => Helpers.Timing.eventIsInBounds(event, context.bounds);
-  const contextRequests = data.NetworkRequests.byTime.filter(isWithinContext);
-
-  const results: CacheableRequest[] = [];
-  let totalWastedBytes = 0;
-  const wastedBytesByRequestId = new Map<string, number>();
-  for (const req of contextRequests) {
-    if (!req.args.data.responseHeaders || !isCacheable(req)) {
-      continue;
-    }
-
-    const headers = getCombinedHeaders(req.args.data.responseHeaders);
-    const cacheControl = headers.get('cache-control') ?? null;
-    const parsedDirectives = Helpers.Network.parseCacheControl(cacheControl);
-
-    // Skip requests that are deliberately avoiding caching.
-    if (cachingDisabled(headers, parsedDirectives)) {
-      continue;
-    }
-
-    let ttl = computeCacheLifetimeInSeconds(req.args.data.responseHeaders, parsedDirectives);
-    // Ignore if a non-positive number.
-    if (ttl !== null && (!Number.isFinite(ttl) || ttl <= 0)) {
-      continue;
-    }
-    ttl = ttl || 0;
-
-    // Ignore >= 30d.
-    const ttlDays = ttl / 86400;
-    if (ttlDays >= 30) {
-      continue;
-    }
-
-    // If cache lifetime is high enough, let's skip.
-    const cacheHitProbability = getCacheHitProbability(ttl);
-    if (cacheHitProbability > IGNORE_THRESHOLD_IN_PERCENT) {
-      continue;
-    }
-
-    const transferSize = req.args.data.encodedDataLength || 0;
-    const wastedBytes = (1 - cacheHitProbability) * transferSize;
-
-    wastedBytesByRequestId.set(req.args.data.requestId, wastedBytes);
-    totalWastedBytes += wastedBytes;
-
-    results.push({request: req, ttl, wastedBytes});
-  }
-
-  // Sort by transfer size.
-  results.sort((a, b) => {
-    return b.request.args.data.decodedBodyLength - a.request.args.data.decodedBodyLength || a.ttl - b.ttl;
-  });
-
-  return finalize({
-    relatedEvents: results.map(r => r.request),
-    requests: results,
-    metricSavings: metricSavingsForWastedBytes(wastedBytesByRequestId, context),
-    wastedBytes: totalWastedBytes,
-  });
-}
-
-export function createOverlayForRequest(request: Types.Events.SyntheticNetworkRequest): Types.Overlays.EntryOutline {
-  return {
-    type: 'ENTRY_OUTLINE',
-    entry: request,
-    outlineReason: 'ERROR',
-  };
-}
-
-export function createOverlays(model: CacheInsightModel): Types.Overlays.Overlay[] {
-  return model.requests.map(req => createOverlayForRequest(req.request));
-}