@cloudflare/pages-shared 0.0.1 → 0.0.4

package/src/asset-server/responses.ts

@@ -0,0 +1,152 @@
+type HeadersInit = ConstructorParameters<typeof Headers>[0];
+
+function mergeHeaders(base: HeadersInit, extra: HeadersInit) {
+	base = new Headers(base ?? {});
+	extra = new Headers(extra ?? {});
+
+	return new Headers({
+		...Object.fromEntries(base.entries()),
+		...Object.fromEntries(extra.entries()),
+	});
+}
+
+export class OkResponse extends Response {
+	constructor(...[body, init]: ConstructorParameters<typeof Response>) {
+		super(body, {
+			...init,
+			status: 200,
+			statusText: "OK",
+		});
+	}
+}
+
+export class MovedPermanentlyResponse extends Response {
+	constructor(
+		location: string,
+		init?: ConstructorParameters<typeof Response>[1]
+	) {
+		super(`Redirecting to ${location}`, {
+			...init,
+			status: 301,
+			statusText: "Moved Permanently",
+			headers: mergeHeaders(init?.headers, {
+				location,
+			}),
+		});
+	}
+}
+
+export class FoundResponse extends Response {
+	constructor(
+		location: string,
+		init?: ConstructorParameters<typeof Response>[1]
+	) {
+		super(`Redirecting to ${location}`, {
+			...init,
+			status: 302,
+			statusText: "Found",
+			headers: mergeHeaders(init?.headers, {
+				location,
+			}),
+		});
+	}
+}
+
+export class NotModifiedResponse extends Response {
+	constructor(...[_body, _init]: ConstructorParameters<typeof Response>) {
+		super(undefined, {
+			status: 304,
+			statusText: "Not Modified",
+		});
+	}
+}
+
+export class PermanentRedirectResponse extends Response {
+	constructor(
+		location: string,
+		init?: ConstructorParameters<typeof Response>[1]
+	) {
+		super(undefined, {
+			...init,
+			status: 308,
+			statusText: "Permanent Redirect",
+			headers: mergeHeaders(init?.headers, {
+				location,
+			}),
+		});
+	}
+}
+
+export class NotFoundResponse extends Response {
+	constructor(...[body, init]: ConstructorParameters<typeof Response>) {
+		super(body, {
+			...init,
+			status: 404,
+			statusText: "Not Found",
+		});
+	}
+}
+
+export class MethodNotAllowedResponse extends Response {
+	constructor(...[body, init]: ConstructorParameters<typeof Response>) {
+		super(body, {
+			...init,
+			status: 405,
+			statusText: "Method Not Allowed",
+		});
+	}
+}
+
+export class NotAcceptableResponse extends Response {
+	constructor(...[body, init]: ConstructorParameters<typeof Response>) {
+		super(body, {
+			...init,
+			status: 406,
+			statusText: "Not Acceptable",
+		});
+	}
+}
+
+export class InternalServerErrorResponse extends Response {
+	constructor(err: Error, init?: ConstructorParameters<typeof Response>[1]) {
+		let body: string | undefined = undefined;
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		if ((globalThis as any).DEBUG) {
+			body = `${err.message}\n\n${err.stack}`;
+		}
+
+		super(body, {
+			...init,
+			status: 500,
+			statusText: "Internal Server Error",
+		});
+	}
+}
+
+export class SeeOtherResponse extends Response {
+	constructor(
+		location: string,
+		init?: ConstructorParameters<typeof Response>[1]
+	) {
+		super(`Redirecting to ${location}`, {
+			...init,
+			status: 303,
+			statusText: "See Other",
+			headers: mergeHeaders(init?.headers, { location }),
+		});
+	}
+}
+
+export class TemporaryRedirectResponse extends Response {
+	constructor(
+		location: string,
+		init?: ConstructorParameters<typeof Response>[1]
+	) {
+		super(`Redirecting to ${location}`, {
+			...init,
+			status: 307,
+			statusText: "Temporary Redirect",
+			headers: mergeHeaders(init?.headers, { location }),
+		});
+	}
+}

package/src/asset-server/rulesEngine.ts

@@ -0,0 +1,82 @@
+// Taken from https://stackoverflow.com/a/3561711
+// which is everything from the tc39 proposal, plus the following two characters: ^/
+// It's also everything included in the URLPattern escape (https://wicg.github.io/urlpattern/#escape-a-regexp-string), plus the following: -
+// As the answer says, there's no downside to escaping these extra characters, so better safe than sorry
+const ESCAPE_REGEX_CHARACTERS = /[-/\\^$*+?.()|[\]{}]/g;
+const escapeRegex = (str: string) => {
+	return str.replace(ESCAPE_REGEX_CHARACTERS, "\\$&");
+};
+
+// Placeholder names must begin with a colon, be alphanumeric and optionally contain underscores.
+// e.g. :place_123_holder
+const HOST_PLACEHOLDER_REGEX = /(?<=^https:\\\/\\\/[^/]*?):([^\\]+)(?=\\)/g;
+const PLACEHOLDER_REGEX = /:(\w+)/g;
+
+export type Replacements = Record<string, string>;
+
+export type Removals = string[];
+
+export const replacer = (str: string, replacements: Replacements) => {
+	for (const [replacement, value] of Object.entries(replacements)) {
+		str = str.replaceAll(`:${replacement}`, value);
+	}
+	return str;
+};
+
+export const generateRulesMatcher = <T>(
+	rules?: Record<string, T>,
+	replacerFn: (match: T, replacements: Replacements) => T = (match) => match
+) => {
+	if (!rules) return () => [];
+
+	const compiledRules = Object.entries(rules)
+		.map(([rule, match]) => {
+			const crossHost = rule.startsWith("https://");
+
+			// Create :splat capturer then escape.
+			rule = rule.split("*").map(escapeRegex).join("(?<splat>.*)");
+
+			// Create :placeholder capturers (already escaped).
+			// For placeholders in the host, we separate at forward slashes and periods.
+			// For placeholders in the path, we separate at forward slashes.
+			// This matches the behavior of URLPattern.
+			// e.g. https://:subdomain.domain/ -> https://(here).domain/
+			// e.g. /static/:file -> /static/(image.jpg)
+			// e.g. /blog/:post -> /blog/(an-exciting-post)
+			const host_matches = rule.matchAll(HOST_PLACEHOLDER_REGEX);
+			for (const host_match of host_matches) {
+				rule = rule.split(host_match[0]).join(`(?<${host_match[1]}>[^/.]+)`);
+			}
+
+			const path_matches = rule.matchAll(PLACEHOLDER_REGEX);
+			for (const path_match of path_matches) {
+				rule = rule.split(path_match[0]).join(`(?<${path_match[1]}>[^/]+)`);
+			}
+
+			// Wrap in line terminators to be safe.
+			rule = "^" + rule + "$";
+
+			try {
+				const regExp = new RegExp(rule);
+				return [{ crossHost, regExp }, match];
+			} catch {}
+		})
+		.filter((value) => value !== undefined) as [
+		{ crossHost: boolean; regExp: RegExp },
+		T
+	][];
+
+	return ({ request }: { request: Request }) => {
+		const { pathname, host } = new URL(request.url);
+
+		return compiledRules
+			.map(([{ crossHost, regExp }, match]) => {
+				const test = crossHost ? `https://${host}${pathname}` : pathname;
+				const result = regExp.exec(test);
+				if (result) {
+					return replacerFn(match, result.groups || {});
+				}
+			})
+			.filter((value) => value !== undefined) as T[];
+	};
+};

package/src/environment-polyfills/index.ts

@@ -0,0 +1,14 @@
+import type { PolyfilledRuntimeEnvironment } from "./types";
+
+export const polyfill = (
+	environment: Record<keyof PolyfilledRuntimeEnvironment, unknown>
+) => {
+	Object.entries(environment).map(([name, value]) => {
+		Object.defineProperty(globalThis, name, {
+			value,
+			configurable: true,
+			enumerable: true,
+			writable: true,
+		});
+	});
+};

package/src/environment-polyfills/miniflare.ts

@@ -0,0 +1,14 @@
+import {
+	fetch as miniflareFetch,
+	Headers as MiniflareHeaders,
+	Request as MiniflareRequest,
+	Response as MiniflareResponse,
+} from "@miniflare/core";
+import { polyfill } from ".";
+
+polyfill({
+	fetch: miniflareFetch,
+	Headers: MiniflareHeaders,
+	Request: MiniflareRequest,
+	Response: MiniflareResponse,
+});

package/src/environment-polyfills/types.ts

@@ -0,0 +1,44 @@
+import {
+	Headers as MiniflareHeaders,
+	Request as MiniflareRequest,
+	Response as MiniflareResponse,
+} from "@miniflare/core";
+import { HTMLRewriter as MiniflareHTMLRewriter } from "@miniflare/html-rewriter";
+import type { CacheInterface as MiniflareCacheInterface } from "@miniflare/cache";
+import type { fetch as miniflareFetch } from "@miniflare/core";
+import type { ReadableStream as SimilarReadableStream } from "stream/web";
+
+declare global {
+	const fetch: typeof miniflareFetch;
+	class Headers extends MiniflareHeaders {}
+	class Request extends MiniflareRequest {}
+	class Response extends MiniflareResponse {}
+
+	type CacheInterface = Omit<MiniflareCacheInterface, "match"> & {
+		match(
+			...args: Parameters<MiniflareCacheInterface["match"]>
+		): Promise<Response | undefined>;
+	};
+
+	class CacheStorage {
+		get default(): CacheInterface;
+		open(cacheName: string): Promise<CacheInterface>;
+	}
+
+	class HTMLRewriter extends MiniflareHTMLRewriter {
+		// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+		// @ts-ignore
+		transform(response: Response): Response;
+	}
+
+	type ReadableStream = SimilarReadableStream;
+}
+
+export type PolyfilledRuntimeEnvironment = {
+	fetch: typeof fetch;
+	Headers: typeof Headers;
+	Request: typeof Request;
+	Response: typeof Response;
+};
+
+export { fetch, Headers, Request, Response };

package/src/index.ts

@@ -0,0 +1 @@
+export {};

package/src/metadata-generator/constants.ts

@@ -0,0 +1,15 @@
+export const REDIRECTS_VERSION = 1;
+export const HEADERS_VERSION = 2;
+export const ANALYTICS_VERSION = 1;
+export const ROUTES_JSON_VERSION = 1;
+
+export const PERMITTED_STATUS_CODES = new Set([301, 302, 303, 307, 308]);
+export const HEADER_SEPARATOR = ":";
+export const MAX_LINE_LENGTH = 2000;
+export const MAX_HEADER_RULES = 100;
+export const MAX_DYNAMIC_REDIRECT_RULES = 100;
+export const MAX_STATIC_REDIRECT_RULES = 2000;
+export const UNSET_OPERATOR = "! ";
+
+export const SPLAT_REGEX = /\*/g;
+export const PLACEHOLDER_REGEX = /:\w+/g;

package/src/metadata-generator/createMetadataObject.ts

@@ -0,0 +1,156 @@
+import {
+	ANALYTICS_VERSION,
+	REDIRECTS_VERSION,
+	HEADERS_VERSION,
+	SPLAT_REGEX,
+	PLACEHOLDER_REGEX,
+} from "./constants";
+import type {
+	Metadata,
+	MetadataRedirects,
+	MetadataHeaders,
+	ParsedRedirects,
+	ParsedHeaders,
+	Logger,
+} from "./types";
+
+export function createMetadataObject({
+	redirects,
+	headers,
+	webAnalyticsToken,
+	deploymentId,
+	logger = (_message: string) => {},
+}: {
+	redirects?: ParsedRedirects;
+	headers?: ParsedHeaders;
+	webAnalyticsToken?: string;
+	deploymentId?: string;
+	logger?: Logger;
+}): Metadata {
+	return {
+		...constructRedirects({ redirects, logger }),
+		...constructHeaders({ headers, logger }),
+		...constructWebAnalytics({ webAnalyticsToken, logger }),
+		deploymentId,
+	};
+}
+
+function constructRedirects({
+	redirects,
+	logger,
+}: {
+	redirects?: ParsedRedirects;
+	logger: Logger;
+}): Metadata {
+	if (!redirects) return {};
+
+	const num_valid = redirects.rules.length;
+	const num_invalid = redirects.invalid.length;
+
+	logger(
+		`Parsed ${num_valid} valid redirect rule${num_valid === 1 ? "" : "s"}.`
+	);
+
+	if (num_invalid > 0) {
+		logger(`Found invalid redirect lines:`);
+		for (const { line, lineNumber, message } of redirects.invalid) {
+			if (line) logger(`  - ${lineNumber ? `#${lineNumber}: ` : ""}${line}`);
+			logger(`    ${message}`);
+		}
+	}
+
+	/* Better to return no Redirects object at all than one with empty rules */
+	if (num_valid === 0) {
+		return {};
+	}
+
+	const staticRedirects: MetadataRedirects = {};
+	const dynamicRedirects: MetadataRedirects = {};
+	let canCreateStaticRule = true;
+	for (const rule of redirects.rules) {
+		if (!rule.from.match(SPLAT_REGEX) && !rule.from.match(PLACEHOLDER_REGEX)) {
+			if (canCreateStaticRule) {
+				staticRedirects[rule.from] = { status: rule.status, to: rule.to };
+				continue;
+			} else {
+				logger(
+					`Info: the redirect rule ${rule.from} → ${rule.status} ${rule.to} could be made more performant by bringing it above any lines with splats or placeholders.`
+				);
+			}
+		}
+
+		dynamicRedirects[rule.from] = { status: rule.status, to: rule.to };
+		canCreateStaticRule = false;
+	}
+
+	return {
+		redirects: {
+			version: REDIRECTS_VERSION,
+			staticRules: staticRedirects,
+			rules: dynamicRedirects,
+		},
+	};
+}
+
+function constructHeaders({
+	headers,
+	logger,
+}: {
+	headers?: ParsedHeaders;
+	logger: Logger;
+}): Metadata {
+	if (!headers) return {};
+
+	const num_valid = headers.rules.length;
+	const num_invalid = headers.invalid.length;
+
+	logger(`Parsed ${num_valid} valid header rule${num_valid === 1 ? "" : "s"}.`);
+
+	if (num_invalid > 0) {
+		logger(`Found invalid header lines:`);
+		for (const { line, lineNumber, message } of headers.invalid) {
+			if (line) logger(`  - ${lineNumber ? `#${lineNumber}: ` : ""} ${line}`);
+			logger(`    ${message}`);
+		}
+	}
+
+	/* Better to return no Headers object at all than one with empty rules */
+	if (num_valid === 0) {
+		return {};
+	}
+
+	const rules: MetadataHeaders = {};
+	for (const rule of headers.rules) {
+		rules[rule.path] = {};
+
+		if (Object.keys(rule.headers).length) {
+			rules[rule.path].set = rule.headers;
+		}
+		if (rule.unsetHeaders.length) {
+			rules[rule.path].unset = rule.unsetHeaders;
+		}
+	}
+
+	return {
+		headers: {
+			version: HEADERS_VERSION,
+			rules,
+		},
+	};
+}
+
+function constructWebAnalytics({
+	webAnalyticsToken,
+}: {
+	webAnalyticsToken?: string;
+	logger: Logger;
+}) {
+	if (!webAnalyticsToken) return {};
+
+	return {
+		analytics: {
+			version: ANALYTICS_VERSION,
+			token: webAnalyticsToken,
+		},
+	};
+}

package/src/metadata-generator/parseHeaders.ts

@@ -0,0 +1,168 @@
+import {
+	MAX_LINE_LENGTH,
+	MAX_HEADER_RULES,
+	HEADER_SEPARATOR,
+	UNSET_OPERATOR,
+} from "./constants";
+import { validateUrl } from "./validateURL";
+import type { InvalidHeadersRule, ParsedHeaders, HeadersRule } from "./types";
+
+// Not strictly necessary to check for all protocols-like beginnings, since _technically_ that could be a legit header (e.g. name=http, value=://I'm a value).
+// But we're checking here since some people might be caught out and it'll help 99.9% of people who get it wrong.
+// We do the proper validation in `validateUrl` anyway :)
+const LINE_IS_PROBABLY_A_PATH = new RegExp(/^([^\s]+:\/\/|^\/)/);
+
+export function parseHeaders(input: string): ParsedHeaders {
+	const lines = input.split("\n");
+	const rules: HeadersRule[] = [];
+	const invalid: InvalidHeadersRule[] = [];
+
+	let rule: (HeadersRule & { line: string }) | undefined = undefined;
+
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i].trim();
+		if (line.length === 0 || line.startsWith("#")) continue;
+
+		if (line.length > MAX_LINE_LENGTH) {
+			invalid.push({
+				message: `Ignoring line ${
+					i + 1
+				} as it exceeds the maximum allowed length of ${MAX_LINE_LENGTH}.`,
+			});
+			continue;
+		}
+
+		if (LINE_IS_PROBABLY_A_PATH.test(line)) {
+			if (rules.length >= MAX_HEADER_RULES) {
+				invalid.push({
+					message: `Maximum number of rules supported is ${MAX_HEADER_RULES}. Skipping remaining ${
+						lines.length - i
+					} lines of file.`,
+				});
+				break;
+			}
+
+			if (rule) {
+				if (isValidRule(rule)) {
+					rules.push({
+						path: rule.path,
+						headers: rule.headers,
+						unsetHeaders: rule.unsetHeaders,
+					});
+				} else {
+					invalid.push({
+						line: rule.line,
+						lineNumber: i + 1,
+						message: "No headers specified",
+					});
+				}
+			}
+
+			const [path, pathError] = validateUrl(line);
+			if (pathError) {
+				invalid.push({
+					line,
+					lineNumber: i + 1,
+					message: pathError,
+				});
+				rule = undefined;
+				continue;
+			}
+
+			rule = {
+				path: path as string,
+				line,
+				headers: {},
+				unsetHeaders: [],
+			};
+			continue;
+		}
+
+		if (!line.includes(HEADER_SEPARATOR)) {
+			if (!rule) {
+				invalid.push({
+					line,
+					lineNumber: i + 1,
+					message: "Expected a path beginning with at least one forward-slash",
+				});
+			} else {
+				if (line.trim().startsWith(UNSET_OPERATOR)) {
+					rule.unsetHeaders.push(line.trim().replace(UNSET_OPERATOR, ""));
+				} else {
+					invalid.push({
+						line,
+						lineNumber: i + 1,
+						message:
+							"Expected a colon-separated header pair (e.g. name: value)",
+					});
+				}
+			}
+			continue;
+		}
+
+		const [rawName, ...rawValue] = line.split(HEADER_SEPARATOR);
+		const name = rawName.trim().toLowerCase();
+
+		if (name.includes(" ")) {
+			invalid.push({
+				line,
+				lineNumber: i + 1,
+				message: "Header name cannot include spaces",
+			});
+			continue;
+		}
+
+		const value = rawValue.join(HEADER_SEPARATOR).trim();
+
+		if (name === "") {
+			invalid.push({
+				line,
+				lineNumber: i + 1,
+				message: "No header name specified",
+			});
+			continue;
+		}
+
+		if (value === "") {
+			invalid.push({
+				line,
+				lineNumber: i + 1,
+				message: "No header value specified",
+			});
+			continue;
+		}
+
+		if (!rule) {
+			invalid.push({
+				line,
+				lineNumber: i + 1,
+				message: `Path should come before header (${name}: ${value})`,
+			});
+			continue;
+		}
+
+		const existingValues = rule.headers[name];
+		rule.headers[name] = existingValues ? `${existingValues}, ${value}` : value;
+	}
+
+	if (rule) {
+		if (isValidRule(rule)) {
+			rules.push({
+				path: rule.path,
+				headers: rule.headers,
+				unsetHeaders: rule.unsetHeaders,
+			});
+		} else {
+			invalid.push({ line: rule.line, message: "No headers specified" });
+		}
+	}
+
+	return {
+		rules,
+		invalid,
+	};
+}
+
+function isValidRule(rule: HeadersRule) {
+	return Object.keys(rule.headers).length > 0 || rule.unsetHeaders.length > 0;
+}