wrangler 0.0.0-fb43821 → 0.0.0-fb53fda

package/src/tail/filters.ts

@@ -0,0 +1,279 @@
+/**
+ * When tailing logs from a worker, oftentimes you don't want to see _every
+ * single event_. That's where filters come in. We can send a set of filters
+ * to the tail worker, and it will pre-filter any logs for us so that we
+ * only recieve the ones we care about.
+ */
+
+/**
+ * These are the filters we accept in the CLI. They
+ * were copied directly from wrangler 1 in order to
+ * maintain compatability, so they aren't actually the exact
+ * filters we need to send up to the tail worker. They generally map 1:1,
+ * but often require some transformation or
+ * renaming to match what it expects.
+ *
+ * For a full description of each filter, either check the
+ * CLI description or see the documentation for `ApiFilter`.
+ */
+export type TailCLIFilters = {
+  status?: ("ok" | "error" | "canceled")[];
+  header?: string;
+  method?: string[];
+  search?: string;
+  samplingRate?: number;
+  clientIp?: string[];
+};
+
+/**
+ * These are the filters we send to the tail worker. We
+ * actually send a list of filters (an array of objects),
+ * so rather than having a single TailAPIFilters type,
+ * each kind of filter gets its own type and we define
+ * TailAPIFilter to be the union of those types.
+ */
+export type TailAPIFilter =
+  | SamplingRateFilter
+  | OutcomeFilter
+  | MethodFilter
+  | HeaderFilter
+  | ClientIPFilter
+  | QueryFilter;
+
+/**
+ * Filters logs based on a given sampling rate.
+ * For example, a `sampling_rate` of 0.25 will let one-quarter of the
+ * logs through.
+ */
+type SamplingRateFilter = {
+  sampling_rate: number;
+};
+
+/**
+ * Filters logs based on the outcome of the worker's event handler.
+ */
+type OutcomeFilter = {
+  outcome: Outcome[];
+};
+
+/**
+ * There are five possible outcomes we can get, three of which
+ * (exception, exceededCpu, and unknown) are considered errors
+ */
+export type Outcome =
+  | "ok"
+  | "canceled"
+  | "exception"
+  | "exceededCpu"
+  | "unknown";
+
+/**
+ * Filters logs based on the HTTP method used for the request
+ * that triggered the worker.
+ */
+type MethodFilter = {
+  method: string[];
+};
+
+/**
+ * Filters logs based on an HTTP header on the request that
+ * triggered the worker.
+ */
+type HeaderFilter = {
+  header: {
+    /**
+     * Filters on the header "key", e.g. "X-CLOUDFLARE-HEADER"
+     * or "X-CUSTOM-HEADER"
+     */
+    key: string;
+
+    /**
+     * Filters on the header "value", e.g. if this is set to
+     * "filter-for-me" and the "key" is "X-SHOULD-LOG", only
+     * events triggered by requests with the header
+     * "X-SHOULD-LOG:filter-for-me" will be logged.
+     */
+    query?: string;
+  };
+};
+
+/**
+ * Filters on the IP address the request came from that triggered
+ * the worker. A value of "self" will be replaced with the IP
+ * address that is running `wrangler tail`
+ */
+type ClientIPFilter = {
+  client_ip: string[];
+};
+
+/**
+ * Filters logs by a query string. This means only logs that
+ * contain the given string will be sent to wrangler, and any
+ * that don't will be discarded by the tail worker.
+ */
+type QueryFilter = {
+  query: string;
+};
+
+/**
+ * The full message we send to the tail worker includes our
+ * filters and a debug flag.
+ */
+export type TailFilterMessage = {
+  filters: TailAPIFilter[];
+  debug: boolean;
+};
+
+/**
+ * Translate the flags passed in via a CLI invokation of wrangler
+ * into a message that we can send to the tail worker.
+ *
+ * @param cliFilters An object containing all the filters passed in from the CLI
+ * @param debug Whether or not we should be in debug mode
+ * @returns A filter message ready to be sent to the tail worker
+ */
+export function translateCLICommandToFilterMessage(
+  cliFilters: TailCLIFilters,
+  debug: boolean
+): TailFilterMessage {
+  const apiFilters: TailAPIFilter[] = [];
+
+  if (cliFilters.samplingRate) {
+    apiFilters.push(parseSamplingRate(cliFilters.samplingRate));
+  }
+
+  if (cliFilters.status) {
+    apiFilters.push(parseOutcome(cliFilters.status));
+  }
+
+  if (cliFilters.method) {
+    apiFilters.push(parseMethod(cliFilters.method));
+  }
+
+  if (cliFilters.header) {
+    apiFilters.push(parseHeader(cliFilters.header));
+  }
+
+  if (cliFilters.clientIp) {
+    apiFilters.push(parseIP(cliFilters.clientIp));
+  }
+
+  if (cliFilters.search) {
+    apiFilters.push(parseQuery(cliFilters.search));
+  }
+
+  return {
+    filters: apiFilters,
+    debug,
+  };
+}
+
+/**
+ * Parse the sampling rate passed in via command line
+ *
+ * @param sampling_rate the sampling rate passed in via CLI
+ * @throws an Error if the rate doesn't make sense
+ * @returns a SamplingRateFilter for use with the API
+ */
+function parseSamplingRate(sampling_rate: number): SamplingRateFilter {
+  if (sampling_rate <= 0 || sampling_rate >= 1) {
+    throw new Error(
+      "A sampling rate must be between 0 and 1 in order to have any effect.\nFor example, a sampling rate of 0.25 means 25% of events will be logged."
+    );
+  }
+
+  return { sampling_rate };
+}
+
+/**
+ * Translate from CLI "status"es to API "outcome"s, including
+ * broadening "error" into "exception", "exceededCpu", and "unknown".
+ *
+ * @param statuses statuses passed in via CLI
+ * @returns an OutcomeFilter for use with the API
+ */
+function parseOutcome(
+  statuses: ("ok" | "error" | "canceled")[]
+): OutcomeFilter {
+  const outcomes = new Set<Outcome>();
+
+  for (const status of statuses) {
+    switch (status) {
+      case "ok":
+        outcomes.add("ok");
+        break;
+
+      case "canceled":
+        outcomes.add("canceled");
+        break;
+
+      case "error":
+        outcomes.add("exception");
+        outcomes.add("exceededCpu");
+        outcomes.add("unknown");
+        break;
+
+      default:
+        break;
+    }
+  }
+
+  return {
+    outcome: Array.from(outcomes),
+  };
+}
+
+/**
+ * We just send silly methods through to the API anyway, since they don't
+ * cause any harm.
+ *
+ * @param method an array of HTTP request methods passed in via CLI
+ * @returns a MethodFilter for use with the API
+ */
+function parseMethod(method: string[]): MethodFilter {
+  return { method };
+}
+
+/**
+ * Header filters can contain either just a key ("X-HEADER-KEY") or both
+ * a key and a value ("X-HEADER-KEY:some-value"). This function parses
+ * a given string according to that pattern.
+ *
+ * @param header a header string, "X-HEADER-KEY" or "X-HEADER-KEY:some-value"
+ * @returns a HeaderFilter for use with the API
+ */
+function parseHeader(header: string): HeaderFilter {
+  const [headerKey, headerQuery] = header.split(":", 2);
+
+  return {
+    header: {
+      key: headerKey.trim(),
+      query: headerQuery?.trim(),
+    },
+  };
+}
+
+/**
+ * A list of IPs can be passed in to filter for messages that come from
+ * a worker triggered by a request originating from one of those IPs.
+ * You can also pass in the string "self" to filter for the IP of the
+ * machine running `wrangler tail`.
+ *
+ * @param client_ip an array of IP addresses to filter
+ * @returns a ClientIPFilter for use with the API
+ */
+function parseIP(client_ip: string[]): ClientIPFilter {
+  return { client_ip };
+}
+
+/**
+ * Users can filter for logs that contain a "search" or a "query string".
+ * For example, if `--search findme` is passed to then we will only
+ * receive logs that contain the string "findme".
+ *
+ * @param query a query string to search for
+ * @returns a QueryFilter for use with the API
+ */
+function parseQuery(query: string): QueryFilter {
+  return { query };
+}

package/src/tail/index.ts

@@ -0,0 +1,299 @@
+import WebSocket from "ws";
+import { version as packageVersion } from "../../package.json";
+import { fetchResult } from "../cfetch";
+import type { TailFilterMessage, Outcome } from "./filters";
+export type { TailCLIFilters } from "./filters";
+export { translateCLICommandToFilterMessage } from "./filters";
+export { jsonPrintLogs, prettyPrintLogs } from "./printing";
+import type { Request } from "undici";
+
+/**
+ * When creating a Tail, the response from the API contains
+ * - an ID used for identifying the tail
+ * - a URL to a WebSocket connection available for the tail to connect to
+ * - an expiration date when the tail is no longer guaranteed to be valid
+ */
+type TailCreationApiResponse = {
+  id: string;
+  url: string;
+  expires_at: Date;
+};
+
+/**
+ * Generate a URL that, when `cfetch`ed, creates a tail.
+ *
+ * https://api.cloudflare.com/#worker-tail-logs-start-tail
+ *
+ * @param accountId the account ID associated with the worker to tail
+ * @param workerName the name of the worker to tail
+ * @returns a `cfetch`-ready URL for creating a new tail
+ */
+function makeCreateTailUrl(
+  accountId: string,
+  workerName: string,
+  env: string | undefined
+): string {
+  return env
+    ? `/accounts/${accountId}/workers/services/${workerName}/environments/${env}/tails`
+    : `/accounts/${accountId}/workers/scripts/${workerName}/tails`;
+}
+
+/**
+ * Generate a URL that, when `cfetch`ed, deletes a tail
+ *
+ * https://api.cloudflare.com/#worker-tail-logs-delete-tail
+ *
+ * @param accountId the account ID associated with the worker we're tailing
+ * @param workerName the name of the worker we're tailing
+ * @param tailId the ID of the tail we want to delete
+ * @returns a `cfetch`-ready URL for deleting a tail
+ */
+function makeDeleteTailUrl(
+  accountId: string,
+  workerName: string,
+  tailId: string,
+  env: string | undefined
+): string {
+  return env
+    ? `/accounts/${accountId}/workers/services/${workerName}/environments/${env}/tails/${tailId}`
+    : `/accounts/${accountId}/workers/scripts/${workerName}/tails/${tailId}`;
+}
+
+/**
+ * Create and connect to a tail.
+ *
+ * Under the hood, this function
+ * - Registers a new Tail with the API
+ * - Connects to the tail worker
+ * - Sends any filters over the connection
+ *
+ * @param accountId the account ID associated with the worker to tail
+ * @param workerName the name of the worker to tail
+ * @param message a `TailFilterMessage` to send up to the tail worker
+ * @returns a websocket connection, an expiration, and a function to call to delete the tail
+ */
+export async function createTail(
+  accountId: string,
+  workerName: string,
+  message: TailFilterMessage,
+  env: string | undefined
+): Promise<{
+  tail: WebSocket;
+  expiration: Date;
+  deleteTail: () => Promise<void>;
+}> {
+  // create the tail
+  const createTailUrl = makeCreateTailUrl(accountId, workerName, env);
+  const {
+    id: tailId,
+    url: websocketUrl,
+    expires_at: expiration,
+  } = await fetchResult<TailCreationApiResponse>(createTailUrl, {
+    method: "POST",
+  });
+
+  // delete the tail (not yet!)
+  const deleteUrl = makeDeleteTailUrl(accountId, workerName, tailId, env);
+  async function deleteTail() {
+    await fetchResult(deleteUrl, { method: "DELETE" });
+  }
+
+  // connect to the tail
+  const tail = new WebSocket(websocketUrl, "trace-v1", {
+    headers: {
+      "Sec-WebSocket-Protocol": "trace-v1", // needs to be `trace-v1` to be accepted
+      "User-Agent": `wrangler-js/${packageVersion}`,
+    },
+  });
+
+  // send filters when we open up
+  tail.on("open", function () {
+    tail.send(
+      JSON.stringify(message),
+      { binary: false, compress: false, mask: false, fin: true },
+      (err) => {
+        if (err) {
+          throw err;
+        }
+      }
+    );
+  });
+
+  return { tail, expiration, deleteTail };
+}
+
+/**
+ * Everything captured by the trace worker and sent to us via
+ * `wrangler tail` is structured JSON that deserializes to this type.
+ */
+export type TailEventMessage = {
+  /**
+   * Whether the execution of this worker succeeded or failed
+   */
+  outcome: Outcome;
+
+  /**
+   * The name of the script we're tailing
+   */
+  scriptName?: string;
+
+  /**
+   * Any exceptions raised by the worker
+   */
+  exceptions: {
+    /**
+     * The name of the exception.
+     */
+    name: string;
+
+    /**
+     * The error message
+     */
+    message: unknown;
+
+    /**
+     * When the exception was raised/thrown
+     */
+    timestamp: number;
+  }[];
+
+  /**
+   * Any logs sent out by the worker
+   */
+  logs: {
+    message: unknown;
+    level: string; // TODO: make this a union of possible values
+    timestamp: number;
+  }[];
+
+  /**
+   * When the event was triggered
+   */
+  eventTimestamp: number;
+
+  /**
+   * The event that triggered the worker. In the case of an HTTP request,
+   * this will be a RequestEvent. If it's a cron trigger, it'll be a
+   * ScheduledEvent.
+   *
+   * Until workers-types exposes individual types for export, we'll have
+   * to just re-define these types ourselves.
+   */
+  event: RequestEvent | ScheduledEvent;
+};
+
+/**
+ * A request that triggered worker execution
+ */
+
+export type RequestEvent = {
+  request: Pick<Request, "url" | "method" | "headers"> & {
+    /**
+     * Cloudflare-specific properties
+     * https://developers.cloudflare.com/workers/runtime-apis/request#incomingrequestcfproperties
+     */
+    cf: {
+      /**
+       * How long (in ms) it took for the client's TCP connection to make a
+       * round trip to the worker and back. For all my gamers out there,
+       * this is the request's ping
+       */
+      clientTcpRtt?: number;
+
+      /**
+       * Longitude and Latitude of where the request originated from
+       */
+      longitude?: string;
+      latitude?: string;
+
+      /**
+       * What cipher was used to establish the TLS connection
+       */
+      tlsCipher: string;
+
+      /**
+       * Which continent the request came from.
+       */
+      continent?: "NA";
+
+      /**
+       * ASN of the incoming request
+       */
+      asn: number;
+
+      /**
+       * The country the incoming request is coming from
+       */
+      country?: string;
+
+      /**
+       * The TLS version the connection used
+       */
+      tlsVersion: string;
+
+      /**
+       * The colo that processed the request (i.e. the airport code
+       * of the closest city to the server that spun up the worker)
+       */
+      colo: string;
+
+      /**
+       * The timezone where the request came from
+       */
+      timezone?: string;
+
+      /**
+       * The city where the request came from
+       */
+      city?: string;
+
+      /**
+       * The browser-requested prioritization information in the request object
+       */
+      requestPriority?: string;
+
+      /**
+       * Which version of HTTP the request came over e.g. "HTTP/2"
+       */
+      httpProtocol: string;
+
+      /**
+       * The region where the request originated from
+       */
+      region?: string;
+      regionCode?: string;
+
+      /**
+       * The organization which owns the ASN of the incoming request, for example, Google Cloud.
+       */
+      asOrganization: string;
+
+      /**
+       * Metro code (DMA) of the incoming request, for example, "635".
+       */
+      metroCode?: string;
+
+      /**
+       * Postal code of the incoming request, for example, "78701".
+       */
+      postalCode?: string;
+    };
+  };
+};
+
+/**
+ * An event that was triggered at a certain time
+ */
+export type ScheduledEvent = {
+  /**
+   * The cron pattern that matched when this event fired
+   */
+  cron: string;
+
+  /**
+   * The time this worker was scheduled to run.
+   * For some reason, this doesn't...work correctly when we
+   * do it directly as a Date. So parse it later on your own.
+   */
+  scheduledTime: number;
+};

package/src/tail/printing.ts

@@ -0,0 +1,62 @@
+import type { RequestEvent, ScheduledEvent, TailEventMessage } from ".";
+import type { Outcome } from "./filters";
+import type WebSocket from "ws";
+
+export function prettyPrintLogs(data: WebSocket.RawData): void {
+  const eventMessage: TailEventMessage = JSON.parse(data.toString());
+
+  if (isScheduledEvent(eventMessage.event)) {
+    const cronPattern = eventMessage.event.cron;
+    const datetime = new Date(
+      eventMessage.event.scheduledTime
+    ).toLocaleString();
+    const outcome = prettifyOutcome(eventMessage.outcome);
+
+    console.log(`"${cronPattern}" @ ${datetime} - ${outcome}`);
+  } else {
+    const requestMethod = eventMessage.event.request.method.toUpperCase();
+    const url = eventMessage.event.request.url;
+    const outcome = prettifyOutcome(eventMessage.outcome);
+    const datetime = new Date(eventMessage.eventTimestamp).toLocaleString();
+
+    console.log(`${requestMethod} ${url} - ${outcome} @ ${datetime}`);
+  }
+
+  if (eventMessage.logs.length > 0) {
+    eventMessage.logs.forEach(({ level, message }) => {
+      console.log(`  (${level}) ${message}`);
+    });
+  }
+
+  if (eventMessage.exceptions.length > 0) {
+    eventMessage.exceptions.forEach(({ name, message }) => {
+      console.error(`  ${name}: ${message}`);
+    });
+  }
+}
+
+export function jsonPrintLogs(data: WebSocket.RawData): void {
+  console.log(JSON.stringify(JSON.parse(data.toString()), null, 2));
+}
+
+function isScheduledEvent(
+  event: RequestEvent | ScheduledEvent
+): event is ScheduledEvent {
+  return "cron" in event;
+}
+
+function prettifyOutcome(outcome: Outcome): string {
+  switch (outcome) {
+    case "ok":
+      return "Ok";
+    case "canceled":
+      return "Canceled";
+    case "exceededCpu":
+      return "Exceeded CPU Limit";
+    case "exception":
+      return "Exception Thrown";
+    case "unknown":
+    default:
+      return "Unknown";
+  }
+}