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

package/src/routing/decorators/argument.decorator.ts

@@ -0,0 +1,33 @@
+import type { Constructable } from "@decohere/core/reflection";
+import { defineArgumentMeta } from "@decohere/core/reflection";
+import { MetadataKeys } from "../../const.js";
+import { type ArgumentMeta, type RequestPart, RequestParts } from "../anvil.types.js";
+import type { Pipe } from "../pipes/pipes.js";
+
+export type ArgumentOptions = {
+	mappingKey?: string;
+	argumentLocation?: RequestPart;
+	pipes?: Constructable<Pipe>[];
+};
+
+export function Query(key: string) {
+	return Argument({ mappingKey: key, argumentLocation: RequestParts.query });
+}
+
+export function Param(key: string) {
+	return Argument({ mappingKey: key, argumentLocation: RequestParts.params });
+}
+
+export function Argument(options: ArgumentOptions) {
+	return (target: object, functionName: string, argumentIndex: number) => {
+		const { mappingKey, argumentLocation, pipes } = options;
+		const func = target[functionName];
+		const meta: ArgumentMeta = {
+			argumentIndex,
+			mappingKey,
+			argumentLocation,
+			pipes,
+		};
+		defineArgumentMeta<ArgumentMeta>(MetadataKeys.parameter, meta, func, argumentIndex);
+	};
+}

package/src/routing/decorators/auth.decorator.ts

@@ -0,0 +1,79 @@
+import type { Constructable, FunctionType } from "@decohere/core/reflection";
+import { defineArgumentMeta, defineMeta, getMeta } from "@decohere/core/reflection";
+import { MetadataKeys } from "../../const.js";
+import type { ArgumentMeta } from "../anvil.types.js";
+
+export type AuthorizeOptions = {
+	action: string;
+	subject: string;
+};
+
+/**
+ * Require the principal to be able to perform `action` on `subject`.
+ * Uses an IAuthorizationService (e.g. CaslAuthorizationService) registered in DI.
+ * When applied to a class, all methods inherit the constraint.
+ * When applied to a method, it takes precedence over the class-level decorator.
+ *
+ * @example
+ * \@Authorize("delete", "Article")
+ * \@Authorize("manage", "all")
+ */
+export function Authorize(action: string, subject = "all") {
+	const options: AuthorizeOptions = { action, subject };
+	return (
+		target: object | Constructable,
+		methodName?: string,
+		_descriptor?: PropertyDescriptor,
+	) => {
+		if (methodName) {
+			const fn = (target as object)[methodName];
+			defineMeta(MetadataKeys.authorize, options, fn);
+		} else {
+			defineMeta(MetadataKeys.authorize, options, (target as Constructable).prototype);
+		}
+	};
+}
+
+/**
+ * Opt a specific route method out of authentication, even when the controller
+ * class is decorated with @Authorize.
+ */
+export function AllowAnonymous() {
+	return (target: object, methodName: string, _descriptor?: PropertyDescriptor) => {
+		const fn = (target as object)[methodName];
+		defineMeta(MetadataKeys.allowAnonymous, true, fn);
+	};
+}
+
+/** Read the effective @Authorize options for a handler function. */
+export function getAuthorizeOptions(
+	controllerPrototype: object,
+	handlerFn: object,
+): AuthorizeOptions | undefined {
+	// Method-level overrides class-level
+	const methodLevel = getMeta<AuthorizeOptions>(MetadataKeys.authorize, handlerFn);
+	if (methodLevel !== undefined) return methodLevel;
+	return getMeta<AuthorizeOptions>(MetadataKeys.authorize, controllerPrototype);
+}
+
+/** Returns true only when the handler is explicitly marked @AllowAnonymous. */
+export function isAllowAnonymous(_controllerPrototype: object, handlerFn: object): boolean {
+	return getMeta<boolean>(MetadataKeys.allowAnonymous, handlerFn) === true;
+}
+
+/**
+ * Parameter decorator — injects the authenticated Principal into this argument.
+ * The argument resolver will supply the principal verified during the auth step.
+ */
+export function CurrentUser() {
+	return (target: object, propertyKey: string, parameterIndex: number) => {
+		const fn = (target as Record<string, FunctionType>)[propertyKey];
+		const meta: ArgumentMeta = {
+			argumentIndex: parameterIndex,
+			argumentLocation: "principal",
+			mappingKey: undefined,
+			pipes: [],
+		};
+		defineArgumentMeta<ArgumentMeta>(MetadataKeys.parameter, meta, fn, parameterIndex);
+	};
+}

package/src/routing/decorators/controller.decorator.ts

@@ -0,0 +1,9 @@
+import type { Constructable } from "@decohere/core/reflection";
+import { MetadataKeys } from "../../const.js";
+import type { ControllerMetadata } from "../anvil.types.js";
+
+export function Controller(options?: ControllerMetadata) {
+	return (target: Constructable) => {
+		Reflect.defineMetadata(MetadataKeys.controller, options, target.prototype);
+	};
+}

package/src/routing/decorators/field.decorator.ts

@@ -0,0 +1,15 @@
+import { defineMeta, getFieldType, getMeta } from "@decohere/core/reflection";
+import { MetadataKeys } from "../../const.js";
+import type { FieldMeta, RequestPart } from "../anvil.types.js";
+
+export function Field(fieldLocation?: RequestPart, mappingKey?: string) {
+	return (target: object, fieldName: string) => {
+		const fieldMap =
+			getMeta<Map<string, FieldMeta>>(MetadataKeys.fieldMap, target) ??
+			new Map<string, FieldMeta>();
+
+		const fieldType = getFieldType(target, fieldName);
+		fieldMap.set(fieldName, { fieldKey: fieldName, mappingKey, fieldType, fieldLocation });
+		defineMeta<Map<string, FieldMeta>>(MetadataKeys.fieldMap, fieldMap, target);
+	};
+}

package/src/routing/decorators/request.decorator.ts

@@ -0,0 +1,34 @@
+import type { Constructable } from "@decohere/core/reflection";
+import { defineMeta, getFields, getFieldType, getMeta } from "@decohere/core/reflection";
+import { MetadataKeys } from "../../const.js";
+import type { FieldMeta, RequestPart } from "../anvil.types.js";
+
+/**
+ * Used to map a request object to route params
+ * @param mappingKey
+ * @returns
+ */
+export function Request(mappingKey?: RequestPart) {
+	return (target: Constructable) => {
+		const inst = new target();
+
+		const fieldMap =
+			getMeta<Map<string, FieldMeta>>(MetadataKeys.fieldMap, target.prototype) ??
+			new Map<string, FieldMeta>();
+
+		const fields = getFields(inst);
+
+		for (const field of fields) {
+			const fieldType = getFieldType(target.prototype, field.key);
+			const overrides = fieldMap.get(field.key);
+			fieldMap.set(field.key, {
+				fieldKey: field.key,
+				mappingKey: overrides?.mappingKey ?? field.key,
+				fieldType: overrides?.fieldType ?? fieldType,
+				fieldLocation: overrides?.fieldLocation ?? mappingKey,
+			});
+		}
+
+		defineMeta(MetadataKeys.fieldMap, fieldMap, target.prototype);
+	};
+}

package/src/routing/decorators/response.decorator.ts

@@ -0,0 +1,18 @@
+import { defineMeta, getMeta } from "@decohere/core/reflection";
+import { MetadataKeys } from "../../const.js";
+
+/** Set the HTTP status code returned on a successful handler response. */
+export function HttpCode(statusCode: number) {
+	return (_target: object, _methodName: string, descriptor: PropertyDescriptor) => {
+		defineMeta(MetadataKeys.httpCode, statusCode, descriptor.value);
+	};
+}
+
+/** Set a response header on a successful handler response. Stackable. */
+export function Header(name: string, value: string) {
+	return (_target: object, _methodName: string, descriptor: PropertyDescriptor) => {
+		const existing =
+			getMeta<Record<string, string>>(MetadataKeys.headers, descriptor.value) ?? {};
+		defineMeta(MetadataKeys.headers, { ...existing, [name]: value }, descriptor.value);
+	};
+}

package/src/routing/decorators/route.decorator.ts

@@ -0,0 +1,52 @@
+import { defineMeta } from "@decohere/core/reflection";
+import { type HTTPMethod, HTTPMethods, MetadataKeys } from "../../const.js";
+import type { RouteMetadata } from "../anvil.types.js";
+import { RouteConfigurationError } from "../anvil.types.js";
+
+export function Get(path?: string) {
+	return routeDecorator(HTTPMethods.GET, path);
+}
+
+export function Post(path?: string) {
+	return routeDecorator(HTTPMethods.POST, path);
+}
+
+export function Put(path?: string) {
+	return routeDecorator(HTTPMethods.PUT, path);
+}
+
+export function Patch(path?: string) {
+	return routeDecorator(HTTPMethods.PATCH, path);
+}
+
+export function Delete(path?: string) {
+	return routeDecorator(HTTPMethods.DELETE, path);
+}
+
+export function Route(method: HTTPMethod, path?: string) {
+	return routeDecorator(method, path);
+}
+
+/**
+ * Store method + relative path only. Controller / global prefixes are applied
+ * at registration time in RouteRegistry (avoids TS decorator-order issues).
+ */
+function routeDecorator(method: HTTPMethod, path: string = "") {
+	return (
+		targetClass: object,
+		functionName: string,
+		descriptor?: TypedPropertyDescriptor<(...args: any[]) => any>,
+	) => {
+		if (path !== "" && !path.startsWith("/")) {
+			throw new RouteConfigurationError(
+				`Error configuring routes. Path defined in controller ${
+					targetClass.constructor.name
+				}.${functionName}() should start '/'`,
+			);
+		}
+
+		const { value: handler } = descriptor;
+		const routeConfig: RouteMetadata = { method, path };
+		defineMeta(MetadataKeys.route, routeConfig, handler);
+	};
+}

package/src/routing/filters/exception-filter-host.ts

@@ -0,0 +1,90 @@
+import { type LifetimeScope, LifetimeScopeToken } from "@decohere/di";
+import { inject, injectable } from "@decohere/di/decorators";
+import type { Constructable } from "@decohere/core/reflection";
+import { scribe } from "@decohere/scribe";
+import { HttpOptionsToken } from "../../const.js";
+import type { HttpOptions } from "../../http/http.options.js";
+import { HttpError, ValidationError } from "../anvil.types.js";
+import {
+	type ExceptionContext,
+	type ExceptionFilter,
+	type ExceptionResult,
+	getCatchTypes,
+} from "./exception-filter.js";
+
+@injectable()
+export class DefaultHttpExceptionFilter implements ExceptionFilter {
+	private readonly logger = scribe.logger(DefaultHttpExceptionFilter.name);
+
+	public catch(error: unknown, _ctx: ExceptionContext): ExceptionResult {
+		if (error instanceof ValidationError) {
+			return {
+				status: 400,
+				body: {
+					statusCode: 400,
+					error: "Bad Request",
+					message: error.message,
+					errors: error.errors,
+				},
+			};
+		}
+		if (error instanceof HttpError) {
+			// Never expose internal auth failure details (header shape, issuer, etc.) to clients.
+			if (error.status === 401) {
+				this.logger.warn(error.message);
+				return { status: 401, body: { message: "Unauthorized" } };
+			}
+			// Sanitize only true 500s. Keep intentional 503 probe messages (e.g. /ready).
+			if (error.status === 500) {
+				this.logger.error(error.message);
+				return { status: 500, body: { message: "Internal Server Error" } };
+			}
+			return { status: error.status, body: { message: error.message } };
+		}
+		if (error instanceof Error) {
+			this.logger.error(error.message, error.stack);
+			return { status: 500, body: { message: "Internal Server Error" } };
+		}
+		return { status: 500, body: { message: "Internal Server Error" } };
+	}
+}
+
+/**
+ * Resolves the first matching filter for an error.
+ * Custom filters (registered via builder) are tried first; default is last.
+ */
+@injectable()
+export class ExceptionFilterHost {
+	private filters?: ExceptionFilter[];
+
+	public constructor(
+		@inject(HttpOptionsToken) private readonly options?: HttpOptions,
+		@inject(LifetimeScopeToken) private readonly scope?: LifetimeScope,
+	) {}
+
+	public async handle(error: unknown, ctx: ExceptionContext): Promise<ExceptionResult> {
+		for (const filter of this.getFilters()) {
+			const filterType = filter.constructor as Constructable;
+			const types = getCatchTypes(filterType);
+			if (types.length === 0 || types.some((t) => error instanceof t)) {
+				return await filter.catch(error, ctx);
+			}
+		}
+		return new DefaultHttpExceptionFilter().catch(error, ctx);
+	}
+
+	private getFilters(): ExceptionFilter[] {
+		if (this.filters != null) {
+			return this.filters;
+		}
+		const custom =
+			this.options?.filterTypes.map((type) => {
+				if (this.scope == null) {
+					return new (type as Constructable<ExceptionFilter>)();
+				}
+				return this.scope.resolve<ExceptionFilter>(type);
+			}) ?? [];
+		this.filters = [...custom, new DefaultHttpExceptionFilter()];
+		return this.filters;
+	}
+}

package/src/routing/filters/exception-filter.ts

@@ -0,0 +1,29 @@
+import type { Constructable } from "@decohere/core/reflection";
+import { defineMeta, getMeta } from "@decohere/core/reflection";
+import { MetadataKeys } from "../../const.js";
+import type { HttpRequest } from "../anvil.types.js";
+
+export type ExceptionResult = {
+	status: number;
+	body: unknown;
+	headers?: Record<string, string>;
+};
+
+export type ExceptionContext = {
+	request: HttpRequest;
+};
+
+export interface ExceptionFilter {
+	catch(error: unknown, ctx: ExceptionContext): ExceptionResult | Promise<ExceptionResult>;
+}
+
+/** Declare which error types this filter handles. Empty = catch-all. */
+export function Catch(...types: Constructable[]) {
+	return (target: Constructable) => {
+		defineMeta(MetadataKeys.catch, types, target);
+	};
+}
+
+export function getCatchTypes(filterType: Constructable): Constructable[] {
+	return getMeta<Constructable[]>(MetadataKeys.catch, filterType) ?? [];
+}

package/src/routing/middleware/http-access-log.middleware.ts

@@ -0,0 +1,36 @@
+import { injectable } from "@decohere/di/decorators";
+import { scribe } from "@decohere/scribe";
+import { HttpError } from "../anvil.types.js";
+import type { Middleware, MiddlewareContext } from "./middleware.js";
+import { REQUEST_ID_HEADER } from "./request-id.js";
+
+/**
+ * Echoes `x-request-id` on the response and writes an HTTP access line via Scribe
+ * (method, path, status, durationMs, requestId). Enabled by default through `withHttp`.
+ */
+@injectable()
+export class HttpAccessLogMiddleware implements Middleware {
+	public async use(ctx: MiddlewareContext, next: () => Promise<unknown>): Promise<unknown> {
+		const logger = scribe.logger(HttpAccessLogMiddleware.name);
+		const start = performance.now();
+		ctx.request.responseHeaders[REQUEST_ID_HEADER] = ctx.request.requestId;
+
+		let status = ctx.route.httpCode ?? 200;
+		try {
+			return await next();
+		} catch (error) {
+			status = error instanceof HttpError ? error.status : 500;
+			throw error;
+		} finally {
+			const durationMs = Math.round(performance.now() - start);
+			logger.info({
+				msg: "access",
+				method: ctx.request.method,
+				path: ctx.request.url,
+				status,
+				durationMs,
+				requestId: ctx.request.requestId,
+			});
+		}
+	}
+}

package/src/routing/middleware/middleware.ts

@@ -0,0 +1,26 @@
+import type { HttpRequest, MappedRoute } from "../anvil.types.js";
+
+export type MiddlewareContext = {
+	request: HttpRequest;
+	route: MappedRoute;
+};
+
+export interface Middleware {
+	use(ctx: MiddlewareContext, next: () => Promise<unknown>): Promise<unknown>;
+}
+
+/** Compose middleware around a terminal handler; returns the handler result. */
+export function composeMiddleware(
+	middlewares: Middleware[],
+	handler: () => Promise<unknown>,
+	ctx: MiddlewareContext,
+): Promise<unknown> {
+	const dispatch = (index: number): Promise<unknown> => {
+		if (index >= middlewares.length) {
+			return handler();
+		}
+		const middleware = middlewares[index];
+		return middleware.use(ctx, () => dispatch(index + 1));
+	};
+	return dispatch(0);
+}

package/src/routing/middleware/request-id.ts

@@ -0,0 +1,18 @@
+import { randomUUID } from "node:crypto";
+
+/** Canonical inbound/outbound request id header (lowercase). */
+export const REQUEST_ID_HEADER = "x-request-id";
+
+/**
+ * Prefer an inbound `x-request-id`, then an existing id, otherwise generate one.
+ */
+export function resolveRequestId(headers: Record<string, string>, fallback?: string): string {
+	const fromHeader = headers[REQUEST_ID_HEADER]?.trim();
+	if (fromHeader) {
+		return fromHeader;
+	}
+	if (fallback?.trim()) {
+		return fallback.trim();
+	}
+	return randomUUID();
+}

package/src/routing/path.util.ts

@@ -0,0 +1,38 @@
+/** Normalize a prefix to `/foo` form with no trailing slash. Empty → `""`. */
+export function normalizePrefix(prefix: string | undefined | null): string {
+	if (prefix == null || prefix === "" || prefix === "/") {
+		return "";
+	}
+	const withSlash = prefix.startsWith("/") ? prefix : `/${prefix}`;
+	return withSlash.replace(/\/+$/, "");
+}
+
+/**
+ * Join a controller prefix with a method-relative route path.
+ * Preserves `@Get("/")` trailing-slash semantics (`/hello` + `/` → `/hello/`).
+ */
+export function joinRoutePath(prefix: string, routePath: string): string {
+	const p = normalizePrefix(prefix);
+	if (routePath === "" || routePath == null) {
+		return p === "" ? "/" : p;
+	}
+	if (routePath === "/") {
+		return p === "" ? "/" : `${p}/`;
+	}
+	if (!routePath.startsWith("/")) {
+		throw new Error(`Route path must start with '/': ${routePath}`);
+	}
+	return `${p}${routePath}`;
+}
+
+/** Prepend a global prefix onto an already-joined controller route path. */
+export function applyGlobalPrefix(globalPrefix: string, path: string): string {
+	const g = normalizePrefix(globalPrefix);
+	if (g === "") {
+		return path === "" ? "/" : path;
+	}
+	if (path === "/") {
+		return `${g}/`;
+	}
+	return `${g}${path.startsWith("/") ? path : `/${path}`}`;
+}

package/src/routing/pipes/pipes.ts

@@ -0,0 +1,132 @@
+import type { Type } from "@decohere/core/reflection";
+import { isDateType } from "@decohere/core/reflection";
+import { TransformError, ValidationError } from "../anvil.types.js";
+
+export type PipeContext = {
+	fieldTypes: Record<string, Type>;
+};
+
+const invalidBooleanIssue = {
+	path: "/value",
+	message: "Invalid boolean",
+	keyword: "type",
+} as const;
+
+const invalidNumberIssue = {
+	path: "/value",
+	message: "Invalid number",
+	keyword: "type",
+} as const;
+
+const invalidDateIssue = {
+	path: "/value",
+	message: "Invalid date",
+	keyword: "format",
+} as const;
+
+export abstract class Pipe<T = unknown> {
+	public abstract transform(value: unknown, context?: PipeContext): T;
+}
+
+export class BooleanPipe extends Pipe<boolean> {
+	public transform(value: unknown, _context?: unknown): boolean {
+		if (typeof value === "boolean") {
+			return value;
+		}
+
+		const normalized = typeof value === "string" ? value.trim().toLowerCase() : value;
+
+		switch (normalized) {
+			case "true":
+			case "1":
+			case 1:
+				return true;
+			case "false":
+			case "0":
+			case 0:
+				return false;
+			default:
+				throw new ValidationError("Validation failed", [invalidBooleanIssue]);
+		}
+	}
+}
+
+export class DatePipe extends Pipe<Date> {
+	public transform(value: unknown, _context?: unknown): Date {
+		if (value instanceof Date) {
+			if (Number.isNaN(value.getTime())) {
+				throw new ValidationError("Validation failed", [invalidDateIssue]);
+			}
+			return value;
+		}
+
+		if (typeof value === "string") {
+			const trimmed = value.trim();
+			if (trimmed === "") {
+				throw new ValidationError("Validation failed", [invalidDateIssue]);
+			}
+			if (/^-?\d+(\.\d+)?$/.test(trimmed)) {
+				return new Date(Number(trimmed));
+			}
+			const parsed = new Date(trimmed);
+			if (Number.isNaN(parsed.getTime())) {
+				throw new ValidationError("Validation failed", [invalidDateIssue]);
+			}
+			return parsed;
+		}
+
+		if (typeof value === "number" && !Number.isNaN(value)) {
+			return new Date(value);
+		}
+
+		throw new ValidationError("Validation failed", [invalidDateIssue]);
+	}
+}
+
+export class JsonPipe extends Pipe<object> {
+	public transform(value: string, context?: PipeContext): object {
+		try {
+			const obj = JSON.parse(value, (fieldKey, fieldValue) => {
+				const val = this.reviver(context?.fieldTypes, fieldKey, fieldValue);
+				return val;
+			});
+			return obj;
+		} catch (err) {
+			throw new TransformError(`Error parsing json ${err}`);
+		}
+	}
+
+	private reviver(fieldTypes: Record<string, Type>, fieldKey: string, value: unknown) {
+		if (!fieldKey) {
+			return value;
+		}
+
+		if (!fieldTypes) {
+			return value;
+		}
+
+		const fieldType = fieldTypes[fieldKey];
+
+		if (fieldType == null) {
+			return value;
+		}
+
+		if (!isDateType(fieldType)) {
+			return value;
+		}
+
+		return new Date(value.toString());
+	}
+}
+
+export class NumberPipe extends Pipe<number> {
+	/** Finite numbers only. Blank or non-numeric input is a 400, not `undefined` (#503). */
+	public transform(value: unknown, _context?: unknown): number {
+		const text = typeof value === "number" ? null : String(value).trim();
+		const number = text == null ? (value as number) : text === "" ? Number.NaN : Number(text);
+		if (!Number.isFinite(number)) {
+			throw new ValidationError("Validation failed", [invalidNumberIssue]);
+		}
+		return number;
+	}
+}