@decohere/http 0.0.1-dev.125 → 0.0.1-dev.5

package/src/openapi/request-validator.ts

@@ -0,0 +1,95 @@
+import { Ajv, type ErrorObject, type ValidateFunction } from "ajv";
+import type { HttpRequest, MappedRoute, ValidationIssue } from "../routing/anvil.types.js";
+import { ValidationError } from "../routing/anvil.types.js";
+import { buildRouteRequestSchemas, pathParamsToSchema } from "./request-schema.js";
+
+export type { ValidationIssue };
+export { ValidationError };
+
+/**
+ * Fail-closed request validation from route / OpenAPI / `@Field` metadata.
+ * Uses AJV against the same schemas as the OpenAPI generator (no type coercion).
+ */
+export function validateRequest(route: MappedRoute, request: HttpRequest): void {
+	const { params, body } = getValidators(route);
+	const issues: ValidationIssue[] = [];
+
+	if (params != null) {
+		collectIssues(params, request.params ?? {}, "/params", issues);
+	}
+	if (body != null) {
+		collectIssues(body, request.body, "/body", issues);
+	}
+
+	if (issues.length > 0) {
+		throw new ValidationError("Validation failed", issues);
+	}
+}
+
+const ajv = new Ajv({
+	allErrors: true,
+	coerceTypes: false,
+	removeAdditional: false,
+	useDefaults: false,
+	strict: false,
+});
+
+type RouteValidators = { params?: ValidateFunction; body?: ValidateFunction };
+
+/**
+ * Compiled once per route and reused. Compiling per request was slow, and AJV keeps every
+ * schema it compiles, so memory grew with traffic (#498).
+ */
+const validatorsByRoute = new WeakMap<MappedRoute, RouteValidators>();
+
+function getValidators(route: MappedRoute): RouteValidators {
+	let validators = validatorsByRoute.get(route);
+	if (validators == null) {
+		const schemas = buildRouteRequestSchemas(route);
+		const paramsSchema = pathParamsToSchema(schemas.pathParams);
+		validators = {
+			params: paramsSchema != null ? ajv.compile(paramsSchema) : undefined,
+			body: schemas.body != null ? ajv.compile(schemas.body) : undefined,
+		};
+		validatorsByRoute.set(route, validators);
+	}
+	return validators;
+}
+
+function collectIssues(
+	validate: ValidateFunction,
+	data: unknown,
+	rootPath: string,
+	issues: ValidationIssue[],
+): void {
+	if (validate(data)) {
+		return;
+	}
+	for (const err of validate.errors ?? []) {
+		issues.push(toIssue(err, rootPath));
+	}
+}
+
+function toIssue(err: ErrorObject, rootPath: string): ValidationIssue {
+	const instance = err.instancePath ?? "";
+	const path = instance.length > 0 ? `${rootPath}${instance}` : rootPath;
+	const message = err.message ?? "is invalid";
+	return {
+		path,
+		message: formatAjvMessage(err, message),
+		keyword: err.keyword,
+	};
+}
+
+function formatAjvMessage(err: ErrorObject, fallback: string): string {
+	if (err.keyword === "required" && typeof err.params?.missingProperty === "string") {
+		return `must have required property '${err.params.missingProperty}'`;
+	}
+	if (
+		err.keyword === "additionalProperties" &&
+		typeof err.params?.additionalProperty === "string"
+	) {
+		return `must NOT have additional property '${err.params.additionalProperty}'`;
+	}
+	return fallback;
+}

package/src/providers/fastify.provider.ts

@@ -0,0 +1,454 @@
+import { randomUUID } from "node:crypto";
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { inject } from "@decohere/di/decorators";
+import { scribe } from "@decohere/scribe";
+import compress from "@fastify/compress";
+import cors from "@fastify/cors";
+import helmet from "@fastify/helmet";
+import rateLimit from "@fastify/rate-limit";
+import fastifyStatic from "@fastify/static";
+import Fastify, {
+	type FastifyInstance,
+	type FastifyReply,
+	type FastifyRequest,
+} from "fastify";
+import {
+	ExceptionFilterHostToken,
+	HttpOptionsToken,
+	RouteRegistryToken,
+	RouterToken,
+} from "../const.js";
+import type { HttpOptions } from "../http/http.options.js";
+import {
+	DEFAULT_HTTP_BODY_LIMIT,
+	DEFAULT_HTTP_RATE_LIMIT,
+	type HelmetOptions,
+	type RateLimitOptions,
+} from "../http/http.security.js";
+import {
+	type CompressionOptions,
+	DEFAULT_COMPRESSION_ENCODINGS,
+	DEFAULT_COMPRESSION_THRESHOLD,
+} from "../http/http.compression.js";
+import { type ResolvedStaticMount, staticFiles } from "../http/http.static.js";
+import { generateOpenApiDocument, resolveOpenApiPath } from "../openapi/openapi.generator.js";
+import {
+	type CorsOptions,
+	type HttpProvider,
+	HttpRequest,
+	type MappedRoute,
+	type StartOptions,
+	type StartResponse,
+	type StopResponse,
+} from "../routing/anvil.types.js";
+import {
+	DefaultHttpExceptionFilter,
+	type ExceptionFilterHost,
+} from "../routing/filters/exception-filter-host.js";
+import { REQUEST_ID_HEADER, resolveRequestId } from "../routing/middleware/request-id.js";
+import { normalizePrefix } from "../routing/path.util.js";
+import type { RouteRegistry } from "../routing/services/route-registry.js";
+import type { Router } from "../routing/services/router.js";
+import { encodeSse } from "../sse/sse.encoder.js";
+import { DEFAULT_SSE_HEARTBEAT_MS, SseResponse } from "../sse/sse.types.js";
+
+export class FastifyProvider implements HttpProvider {
+	public readonly provider: FastifyInstance;
+	public readonly router: Router;
+	private readonly routeRegistry: RouteRegistry;
+	private readonly httpOptions?: HttpOptions;
+	private readonly exceptionFilterHost?: ExceptionFilterHost;
+	private closing: Promise<void> | undefined;
+	private readonly logger = scribe.logger(FastifyProvider.name);
+	/** One per live `@Sse()` request, so stopping the app can end the streams. */
+	private readonly openStreams = new Set<AbortController>();
+
+	public constructor(
+		@inject(RouteRegistryToken) routeRegistry?: RouteRegistry,
+		@inject(RouterToken) router?: Router,
+		@inject(HttpOptionsToken) httpOptions?: HttpOptions,
+		@inject(ExceptionFilterHostToken) exceptionFilterHost?: ExceptionFilterHost,
+	) {
+		this.routeRegistry = routeRegistry;
+		this.router = router;
+		this.httpOptions = httpOptions;
+		this.exceptionFilterHost = exceptionFilterHost;
+		this.provider = Fastify({
+			logger: false,
+			requestIdHeader: REQUEST_ID_HEADER,
+			genReqId: () => randomUUID(),
+			bodyLimit: httpOptions?.bodyLimit ?? DEFAULT_HTTP_BODY_LIMIT,
+		});
+	}
+
+	public async start<T extends StartOptions>(options?: T): Promise<StartResponse> {
+		const statics = await this.resolveStatics();
+		await this.registerHelmet(this.httpOptions?.helmet);
+		await this.registerRateLimit(this.httpOptions?.rateLimit, statics);
+		await this.registerCors(this.httpOptions?.cors);
+		await this.registerCompression(this.httpOptions?.compression);
+		this.registerOpenApi(this.httpOptions);
+		this.registerAllRoutes(this.routeRegistry);
+		for (const mount of statics) {
+			await this.registerStatic(mount, statics);
+		}
+		this.closeConnectionsWhileStopping();
+		await this.provider.listen(options);
+		return {
+			addresses: this.addresses,
+		};
+	}
+
+	public async stop(): Promise<StopResponse> {
+		// App stops HTTP before disposing the container, which calls this again.
+		// A stream never finishes on its own, and close() waits for open responses, so end them first.
+		for (const stream of this.openStreams) {
+			stream.abort(new Error("The app is stopping"));
+		}
+		this.closing ??= this.provider.close();
+		await this.closing;
+		return { message: "closed" };
+	}
+
+	public async [Symbol.asyncDispose](): Promise<void> {
+		await this.stop();
+	}
+
+	/**
+	 * Once stopping, tell clients to drop the connection after their response. Otherwise
+	 * a request that was in flight leaves a kept-alive socket that holds `close()` open
+	 * until Node's keep-alive timeout (5s).
+	 */
+	private closeConnectionsWhileStopping() {
+		this.provider.addHook("onSend", async (_request, reply, payload) => {
+			if (this.closing) reply.header("connection", "close");
+			return payload;
+		});
+	}
+
+	public get addresses() {
+		return this.provider
+			.addresses()
+			.filter((a) => a.family === "IPv4")
+			.map((a) => `http://${a.address}:${a.port}`);
+	}
+
+	private async registerHelmet(helmetOptions?: HelmetOptions) {
+		if (helmetOptions === false) {
+			return;
+		}
+		await this.provider.register(helmet, helmetOptions ?? {});
+	}
+
+	private async registerRateLimit(
+		rateLimitOptions: RateLimitOptions | undefined,
+		statics: readonly ResolvedStaticMount[],
+	) {
+		if (rateLimitOptions === false) {
+			return;
+		}
+		// Static files are outside the rate limit (ADR 0007). Matched on the route the request
+		// resolved to, not on its URL, so only requests the static plugin serves are exempt.
+		const staticRoutes = new Set(statics.map((mount) => `${mount.prefix}*`));
+		const userAllowList = rateLimitOptions?.allowList;
+		await this.provider.register(rateLimit, {
+			...DEFAULT_HTTP_RATE_LIMIT,
+			...rateLimitOptions,
+			allowList: (request: FastifyRequest, key: string) => {
+				if (staticRoutes.has(request.routeOptions.url ?? "")) return true;
+				if (typeof userAllowList === "function") return userAllowList(request, key);
+				return Array.isArray(userAllowList) && userAllowList.includes(key);
+			},
+		});
+	}
+
+	private async resolveStatics(): Promise<ResolvedStaticMount[]> {
+		return staticFiles.resolve(this.httpOptions?.statics ?? [], {
+			nodeEnv: process.env.NODE_ENV,
+			directoryExists: async (directory) =>
+				(await stat(directory).catch(() => undefined))?.isDirectory() === true,
+			warn: (message) => this.logger.warn(message),
+		});
+	}
+
+	/**
+	 * One encapsulated context per mount: its not-found handler (the SPA fallback) applies to
+	 * paths under the prefix and nowhere else, so an API 404 is never answered with the UI.
+	 */
+	private async registerStatic(
+		mount: ResolvedStaticMount,
+		mounts: readonly ResolvedStaticMount[],
+	) {
+		const withoutSlash = mount.prefix.slice(0, -1);
+		const isRoot = mount.prefix === "/";
+		const excluded = staticFiles.excluder(mount.exclude);
+		const belongsToApi = this.apiBoundary();
+		// Requests that already fell back once: a missing index must be a 404, not a loop.
+		const fellBack = new WeakSet<FastifyRequest>();
+		await this.provider.register(
+			async (scope) => {
+				await scope.register(fastifyStatic, {
+					root: mount.root,
+					prefix: "/",
+					index: mount.index,
+					dotfiles: "ignore",
+					list: false,
+					redirect: false,
+					etag: true,
+					lastModified: true,
+					// The header is set in setHeaders, per file.
+					cacheControl: false,
+					setHeaders: (reply, filePath) => {
+						reply.header(
+							"cache-control",
+							staticFiles.cacheControlFor(mount, path.relative(mount.root, filePath)),
+						);
+					},
+				});
+				// Excluded paths are not served at all: not as a file, not as the fallback.
+				scope.addHook("onRequest", async (request, reply) => {
+					if (excluded(staticFiles.normalizePathname(request.url))) {
+						return reply.callNotFound();
+					}
+				});
+				scope.setNotFoundHandler((request, reply) => {
+					const [pathname = "", query] = request.url.split("?");
+					const readOnly = request.method === "GET" || request.method === "HEAD";
+					// `/ui` goes to `/ui/`. A request for it reaches the root mount's handler instead
+					// when there is one, so that handler redirects for the other mounts too.
+					const redirectTo = mounts.find(
+						(other) =>
+							other.prefix !== "/" &&
+							other.prefix.slice(0, -1) === pathname &&
+							(isRoot || other === mount),
+					);
+					if (readOnly && redirectTo != null) {
+						return reply.redirect(
+							query == null ? redirectTo.prefix : `${redirectTo.prefix}?${query}`,
+							301,
+						);
+					}
+					const normalized = staticFiles.normalizePathname(request.url);
+					if (
+						mount.spaFallback &&
+						!fellBack.has(request) &&
+						!excluded(normalized) &&
+						staticFiles.shouldFallBack(
+							{ method: request.method, pathname: normalized, accept: request.headers.accept },
+							belongsToApi,
+						)
+					) {
+						fellBack.add(request);
+						return reply.sendFile(mount.index);
+					}
+					return reply.code(404).send({
+						message: `Route ${request.method}:${pathname} not found`,
+						error: "Not Found",
+						statusCode: 404,
+					});
+				});
+			},
+			{ prefix: withoutSlash },
+		);
+	}
+
+	/** What the static fallback leaves to the API: the global prefix, else the registered routes. ADR 0007. */
+	private apiBoundary(): (pathname: string) => boolean {
+		return staticFiles.apiBoundary({
+			globalPrefix: normalizePrefix(this.httpOptions?.globalPrefix),
+			openApiPath:
+				this.httpOptions?.openapi == null
+					? undefined
+					: resolveOpenApiPath(this.httpOptions.openapi),
+			routePaths: [...this.routeRegistry.routes].map((route) => route.path),
+		});
+	}
+
+	/**
+	 * `@fastify/compress` with best-practice defaults; the plugin owns the policy. Registered
+	 * before any route so every response goes through it, errors and static files included.
+	 * `providerOptions` is merged last, so a user can override any plugin option.
+	 */
+	private async registerCompression(compressionOptions: CompressionOptions | undefined) {
+		if (compressionOptions === false) {
+			return;
+		}
+		await this.provider.register(compress, {
+			global: true,
+			threshold: compressionOptions?.threshold ?? DEFAULT_COMPRESSION_THRESHOLD,
+			encodings: [...(compressionOptions?.encodings ?? DEFAULT_COMPRESSION_ENCODINGS)],
+			...(compressionOptions?.types != null && { customTypes: compressionOptions.types }),
+			...compressionOptions?.providerOptions,
+		});
+	}
+
+	private async registerCors(corsOptions?: CorsOptions) {
+		if (corsOptions == null) {
+			return;
+		}
+		await this.provider.register(cors, {
+			origin: corsOptions.origin,
+			methods: corsOptions.methods,
+			allowedHeaders: corsOptions.allowedHeaders,
+			exposedHeaders: corsOptions.exposedHeaders,
+			credentials: corsOptions.credentials,
+			maxAge: corsOptions.maxAge,
+		});
+	}
+
+	private registerOpenApi(httpOptions?: HttpOptions) {
+		const openapi = httpOptions?.openapi;
+		if (openapi == null) {
+			return;
+		}
+		const path = resolveOpenApiPath(openapi);
+		const document = generateOpenApiDocument(this.routeRegistry, openapi);
+		this.provider.get(path, async (_request, reply) => {
+			reply.header("content-type", "application/json; charset=utf-8");
+			return document;
+		});
+	}
+
+	private registerAllRoutes(registry: RouteRegistry) {
+		for (const route of registry.routes) {
+			const { key, method, path } = route;
+			this.provider.route({
+				method,
+				url: path,
+				handler: (request, reply) => this.routeRequest(route, key, request, reply),
+			});
+		}
+	}
+
+	private async routeRequest(
+		route: MappedRoute,
+		key: string,
+		request: FastifyRequest,
+		reply: FastifyReply,
+	) {
+		const httpRequest = this.fastifyToRequest(request);
+		const disconnect = this.abortOnDisconnect(reply, httpRequest, route.sse != null);
+		try {
+			const response = await this.router.route(key, httpRequest);
+			if (route.httpCode != null) {
+				reply.status(route.httpCode);
+			}
+			if (route.headers != null) {
+				for (const [name, value] of Object.entries(route.headers)) {
+					reply.header(name, value);
+				}
+			}
+			this.applyResponseHeaders(reply, httpRequest);
+			if (response instanceof SseResponse) {
+				return this.sendEventStream(route, reply, response, disconnect);
+			}
+			return response;
+		} catch (error) {
+			const result = this.exceptionFilterHost
+				? await this.exceptionFilterHost.handle(error, { request: httpRequest })
+				: new DefaultHttpExceptionFilter().catch(error, { request: httpRequest });
+			if (result.headers) {
+				for (const [name, value] of Object.entries(result.headers)) {
+					reply.header(name, value);
+				}
+			}
+			this.applyResponseHeaders(reply, httpRequest);
+			// Returned so Fastify waits for the async onSend hooks instead of sending an empty reply of its own.
+			return reply.status(result.status).send(result.body);
+		}
+	}
+
+	/**
+	 * Gives the handler a signal that aborts when the client goes away before the response
+	 * finished. Streams are also tracked so that stopping the app can abort them.
+	 */
+	private abortOnDisconnect(
+		reply: FastifyReply,
+		httpRequest: HttpRequest,
+		isStream: boolean,
+	): AbortController {
+		const controller = new AbortController();
+		httpRequest.signal = controller.signal;
+		if (isStream) {
+			if (this.closing) controller.abort(new Error("The app is stopping"));
+			this.openStreams.add(controller);
+		}
+		reply.raw.once("close", () => {
+			this.openStreams.delete(controller);
+			if (!reply.raw.writableFinished) {
+				controller.abort(new Error("The client disconnected"));
+			}
+		});
+		return controller;
+	}
+
+	private sendEventStream(
+		route: MappedRoute,
+		reply: FastifyReply,
+		response: SseResponse,
+		disconnect: AbortController,
+	) {
+		let started = false;
+		const release = () => {
+			response.release().catch((error: unknown) => {
+				this.logger.error("Releasing the request scope of an SSE stream failed", error);
+			});
+		};
+		const frames = encodeSse(response.events, {
+			signal: disconnect.signal,
+			heartbeatMs: route.sse?.heartbeatMs ?? DEFAULT_SSE_HEARTBEAT_MS,
+			onProducerStopped: (stopped) => void stopped.then(release),
+		});
+		const guarded = (async function* () {
+			started = true;
+			yield* frames;
+		})();
+		// Never pulled if the client left first, in which case nothing else would release the scope.
+		reply.raw.once("close", () => {
+			if (!started) release();
+		});
+		return (
+			reply
+				.status(route.httpCode ?? 200)
+				.header("content-type", "text/event-stream; charset=utf-8")
+				.header("cache-control", "no-cache, no-transform")
+				.header("x-accel-buffering", "no")
+				// A stream owns its connection; closing it afterwards lets app stop finish at once instead of waiting out keep-alive.
+				.header("connection", "close")
+				.send(Readable.from(guarded))
+		);
+	}
+
+	private applyResponseHeaders(reply: FastifyReply, httpRequest: HttpRequest) {
+		reply.header(REQUEST_ID_HEADER, httpRequest.requestId);
+		for (const [name, value] of Object.entries(httpRequest.responseHeaders)) {
+			reply.header(name, value);
+		}
+	}
+
+	private fastifyToRequest(fastifyRequest: FastifyRequest): HttpRequest {
+		const method = fastifyRequest.method;
+		const url = fastifyRequest.url;
+		const params = fastifyRequest.params as Record<string, string>;
+		const query = fastifyRequest.query as Record<string, string>;
+		const body = fastifyRequest.body ?? {};
+		const headers: Record<string, string> = {};
+		for (const [key, value] of Object.entries(fastifyRequest.headers)) {
+			if (typeof value === "string") {
+				headers[key.toLowerCase()] = value;
+			}
+		}
+		const requestId = resolveRequestId(headers, String(fastifyRequest.id ?? ""));
+		return new HttpRequest({
+			requestId,
+			url,
+			method,
+			params,
+			query,
+			body,
+			headers,
+		});
+	}
+}

package/src/routing/anvil.types.ts

@@ -0,0 +1,150 @@
+import type { Constructable, Type } from "@decohere/core/reflection";
+import type { HTTPMethod } from "../const.js";
+import type { SseOptions } from "../sse/sse.types.js";
+import type { Pipe } from "./pipes/pipes.js";
+
+export type Metadata =
+	| "controller"
+	| "route"
+	| "parameter"
+	| "fieldMap"
+	| "authorize"
+	| "allowAnonymous"
+	| "httpCode"
+	| "headers"
+	| "catch";
+
+export type CorsOptions = {
+	origin?: boolean | string | string[];
+	methods?: string[];
+	allowedHeaders?: string[];
+	exposedHeaders?: string[];
+	credentials?: boolean;
+	maxAge?: number;
+};
+
+export const RequestParts = {
+	query: "query",
+	params: "params",
+	body: "body",
+	principal: "principal",
+	signal: "signal",
+	lastEventId: "lastEventId",
+} satisfies Record<RequestPart, RequestPart>;
+
+export interface HttpProvider {
+	start<T extends StartOptions>(options: T): Promise<StartResponse>;
+	stop(): Promise<StopResponse>;
+	[Symbol.asyncDispose](): Promise<void>;
+}
+
+export type RequestPart = "query" | "params" | "body" | "principal" | "signal" | "lastEventId";
+
+/** Argument locations filled by the HTTP package itself rather than read from the request payload. */
+export const InjectedParts: readonly RequestPart[] = ["principal", "signal", "lastEventId"];
+
+export type MappedRoute = {
+	key: string;
+	controller: Constructable;
+	handler: string;
+	routeArgs?: RouteArg[];
+	httpCode?: number;
+	headers?: Record<string, string>;
+	/** Set by `@Sse()`: the handler returns a stream of events instead of a single response. */
+	sse?: SseOptions;
+} & RouteMetadata;
+
+export type RouteArg = {
+	argumentType: Constructable;
+	fieldMap?: Map<string, FieldMeta>;
+	pipes?: Constructable<Pipe>[];
+} & ArgumentMeta;
+
+export class HttpRequest {
+	public constructor(data?: Partial<HttpRequest>) {
+		Object.assign(this, data);
+	}
+	public requestId = "";
+	public url: string;
+	public method: string;
+	public params: Record<string, string> = {};
+	public query: Record<string, string> = {};
+	public body: unknown;
+	public headers: Record<string, string> = {};
+	/** Aborts when the client disconnects or the app stops. Never aborts if the provider cannot tell. */
+	public signal: AbortSignal = new AbortController().signal;
+	/** Outbound headers set by middleware; applied by the HTTP provider. */
+	public responseHeaders: Record<string, string> = {};
+}
+
+export type StartResponse = { addresses: string[] };
+export type StopResponse = { message: string };
+export type StartOptions = { port: number; host?: string };
+
+export type ArgumentMeta = {
+	argumentIndex: number;
+	mappingKey?: string;
+	argumentLocation?: RequestPart;
+	pipes: Constructable<Pipe>[];
+};
+
+export type ControllerMetadata = {
+	prefix: string;
+	/**
+	 * `false` leaves this controller's routes out of the global prefix (`withGlobalPrefix`), for
+	 * paths something outside the app expects at a fixed place: probes, webhooks, metrics. Default
+	 * `true`.
+	 */
+	globalPrefix?: boolean;
+};
+
+export type FieldMeta = {
+	fieldKey: string;
+	fieldType: Type;
+	mappingKey: string;
+	fieldLocation?: RequestPart;
+	pipes?: Constructable<Pipe>[];
+};
+
+export type RouteMetadata = {
+	path: string;
+	method: HTTPMethod;
+};
+export class RouteConfigurationError extends Error {}
+export class RoutingError extends Error {}
+export class TransformError extends Error {}
+
+export class HttpError extends Error {
+	public readonly status: number;
+	public constructor(message: string, status: number) {
+		super(message);
+		this.status = status;
+	}
+}
+
+export class UnauthorizedError extends HttpError {
+	public constructor(message = "Unauthorized") {
+		super(message, 401);
+	}
+}
+
+export class ForbiddenError extends HttpError {
+	public constructor(message = "Forbidden") {
+		super(message, 403);
+	}
+}
+
+export type ValidationIssue = {
+	path: string;
+	message: string;
+	keyword?: string;
+};
+
+export class ValidationError extends HttpError {
+	public readonly errors: ValidationIssue[];
+
+	public constructor(message = "Bad Request", errors: ValidationIssue[] = []) {
+		super(message, 400);
+		this.errors = errors;
+	}
+}