@znight/http 0.2.2 → 0.4.0

package/README.md

@@ -236,6 +236,36 @@ the server's time zone) answer `400`. A missing required value answers `400 Miss
 `| undefined`, default value) receive `undefined` when absent, so default values apply:
 `@Query('page') page = 1`. A repeated query key for a scalar parameter is a `400`.
 
+### Custom parameter decorators
+
+`createParamDecorator` from `@znight/core` defines your own parameter decorators, such as a
+`@CurrentUser()` reading what an authentication guard stored (RFC 0010). The `http` resolver
+receives the `HttpContext` and the data argument of the use:
+
+```ts
+import { createParamDecorator } from '@znight/core'
+import { UnauthorizedException } from '@znight/http'
+import type { User } from './user.ts'
+
+export const CurrentUser = createParamDecorator<User>({
+  http: ctx => {
+    const user = ctx.state.get('user') as User | undefined
+    if (user === undefined) throw new UnauthorizedException()
+    return user
+  },
+})
+
+// @Get('/me') me(@CurrentUser() user: User) { return user }
+```
+
+The resolver runs inside `invoke`, after the guards and the interceptors, in parameter order with
+the other arguments; what it throws is answered like a handler error. It may return a promise (the
+route then awaits it), or be the class of a provider implementing `ParamResolver` (constructor
+injection, any scope: a request-scoped resolver is created once per request). The compiler checks
+every use: the decorator must have an `http` resolver, be the only parameter decorator of the
+parameter, and inject a type the parameter accepts. Custom parameters are not documented by
+`@znight/openapi`: document the header or cookie they read with `@ApiHeader` or `@ApiSecurity`.
+
 ## Validation
 
 Any library implementing [Standard Schema v1](https://standardschema.dev) works, without adapter:
@@ -1622,6 +1652,13 @@ export class StatusPlugin implements Plugin, PluginHttpRoutes {
   needs a decision there too: without one the boot fails (ZNIGHT023), with a hint naming the plugin.
 - An invalid route (method, path grammar, name, handler, meta, body limit) or a collision with another route is
   ZNIGHT007 naming the plugin. `HttpPlugin.routes` lists the routes with `source: '<plugin name>'`.
+- `onHttpDrain()` (optional) is called once when `HttpPlugin` starts draining, in its `onStop`,
+  whatever the plugin order: after it stopped accepting connections and started closing its event
+  streams, before it waits for the requests in flight. A plugin whose routes answer long-lived
+  streams `HttpPlugin` does not know of (a streamed `Response` produced by another server, such as a
+  GraphQL driver's subscriptions) ends them there, so that the drain does not wait for them until
+  `drainTimeoutMs`. The drain waits for a returned promise too (within `drainTimeoutMs`); a failure
+  is logged, never thrown.
 
 ## Adapters
 
@@ -2144,8 +2181,12 @@ Rules:
   stream (an `HttpResponse` or a Web `Response` is sent as usual). Only on `GET` routes; invalid
   values are ZNIGHT007 at boot.
 - Param sources (`HttpParamSource`): `param`, `query`, `body`, `headers`, `request`, `response`,
-  `context`, `file`, `files`, `cookie` and `signedCookie` (`name`: the cookie name; absent for
-  `@Cookie()`). A route with a `signedCookie` parameter fails the boot without `cookies.secrets`
+  `context`, `file`, `files`, `cookie`, `signedCookie` (`name`: the cookie name; absent for
+  `@Cookie()`) and `custom` (a custom parameter decorator, `name`: the decorator's name).
+- `paramResolvers` (`Token[]`, omitted when empty): the provider classes resolving custom
+  parameters (`ParamResolver`), in order of first use. `invoke` then takes a third parameter `x`,
+  the instances in that order; the plugin resolves them once at boot when they are all singletons,
+  otherwise in the request scope of each call. A route with a `signedCookie` parameter fails the boot without `cookies.secrets`
   (ZNIGHT006).
 - Guards, interceptors and controllers referenced by tokens must be providers (the compiler
   registers injectable helper classes, §6.5 `resolveClassRef`). Request-scoped guards/interceptors
@@ -2205,6 +2246,14 @@ expressions of the table below are `validate(S, ...)` calls in both forms.
 | `@UploadedFiles('f') f: File[]`         | `uploads.files(ctx, 'f')` · optional: `uploads.optionalFiles(ctx, 'f')`       |
 | `@UploadedFile()` / `@UploadedFiles()`  | the same helpers with `undefined` as field (any field)                        |
 | `@Ctx()`                                | `ctx`                                                                         |
+| custom, function resolver               | `(D.resolvers.http as ParamFunctionOf<typeof D, 'http'>)(ctx, data)`          |
+| custom, class resolver                  | `x[i].resolve(ctx, data)` (`data` left out when `resolve` declares one param) |
+
+Custom parameters (`createParamDecorator`, RFC 0010) are treated like validated arguments: the
+resolver may return a thenable, so each one is followed by the `isThenable` fallback, and the route
+stays synchronous while the resolvers return values. `data` is the literal data argument or an
+imported reference (`undefined` without argument). The cast `as never` is added when the compiler
+could not check the value type against the parameter.
 
 `coerce.X` by declared type (`T`):
 

package/dist/{adapter-J0UXFnNM.d.mts → adapter-DmhQGqAR.d.mts}

@@ -403,6 +403,12 @@ interface HttpRouteInfo {
    */
   readonly meta: Readonly<Record<string, unknown>>;
 }
+declare module "@znight/core" {
+  /** Custom parameter decorators (`createParamDecorator`) resolve HTTP parameters from the {@link HttpContext}. */
+  interface ParamContexts {
+    http: HttpContext;
+  }
+}
 /**
  * Adapter-neutral view of the current HTTP request, shared by guards, interceptors, exception
  * mappers and handlers (`@Ctx()`), and injectable in request-scoped providers.
@@ -528,7 +534,7 @@ type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTION
  * `name` being the multipart field; `cookie` / `signedCookie`: `@Cookie` / `@SignedCookie`, the
  * `name` being the cookie name).
  */
-type HttpParamSource = "param" | "query" | "body" | "headers" | "request" | "response" | "context" | "file" | "files" | "cookie" | "signedCookie";
+type HttpParamSource = "param" | "query" | "body" | "headers" | "request" | "response" | "context" | "file" | "files" | "cookie" | "signedCookie" | "custom";
 /** A handler parameter (informational: extraction, coercion and validation happen in `invoke`). */
 interface HttpParamDefinition {
   /** Position in the handler signature. */
@@ -613,10 +619,17 @@ interface HttpRouteDefinition {
    */
   readonly sse?: HttpSseDefinition;
   /**
-   * Calls the handler: extracts, coerces and validates every argument from the context, then calls
-   * the method on the controller instance. May return a promise.
+   * Provider classes resolving custom parameters (`ParamResolver`, RFC 0010), in order of first use:
+   * the plugin resolves them in the request scope and passes the instances to `invoke` as `x`
+   * (`x[i]` is the instance of `paramResolvers[i]`). Absent when the route has none.
+   */
+  readonly paramResolvers?: readonly Token[];
+  /**
+   * Calls the handler: extracts, coerces and validates every argument from the context (custom
+   * parameters included), then calls the method on the controller instance. May return a promise.
+   * `resolvers` is passed when the route has {@link paramResolvers}.
    */
-  readonly invoke: (controller: any, ctx: HttpContext) => unknown;
+  readonly invoke: (controller: any, ctx: HttpContext, resolvers?: any) => unknown;
 }
 /** A controller: a provider whose methods are routes. */
 interface HttpControllerDefinition {
@@ -879,4 +892,4 @@ interface HttpAdapter {
   injectStream?(request: InjectStreamRequest): Promise<InjectStreamResponse>;
 }
 export { PayloadTooLargeException as $, UploadedFileOptions as A, BadRequestException as B, HttpUploadDefinition as C, CookieOptions as Ct, RequestAbortedError as D, parseSetCookie as Dt, RequestAbortKind as E, parseCookieHeader as Et, formatByteSize as F, HeaderValue as G, ForbiddenException as H, parseByteSize as I, HttpExceptionOptions as J, HttpErrorBody as K, QueryRecord as L, Uploads as M, uploads as N, RequestId as O, serializeClearCookie as Ot, ByteSize as P, NotImplementedException as Q, parseQuery as R, HttpSseDefinition as S, CookieDefaults as St, HttpRouteInfo as T, SetCookieInfo as Tt, GatewayTimeoutException as U, ConflictException as V, GoneException as W, MethodNotAllowedException as X, InternalServerErrorException as Y, NotFoundException as Z, HttpMethod as _, StandardSchemaV1Result as _t, AdapterRoute as a, ValidationException as at, HttpRouteDefinition as b, isStandardSchema as bt, HttpServerAddress as c, toIssueDetail as ct, InjectStreamOptions as d, StandardSchemaV1 as dt, ServiceUnavailableException as et, InjectStreamRequest as f, StandardSchemaV1FailureResult as ft, HttpMetadata as g, StandardSchemaV1Props as gt, HttpControllerDefinition as h, StandardSchemaV1PathSegment as ht, AdapterRequest as i, UnsupportedMediaTypeException as it, UploadedFilesOptions as j, UploadLimits as k, serializeCookie as kt, InjectRequest as l, InferSchemaInput as lt, ReplyBody as m, StandardSchemaV1Options as mt, AdapterHandler as n, UnauthorizedException as nt, FallbackHandler as o, ValidationIssueDetail as ot, InjectStreamResponse as p, StandardSchemaV1Issue as pt, HttpException as q, AdapterReply as r, UnprocessableEntityException as rt, HttpAdapter as s, isHttpException as st, AdapterCloseOptions as t, TooManyRequestsException as tt, InjectResponse as u, InferSchemaOutput as ut, HttpParamDefinition as v, StandardSchemaV1SuccessResult as vt, HttpContext as w, ResponseCookie as wt, HttpRouteGroupDefinition as x, ClearCookieOptions as xt, HttpParamSource as y, StandardSchemaV1Types as yt, BadGatewayException as z };
-//# sourceMappingURL=adapter-J0UXFnNM.d.mts.map
+//# sourceMappingURL=adapter-DmhQGqAR.d.mts.map

package/dist/compiler.d.mts

@@ -1,4 +1,4 @@
-import { _ as HttpMethod, y as HttpParamSource } from "./adapter-J0UXFnNM.mjs";
+import { _ as HttpMethod, y as HttpParamSource } from "./adapter-DmhQGqAR.mjs";
 import { AnalyzeContext, ClassInfo, ClassRef, CompilerExtension, Location, MethodInfo, StaticValue, ValidateContext, ValueRef } from "@znight/compiler";
 /** Primitive coercions (`coerce.<kind>`). */
 type ScalarCoercion = "string" | "number" | "integer" | "boolean" | "bigint" | "date";
@@ -46,6 +46,26 @@ interface UploadData {
   /** The injected value does not have the declared type (`node:buffer` File, `File | null`): `as never`. */
   readonly cast: boolean;
 }
+/** A custom parameter (`createParamDecorator`, RFC 0010). */
+interface CustomParamData {
+  /** Canonical identity of the decorator `const` (imported by the generated module). */
+  readonly identity: string;
+  /** Name of the decorator (`CurrentUser`). */
+  readonly name: string;
+  /** The data argument: evaluated value (it may contain references) or a reference; `undefined` without argument. */
+  readonly data: {
+    readonly value: StaticValue;
+  } | undefined;
+  /** The class resolver (`x[i].resolve(ctx, data)`); `undefined` for a function resolver. */
+  readonly resolver: ClassRef | undefined;
+  /**
+   * Parameters of the class resolver's `resolve` (own, inherited or an arrow function property);
+   * `undefined` for a function resolver, or when the compiler cannot read it (the call is cast).
+   */
+  readonly arity?: number;
+  /** The value type could not be checked against the parameter: `as never`. */
+  readonly cast: boolean;
+}
 /** A handler parameter. */
 interface HttpParamData {
   /** Position in the handler signature. */
@@ -65,6 +85,8 @@ interface HttpParamData {
   readonly coercion: ParamCoercion | undefined;
   /** Upload parameter (`source` `file` / `files`). */
   readonly upload?: UploadData;
+  /** Custom parameter (`source` `custom`). */
+  readonly custom?: CustomParamData;
   /**
    * The default value of the handler parameter (`@Query('page') page = 1` → `1`), when it is
    * statically evaluable (literals, `const` references; references to exported bindings are left

package/dist/compiler.mjs

@@ -1150,7 +1150,15 @@ function analyzeParams(ctx, cls, method, where, bodyValidation) {
 	const params = [];
 	let complete = true;
 	for (const param of method.params) {
-		const [decorator, ...extra] = unique(param.decorators).filter((decorator) => decorator.owner === "http" && PARAM_SOURCES.has(decorator.identity ?? ""));
+		const decorators = unique(param.decorators).filter((decorator) => decorator.owner === "http" && PARAM_SOURCES.has(decorator.identity ?? ""));
+		const custom = typeof ctx.paramDecorator === "function" ? ctx.paramDecorator(param, "http", cls) : void 0;
+		if (custom !== void 0) {
+			for (const other of decorators) error(ctx, other.location, `Parameter '${param.name}' of ${where} has several parameter decorators (@${custom.decorator.name} and @${other.name})`, ["Keep a single parameter decorator"]);
+			if (custom.ok && decorators.length === 0) params.push(customParam(param, custom));
+			else complete = false;
+			continue;
+		}
+		const [decorator, ...extra] = decorators;
 		const foreign = decorator === void 0 ? foreignParameterDecorator(param) : void 0;
 		if (foreign !== void 0) {
 			error(ctx, foreign.decorator.location, `@${foreign.decorator.name} on parameter '${param.name}' of ${where} is imported from '${foreign.module}': route parameters use ${foreign.name} from '${HTTP_PACKAGE}'`, [`Import it from '${HTTP_PACKAGE}': import { ${foreign.name} } from '${HTTP_PACKAGE}'`]);
@@ -1177,6 +1185,29 @@ function analyzeParams(ctx, cls, method, where, bodyValidation) {
 		complete
 	};
 }
+/** A custom parameter (`source: 'custom'`, the decorator name as `name`). */
+function customParam(param, use) {
+	const data = use.data;
+	return {
+		index: param.index,
+		name: param.name,
+		source: "custom",
+		key: use.name,
+		type: void 0,
+		optional: param.optional || param.hasDefault,
+		schema: void 0,
+		coercion: void 0,
+		custom: {
+			identity: use.identity,
+			name: use.name,
+			data: data === void 0 ? void 0 : { value: data.ref ?? data.value },
+			resolver: use.resolver.kind === "class" ? use.resolver.ref : void 0,
+			...use.resolver.kind === "class" && use.resolver.arity !== void 0 ? { arity: use.resolver.arity } : {},
+			cast: use.cast
+		},
+		location: use.location
+	};
+}
 function analyzeParam(ctx, cls, method, param, decorator, where, bodyValidation) {
 	const source = PARAM_SOURCES.get(decorator.identity ?? "");
 	if (source === void 0) return;
@@ -1730,6 +1761,7 @@ function createHelpers(ctx) {
 	let isThenable;
 	let uploads;
 	let context;
+	let paramFunctionOf;
 	return {
 		coerce: () => {
 			coerce ??= ctx.importFrom(HTTP_PACKAGE, "coerce");
@@ -1750,6 +1782,10 @@ function createHelpers(ctx) {
 		context: () => {
 			context ??= ctx.importFrom(HTTP_PACKAGE, "HttpContext", { type: true });
 			return context;
+		},
+		paramFunctionOf: () => {
+			paramFunctionOf ??= ctx.importFrom("@znight/core", "ParamFunctionOf", { type: true });
+			return paramFunctionOf;
 		}
 	};
 }
@@ -1778,7 +1814,9 @@ function routeNode(ctx, helpers, controller, route) {
 	if (uploads.length > 0) entries.push(["uploads", ctx.arr(uploads.map((upload) => uploadNode(ctx, upload)))]);
 	if (route.rawResponse) entries.push(["rawResponse", true]);
 	if (route.sse !== void 0) entries.push(["sse", sseNode(ctx, route.sse)]);
-	entries.push(["invoke", invokeNode(ctx, helpers, controller, route)]);
+	const resolvers = paramResolvers(route);
+	if (resolvers.length > 0) entries.push(["paramResolvers", tokens(ctx, resolvers)]);
+	entries.push(["invoke", invokeNode(ctx, helpers, controller, route, resolvers)]);
 	return ctx.obj(entries);
 }
 /** `{ heartbeat?, retry?, maxDuration? }` (`{}` without options). */
@@ -1821,20 +1859,73 @@ function tokens(ctx, refs) {
 * `@Body()` parameter reads the body in `invoke`: that arrow is `async` and `await`s every
 * `validate()`.
 */
-function invokeNode(ctx, helpers, controller, route) {
+function invokeNode(ctx, helpers, controller, route, resolvers) {
 	const params = [["c", ctx.importType(controller.identity)]];
-	if (route.params.length > 0 || route.bodySchema !== void 0) params.push(["ctx", helpers.context()]);
+	if (route.params.length > 0 || route.bodySchema !== void 0) params.push([readsContext(route) ? "ctx" : "_ctx", helpers.context()]);
+	if (resolvers.length > 0) {
+		const tuple = resolvers.map((ref) => ctx.importType(ref));
+		params.push(["x", ctx.code`readonly [${joinNodes(ctx, tuple)}]`]);
+		const index = new Map(resolvers.map((ref, position) => [ref.token, position]));
+		const withResolvers = (x) => x === void 0 ? helpers : {
+			...helpers,
+			resolvers: {
+				x,
+				index
+			}
+		};
+		return invokeArrow(ctx, params, route, (c, http, x) => [
+			c,
+			http,
+			withResolvers(x)
+		]);
+	}
+	return invokeArrow(ctx, params, route, (c, http) => [
+		c,
+		http,
+		helpers
+	]);
+}
+/** `true` when an argument (or the body validation) reads the context: all but a `resolve()` without parameter. */
+function readsContext(route) {
+	return route.bodySchema !== void 0 || route.params.some((param) => param.custom?.resolver === void 0 || param.custom.arity !== 0);
+}
+/** The provider classes resolving custom parameters, in order of first use (`x[i]`). */
+function paramResolvers(route) {
+	const found = /* @__PURE__ */ new Map();
+	for (const param of route.params) {
+		const resolver = param.custom?.resolver;
+		if (resolver !== void 0 && !found.has(resolver.token)) found.set(resolver.token, resolver);
+	}
+	return [...found.values()];
+}
+/** `a, b, c`. */
+function joinNodes(ctx, nodes) {
+	return nodes.slice(1).reduce((joined, node) => ctx.code`${joined}, ${node}`, nodes[0]);
+}
+/** The arrow of {@link invokeNode}; `bind` maps the arrow parameters to the controller, the context and the helpers. */
+function invokeArrow(ctx, params, route, bind) {
 	const slots = [];
 	for (const param of route.params) slots[param.index] = param;
 	const bodySchema = route.bodySchema;
-	if (bodySchema !== void 0) return ctx.arrow(params, (c, http) => {
+	if (bodySchema !== void 0) return ctx.arrow(params, (...bound) => {
+		const [c, http, helpers] = bind(...bound);
 		const call = handlerCall(ctx, c, route, Array.from(slots, (param) => awaitedArgument(ctx, helpers, http, param)));
 		const body = ctx.code`await ${ctx.call(ctx.member(http, "parseBody"))}`;
 		const check = ctx.code`await ${validation(ctx, helpers, bodySchema, body, "body")}`;
 		return ctx.code`{ ${check}; return ${call} }`;
 	}, { async: true });
-	const last = slots.findLastIndex((param) => param?.schema !== void 0);
-	return ctx.arrow(params, (c, http) => last === -1 ? handlerCall(ctx, c, route, Array.from(slots, (param) => plainArgument(ctx, helpers, http, param))) : validatingBlock(ctx, helpers, route, slots, last, c, http));
+	const last = slots.findLastIndex((param) => param !== void 0 && isDeferred(param));
+	return ctx.arrow(params, (...bound) => {
+		const [c, http, helpers] = bind(...bound);
+		return last === -1 ? handlerCall(ctx, c, route, Array.from(slots, (param) => plainArgument(ctx, helpers, http, param))) : validatingBlock(ctx, helpers, route, slots, last, c, http);
+	});
+}
+/**
+* `true` for an argument whose expression may return a thenable: a validation with a schema, or a
+* custom parameter (its resolver may return a promise).
+*/
+function isDeferred(param) {
+	return param.schema !== void 0 || param.custom !== void 0;
 }
 /** `c.handler(args)`. */
 function handlerCall(ctx, c, route, args) {
@@ -1873,7 +1964,7 @@ function validatingBlock(ctx, helpers, route, slots, last, c, http) {
 			const param = slots[index];
 			const name = local.get(index);
 			statements.push(ctx.code`const ${name} = ${plainArgument(ctx, helpers, http, param)}`);
-			if (param.schema !== void 0) {
+			if (isDeferred(param)) {
 				const rest = Array.from(slots, (other, position) => {
 					if (position < index) return evaluated(position);
 					return position === index ? ctx.code`await ${name}` : awaitedArgument(ctx, helpers, http, other);
@@ -1890,7 +1981,7 @@ function validatingBlock(ctx, helpers, route, slots, last, c, http) {
 /** An argument evaluated in an `async` arrow: its validation, if any, is `await`ed. */
 function awaitedArgument(ctx, helpers, http, param) {
 	const node = plainArgument(ctx, helpers, http, param);
-	return param?.schema === void 0 ? node : ctx.code`await ${node}`;
+	return param === void 0 || !isDeferred(param) ? node : ctx.code`await ${node}`;
 }
 /** An argument as an expression (`validate()` not awaited); `undefined` for a hole. */
 function plainArgument(ctx, helpers, http, param) {
@@ -1943,7 +2034,33 @@ function argumentNode(ctx, helpers, http, param) {
 				cast: false
 			}, value, label);
 		}
+		case "custom": return customArgument(ctx, helpers, http, param.custom);
+	}
+}
+/**
+* A custom parameter (RFC 0010): `(D.resolvers.http as ParamFunctionOf<typeof D, 'http'>)(ctx, data)`
+* for a function resolver, `x[i].resolve(ctx, data)` for a class resolver; cast with `as never` when
+* the value type could not be checked against the parameter.
+*/
+function customArgument(ctx, helpers, http, custom) {
+	const data = custom.data === void 0 ? ctx.lit(void 0) : dataNode(ctx, custom.data.value);
+	let call;
+	if (custom.resolver === void 0) {
+		const decorator = ctx.importValue(custom.identity);
+		const callee = ctx.code`${ctx.member(decorator, "resolvers", "http")} as ${helpers.paramFunctionOf()}<typeof ${decorator}, 'http'>`;
+		call = ctx.call(callee, [http, data]);
+	} else {
+		const resolvers = helpers.resolvers;
+		const index = resolvers.index.get(custom.resolver.token);
+		if (custom.arity === void 0) return ctx.code`(${resolvers.x}[${index}] as { resolve(ctx: unknown, data: unknown): unknown }).resolve(${http}, ${data}) as never`;
+		const args = [http, data].slice(0, custom.arity);
+		call = ctx.code`${resolvers.x}[${index}].resolve(${args.length === 0 ? ctx.code`` : joinNodes(ctx, args)})`;
 	}
+	return custom.cast ? ctx.code`${call} as never` : call;
+}
+/** The data argument of a custom parameter: a literal (references imported) or a reference. */
+function dataNode(ctx, value) {
+	return isValueRef(value) ? ctx.ref(value) : ctx.lit(value);
 }
 /** `validate(schema, value, location)` (the value, or a promise when the schema validates asynchronously). */
 function validation(ctx, helpers, schema, value, location) {