@owlmeans/server-api 0.1.18-rc.50 → 0.1.18-rc.52

package/src/utils/error.ts

@@ -11,210 +11,180 @@ import type { Config, HttpErrorExposure } from '../types.js'
 import { CLIENT_ERROR_FIRST, CLIENT_ERROR_LAST, SERVER_ERROR_FIRST, SERVER_ERROR_LAST } from './consts.local.js'
 import { INCIDENT_ID_HEADER } from './consts.js'
 import type { HttpStatusDeclaration, SerializedHttpError } from './types.js'
+import type { HttpErrorHelper } from './error/types.js'
 
+export const createHttpErrorHelper = (): HttpErrorHelper => {
+  const declaredErrorStatus = (error: unknown): number | null => {
+    if (error == null || typeof error !== 'object') {
+      return null
+    }
+    const declaration = error.constructor as HttpStatusDeclaration | undefined
+    const status = declaration?.httpStatus
+    if (typeof status !== 'number' || !Number.isInteger(status)) {
+      return null
+    }
+    if (status >= CLIENT_ERROR_FIRST && status <= CLIENT_ERROR_LAST) return status
+    if (status >= SERVER_ERROR_FIRST && status <= SERVER_ERROR_LAST
+      && declaration?.allowServerErrorStatus === true) return status
 
-/**
- * The HTTP status an error's class declares, or `null` when it declares none that may be honoured.
- *
- * Read through the constructor chain — a static property is inherited, so a subclass answers what
- * its nearest declaring ancestor says, and redeclares to change it. An integer 4xx is honoured
- * directly. A 5xx is honoured only with `allowServerErrorStatus = true`, so a domain class must
- * explicitly opt in to exposing a precise availability response. The read is structural, so a
- * class from a duplicate module copy declares exactly what the imported one does.
- */
-export const declaredErrorStatus = (error: unknown): number | null => {
-  if (error == null || typeof error !== 'object') {
     return null
   }
-  const declaration = error.constructor as HttpStatusDeclaration | undefined
-  const status = declaration?.httpStatus
-  if (typeof status !== 'number' || !Number.isInteger(status)) {
-    return null
-  }
-  if (status >= CLIENT_ERROR_FIRST && status <= CLIENT_ERROR_LAST) return status
-  if (status >= SERVER_ERROR_FIRST && status <= SERVER_ERROR_LAST
-    && declaration?.allowServerErrorStatus === true) return status
-
-  return null
-}
 
-/**
- * The registered type names an error carries: its own `type`, and the static `typeName` of every
- * class on its constructor chain.
- *
- * This is how a class is recognised when `instanceof` cannot see it. A process that loads a package
- * twice — `bun --preserve-symlinks` over a linked workspace resolves one package through several
- * `node_modules` paths — holds several copies of every error class, and an error built by one copy
- * is not an instance of another. The registered names are the same in every copy. A subclass's
- * `typeName` does not reliably embed its parent's (`EntitlementRefusal` extends `AuthForbidden`), so
- * a family is recognised by walking the chain and matching names exactly, never by a substring.
- */
-const typeNamesOf = (error: object): Set<string> => {
-  const names = new Set<string>()
-  const type = (error as { type?: unknown }).type
-  if (typeof type === 'string') {
-    names.add(type)
-  }
-  let ctor: unknown = error.constructor
-  while (typeof ctor === 'function') {
-    const name = (ctor as { typeName?: unknown }).typeName
-    if (typeof name === 'string') {
-      names.add(name)
+  /**
+   * The registered type names an error carries: its own `type`, and the static `typeName` of every
+   * class on its constructor chain.
+   *
+   * This is how a class is recognised when `instanceof` cannot see it. A process that loads a package
+   * twice — `bun --preserve-symlinks` over a linked workspace resolves one package through several
+   * `node_modules` paths — holds several copies of every error class, and an error built by one copy
+   * is not an instance of another. The registered names are the same in every copy. A subclass's
+   * `typeName` does not reliably embed its parent's (`EntitlementRefusal` extends `AuthForbidden`), so
+   * a family is recognised by walking the chain and matching names exactly, never by a substring.
+   */
+  const typeNamesOf = (error: object): Set<string> => {
+    const names = new Set<string>()
+    const type = (error as { type?: unknown }).type
+    if (typeof type === 'string') {
+      names.add(type)
+    }
+    let ctor: unknown = error.constructor
+    while (typeof ctor === 'function') {
+      const name = (ctor as { typeName?: unknown }).typeName
+      if (typeof name === 'string') {
+        names.add(name)
+      }
+      ctor = Object.getPrototypeOf(ctor)
     }
-    ctor = Object.getPrototypeOf(ctor)
-  }
-
-  return names
-}
 
-const isOfFamily = (names: Set<string>, family: string[]): boolean =>
-  family.some(typeName => names.has(typeName))
-
-/**
- * The HTTP status an error is answered with, read off the error exactly as given.
- *
- * Two families reach here and both must be recognised. `AuthFailedError` / `AccessError` are this
- * package's own, raised by the request pipeline itself. `AuthorizationError` / `AuthForbidden`
- * come from `@owlmeans/auth` and are what the guards and gates actually throw — an unrecognised
- * one answers 500, which reports a refused request as a crashed server: the client cannot tell
- * "sign in again" from "the service is broken", and a consumer watching statuses concludes the
- * application fell over. A family member is recognised by class OR by registered type name
- * ({@link typeNamesOf}), so a class from a duplicate module copy answers the same status.
- *
- * **Order matters.** `AuthForbidden extends AuthorizationError`, so the 403 branch has to be
- * tested first or every refusal of a permission is reported as a failure to authenticate. Both
- * auth branches come before a class's own declaration, so an auth refusal can never be restated
- * as something else. Everything that is neither an auth error nor a class declaring an allowed
- * {@link declaredErrorStatus} answers 500.
- */
-export const errorStatus = (error: unknown): number => {
-  if (error == null || typeof error !== 'object') {
-    return SERVER_ERROR
-  }
-  const names = typeNamesOf(error)
-  if (error instanceof AuthForbidden || error instanceof AccessError
-    || isOfFamily(names, [AuthForbidden.typeName, AccessError.typeName])) {
-    // An established identity that lacks the permission. Re-authenticating changes nothing.
-    return FORBIDDEN_ERROR
-  }
-  if (error instanceof AuthorizationError || error instanceof AuthFailedError
-    || isOfFamily(names, [AuthorizationError.typeName, AuthFailedError.typeName])) {
-    // No usable credential — absent, expired, revoked, or naming a session this server no longer
-    // holds. The caller is told to sign in, not that signing in would not help.
-    return UNAUTHORIZED_ERROR
+    return names
   }
 
-  return declaredErrorStatus(error) ?? SERVER_ERROR
-}
+  const isOfFamily = (names: Set<string>, family: string[]): boolean =>
+    family.some(typeName => names.has(typeName))
 
-/** Invalid or absent configuration always resolves to the production-safe policy. */
-export const errorExposure = (config?: Pick<Config, 'http'>): HttpErrorExposure =>
-  config?.http?.errors?.exposure === 'development' ? 'development' : 'production'
-
-/**
- * Preserve a typed/marshalled error when possible without asking `ensure` to convert a plain
- * error. In particular, `ensure` deliberately rethrows SyntaxError; an HTTP boundary still has
- * to serialize it safely and let the incident log retain the original object.
- */
-const normalizeForWire = (error: Error): Error => {
-  if (error instanceof SyntaxError || isResilientError(error)) {
-    return error
-  }
-  if (error.message.includes(SEPARATOR)) {
-    const ensured = ResilientError.ensure(error)
-    // The catch-all converter's legacy constructor shape shifts an ordinary error's fields.
-    // Only keep `ensure`'s result when a registered wire prefix actually rebuilt something.
-    if (ensured.type !== error.message || ensured.message !== error.stack) {
-      return ensured
+  const errorStatus = (error: unknown): number => {
+    if (error == null || typeof error !== 'object') {
+      return SERVER_ERROR
+    }
+    const names = typeNamesOf(error)
+    if (error instanceof AuthForbidden || error instanceof AccessError
+      || isOfFamily(names, [AuthForbidden.typeName, AccessError.typeName])) {
+      // An established identity that lacks the permission. Re-authenticating changes nothing.
+      return FORBIDDEN_ERROR
+    }
+    if (error instanceof AuthorizationError || error instanceof AuthFailedError
+      || isOfFamily(names, [AuthorizationError.typeName, AuthFailedError.typeName])) {
+      // No usable credential — absent, expired, revoked, or naming a session this server no longer
+      // holds. The caller is told to sign in, not that signing in would not help.
+      return UNAUTHORIZED_ERROR
     }
-  }
-  return error
-}
 
-/** One central wire shape for every server error. */
-export const serializeError = (
-  error: Error, exposure: HttpErrorExposure = 'production'
-): SerializedHttpError => {
-  const normalized = normalizeForWire(error)
-  const thrown = errorStatus(error)
-  const status = thrown !== SERVER_ERROR ? thrown : errorStatus(normalized)
-  const incidentId = randomUUID()
-  // The server log owns every diagnostic. Production callers receive only its correlation key;
-  // development keeps the typed wire form so local clients can retain their usual error details.
-  Object.assign(error, { incidentId })
-  if (isResilientError(normalized)) normalized.incidentId = incidentId
-  const body = exposure === 'production'
-    ? incidentId
-    : ResilientError.marshal(normalized, { includeStack: true, incidentId }).message
-
-  return { status, body, incidentId }
-}
+    return declaredErrorStatus(error) ?? SERVER_ERROR
+  }
 
-/** Apply safe response metadata carried by an error without coupling its package to Fastify. */
-export const applyErrorHeaders = (error: unknown, reply: FastifyReply): void => {
-  if (error == null || typeof error !== 'object') {
-    return
+  const errorExposure = (config?: Pick<Config, 'http'>): HttpErrorExposure =>
+    config?.http?.errors?.exposure === 'development' ? 'development' : 'production'
+
+  /**
+   * Preserve a typed/marshalled error when possible without asking `ensure` to convert a plain
+   * error. In particular, `ensure` deliberately rethrows SyntaxError; an HTTP boundary still has
+   * to serialize it safely and let the incident log retain the original object.
+   */
+  const normalizeForWire = (error: Error): Error => {
+    if (error instanceof SyntaxError || isResilientError(error)) {
+      return error
+    }
+    if (error.message.includes(SEPARATOR)) {
+      const ensured = ResilientError.ensure(error)
+      // The catch-all converter's legacy constructor shape shifts an ordinary error's fields.
+      // Only keep `ensure`'s result when a registered wire prefix actually rebuilt something.
+      if (ensured.type !== error.message || ensured.message !== error.stack) {
+        return ensured
+      }
+    }
+    return error
   }
-  const retryAfter = (error as { retryAfter?: unknown }).retryAfter
-  if (typeof retryAfter === 'number' && Number.isFinite(retryAfter) && retryAfter > 0) {
-    reply.header('Retry-After', String(Math.ceil(retryAfter)))
+
+  const serializeError = (
+    error: Error, exposure: HttpErrorExposure = 'production'
+  ): SerializedHttpError => {
+    const normalized = normalizeForWire(error)
+    const thrown = errorStatus(error)
+    const status = thrown !== SERVER_ERROR ? thrown : errorStatus(normalized)
+    const incidentId = randomUUID()
+    // The server log owns every diagnostic. Production callers receive only its correlation key;
+    // development keeps the typed wire form so local clients can retain their usual error details.
+    Object.assign(error, { incidentId })
+    if (isResilientError(normalized)) normalized.incidentId = incidentId
+    const body = exposure === 'production'
+      ? incidentId
+      : ResilientError.marshal(normalized, { includeStack: true, incidentId }).message
+
+    return { status, body, incidentId }
   }
-  // Match exact registered types. EntitlementRefusal also extends AuthForbidden but is a plan
-  // decision, not a person's IAM permission denial.
-  const type = (error as { type?: unknown }).type
-  if (type === AuthForbidden.typeName || type === AccessError.typeName) {
-    reply.header(DENIAL_KIND_HEADER, ACCESS_DENIED_KIND)
+
+  const applyErrorHeaders = (error: unknown, reply: FastifyReply): void => {
+    if (error == null || typeof error !== 'object') {
+      return
+    }
+    const retryAfter = (error as { retryAfter?: unknown }).retryAfter
+    if (typeof retryAfter === 'number' && Number.isFinite(retryAfter) && retryAfter > 0) {
+      reply.header('Retry-After', String(Math.ceil(retryAfter)))
+    }
+    // Match exact registered types. EntitlementRefusal also extends AuthForbidden but is a plan
+    // decision, not a person's IAM permission denial.
+    const type = (error as { type?: unknown }).type
+    if (type === AuthForbidden.typeName || type === AccessError.typeName) {
+      reply.header(DENIAL_KIND_HEADER, ACCESS_DENIED_KIND)
+    }
   }
-}
 
-const http = logger('http')
-
-/**
- * The one log entry of a failed request, by what the failure means:
- *
- * | Status | Level | Why |
- * |---|---|---|
- * | 5xx | error | a fault — the one entry that owns type, message and stack, keyed by the incident id |
- * | 403 | warn, `access.forbidden` | an established identity was refused; worth an operator's eye |
- * | 401 | debug, `auth.refused` | an absent or expired credential is the ordinary shape of a sign-in |
- * | other 4xx | debug | the caller's mistake, not the server's |
- *
- * The method and path are logged; the query string is not — it can carry a token.
- */
-const logFailure = (error: Error, reply: FastifyReply, status: number, incidentId: string): void => {
-  const request = reply.request
-  const where = { method: request?.method, path: request?.url?.split('?')[0], status, incidentId }
-  if (status >= SERVER_ERROR) {
-    http.error('Request failed', { err: error, ...where })
-  } else if (status === FORBIDDEN_ERROR) {
-    http.warn('Access forbidden', { type: (error as { type?: unknown }).type, message: error.message, ...where },
-      { event: 'access.forbidden' })
-  } else if (status === UNAUTHORIZED_ERROR) {
-    http.debug('Authentication refused', { message: error.message, ...where }, { event: 'auth.refused' })
-  } else {
-    http.debug('Request refused', { message: error.message, ...where })
+  const http = logger('http')
+
+  /**
+   * The one log entry of a failed request, by what the failure means:
+   *
+   * | Status | Level | Why |
+   * |---|---|---|
+   * | 5xx | error | a fault — the one entry that owns type, message and stack, keyed by the incident id |
+   * | 403 | warn, `access.forbidden` | an established identity was refused; worth an operator's eye |
+   * | 401 | debug, `auth.refused` | an absent or expired credential is the ordinary shape of a sign-in |
+   * | other 4xx | debug | the caller's mistake, not the server's |
+   *
+   * The method and path are logged; the query string is not — it can carry a token.
+   */
+  const logFailure = (error: Error, reply: FastifyReply, status: number, incidentId: string): void => {
+    const request = reply.request
+    const where = { method: request?.method, path: request?.url?.split('?')[0], status, incidentId }
+    if (status >= SERVER_ERROR) {
+      http.error('Request failed', { err: error, ...where })
+    } else if (status === FORBIDDEN_ERROR) {
+      http.warn('Access forbidden', { type: (error as { type?: unknown }).type, message: error.message, ...where },
+        { event: 'access.forbidden' })
+    } else if (status === UNAUTHORIZED_ERROR) {
+      http.debug('Authentication refused', { message: error.message, ...where }, { event: 'auth.refused' })
+    } else {
+      http.debug('Request refused', { message: error.message, ...where })
+    }
   }
-}
 
-/**
- * Answer a thrown error: a status, and the marshalled `ResilientError` as the body.
- *
- * The status is resolved in two steps. The error AS THROWN comes first: it is the one object whose
- * class is certainly the class that was raised, while `ResilientError.ensure` rebuilds through the
- * registry of whichever `@owlmeans/error` copy this module loaded — under duplicate module copies
- * that turns a perfectly recognisable auth refusal into a plain `ResilientError` answering 500.
- * Only when the thrown error answers 500 is the ENSURED error asked, because the rebuild is what
- * gives a status to a marshalled error that crossed a hop as a plain `Error`.
- */
-export const handleError = (
-  error: Error, reply: FastifyReply, exposure: HttpErrorExposure = 'production'
-) => {
-  if (!reply.sent) {
-    const serialized = serializeError(error, exposure)
-    applyErrorHeaders(error, reply)
-    logFailure(error, reply, serialized.status, serialized.incidentId)
-    reply.header(INCIDENT_ID_HEADER, serialized.incidentId)
-      .code(serialized.status)
-      .send(serialized.body)
+  const handleError = (
+    error: Error, reply: FastifyReply, exposure: HttpErrorExposure = 'production'
+  ): void => {
+    if (!reply.sent) {
+      const serialized = serializeError(error, exposure)
+      applyErrorHeaders(error, reply)
+      logFailure(error, reply, serialized.status, serialized.incidentId)
+      reply.header(INCIDENT_ID_HEADER, serialized.incidentId)
+        .code(serialized.status)
+        .send(serialized.body)
+    }
   }
+
+  return { declaredErrorStatus, errorStatus, errorExposure, serializeError, applyErrorHeaders, handleError }
 }
+
+export const httpErrorHelper = createHttpErrorHelper()
+
+/** @deprecated compat:factory-refactor — use `httpErrorHelper.errorStatus(…)` */
+export const errorStatus = (error: unknown): number => httpErrorHelper.errorStatus(error)

package/src/utils/guards.ts

@@ -1,11 +1,11 @@
 import type { FastifyReply, FastifyRequest } from 'fastify'
 import type { ServerEntrypoint } from '@owlmeans/server-entrypoint'
 import { type GuardService, provideResponse } from '@owlmeans/entrypoint'
-import { executeResponse, provideRequest } from './payload.js'
+import { payloadHelper } from './payload.js'
 import { AuthFailedError } from '../errors.js'
 import type { Auth } from '@owlmeans/auth'
-import { attachEntity } from '@owlmeans/auth-common'
 import type { Config, Context } from './types.local.js'
+import { makeEntityScope } from '@owlmeans/auth-common'
 
 
 export const authorize = async <C extends Config, T extends Context<C>>(
@@ -15,7 +15,7 @@ export const authorize = async <C extends Config, T extends Context<C>>(
   const guards = module.getGuards()
   if (guards.length > 0) {
     const response = provideResponse(reply)
-    const request = provideRequest(module.alias, req)
+    const request = payloadHelper.provideRequest(module.alias, req)
 
     let guard: GuardService | undefined = undefined
     for (const alias of guards) {
@@ -23,7 +23,7 @@ export const authorize = async <C extends Config, T extends Context<C>>(
       if (await _guard.match(request, response)) {
         guard = _guard
       }
-      executeResponse(response, reply, true)
+      payloadHelper.executeResponse(response, reply, true)
       if (guard != null) {
         break
       }
@@ -37,7 +37,7 @@ export const authorize = async <C extends Config, T extends Context<C>>(
     if (!await guard.handle<boolean>(request, authResponse)) {
       throw new AuthFailedError(guard.alias)
     }
-    executeResponse(authResponse, reply, true)
+    payloadHelper.executeResponse(authResponse, reply, true)
     // Guard that returns true and does not provide an error is an optional guard
     // if (authResponse.value == null) {
     //   throw SyntaxError(`Guard that returns true and does not provide an error, should provide authorization`)
@@ -51,7 +51,7 @@ export const authorize = async <C extends Config, T extends Context<C>>(
     // infrastructure names — keys on the entity's stable id. Resolving here, once, is what keeps a
     // rename from being a sweep of every handler: the id arrives on the request, and a slug that
     // has since been retired still resolves to the entity that retired it.
-    const entity = await attachEntity(context, request)
+    const entity = await makeEntityScope(request).attachEntity(context)
     if (entity != null) {
       // Carried on the raw request the same way `_auth` is, so the request the handler is given
       // later — a different object, built after this runs — sees the same resolution.

package/src/utils/index.ts

@@ -2,8 +2,11 @@
 export * from './error.js'
 export * from './consts.js'
 export type * from './types.js'
+export type * from './error/types.js'
+export type * from './payload/types.js'
+export type * from './context/types.js'
 export * from './server.js'
 export * from './payload.js'
-export * from './server.js'
+export * from './schema.js'
 export * from './guards.js'
 export * from './context.js'

package/src/utils/payload/types.ts

@@ -0,0 +1,18 @@
+import type { AbstractRequest, AbstractResponse } from '@owlmeans/entrypoint'
+import type { Request, Response } from '../../types.js'
+
+/** Moves an exchange between Fastify and the entrypoint shapes: the request in, the response out. */
+export interface PayloadHelper {
+  /** The entrypoint request of a Fastify request; `provision` keeps the original on it. */
+  provideRequest: (alias: string, req: Request, provision?: boolean) => AbstractRequest
+  /**
+   * Emits the response onto the fastify reply if the handler produced an
+   * error or an outcome. Returns `true` when something was actually sent so
+   * callers don't rely on `reply.sent`, which in fastify v5 only flips once
+   * the raw socket finishes writing (asynchronously) and therefore reads
+   * `false` synchronously right after `reply.send()`.
+   *
+   * @throws {Error}
+   */
+  executeResponse: <T>(response: AbstractResponse<T>, reply: Response, throwOnError?: boolean) => boolean
+}

package/src/utils/payload.ts

@@ -2,75 +2,53 @@ import { EntrypointOutcome } from '@owlmeans/entrypoint'
 import type { AbstractResponse, AbstractRequest } from '@owlmeans/entrypoint'
 import type { Request, Response } from '../types.js'
 import { ACCEPTED, CREATED, OK } from '@owlmeans/api'
-import type { AnySchemaObject } from 'ajv'
-import { handleError } from './error.js'
+import { httpErrorHelper } from './error.js'
+import type { PayloadHelper } from './payload/types.js'
 
-export const provideRequest = (alias: string, req: Request, provision?: boolean): AbstractRequest => {
-  provision = provision ?? false
-  return {
-    alias,
-    auth: (req as any)._auth ?? undefined,
-    // Resolved once by `authorize` and carried by reference, exactly like `_auth`, so a handler
-    // reached through any path sees the same entity the guard admitted.
-    entity: (req as any)._entity ?? undefined,
-    params: req.params as Record<string, string | number | undefined | null>,
-    body: req.body as Record<string, any>,
-    headers: req.headers,
-    query: req.query as Record<string, string | number | undefined | null>,
-    path: req.url,
-    original: provision ? req : undefined
-  }
-}
-
-/**
- * Emits the response onto the fastify reply if the handler produced an
- * error or an outcome. Returns `true` when something was actually sent so
- * callers don't rely on `reply.sent`, which in fastify v5 only flips once
- * the raw socket finishes writing (asynchronously) and therefore reads
- * `false` synchronously right after `reply.send()`.
- *
- * @throws {Error}
- */
-export const executeResponse = <T>(response: AbstractResponse<T>, reply: Response, throwOnError?: boolean): boolean => {
-  if (response.error != null) {
-    if (throwOnError ?? false) {
-      throw response.error
+export const createPayloadHelper = (): PayloadHelper => {
+  const provideRequest = (alias: string, req: Request, provision?: boolean): AbstractRequest => {
+    provision = provision ?? false
+    return {
+      alias,
+      auth: (req as any)._auth ?? undefined,
+      // Resolved once by `authorize` and carried by reference, exactly like `_auth`, so a handler
+      // reached through any path sees the same entity the guard admitted.
+      entity: (req as any)._entity ?? undefined,
+      params: req.params as Record<string, string | number | undefined | null>,
+      body: req.body as Record<string, any>,
+      headers: req.headers,
+      query: req.query as Record<string, string | number | undefined | null>,
+      path: req.url,
+      original: provision ? req : undefined
     }
-    handleError(response.error, reply)
-    return true
-  } else if (response.outcome != null) {
-    switch (response.outcome) {
-      case EntrypointOutcome.Accepted:
-        reply.code(ACCEPTED).send(response.value)
-        break
-      case EntrypointOutcome.Created:
-        reply.code(CREATED).send(response.value)
-        break
-      case EntrypointOutcome.Ok:
-      default:
-        reply.code(OK).send(response.value)
-    }
-    return true
   }
 
-  return false
-}
-
-
-export const fixFormatDates = (schema: AnySchemaObject) => {
-  if (schema.type === 'object') {
-    if (schema.format === 'date-time') {
-      schema.type = 'string'
-      schema.format = 'date-time'
-      if (schema.required != null) {
-        delete schema.required
+  const executeResponse = <T>(response: AbstractResponse<T>, reply: Response, throwOnError?: boolean): boolean => {
+    if (response.error != null) {
+      if (throwOnError ?? false) {
+        throw response.error
+      }
+      httpErrorHelper.handleError(response.error, reply)
+      return true
+    } else if (response.outcome != null) {
+      switch (response.outcome) {
+        case EntrypointOutcome.Accepted:
+          reply.code(ACCEPTED).send(response.value)
+          break
+        case EntrypointOutcome.Created:
+          reply.code(CREATED).send(response.value)
+          break
+        case EntrypointOutcome.Ok:
+        default:
+          reply.code(OK).send(response.value)
       }
-    } else if (schema.properties != null) {
-      schema.properties = Object.fromEntries(
-        Object.entries(schema.properties).map(([key, value]) => [key, fixFormatDates(value as AnySchemaObject)])
-      )
+      return true
     }
+
+    return false
   }
 
-  return schema
+  return { provideRequest, executeResponse }
 }
+
+export const payloadHelper = createPayloadHelper()

package/src/utils/schema.ts

@@ -0,0 +1,23 @@
+import type { AnySchemaObject } from 'ajv'
+
+/**
+ * A request schema Fastify can serve: a `date-time` object becomes a `date-time` string (and loses
+ * its `required` list), recursively through object properties. Mutates and returns `schema`.
+ */
+export const fixFormatDates = (schema: AnySchemaObject): AnySchemaObject => {
+  if (schema.type === 'object') {
+    if (schema.format === 'date-time') {
+      schema.type = 'string'
+      schema.format = 'date-time'
+      if (schema.required != null) {
+        delete schema.required
+      }
+    } else if (schema.properties != null) {
+      schema.properties = Object.fromEntries(
+        Object.entries(schema.properties).map(([key, value]) => [key, fixFormatDates(value as AnySchemaObject)])
+      )
+    }
+  }
+
+  return schema
+}

package/src/utils/server.ts

@@ -5,8 +5,8 @@ import { type CommonEntrypoint, type GateService, provideResponse } from '@owlme
 import { ResilientError } from '@owlmeans/error'
 import { OK } from '@owlmeans/api'
 import { logger } from '@owlmeans/log'
-import { errorExposure, handleError } from './error.js'
-import { executeResponse, provideRequest } from './payload.js'
+import { httpErrorHelper } from './error.js'
+import { payloadHelper } from './payload.js'
 import { authorize } from './guards.js'
 import { RouteProtocols } from '@owlmeans/route'
 import type { ServerConfig2, ServerContext2 } from './types.local.js'
@@ -38,13 +38,13 @@ export const createServerHandler = (module: ServerEntrypoint<FastifyRequest>, lo
       module = authorized[1]
 
       const response = provideResponse(reply)
-      const request = provideRequest(module.alias, req, true)
+      const request = payloadHelper.provideRequest(module.alias, req, true)
 
       const gates = module.getGates()
       for (const [srv, params] of gates) {
         const gate: GateService = context.service(srv)
         await gate.assert(request, response, params)
-        executeResponse(response, reply, true)
+        payloadHelper.executeResponse(response, reply, true)
       }
 
       await module.handle(request, response)
@@ -55,7 +55,7 @@ export const createServerHandler = (module: ServerEntrypoint<FastifyRequest>, lo
       // synchronously right after `reply.send()`. Track the emitted state
       // explicitly instead, and only fall back to a default response when
       // neither `executeResponse` nor the handler itself (hijack) replied.
-      const responded = executeResponse(response, reply, true)
+      const responded = payloadHelper.executeResponse(response, reply, true)
       if (!responded && !reply.sent) {
         logger('http').warn(`SENDS DEFAULT RESPONSE: ${module.alias}`)
         reply.code(OK).send(response.value)
@@ -66,6 +66,6 @@ export const createServerHandler = (module: ServerEntrypoint<FastifyRequest>, lo
         fixer.handle(reply, ResilientError.ensure(error as Error))
         return
       }
-      handleError(error as Error, reply, errorExposure(context.cfg))
+      httpErrorHelper.handleError(error as Error, reply, httpErrorHelper.errorExposure(context.cfg))
     }
   }