@fishenv/http 0.0.2 → 0.0.3

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 {};

package/dist/static/router.js

@@ -0,0 +1,217 @@
+/** `staticFiles()`, `spa()` and the `withStatic()` mixin. */
+import path from "node:path";
+import { BadRequestError, NotFoundError, r, } from "../core/index.js";
+import { acceptsHtml } from "./negotiate.js";
+import { compileStaticOptions, isServable, } from "./options.js";
+import { BAD_ENCODING, locate, parseRequestPath } from "./resolve.js";
+import { serveWithVariants, statFile, } from "./response.js";
+import { applyRules } from "./rules.js";
+/**
+ * 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 function staticFiles(opts) {
+    const cfg = compileStaticOptions(opts);
+    const cache = cfg.cache ? new LookupCache(cfg.cache) : null;
+    const router = r();
+    router.get("/:path*").handle(async ({ req, path: params }) => {
+        const raw = params.path;
+        const parsed = parseRequestPath(raw, cfg.windows);
+        if (parsed === BAD_ENCODING)
+            throw new BadRequestError();
+        if (parsed === null || !isServable(cfg, parsed.segments)) {
+            throw new NotFoundError();
+        }
+        const key = parsed.segments.join("/") + (parsed.trailingSlash ? "/" : "");
+        const found = await resolveFresh(cfg, cache, key, parsed);
+        if (found.kind === "file")
+            return serveLookup(req, cfg, found, found.stat);
+        if (found.kind === "redirect")
+            return redirectToDirectory(req);
+        if (cfg.fallback && isFallbackEligible(req, parsed.segments)) {
+            const shell = await withStat(await lookup(cfg, cfg.fallback, false));
+            if (shell?.kind === "file") {
+                return serveLookup(req, cfg, shell, shell.stat, { forceNoCache: true });
+            }
+        }
+        throw new NotFoundError();
+    });
+    return Object.defineProperty(router, "invalidate", {
+        value: (relPath) => cache?.invalidate(relPath),
+        enumerable: false,
+        configurable: true,
+    });
+}
+/**
+ * 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 function spa(opts) {
+    return staticFiles({
+        index: ["index.html"],
+        fallback: "index.html",
+        ...opts,
+    });
+}
+/** Mixin sugar for `router.add(prefix, staticFiles(opts))`. */
+// biome-ignore lint/suspicious/noExplicitAny: accepts routers of any context
+export function withStatic(router, prefix, opts) {
+    router.add(prefix, staticFiles(opts));
+    return router;
+}
+/** Attach a fresh stat to a file lookup; `null` if it is no longer a file. */
+async function withStat(found) {
+    if (found.kind !== "file")
+        return found;
+    const stat = await statFile(found.abs);
+    return stat ? { ...found, stat } : null;
+}
+/**
+ * Look up through the cache, but never build a response from a cached file
+ * without a fresh stat: a vanished or replaced entry is resolved again.
+ */
+async function resolveFresh(cfg, cache, key, parsed) {
+    const cached = cache?.get(key);
+    if (cached) {
+        const fresh = await withStat(cached);
+        if (fresh)
+            return fresh;
+        cache?.delete(key);
+    }
+    const found = await lookup(cfg, parsed.segments, parsed.trailingSlash);
+    const fresh = await withStat(found);
+    if (fresh) {
+        cache?.set(key, found);
+        return fresh;
+    }
+    return { kind: "missing" };
+}
+function serveLookup(req, cfg, found, stat, extras = {}) {
+    const rules = applyRules(cfg.rules, found.rel);
+    return serveWithVariants(req, cfg, { path: found.rel, abs: found.abs, stat, variants: found.variants }, { cacheControl: rules.cacheControl, headers: rules.headers, ...extras });
+}
+/** Steps 6–10: file, directory index, redirect, extension fallback. */
+async function lookup(cfg, segments, trailingSlash) {
+    const target = await locate(cfg.root, segments, cfg.symlinks, cfg.allowCanonical);
+    if (target?.stat.isDirectory()) {
+        if (cfg.index.length === 0)
+            return { kind: "missing" };
+        if (!trailingSlash)
+            return { kind: "redirect" };
+        for (const name of cfg.index) {
+            const found = await findFile(cfg, [...segments, name]);
+            if (found)
+                return found;
+        }
+        return { kind: "missing" };
+    }
+    if (target && !trailingSlash)
+        return withVariants(cfg, segments, target.abs);
+    if (!trailingSlash && segments.length > 0) {
+        const last = segments[segments.length - 1];
+        for (const ext of cfg.extensions) {
+            const found = await findFile(cfg, [
+                ...segments.slice(0, -1),
+                `${last}.${ext}`,
+            ]);
+            if (found)
+                return found;
+        }
+    }
+    return { kind: "missing" };
+}
+/** A derived candidate (index, extension) is checked like a request path. */
+async function findFile(cfg, segments) {
+    if (!isServable(cfg, segments))
+        return null;
+    const located = await locate(cfg.root, segments, cfg.symlinks, cfg.allowCanonical);
+    if (!located?.stat.isFile())
+        return null;
+    return withVariants(cfg, segments, located.abs);
+}
+async function withVariants(cfg, segments, abs) {
+    const variants = {};
+    const last = segments[segments.length - 1];
+    for (const enc of cfg.precompressed) {
+        const suffix = enc === "br" ? ".br" : ".gz";
+        const sibling = await locate(cfg.root, [...segments.slice(0, -1), last + suffix], cfg.symlinks, cfg.allowCanonical);
+        if (sibling?.stat.isFile())
+            variants[enc] = sibling.abs;
+    }
+    return { kind: "file", rel: segments.join("/"), abs, variants };
+}
+/**
+ * Redirect `/dir` to `/dir/` with a relative `Location` built from the last
+ * URL segment. `./` keeps a segment like `https:evil.com` from reading as an
+ * absolute URL; nothing here can produce `//host`.
+ */
+function redirectToDirectory(req) {
+    const url = new URL(req.url);
+    const last = url.pathname.slice(url.pathname.lastIndexOf("/") + 1);
+    return new Response(null, {
+        status: 301,
+        headers: { Location: `./${last}/${url.search}` },
+    });
+}
+function isFallbackEligible(req, segments) {
+    const last = segments[segments.length - 1] ?? "";
+    if (path.extname(last) !== "")
+        return false;
+    return acceptsHtml(req.headers.get("accept"));
+}
+/** Bounded LRU of lookups. Misses expire sooner than hits. Internal; exported for tests. */
+export class LookupCache {
+    #entries = new Map();
+    #ttlMs;
+    #maxEntries;
+    constructor(opts) {
+        this.#ttlMs = opts.ttlMs;
+        this.#maxEntries = opts.maxEntries;
+    }
+    get size() {
+        return this.#entries.size;
+    }
+    get(key) {
+        const entry = this.#entries.get(key);
+        if (!entry)
+            return undefined;
+        this.#entries.delete(key);
+        if (entry.expires <= Date.now())
+            return undefined;
+        this.#entries.set(key, entry); // most recently used goes last
+        return entry.lookup;
+    }
+    set(key, lookup) {
+        const ttl = lookup.kind === "missing" ? Math.min(this.#ttlMs, 1_000) : this.#ttlMs;
+        this.#entries.delete(key);
+        this.#entries.set(key, { lookup, expires: Date.now() + ttl });
+        while (this.#entries.size > this.#maxEntries) {
+            const oldest = this.#entries.keys().next().value;
+            this.#entries.delete(oldest);
+        }
+    }
+    delete(key) {
+        this.#entries.delete(key);
+    }
+    invalidate(relPath) {
+        if (relPath === undefined) {
+            this.#entries.clear();
+            return;
+        }
+        const key = relPath.replace(/^\/+/, "").replace(/\/+$/, "");
+        this.#entries.delete(key);
+        this.#entries.delete(`${key}/`);
+    }
+}

package/dist/static/rules.d.ts

@@ -0,0 +1,21 @@
+import type { StaticRule } from "./types.ts";
+export interface CompiledRule {
+    regex: RegExp;
+    rule: StaticRule;
+}
+export interface RuleResult {
+    deny: boolean;
+    cacheControl?: string;
+    headers: Record<string, string>;
+}
+/**
+ * Compile a route-style glob for matching relative file paths. Reuses the
+ * route compiler so there is one glob dialect and no user-supplied RegExp.
+ * Matching is case-insensitive so deny rules hold on case-insensitive disks.
+ */
+export declare function compileGlob(pattern: string): RegExp;
+/** True when `rel` (no leading slash) matches the compiled glob. */
+export declare function matchesGlob(regex: RegExp, rel: string): boolean;
+export declare function compileRules(rules: StaticRule[]): CompiledRule[];
+/** Fold every matching rule in order; later rules win per field. */
+export declare function applyRules(rules: CompiledRule[], rel: string): RuleResult;

package/dist/static/rules.js

@@ -0,0 +1,49 @@
+import { buildRouteRegex } from "../core/index.js";
+/**
+ * Compile a route-style glob for matching relative file paths. Reuses the
+ * route compiler so there is one glob dialect and no user-supplied RegExp.
+ * Matching is case-insensitive so deny rules hold on case-insensitive disks.
+ */
+export function compileGlob(pattern) {
+    if (typeof pattern !== "string" || pattern.trim() === "") {
+        throw new Error("static: glob patterns must be non-empty strings");
+    }
+    const trimmed = pattern.replace(/^\/+/, "");
+    if (trimmed.split("/").some((seg) => seg.startsWith(":"))) {
+        throw new Error(`static: glob "${pattern}" has a ":param" segment; use * or ** instead`);
+    }
+    const { regex } = buildRouteRegex(`/${trimmed}`);
+    return new RegExp(regex.source, "i");
+}
+/** True when `rel` (no leading slash) matches the compiled glob. */
+export function matchesGlob(regex, rel) {
+    return regex.test(`/${rel}`);
+}
+export function compileRules(rules) {
+    return rules.map((rule) => {
+        if (typeof rule !== "object" || rule === null) {
+            throw new Error("static: each rule must be an object");
+        }
+        for (const key of Object.keys(rule)) {
+            if (!["match", "cacheControl", "headers", "deny"].includes(key)) {
+                throw new Error(`static: unknown rule option "${key}"`);
+            }
+        }
+        return { regex: compileGlob(rule.match), rule };
+    });
+}
+/** Fold every matching rule in order; later rules win per field. */
+export function applyRules(rules, rel) {
+    const result = { deny: false, headers: {} };
+    for (const { regex, rule } of rules) {
+        if (!matchesGlob(regex, rel))
+            continue;
+        if (rule.deny !== undefined)
+            result.deny = rule.deny;
+        if (rule.cacheControl !== undefined)
+            result.cacheControl = rule.cacheControl;
+        if (rule.headers)
+            Object.assign(result.headers, rule.headers);
+    }
+    return result;
+}

package/dist/static/types.d.ts

@@ -0,0 +1,76 @@
+/** Pre-compressed sibling encodings: `file.br` and `file.gz`. */
+export type StaticEncoding = "br" | "gzip";
+/** Per-path overrides, matched against the decoded relative path. */
+export interface StaticRule {
+    /** Route-style glob (`*`, `**`, `{a,b}`), matched case-insensitively. */
+    match: string;
+    cacheControl?: string;
+    headers?: Record<string, string>;
+    /** Respond 404 as if the file did not exist. */
+    deny?: boolean;
+}
+/** What `setHeaders` learns about the file being served. */
+export interface StaticFileInfo {
+    /** Relative `/`-joined path inside the root (absolute for `serveFile`). */
+    path: string;
+    size: number;
+    mtime: Date;
+    /** Set when a pre-compressed sibling is served. */
+    encoding?: StaticEncoding;
+}
+export type SetHeadersFn = (info: StaticFileInfo, headers: Headers) => void;
+/** Response options shared by `staticFiles()` and `serveFile()`. */
+export interface StaticResponseOptions {
+    /** Sibling encodings to look for, in server preference order. Default `[]`. */
+    precompressed?: StaticEncoding[];
+    /** Default `true`. */
+    etag?: boolean;
+    /** Default `true`. */
+    lastModified?: boolean;
+    /** Default `"no-cache"`. */
+    cacheControl?: string;
+    /** Added to every file response. */
+    headers?: Record<string, string>;
+    /**
+     * Serve files as untrusted (user uploads): CSP sandbox on every response and
+     * `Content-Disposition: attachment` for anything but passive media types.
+     */
+    untrusted?: boolean;
+    /** Runs last; may override any header. */
+    setHeaders?: SetHeadersFn;
+}
+export interface StaticCacheOptions {
+    /** Default 5000. */
+    ttlMs?: number;
+    /** Default 10000. */
+    maxEntries?: number;
+}
+export interface StaticOptions extends StaticResponseOptions {
+    /** Directory to serve. Resolved through symlinks once, at creation. */
+    root: string;
+    /** File names tried for directory requests. Default `["index.html"]`. */
+    index?: string[];
+    /** Extensions tried for extension-less misses, e.g. `["html"]`. Default `[]`. */
+    extensions?: string[];
+    /** `"hide"` (default) answers 404 for any path segment starting with `.`. */
+    dotfiles?: "hide" | "allow";
+    /** Dot-segments still served under `dotfiles: "hide"`, e.g. `[".well-known"]`. */
+    allowDotfiles?: string[];
+    /**
+     * `"within-root"` (default) follows links whose target stays inside the
+     * root; `"deny"` refuses any link; `"follow"` follows links anywhere.
+     * Defaults to `"deny"` when `untrusted` is set.
+     */
+    symlinks?: "within-root" | "deny" | "follow";
+    /** Ordered per-path overrides; later rules win per field. */
+    rules?: StaticRule[];
+    /** Globs this router never serves (and never falls back for). */
+    exclude?: string[];
+    /**
+     * File served for unknown extension-less paths when the client accepts
+     * HTML (SPA routing), e.g. `"index.html"`. Always sent `no-cache`.
+     */
+    fallback?: string;
+    /** Cache path resolution (not contents). `true` uses the defaults. */
+    cache?: boolean | StaticCacheOptions;
+}