@cloudflare/pages-shared 0.0.2 → 0.0.3

package/dist/asset-server/patchUrl.js

@@ -0,0 +1,15 @@
+globalThis.URL = function(globalURL) {
+  PatchedURL.prototype = globalURL.prototype;
+  PatchedURL.createObjectURL = globalURL.createObjectURL;
+  PatchedURL.revokeObjectURL = globalURL.revokeObjectURL;
+  return PatchedURL;
+  function PatchedURL(input, base) {
+    const url = new URL(encodeURI(input), base);
+    return new Proxy(url, {
+      get(target, prop) {
+        return globalThis.decodeURIComponent(target[prop]);
+      }
+    });
+  }
+}(URL);
+export {};

package/dist/asset-server/responses.js

@@ -0,0 +1,123 @@
+function mergeHeaders(base, extra) {
+  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]) {
+    super(body, {
+      ...init,
+      status: 200,
+      statusText: "OK"
+    });
+  }
+}
+export class MovedPermanentlyResponse extends Response {
+  constructor(location, init) {
+    super(`Redirecting to ${location}`, {
+      ...init,
+      status: 301,
+      statusText: "Moved Permanently",
+      headers: mergeHeaders(init?.headers, {
+        location
+      })
+    });
+  }
+}
+export class FoundResponse extends Response {
+  constructor(location, init) {
+    super(`Redirecting to ${location}`, {
+      ...init,
+      status: 302,
+      statusText: "Found",
+      headers: mergeHeaders(init?.headers, {
+        location
+      })
+    });
+  }
+}
+export class NotModifiedResponse extends Response {
+  constructor(...[_body, _init]) {
+    super(void 0, {
+      status: 304,
+      statusText: "Not Modified"
+    });
+  }
+}
+export class PermanentRedirectResponse extends Response {
+  constructor(location, init) {
+    super(void 0, {
+      ...init,
+      status: 308,
+      statusText: "Permanent Redirect",
+      headers: mergeHeaders(init?.headers, {
+        location
+      })
+    });
+  }
+}
+export class NotFoundResponse extends Response {
+  constructor(...[body, init]) {
+    super(body, {
+      ...init,
+      status: 404,
+      statusText: "Not Found"
+    });
+  }
+}
+export class MethodNotAllowedResponse extends Response {
+  constructor(...[body, init]) {
+    super(body, {
+      ...init,
+      status: 405,
+      statusText: "Method Not Allowed"
+    });
+  }
+}
+export class NotAcceptableResponse extends Response {
+  constructor(...[body, init]) {
+    super(body, {
+      ...init,
+      status: 406,
+      statusText: "Not Acceptable"
+    });
+  }
+}
+export class InternalServerErrorResponse extends Response {
+  constructor(err, init) {
+    let body = void 0;
+    if (globalThis.DEBUG) {
+      body = `${err.message}
+
+${err.stack}`;
+    }
+    super(body, {
+      ...init,
+      status: 500,
+      statusText: "Internal Server Error"
+    });
+  }
+}
+export class SeeOtherResponse extends Response {
+  constructor(location, init) {
+    super(`Redirecting to ${location}`, {
+      ...init,
+      status: 303,
+      statusText: "See Other",
+      headers: mergeHeaders(init?.headers, { location })
+    });
+  }
+}
+export class TemporaryRedirectResponse extends Response {
+  constructor(location, init) {
+    super(`Redirecting to ${location}`, {
+      ...init,
+      status: 307,
+      statusText: "Temporary Redirect",
+      headers: mergeHeaders(init?.headers, { location })
+    });
+  }
+}

package/dist/asset-server/rulesEngine.js

@@ -0,0 +1,44 @@
+const ESCAPE_REGEX_CHARACTERS = /[-/\\^$*+?.()|[\]{}]/g;
+const escapeRegex = (str) => {
+  return str.replace(ESCAPE_REGEX_CHARACTERS, "\\$&");
+};
+const HOST_PLACEHOLDER_REGEX = /(?<=^https:\\\/\\\/[^/]*?):([^\\]+)(?=\\)/g;
+const PLACEHOLDER_REGEX = /:(\w+)/g;
+export const replacer = (str, replacements) => {
+  for (const [replacement, value] of Object.entries(replacements)) {
+    str = str.replaceAll(`:${replacement}`, value);
+  }
+  return str;
+};
+export const generateRulesMatcher = (rules, replacerFn = (match) => match) => {
+  if (!rules)
+    return () => [];
+  const compiledRules = Object.entries(rules).map(([rule, match]) => {
+    const crossHost = rule.startsWith("https://");
+    rule = rule.split("*").map(escapeRegex).join("(?<splat>.*)");
+    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]}>[^/]+)`);
+    }
+    rule = "^" + rule + "$";
+    try {
+      const regExp = new RegExp(rule);
+      return [{ crossHost, regExp }, match];
+    } catch {
+    }
+  }).filter((value) => value !== void 0);
+  return ({ 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 !== void 0);
+  };
+};

package/package.json

@@ -1,8 +1,9 @@
 {
 	"name": "@cloudflare/pages-shared",
-	"version": "0.0.2",
+	"version": "0.0.3",
 	"files": [
 		"tsconfig.json",
+		"src/**/*",
 		"dist/**/*"
 	],
 	"scripts": {
@@ -36,7 +37,9 @@
 	},
 	"devDependencies": {
 		"@cloudflare/workers-types": "^3.16.0",
+		"@types/service-worker-mock": "^2.0.1",
 		"concurrently": "^7.3.0",
-		"glob": "^8.0.3"
+		"glob": "^8.0.3",
+		"service-worker-mock": "^2.0.5"
 	}
 }

package/src/asset-server/metadata.ts

@@ -0,0 +1,66 @@
+// TODO: Use types from metadata-generator instead
+
+export type MetadataStaticRedirectEntry = {
+	status: number;
+	to: string;
+	lineNumber: number;
+};
+
+export type MetadataRedirectEntry = {
+	status: number;
+	to: string;
+	lineNumber?: number;
+};
+
+export type MetadataStaticRedirects = {
+	[path: string]: MetadataStaticRedirectEntry;
+};
+
+export type MetadataRedirects = {
+	[path: string]: MetadataRedirectEntry;
+};
+
+// v1 Types
+export type MetadataHeadersEntries = Record<string, string>;
+
+export type MetadataHeadersRulesV1 = {
+	[path: string]: MetadataHeadersEntries;
+};
+
+export type MetadataHeadersV1 = {
+	version: number; // TODO: This could be 1
+	rules: MetadataHeadersRulesV1;
+};
+
+// v2 Types
+export type SetHeaders = MetadataHeadersEntries;
+
+export type UnsetHeaders = Array<string>;
+
+export type MetadataHeadersRulesV2 = {
+	[path: string]: MetadataHeaderEntry;
+};
+
+export type MetadataHeaderEntry = {
+	set?: SetHeaders;
+	unset?: UnsetHeaders;
+};
+
+export type MetadataHeadersV2 = {
+	version: number; // TODO: This could be 2
+	rules: MetadataHeadersRulesV2;
+};
+
+export type Metadata = {
+	redirects?: {
+		version: number;
+		staticRules?: MetadataStaticRedirects;
+		rules: MetadataRedirects;
+	};
+	headers?: MetadataHeadersV1 | MetadataHeadersV2;
+	analytics?: {
+		version: number;
+		token: string;
+	};
+	deploymentId?: string;
+};

package/src/asset-server/patchUrl.ts

@@ -0,0 +1,22 @@
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-nocheck
+globalThis.URL = (function (globalURL) {
+	PatchedURL.prototype = globalURL.prototype;
+	PatchedURL.createObjectURL = globalURL.createObjectURL;
+	PatchedURL.revokeObjectURL = globalURL.revokeObjectURL;
+
+	return PatchedURL as unknown as typeof globalURL;
+
+	function PatchedURL(input: string, base?: string | URL) {
+		const url = new URL(encodeURI(input), base);
+
+		return new Proxy(url, {
+			get(target, prop) {
+				// eslint-disable-next-line @typescript-eslint/no-explicit-any
+				return globalThis.decodeURIComponent((target as any)[prop]);
+			},
+		});
+	}
+})(URL);
+
+export {};

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,84 @@
+declare type Request = { url: string };
+
+// 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/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;
+}

package/src/metadata-generator/parseRedirects.ts

@@ -0,0 +1,129 @@
+import {
+	MAX_LINE_LENGTH,
+	MAX_DYNAMIC_REDIRECT_RULES,
+	MAX_STATIC_REDIRECT_RULES,
+	PERMITTED_STATUS_CODES,
+	SPLAT_REGEX,
+	PLACEHOLDER_REGEX,
+} from "./constants";
+import { validateUrl } from "./validateURL";
+import type {
+	InvalidRedirectRule,
+	ParsedRedirects,
+	RedirectLine,
+	RedirectRule,
+} from "./types";
+
+export function parseRedirects(input: string): ParsedRedirects {
+	const lines = input.split("\n");
+	const rules: RedirectRule[] = [];
+	const seen_paths = new Set<string>();
+	const invalid: InvalidRedirectRule[] = [];
+
+	let staticRules = 0;
+	let dynamicRules = 0;
+	let canCreateStaticRule = true;
+
+	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;
+		}
+
+		const tokens = line.split(/\s+/);
+
+		if (tokens.length < 2 || tokens.length > 3) {
+			invalid.push({
+				line,
+				lineNumber: i + 1,
+				message: `Expected exactly 2 or 3 whitespace-separated tokens. Got ${tokens.length}.`,
+			});
+			continue;
+		}
+
+		const [str_from, str_to, str_status = "302"] = tokens as RedirectLine;
+
+		const fromResult = validateUrl(str_from, true, false, false);
+		if (fromResult[0] === undefined) {
+			invalid.push({
+				line,
+				lineNumber: i + 1,
+				message: fromResult[1],
+			});
+			continue;
+		}
+		const from = fromResult[0];
+
+		if (
+			canCreateStaticRule &&
+			!from.match(SPLAT_REGEX) &&
+			!from.match(PLACEHOLDER_REGEX)
+		) {
+			staticRules += 1;
+
+			if (staticRules > MAX_STATIC_REDIRECT_RULES) {
+				invalid.push({
+					message: `Maximum number of static rules supported is ${MAX_STATIC_REDIRECT_RULES}. Skipping line.`,
+				});
+				continue;
+			}
+		} else {
+			dynamicRules += 1;
+			canCreateStaticRule = false;
+
+			if (dynamicRules > MAX_DYNAMIC_REDIRECT_RULES) {
+				invalid.push({
+					message: `Maximum number of dynamic rules supported is ${MAX_DYNAMIC_REDIRECT_RULES}. Skipping remaining ${
+						lines.length - i
+					} lines of file.`,
+				});
+				break;
+			}
+		}
+
+		const toResult = validateUrl(str_to, false, true, true);
+		if (toResult[0] === undefined) {
+			invalid.push({
+				line,
+				lineNumber: i + 1,
+				message: toResult[1],
+			});
+			continue;
+		}
+		const to = toResult[0];
+
+		const status = Number(str_status);
+		if (isNaN(status) || !PERMITTED_STATUS_CODES.has(status)) {
+			invalid.push({
+				line,
+				lineNumber: i + 1,
+				message: `Valid status codes are 301, 302 (default), 303, 307, or 308. Got ${str_status}.`,
+			});
+			continue;
+		}
+
+		if (seen_paths.has(from)) {
+			invalid.push({
+				line,
+				lineNumber: i + 1,
+				message: `Ignoring duplicate rule for path ${from}.`,
+			});
+			continue;
+		}
+		seen_paths.add(from);
+
+		rules.push({ from, to, status, lineNumber: i + 1 });
+	}
+
+	return {
+		rules,
+		invalid,
+	};
+}

package/src/metadata-generator/types.ts

@@ -0,0 +1,89 @@
+/* REDIRECT PARSING TYPES */
+
+export type RedirectLine = [from: string, to: string, status?: number];
+export type RedirectRule = {
+	from: string;
+	to: string;
+	status: number;
+	lineNumber: number;
+};
+
+export type Headers = Record<string, string>;
+export type HeadersRule = {
+	path: string;
+	headers: Headers;
+	unsetHeaders: string[];
+};
+
+export type InvalidRedirectRule = {
+	line?: string;
+	lineNumber?: number;
+	message: string;
+};
+
+export type InvalidHeadersRule = {
+	line?: string;
+	lineNumber?: number;
+	message: string;
+};
+
+export type ParsedRedirects = {
+	invalid: InvalidRedirectRule[];
+	rules: RedirectRule[];
+};
+
+/** Parsed redirects and input file */
+export type ParsedRedirectsWithFile = {
+	parsedRedirects?: ParsedRedirects;
+	file?: string;
+};
+
+export type ParsedHeaders = {
+	invalid: InvalidHeadersRule[];
+	rules: HeadersRule[];
+};
+
+/** Parsed headers and input file */
+export type ParsedHeadersWithFile = {
+	parsedHeaders?: ParsedHeaders;
+	file?: string;
+};
+
+/* METADATA TYPES*/
+
+export type MetadataRedirectEntry = {
+	status: number;
+	to: string;
+};
+
+export type MetadataRedirects = {
+	[path: string]: MetadataRedirectEntry;
+};
+
+export type MetadataHeaders = {
+	[path: string]: MetadataHeaderEntry;
+};
+
+export type MetadataHeaderEntry = {
+	set?: Record<string, string>;
+	unset?: Array<string>;
+};
+
+export type Metadata = {
+	redirects?: {
+		version: number;
+		staticRules: MetadataRedirects;
+		rules: MetadataRedirects;
+	};
+	headers?: {
+		version: number;
+		rules: MetadataHeaders;
+	};
+	analytics?: {
+		version: number;
+		token: string;
+	};
+	deploymentId?: string;
+};
+
+export type Logger = (message: string) => void;

package/src/metadata-generator/validateURL.ts

@@ -0,0 +1,57 @@
+export const extractPathname = (
+	path = "/",
+	includeSearch: boolean,
+	includeHash: boolean
+): string => {
+	if (!path.startsWith("/")) path = `/${path}`;
+	const url = new URL(`//${path}`, "relative://");
+	return `${url.pathname}${includeSearch ? url.search : ""}${
+		includeHash ? url.hash : ""
+	}`;
+};
+
+const URL_REGEX = /^https:\/\/+(?<host>[^/]+)\/?(?<path>.*)/;
+const PATH_REGEX = /^\//;
+
+export const validateUrl = (
+	token: string,
+	onlyRelative = false,
+	includeSearch = false,
+	includeHash = false
+): [undefined, string] | [string, undefined] => {
+	const host = URL_REGEX.exec(token);
+	if (host && host.groups && host.groups.host) {
+		if (onlyRelative)
+			return [
+				undefined,
+				`Only relative URLs are allowed. Skipping absolute URL ${token}.`,
+			];
+
+		return [
+			`https://${host.groups.host}${extractPathname(
+				host.groups.path,
+				includeSearch,
+				includeHash
+			)}`,
+			undefined,
+		];
+	} else {
+		if (!token.startsWith("/") && onlyRelative) token = `/${token}`;
+
+		const path = PATH_REGEX.exec(token);
+		if (path) {
+			try {
+				return [extractPathname(token, includeSearch, includeHash), undefined];
+			} catch {
+				return [undefined, `Error parsing URL segment ${token}. Skipping.`];
+			}
+		}
+	}
+
+	return [
+		undefined,
+		onlyRelative
+			? "URLs should begin with a forward-slash."
+			: 'URLs should either be relative (e.g. begin with a forward-slash), or use HTTPS (e.g. begin with "https://").',
+	];
+};