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

package/src/hosting/hosted-service-host.ts

@@ -0,0 +1,102 @@
+import type { IContainer } from "@decohere/di";
+import type { Constructable } from "@decohere/core/reflection";
+import { scribe } from "@decohere/scribe";
+import type { IReadinessCheck } from "../health/readiness.types.js";
+import type { HostedService } from "./hosted-service.js";
+
+/**
+ * Starts and stops the app's {@link HostedService}s. One per app; `Builder.withHostedService`
+ * adds the types and `App` drives it.
+ */
+export class HostedServiceHost {
+	private readonly logger = scribe.logger(HostedServiceHost.name);
+	private readonly types: Constructable<HostedService>[] = [];
+	private readonly controller = new AbortController();
+	/** In start order; stopped in reverse. */
+	private readonly started: HostedService[] = [];
+	private starting: Promise<void> | undefined;
+	private stopping: Promise<void> | undefined;
+
+	public add(...types: Constructable<HostedService>[]) {
+		this.types.push(...types);
+	}
+
+	public get isEmpty(): boolean {
+		return this.types.length === 0;
+	}
+
+	/**
+	 * Start every service in registration order. If one throws, the ones already started are
+	 * stopped and the error is rethrown. Stops launching more once {@link stop} has begun.
+	 */
+	public start(container: IContainer): Promise<void> {
+		this.starting ??= this.startAll(container);
+		return this.starting;
+	}
+
+	/** Abort the services' signal: background work should wind down. {@link stop} does this too. */
+	public abort() {
+		this.controller.abort();
+	}
+
+	/**
+	 * Abort the signal, wait for a start still in progress, then stop the started services in
+	 * reverse order. Every `stop()` runs even if one throws; the failures are rethrown after.
+	 */
+	public stop(): Promise<void> {
+		this.stopping ??= this.stopAll();
+		return this.stopping;
+	}
+
+	/** The started services that report readiness, for `GET /ready`. */
+	public readinessChecks(): IReadinessCheck[] {
+		return this.started
+			.filter((service) => typeof service.check === "function")
+			.map((service) => ({
+				name: service.constructor.name,
+				check: () => service.check?.() ?? Promise.resolve(),
+			}));
+	}
+
+	private async startAll(container: IContainer) {
+		const { signal } = this.controller;
+		for (const type of this.types) {
+			if (signal.aborted) return;
+			const service = container.resolve(type);
+			try {
+				await service.start(signal);
+			} catch (error) {
+				this.logger.error(`Hosted service ${type.name} failed to start`, error);
+				// Not stop(): it waits for this start to settle.
+				this.controller.abort();
+				await this.stopStarted().catch(() => {});
+				throw error;
+			}
+			this.started.push(service);
+			this.logger.debug(`Hosted service ${type.name} started`);
+		}
+	}
+
+	private async stopAll() {
+		this.controller.abort();
+		await Promise.allSettled([this.starting]);
+		await this.stopStarted();
+	}
+
+	/** Stop what is started, newest first. Takes each service off the list, so it runs once. */
+	private async stopStarted() {
+		const failures: unknown[] = [];
+		for (let service = this.started.pop(); service != null; service = this.started.pop()) {
+			try {
+				await service.stop?.();
+			} catch (error) {
+				this.logger.error(`Hosted service ${service.constructor.name} failed to stop`, error);
+				failures.push(error);
+			}
+		}
+		if (failures.length === 1) throw failures[0];
+		if (failures.length > 1) {
+			throw new AggregateError(failures, `${failures.length} hosted services failed to stop`);
+		}
+	}
+}

package/src/hosting/hosted-service.ts

@@ -0,0 +1,31 @@
+/**
+ * Work that runs for the life of the app outside a request: a feed, a poller, a queue consumer.
+ * Register it with `builder.withHostedService(Type)`; it is a singleton, so other services can
+ * inject it by its class.
+ *
+ * The app starts hosted services in registration order before the HTTP server listens, and stops
+ * them in reverse order when it stops (`app.dispose()`, SIGTERM or SIGINT, a Flux reboot).
+ */
+export interface HostedService {
+	/**
+	 * Called once when the app starts, and awaited: a throw fails `app.start()`. Do what must be
+	 * ready before traffic, then start long work (a first load that takes minutes, a timer) in
+	 * the background and return. Waiting for it here keeps the HTTP server dark.
+	 *
+	 * `signal` is aborted as soon as the app starts stopping, before `stop()` is called, also
+	 * while `start()` itself is still running. Stop background work and clear timers on it.
+	 */
+	start(signal: AbortSignal): Promise<void> | void;
+	/**
+	 * Called once when the app stops, after the HTTP server has drained and before the container
+	 * is disposed, so the services it uses (a DataSource) are still open. Wait here for the
+	 * background work to finish. Optional: a service with nothing to wait for can rely on the
+	 * signal, or on `Symbol.asyncDispose`, which the container calls later.
+	 */
+	stop?(): Promise<void> | void;
+	/**
+	 * Readiness while the service is started but still warming up: throw until it can serve, and
+	 * `GET /ready` answers 503 (`withHealth()`). Optional.
+	 */
+	check?(): Promise<void>;
+}

package/src/http/http.compression.ts

@@ -0,0 +1,38 @@
+/**
+ * Response compression (`builder.withCompression`). Provider-neutral options and defaults;
+ * the HTTP provider hands them to its compression plugin and the plugin owns the policy
+ * (which responses are compressed, `Vary`, `HEAD`, streams). See ADR 0008.
+ */
+
+/** A content coding the HTTP package can offer. */
+export type CompressionEncoding = "br" | "gzip" | "deflate";
+
+/** Bodies smaller than this many bytes are sent as they are (not applied to streams, such as files). */
+export const DEFAULT_COMPRESSION_THRESHOLD = 1024;
+
+/** The codings offered by default, in order of preference. `deflate` is left out on purpose. */
+export const DEFAULT_COMPRESSION_ENCODINGS: readonly CompressionEncoding[] = ["br", "gzip"];
+
+/** Options for {@link Builder.withCompression}. `false` turns compression off. */
+export type CompressionOptions =
+	| false
+	| {
+			/** Smallest body, in bytes, that is compressed. Defaults to 1024. Not applied to streamed bodies. */
+			threshold?: number;
+			/** The codings to offer, in order of preference. Defaults to `["br", "gzip"]`. */
+			encodings?: CompressionEncoding[];
+			/**
+			 * Content types to compress, tested against the `Content-Type` header. Passed to the
+			 * plugin as `customTypes`: it replaces the plugin's default pattern (text, JSON, XML,
+			 * `octet-stream`; never `text/event-stream`) and anything the MIME database marks
+			 * compressible is still compressed. Use it to add a type; do not match
+			 * `text/event-stream` unless you want streams buffered.
+			 */
+			types?: RegExp | ((contentType: string) => boolean);
+			/**
+			 * Fastify-specific. Any other `@fastify/compress` option (`brotliOptions`, `zlibOptions`,
+			 * `onUnsupportedEncoding`, `inflateIfDeflated`, ...), merged last so it overrides the
+			 * values above. Not portable to another HTTP provider.
+			 */
+			providerOptions?: Record<string, unknown>;
+	  };

package/src/http/http.extensions.ts

@@ -0,0 +1,244 @@
+import type { ContainerBuilder, IContainer } from "@decohere/di";
+import { extension } from "@decohere/core/extensibility";
+import type { Constructable } from "@decohere/core/reflection";
+import { scribe } from "@decohere/scribe";
+import { PrincipalProvider } from "../auth/principal-provider.js";
+import { Builder } from "../builder/builder.js";
+import {
+	ExceptionFilterHostToken,
+	HttpOptionsToken,
+	HttpProviderToken,
+	IPrincipalProviderToken,
+	RouteRegistryToken,
+	RouterToken,
+} from "../const.js";
+import type { OpenApiOptions } from "../openapi/openapi.types.js";
+import type { CorsOptions, HttpProvider } from "../routing/anvil.types.js";
+import type { ExceptionFilter } from "../routing/filters/exception-filter.js";
+import { ExceptionFilterHost } from "../routing/filters/exception-filter-host.js";
+import { HttpAccessLogMiddleware } from "../routing/middleware/http-access-log.middleware.js";
+import type { Middleware } from "../routing/middleware/middleware.js";
+import { RouteRegistry } from "../routing/services/route-registry.js";
+import { Router } from "../routing/services/router.js";
+import type { WithHttpOptions } from "./http.options.js";
+import { getOrCreateHttpOptions } from "./http.options.store.js";
+import type { CompressionOptions } from "./http.compression.js";
+import type { HelmetOptions, RateLimitOptions } from "./http.security.js";
+import { type StaticOptions, staticFiles } from "./http.static.js";
+
+const httpProviderStore = new WeakMap<Builder, Constructable<HttpProvider>>();
+const controllersStore = new WeakMap<Builder, Constructable[]>();
+
+declare module "@decohere/http" {
+	interface Builder {
+		withHttpProvider<Thttp extends Constructable<HttpProvider>>(type: Thttp): Builder;
+		/**
+		 * HTTP provider plus scaffold defaults (request id + Scribe access log).
+		 * Prefer this over {@link Builder.withHttpProvider} for application entrypoints.
+		 */
+		withHttp<Thttp extends Constructable<HttpProvider>>(
+			type: Thttp,
+			options?: WithHttpOptions,
+		): Builder;
+		withControllers(...controllers: Constructable[]): Builder;
+		/**
+		 * Prefix every controller route (`/api` makes `/lp/portfolio` into `/api/lp/portfolio`).
+		 * It covers controller routes only: not static mounts (`withStatic`), not the OpenAPI
+		 * document, and not a controller declared with `@Controller({ globalPrefix: false })`,
+		 * such as the `withHealth()` probes, which platforms expect at the root. With a prefix
+		 * set, the static fallback treats everything under it as the API.
+		 */
+		withGlobalPrefix(prefix: string): Builder;
+		withCors(options: CorsOptions): Builder;
+		/**
+		 * Override or disable default `@fastify/helmet` headers.
+		 * Defaults are on with `withHttpProvider`; pass `false` to disable.
+		 */
+		withHelmet(options?: HelmetOptions): Builder;
+		/**
+		 * Override or disable default `@fastify/rate-limit` (100 req / 1 minute).
+		 * Pass `false` to disable.
+		 */
+		withRateLimit(options?: RateLimitOptions): Builder;
+		/**
+		 * Compress responses with `br` or `gzip` when the client accepts it, using `@fastify/compress`
+		 * with best-practice defaults (on by default, 1 KB threshold, no `deflate`). Pass `false` to
+		 * turn it off, or `{ threshold, encodings, types, providerOptions }` to override. The plugin
+		 * does not compress `text/event-stream` by default. Compressing a response that mixes a secret
+		 * with input an attacker controls can leak the secret over HTTPS (BREACH); see ADR 0008.
+		 */
+		withCompression(options?: CompressionOptions): Builder;
+		/**
+		 * Override the default request body size limit (1 MiB).
+		 */
+		withBodyLimit(bytes: number): Builder;
+		withMiddleware(...middlewares: Constructable<Middleware>[]): Builder;
+		withExceptionFilters(...filters: Constructable<ExceptionFilter>[]): Builder;
+		withOpenApi(options: OpenApiOptions): Builder;
+		/**
+		 * Serve a built UI (a folder of static files) from this API, for example
+		 * `.withStatic("/ui/", "ui")`. The directory is resolved from the process working
+		 * directory, like `./config`. The files are public: they are served before auth,
+		 * validation and middleware, and outside the rate limit. An unknown path under the prefix
+		 * serves `index.html` to a browser (`Accept: text/html`) so client routes survive a reload. `"/"` mounts it at the root. Hashed assets are cached for a
+		 * year, `index.html` is not cached. See {@link StaticOptions}.
+		 */
+		withStatic(prefix: string, directory: string, options?: StaticOptions): Builder;
+	}
+}
+
+export class BuilderExtensions {
+	@extension(Builder)
+	public static withHttpProvider<Thttp extends Constructable<HttpProvider>>(
+		builder: Builder,
+		type: Thttp,
+	) {
+		httpProviderStore.set(builder, type);
+		const httpOptions = getOrCreateHttpOptions(builder);
+
+		builder.withServices((containerBuilder: ContainerBuilder) => {
+			const logger = scribe.logger("BuilderExtensions");
+			logger.trace("Configuring Http Provider");
+
+			const http = httpProviderStore.get(builder);
+			if (!http) {
+				return;
+			}
+
+			containerBuilder.registerSingleton(HttpOptionsToken, httpOptions);
+			containerBuilder.registerSingleton(HttpProviderToken, http);
+			containerBuilder.registerSingleton(RouterToken, Router);
+			containerBuilder.registerSingleton(RouteRegistryToken, RouteRegistry);
+			containerBuilder.registerSingleton(ExceptionFilterHostToken, ExceptionFilterHost);
+			containerBuilder.registerRequestScoped(IPrincipalProviderToken, PrincipalProvider);
+
+			for (const middlewareType of httpOptions.middlewareTypes) {
+				containerBuilder.registerSingleton(middlewareType);
+			}
+			for (const filterType of httpOptions.filterTypes) {
+				containerBuilder.registerSingleton(filterType);
+			}
+
+			const controllers = controllersStore.get(builder) || [];
+			for (const controllerFn of controllers) {
+				containerBuilder.registerRequestScoped(controllerFn);
+			}
+		});
+
+		builder.registerPostBuildStep((container: IContainer) => {
+			const logger = scribe.logger("BuilderExtensions");
+			const registry = container.resolve<RouteRegistry>(RouteRegistryToken);
+			const controllers = controllersStore.get(builder) || [];
+			for (const controllerFn of controllers) {
+				logger.trace(`Add routes from ${controllerFn.name}`);
+				registry.addController(controllerFn);
+			}
+		});
+
+		return builder;
+	}
+
+	@extension(Builder)
+	public static withHttp<Thttp extends Constructable<HttpProvider>>(
+		builder: Builder,
+		type: Thttp,
+		options?: WithHttpOptions,
+	) {
+		const accessLog = options?.accessLog !== false;
+		if (accessLog) {
+			const httpOptions = getOrCreateHttpOptions(builder);
+			if (!httpOptions.middlewareTypes.includes(HttpAccessLogMiddleware)) {
+				httpOptions.middlewareTypes = [
+					...httpOptions.middlewareTypes,
+					HttpAccessLogMiddleware,
+				];
+			}
+		}
+		return BuilderExtensions.withHttpProvider(builder, type);
+	}
+
+	@extension(Builder)
+	public static withControllers(builder: Builder, ...controllers: Constructable[]) {
+		const existing = controllersStore.get(builder) || [];
+		controllersStore.set(builder, [...existing, ...controllers]);
+		return builder;
+	}
+
+	@extension(Builder)
+	public static withGlobalPrefix(builder: Builder, prefix: string) {
+		getOrCreateHttpOptions(builder).globalPrefix = prefix;
+		return builder;
+	}
+
+	@extension(Builder)
+	public static withCors(builder: Builder, options: CorsOptions) {
+		getOrCreateHttpOptions(builder).cors = options;
+		return builder;
+	}
+
+	@extension(Builder)
+	public static withHelmet(builder: Builder, options: HelmetOptions = {}) {
+		getOrCreateHttpOptions(builder).helmet = options;
+		return builder;
+	}
+
+	@extension(Builder)
+	public static withRateLimit(builder: Builder, options: RateLimitOptions = {}) {
+		getOrCreateHttpOptions(builder).rateLimit = options;
+		return builder;
+	}
+
+	@extension(Builder)
+	public static withCompression(builder: Builder, options: CompressionOptions = {}) {
+		getOrCreateHttpOptions(builder).compression = options;
+		return builder;
+	}
+
+	@extension(Builder)
+	public static withBodyLimit(builder: Builder, bytes: number) {
+		getOrCreateHttpOptions(builder).bodyLimit = bytes;
+		return builder;
+	}
+
+	@extension(Builder)
+	public static withMiddleware(builder: Builder, ...middlewares: Constructable<Middleware>[]) {
+		const httpOptions = getOrCreateHttpOptions(builder);
+		httpOptions.middlewareTypes = [...httpOptions.middlewareTypes, ...middlewares];
+		return builder;
+	}
+
+	@extension(Builder)
+	public static withExceptionFilters(
+		builder: Builder,
+		...filters: Constructable<ExceptionFilter>[]
+	) {
+		const httpOptions = getOrCreateHttpOptions(builder);
+		httpOptions.filterTypes = [...httpOptions.filterTypes, ...filters];
+		return builder;
+	}
+
+	@extension(Builder)
+	public static withOpenApi(builder: Builder, options: OpenApiOptions) {
+		getOrCreateHttpOptions(builder).openapi = {
+			validateRequests: true,
+			path: "/openapi.json",
+			...options,
+		};
+		return builder;
+	}
+
+	@extension(Builder)
+	public static withStatic(
+		builder: Builder,
+		prefix: string,
+		directory: string,
+		options?: StaticOptions,
+	) {
+		const httpOptions = getOrCreateHttpOptions(builder);
+		httpOptions.statics = [
+			...httpOptions.statics,
+			staticFiles.toMount(prefix, directory, options),
+		];
+		return builder;
+	}
+}

package/{types/src/http/http.options.store.d.ts → src/http/http.options.store.ts}

@@ -1,7 +1,17 @@
 import type { Builder } from "../builder/builder.js";
 import { HttpOptions } from "./http.options.js";
+
+const httpOptionsStore = new WeakMap<Builder, HttpOptions>();
+
 /**
  * The {@link HttpOptions} a builder collects through its extensions. Internal: lets extensions
  * outside `http.extensions.ts` (`withHealth`) set an option without a public builder method.
  */
-export declare function getOrCreateHttpOptions(builder: Builder): HttpOptions;
+export function getOrCreateHttpOptions(builder: Builder): HttpOptions {
+	let options = httpOptionsStore.get(builder);
+	if (options == null) {
+		options = new HttpOptions();
+		httpOptionsStore.set(builder, options);
+	}
+	return options;
+}

package/src/http/http.options.ts

@@ -0,0 +1,41 @@
+import type { Constructable } from "@decohere/core/reflection";
+import type { OpenApiOptions } from "../openapi/openapi.types.js";
+import type { CorsOptions } from "../routing/anvil.types.js";
+import type { ExceptionFilter } from "../routing/filters/exception-filter.js";
+import type { Middleware } from "../routing/middleware/middleware.js";
+import type { CompressionOptions } from "./http.compression.js";
+import type { StaticMount } from "./http.static.js";
+import type { HelmetOptions, RateLimitOptions } from "./http.security.js";
+
+/** Options for {@link Builder.withHttp} (request-id / access-log defaults, etc.). */
+export type WithHttpOptions = {
+	/**
+	 * Register {@link HttpAccessLogMiddleware} (request id echo + Scribe access log).
+	 * Defaults to `true`.
+	 */
+	accessLog?: boolean;
+};
+
+/** App-level HTTP options set via builder extensions (`withCors`, `withGlobalPrefix`, …). */
+export class HttpOptions {
+	public globalPrefix = "";
+	/**
+	 * Controllers put under the global prefix although they declare `globalPrefix: false`
+	 * (`withHealth({ underGlobalPrefix: true })`).
+	 */
+	public readonly underGlobalPrefix = new Set<Constructable>();
+	public cors?: CorsOptions;
+	public openapi?: OpenApiOptions;
+	/** `undefined` = helmet on with defaults; `false` = off; object = plugin options. */
+	public helmet?: HelmetOptions;
+	/** `undefined` = rate-limit on with defaults; `false` = off; object = plugin options. */
+	public rateLimit?: RateLimitOptions;
+	/** `undefined` = compression on with defaults; `false` = off; object = options. See `withCompression`. */
+	public compression?: CompressionOptions;
+	/** Request body size limit in bytes; `undefined` uses the 1 MiB default. */
+	public bodyLimit?: number;
+	/** Built UIs served from this API, see `withStatic`. */
+	public statics: StaticMount[] = [];
+	public middlewareTypes: Constructable<Middleware>[] = [];
+	public filterTypes: Constructable<ExceptionFilter>[] = [];
+}

package/{types/src/http/http.security.d.ts → src/http/http.security.ts}

@@ -3,18 +3,24 @@
  * `withHttpProvider` is used. Override via `withHelmet` / `withRateLimit` /
  * `withBodyLimit` (pass `false` to disable helmet or rate-limit).
  */
+
 /** Fastify body size limit (bytes). Matches Fastify's built-in default, made explicit and overridable. */
-export declare const DEFAULT_HTTP_BODY_LIMIT = 1048576;
+export const DEFAULT_HTTP_BODY_LIMIT = 1_048_576;
+
 /** Global request rate limit applied unless disabled or customized. */
-export declare const DEFAULT_HTTP_RATE_LIMIT: {
-    readonly max: 100;
-    readonly timeWindow: "1 minute";
-};
+export const DEFAULT_HTTP_RATE_LIMIT = {
+	max: 100,
+	timeWindow: "1 minute",
+} as const;
+
 /** `false` disables the plugin; an object customizes `@fastify/helmet`. */
 export type HelmetOptions = false | Record<string, unknown>;
+
 /** `false` disables the plugin; an object customizes `@fastify/rate-limit`. */
-export type RateLimitOptions = false | {
-    max?: number;
-    timeWindow?: number | string;
-    [key: string]: unknown;
-};
+export type RateLimitOptions =
+	| false
+	| {
+			max?: number;
+			timeWindow?: number | string;
+			[key: string]: unknown;
+	  };