@owlmeans/server-api 0.1.18-rc.8 → 0.1.18

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@owlmeans/server-api",
-  "version": "0.1.18-rc.8",
+  "version": "0.1.18",
   "license": "MIT",
   "type": "module",
   "scripts": {
     "build": "tsc -b",
     "dev": "sleep 264 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
-    "watch": "tsc -b -w --preserveWatchOutput --pretty"
+    "watch": "tsc -b -w --preserveWatchOutput --pretty",
+    "test": "bun test ./tests"
   },
   "main": "build/index.js",
   "module": "build/index.js",
@@ -29,30 +30,33 @@
   },
   "dependencies": {
     "@fastify/cors": "^11.3.0",
-    "@fastify/helmet": "^13.1.0",
-    "@fastify/middie": "^9.0.2",
-    "@fastify/multipart": "^9.0.1",
-    "@owlmeans/api": "^0.1.18-rc.6",
-    "@owlmeans/auth": "^0.1.18-rc.6",
-    "@owlmeans/auth-common": "^0.1.18-rc.6",
-    "@owlmeans/context": "^0.1.18-rc.6",
-    "@owlmeans/error": "^0.1.18-rc.6",
-    "@owlmeans/entrypoint": "^0.1.18-rc.6",
-    "@owlmeans/route": "^0.1.18-rc.6",
-    "@owlmeans/server-context": "^0.1.18-rc.6",
-    "@owlmeans/server-entrypoint": "^0.1.18-rc.6",
+    "@fastify/helmet": "^13.1.1",
+    "@fastify/middie": "^9.3.4",
+    "@fastify/multipart": "^10.1.2",
+    "@owlmeans/api": "^0.1.18",
+    "@owlmeans/auth": "^0.1.18",
+    "@owlmeans/auth-common": "^0.1.18",
+    "@owlmeans/context": "^0.1.18",
+    "@owlmeans/entrypoint": "^0.1.18",
+    "@owlmeans/error": "^0.1.18",
+    "@owlmeans/log": "^0.1.18",
+    "@owlmeans/route": "^0.1.18",
+    "@owlmeans/server-context": "^0.1.18",
+    "@owlmeans/server-entrypoint": "^0.1.18",
     "ajv-errors": "^3.0.0",
-    "fastify": "^5.0.0",
-    "fastify-raw-body": "^5.0.0",
-    "pino-pretty": "^13.0.0"
+    "fastify": "^5.12.5",
+    "fastify-raw-body": "^6.0.1",
+    "pino-pretty": "^13.2.0"
   },
   "peerDependencies": {
     "ajv": "*",
     "ajv-formats": "*"
   },
   "devDependencies": {
-    "@owlmeans/dep-config": "workspace:*",
-    "@types/node": "^26.1.0",
+    "@owlmeans/dep-config": "^0.1.18",
+    "@owlmeans/resource": "^0.1.18",
+    "@types/bun": "^1.4.2",
+    "@types/node": "^26.6.4",
     "nodemon": "^3.1.14",
     "typescript": "^7.0.2"
   },

package/src/consts.local.ts

@@ -0,0 +1 @@
+export const bodyLimit = 1024 * 1024 * 20

package/src/errors.ts

@@ -29,7 +29,25 @@ export class NoFileError extends ApiError {
   }
 }
 
+/**
+ * `handlers().body/params/request` was handed something it cannot serve — not a plain callback,
+ * and not a `BoundEntrypointHandler` bound to the SAME protocol it is being wrapped for. Thrown
+ * from inside the bound handler's own request path, so the module still loads and every OTHER
+ * route on it still answers; only the misconfigured one reports why, as a 500 rather than the
+ * opaque `TypeError: handler is not a function` a double wrap used to fail with. See
+ * `handlers()` in `protocol.ts` for what does and does not reach here.
+ */
+export class HandlerMisconfiguredError extends ApiError {
+  public static override typeName = 'HandlerMisconfiguredError'
+
+  constructor(message: string = 'error') {
+    super(`handler:misconfigured:${message}`)
+    this.type = HandlerMisconfiguredError.typeName
+  }
+}
+
 ResilientError.registerErrorClass(AuthFailedError)
 ResilientError.registerErrorClass(AccessError)
 ResilientError.registerErrorClass(NoFileError)
+ResilientError.registerErrorClass(HandlerMisconfiguredError)
 

package/src/helper.ts

@@ -1,15 +1,21 @@
 
-import type { BasicConfig, BasicContext } from '@owlmeans/context'
-import { assertContext } from '@owlmeans/context'
-import { EntrypointOutcome } from '@owlmeans/entrypoint'
-import type { AbstractRequest, AbstractResponse } from '@owlmeans/entrypoint'
+import { type BasicConfig, type BasicContext, assertContext } from '@owlmeans/context'
+import { EntrypointOutcome, type AbstractRequest, type AbstractResponse } from '@owlmeans/entrypoint'
 import type { RefedEntrypointHandler } from '@owlmeans/server-entrypoint'
-import type { Config, Context } from './types.js'
+import type { Config, Context, UploadedFile } from './types.js'
 import type { FastifyRequest } from 'fastify'
-import type { MultipartFile } from '@fastify/multipart'
 
+/**
+ * The context a handler runs against.
+ *
+ * The HTTP boundary hangs the request-scoped context on the raw Fastify request, so a handler
+ * reached that way gets it from there. A request that did not come from Fastify has no `original`
+ * at all — a queued call is rebuilt from an envelope, and a socket frame carries its own — so this
+ * has to fall back rather than dereference: these handlers are the same functions on every
+ * transport, and only the way they were reached differs.
+ */
 const _castContextFromOriginal = <C extends BasicConfig, T extends BasicContext<C> = BasicContext<C>>(req: AbstractRequest, def: T): T => {
-  return req.original._ctx ?? def
+  return req.original?._ctx ?? def
 }
 
 export const handleBody: <T>(
@@ -86,4 +92,3 @@ export const extractUploadedFile = async <T extends {} = {}>(req: AbstractReques
   return request.file()
 }
 
-export interface UploadedFile extends MultipartFile { }

package/src/hold.ts

@@ -0,0 +1,66 @@
+import Fastify from 'fastify'
+import { logger } from '@owlmeans/log'
+import type { ServerConfig } from '@owlmeans/server-context'
+import { CLOSED_HOST, OPENED_HOST, PORT } from './consts.js'
+import type { ApiPortHold, ApiPortHoldOptions } from './types.js'
+
+/**
+ * Own the app's port while the context initializes, and answer for the app until `listen()`
+ * takes over.
+ *
+ * The API server itself cannot do this: it builds its route table from the entrypoints the
+ * context knows about, so it can only bind AFTER `init()` resolves — and Fastify refuses new
+ * routes once it is listening. Without a hold, the whole boot window, and every way a boot can
+ * fail, leaves nothing on the port; the edge then answers a bare upstream connect error that
+ * names neither the app nor the reason, which is indistinguishable from a crashed pod or an app
+ * that was never installed.
+ *
+ * So the boot sequence an app wants is:
+ *
+ *     const hold = await holdApiPort(cfg, { okPath, payload })   // bind FIRST
+ *     try { ...initialize... } catch { record the failure; return }  // hold keeps answering
+ *     await hold.release()
+ *     await context.getApiServer().listen()
+ *
+ * Everything that is not the health path answers **503, not 404**: the routes the app really
+ * serves do not exist yet, and "no such route" would be a lie that outlives the boot.
+ *
+ * The port and host are resolved exactly as `listen()` resolves them — from the service's own
+ * declaration in `cfg.services[cfg.service]` — so the hold and the server can never disagree
+ * about which socket they are trading.
+ *
+ * A bind failure here (EADDRINUSE above all) throws to the caller and must be treated as fatal:
+ * a process that continues past it ends the boot with nothing listening and nothing holding the
+ * event loop, i.e. a clean exit 0 while a predecessor keeps serving stale code. Name the error
+ * and exit non-zero — that is what makes a supervisor reclaim the port instead of respawning
+ * into it.
+ */
+export const holdApiPort = async (
+  cfg: ServerConfig, opts: ApiPortHoldOptions = {}
+): Promise<ApiPortHold> => {
+  const config = cfg.services[cfg.service]
+  const port = config?.internalPort ?? config?.port ?? PORT
+  const host = config?.opened === true ? OPENED_HOST : CLOSED_HOST
+
+  const payload = opts.payload ?? (() => ({ status: 'OK' }))
+
+  // Quiet and disposable: no logger, no plugins, and connections are force-closed on release so
+  // the handover to the real server is bounded rather than waiting out a keep-alive.
+  const server = Fastify({ logger: false, forceCloseConnections: true })
+
+  if (opts.okPath != null) {
+    server.all(opts.okPath, async (_request, reply) => {
+      return await reply.code(200).send(payload())
+    })
+  }
+  server.setNotFoundHandler(async (_request, reply) => {
+    return await reply.code(503).send(payload())
+  })
+
+  await server.listen({ port, host })
+  logger('server').info(`api-server: holding ${host}:${port} for the boot${opts.okPath != null ? ` (${opts.okPath})` : ''}`, undefined, { event: 'server.hold' })
+
+  return {
+    release: async () => { await server.close() },
+  }
+}

package/src/index.ts

@@ -4,3 +4,5 @@ export * from './server.js'
 export * from './consts.js'
 export * from './errors.js'
 export * from './helper.js'
+export * from './hold.js'
+export * from './protocol.js'

package/src/protocol.ts

@@ -0,0 +1,149 @@
+import { assertContext, type BasicConfig, type BasicContext } from '@owlmeans/context'
+import { EntrypointOutcome, type BodyOf, type EntrypointProtocolDeclaration, type HandlerRequest, type OpenRequest, type ParamsOf, type RequestOf, type ResponseOf, type AbstractRequest } from '@owlmeans/entrypoint'
+import type { BoundEntrypointHandler } from '@owlmeans/server-entrypoint'
+import { HandlerMisconfiguredError } from './errors.js'
+import { logger } from '@owlmeans/log'
+import type { AnyBoundHandler, BodyProtocol, ContextCarrier, HandlerResponse, MaybePromise, ParamsProtocol } from './types.local.js'
+
+
+const contextFor = <Context extends BasicContext<BasicConfig>>(
+  request: AbstractRequest,
+  fallback: Context,
+): Context => {
+  const original = request.original
+  if (original != null && typeof original === 'object' && '_ctx' in original) {
+    return (original as ContextCarrier<Context>)._ctx ?? fallback
+  }
+
+  return fallback
+}
+
+const bind = <Protocol extends EntrypointProtocolDeclaration, Context extends BasicContext<BasicConfig>>(
+  protocol: Protocol,
+  execute: (request: HandlerRequest<RequestOf<Protocol>>, context: Context) => MaybePromise<HandlerResponse<ResponseOf<Protocol>>>,
+): BoundEntrypointHandler<Protocol> => ({
+  protocol,
+  bind: ref => async (request, response) => {
+    const fallback = assertContext<BasicConfig, Context>(ref.ref?.ctx, protocol.alias)
+
+    try {
+      const typedRequest = (request as HandlerRequest<OpenRequest>) as HandlerRequest<RequestOf<Protocol>>
+      const value = await execute(
+        typedRequest,
+        contextFor(request, fallback),
+      )
+      response.resolve(value as ResponseOf<Protocol>, EntrypointOutcome.Ok)
+    } catch (error) {
+      response.reject(error as Error)
+    }
+
+    return response.value
+  },
+})
+
+/**
+ * `value` is shaped like a `BoundEntrypointHandler` — never a plain function, which also carries
+ * its own `.bind` and would otherwise pass a `typeof value.bind === 'function'` check alone.
+ */
+const isBoundHandler = (value: unknown): value is AnyBoundHandler =>
+  typeof value === 'object' && value != null
+  && typeof (value as { bind?: unknown }).bind === 'function'
+  && (value as { protocol?: unknown }).protocol != null
+
+const warnedAliases = new Set<string>()
+
+/**
+ * What `body`/`params`/`request` do with something that is not the plain callback they declare —
+ * the shape a handler module wraps its own export in when it is bound TWICE. `null` means the
+ * second argument really is a callback and the caller should wrap it as usual.
+ *
+ * A handler bound to THIS protocol is returned unchanged, with a one-time warning: the module
+ * already produced a working `BoundEntrypointHandler`, and re-wrapping it here would only wrap it
+ * again — returning it as-is is what makes `bind(protocol, api.body(protocol, alreadyBound))`
+ * behave exactly like `bind(protocol, alreadyBound)`, which is what a wrap-once file looks like at
+ * this call site. Anything else — a handler bound to a DIFFERENT protocol, or a value that is
+ * neither a function nor a bound handler at all — answers every request on this route with
+ * {@link HandlerMisconfiguredError} instead of throwing `TypeError: handler is not a function`
+ * out of the request pipeline's own `try`, where the type name and the alias it happened on are
+ * both lost.
+ */
+const toleratedHandler = <Protocol extends EntrypointProtocolDeclaration>(
+  protocol: Protocol, handler: unknown
+): BoundEntrypointHandler<Protocol> | null => {
+  if (typeof handler === 'function') return null
+
+  if (isBoundHandler(handler)) {
+    if (handler.protocol.alias === protocol.alias) {
+      if (!warnedAliases.has(protocol.alias)) {
+        warnedAliases.add(protocol.alias)
+        logger('server-api').warn(
+          `${protocol.alias}: handler is already bound — pass it to bind() directly; `
+          + 'wrapping it again here is a type error (TS2345 "BoundEntrypointHandler<…> is not '
+          + 'assignable"), tolerated at runtime for a project generated before the wrap-once rule.'
+        )
+      }
+
+      return handler as unknown as BoundEntrypointHandler<Protocol>
+    }
+
+    return bind<Protocol, BasicContext<BasicConfig>>(protocol, () => {
+      throw new HandlerMisconfiguredError(
+        `${protocol.alias}: handler is bound to a different protocol ('${handler.protocol.alias}')`
+      )
+    })
+  }
+
+  return bind<Protocol, BasicContext<BasicConfig>>(protocol, () => {
+    throw new HandlerMisconfiguredError(`${protocol.alias}: handler is not a function`)
+  })
+}
+
+/**
+ * Make server handlers that infer request sections and response values from their protocol.
+ * The protocol is passed once; application callbacks never name request or reply generics.
+ */
+export const handlers = <Context extends BasicContext<BasicConfig>>() => ({
+  body: <Protocol extends EntrypointProtocolDeclaration>(
+    protocol: Protocol,
+    handler: Protocol extends BodyProtocol<Protocol> ? (
+        payload: BodyOf<Protocol>,
+        context: Context,
+        request: HandlerRequest<RequestOf<Protocol>>,
+      ) => MaybePromise<HandlerResponse<ResponseOf<Protocol>>>
+      : never,
+  ): BoundEntrypointHandler<Protocol> => toleratedHandler(protocol, handler) ?? bind<Protocol, Context>(protocol, (request, context) =>
+    (handler as (
+      payload: BodyOf<Protocol>, context: Context, request: HandlerRequest<RequestOf<Protocol>>,
+    ) => MaybePromise<HandlerResponse<ResponseOf<Protocol>>>)(request.body as BodyOf<Protocol>, context, request)),
+
+  params: <Protocol extends EntrypointProtocolDeclaration>(
+    protocol: Protocol,
+    handler: Protocol extends ParamsProtocol<Protocol> ? (
+        payload: ParamsOf<Protocol>,
+        context: Context,
+        request: HandlerRequest<RequestOf<Protocol>>,
+      ) => MaybePromise<HandlerResponse<ResponseOf<Protocol>>>
+      : never,
+  ): BoundEntrypointHandler<Protocol> => toleratedHandler(protocol, handler) ?? bind<Protocol, Context>(protocol, (request, context) =>
+    (handler as (
+      payload: ParamsOf<Protocol>, context: Context, request: HandlerRequest<RequestOf<Protocol>>,
+    ) => MaybePromise<HandlerResponse<ResponseOf<Protocol>>>)(request.params as ParamsOf<Protocol>, context, request)),
+
+  request: <Protocol extends EntrypointProtocolDeclaration>(
+    protocol: Protocol,
+    handler: (
+      request: HandlerRequest<RequestOf<Protocol>>,
+      context: Context,
+    ) => MaybePromise<HandlerResponse<ResponseOf<Protocol>>>,
+  ): BoundEntrypointHandler<Protocol> => toleratedHandler(protocol, handler) ?? bind<Protocol, Context>(protocol, handler),
+})
+
+/** Access a Fastify-specific upload through an explicit boundary helper, never `request.original`. */
+export const uploadedFile = async (
+  request: HandlerRequest<{ body: object }>,
+): Promise<import('@fastify/multipart').MultipartFile | undefined> => {
+  const original = (request as AbstractRequest).original
+  if (original == null || typeof original !== 'object' || !('file' in original)) return undefined
+
+  return (original as import('fastify').FastifyRequest).file()
+}

package/src/server.ts

@@ -1,13 +1,16 @@
-import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
+import type { ServerContext } from '@owlmeans/server-context'
 import type { ApiServer, ApiServerAppend } from './types.js'
-import { Layer, assertContext, createService } from '@owlmeans/context'
-import { canServeModule, executeResponse, provideRequest } from './utils/index.js'
+import { assertContext, createService } from '@owlmeans/context'
+import { canServeModule, payloadHelper, createServerHandler, fixFormatDates } from './utils/index.js'
 import { DEFAULT_ALIAS, CLOSED_HOST, PORT, OPENED_HOST } from './consts.js'
 import type { ServerEntrypoint } from '@owlmeans/server-entrypoint'
 import { RouteMethod } from '@owlmeans/route'
-import { createServerHandler, fixFormatDates } from './utils/index.js'
 import { provideResponse } from '@owlmeans/entrypoint'
 import { TOKEN_UPDATE } from '@owlmeans/auth-common'
+import { INCIDENT_ID_HEADER } from './utils/consts.js'
+import { DENIAL_KIND_HEADER } from '@owlmeans/api'
+import { logger } from '@owlmeans/log'
+import { fastifyLogUtils } from './utils/log.js'
 
 import Fastify from 'fastify'
 import type { FastifyRequest } from 'fastify'
@@ -20,6 +23,8 @@ import Multipart from '@fastify/multipart'
 import formatsPlugin from 'ajv-formats'
 import Ajv from 'ajv'
 import ajvErrors from "ajv-errors"
+import { bodyLimit } from './consts.local.js'
+import type { Config, Context } from './types.local.js'
 
 
 const ajv = new Ajv({
@@ -32,32 +37,29 @@ const ajv = new Ajv({
 formatsPlugin(ajv)
 ajvErrors(ajv, { singleError: true })
 
-type Config = ServerConfig
-type Context = ServerContext<Config>
 
-const bodyLimit = 1024 * 1024 * 20
+const http = logger('http')
+
+/**
+ * Fastify logging through `@owlmeans/log`, never with what a caller sent. The adapter writes every
+ * record's data through `safeData` (no body, raw body, multipart bytes, headers, cookies or query);
+ * the log controller drops Fastify's per-request pair — a request is a debug record written once
+ * from `onResponse` (below) — and logs a request Fastify itself refuses (a schema-invalid body, an
+ * unparsable payload, a size limit) like `handleError` logs a failed handler: method, path, status,
+ * error code and message.
+ */
+const createFastify = () => Fastify({
+  loggerInstance: fastifyLogUtils.logger(http),
+  logController: fastifyLogUtils.controller(),
+  bodyLimit,
+})
 
 export const createApiServer = (alias: string): ApiServer => {
   const location = `service:${alias}`
   const _assertContext = (context: Context | undefined): Context => assertContext<Config, Context>(context, location)
 
   const service = createService<ApiServer>(alias, {
-    server: Fastify({
-      logger: true,
-      bodyLimit,
-      /*{
-       transport: {
-         target: 'pino-pretty',
-         options: {
-           singleLine: true,
-           translateTime: 'HH:MM:ss Z',
-           ignore: 'pid,hostname',
-         },
-       },
-     }*/
-    }),
-
-    layers: [Layer.System],
+    server: createFastify(),
 
     listen: async () => {
       const context = _assertContext(service.ctx as Context)
@@ -67,7 +69,7 @@ export const createApiServer = (alias: string): ApiServer => {
       const port = config?.internalPort ?? config?.port ?? PORT
       const host = config.opened === true ? OPENED_HOST : CLOSED_HOST
       await service.server.listen({ port, host })
-      console.info(`${location}: server listening on ${host}${port != null ? `:${port}` : ''}`)
+      logger('server').info(`${location}: server listening on ${host}${port != null ? `:${port}` : ''}`, undefined, { event: 'server.listening' })
 
       process.on('SIGTERM', () => {
         service.server.close().then(() => {
@@ -78,7 +80,7 @@ export const createApiServer = (alias: string): ApiServer => {
   }, service => async () => {
     if (service.server.server.listening) {
       await service.server.close()
-      service.server = Fastify({ logger: true, bodyLimit })
+      service.server = createFastify()
     }
 
     const context = _assertContext(service.ctx as Context)
@@ -86,6 +88,15 @@ export const createApiServer = (alias: string): ApiServer => {
     const server = service.server
     // @TODO We should ensure some way that Resilient Error is thrown and go to the flow
     server.setValidatorCompiler(opts => ajv.compile(opts.schema))
+    server.addHook('onResponse', (request, reply, done) => {
+      if (http.enabled('debug')) {
+        // The path only: a query string can carry a token.
+        http.debug('request', {
+          ...fastifyLogUtils.requestOf(request), status: reply.statusCode, ms: Math.round(reply.elapsedTime),
+        })
+      }
+      done()
+    })
     // @TODO It's quite unsafe and should be properly configured
     await server.register(cors, {
       origin: '*',
@@ -101,7 +112,7 @@ export const createApiServer = (alias: string): ApiServer => {
         ...Object.values(RouteMethod).map(method => method.toUpperCase()),
         'HEAD', 'OPTIONS'
       ],
-      exposedHeaders: [TOKEN_UPDATE]
+      exposedHeaders: [TOKEN_UPDATE, INCIDENT_ID_HEADER, DENIAL_KIND_HEADER]
     })
 
     await server.register(Multipart, {
@@ -133,59 +144,53 @@ export const createApiServer = (alias: string): ApiServer => {
           return context
         }
 
-        // await module.route.resolve(context as any)
-        await module.resolve()
-        // Actually intermediate module can be created without handler by elevate function
-        if (module.route.match(request) && module.handle != null) {
+        // An intermediate route can be created without a handler by the binding layer.
+        if (module.route.match(request, module.mount()) && module.handle != null) {
           const response = provideResponse(reply)
-          const currentRequest = provideRequest(module.alias, request, true)
+          const currentRequest = payloadHelper.provideRequest(module.alias, request, true)
           currentRequest.original._ctx = context
           const result: Context = await module.handle(currentRequest, response)
           if (result != null) {
             context = result
           }
-          responded = executeResponse(response, reply, true) || responded
+          responded = payloadHelper.executeResponse(response, reply, true) || responded
         }
         return context
       }, Promise.resolve(context))
     })
 
-    await Promise.all(
-      context.entrypoints<ServerEntrypoint<FastifyRequest>>()
-        .filter(module => canServeModule(context, module) && !module.route.isIntermediate())
-        .map(async module => {
-          // await module.route.resolve(context as any)
-          await module.resolve()
-          const method = module.route.route.method ?? RouteMethod.GET
-          if (module.handle == null) {
-            return
-          }
-          server.route({
-            url: module.getPath(), method,
-            schema: {
-              consumes: [
-                'application/json',
-                'application/x-www-form-urlencoded',
-                'multipart/form-data',
-              ],
-              querystring: fixFormatDates(module.filter?.query ?? {}),
-              ...(
-                [
-                  RouteMethod.POST,
-                  RouteMethod.PATCH,
-                  RouteMethod.PUT
-                ].includes(method)
-                  ? { body: fixFormatDates(module.filter?.body ?? {}) }
-                  : {}
-              ),
-              params: fixFormatDates(module.filter?.params ?? {}),
-              response: module.filter?.response,
-              headers: fixFormatDates(module.filter?.headers ?? {})
-            },
-            handler: createServerHandler(module, location)
-          })
+    context.entrypoints<ServerEntrypoint<FastifyRequest>>()
+      .filter(module => canServeModule(context, module) && !module.route.isIntermediate())
+      .forEach(module => {
+        const method = module.route.route.method ?? RouteMethod.GET
+        if (module.handle == null) {
+          return
+        }
+        server.route({
+          url: module.mount(), method,
+          schema: {
+            consumes: [
+              'application/json',
+              'application/x-www-form-urlencoded',
+              'multipart/form-data',
+            ],
+            querystring: fixFormatDates(module.filter?.query ?? {}),
+            ...(
+              [
+                RouteMethod.POST,
+                RouteMethod.PATCH,
+                RouteMethod.PUT
+              ].includes(method)
+                ? { body: fixFormatDates(module.filter?.body ?? {}) }
+                : {}
+            ),
+            params: fixFormatDates(module.filter?.params ?? {}),
+            response: module.filter?.response,
+            headers: fixFormatDates(module.filter?.headers ?? {})
+          },
+          handler: createServerHandler(module, location)
         })
-    )
+      })
 
     service.initialized = true
   })
@@ -207,5 +212,3 @@ export const appendApiServer = <C extends Config, T extends ServerContext<C>>(
 
   return context
 }
-
-

package/src/types.local.ts

@@ -0,0 +1,44 @@
+import type { EntrypointProtocolDeclaration, OpenValue, RequestOf } from '@owlmeans/entrypoint'
+import type { BoundEntrypointHandler } from '@owlmeans/server-entrypoint'
+import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
+
+/**
+ * True for a response the declaration left with no compile-time contract: `typed<any>()` (an
+ * `[any] extends [X]` conditional does not produce `any`'s usual both-branches union once the
+ * checked type is wrapped in a tuple, so it resolves to a single branch like any other type) and
+ * a response inferred as bare `typed()` with nothing to infer from, which resolves to `undefined`
+ * with no shape to validate a handler's return against — the same signal a zero-argument
+ * `contract()` produces for a genuinely response-less route. Neither means "this handler must
+ * return void": it means the declaration did not constrain the response, so the handler is free to
+ * return whatever its route actually sends.
+ */
+export type IsUntypedResponse<T> = 0 extends (1 & T) ? true : [T] extends [undefined] ? true : false
+
+/**
+ * The type a bound handler is allowed to return for a given protocol response.
+ *
+ * A concretely typed or schema-backed `Response` is returned unchanged — the handler must produce
+ * exactly that shape. An untyped one (see `IsUntypedResponse` above) relaxes to `any`: the
+ * declaration made no promise about the response, so nothing here should force a handler bound to
+ * it into returning `void`.
+ */
+export type HandlerResponse<Response> = IsUntypedResponse<Response> extends true ? any : Response
+
+export type MaybePromise<Value> = Value | Promise<Value>
+
+export type BodyProtocol<Protocol extends EntrypointProtocolDeclaration> = RequestOf<Protocol> extends { body: OpenValue }
+  ? Protocol : never
+
+export type ParamsProtocol<Protocol extends EntrypointProtocolDeclaration> = RequestOf<Protocol> extends { params: object }
+  ? Protocol : never
+
+export type Config = ServerConfig
+
+export type Context = ServerContext<Config>
+
+export interface ContextCarrier<Context> {
+  _ctx?: Context
+}
+
+/** Structural, not `instanceof`: a `BoundEntrypointHandler` crosses no class boundary a runtime check could use. */
+export type AnyBoundHandler = BoundEntrypointHandler<EntrypointProtocolDeclaration>