devtools-tracing 1.0.0

package/lib/front_end/models/trace/lantern/metrics/TBTUtils.ts

@@ -0,0 +1,82 @@
+// 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.
+
+const BLOCKING_TIME_THRESHOLD = 50;
+
+/**
+ * For TBT, We only want to consider tasks that fall in our time range
+ * - FCP and TTI for navigation mode
+ * - Trace start and trace end for timespan mode
+ *
+ * FCP is picked as `startTimeMs` because there is little risk of user input happening
+ * before FCP so Long Queuing Qelay regions do not harm user experience. Developers should be
+ * optimizing to reach FCP as fast as possible without having to worry about task lengths.
+ *
+ * TTI is picked as `endTimeMs` because we want a well defined end point for page load.
+ *
+ * @param startTimeMs Should be FCP in navigation mode and the trace start time in timespan mode
+ * @param endTimeMs Should be TTI in navigation mode and the trace end time in timespan mode
+ * @param topLevelEvent Leave unset if `event` is top level. Has no effect if `event` has the same duration as `topLevelEvent`.
+ */
+function calculateTbtImpactForEvent(
+    event: {start: number, end: number, duration: number}, startTimeMs: number, endTimeMs: number,
+    topLevelEvent?: {start: number, end: number, duration: number}): number {
+  let threshold = BLOCKING_TIME_THRESHOLD;
+
+  // If a task is not top level, it doesn't make sense to subtract the entire 50ms
+  // blocking threshold from the event.
+  //
+  // e.g. A 80ms top level task with two 40ms children should attribute some blocking
+  // time to the 40ms tasks even though they do not meet the 50ms threshold.
+  //
+  // The solution is to scale the threshold for child events to be considered blocking.
+  if (topLevelEvent) {
+    threshold *= (event.duration / topLevelEvent.duration);
+  }
+
+  if (event.duration < threshold) {
+    return 0;
+  }
+  if (event.end < startTimeMs) {
+    return 0;
+  }
+  if (event.start > endTimeMs) {
+    return 0;
+  }
+
+  // Perform the clipping and then calculate Blocking Region. So if we have a 150ms task
+  // [0, 150] and `startTimeMs` is at 50ms, we first clip the task to [50, 150], and then
+  // calculate the Blocking Region to be [100, 150]. The rational here is that tasks before
+  // the start time are unimportant, so we care whether the main thread is busy more than
+  // 50ms at a time only after the start time.
+  const clippedStart = Math.max(event.start, startTimeMs);
+  const clippedEnd = Math.min(event.end, endTimeMs);
+  const clippedDuration = clippedEnd - clippedStart;
+  if (clippedDuration < threshold) {
+    return 0;
+  }
+
+  return clippedDuration - threshold;
+}
+
+function calculateSumOfBlockingTime(
+    topLevelEvents: Array<{start: number, end: number, duration: number}>, startTimeMs: number,
+    endTimeMs: number): number {
+  if (endTimeMs <= startTimeMs) {
+    return 0;
+  }
+
+  let sumBlockingTime = 0;
+  for (const event of topLevelEvents) {
+    sumBlockingTime += calculateTbtImpactForEvent(event, startTimeMs, endTimeMs);
+  }
+
+  return sumBlockingTime;
+}
+
+export {
+  BLOCKING_TIME_THRESHOLD,
+  calculateSumOfBlockingTime,
+  calculateTbtImpactForEvent,
+};

package/lib/front_end/models/trace/lantern/metrics/TotalBlockingTime.ts

@@ -0,0 +1,112 @@
+// 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 Core from '../core/core.js';
+import * as Graph from '../graph/graph.js';
+import type * as Simulation from '../simulation/simulation.js';
+
+import {
+  type Extras,
+  Metric,
+  type MetricCoefficients,
+  type MetricComputationDataInput,
+  type MetricResult,
+} from './Metric.js';
+import {BLOCKING_TIME_THRESHOLD, calculateSumOfBlockingTime} from './TBTUtils.js';
+
+class TotalBlockingTime extends Metric {
+  static override get coefficients(): MetricCoefficients {
+    return {
+      intercept: 0,
+      optimistic: 0.5,
+      pessimistic: 0.5,
+    };
+  }
+
+  static override getOptimisticGraph(dependencyGraph: Graph.Node): Graph.Node {
+    return dependencyGraph;
+  }
+
+  static override getPessimisticGraph(dependencyGraph: Graph.Node): Graph.Node {
+    return dependencyGraph;
+  }
+
+  static override getEstimateFromSimulation(simulation: Simulation.Result, extras: Extras): Simulation.Result {
+    if (!extras.fcpResult) {
+      throw new Core.LanternError('missing fcpResult');
+    }
+    if (!extras.interactiveResult) {
+      throw new Core.LanternError('missing interactiveResult');
+    }
+
+    // Intentionally use the opposite FCP estimate. A pessimistic FCP is higher than equal to an
+    // optimistic FCP, which means potentially more tasks are excluded from the Total Blocking Time
+    // computation. So a more pessimistic FCP gives a more optimistic Total Blocking Time for the
+    // same work.
+    const fcpTimeInMs = extras.optimistic ? extras.fcpResult.pessimisticEstimate.timeInMs :
+                                            extras.fcpResult.optimisticEstimate.timeInMs;
+
+    // Similarly, we always have pessimistic TTI >= optimistic TTI. Therefore, picking optimistic
+    // TTI means our window of interest is smaller and thus potentially more tasks are excluded from
+    // Total Blocking Time computation, yielding a lower (more optimistic) Total Blocking Time value
+    // for the same work.
+    const interactiveTimeMs = extras.optimistic ? extras.interactiveResult.optimisticEstimate.timeInMs :
+                                                  extras.interactiveResult.pessimisticEstimate.timeInMs;
+
+    const minDurationMs = BLOCKING_TIME_THRESHOLD;
+
+    const events = TotalBlockingTime.getTopLevelEvents(
+        simulation.nodeTimings,
+        minDurationMs,
+    );
+
+    return {
+      timeInMs: calculateSumOfBlockingTime(
+          events,
+          fcpTimeInMs,
+          interactiveTimeMs,
+          ),
+      nodeTimings: simulation.nodeTimings,
+    };
+  }
+
+  static override compute(data: MetricComputationDataInput, extras?: Omit<Extras, 'optimistic'>): MetricResult {
+    const fcpResult = extras?.fcpResult;
+    if (!fcpResult) {
+      throw new Core.LanternError('FCP is required to calculate the TBT metric');
+    }
+
+    const interactiveResult = extras?.fcpResult;
+    if (!interactiveResult) {
+      throw new Core.LanternError('Interactive is required to calculate the TBT metric');
+    }
+
+    return super.compute(data, extras);
+  }
+
+  static getTopLevelEvents(nodeTimings: Simulation.Result['nodeTimings'], minDurationMs: number):
+      Array<{start: number, end: number, duration: number}> {
+    const events: Array<{start: number, end: number, duration: number}> = [];
+
+    for (const [node, timing] of nodeTimings.entries()) {
+      if (node.type !== Graph.BaseNode.types.CPU) {
+        continue;
+      }
+      // Filtering out events below minimum duration.
+      if (timing.duration < minDurationMs) {
+        continue;
+      }
+
+      events.push({
+        start: timing.startTime,
+        end: timing.endTime,
+        duration: timing.duration,
+      });
+    }
+
+    return events;
+  }
+}
+
+export {TotalBlockingTime};

package/lib/front_end/models/trace/lantern/metrics/metrics.ts

@@ -0,0 +1,12 @@
+// 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.
+
+export * from './FirstContentfulPaint.js';
+export * from './Interactive.js';
+export * from './LargestContentfulPaint.js';
+export * from './MaxPotentialFID.js';
+export * from './Metric.js';
+export * from './SpeedIndex.js';
+export * from './TotalBlockingTime.js';
+export * as TBTUtils from './TBTUtils.js';

package/lib/front_end/models/trace/lantern/simulation/ConnectionPool.ts

@@ -0,0 +1,150 @@
+// 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 Core from '../core/core.js';
+import type * as Lantern from '../types/types.js';
+
+import {TCPConnection} from './TCPConnection.js';
+
+const DEFAULT_SERVER_RESPONSE_TIME = 30;
+const TLS_SCHEMES = ['https', 'wss'];
+
+// Each origin can have 6 simultaneous connections open
+// https://cs.chromium.org/chromium/src/net/socket/client_socket_pool_manager.cc?type=cs&q="int+g_max_sockets_per_group"
+const CONNECTIONS_PER_ORIGIN = 6;
+
+export class ConnectionPool {
+  options: Required<Lantern.Simulation.Options>;
+  records: Lantern.NetworkRequest[];
+  connectionsByOrigin: Map<string, TCPConnection[]>;
+  connectionsByRequest: Map<Lantern.NetworkRequest, TCPConnection>;
+  _connectionsInUse: Set<TCPConnection>;
+  connectionReusedByRequestId: Map<string, boolean>;
+
+  constructor(records: Lantern.NetworkRequest[], options: Required<Lantern.Simulation.Options>) {
+    this.options = options;
+
+    this.records = records;
+    this.connectionsByOrigin = new Map();
+    this.connectionsByRequest = new Map();
+    this._connectionsInUse = new Set();
+    this.connectionReusedByRequestId = Core.NetworkAnalyzer.estimateIfConnectionWasReused(records, {
+      forceCoarseEstimates: true,
+    });
+
+    this.initializeConnections();
+  }
+
+  connectionsInUse(): TCPConnection[] {
+    return Array.from(this._connectionsInUse);
+  }
+
+  initializeConnections(): void {
+    const connectionReused = this.connectionReusedByRequestId;
+    const additionalRttByOrigin = this.options.additionalRttByOrigin;
+    const serverResponseTimeByOrigin = this.options.serverResponseTimeByOrigin;
+
+    const recordsByOrigin = Core.NetworkAnalyzer.groupByOrigin(this.records);
+    for (const [origin, requests] of recordsByOrigin.entries()) {
+      const connections = [];
+      const additionalRtt = additionalRttByOrigin.get(origin) || 0;
+      const responseTime = serverResponseTimeByOrigin.get(origin) || DEFAULT_SERVER_RESPONSE_TIME;
+
+      for (const request of requests) {
+        if (connectionReused.get(request.requestId)) {
+          continue;
+        }
+
+        const isTLS = TLS_SCHEMES.includes(request.parsedURL.scheme);
+        const isH2 = request.protocol === 'h2';
+        const connection = new TCPConnection(
+            this.options.rtt + additionalRtt,
+            this.options.throughput,
+            responseTime,
+            isTLS,
+            isH2,
+        );
+
+        connections.push(connection);
+      }
+
+      if (!connections.length) {
+        throw new Core.LanternError(`Could not find a connection for origin: ${origin}`);
+      }
+
+      // Make sure each origin has minimum number of connections available for max throughput.
+      // But only if it's not over H2 which maximizes throughput already.
+      const minConnections = connections[0].isH2() ? 1 : CONNECTIONS_PER_ORIGIN;
+      while (connections.length < minConnections) {
+        connections.push(connections[0].clone());
+      }
+
+      this.connectionsByOrigin.set(origin, connections);
+    }
+  }
+
+  findAvailableConnectionWithLargestCongestionWindow(connections: TCPConnection[]): TCPConnection|null {
+    let maxConnection: TCPConnection|null = null;
+    for (let i = 0; i < connections.length; i++) {
+      const connection = connections[i];
+
+      // Connections that are in use are never available.
+      if (this._connectionsInUse.has(connection)) {
+        continue;
+      }
+
+      // This connection is a match and is available! Update our max if it has a larger congestionWindow
+      const currentMax = (maxConnection?.congestionWindow) || -Infinity;
+      if (connection.congestionWindow > currentMax) {
+        maxConnection = connection;
+      }
+    }
+
+    return maxConnection;
+  }
+
+  /**
+   * 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
+   * records until release is called.
+   */
+  acquire(request: Lantern.NetworkRequest): TCPConnection|null {
+    if (this.connectionsByRequest.has(request)) {
+      throw new Core.LanternError('Record already has a connection');
+    }
+
+    const origin = request.parsedURL.securityOrigin;
+    const connections = this.connectionsByOrigin.get(origin) || [];
+    const connectionToUse = this.findAvailableConnectionWithLargestCongestionWindow(connections);
+
+    if (!connectionToUse) {
+      return null;
+    }
+
+    this._connectionsInUse.add(connectionToUse);
+    this.connectionsByRequest.set(request, connectionToUse);
+    return connectionToUse;
+  }
+
+  /**
+   * Return the connection currently being used to fetch a request. If no connection
+   * currently being used for this request, an error will be thrown.
+   */
+  acquireActiveConnectionFromRequest(request: Lantern.NetworkRequest): TCPConnection {
+    const activeConnection = this.connectionsByRequest.get(request);
+    if (!activeConnection) {
+      throw new Core.LanternError('Could not find an active connection for request');
+    }
+
+    return activeConnection;
+  }
+
+  release(request: Lantern.NetworkRequest): void {
+    const connection = this.connectionsByRequest.get(request);
+    this.connectionsByRequest.delete(request);
+    if (connection) {
+      this._connectionsInUse.delete(connection);
+    }
+  }
+}

package/lib/front_end/models/trace/lantern/simulation/Constants.ts

@@ -0,0 +1,46 @@
+// 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.
+
+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/lib/front_end/models/trace/lantern/simulation/DNSCache.ts

@@ -0,0 +1,61 @@
+// 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 type * as Lantern from '../types/types.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
+// Example: https://www.webpagetest.org/result/180707_1M_89673eb633b5d98386de95dfcf9b33d5/1/details/#waterfall_view_step1
+// DNS is highly variable though, many times it's a little more than 1, but can easily be 4-5x RTT.
+// We'll use 2 since it seems to give the most accurate results on average, but this can be tweaked.
+const DNS_RESOLUTION_RTT_MULTIPLIER = 2;
+
+class DNSCache {
+  static rttMultiplier = DNS_RESOLUTION_RTT_MULTIPLIER;
+
+  rtt: number;
+  resolvedDomainNames: Map<string, {resolvedAt: number}>;
+
+  constructor({rtt}: {rtt: number}) {
+    this.rtt = rtt;
+    this.resolvedDomainNames = new Map();
+  }
+
+  getTimeUntilResolution(
+      request: Lantern.NetworkRequest, options?: {requestedAt?: number, shouldUpdateCache?: boolean}): number {
+    const {requestedAt = 0, shouldUpdateCache = false} = options || {};
+
+    const domain = request.parsedURL.host;
+    const cacheEntry = this.resolvedDomainNames.get(domain);
+    let timeUntilResolved = this.rtt * DNSCache.rttMultiplier;
+    if (cacheEntry) {
+      const timeUntilCachedIsResolved = Math.max(cacheEntry.resolvedAt - requestedAt, 0);
+      timeUntilResolved = Math.min(timeUntilCachedIsResolved, timeUntilResolved);
+    }
+
+    const resolvedAt = requestedAt + timeUntilResolved;
+    if (shouldUpdateCache) {
+      this.updateCacheResolvedAtIfNeeded(request, resolvedAt);
+    }
+
+    return timeUntilResolved;
+  }
+
+  updateCacheResolvedAtIfNeeded(request: Lantern.NetworkRequest, resolvedAt: number): void {
+    const domain = request.parsedURL.host;
+    const cacheEntry = this.resolvedDomainNames.get(domain) || {resolvedAt};
+    cacheEntry.resolvedAt = Math.min(cacheEntry.resolvedAt, resolvedAt);
+    this.resolvedDomainNames.set(domain, cacheEntry);
+  }
+
+  /**
+   * Forcefully sets the DNS resolution time for a request.
+   * Useful for testing and alternate execution simulations.
+   */
+  setResolvedAt(domain: string, resolvedAt: number): void {
+    this.resolvedDomainNames.set(domain, {resolvedAt});
+  }
+}
+
+export {DNSCache};

package/lib/front_end/models/trace/lantern/simulation/SimulationTimingMap.ts

@@ -0,0 +1,196 @@
+// 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.
+
+/**
+ * @file
+ *
+ * This class encapsulates the type-related validation logic for moving timing information for nodes
+ * through the different simulation phases. Methods here ensure that the invariants of simulation hold
+ * as nodes are queued, partially simulated, and completed.
+ */
+
+import * as Core from '../core/core.js';
+import * as Graph from '../graph/graph.js';
+
+interface NodeTimingComplete {
+  startTime: number;
+  endTime: number;
+  queuedTime: number;
+  estimatedTimeElapsed: number;
+  timeElapsed: number;
+  timeElapsedOvershoot: number;
+  bytesDownloaded: number;
+}
+
+type NodeTimingQueued = Pick<NodeTimingComplete, 'queuedTime'>;
+
+type CpuNodeTimingStarted = NodeTimingQueued&Pick<NodeTimingComplete, 'startTime'|'timeElapsed'>;
+type NetworkNodeTimingStarted = CpuNodeTimingStarted&Pick<NodeTimingComplete, 'timeElapsedOvershoot'|'bytesDownloaded'>;
+
+type CpuNodeTimingInProgress = CpuNodeTimingStarted&Pick<NodeTimingComplete, 'estimatedTimeElapsed'>;
+type NetworkNodeTimingInProgress = NetworkNodeTimingStarted&Pick<NodeTimingComplete, 'estimatedTimeElapsed'>;
+
+export type CpuNodeTimingComplete = CpuNodeTimingInProgress&Pick<NodeTimingComplete, 'endTime'>;
+export type NetworkNodeTimingComplete =
+    NetworkNodeTimingInProgress&Pick<NodeTimingComplete, 'endTime'>&{connectionTiming: ConnectionTiming};
+export type CompleteNodeTiming = CpuNodeTimingComplete|NetworkNodeTimingComplete;
+
+type NodeTimingData = NodeTimingQueued|CpuNodeTimingStarted|NetworkNodeTimingStarted|CpuNodeTimingInProgress|
+    NetworkNodeTimingInProgress|CpuNodeTimingComplete|NetworkNodeTimingComplete;
+
+export interface ConnectionTiming {
+  dnsResolutionTime?: number;
+  connectionTime?: number;
+  sslTime?: number;
+  timeToFirstByte: number;
+}
+
+class SimulatorTimingMap {
+  nodeTimings: Map<Graph.Node, NodeTimingData>;
+
+  constructor() {
+    this.nodeTimings = new Map<Graph.Node, NodeTimingData>();
+  }
+
+  getNodes(): Graph.Node[] {
+    return Array.from(this.nodeTimings.keys());
+  }
+
+  setReadyToStart(node: Graph.Node, values: {queuedTime: number}): void {
+    this.nodeTimings.set(node, values);
+  }
+
+  setInProgress(node: Graph.Node, values: {startTime: number}): void {
+    const nodeTiming = {
+      ...this.getQueued(node),
+      startTime: values.startTime,
+      timeElapsed: 0,
+    };
+
+    this.nodeTimings.set(
+        node,
+        node.type === Graph.BaseNode.types.NETWORK ? {...nodeTiming, timeElapsedOvershoot: 0, bytesDownloaded: 0} :
+                                                     nodeTiming,
+    );
+  }
+
+  setCompleted(node: Graph.Node, values: {endTime: number, connectionTiming?: ConnectionTiming}): void {
+    const nodeTiming = {
+      ...this.getInProgress(node),
+      endTime: values.endTime,
+      connectionTiming: values.connectionTiming,
+    };
+
+    this.nodeTimings.set(node, nodeTiming);
+  }
+
+  setCpu(node: Graph.CPUNode, values: {timeElapsed: number}): void {
+    const nodeTiming = {
+      ...this.getCpuStarted(node),
+      timeElapsed: values.timeElapsed,
+    };
+
+    this.nodeTimings.set(node, nodeTiming);
+  }
+
+  setCpuEstimated(node: Graph.CPUNode, values: {estimatedTimeElapsed: number}): void {
+    const nodeTiming = {
+      ...this.getCpuStarted(node),
+      estimatedTimeElapsed: values.estimatedTimeElapsed,
+    };
+
+    this.nodeTimings.set(node, nodeTiming);
+  }
+
+  setNetwork(
+      node: Graph.NetworkNode,
+      values: {timeElapsed: number, timeElapsedOvershoot: number, bytesDownloaded: number}): void {
+    const nodeTiming = {
+      ...this.getNetworkStarted(node),
+      timeElapsed: values.timeElapsed,
+      timeElapsedOvershoot: values.timeElapsedOvershoot,
+      bytesDownloaded: values.bytesDownloaded,
+    };
+
+    this.nodeTimings.set(node, nodeTiming);
+  }
+
+  setNetworkEstimated(node: Graph.NetworkNode, values: {estimatedTimeElapsed: number}): void {
+    const nodeTiming = {
+      ...this.getNetworkStarted(node),
+      estimatedTimeElapsed: values.estimatedTimeElapsed,
+    };
+
+    this.nodeTimings.set(node, nodeTiming);
+  }
+
+  getQueued(node: Graph.Node): NodeTimingData {
+    const timing = this.nodeTimings.get(node);
+    if (!timing) {
+      throw new Core.LanternError(`Node ${node.id} not yet queued`);
+    }
+    return timing;
+  }
+
+  getCpuStarted(node: Graph.CPUNode): CpuNodeTimingStarted {
+    const timing = this.nodeTimings.get(node);
+    if (!timing) {
+      throw new Core.LanternError(`Node ${node.id} not yet queued`);
+    }
+    if (!('startTime' in timing)) {
+      throw new Core.LanternError(`Node ${node.id} not yet started`);
+    }
+    if ('bytesDownloaded' in timing) {
+      throw new Core.LanternError(`Node ${node.id} timing not valid`);
+    }
+    return timing;
+  }
+
+  getNetworkStarted(node: Graph.NetworkNode): NetworkNodeTimingStarted {
+    const timing = this.nodeTimings.get(node);
+    if (!timing) {
+      throw new Core.LanternError(`Node ${node.id} not yet queued`);
+    }
+    if (!('startTime' in timing)) {
+      throw new Core.LanternError(`Node ${node.id} not yet started`);
+    }
+    if (!('bytesDownloaded' in timing)) {
+      throw new Core.LanternError(`Node ${node.id} timing not valid`);
+    }
+    return timing;
+  }
+
+  getInProgress(node: Graph.Node): CpuNodeTimingInProgress|NetworkNodeTimingInProgress {
+    const timing = this.nodeTimings.get(node);
+    if (!timing) {
+      throw new Core.LanternError(`Node ${node.id} not yet queued`);
+    }
+    if (!('startTime' in timing)) {
+      throw new Core.LanternError(`Node ${node.id} not yet started`);
+    }
+    if (!('estimatedTimeElapsed' in timing)) {
+      throw new Core.LanternError(`Node ${node.id} not yet in progress`);
+    }
+    return timing;
+  }
+
+  getCompleted(node: Graph.Node): CpuNodeTimingComplete|NetworkNodeTimingComplete {
+    const timing = this.nodeTimings.get(node);
+    if (!timing) {
+      throw new Core.LanternError(`Node ${node.id} not yet queued`);
+    }
+    if (!('startTime' in timing)) {
+      throw new Core.LanternError(`Node ${node.id} not yet started`);
+    }
+    if (!('estimatedTimeElapsed' in timing)) {
+      throw new Core.LanternError(`Node ${node.id} not yet in progress`);
+    }
+    if (!('endTime' in timing)) {
+      throw new Core.LanternError(`Node ${node.id} not yet completed`);
+    }
+    return timing;
+  }
+}
+
+export {SimulatorTimingMap};