@fishenv/http 0.0.0-stage → 0.0.3

package/dist/static/options.js

@@ -0,0 +1,190 @@
+import { realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import { isSafeSegment, isWithin, } from "./resolve.js";
+import { applyRules, compileGlob, compileRules, matchesGlob, } from "./rules.js";
+const RESPONSE_KEYS = [
+    "precompressed",
+    "etag",
+    "lastModified",
+    "cacheControl",
+    "headers",
+    "untrusted",
+    "setHeaders",
+];
+const STATIC_KEYS = new Set([
+    ...RESPONSE_KEYS,
+    "root",
+    "index",
+    "extensions",
+    "dotfiles",
+    "allowDotfiles",
+    "symlinks",
+    "rules",
+    "exclude",
+    "fallback",
+    "cache",
+]);
+const ENCODINGS = ["br", "gzip"];
+function fail(message) {
+    throw new Error(`static: ${message}`);
+}
+function checkKeys(opts, known, what) {
+    for (const key of Object.keys(opts)) {
+        if (!known.has(key))
+            fail(`unknown ${what} option "${key}"`);
+    }
+}
+function stringArray(value, name) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.some((v) => typeof v !== "string")) {
+        fail(`"${name}" must be an array of strings`);
+    }
+    return value;
+}
+/** Validate and normalize the options shared with `serveFile()`. */
+export function compileResponseOptions(opts) {
+    const precompressed = stringArray(opts.precompressed, "precompressed");
+    for (const enc of precompressed) {
+        if (!ENCODINGS.includes(enc)) {
+            fail(`unsupported precompressed encoding "${enc}" (use "br" | "gzip")`);
+        }
+    }
+    if (opts.setHeaders !== undefined && typeof opts.setHeaders !== "function") {
+        fail(`"setHeaders" must be a function`);
+    }
+    return {
+        precompressed: [...new Set(precompressed)],
+        etag: opts.etag ?? true,
+        lastModified: opts.lastModified ?? true,
+        cacheControl: opts.cacheControl ?? "no-cache",
+        headers: { ...opts.headers },
+        untrusted: opts.untrusted ?? false,
+        setHeaders: opts.setHeaders,
+    };
+}
+export function compileServeFileOptions(opts) {
+    checkKeys(opts, new Set(RESPONSE_KEYS), "serveFile");
+    return compileResponseOptions(opts);
+}
+/** True when `segments` may be served at all (dotfiles, deny, exclude). */
+export function isServable(cfg, segments) {
+    const rel = segments.join("/");
+    if (cfg.exclude.some((re) => matchesGlob(re, rel)))
+        return false;
+    return passesFilePolicy(cfg, segments);
+}
+/**
+ * Dotfile and deny rules. Unlike `exclude`, which carves out URL space,
+ * these protect files, so they are also applied to the canonical on-disk
+ * name of whatever a request resolves to.
+ */
+export function passesFilePolicy(cfg, segments) {
+    if (cfg.dotfiles === "hide") {
+        for (const segment of segments) {
+            if (segment.startsWith(".") &&
+                !cfg.allowDotfiles.has(segment.toLowerCase())) {
+                return false;
+            }
+        }
+    }
+    return !applyRules(cfg.rules, segments.join("/")).deny;
+}
+/** Validate options and resolve the root. Throws on any misconfiguration. */
+export function compileStaticOptions(opts) {
+    if (typeof opts !== "object" || opts === null)
+        fail("options are required");
+    checkKeys(opts, STATIC_KEYS, "staticFiles");
+    if (typeof opts.root !== "string" || opts.root === "") {
+        fail(`"root" is required`);
+    }
+    let root;
+    try {
+        root = realpathSync(path.resolve(opts.root));
+    }
+    catch {
+        fail(`root "${opts.root}" does not exist`);
+    }
+    if (!statSync(root).isDirectory()) {
+        fail(`root "${opts.root}" is not a directory`);
+    }
+    if (path.parse(root).root === root) {
+        fail("refusing to serve the filesystem root");
+    }
+    const untrusted = opts.untrusted ?? false;
+    const dotfiles = opts.dotfiles ?? "hide";
+    if (dotfiles !== "hide" && dotfiles !== "allow") {
+        fail(`"dotfiles" must be "hide" or "allow"`);
+    }
+    if (untrusted && dotfiles === "allow") {
+        fail(`"dotfiles: allow" cannot be combined with "untrusted"`);
+    }
+    const symlinks = opts.symlinks ?? (untrusted ? "deny" : "within-root");
+    if (!["within-root", "deny", "follow"].includes(symlinks)) {
+        fail(`"symlinks" must be "within-root", "deny" or "follow"`);
+    }
+    const windows = process.platform === "win32";
+    const index = stringArray(opts.index ?? ["index.html"], "index");
+    for (const name of index) {
+        if (!isSafeSegment(name, windows))
+            fail(`invalid index name "${name}"`);
+    }
+    const extensions = stringArray(opts.extensions, "extensions").map((e) => e.replace(/^\./, ""));
+    for (const ext of extensions) {
+        if (!isSafeSegment(`x.${ext}`, windows) || ext === "") {
+            fail(`invalid extension "${ext}"`);
+        }
+    }
+    let cache;
+    if (opts.cache) {
+        const c = opts.cache === true ? {} : opts.cache;
+        checkKeys(c, new Set(["ttlMs", "maxEntries"]), "cache");
+        cache = { ttlMs: c.ttlMs ?? 5_000, maxEntries: c.maxEntries ?? 10_000 };
+        if (!(cache.ttlMs > 0) || !(cache.maxEntries >= 1)) {
+            fail(`"cache.ttlMs" and "cache.maxEntries" must be positive`);
+        }
+    }
+    const cfg = {
+        ...compileResponseOptions(opts),
+        root,
+        index,
+        extensions,
+        dotfiles,
+        allowDotfiles: new Set(stringArray(opts.allowDotfiles, "allowDotfiles").map((s) => s.toLowerCase())),
+        symlinks,
+        rules: compileRules(opts.rules ?? []),
+        exclude: stringArray(opts.exclude, "exclude").map(compileGlob),
+        cache,
+        windows,
+        allowCanonical: (segments) => passesFilePolicy(cfg, segments),
+    };
+    if (opts.fallback !== undefined) {
+        cfg.fallback = compileFallback(cfg, opts.fallback);
+    }
+    return cfg;
+}
+/** The fallback must be a servable regular file inside the root. */
+function compileFallback(cfg, fallback) {
+    if (typeof fallback !== "string")
+        fail(`"fallback" must be a string`);
+    const segments = fallback.replace(/^\/+/, "").split("/");
+    if (!segments.every((s) => isSafeSegment(s, cfg.windows))) {
+        fail(`invalid fallback path "${fallback}"`);
+    }
+    if (!isServable(cfg, segments)) {
+        fail(`fallback "${fallback}" is hidden by dotfiles, rules or exclude`);
+    }
+    try {
+        const real = realpathSync(path.join(cfg.root, ...segments));
+        const canonical = path.relative(cfg.root, real).split(path.sep);
+        if (isWithin(cfg.root, real) &&
+            passesFilePolicy(cfg, canonical) &&
+            statSync(real).isFile()) {
+            return segments;
+        }
+    }
+    catch {
+        // fall through
+    }
+    return fail(`fallback "${fallback}" is not a file inside the root`);
+}

package/dist/static/resolve.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Request path → file on disk. Every step either continues or rejects; see
+ * `.plan/12-static-files.md` ("Request → file pipeline") for the reasoning
+ * behind each check.
+ */
+import type { Stats } from "node:fs";
+import { lstat, realpath, stat } from "node:fs/promises";
+/**
+ * Filesystem calls used by the resolver. Exported so tests can observe how
+ * many syscalls a lookup performs; not part of the public API.
+ */
+export declare const fsOps: {
+    lstat: typeof lstat;
+    realpath: typeof realpath;
+    stat: typeof stat;
+};
+export interface ParsedPath {
+    /** Decoded, validated segments. Empty for the mount root. */
+    segments: string[];
+    /** The request ended in `/` (a directory request). */
+    trailingSlash: boolean;
+}
+/** Marker for `%` sequences that fail to decode (→ 400). */
+export declare const BAD_ENCODING: unique symbol;
+/** Validate one decoded segment (step 3). */
+export declare function isSafeSegment(segment: string, windows: boolean): boolean;
+/**
+ * Steps 1–3: split the raw (percent-encoded) remainder on `/`, then decode
+ * each segment exactly once and validate it. Splitting before decoding is
+ * what turns `..%2F..%2Fetc` into a single (rejected) segment.
+ *
+ * Returns `null` for a path that can never be served (→ 404).
+ */
+export declare function parseRequestPath(raw: string | undefined, windows?: boolean): ParsedPath | typeof BAD_ENCODING | null;
+/** Lexical containment: `candidate` is `root` or strictly below it. */
+export declare function isWithin(root: string, candidate: string): boolean;
+export type SymlinkPolicy = "within-root" | "deny" | "follow";
+export interface Located {
+    /** Path to open: the resolved real path, except under `"follow"`. */
+    abs: string;
+    stat: Stats;
+}
+/**
+ * Policy check on the canonical (on-disk) segments of what was resolved.
+ * The request may have named it through an alias — an in-root symlink, a
+ * Windows 8.3 short name, other case on a case-insensitive disk, another
+ * Unicode normalization — so dotfile and deny rules must also hold here.
+ */
+export type CanonicalCheck = (segments: string[]) => boolean;
+/**
+ * Steps 6–8: map validated segments to a regular file or directory inside
+ * `root` (which must already be a real path). Anything else — missing,
+ * escaping, a forbidden symlink, a FIFO/socket/device, a canonical name
+ * that `allow` rejects — is `null`.
+ */
+export declare function locate(root: string, segments: string[], symlinks: SymlinkPolicy, allow?: CanonicalCheck): Promise<Located | null>;

package/dist/static/resolve.js

@@ -0,0 +1,113 @@
+/**
+ * Request path → file on disk. Every step either continues or rejects; see
+ * `.plan/12-static-files.md` ("Request → file pipeline") for the reasoning
+ * behind each check.
+ */
+import { lstat, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+/**
+ * Filesystem calls used by the resolver. Exported so tests can observe how
+ * many syscalls a lookup performs; not part of the public API.
+ */
+export const fsOps = { lstat, realpath, stat };
+/** Marker for `%` sequences that fail to decode (→ 400). */
+export const BAD_ENCODING = Symbol("bad-encoding");
+// C0 controls and DEL.
+// biome-ignore lint/suspicious/noControlCharactersInRegex: matching them is the point
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]/;
+// Characters Windows refuses in names, plus `:` (alternate data streams).
+const WINDOWS_FORBIDDEN = /[<>:"|?*]/;
+const WINDOWS_DEVICE = /^(con|prn|aux|nul|com[0-9]|lpt[0-9])(\..*)?$/i;
+/** Validate one decoded segment (step 3). */
+export function isSafeSegment(segment, windows) {
+    if (segment === "" || segment === "." || segment === "..")
+        return false;
+    if (segment.includes("/") || segment.includes("\\"))
+        return false;
+    if (CONTROL_CHARS.test(segment))
+        return false;
+    if (windows) {
+        if (WINDOWS_FORBIDDEN.test(segment))
+            return false;
+        if (/[. ]$/.test(segment))
+            return false;
+        if (WINDOWS_DEVICE.test(segment))
+            return false;
+    }
+    return true;
+}
+/**
+ * Steps 1–3: split the raw (percent-encoded) remainder on `/`, then decode
+ * each segment exactly once and validate it. Splitting before decoding is
+ * what turns `..%2F..%2Fetc` into a single (rejected) segment.
+ *
+ * Returns `null` for a path that can never be served (→ 404).
+ */
+export function parseRequestPath(raw, windows = process.platform === "win32") {
+    if (raw === undefined || raw === "") {
+        // `/mount` (no slash) vs `/mount/`: the rest param is absent vs empty.
+        return { segments: [], trailingSlash: raw === "" };
+    }
+    const parts = raw.split("/");
+    const trailingSlash = parts[parts.length - 1] === "";
+    if (trailingSlash)
+        parts.pop();
+    const segments = [];
+    for (const part of parts) {
+        let decoded;
+        try {
+            decoded = decodeURIComponent(part);
+        }
+        catch {
+            return BAD_ENCODING;
+        }
+        if (!isSafeSegment(decoded, windows))
+            return null;
+        segments.push(decoded);
+    }
+    return { segments, trailingSlash };
+}
+/** Lexical containment: `candidate` is `root` or strictly below it. */
+export function isWithin(root, candidate) {
+    return candidate === root || candidate.startsWith(root + path.sep);
+}
+/**
+ * Steps 6–8: map validated segments to a regular file or directory inside
+ * `root` (which must already be a real path). Anything else — missing,
+ * escaping, a forbidden symlink, a FIFO/socket/device, a canonical name
+ * that `allow` rejects — is `null`.
+ */
+export async function locate(root, segments, symlinks, allow) {
+    const candidate = path.join(root, ...segments);
+    if (!isWithin(root, candidate))
+        return null;
+    try {
+        if (symlinks === "deny") {
+            let current = root;
+            for (const segment of segments) {
+                current = path.join(current, segment);
+                if ((await fsOps.lstat(current)).isSymbolicLink())
+                    return null;
+            }
+        }
+        const real = await fsOps.realpath(candidate);
+        const inside = isWithin(root, real);
+        if (!inside && symlinks !== "follow")
+            return null;
+        // Under "follow" a target outside the root was explicitly allowed;
+        // there is no in-root name to check rules against.
+        if (inside && allow && !allow(canonicalSegments(root, real)))
+            return null;
+        const abs = symlinks === "follow" ? candidate : real;
+        const st = await fsOps.stat(abs);
+        if (!st.isFile() && !st.isDirectory())
+            return null;
+        return { abs, stat: st };
+    }
+    catch {
+        return null;
+    }
+}
+function canonicalSegments(root, real) {
+    return path.relative(root, real).split(path.sep).filter(Boolean);
+}

package/dist/static/response.d.ts

@@ -0,0 +1,53 @@
+import { type ResponseConfig } from "./options.ts";
+import type { StaticEncoding, StaticResponseOptions } from "./types.ts";
+/** A file ready to be served, with its fresh `stat`. */
+export interface ServableFile {
+    /** Path handed to `setHeaders` (relative for `staticFiles`). */
+    path: string;
+    /** Original file; decides `Content-Type` even when a variant is sent. */
+    contentTypeFrom: string;
+    /** File actually sent (original or `.br` / `.gz` sibling). */
+    abs: string;
+    size: number;
+    mtimeMs: number;
+    encoding?: StaticEncoding;
+}
+/** Per-response extras from `staticFiles` (rules, SPA fallback). */
+export interface ResponseExtras {
+    cacheControl?: string;
+    headers?: Record<string, string>;
+    /** SPA shell: force `no-cache` over options and rules. */
+    forceNoCache?: boolean;
+}
+/** Build the response for a resolved file: headers, conditionals, body. */
+export declare function buildFileResponse(req: Request, file: ServableFile, cfg: ResponseConfig, extras?: ResponseExtras): Response;
+/** Stat a candidate and return it only if it is a regular file. */
+export declare function statFile(abs: string): Promise<{
+    size: number;
+    mtimeMs: number;
+} | null>;
+/**
+ * Serve one known file from a handler, with the same headers, validators
+ * and pre-compressed negotiation as `staticFiles()`.
+ *
+ * `absPath` is trusted: never build it from request input — use
+ * `staticFiles()` for that. Throws `NotFoundError` when it is not a file.
+ *
+ * ```ts
+ * api.get("/report").handle(({ req }) => serveFile(req, reportPath));
+ * ```
+ */
+export declare function serveFile(req: Request, absPath: string, opts?: StaticResponseOptions): Promise<Response>;
+/**
+ * Choose an encoding among candidate sibling paths, stat the chosen file
+ * fresh, and fall back to the original when a variant has vanished.
+ */
+export declare function serveWithVariants(req: Request, cfg: ResponseConfig, target: {
+    path: string;
+    abs: string;
+    stat: {
+        size: number;
+        mtimeMs: number;
+    };
+    variants: Partial<Record<StaticEncoding, string>>;
+}, extras?: ResponseExtras): Promise<Response>;

package/dist/static/response.js

@@ -0,0 +1,146 @@
+import { stat } from "node:fs/promises";
+import { NotFoundError } from "../core/index.js";
+import { chooseEncoding, isNotModified, makeEtag } from "./negotiate.js";
+import { compileServeFileOptions } from "./options.js";
+/** Types that cannot run script, so `untrusted` may show them inline. */
+function isPassiveType(contentType) {
+    const type = contentType.split(";")[0].trim().toLowerCase();
+    if (type.startsWith("image/"))
+        return type !== "image/svg+xml";
+    return (type.startsWith("audio/") ||
+        type.startsWith("video/") ||
+        type === "text/plain" ||
+        type === "application/pdf");
+}
+// Headers a 304 keeps (RFC 9110 §15.4.5).
+const NOT_MODIFIED_HEADERS = [
+    "cache-control",
+    "content-location",
+    "etag",
+    "expires",
+    "last-modified",
+    "vary",
+];
+/** Build the response for a resolved file: headers, conditionals, body. */
+export function buildFileResponse(req, file, cfg, extras = {}) {
+    const contentType = Bun.file(file.contentTypeFrom).type;
+    const etag = cfg.etag
+        ? makeEtag(file.size, file.mtimeMs, file.encoding)
+        : undefined;
+    const headers = new Headers({
+        "Content-Type": contentType,
+        "X-Content-Type-Options": "nosniff",
+        "Cache-Control": cfg.cacheControl,
+    });
+    if (cfg.precompressed.length > 0)
+        headers.set("Vary", "Accept-Encoding");
+    if (etag)
+        headers.set("ETag", etag);
+    if (cfg.lastModified) {
+        headers.set("Last-Modified", new Date(file.mtimeMs).toUTCString());
+    }
+    if (file.encoding)
+        headers.set("Content-Encoding", file.encoding);
+    // Bun adds it itself to 206 responses; setting it too would duplicate it.
+    if (!req.headers.has("range"))
+        headers.set("Accept-Ranges", "bytes");
+    for (const [k, v] of Object.entries(cfg.headers))
+        headers.set(k, v);
+    if (extras.cacheControl)
+        headers.set("Cache-Control", extras.cacheControl);
+    for (const [k, v] of Object.entries(extras.headers ?? {}))
+        headers.set(k, v);
+    if (cfg.untrusted) {
+        headers.set("Content-Security-Policy", "sandbox; default-src 'none'");
+        if (!isPassiveType(contentType)) {
+            headers.set("Content-Disposition", "attachment");
+        }
+    }
+    if (extras.forceNoCache)
+        headers.set("Cache-Control", "no-cache");
+    cfg.setHeaders?.({
+        path: file.path,
+        size: file.size,
+        mtime: new Date(file.mtimeMs),
+        encoding: file.encoding,
+    }, headers);
+    if (isNotModified(req, etag, cfg.lastModified ? file.mtimeMs : undefined)) {
+        const kept = new Headers();
+        for (const name of NOT_MODIFIED_HEADERS) {
+            const value = headers.get(name);
+            if (value !== null)
+                kept.set(name, value);
+        }
+        return new Response(null, { status: 304, headers: kept });
+    }
+    // Bun applies Range / If-Range to file bodies and sends via sendfile.
+    return new Response(Bun.file(file.abs), { headers });
+}
+/** Stat a candidate and return it only if it is a regular file. */
+export async function statFile(abs) {
+    try {
+        const st = await stat(abs);
+        return st.isFile() ? { size: st.size, mtimeMs: st.mtimeMs } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Serve one known file from a handler, with the same headers, validators
+ * and pre-compressed negotiation as `staticFiles()`.
+ *
+ * `absPath` is trusted: never build it from request input — use
+ * `staticFiles()` for that. Throws `NotFoundError` when it is not a file.
+ *
+ * ```ts
+ * api.get("/report").handle(({ req }) => serveFile(req, reportPath));
+ * ```
+ */
+export async function serveFile(req, absPath, opts = {}) {
+    const cfg = compileServeFileOptions(opts);
+    const original = await statFile(absPath);
+    if (!original)
+        throw new NotFoundError();
+    const variants = {};
+    for (const enc of cfg.precompressed) {
+        variants[enc] = `${absPath}${enc === "br" ? ".br" : ".gz"}`;
+    }
+    return serveWithVariants(req, cfg, {
+        path: absPath,
+        abs: absPath,
+        stat: original,
+        variants,
+    });
+}
+/**
+ * Choose an encoding among candidate sibling paths, stat the chosen file
+ * fresh, and fall back to the original when a variant has vanished.
+ */
+export async function serveWithVariants(req, cfg, target, extras) {
+    const acceptEncoding = req.headers.get("accept-encoding");
+    let available = cfg.precompressed.filter((enc) => target.variants[enc]);
+    while (available.length > 0) {
+        const encoding = chooseEncoding(acceptEncoding, available);
+        if (!encoding)
+            break;
+        const abs = target.variants[encoding];
+        const st = await statFile(abs);
+        if (st) {
+            return buildFileResponse(req, {
+                path: target.path,
+                contentTypeFrom: target.abs,
+                abs,
+                ...st,
+                encoding,
+            }, cfg, extras);
+        }
+        available = available.filter((e) => e !== encoding);
+    }
+    return buildFileResponse(req, {
+        path: target.path,
+        contentTypeFrom: target.abs,
+        abs: target.abs,
+        ...target.stat,
+    }, cfg, extras);
+}

package/dist/static/router.d.ts

@@ -0,0 +1,59 @@
+/** `staticFiles()`, `spa()` and the `withStatic()` mixin. */
+import { type Router } from "../core/index.ts";
+import type { StaticEncoding, StaticOptions } from "./types.ts";
+/** Outcome of mapping a validated request path to the filesystem. */
+type Lookup = {
+    kind: "file";
+    /** Relative path of the file actually served (may be an index). */
+    rel: string;
+    abs: string;
+    variants: Partial<Record<StaticEncoding, string>>;
+} | {
+    kind: "redirect";
+} | {
+    kind: "missing";
+};
+/** A router serving a directory; `invalidate()` clears the lookup cache. */
+export type StaticRouter = Router<Record<never, never>, Record<never, never>> & {
+    invalidate(relPath?: string): void;
+};
+/**
+ * Serve a directory as a mountable router:
+ *
+ * ```ts
+ * app.add("/assets", staticFiles({ root: "./public" }));
+ * ```
+ *
+ * Paths are decoded and validated per segment, kept inside the (real) root,
+ * and dotfiles are hidden by default. Every rejection is a plain 404
+ * (`NotFoundError`), except undecodable `%` sequences (`BadRequestError`).
+ * Throws at creation on any misconfiguration.
+ */
+export declare function staticFiles(opts: StaticOptions): StaticRouter;
+/**
+ * Single-page app: `staticFiles()` with `index.html` as both the directory
+ * index and the fallback for unknown, extension-less HTML requests.
+ *
+ * ```ts
+ * app.add(api).add(spa({ root: "./dist", exclude: ["api/**"] }));
+ * ```
+ */
+export declare function spa(opts: Omit<StaticOptions, "fallback"> & {
+    fallback?: string;
+}): StaticRouter;
+/** Mixin sugar for `router.add(prefix, staticFiles(opts))`. */
+export declare function withStatic<R extends Router<any, any>>(router: R, prefix: string, opts: StaticOptions): R;
+/** Bounded LRU of lookups. Misses expire sooner than hits. Internal; exported for tests. */
+export declare class LookupCache {
+    #private;
+    constructor(opts: {
+        ttlMs: number;
+        maxEntries: number;
+    });
+    get size(): number;
+    get(key: string): Lookup | undefined;
+    set(key: string, lookup: Lookup): void;
+    delete(key: string): void;
+    invalidate(relPath?: string): void;
+}
+export {};