@znight/http 0.2.2 → 0.4.0

package/dist/node.d.mts

@@ -1,4 +1,4 @@
-import { s as HttpAdapter } from "./adapter-J0UXFnNM.mjs";
+import { s as HttpAdapter } from "./adapter-DmhQGqAR.mjs";
 import { IncomingMessage, Server, ServerOptions, ServerResponse } from "node:http";
 /** Options of {@link nodeAdapter}. */
 export interface NodeAdapterOptions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@znight/http",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "description": "Znight HTTP plugin: controllers, routing, guards, interceptors, validation with Fastify, Express or Hono",
   "license": "MIT",
   "author": "Ugho STEPHAN",
@@ -79,7 +79,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@znight/core": "0.2.2"
+    "@znight/core": "0.4.0"
   },
   "peerDependencies": {
     "@hono/node-server": "^2.1.5",
@@ -87,7 +87,7 @@
     "fastify": "^5.12.7",
     "hono": "^4.13.14",
     "light-my-request": "^6.8.0",
-    "@znight/compiler": "^0.2.2"
+    "@znight/compiler": "^0.4.0"
   },
   "peerDependenciesMeta": {
     "@hono/node-server": {
@@ -118,7 +118,7 @@
     "valibot": "1.5.0",
     "zod": "4.6.7",
     "light-my-request": "6.8.0",
-    "@znight/compiler": "0.2.2"
+    "@znight/compiler": "0.4.0"
   },
   "znight": {
     "apiVersion": 1,

package/src/compiler/analyze.ts

@@ -11,6 +11,7 @@ import type {
   DecoratorInfo,
   Location,
   MethodInfo,
+  ParamDecoratorUse,
   ParameterInfo,
   StaticValue,
   TypeInfo,
@@ -813,6 +814,24 @@ function analyzeParams(
     const decorators = unique(param.decorators).filter(
       decorator => decorator.owner === EXTENSION_NAME && PARAM_SOURCES.has(decorator.identity ?? ''),
     )
+    // custom parameter decorators (RFC 0010); compilers before it have no paramDecorator
+    const custom = typeof ctx.paramDecorator === 'function' ? ctx.paramDecorator(param, 'http', cls) : undefined
+    if (custom !== undefined) {
+      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 === undefined ? foreignParameterDecorator(param) : undefined
     if (foreign !== undefined) {
@@ -852,6 +871,30 @@ function analyzeParams(
   return { params, complete }
 }
 
+/** A custom parameter (`source: 'custom'`, the decorator name as `name`). */
+function customParam(param: ParameterInfo, use: Extract<ParamDecoratorUse, { readonly ok: true }>): HttpParamData {
+  const data = use.data
+  return {
+    index: param.index,
+    name: param.name,
+    source: 'custom',
+    key: use.name,
+    type: undefined,
+    optional: param.optional || param.hasDefault,
+    schema: undefined,
+    coercion: undefined,
+    custom: {
+      identity: use.identity,
+      name: use.name,
+      data: data === undefined ? undefined : { value: data.ref ?? (data.value as StaticValue) },
+      resolver: use.resolver.kind === 'class' ? use.resolver.ref : undefined,
+      ...(use.resolver.kind === 'class' && use.resolver.arity !== undefined ? { arity: use.resolver.arity } : {}),
+      cast: use.cast,
+    },
+    location: use.location,
+  }
+}
+
 function analyzeParam(
   ctx: Context,
   cls: ClassInfo,

package/src/compiler/generate.ts

@@ -3,9 +3,10 @@
  * (README, "Compiler contract"). Controllers are sorted by token, routes keep their source order and
  * every route gets an `invoke(c, ctx)` arrow extracting, coercing and validating its arguments.
  */
-import type { ClassRef, GenerateContext, GenInput, GenNode, ValueRef } from '@znight/compiler'
+import type { ClassRef, GenerateContext, GenInput, GenNode, StaticValue, ValueRef } from '@znight/compiler'
 import type {
   CoercionPlan,
+  CustomParamData,
   HttpControllerData,
   HttpParamData,
   HttpRouteData,
@@ -17,6 +18,7 @@ import type {
 
 import { compareStrings } from '../path.ts'
 import { HTTP_PACKAGE } from './model.ts'
+import { isValueRef } from './route-decorators.ts'
 
 type Context = GenerateContext<HttpControllerData>
 
@@ -33,6 +35,9 @@ interface Helpers {
   isThenable(): GenNode
   uploads(): GenNode
   context(): GenNode
+  paramFunctionOf(): GenNode
+  /** The resolver instances of the route being generated (`x`), with the index of each token. */
+  readonly resolvers?: { readonly x: GenNode; readonly index: ReadonlyMap<string, number> }
 }
 
 /** Generates `metadata.extensions.http` (`undefined` when the application has no controller). */
@@ -102,6 +107,7 @@ function createHelpers(ctx: Context): Helpers {
   let isThenable: GenNode | undefined
   let uploads: GenNode | undefined
   let context: GenNode | undefined
+  let paramFunctionOf: GenNode | undefined
   return {
     coerce: () => {
       coerce ??= ctx.importFrom(HTTP_PACKAGE, 'coerce')
@@ -123,6 +129,10 @@ function createHelpers(ctx: Context): Helpers {
       context ??= ctx.importFrom(HTTP_PACKAGE, 'HttpContext', { type: true })
       return context
     },
+    paramFunctionOf: () => {
+      paramFunctionOf ??= ctx.importFrom('@znight/core', 'ParamFunctionOf', { type: true })
+      return paramFunctionOf
+    },
   }
 }
 
@@ -169,7 +179,11 @@ function routeNode(ctx: Context, helpers: Helpers, controller: HttpControllerDat
   if (route.sse !== undefined) {
     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)
 }
 
@@ -251,12 +265,63 @@ function tokens(ctx: Context, refs: readonly ClassRef[]): GenNode {
  * `@Body()` parameter reads the body in `invoke`: that arrow is `async` and `await`s every
  * `validate()`.
  */
-function invokeNode(ctx: Context, helpers: Helpers, controller: HttpControllerData, route: HttpRouteData): GenNode {
+function invokeNode(
+  ctx: Context,
+  helpers: Helpers,
+  controller: HttpControllerData,
+  route: HttpRouteData,
+  resolvers: readonly ClassRef[],
+): GenNode {
   const params: [string, GenNode][] = [['c', ctx.importType(controller.identity)]]
-  // `ctx` is declared only when used (generated code type-checks with `noUnusedParameters`)
+  // `ctx` is declared only when used (generated code type-checks with `noUnusedParameters`), and as
+  // `_ctx` before `x` when only class resolvers whose `resolve()` takes no parameter need arguments
   if (route.params.length > 0 || route.bodySchema !== undefined) {
-    params.push(['ctx', helpers.context()])
+    params.push([readsContext(route) ? 'ctx' : '_ctx', helpers.context()])
+  }
+  // `x`: the instances of the parameter resolvers (RFC 0010), only for routes that have some
+  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: GenNode | undefined): Helpers =>
+      x === undefined ? 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: HttpRouteData): boolean {
+  return (
+    route.bodySchema !== undefined ||
+    route.params.some(param => param.custom?.resolver === undefined || param.custom.arity !== 0)
+  )
+}
+
+/** The provider classes resolving custom parameters, in order of first use (`x[i]`). */
+function paramResolvers(route: HttpRouteData): ClassRef[] {
+  const found = new Map<string, ClassRef>()
+  for (const param of route.params) {
+    const resolver = param.custom?.resolver
+    if (resolver !== undefined && !found.has(resolver.token)) {
+      found.set(resolver.token, resolver)
+    }
   }
+  return [...found.values()]
+}
+
+/** `a, b, c`. */
+function joinNodes(ctx: Context, nodes: readonly GenNode[]): GenNode {
+  return nodes.slice(1).reduce((joined, node) => ctx.code`${joined}, ${node}`, nodes[0] as GenNode)
+}
+
+/** The arrow of {@link invokeNode}; `bind` maps the arrow parameters to the controller, the context and the helpers. */
+function invokeArrow(
+  ctx: Context,
+  params: readonly [string, GenNode][],
+  route: HttpRouteData,
+  bind: (...params: GenNode[]) => readonly [GenNode, GenNode | undefined, Helpers],
+): GenNode {
   // arguments in evaluation order (handler parameter order); a hole is passed as `undefined`
   const slots: (HttpParamData | undefined)[] = []
   for (const param of route.params) {
@@ -266,7 +331,8 @@ function invokeNode(ctx: Context, helpers: Helpers, controller: HttpControllerDa
   if (bodySchema !== undefined) {
     return ctx.arrow(
       params,
-      (c, http) => {
+      (...bound) => {
+        const [c, http, helpers] = bind(...bound)
         const call = handlerCall(
           ctx,
           c,
@@ -281,17 +347,26 @@ function invokeNode(ctx: Context, helpers: Helpers, controller: HttpControllerDa
       { async: true },
     )
   }
-  const last = slots.findLastIndex(param => param?.schema !== undefined)
-  return ctx.arrow(params, (c, http) =>
-    last === -1
+  const last = slots.findLastIndex(param => param !== undefined && 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 as GenNode, param)),
         )
-      : validatingBlock(ctx, helpers, route, slots, last, c, http as GenNode),
-  )
+      : validatingBlock(ctx, helpers, route, slots, last, c, http as GenNode)
+  })
+}
+
+/**
+ * `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: HttpParamData): boolean {
+  return param.schema !== undefined || param.custom !== undefined
 }
 
 /** `c.handler(args)`. */
@@ -346,7 +421,7 @@ function validatingBlock(
         const param = slots[index] as HttpParamData
         const name = local.get(index) as GenNode
         statements.push(ctx.code`const ${name} = ${plainArgument(ctx, helpers, http, param)}`)
-        if (param.schema !== undefined) {
+        if (isDeferred(param)) {
           const rest = Array.from(slots, (other, position) => {
             if (position < index) {
               return evaluated(position)
@@ -369,7 +444,7 @@ function validatingBlock(
 /** An argument evaluated in an `async` arrow: its validation, if any, is `await`ed. */
 function awaitedArgument(ctx: Context, helpers: Helpers, http: GenNode, param: HttpParamData | undefined): GenNode {
   const node = plainArgument(ctx, helpers, http, param)
-  return param?.schema === undefined ? node : ctx.code`await ${node}`
+  return param === undefined || !isDeferred(param) ? node : ctx.code`await ${node}`
 }
 
 /** An argument as an expression (`validate()` not awaited); `undefined` for a hole. */
@@ -435,9 +510,43 @@ function argumentNode(ctx: Context, helpers: Helpers, http: GenNode, param: Http
       }
       return coercion(ctx, helpers, param.coercion ?? { plan: { kind: 'raw' }, cast: false }, value, label)
     }
+    case 'custom':
+      return customArgument(ctx, helpers, http, param.custom as CustomParamData)
   }
 }
 
+/**
+ * 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: Context, helpers: Helpers, http: GenNode, custom: CustomParamData): GenNode {
+  const data = custom.data === undefined ? ctx.lit(undefined) : dataNode(ctx, custom.data.value)
+  let call: GenNode
+  if (custom.resolver === undefined) {
+    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 as NonNullable<Helpers['resolvers']>
+    const index = resolvers.index.get(custom.resolver.token) as number
+    if (custom.arity === undefined) {
+      // a `resolve` the compiler cannot read (inherited from a mixin...): the instance is cast to a
+      // method taking both arguments (method parameters are bivariant), the value with `as never`
+      return ctx.code`(${resolvers.x}[${index}] as { resolve(ctx: unknown, data: unknown): unknown }).resolve(${http}, ${data}) as never`
+    }
+    // a `resolve(ctx)` that ignores the data gets no data argument (TypeScript checks the arity)
+    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: Context, value: StaticValue): GenNode {
+  return isValueRef(value) ? ctx.ref(value) : ctx.lit(value as Parameters<Context['lit']>[0])
+}
+
 /** `validate(schema, value, location)` (the value, or a promise when the schema validates asynchronously). */
 function validation(ctx: Context, helpers: Helpers, schema: ValueRef, value: GenNode, location: string): GenNode {
   return ctx.call(helpers.validate(), [ctx.ref(schema), value, location])

package/src/compiler/model.ts

@@ -150,6 +150,25 @@ export interface UploadData {
   readonly cast: boolean
 }
 
+/** A custom parameter (`createParamDecorator`, RFC 0010). */
+export 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. */
 export interface HttpParamData {
   /** Position in the handler signature. */
@@ -169,6 +188,8 @@ export 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/src/context.ts

@@ -63,6 +63,13 @@ export 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.

package/src/metadata.ts

@@ -26,6 +26,8 @@ export type HttpParamSource =
   | 'files'
   | 'cookie'
   | 'signedCookie'
+  /** A custom parameter decorator (`createParamDecorator`, RFC 0010); `name` is the decorator's name. */
+  | 'custom'
 
 /** A handler parameter (informational: extraction, coercion and validation happen in `invoke`). */
 export interface HttpParamDefinition {
@@ -114,11 +116,18 @@ export 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.
    */
-  // biome-ignore lint/suspicious/noExplicitAny: generated functions take the concrete controller class
-  readonly invoke: (controller: any, ctx: HttpContext) => unknown
+  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}.
+   */
+  // biome-ignore lint/suspicious/noExplicitAny: generated functions take the concrete controller class and resolver tuple
+  readonly invoke: (controller: any, ctx: HttpContext, resolvers?: any) => unknown
 }
 
 /** A controller: a provider whose methods are routes. */

package/src/pipeline.ts

@@ -1,5 +1,6 @@
 import type { Container, CoreLogger, Hooks, HttpRequestEvent, OpenedScope, Token } from '@znight/core'
 import type { AdapterHandler, AdapterReply, AdapterRequest, ReplyBody } from './adapter.ts'
+import type { HttpContext } from './context.ts'
 import type { CookieSettings } from './cookie-settings.ts'
 import type { SerializedCookie } from './cookies.ts'
 import type { CorsPolicy } from './cors.ts'
@@ -53,6 +54,11 @@ export type Resolvable<T> = { readonly instance: T } | { readonly token: Token }
 /** Everything the pipeline needs to serve one registered route (internal). */
 export interface RoutePlan {
   readonly definition: HttpRouteDefinition
+  /**
+   * Calls the handler: `definition.invoke`, or for a route with parameter resolvers a function
+   * passing their instances (resolved in the request scope) as the third argument.
+   */
+  readonly invoke: (controller: object, ctx: HttpContext) => unknown
   /** The registered path (a trailing-slash variant has an extra empty static segment). */
   readonly path: RoutePath
   readonly info: HttpRouteInfo
@@ -436,7 +442,7 @@ export class Pipeline {
     let result: unknown
     let reply: AdapterReply | undefined
     try {
-      result = plan.definition.invoke(this.#resolve(plan.controller), ctx)
+      result = plan.invoke(this.#resolve(plan.controller), ctx)
       if (isThenable(result)) return this.#fastLater(route, request, ctx, result, startTime)
       reply = this.#fastReply(route, ctx, result)
     } catch (error) {
@@ -480,7 +486,7 @@ export class Pipeline {
       if (result === NO_RESULT) {
         const controller = this.#resolve(plan.controller)
         await ctx.parseBody()
-        result = plan.definition.invoke(controller, ctx)
+        result = plan.invoke(controller, ctx)
       }
       if (isThenable(result)) result = await result
       reply = this.#fastReply(route, ctx, result)
@@ -584,7 +590,7 @@ export class Pipeline {
     if (plan.parseBody) return this.#fastOperationLater(x, route, NO_RESULT)
     let result: unknown
     try {
-      result = plan.definition.invoke(this.#resolve(plan.controller), ctx)
+      result = plan.invoke(this.#resolve(plan.controller), ctx)
     } catch (error) {
       return this.#fastChecked(x, this.#failed(error, ctx, x.event))
     }
@@ -601,7 +607,7 @@ export class Pipeline {
       if (result === NO_RESULT) {
         const controller = this.#resolve(plan.controller)
         await ctx.parseBody()
-        result = plan.definition.invoke(controller, ctx)
+        result = plan.invoke(controller, ctx)
       }
       if (isThenable(result)) result = await result
     } catch (error) {
@@ -1235,13 +1241,12 @@ export class Pipeline {
         if (allowed !== true) throw new ForbiddenException('Forbidden resource')
       }
       if (plan.parseBody) await ctx.parseBody()
-      const definition = plan.definition
       const interceptors = plan.interceptors
       if (interceptors.length === 0) {
-        result = definition.invoke(controller, ctx)
+        result = plan.invoke(controller, ctx)
       } else {
         const chain = async (index: number): Promise<unknown> => {
-          if (index === interceptors.length) return await definition.invoke(controller, ctx)
+          if (index === interceptors.length) return await plan.invoke(controller, ctx)
           const interceptor = this.#resolve(interceptors[index] as Resolvable<HttpInterceptor>)
           return await interceptor.intercept(ctx, () => chain(index + 1))
         }

package/src/plugin-routes.ts

@@ -3,7 +3,7 @@
  * health or metrics endpoints), registered on every adapter in the same pipeline as the compiled
  * controllers.
  */
-import type { Container, Plugin } from '@znight/core'
+import type { Container, CoreLogger, Plugin } from '@znight/core'
 import type { HttpContext } from './context.ts'
 import type { RouteMetaEntry } from './decorators.ts'
 import type { HttpMethod } from './metadata.ts'
@@ -71,6 +71,14 @@ export interface PluginHttpRoutesContext {
  */
 export interface PluginHttpRoutes {
   httpRoutes(context: PluginHttpRoutesContext): readonly PluginRoute[]
+  /**
+   * Called once when `HttpPlugin` starts draining (its `onStop`, whatever the plugin order), after
+   * it stopped accepting connections and started closing its event streams: end the long-lived
+   * responses `HttpPlugin` does not know of (a stream another server produced), so that the drain
+   * does not wait for them until `drainTimeoutMs`. Requests still in flight are served. The drain
+   * waits for a returned promise too (within `drainTimeoutMs`); a failure is logged.
+   */
+  onHttpDrain?(): void | Promise<void>
 }
 
 /** A validated plugin route (internal). */
@@ -122,6 +130,31 @@ export function collectPluginRoutes(
   return collected
 }
 
+/**
+ * Calls `onHttpDrain()` on every other plugin implementing it, in plugin order: the promises the
+ * drain waits for (they never reject: a failure is logged).
+ */
+export function drainPlugins(plugins: readonly Plugin[], self: Plugin, logger: CoreLogger): Promise<void>[] {
+  const pending: Promise<void>[] = []
+  for (const plugin of plugins) {
+    if (plugin === self) continue
+    const drain = (plugin as Plugin & Partial<PluginHttpRoutes>).onHttpDrain
+    if (typeof drain !== 'function') continue
+    const failed = (error: unknown): void => {
+      logger.error(`HttpPlugin: onHttpDrain() of the plugin "${String(plugin.name)}" failed`, { err: error })
+    }
+    try {
+      const result: unknown = drain.call(plugin)
+      if (typeof (result as PromiseLike<void> | undefined)?.then === 'function') {
+        pending.push(Promise.resolve(result as PromiseLike<void>).then(undefined, failed))
+      }
+    } catch (error) {
+      failed(error)
+    }
+  }
+  return pending
+}
+
 function validateRoute(instance: object, plugin: string, value: unknown, prefix: string): CollectedPluginRoute {
   if (value === null || typeof value !== 'object') throw invalid(plugin, `invalid route ${describe(value)}`)
   const route = value as Partial<PluginRoute>

package/src/plugin.ts

@@ -56,7 +56,7 @@ import {
   randomRequestId,
   type SseSettings,
 } from './pipeline.ts'
-import { collectPluginRoutes } from './plugin-routes.ts'
+import { collectPluginRoutes, drainPlugins } from './plugin-routes.ts'
 import { resolveTrustProxy } from './proxy.ts'
 import { RouteTable } from './router.ts'
 import { resolveSecurityHeaders } from './security-headers.ts'
@@ -552,6 +552,8 @@ export class HttpPlugin implements Plugin {
     runtime.pipeline.draining = true
     // event streams never end by themselves: let their sources finish, then send them a jittered retry
     runtime.pipeline.closeStreams('shutdown')
+    // the streams other plugins serve on their routes (a GraphQL driver's subscriptions)
+    const drains = drainPlugins(ctx.app.plugins, this, ctx.logger)
     const timeoutMs = runtime.options.drainTimeoutMs
     let timer: ReturnType<typeof setTimeout> | undefined
     // no timer for Infinity; larger delays than setTimeout supports are clamped (they would fire at once)
@@ -561,7 +563,9 @@ export class HttpPlugin implements Plugin {
       }
     })
     try {
-      const drained = Promise.all([runtime.adapter.close(), runtime.pipeline.whenIdle()]).then(() => 'drained' as const)
+      const drained = Promise.all([runtime.adapter.close(), runtime.pipeline.whenIdle(), ...drains]).then(
+        () => 'drained' as const,
+      )
       if ((await Promise.race([drained, timeout])) === 'timeout') {
         ctx.logger.warn(`HTTP server: closing ${runtime.pipeline.inflight} in-flight request(s) after ${timeoutMs} ms`)
         await runtime.adapter.close({ force: true })
@@ -965,6 +969,7 @@ function buildRegistrations(
       const body = bodyPlan(route, options.bodyLimit, options.uploads)
       const parseBody = body.upload || route.params.some(param => param.source === 'body')
       const chain = guards.map(guard => guard.resolvable)
+      const invoke = routeInvoke(container, route, lookup, where)
       // computed once every group is declared (guards of every chain, plugin routes), then frozen
       let meta: RouteMeta | undefined
       const effective = (): RouteMeta => {
@@ -977,6 +982,7 @@ function buildRegistrations(
         path,
         plan: (method: string): RoutePlan => ({
           definition: route,
+          invoke,
           path,
           info: Object.freeze({
             method,
@@ -1048,6 +1054,7 @@ function buildRegistrations(
       path,
       plan: (method: string): RoutePlan => ({
         definition,
+        invoke: definition.invoke,
         path,
         info: Object.freeze({ method, path: path.path, controller: route.plugin, handler: route.name, meta }),
         controller: instance,
@@ -1260,6 +1267,9 @@ function assertRoute(route: HttpRouteDefinition, where: string): void {
   }
   if (route.uploads !== undefined) assertUploads(route, where)
   if (route.sse !== undefined) assertSse(route, where)
+  if (route.paramResolvers !== undefined && !Array.isArray(route.paramResolvers)) {
+    throw new ZnightError(ErrorCode.InvalidRoute, `Invalid route ${where}: paramResolvers must be an array of tokens`)
+  }
 }
 
 function assertSse(route: HttpRouteDefinition, where: string): void {
@@ -1336,6 +1346,33 @@ function describeValue(value: unknown): string {
 // Provider resolution
 // -------------------------------------------------------------------------------------------------
 
+/**
+ * The `invoke` of a route plan: the generated `invoke` itself, unless the route has parameter
+ * resolvers (RFC 0010), whose instances are passed as its third argument: one frozen array resolved
+ * at bootstrap when they are all singletons, otherwise an array resolved in the request scope.
+ */
+function routeInvoke(
+  container: Container,
+  route: HttpRouteDefinition,
+  lookup: <T>(token: Token, what: string) => Resolvable<T>,
+  where: string,
+): RoutePlan['invoke'] {
+  const invoke = route.invoke
+  const tokens = route.paramResolvers
+  if (tokens === undefined || tokens.length === 0) return invoke
+  const resolvers = tokens.map(token => lookup<object>(token, `parameter resolver of ${where}`))
+  if (resolvers.every(resolver => 'instance' in resolver)) {
+    const instances = Object.freeze(resolvers.map(resolver => (resolver as { readonly instance: object }).instance))
+    return (controller, ctx) => invoke(controller, ctx, instances)
+  }
+  return (controller, ctx) =>
+    invoke(
+      controller,
+      ctx,
+      resolvers.map(resolver => ('instance' in resolver ? resolver.instance : container.get(resolver.token))),
+    )
+}
+
 /**
  * Singletons (and registered values) are resolved once at bootstrap; request-scoped and transient
  * providers on every request.