@fishenv/http 0.0.2 → 0.0.4

package/dist/sse/types.d.ts

@@ -2,6 +2,7 @@
  * Shared SSE data types. Deliberately free of class references so every other
  * module in this package can import from here without a cycle.
  */
+import type { Transport, TransportEnvelope } from "../core/transport.ts";
 export interface SseEventOptions {
     /** `event:` field — the client-side listener name. Defaults to `message`. */
     event?: string;
@@ -25,7 +26,7 @@ export interface SseConnectionOptions {
     onOverflow?: SseOverflowPolicy;
 }
 /** Cross-process fan-out envelope. Must be JSON-serializable. */
-export interface SseTransportMessage {
+export interface SseTransportMessage extends TransportEnvelope {
     /** `null` means broadcast to every connection. */
     key: string | null;
     data: unknown;
@@ -36,10 +37,7 @@ export interface SseTransportMessage {
     origin: string;
 }
 /** Seam for multi-instance deployments (Redis pub/sub, NATS, Postgres LISTEN…). */
-export interface SseTransport {
-    publish(message: SseTransportMessage): void | Promise<void>;
-    subscribe(onMessage: (message: SseTransportMessage) => void): () => void;
-}
+export type SseTransport = Transport<SseTransportMessage>;
 export interface SseHubOptions {
     transport?: SseTransport;
 }

package/dist/static/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Static file serving for `@fishenv/http`.
+ *
+ * `staticFiles()` returns an ordinary router, so it is mounted, prefixed and
+ * wrapped in middleware like any other:
+ *
+ * ```ts
+ * app.add("/assets", staticFiles({ root: "./public" }));
+ * app.add(api).add(spa({ root: "./dist", exclude: ["api/**"] }));
+ * ```
+ *
+ * Requests are decoded and validated per segment, confined to the real root
+ * (symlinks included), dotfiles are hidden and every rejection is a plain 404.
+ *
+ * Module layout:
+ * - `types.ts`     — option and rule types
+ * - `options.ts`   — validation and normalization at creation (throws)
+ * - `resolve.ts`   — request path → file on disk (the security core)
+ * - `rules.ts`     — route-style globs for rules and `exclude`
+ * - `negotiate.ts` — Accept-Encoding, Accept and conditional requests
+ * - `response.ts`  — headers and body; `serveFile()`
+ * - `router.ts`    — `staticFiles()`, `spa()`, `withStatic()`
+ */
+export { serveFile } from "./response.ts";
+export type { StaticRouter } from "./router.ts";
+export { spa, staticFiles, withStatic } from "./router.ts";
+export type { SetHeadersFn, StaticCacheOptions, StaticEncoding, StaticFileInfo, StaticOptions, StaticResponseOptions, StaticRule, } from "./types.ts";

package/dist/static/index.js

@@ -0,0 +1,25 @@
+/**
+ * Static file serving for `@fishenv/http`.
+ *
+ * `staticFiles()` returns an ordinary router, so it is mounted, prefixed and
+ * wrapped in middleware like any other:
+ *
+ * ```ts
+ * app.add("/assets", staticFiles({ root: "./public" }));
+ * app.add(api).add(spa({ root: "./dist", exclude: ["api/**"] }));
+ * ```
+ *
+ * Requests are decoded and validated per segment, confined to the real root
+ * (symlinks included), dotfiles are hidden and every rejection is a plain 404.
+ *
+ * Module layout:
+ * - `types.ts`     — option and rule types
+ * - `options.ts`   — validation and normalization at creation (throws)
+ * - `resolve.ts`   — request path → file on disk (the security core)
+ * - `rules.ts`     — route-style globs for rules and `exclude`
+ * - `negotiate.ts` — Accept-Encoding, Accept and conditional requests
+ * - `response.ts`  — headers and body; `serveFile()`
+ * - `router.ts`    — `staticFiles()`, `spa()`, `withStatic()`
+ */
+export { serveFile } from "./response.js";
+export { spa, staticFiles, withStatic } from "./router.js";

package/dist/static/negotiate.d.ts

@@ -0,0 +1,23 @@
+import type { StaticEncoding } from "./types.ts";
+interface QItem {
+    value: string;
+    q: number;
+}
+/** Parse a `token;q=0.5, other` header into lowercase values with weights. */
+export declare function parseQList(header: string): QItem[];
+/**
+ * Pick the best available encoding for an `Accept-Encoding` header. Highest
+ * q wins; ties go to `available` order (server preference). `q=0` refuses a
+ * coding, `*` covers codings not listed. No header means identity only.
+ */
+export declare function chooseEncoding(header: string | null, available: StaticEncoding[]): StaticEncoding | undefined;
+/** True when the client accepts an HTML document (used for SPA fallback). */
+export declare function acceptsHtml(header: string | null): boolean;
+/** Weak ETag from size + mtime (no inode), suffixed per encoding. */
+export declare function makeEtag(size: number, mtimeMs: number, encoding?: StaticEncoding): string;
+/**
+ * Evaluate `If-None-Match` (weak comparison, `*`, lists), falling back to
+ * `If-Modified-Since` only when `If-None-Match` is absent (RFC 9110 §13.2.2).
+ */
+export declare function isNotModified(req: Request, etag: string | undefined, mtimeMs: number | undefined): boolean;
+export {};

package/dist/static/negotiate.js

@@ -0,0 +1,85 @@
+/** Parse a `token;q=0.5, other` header into lowercase values with weights. */
+export function parseQList(header) {
+    const items = [];
+    for (const part of header.split(",")) {
+        const [rawValue, ...params] = part.split(";");
+        const value = rawValue.trim().toLowerCase();
+        if (!value)
+            continue;
+        let q = 1;
+        for (const param of params) {
+            const [k, v] = param.split("=").map((s) => s.trim());
+            if (k.toLowerCase() === "q") {
+                const n = Number(v);
+                q = Number.isFinite(n) ? Math.min(Math.max(n, 0), 1) : 0;
+            }
+        }
+        items.push({ value, q });
+    }
+    return items;
+}
+const CODING_NAMES = {
+    br: ["br"],
+    gzip: ["gzip", "x-gzip"],
+};
+/**
+ * Pick the best available encoding for an `Accept-Encoding` header. Highest
+ * q wins; ties go to `available` order (server preference). `q=0` refuses a
+ * coding, `*` covers codings not listed. No header means identity only.
+ */
+export function chooseEncoding(header, available) {
+    if (!header || available.length === 0)
+        return undefined;
+    const items = parseQList(header);
+    const star = items.find((i) => i.value === "*")?.q;
+    let best;
+    let bestQ = 0;
+    for (const enc of available) {
+        const explicit = items.find((i) => CODING_NAMES[enc].includes(i.value));
+        const q = explicit?.q ?? star ?? 0;
+        if (q > bestQ) {
+            best = enc;
+            bestQ = q;
+        }
+    }
+    return best;
+}
+/** True when the client accepts an HTML document (used for SPA fallback). */
+export function acceptsHtml(header) {
+    if (!header)
+        return true;
+    return parseQList(header).some((i) => i.q > 0 &&
+        (i.value === "text/html" || i.value === "text/*" || i.value === "*/*"));
+}
+/** Weak ETag from size + mtime (no inode), suffixed per encoding. */
+export function makeEtag(size, mtimeMs, encoding) {
+    const suffix = encoding ? `-${encoding}` : "";
+    return `W/"${size.toString(16)}-${Math.floor(mtimeMs).toString(16)}${suffix}"`;
+}
+function opaqueTag(tag) {
+    return tag.trim().replace(/^W\//, "");
+}
+/**
+ * Evaluate `If-None-Match` (weak comparison, `*`, lists), falling back to
+ * `If-Modified-Since` only when `If-None-Match` is absent (RFC 9110 §13.2.2).
+ */
+export function isNotModified(req, etag, mtimeMs) {
+    const inm = req.headers.get("if-none-match");
+    if (inm !== null) {
+        if (!etag)
+            return false;
+        if (inm.trim() === "*")
+            return true;
+        const ours = opaqueTag(etag);
+        return inm.split(",").some((t) => opaqueTag(t) === ours);
+    }
+    const ims = req.headers.get("if-modified-since");
+    if (ims !== null && mtimeMs !== undefined) {
+        const since = Date.parse(ims);
+        if (Number.isNaN(since))
+            return false;
+        // HTTP dates have second precision.
+        return Math.floor(mtimeMs / 1000) * 1000 <= since;
+    }
+    return false;
+}

package/dist/static/options.d.ts

@@ -0,0 +1,44 @@
+import { type CanonicalCheck, type SymlinkPolicy } from "./resolve.ts";
+import { type CompiledRule } from "./rules.ts";
+import type { SetHeadersFn, StaticEncoding, StaticOptions, StaticResponseOptions } from "./types.ts";
+/** Normalized response options. */
+export interface ResponseConfig {
+    precompressed: StaticEncoding[];
+    etag: boolean;
+    lastModified: boolean;
+    cacheControl: string;
+    headers: Record<string, string>;
+    untrusted: boolean;
+    setHeaders?: SetHeadersFn;
+}
+export interface StaticConfig extends ResponseConfig {
+    root: string;
+    index: string[];
+    extensions: string[];
+    dotfiles: "hide" | "allow";
+    allowDotfiles: Set<string>;
+    symlinks: SymlinkPolicy;
+    rules: CompiledRule[];
+    exclude: RegExp[];
+    fallback?: string[];
+    cache?: {
+        ttlMs: number;
+        maxEntries: number;
+    };
+    windows: boolean;
+    /** `passesFilePolicy` bound to this config, for `locate()`. */
+    allowCanonical: CanonicalCheck;
+}
+/** Validate and normalize the options shared with `serveFile()`. */
+export declare function compileResponseOptions(opts: StaticResponseOptions): ResponseConfig;
+export declare function compileServeFileOptions(opts: StaticResponseOptions): ResponseConfig;
+/** True when `segments` may be served at all (dotfiles, deny, exclude). */
+export declare function isServable(cfg: StaticConfig, segments: string[]): boolean;
+/**
+ * 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 declare function passesFilePolicy(cfg: StaticConfig, segments: string[]): boolean;
+/** Validate options and resolve the root. Throws on any misconfiguration. */
+export declare function compileStaticOptions(opts: StaticOptions): StaticConfig;

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