@sproutboat/assets 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @sproutboat/assets
 
+## 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,8 +1,13 @@
 {
   "name": "@sproutboat/assets",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "MIT",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/baronunread/sproutboat-packages.git",
+    "directory": "packages/assets"
+  },
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "scripts": {

package/src/assets.test.ts

@@ -0,0 +1,133 @@
+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,
+  matchRedirect,
+  parseHeaders,
+  parseRedirects,
+  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("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,133 @@ 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;
+}
+
+/**
+ * Match `pathname` against one `_redirects` rule's `from`, substituting
+ * `:name` segments and a trailing `*` (as `:splat`) into `to`. `null` if the
+ * rule doesn't match.
+ *
+ * The splat case matches on the literal string prefix up to `*`, not a
+ * segment array — `pathname.split("/").filter(Boolean)` would collapse
+ * `/blog` and `/blog/` to the same `["blog"]`, wrongly matching `/blog/*`
+ * against a path that never reaches the `/` the wildcard starts after.
+ */
+export function matchRedirect(rule: RedirectRule, pathname: string): string | null {
+  const starIndex = rule.from.indexOf("*");
+  if (starIndex !== -1) {
+    const prefix = rule.from.slice(0, starIndex);
+    if (!pathname.startsWith(prefix)) return null;
+    const splat = pathname.slice(prefix.length);
+    return rule.to.split(":splat").join(splat);
+  }
+
+  const fromSegments = rule.from.split("/").filter(Boolean);
+  const pathSegments = pathname.split("/").filter(Boolean);
+  if (fromSegments.length !== pathSegments.length) return null;
+  const params: Record<string, string> = {};
+  for (let i = 0; i < fromSegments.length; i++) {
+    const segment = fromSegments[i];
+    if (segment.startsWith(":")) {
+      params[segment.slice(1)] = pathSegments[i];
+      continue;
+    }
+    if (pathSegments[i] !== segment) return null;
+  }
+
+  let to = rule.to;
+  for (const [name, value] of Object.entries(params)) to = to.split(`:${name}`).join(value);
+  return to;
+}
+
+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")) : [],
+  };
+}