@owlmeans/server-api 0.1.18-rc.4 → 0.1.18-rc.41

package/src/server.ts

@@ -1,6 +1,6 @@
 import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
 import type { ApiServer, ApiServerAppend } from './types.js'
-import { Layer, assertContext, createService } from '@owlmeans/context'
+import { assertContext, createService } from '@owlmeans/context'
 import { canServeModule, executeResponse, provideRequest } from './utils/index.js'
 import { DEFAULT_ALIAS, CLOSED_HOST, PORT, OPENED_HOST } from './consts.js'
 import type { ServerEntrypoint } from '@owlmeans/server-entrypoint'
@@ -8,6 +8,7 @@ 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/error.js'
 
 import Fastify from 'fastify'
 import type { FastifyRequest } from 'fastify'
@@ -57,8 +58,6 @@ export const createApiServer = (alias: string): ApiServer => {
      }*/
     }),
 
-    layers: [Layer.System],
-
     listen: async () => {
       const context = _assertContext(service.ctx as Context)
 
@@ -101,7 +100,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]
     })
 
     await server.register(Multipart, {
@@ -133,10 +132,8 @@ 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)
           currentRequest.original._ctx = context
@@ -150,42 +147,38 @@ export const createApiServer = (alias: string): ApiServer => {
       }, 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 +200,3 @@ export const appendApiServer = <C extends Config, T extends ServerContext<C>>(
 
   return context
 }
-
-

package/src/types.ts

@@ -1,5 +1,5 @@
 
-import type { InitializedService, Layer } from '@owlmeans/context'
+import type { InitializedService } from '@owlmeans/context'
 import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
 import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify'
 import '@fastify/middie/types/index.d.ts'
@@ -7,8 +7,6 @@ import '@fastify/middie/types/index.d.ts'
 export interface ApiServer extends InitializedService {
   server: FastifyInstance
 
-  layers: [Layer.System]
-
   listen: () => Promise<void>
 }
 
@@ -20,7 +18,20 @@ export interface ApiServerAppend {
   getApiServer: () => ApiServer
 }
 
-export interface Config extends ServerConfig { }
+export type HttpErrorExposure = 'production' | 'development'
+
+export interface HttpErrorsConfig {
+  /** Production is the safe default; development is the only mode that exposes stacks. */
+  exposure?: HttpErrorExposure
+}
+
+export interface HttpConfig {
+  errors?: HttpErrorsConfig
+}
+
+export interface Config extends ServerConfig {
+  http?: HttpConfig
+}
 
 export interface Context<C extends Config = Config> extends ServerContext<C>,
   ApiServerAppend { }

package/src/utils/error.ts

@@ -1,18 +1,206 @@
 import { FORBIDDEN_ERROR, SERVER_ERROR, UNAUTHORIZED_ERROR } from '@owlmeans/api'
 import type { FastifyReply } from 'fastify'
 import { AccessError, AuthFailedError } from '../errors.js'
-import { ResilientError } from '@owlmeans/error'
+import { AuthForbidden, AuthorizationError } from '@owlmeans/auth'
+import { isResilientError, ResilientError, SEPARATOR } from '@owlmeans/error'
+import { randomUUID } from 'node:crypto'
+import type { Config, HttpErrorExposure } from '../types.js'
 
-export const handleError = (error: Error, reply: FastifyReply) => {
-  let code: number = SERVER_ERROR
-  if (error instanceof AuthFailedError) {
-    code = UNAUTHORIZED_ERROR
-  } else if (error instanceof AccessError) {
-    code = FORBIDDEN_ERROR
+export const INCIDENT_ID_HEADER = 'X-Incident-ID'
+
+/**
+ * What an error class may declare about the HTTP status it is answered with.
+ *
+ * Structural on purpose: the classes that declare it live in packages that must not depend on an
+ * HTTP server (`@owlmeans/payment`, a product's contract package), so they write a plain
+ * `public static httpStatus = 409` and nothing imports this type.
+ */
+export interface HttpStatusDeclaration {
+  httpStatus?: unknown
+  /** Explicit opt-in for a declared 5xx response. Client-error declarations need no opt-in. */
+  allowServerErrorStatus?: unknown
+}
+
+const CLIENT_ERROR_FIRST = 400
+const CLIENT_ERROR_LAST = 499
+const SERVER_ERROR_FIRST = 500
+const SERVER_ERROR_LAST = 599
+
+/**
+ * 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)
+    }
+    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 declaredErrorStatus(error) ?? SERVER_ERROR
+}
+
+export interface SerializedHttpError {
+  status: number
+  body: string
+  incidentId: string
+}
+
+/** 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
+    }
+  }
+  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 }
+}
+
+/** 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 retryAfter = (error as { retryAfter?: unknown }).retryAfter
+  if (typeof retryAfter === 'number' && Number.isFinite(retryAfter) && retryAfter > 0) {
+    reply.header('Retry-After', String(Math.ceil(retryAfter)))
+  }
+}
+
+/**
+ * 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) {
-    reply.code(code).send(
-      ResilientError.marshal(ResilientError.ensure(error as Error)).message
-    )
+    const serialized = serializeError(error, exposure)
+    applyErrorHeaders(error, reply)
+    // Fastify/Pino's `err` serializer retains the original type, message and full stack. This is
+    // the one log entry that owns those details in production, keyed by the response incident ID.
+    reply.log.error({ err: error, incidentId: serialized.incidentId }, 'Request failed')
+    reply.header(INCIDENT_ID_HEADER, serialized.incidentId)
+      .code(serialized.status)
+      .send(serialized.body)
   }
 }

package/src/utils/guards.ts

@@ -1,4 +1,3 @@
-import { isContextWithoutIds, Layer } from '@owlmeans/context'
 import type { FastifyReply, FastifyRequest } from 'fastify'
 import type { ServerEntrypoint } from '@owlmeans/server-entrypoint'
 import type { GuardService } from '@owlmeans/entrypoint'
@@ -7,6 +6,7 @@ import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
 import { executeResponse, provideRequest } from './payload.js'
 import { AuthFailedError } from '../errors.js'
 import type { Auth } from '@owlmeans/auth'
+import { attachEntity } from '@owlmeans/auth-common'
 
 type Config = ServerConfig
 interface Context<C extends Config = Config> extends ServerContext<C> { }
@@ -50,22 +50,15 @@ export const authorize = async <C extends Config, T extends Context<C>>(
       (req as any)._auth = request.auth
     }
 
-    if (request.auth?.entityId != null) {
-      // @TODO Probably we need to downgrade context in this case
-      if (!isContextWithoutIds(context as any)) {
-        throw SyntaxError(`Context should be without ids during authorization ${context.cfg.layer}:${context.cfg.layerId}`)
-      }
-
-      if (isContextWithoutIds(context as any) && context.cfg.layer !== Layer.Service) {
-        context = await context.updateContext(undefined, Layer.Service)
-        await context.waitForInitialized()
-      }
-      context = await context.updateContext(request.auth.entityId, Layer.Entity)
-      await context.waitForInitialized()
-
-      // We elevate module to the context level if it was changed
-      module = context.entrypoint(module.alias)
-      await module.resolve()
+    // The token names the organization by slug; everything downstream — grants, records, minted
+    // 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)
+    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.
+      ;(req as any)._entity = entity
     }
   }
   // Update context in request object

package/src/utils/payload.ts

@@ -1,14 +1,18 @@
 import { EntrypointOutcome } from '@owlmeans/entrypoint'
 import type { AbstractResponse, AbstractRequest } from '@owlmeans/entrypoint'
 import type { Request, Response } from '../types.js'
-import { ACCEPTED, CREATED, OK, SERVER_ERROR } from '@owlmeans/api'
+import { ACCEPTED, CREATED, OK } from '@owlmeans/api'
 import type { AnySchemaObject } from 'ajv'
+import { handleError } from './error.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,
@@ -32,7 +36,7 @@ export const executeResponse = <T>(response: AbstractResponse<T>, reply: Respons
     if (throwOnError ?? false) {
       throw response.error
     }
-    reply.code(SERVER_ERROR).send(response.error.message)
+    handleError(response.error, reply)
     return true
   } else if (response.outcome != null) {
     switch (response.outcome) {

package/src/utils/server.ts

@@ -5,15 +5,16 @@ import type { FixerService, ServerEntrypoint } from '@owlmeans/server-entrypoint
 import type { CommonEntrypoint } from '@owlmeans/entrypoint'
 import type { GateService } from '@owlmeans/entrypoint'
 import { provideResponse } from '@owlmeans/entrypoint'
-import type { ServerContext, ServerConfig } from '@owlmeans/server-context'
+import type { ServerContext } from '@owlmeans/server-context'
 import { ResilientError } from '@owlmeans/error'
 import { OK } from '@owlmeans/api'
-import { handleError } from './error.js'
+import { errorExposure, handleError } from './error.js'
 import { executeResponse, provideRequest } from './payload.js'
 import { authorize } from './guards.js'
 import { RouteProtocols } from '@owlmeans/route'
+import type { Config as ApiConfig } from '../types.js'
 
-type Config = ServerConfig
+type Config = ApiConfig
 type Context = ServerContext<Config>
 
 export const canServeModule = (context: Context, module: CommonEntrypoint): module is ServerEntrypoint<unknown> => {
@@ -23,7 +24,9 @@ export const canServeModule = (context: Context, module: CommonEntrypoint): modu
   if (module.route.route.service != null && module.route.route.service !== context.cfg.service) {
     return false
   }
-  if (module.route.route.protocol === RouteProtocols.SOCKET) {
+  // HTTP serves only its own protocol. Custom transports are handled by their owning packages.
+  if (module.route.route.protocol != null
+    && module.route.route.protocol !== RouteProtocols.WEB) {
     return false
   }
 
@@ -63,14 +66,11 @@ export const createServerHandler = (module: ServerEntrypoint<FastifyRequest>, lo
         reply.code(OK).send(response.value)
       }
     } catch (error) {
-      console.error(`Error in ${module.alias} (${location})`)
-      console.error(JSON.stringify(error, null, 2))
-      console.error(error)
       if (module.fixer != null) {
         const fixer: FixerService = context.service(module.fixer)
         fixer.handle(reply, ResilientError.ensure(error as Error))
         return
       }
-      handleError(error as Error, reply)
+      handleError(error as Error, reply, errorExposure(context.cfg))
     }
   }