@sproutboat/assets 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @sproutboat/assets
 
+## 0.3.1
+
+### Patch Changes
+
+- d4bbcd5: `_redirects` matching follows Cloudflare's rules. The whole request path must match, so a trailing slash is significant: `/compare /compare/ 308` redirects `/compare` once, and `/compare/` is then served (or matched by a rule of its own) instead of redirecting to itself forever. Before, a rule's `from` was compared segment by segment with the empty ones dropped, so `/compare` also matched `/compare/` and `/user/:id` matched `/user/42/`.
+  
+  What matches, as in Cloudflare's rules engine:
+  
+  - `:name` matches one or more characters up to the next `/`, may sit inside a segment (`/files/:name.html`), and may appear once per rule;
+  - `*` matches anything including `/` and the empty string, is `:splat` in the target, and may sit in the middle of the path (`/a/*/c`); a rule has at most one;
+  - a rule with a repeated name or two splats never matches (Cloudflare drops it);
+  - a static rule (no `:name`, no `*`) beats a dynamic one whatever the order; among rules of one kind the first in the file wins. `findRedirect(rules, pathname)` is the new entry point; `matchRedirect(rule, pathname)` still answers for one rule.
+  
+  This changes what an existing `_redirects` file does for paths that differ only by a trailing slash, with no compatibility date: the edge serves assets before any app code runs and cannot see the date, and the old matching was what looped. Run `bun run test:native-asset-redirects` to check the compiled matcher against the same cases as the portable one.
+
+## 0.3.0
+
+### Minor Changes
+
+- 6145afe: `_headers`/`_redirects` support (baronunread/sproutboat#61). `AssetManifest` gains optional `headers`/`redirects` arrays, parsed at build time from `_headers`/`_redirects` files at the assets root by the new `readAssetRules()` (`walkAssets()` now excludes those two filenames from the servable file list, root only). `matchHeaders()`/`matchRedirect()` apply them at request time: `_headers` uses Netlify/Pages-style greedy `*` matching (distinct from `run_sprout_first`'s single-segment `globMatch`), `_redirects` supports `:name` segments and a trailing `*` substituted as `:splat`. Pure parsing/matching in this package; wiring them into the edge/broker request path is a separate change downstream.
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -1,4 +1,27 @@
 # `@sproutboat/assets`
 
-Single source of truth for static assets: manifests, key resolution, and
-the sprout-first routing rules shared by the edge asset server and the CLI.
+Static asset manifests, key resolution, and sprout-first routing rules,
+shared by the edge asset server and the CLI.
+
+```sh
+bun add @sproutboat/assets
+```
+
+```ts
+import { resolveAssetKey, walkAssets } from "@sproutboat/assets";
+
+const files = walkAssets("web/dist");
+const key = resolveAssetKey("/docs", (k) => k in files);
+```
+
+## API
+
+- `walkAssets(directory)` inventories an asset directory into the file
+  table (paths, hashes, sizes).
+- `resolveAssetKey(path, has)` maps a request path to an asset key,
+  honoring directory defaults and index files.
+- `isSproutFirst(spec, pathname)` reports whether the handler sees a
+  request before the asset server does, given the assets
+  `runSproutFirst` spec.
+- `contentType(name)` maps extensions to content types.
+- Types: `AssetManifest`, `AssetFiles`, `AssetEntry`.

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "@sproutboat/assets",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/baronunread/sproutboat-packages.git",
+    "directory": "packages/assets"
+  },
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/assets.test.ts

@@ -0,0 +1,183 @@
+import { expect, test } from "bun:test";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  contentType,
+  isSproutFirst,
+  matchHeaders,
+  findRedirect,
+  matchRedirect,
+  parseHeaders,
+  parseRedirects,
+  resolveAssetKey,
+  readAssetRules,
+  walkAssets,
+} from "./assets";
+
+test("contentType maps known extensions, defaults to octet-stream", () => {
+  expect(contentType("index.html")).toBe("text/html; charset=utf-8");
+  expect(contentType("app.CSS")).toBe("text/css; charset=utf-8");
+  expect(contentType("logo.png")).toBe("image/png");
+  expect(contentType("archive.tar")).toBe("application/octet-stream");
+  expect(contentType("noext")).toBe("application/octet-stream");
+});
+
+test("isSproutFirst: boolean short-circuits; patterns match with negation", () => {
+  expect(isSproutFirst(true, "/anything")).toBe(true);
+  expect(isSproutFirst(false, "/anything")).toBe(false);
+  expect(isSproutFirst(["/api/*"], "/api/users")).toBe(true);
+  expect(isSproutFirst(["/api/*"], "/index.html")).toBe(false);
+  expect(isSproutFirst(["/api/*", "!/api/docs/*"], "/api/docs/intro")).toBe(false);
+  expect(isSproutFirst(["/api/**"], "/api/a/b/c")).toBe(true);
+  expect(isSproutFirst(["/api/*"], "/api/a/b")).toBe(false); // single * stays in a segment
+});
+
+test("walkAssets hashes every file under a directory, posix keys", () => {
+  const dir = mkdtempSync(join(tmpdir(), "sb-walk-"));
+  mkdirSync(join(dir, "css"));
+  writeFileSync(join(dir, "index.html"), "<h1>hi</h1>");
+  writeFileSync(join(dir, "css", "app.css"), "body{}");
+  writeFileSync(join(dir, ".hidden"), "skip me");
+  const files = walkAssets(dir);
+  expect(Object.keys(files).sort()).toEqual(["/css/app.css", "/index.html"]);
+  expect(files["/index.html"]).toMatchObject({ size: 11, type: "text/html; charset=utf-8" });
+  expect(files["/index.html"].hash).toMatch(/^[0-9a-f]{64}$/);
+  rmSync(dir, { recursive: true, force: true });
+});
+
+test("walkAssets excludes _headers/_redirects at the root, but not nested files with those names", () => {
+  const dir = mkdtempSync(join(tmpdir(), "sb-walk-"));
+  mkdirSync(join(dir, "sub"));
+  writeFileSync(join(dir, "_headers"), "/*\n  X-Test: 1\n");
+  writeFileSync(join(dir, "_redirects"), "/a /b\n");
+  writeFileSync(join(dir, "sub", "_headers"), "not config, just a file");
+  const files = walkAssets(dir);
+  expect(Object.keys(files).sort()).toEqual(["/sub/_headers"]);
+  rmSync(dir, { recursive: true, force: true });
+});
+
+test("parseHeaders: set and unset lines, comments, and blank lines ending a block", () => {
+  const rules = parseHeaders(
+    [
+      "# a comment",
+      "/*",
+      "  X-Frame-Options: DENY",
+      "  Cache-Control: no-cache",
+      "",
+      "/assets/*",
+      "  Cache-Control: public, max-age=31536000",
+      "  ! X-Frame-Options",
+    ].join("\n"),
+  );
+  expect(rules).toEqual([
+    {
+      pattern: "/*",
+      set: [
+        ["X-Frame-Options", "DENY"],
+        ["Cache-Control", "no-cache"],
+      ],
+      unset: [],
+    },
+    { pattern: "/assets/*", set: [["Cache-Control", "public, max-age=31536000"]], unset: ["X-Frame-Options"] },
+  ]);
+});
+
+test("parseHeaders: an indented line with no preceding pattern is ignored", () => {
+  expect(parseHeaders("  X-Test: 1\n")).toEqual([]);
+});
+
+test("matchHeaders: returns rules whose pattern matches, in file order", () => {
+  const rules = parseHeaders("/*\n  A: 1\n\n/assets/*\n  B: 2\n");
+  expect(matchHeaders(rules, "/assets/app.js").map((r) => r.pattern)).toEqual(["/*", "/assets/*"]);
+  expect(matchHeaders(rules, "/index.html").map((r) => r.pattern)).toEqual(["/*"]);
+});
+
+test("parseRedirects: from/to/status, default status, malformed lines dropped", () => {
+  expect(
+    parseRedirects(["# comment", "/old /new 301", "/a /b", "/bad-status /c 200", "just-one-token"].join("\n")),
+  ).toEqual([
+    { from: "/old", to: "/new", status: 301 },
+    { from: "/a", to: "/b", status: 302 },
+  ]);
+});
+
+test("matchRedirect: exact path, no placeholders", () => {
+  const rule = { from: "/old", to: "/new", status: 301 };
+  expect(matchRedirect(rule, "/old")).toBe("/new");
+  expect(matchRedirect(rule, "/old/extra")).toBeNull();
+  expect(matchRedirect(rule, "/other")).toBeNull();
+});
+
+test("matchRedirect: :name segments substitute into `to`", () => {
+  const rule = { from: "/user/:id", to: "/profile/:id", status: 302 };
+  expect(matchRedirect(rule, "/user/42")).toBe("/profile/42");
+  expect(matchRedirect(rule, "/user")).toBeNull();
+  expect(matchRedirect(rule, "/user/42/extra")).toBeNull();
+});
+
+test("matchRedirect: a trailing * captures the rest of the path as :splat", () => {
+  const rule = { from: "/blog/*", to: "/articles/:splat", status: 301 };
+  expect(matchRedirect(rule, "/blog/2024/hello")).toBe("/articles/2024/hello");
+  expect(matchRedirect(rule, "/blog/")).toBe("/articles/");
+  expect(matchRedirect(rule, "/blog")).toBeNull();
+});
+
+test("matchRedirect: the whole path must match, so a trailing slash is significant", () => {
+  const add = { from: "/compare", to: "/compare/", status: 308 };
+  expect(matchRedirect(add, "/compare")).toBe("/compare/");
+  expect(matchRedirect(add, "/compare/")).toBeNull(); // the loop: this used to match again
+  const drop = { from: "/compare/", to: "/compare", status: 308 };
+  expect(matchRedirect(drop, "/compare/")).toBe("/compare");
+  expect(matchRedirect(drop, "/compare")).toBeNull();
+  const named = { from: "/user/:id", to: "/profile/:id", status: 302 };
+  expect(matchRedirect(named, "/user/42/")).toBeNull();
+  expect(matchRedirect(named, "/user/")).toBeNull();
+  const splat = { from: "/blog/*", to: "/posts/:splat", status: 301 };
+  expect(matchRedirect(splat, "/blog/a/")).toBe("/posts/a/");
+});
+
+test("matchRedirect: a name is one or more characters, backtracks around text, and the splat may sit in the middle", () => {
+  expect(matchRedirect({ from: "/files/:name.html", to: "/pages/:name", status: 302 }, "/files/about.html")).toBe(
+    "/pages/about",
+  );
+  expect(matchRedirect({ from: "/:a-:b", to: "/x/:b/:a", status: 302 }, "/one-two")).toBe("/x/two/one");
+  expect(matchRedirect({ from: "/a/*/c", to: "/x/:splat", status: 302 }, "/a/b/b2/c")).toBe("/x/b/b2");
+  expect(matchRedirect({ from: "/a/*/c", to: "/x/:splat", status: 302 }, "/a/c")).toBeNull();
+  expect(matchRedirect({ from: "/a:1", to: "/b", status: 302 }, "/a:1")).toBe("/b"); // a colon with no letter is text
+});
+
+test("matchRedirect: a rule with a repeated name or two splats never matches, as on Cloudflare", () => {
+  expect(matchRedirect({ from: "/:a/:a", to: "/x", status: 302 }, "/p/p")).toBeNull();
+  expect(matchRedirect({ from: "/*/*", to: "/x", status: 302 }, "/p/q")).toBeNull();
+});
+
+test("findRedirect: a static rule beats a dynamic one above it; within a kind the first rule wins", () => {
+  const rules = parseRedirects(
+    "/blog/* /dynamic/:splat\n/blog/old /static\n/blog/old /static-2\n/x/:a /first\n/x/:b /second",
+  );
+  expect(findRedirect(rules, "/blog/old")).toEqual({ rule: rules[1], location: "/static" });
+  expect(findRedirect(rules, "/blog/new")).toEqual({ rule: rules[0], location: "/dynamic/new" });
+  expect(findRedirect(rules, "/x/1")).toEqual({ rule: rules[3], location: "/first" });
+  expect(findRedirect(rules, "/nothing")).toBeNull();
+});
+
+test("a trailing-slash rule is one hop against the asset resolver too", () => {
+  const rules = parseRedirects("/compare /compare/ 308");
+  const files = new Set(["/compare/index.html"]);
+  const first = findRedirect(rules, "/compare");
+  expect(first?.location).toBe("/compare/");
+  expect(findRedirect(rules, first!.location)).toBeNull();
+  expect(resolveAssetKey(first!.location, (key) => files.has(key))).toBe("/compare/index.html");
+});
+
+test("readAssetRules: empty when neither file exists, parsed when both do", () => {
+  const dir = mkdtempSync(join(tmpdir(), "sb-rules-"));
+  expect(readAssetRules(dir)).toEqual({ headers: [], redirects: [] });
+  writeFileSync(join(dir, "_headers"), "/*\n  X: 1\n");
+  writeFileSync(join(dir, "_redirects"), "/a /b\n");
+  const rules = readAssetRules(dir);
+  expect(rules.headers).toHaveLength(1);
+  expect(rules.redirects).toHaveLength(1);
+  rmSync(dir, { recursive: true, force: true });
+});

package/src/assets.ts

@@ -6,18 +6,26 @@
  * the sprout chooses to serve itself.
  */
 import { createHash } from "node:crypto";
-import { readdirSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join, posix } from "node:path";
 
 export type AssetEntry = { hash: string; size: number; type: string };
 /** `/absolute/posix/path` -> entry. Serialised into `assets.json`. */
 export type AssetFiles = { [path: string]: AssetEntry };
+/** A `_headers` block: `set` applied in order, `unset` (`! Name`) removed. */
+export type HeaderRule = { pattern: string; set: [string, string][]; unset: string[] };
+/** A `_redirects` line: `from  to  [status]`, `:name` segments and a trailing `*` -> `:splat`. */
+export type RedirectRule = { from: string; to: string; status: number };
 export type AssetManifest = {
   /** Fallback for requests that match no file, applied by the broker. */
   notFound: "none" | "single-page-application" | "404-page";
   /** `true` = every path to the sprout first; string[] = selective (leading `!` negates). */
   runSproutFirst: boolean | string[];
   files: AssetFiles;
+  /** Parsed from `_headers` at the assets root (#61). Omitted when there is none. */
+  headers?: HeaderRule[];
+  /** Parsed from `_redirects` at the assets root (#61). Omitted when there is none. */
+  redirects?: RedirectRule[];
 };
 
 const TYPES = new Map<string, string>([
@@ -73,12 +81,13 @@ export function resolveAssetKey(path: string, has: (key: string) => boolean): st
   return null;
 }
 
-/** Walk `dir` recursively, returning `{ "/path": {hash,size,type} }`. */
+/** Walk `dir` recursively, returning `{ "/path": {hash,size,type} }`. `_headers`/`_redirects` at the root are config, not servable files (#61) — see `readAssetRules`. */
 export function walkAssets(dir: string) {
   const out: AssetFiles = {};
   const recurse = (abs: string, rel: string): void => {
     for (const ent of readdirSync(abs, { withFileTypes: true })) {
       if (ent.name.startsWith(".")) continue;
+      if (rel === "" && (ent.name === "_headers" || ent.name === "_redirects")) continue;
       const childAbs = join(abs, ent.name);
       const childRel = posix.join(rel, ent.name);
       if (ent.isDirectory()) {
@@ -119,3 +128,194 @@ function globMatch(pattern: string, path: string): boolean {
     .replace(/ /g, ".*");
   return new RegExp(`^${rx}$`).test(path);
 }
+
+const MAX_HEADER_RULES = 2000;
+const MAX_REDIRECT_RULES = 2000;
+
+/**
+ * Parse a Pages/Netlify-style `_headers` file: a path pattern at column 0,
+ * followed by indented `Name: value` lines (`! Name` strips a header
+ * downstream). A blank line or a new pattern line ends the current block.
+ */
+export function parseHeaders(text: string): HeaderRule[] {
+  const rules: HeaderRule[] = [];
+  let current: HeaderRule | null = null;
+  for (const rawLine of text.split("\n")) {
+    if (rawLine.trim() === "" || /^\s*#/.test(rawLine)) {
+      current = null;
+      continue;
+    }
+    if (!/^\s/.test(rawLine)) {
+      if (rules.length >= MAX_HEADER_RULES) {
+        current = null;
+        continue;
+      }
+      current = { pattern: rawLine.trim(), set: [], unset: [] };
+      rules.push(current);
+      continue;
+    }
+    if (!current) continue;
+    const line = rawLine.trim();
+    if (line.startsWith("!")) {
+      current.unset.push(line.slice(1).trim());
+      continue;
+    }
+    const colon = line.indexOf(":");
+    if (colon === -1) continue;
+    current.set.push([line.slice(0, colon).trim(), line.slice(colon + 1).trim()]);
+  }
+  return rules;
+}
+
+/**
+ * `_headers` patterns follow Netlify/Pages semantics, not `globMatch`'s
+ * (`run_sprout_first` deliberately keeps a bare `*` inside one segment) — a
+ * trailing `*` here is greedy across `/`, so `/assets/*` catches
+ * `/assets/deeply/nested.js` the way a real `_headers` file expects.
+ */
+function headerPatternMatches(pattern: string, pathname: string): boolean {
+  const patternSegments = pattern.split("/").filter(Boolean);
+  const pathSegments = pathname.split("/").filter(Boolean);
+  for (let i = 0; i < patternSegments.length; i++) {
+    if (patternSegments[i] === "*") return true;
+    if (pathSegments[i] !== patternSegments[i]) return false;
+  }
+  return patternSegments.length === pathSegments.length;
+}
+
+/** Every `_headers` rule whose pattern matches `pathname`, in file order (a later rule can override or unset an earlier one when applied). */
+export function matchHeaders(rules: readonly HeaderRule[], pathname: string): HeaderRule[] {
+  return rules.filter((rule) => headerPatternMatches(rule.pattern, pathname));
+}
+
+/**
+ * Parse a Pages/Netlify-style `_redirects` file: `from  to  [status]` per
+ * line, whitespace-separated. `status` must be a 3xx (defaults to 302 when
+ * omitted); anything else is dropped as malformed rather than silently
+ * treated as a rewrite.
+ */
+export function parseRedirects(text: string): RedirectRule[] {
+  const rules: RedirectRule[] = [];
+  for (const rawLine of text.split("\n")) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const parts = line.split(/\s+/);
+    if (parts.length < 2) continue;
+    const [from, to, statusText] = parts;
+    const status = statusText ? Number(statusText) : 302;
+    if (!Number.isInteger(status) || status < 300 || status > 399) continue;
+    rules.push({ from, to, status });
+    if (rules.length >= MAX_REDIRECT_RULES) break;
+  }
+  return rules;
+}
+
+/**
+ * Cloudflare's `_redirects` matching (workers-sdk, `asset-worker/src/utils/rules-engine.ts`), on the request pathname:
+ *
+ *   - the whole pathname must match, so a trailing slash is significant: `/compare` does not match `/compare/`, and
+ *     `/compare /compare/ 308` is one hop, not a loop;
+ *   - `:name` matches one or more characters up to the next `/` (letters, digits and `_` after a letter name it);
+ *     a name may appear once per rule;
+ *   - `*` matches anything, including `/` and nothing, and is `:splat` in `to`; a rule has at most one;
+ *   - a rule that breaks those limits never matches (Cloudflare drops it).
+ *
+ * A rule with no `:name` and no `*` is static: a static rule beats a dynamic one whatever the order (`findRedirect`);
+ * among rules of one kind the first in the file wins.
+ */
+type RedirectToken = { kind: "text"; text: string } | { kind: "name"; name: string } | { kind: "splat" };
+
+function redirectTokens(from: string): RedirectToken[] | null {
+  const tokens: RedirectToken[] = [];
+  const names = new Set<string>();
+  let text = "";
+  const flush = () => {
+    if (text !== "") tokens.push({ kind: "text", text });
+    text = "";
+  };
+  for (let i = 0; i < from.length; i++) {
+    const c = from[i]!;
+    if (c === "*") {
+      flush();
+      if (names.has("splat")) return null;
+      names.add("splat");
+      tokens.push({ kind: "splat" });
+    } else if (c === ":" && /[A-Za-z]/.test(from[i + 1] ?? "")) {
+      let end = i + 2;
+      while (end < from.length && /\w/.test(from[end]!)) end++;
+      const name = from.slice(i + 1, end);
+      if (names.has(name)) return null;
+      names.add(name);
+      flush();
+      tokens.push({ kind: "name", name });
+      i = end - 1;
+    } else text += c;
+  }
+  flush();
+  return tokens;
+}
+
+function matchTokens(tokens: RedirectToken[], t: number, path: string, p: number, groups: [string, string][]): boolean {
+  const token = tokens[t];
+  if (token === undefined) return p === path.length;
+  if (token.kind === "text")
+    return path.startsWith(token.text, p) && matchTokens(tokens, t + 1, path, p + token.text.length, groups);
+  const slash = path.indexOf("/", p);
+  const limit = token.kind === "splat" || slash === -1 ? path.length : slash;
+  const name = token.kind === "splat" ? "splat" : token.name;
+  // Longest first, as the regular expression `[^/]+` / `.*` is greedy; a name needs at least one character.
+  for (let q = limit; q >= (token.kind === "splat" ? p : p + 1); q--) {
+    groups.push([name, path.slice(p, q)]);
+    if (matchTokens(tokens, t + 1, path, q, groups)) return true;
+    groups.pop();
+  }
+  return false;
+}
+
+const isStaticRedirect = (from: string): boolean => !from.includes("*") && !/:[A-Za-z]/.test(from);
+
+function redirectLocation(rule: RedirectRule, pathname: string): string | null {
+  if (isStaticRedirect(rule.from)) return rule.from === pathname ? rule.to : null;
+  const tokens = redirectTokens(rule.from);
+  if (tokens === null) return null;
+  const groups: [string, string][] = [];
+  if (!matchTokens(tokens, 0, pathname, 0, groups)) return null;
+  let to = rule.to;
+  for (const [name, value] of groups) to = to.split(`:${name}`).join(value);
+  return to;
+}
+
+/**
+ * Where one `_redirects` rule sends `pathname`, with `:name` and `:splat` substituted into `to`; `null` if the rule does
+ * not match. See the notes above for what matches.
+ */
+export function matchRedirect(rule: RedirectRule, pathname: string): string | null {
+  return redirectLocation(rule, pathname);
+}
+
+/** The rule that redirects `pathname`, and where to: the first static rule that matches, else the first dynamic one. */
+export function findRedirect(
+  rules: readonly RedirectRule[],
+  pathname: string,
+): { rule: RedirectRule; location: string } | null {
+  for (const rule of rules)
+    if (isStaticRedirect(rule.from) && rule.from === pathname) return { rule, location: rule.to };
+  for (const rule of rules) {
+    if (isStaticRedirect(rule.from)) continue;
+    const location = redirectLocation(rule, pathname);
+    if (location !== null) return { rule, location };
+  }
+  return null;
+}
+
+export type AssetRules = { headers: HeaderRule[]; redirects: RedirectRule[] };
+
+/** Read and parse `_headers`/`_redirects` from the assets root, if present. */
+export function readAssetRules(dir: string): AssetRules {
+  const headersPath = join(dir, "_headers");
+  const redirectsPath = join(dir, "_redirects");
+  return {
+    headers: existsSync(headersPath) ? parseHeaders(readFileSync(headersPath, "utf8")) : [],
+    redirects: existsSync(redirectsPath) ? parseRedirects(readFileSync(redirectsPath, "utf8")) : [],
+  };
+}