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

package/src/utils/log.ts

@@ -0,0 +1,193 @@
+import { LogController } from 'fastify'
+import type { FastifyBaseLogger, FastifyReply, FastifyRequest } from 'fastify'
+import { FORBIDDEN_ERROR, SERVER_ERROR, UNAUTHORIZED_ERROR } from '@owlmeans/api'
+import { logger, type LogLevel, type Logger } from '@owlmeans/log'
+import type { Severity } from './types.local.js'
+import { QUERY_IN_TEXT, SAFE_DATA_DEPTH, UNSAFE_LOG_KEYS } from './log/consts.js'
+import type { FastifyLogUtils, RequestSummary } from './log/types.js'
+
+const pathOf = (url: string): string => url.split('?')[0]
+
+const withoutQueries = (text: string): string => text.replace(QUERY_IN_TEXT, '$1')
+
+/** The error itself, or — when its message names a URL with a query — a copy without the query. */
+const safeError = (error: Error): Error => {
+  const message = withoutQueries(error.message)
+  if (message === error.message) {
+    return error
+  }
+  const copy: Error = Object.assign(Object.create(Object.getPrototypeOf(error) as object) as Error, error)
+  copy.message = message
+  copy.stack = error.stack != null ? withoutQueries(error.stack) : undefined
+  return copy
+}
+
+const isPlain = (value: object): boolean => {
+  const proto = Object.getPrototypeOf(value)
+  return proto === Object.prototype || proto === null
+}
+
+const levelName = (log: Logger): string => {
+  const order: LogLevel[] = ['debug', 'info', 'warn', 'error']
+  return order.find(level => log.enabled(level)) ?? 'silent'
+}
+
+export const createFastifyLogUtils = (): FastifyLogUtils => {
+  const http = logger('http')
+
+  const requestOf = (request: unknown): RequestSummary => {
+    const { method, url } = (request ?? {}) as { method?: unknown, url?: unknown }
+    return {
+      ...(typeof method === 'string' ? { method } : {}),
+      ...(typeof url === 'string' ? { path: pathOf(url) } : {}),
+    }
+  }
+
+  /** A class instance as a record may carry it: a request or reply by summary, anything else by name. */
+  const instanceOf = (value: object): unknown => {
+    const shape = value as { method?: unknown, url?: unknown, statusCode?: unknown }
+    if (typeof shape.method === 'string' && typeof shape.url === 'string') {
+      return requestOf(value)
+    }
+    if (typeof shape.statusCode === 'number') {
+      return { statusCode: shape.statusCode }
+    }
+    const name = value.constructor?.name ?? 'object'
+    if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {
+      return `[${name} ${value.byteLength} bytes]`
+    }
+    return `[${name}]`
+  }
+
+  const safe = (value: unknown, depth: number, seen: WeakSet<object>): unknown => {
+    if (typeof value === 'string') {
+      return withoutQueries(value)
+    }
+    if (value instanceof Error) {
+      return safeError(value)
+    }
+    if (value == null || typeof value !== 'object' || value instanceof Date) {
+      return value
+    }
+    if (seen.has(value)) {
+      return '[circular]'
+    }
+    if (!Array.isArray(value) && !isPlain(value)) {
+      return instanceOf(value)
+    }
+    if (depth >= SAFE_DATA_DEPTH) {
+      return '[…]'
+    }
+    seen.add(value)
+    if (Array.isArray(value)) {
+      return value.map(item => safe(item, depth + 1, seen))
+    }
+    const out: Record<string, unknown> = {}
+    for (const [key, item] of Object.entries(value)) {
+      // A count or a flag under such a key (`limits.files: 5`) says nothing a caller sent.
+      if (UNSAFE_LOG_KEYS.has(key) && typeof item !== 'number' && typeof item !== 'boolean') {
+        continue
+      }
+      out[key] = key === 'url' && typeof item === 'string' ? pathOf(item) : safe(item, depth + 1, seen)
+    }
+    return out
+  }
+
+  const safeData = (data: unknown): unknown => safe(data, 0, new WeakSet())
+
+  const failure: FastifyLogUtils['failure'] = (error, request, status, incidentId) => {
+    const where = { ...requestOf(request), status, ...(incidentId != null ? { incidentId } : {}) }
+    const safe = safeError(error)
+    if (status >= SERVER_ERROR) {
+      http.error('Request failed', { err: safe, ...where })
+    } else if (status === FORBIDDEN_ERROR) {
+      http.warn('Access forbidden', { type: (error as { type?: unknown }).type, message: safe.message, ...where },
+        { event: 'access.forbidden' })
+    } else if (status === UNAUTHORIZED_ERROR) {
+      http.debug('Authentication refused', { message: safe.message, ...where }, { event: 'auth.refused' })
+    } else {
+      const code = (error as { code?: unknown }).code
+      http.debug('Request refused', { ...(typeof code === 'string' ? { code } : {}), message: safe.message, ...where })
+    }
+  }
+
+  /**
+   * Fastify announces its listening address at info; the server writes `server.listening` itself.
+   * Its request lines no longer reach the adapter at all — `controller()` owns them.
+   */
+  const levelOf = (level: Severity, message: unknown): Severity =>
+    level === 'info' && typeof message === 'string' && message.startsWith('Server listening at') ? 'debug' : level
+
+  const fastifyLogger = (log: Logger = http, bindings?: Record<string, unknown>): FastifyBaseLogger => {
+    const call = (requested: Severity) => (first: unknown, second?: unknown): void => {
+      const [object, message] = typeof first === 'string' || first instanceof Error
+        ? [undefined, first] : [first, second]
+      const level = levelOf(requested, message)
+      if (!log.enabled(level)) {
+        return
+      }
+      const data = bindings != null && Object.keys(bindings).length > 0
+        ? { ...bindings, ...(object != null && typeof object === 'object' ? object : {}) } : object
+      const text = message == null ? '' : message instanceof Error ? safeError(message) : withoutQueries(String(message))
+      log[level](text, safeData(data))
+    }
+
+    const adapter = {
+      get level(): string { return levelName(log) },
+      set level(_value: string) { /* the level belongs to the process, not to this server */ },
+      fatal: call('error'), error: call('error'), warn: call('warn'),
+      info: call('info'), debug: call('debug'), trace: call('debug'),
+      silent: () => undefined,
+      // Fastify's second argument (pino options: its own `req`/`res` serializers) is ignored —
+      // `safeData` is this adapter's serializer.
+      child: (extra: Record<string, unknown>) => fastifyLogger(log, { ...bindings, ...extra }),
+    }
+    return adapter as unknown as FastifyBaseLogger
+  }
+
+  /**
+   * Fastify accepts a `logController` only as an instance of its own class, so this one member is a
+   * subclass; its methods use no `this`.
+   */
+  const controller = (): LogController => {
+    class SafeLogController extends LogController {
+      override incomingRequest (): void { /* `onResponse` writes the one record of a request */ }
+
+      override requestCompleted (error: Error | null | undefined, request: FastifyRequest, reply: FastifyReply): void {
+        if (error != null) {
+          http.error('Response failed', { err: error, ...requestOf(request), status: reply.statusCode })
+        }
+      }
+
+      override defaultErrorLog (error: Error, request: FastifyRequest, reply: FastifyReply): void {
+        failure(error, request, reply.statusCode)
+      }
+
+      override streamError (error: Error, request: FastifyRequest, reply: FastifyReply): void {
+        const where = { ...requestOf(request), status: reply.statusCode }
+        if ((error as { code?: unknown }).code === 'ERR_STREAM_PREMATURE_CLOSE') {
+          http.debug('Response stream closed prematurely', where)
+        } else {
+          http.warn('Response stream failed after its headers were sent', { err: error, ...where })
+        }
+      }
+
+      override routeNotFound (request: FastifyRequest): void {
+        http.debug('Route not found', requestOf(request))
+      }
+
+      override writeHeadError (error: Error, request: FastifyRequest, reply: FastifyReply): void {
+        http.warn('Response headers not written', { err: error, ...requestOf(request), status: reply.statusCode })
+      }
+
+      override serializerError (error: Error, request: FastifyRequest, _reply: FastifyReply, metadata: { statusCode: number }): void {
+        http.error('Response serializer failed', { err: error, ...requestOf(request), status: metadata.statusCode })
+      }
+    }
+    return new SafeLogController()
+  }
+
+  return { logger: fastifyLogger, controller, safeData, requestOf, failure }
+}
+
+export const fastifyLogUtils = createFastifyLogUtils()

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

@@ -1,72 +1,54 @@
 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 type { AnySchemaObject } from 'ajv'
+import { ACCEPTED, CREATED, OK } from '@owlmeans/api'
+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,
-    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
     }
-    reply.code(SERVER_ERROR).send(response.error.message)
-    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

@@ -1,29 +1,27 @@
-import { AppType } from '@owlmeans/context'
+import { AppType, assertContext } from '@owlmeans/context'
 import type { FastifyReply, FastifyRequest } from 'fastify'
-import { assertContext } from '@owlmeans/context'
 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 CommonEntrypoint, type GateService, provideResponse } from '@owlmeans/entrypoint'
 import { ResilientError } from '@owlmeans/error'
 import { OK } from '@owlmeans/api'
-import { handleError } from './error.js'
-import { executeResponse, provideRequest } from './payload.js'
+import { logger } from '@owlmeans/log'
+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'
 
-type Config = ServerConfig
-type Context = ServerContext<Config>
 
-export const canServeModule = (context: Context, module: CommonEntrypoint): module is ServerEntrypoint<unknown> => {
+export const canServeModule = (context: ServerContext2, module: CommonEntrypoint): module is ServerEntrypoint<unknown> => {
   if (module.route.route.type !== AppType.Backend) {
     return false
   }
   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
   }
 
@@ -33,20 +31,20 @@ export const canServeModule = (context: Context, module: CommonEntrypoint): modu
 export const createServerHandler = (module: ServerEntrypoint<FastifyRequest>, location: string) =>
   async (req: FastifyRequest, reply: FastifyReply) => {
     // We passed context using fastify request object
-    let context = assertContext<Config, Context>((req as any)._ctx, location)
+    let context = assertContext<ServerConfig2, ServerContext2>((req as any)._ctx, location)
     try {
       const authorized = await authorize(context, module, req, reply)
       context = authorized[0]
       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)
@@ -57,20 +55,17 @@ 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) {
-        console.warn(`SENDS DEFAULT RESPONSE: ${module.alias}`)
+        logger('http').warn(`SENDS DEFAULT RESPONSE: ${module.alias}`)
         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)
+      httpErrorHelper.handleError(error as Error, reply, httpErrorHelper.errorExposure(context.cfg))
     }
   }

package/src/utils/types.local.ts

@@ -0,0 +1,12 @@
+import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
+import type { Config as ApiConfig } from '../types.js'
+
+export type Config = ServerConfig
+
+export interface Context<C extends Config = Config> extends ServerContext<C> { }
+
+export type Severity = 'debug' | 'info' | 'warn' | 'error'
+
+export type ServerConfig2 = ApiConfig
+
+export type ServerContext2 = ServerContext<ServerConfig2>

package/src/utils/types.ts

@@ -0,0 +1,18 @@
+/**
+ * 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
+}
+
+export interface SerializedHttpError {
+  status: number
+  body: string
+  incidentId: string
+}