wrangler 0.0.0-e928f94 → 0.0.0-e93063e9

package/src/tail/createTail.ts

@@ -0,0 +1,379 @@
+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";
+
+const TRACE_VERSION = "trace-v1";
+
+/**
+ * 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}`;
+}
+
+interface CreatePagesTailOptions {
+	accountId: string;
+	projectName: string;
+	deploymentId: string;
+	filters: TailFilterMessage;
+	debug?: boolean;
+}
+
+/**
+ * Create and connect to a Pages Function Tail.
+ *
+ * Under the hood, this function
+ * - Registers a new Tail with the API
+ * - Connects to the tail worker
+ * - Sends any filters over the connection
+ *
+ * @returns a websocket connection, an expiration, and a function to call to delete the tail
+ */
+export async function createPagesTail({
+	accountId,
+	projectName,
+	deploymentId,
+	filters,
+	debug = false,
+}: CreatePagesTailOptions) {
+	const tailRecord = await fetchResult<TailCreationApiResponse>(
+		`/accounts/${accountId}/pages/projects/${projectName}/deployments/${deploymentId}/tails`,
+		{
+			method: "POST",
+			body: JSON.stringify(filters),
+		}
+	);
+
+	const deleteTail = async () =>
+		fetchResult(
+			`/accounts/${accountId}/pages/projects/${projectName}/deployments/${deploymentId}/tails/${tailRecord.id}`,
+			{ method: "DELETE" }
+		);
+
+	const tail = new WebSocket(tailRecord.url, TRACE_VERSION, {
+		headers: {
+			"Sec-WebSocket-Protocol": TRACE_VERSION, // needs to be `trace-v1` to be accepted
+			"User-Agent": `wrangler-js/${packageVersion}`,
+		},
+	});
+
+	// send filters when we open up
+	tail.on("open", () => {
+		tail.send(
+			JSON.stringify({ debug: debug }),
+			{ binary: false, compress: false, mask: false, fin: true },
+			(err) => {
+				if (err) {
+					throw err;
+				}
+			}
+		);
+	});
+
+	return { tail, deleteTail, expiration: tailRecord.expires_at };
+}
+
+/**
+ * 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_VERSION, {
+		headers: {
+			"Sec-WebSocket-Protocol": TRACE_VERSION, // 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

@@ -0,0 +1,277 @@
+/**
+ * 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, exceededMemory, and unknown) are considered errors
+ */
+export type Outcome =
+	| "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[];
+};
+
+/**
+ * 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[];
+};
+
+/**
+ * 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
+ * @returns A filter message ready to be sent to the tail worker
+ */
+export function translateCLICommandToFilterMessage(
+	cliFilters: TailCLIFilters
+): 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,
+	};
+}
+
+/**
+ * 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("exceededMemory");
+				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 };
+}