devtools-tracing 1.0.0

package/lib/front_end/core/sdk/ServerSentEventsProtocol.ts

@@ -0,0 +1,122 @@
+// Copyright 2023 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 Protocol from '../../generated/protocol.js';
+
+/**
+ * Implements Server-Sent-Events protocl parsing as described by
+ * https://html.spec.whatwg.org/multipage/server-sent-events.html#parsing-an-event-stream
+ *
+ * Webpages can use SSE over fetch/XHR and not go through EventSource. DevTools
+ * only receives the raw binary data in this case, which means we have to decode
+ * and parse the event stream ourselves here.
+ *
+ * Implementation mostly ported over from blink
+ * third_party/blink/renderer/modules/eventsource/event_source_parser.cc.
+ */
+export class ServerSentEventsParser {
+  #onEventCallback: (eventType: string, data: string, eventId: string) => void;
+  #decoder: Base64TextDecoder;
+
+  // Parser state.
+  #isRecognizingCrLf = false;
+  #line = '';
+  #id = '';
+  #data = '';
+  #eventType = '';
+
+  constructor(callback: (eventType: string, data: string, eventId: string) => void, encodingLabel?: string) {
+    this.#onEventCallback = callback;
+    this.#decoder = new Base64TextDecoder(this.#onTextChunk.bind(this), encodingLabel);
+  }
+
+  async addBase64Chunk(raw: Protocol.binary): Promise<void> {
+    await this.#decoder.addBase64Chunk(raw);
+  }
+
+  #onTextChunk(chunk: string): void {
+    // A line consists of "this.#line" plus a slice of "chunk[start:<next new cr/lf>]".
+    let start = 0;
+    for (let i = 0; i < chunk.length; ++i) {
+      if (this.#isRecognizingCrLf && chunk[i] === '\n') {
+        // We found the latter part of "\r\n".
+        this.#isRecognizingCrLf = false;
+        ++start;
+        continue;
+      }
+      this.#isRecognizingCrLf = false;
+      if (chunk[i] === '\r' || chunk[i] === '\n') {
+        this.#line += chunk.substring(start, i);
+        this.#parseLine();
+        this.#line = '';
+        start = i + 1;
+        this.#isRecognizingCrLf = chunk[i] === '\r';
+      }
+    }
+    this.#line += chunk.substring(start);
+  }
+
+  #parseLine(): void {
+    if (this.#line.length === 0) {
+      // We dispatch an event when seeing an empty line.
+      if (this.#data.length > 0) {
+        const data = this.#data.slice(0, -1);  // Remove the last newline.
+        this.#onEventCallback(this.#eventType || 'message', data, this.#id);
+        this.#data = '';
+      }
+      this.#eventType = '';
+      return;
+    }
+
+    let fieldNameEnd = this.#line.indexOf(':');
+    let fieldValueStart;
+    if (fieldNameEnd < 0) {
+      fieldNameEnd = this.#line.length;
+      fieldValueStart = fieldNameEnd;
+    } else {
+      fieldValueStart = fieldNameEnd + 1;
+      if (fieldValueStart < this.#line.length && this.#line[fieldValueStart] === ' ') {
+        // Skip a single space preceeding the value.
+        ++fieldValueStart;
+      }
+    }
+    const fieldName = this.#line.substring(0, fieldNameEnd);
+    if (fieldName === 'event') {
+      this.#eventType = this.#line.substring(fieldValueStart);
+      return;
+    }
+    if (fieldName === 'data') {
+      this.#data += this.#line.substring(fieldValueStart);
+      this.#data += '\n';
+    }
+    if (fieldName === 'id') {
+      // We should do a check here whether the id field contains "\0" and ignore it.
+      this.#id = this.#line.substring(fieldValueStart);
+    }
+    // Ignore all other fields. Also ignore "retry", we won't forward that to the backend.
+  }
+}
+
+/**
+ * Small helper class that can decode a stream of base64 encoded bytes. Specify the
+ * text encoding for the raw bytes via constructor. Default is utf-8.
+ */
+class Base64TextDecoder {
+  #decoder: TextDecoderStream;
+  #writer: WritableStreamDefaultWriter;
+
+  constructor(onTextChunk: (chunk: string) => void, encodingLabel?: string) {
+    this.#decoder = new TextDecoderStream(encodingLabel);
+    this.#writer = this.#decoder.writable.getWriter();
+    void this.#decoder.readable.pipeTo(new WritableStream({write: onTextChunk}));
+  }
+
+  async addBase64Chunk(chunk: Protocol.binary): Promise<void> {
+    const binString = window.atob(chunk);
+    const bytes = Uint8Array.from(binString, m => m.codePointAt(0) as number);
+
+    await this.#writer.ready;
+    await this.#writer.write(bytes);
+  }
+}

package/lib/front_end/core/sdk/ServerTiming.ts

@@ -0,0 +1,260 @@
+// Copyright 2016 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 Common from '../common/common.js';
+import * as i18n from '../i18n/i18n.js';
+
+import type {NameValue} from './NetworkRequest.js';
+
+const UIStrings = {
+  /**
+   * @description Text in Server Timing
+   * @example {sql-lookup} PH1
+   */
+  deprecatedSyntaxFoundPleaseUse:
+      'Deprecated syntax found for metric "{PH1}". Please use: <name>;dur=<duration>;desc=<description>',
+  /**
+   * @description Text in Server Timing
+   * @example {https} PH1
+   */
+  duplicateParameterSIgnored: 'Duplicate parameter "{PH1}" ignored.',
+  /**
+   * @description Text in Server Timing
+   * @example {https} PH1
+   */
+  noValueFoundForParameterS: 'No value found for parameter "{PH1}".',
+  /**
+   * @description Text in Server Timing
+   * @example {https} PH1
+   */
+  unrecognizedParameterS: 'Unrecognized parameter "{PH1}".',
+  /**
+   * @description Text in Server Timing
+   */
+  extraneousTrailingCharacters: 'Extraneous trailing characters.',
+  /**
+   * @description Text in Server Timing
+   * @example {https} PH1
+   * @example {2.0} PH2
+   */
+  unableToParseSValueS: 'Unable to parse "{PH1}" value "{PH2}".',
+} as const;
+const str_ = i18n.i18n.registerUIStrings('core/sdk/ServerTiming.ts', UIStrings);
+const i18nString = i18n.i18n.getLocalizedString.bind(undefined, str_);
+
+/**
+ * Represents an authored single server timing metric. https://w3c.github.io/server-timing/#the-server-timing-header-field
+ */
+export interface ServerTimingMetric {
+  /** The name of the metric, a single token */
+  name: string;
+  /** A human-readable description of the metric. */
+  desc?: string;
+  /** The duration; milliseconds is recommended. https://w3c.github.io/server-timing/#duration-attribute. */
+  dur?: number;
+}
+
+export const cloudflarePrefix = '(cf) ';
+export const cloudinaryPrefix = '(cld) ';
+
+export class ServerTiming {
+  metric: string;
+  value: number|null;
+  description: string|null;
+
+  constructor(metric: string, value: number|null, description: string|null) {
+    this.metric = metric;
+    this.value = value;
+    this.description = description;
+  }
+
+  static parseHeaders(headers: NameValue[]): ServerTiming[]|null {
+    const rawServerTimingHeaders = headers.filter(item => item.name.toLowerCase() === 'server-timing');
+    if (!rawServerTimingHeaders.length) {
+      return null;
+    }
+
+    const serverTimings = rawServerTimingHeaders.reduce<ServerTiming[]>((timings, header) => {
+      const timing = this.createFromHeaderValue(header.value);
+      timings.push(...timing.map(function(entry) {
+        return new ServerTiming(entry.name, entry.dur ?? null, entry.desc ?? '');
+      }));
+      return timings;
+    }, []);
+    return serverTimings;
+  }
+
+  static createFromHeaderValue(valueString: string): ServerTimingMetric[] {
+    function trimLeadingWhiteSpace(): void {
+      valueString = valueString.replace(/^\s*/, '');
+    }
+    function consumeDelimiter(char: string): boolean {
+      console.assert(char.length === 1);
+      trimLeadingWhiteSpace();
+      if (valueString.charAt(0) !== char) {
+        return false;
+      }
+
+      valueString = valueString.substring(1);
+      return true;
+    }
+    function consumeToken(): string|null {
+      // https://tools.ietf.org/html/rfc7230#appendix-B
+      const result = /^(?:\s*)([\w!#$%&'*+\-.^`|~]+)(?:\s*)(.*)/.exec(valueString);
+      if (!result) {
+        return null;
+      }
+
+      valueString = result[2];
+      return result[1];
+    }
+    function consumeTokenOrQuotedString(): string|null {
+      trimLeadingWhiteSpace();
+      if (valueString.charAt(0) === '"') {
+        return consumeQuotedString();
+      }
+
+      return consumeToken();
+    }
+    function consumeQuotedString(): string|null {
+      console.assert(valueString.charAt(0) === '"');
+      valueString = valueString.substring(1);  // remove leading DQUOTE
+
+      let value = '';
+      while (valueString.length) {
+        // split into two parts:
+        //  -everything before the first " or \
+        //  -everything else
+        const result = /^([^"\\]*)(.*)/.exec(valueString);
+        if (!result) {
+          return null;  // not a valid quoted-string
+        }
+        value += result[1];
+        if (result[2].charAt(0) === '"') {
+          // we have found our closing "
+          valueString = result[2].substring(1);  // strip off everything after the closing "
+          return value;                          // we are done here
+        }
+
+        console.assert(result[2].charAt(0) === '\\');
+        // special rules for \ found in quoted-string (https://tools.ietf.org/html/rfc7230#section-3.2.6)
+        value += result[2].charAt(1);          // grab the character AFTER the \ (if there was one)
+        valueString = result[2].substring(2);  // strip off \ and next character
+      }
+
+      return null;  // not a valid quoted-string
+    }
+    function consumeExtraneous(): void {
+      const result = /([,;].*)/.exec(valueString);
+      if (result) {
+        valueString = result[1];
+      }
+    }
+
+    const result: ServerTimingMetric[] = [];
+    let name;
+    while ((name = consumeToken()) !== null) {
+      const entry: ServerTimingMetric = {name};
+
+      if (valueString.charAt(0) === '=') {
+        this.showWarning(i18nString(UIStrings.deprecatedSyntaxFoundPleaseUse, {PH1: name}));
+      }
+
+      while (consumeDelimiter(';')) {
+        let paramName;
+        if ((paramName = consumeToken()) === null) {
+          continue;
+        }
+
+        paramName = paramName.toLowerCase();
+        const parseParameter = this.getParserForParameter(paramName);
+        let paramValue: (string|null)|null = null;
+        if (consumeDelimiter('=')) {
+          // always parse the value, even if we don't recognize the parameter #name
+          paramValue = consumeTokenOrQuotedString();
+          consumeExtraneous();
+        }
+
+        if (parseParameter) {
+          // paramName is valid
+          if (entry.hasOwnProperty(paramName)) {
+            this.showWarning(i18nString(UIStrings.duplicateParameterSIgnored, {PH1: paramName}));
+            continue;
+          }
+
+          if (paramValue === null) {
+            this.showWarning(i18nString(UIStrings.noValueFoundForParameterS, {PH1: paramName}));
+          }
+
+          parseParameter.call(this, entry, paramValue);
+        } else {
+          // paramName is not valid
+          // TODO(paulirish): consider showing other included params, like `start`: https://github.com/w3c/server-timing/issues/43
+          this.showWarning(i18nString(UIStrings.unrecognizedParameterS, {PH1: paramName}));
+        }
+      }
+
+      result.push(entry);
+
+      // Special parsing for cloudflare's bespoke format. https://blog.cloudflare.com/new-standards/#measuring-impact
+      // We extract the individual items of the cfL4 server-timing for clear presentation
+      if (entry.name === 'cfL4' && entry.desc) {
+        new URLSearchParams(entry.desc).entries().forEach(([key, val]) => {
+          result.push({name: `${cloudflarePrefix}${key}`, desc: val});
+        });
+      }
+
+      // Special parsing for cloudinary's bespoke format. https://cloudinary.com/blog/inside_the_black_box_with_server_timing#what_details_are_you_sharing_
+      // The format has changed since this blog post
+      if (entry.name === 'content-info' && entry.desc) {
+        new URLSearchParams(entry.desc.replace(/,/g, '&')).entries().forEach(([key, val]) => {
+          result.push({name: `${cloudinaryPrefix}${key}`, desc: val});
+        });
+      }
+
+      if (!consumeDelimiter(',')) {
+        break;
+      }
+    }
+
+    if (valueString.length) {
+      this.showWarning(i18nString(UIStrings.extraneousTrailingCharacters));
+    }
+    return result;
+  }
+
+  static getParserForParameter(paramName: string): ((arg0: ServerTimingMetric, arg1: string|null) => void)|null {
+    switch (paramName) {
+      case 'dur': {
+        function durParser(entry: ServerTimingMetric, paramValue: string|null): void {
+          entry.dur = 0;
+          if (paramValue !== null) {
+            const duration = parseFloat(paramValue);
+            if (isNaN(duration)) {
+              ServerTiming.showWarning(i18nString(UIStrings.unableToParseSValueS, {PH1: paramName, PH2: paramValue}));
+              return;
+            }
+            entry.dur = duration;
+          }
+        }
+        return durParser;
+      }
+
+      case 'desc': {
+        function descParser(entry: ServerTimingMetric, paramValue: string|null): void {
+          entry.desc = paramValue || '';
+        }
+        return descParser;
+      }
+
+      default: {
+        return null;
+      }
+    }
+  }
+
+  static showWarning(msg: string): void {
+    Common.Console.Console.instance().warn(`ServerTiming: ${msg}`);
+  }
+}