@thi.ng/server/static.d.ts

Minimal HTTP server with declarative routing, static file serving and freely extensible via pre/post interceptors

import type { Fn, MaybePromise, Predicate } from "@thi.ng/api";
import { type HashAlgo } from "@thi.ng/file-io";
import type { OutgoingHttpHeaders } from "node:http";
import type { Interceptor, RequestCtx, ServerRoute } from "./api.js";
/**
 * Static file configuration options.
 */
export interface StaticOpts<CTX extends RequestCtx = RequestCtx> {
    /**
     * Path to local root directory for static assets. Also see
     * {@link StaticOpts.prefix}
     *
     * @defaultValue `.` (current cwd)
     */
    rootDir: string;
    /**
     * Filter predicates to validate & exclude file paths from being served.
     * Executed in given order and each one called with the absolute local file
     * path. If any of the predicates returns false, the server produces a 404
     * response. By default only uses {@link pathFilterASCII}.
     */
    filters: Predicate<string>[];
    /**
     * URL path prefix for defining the static assets route. Also see
     * {@link StaticOpts.rootDir}.
     *
     * @remarks
     * If given as array, each item is a path component, i.e. `["public",
     * "img"]` is the same as `"/public/img"`.
     *
     * @defaultValue "static"
     */
    prefix: string | string[];
    /**
     * Additional route specific interceptors.
     */
    intercept: Interceptor<CTX>[];
    /**
     * Additional common headers (e.g. cache control) for a file. If given as
     * function, it will be called with the absolute path (the function will
     * only be called if the path exists and already has passed validation).
     */
    headers: OutgoingHttpHeaders | Fn<string, OutgoingHttpHeaders>;
    /**
     * If true (default: false), files will be served with brotli, gzip or deflate
     * compression (if the client supports it).
     *
     * @remarks
     * Note: Whilst compression can
     *
     * @defaultValue false
     */
    compress: boolean;
    /**
     * User defined function to compute an Etag value for given file path. The
     * file is guaranteed to exist when this function is called.
     */
    etag: Fn<string, MaybePromise<string>>;
    /**
     * If true, the route will have its `auth` flag enabled, e.g. for use with
     * the {@link authenticateWith} interceptor.
     *
     * @defaultValue false
     */
    auth: boolean;
}
/**
 * Defines a configurable {@link ServerRoute} and handler for serving static
 * files from a local directory (optionally with compression, see
 * {@link StaticOpts.compress} for details).
 *
 * @param opts
 */
export declare const staticFiles: <CTX extends RequestCtx = RequestCtx>({ prefix, rootDir, intercept, filters, compress, auth, etag, headers, }?: Partial<StaticOpts<CTX>>) => ServerRoute<CTX>;
/**
 * Etag header value function for {@link StaticOpts.etag}. Computes Etag based
 * on base36-encoded file modified timestamp.
 *
 * @remarks
 * Also see {@link etagFileHash}.
 *
 * @param path
 */
export declare const etagFileTimeModified: (path: string) => string;
/**
 * Higher-order Etag header value function for {@link StaticOpts.etag}. Computes
 * Etag value by computing the hash digest of a given file. Uses MD5 by default.
 *
 * @remarks
 * Also see {@link etagFileTimeModified}.
 *
 * @param algo
 */
export declare const etagFileHash: (algo?: HashAlgo) => (path: string) => Promise<string>;
/**
 * Default path filter predicate for {@link StaticOpts.filter}. Rejects a file
 * path which contains non-printable ASCII chars (i.e. outside the
 * `[0x20,0x7fe]` range).
 *
 * @param path
 */
export declare const pathFilterASCII: (path: string) => boolean;
/**
 * Higher order path filter predicate for {@link StaticOpts.filter}. The
 * returned predicate rejects an absolute file path if its length exceeds given
 * `limit`.
 *
 * @param limit
 */
export declare const pathMaxLength: (limit: number) => Predicate<string>;
//# sourceMappingURL=static.d.ts.map