wrangler 0.0.0-e64812e → 0.0.0-e7a0cd5b

package/src/tail/createTail.ts

@@ -0,0 +1,315 @@
+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 filters A list of `TailAPIFilters` given to the tail
+ * @param debug Flag to run tail in debug mode
+ * @returns a websocket connection, an expiration, and a function to call to delete the tail
+ */
+export async function createTail(
+	accountId: string,
+	workerName: string,
+	filters: TailFilterMessage,
+	debug: boolean,
+	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",
+		body: JSON.stringify(filters),
+	});
+
+	// 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({ debug: debug }),
+			{ 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. If it's a durable object alarm, it's an AlarmEvent.
+	 *
+	 * Until workers-types exposes individual types for export, we'll have
+	 * to just re-define these types ourselves.
+	 */
+	event: RequestEvent | ScheduledEvent | AlarmEvent | undefined | null;
+};
+
+/**
+ * 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;
+};
+
+/**
+ * A event that was triggered from a durable object alarm
+ */
+export type AlarmEvent = {
+	/**
+	 * The datetime the alarm was scheduled for.
+	 *
+	 * This is sent as an ISO timestamp string (different than ScheduledEvent.scheduledTime),
+	 * you should parse it later on on your own.
+	 */
+	scheduledTime: string;
+};

package/src/tail/filters.ts

@@ -17,12 +17,12 @@
  * 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[];
+	status?: ("ok" | "error" | "canceled")[];
+	header?: string;
+	method?: string[];
+	search?: string;
+	samplingRate?: number;
+	clientIp?: string[];
 };
 
 /**
@@ -33,12 +33,12 @@ export type TailCLIFilters = {
  * TailAPIFilter to be the union of those types.
  */
 export type TailAPIFilter =
-  | SamplingRateFilter
-  | OutcomeFilter
-  | MethodFilter
-  | HeaderFilter
-  | ClientIPFilter
-  | QueryFilter;
+	| SamplingRateFilter
+	| OutcomeFilter
+	| MethodFilter
+	| HeaderFilter
+	| ClientIPFilter
+	| QueryFilter;
 
 /**
  * Filters logs based on a given sampling rate.
@@ -46,33 +46,34 @@ export type TailAPIFilter =
  * logs through.
  */
 type SamplingRateFilter = {
-  sampling_rate: number;
+	sampling_rate: number;
 };
 
 /**
  * Filters logs based on the outcome of the worker's event handler.
  */
 type OutcomeFilter = {
-  outcome: Outcome[];
+	outcome: Outcome[];
 };
 
 /**
  * There are five possible outcomes we can get, three of which
- * (exception, exceededCpu, and unknown) are considered errors
+ * (exception, exceededCpu, exceededMemory, and unknown) are considered errors
  */
 export type Outcome =
-  | "ok"
-  | "canceled"
-  | "exception"
-  | "exceededCpu"
-  | "unknown";
+	| "ok"
+	| "canceled"
+	| "exception"
+	| "exceededCpu"
+	| "exceededMemory"
+	| "unknown";
 
 /**
  * Filters logs based on the HTTP method used for the request
  * that triggered the worker.
  */
 type MethodFilter = {
-  method: string[];
+	method: string[];
 };
 
 /**
@@ -80,21 +81,21 @@ type MethodFilter = {
  * 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;
-  };
+	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;
+	};
 };
 
 /**
@@ -103,7 +104,7 @@ type HeaderFilter = {
  * address that is running `wrangler tail`
  */
 type ClientIPFilter = {
-  client_ip: string[];
+	client_ip: string[];
 };
 
 /**
@@ -112,7 +113,7 @@ type ClientIPFilter = {
  * that don't will be discarded by the tail worker.
  */
 type QueryFilter = {
-  query: string;
+	query: string;
 };
 
 /**
@@ -120,8 +121,7 @@ type QueryFilter = {
  * filters and a debug flag.
  */
 export type TailFilterMessage = {
-  filters: TailAPIFilter[];
-  debug: boolean;
+	filters: TailAPIFilter[];
 };
 
 /**
@@ -129,43 +129,40 @@ export type TailFilterMessage = {
  * 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
+	cliFilters: TailCLIFilters
 ): TailFilterMessage {
-  const apiFilters: TailAPIFilter[] = [];
+	const apiFilters: TailAPIFilter[] = [];
 
-  if (cliFilters.samplingRate) {
-    apiFilters.push(parseSamplingRate(cliFilters.samplingRate));
-  }
+	if (cliFilters.samplingRate) {
+		apiFilters.push(parseSamplingRate(cliFilters.samplingRate));
+	}
 
-  if (cliFilters.status) {
-    apiFilters.push(parseOutcome(cliFilters.status));
-  }
+	if (cliFilters.status) {
+		apiFilters.push(parseOutcome(cliFilters.status));
+	}
 
-  if (cliFilters.method) {
-    apiFilters.push(parseMethod(cliFilters.method));
-  }
+	if (cliFilters.method) {
+		apiFilters.push(parseMethod(cliFilters.method));
+	}
 
-  if (cliFilters.header) {
-    apiFilters.push(parseHeader(cliFilters.header));
-  }
+	if (cliFilters.header) {
+		apiFilters.push(parseHeader(cliFilters.header));
+	}
 
-  if (cliFilters.clientIp) {
-    apiFilters.push(parseIP(cliFilters.clientIp));
-  }
+	if (cliFilters.clientIp) {
+		apiFilters.push(parseIP(cliFilters.clientIp));
+	}
 
-  if (cliFilters.search) {
-    apiFilters.push(parseQuery(cliFilters.search));
-  }
+	if (cliFilters.search) {
+		apiFilters.push(parseQuery(cliFilters.search));
+	}
 
-  return {
-    filters: apiFilters,
-    debug,
-  };
+	return {
+		filters: apiFilters,
+	};
 }
 
 /**
@@ -176,13 +173,13 @@ export function translateCLICommandToFilterMessage(
  * @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."
-    );
-  }
+	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 };
+	return { sampling_rate };
 }
 
 /**
@@ -193,34 +190,35 @@ function parseSamplingRate(sampling_rate: number): SamplingRateFilter {
  * @returns an OutcomeFilter for use with the API
  */
 function parseOutcome(
-  statuses: ("ok" | "error" | "canceled")[]
+	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),
-  };
+	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("exceededMemory");
+				outcomes.add("unknown");
+				break;
+
+			default:
+				break;
+		}
+	}
+
+	return {
+		outcome: Array.from(outcomes),
+	};
 }
 
 /**
@@ -231,7 +229,7 @@ function parseOutcome(
  * @returns a MethodFilter for use with the API
  */
 function parseMethod(method: string[]): MethodFilter {
-  return { method };
+	return { method };
 }
 
 /**
@@ -243,14 +241,14 @@ function parseMethod(method: string[]): MethodFilter {
  * @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(),
-    },
-  };
+	const [headerKey, headerQuery] = header.split(":", 2);
+
+	return {
+		header: {
+			key: headerKey.trim(),
+			query: headerQuery?.trim(),
+		},
+	};
 }
 
 /**
@@ -263,7 +261,7 @@ function parseHeader(header: string): HeaderFilter {
  * @returns a ClientIPFilter for use with the API
  */
 function parseIP(client_ip: string[]): ClientIPFilter {
-  return { client_ip };
+	return { client_ip };
 }
 
 /**
@@ -275,5 +273,5 @@ function parseIP(client_ip: string[]): ClientIPFilter {
  * @returns a QueryFilter for use with the API
  */
 function parseQuery(query: string): QueryFilter {
-  return { query };
+	return { query };
 }