wrangler 2.20.0 → 3.0.0

package/src/tail/createTail.ts

@@ -1,415 +0,0 @@
-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.
-	 * If it's a email, it'a an EmailEvent
-	 *
-	 * Until workers-types exposes individual types for export, we'll have
-	 * to just re-define these types ourselves.
-	 */
-	event:
-		| RequestEvent
-		| ScheduledEvent
-		| AlarmEvent
-		| EmailEvent
-		| TailInfo
-		| 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;
-};
-
-/**
- * An event that was triggered from an email
- */
-export type EmailEvent = {
-	/**
-	 * Who sent the email
-	 */
-	mailFrom: string;
-
-	/**
-	 * Who was the email sent to
-	 */
-	rcptTo: string;
-
-	/**
-	 * Size of the email in bytes
-	 */
-	rawSize: number;
-};
-
-/**
- * Message from tail with information about the tail itself
- */
-export type TailInfo = {
-	message: string;
-	type: string;
-};

package/src/tail/filters.ts

@@ -1,277 +0,0 @@
-/**
- * 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 v1 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 };
-}