Feature: configure logging wrapper

documentation/docs/intro.md

@@ -12,7 +12,7 @@ The OGCIO design system requires a wrapper for usage within NextJS. This is done
 
 Most building blocks and 3rd party services are mocked in this mono-repo.
 
-Testing around RSC and RSA is still poorly supported. We use Playwright for e2e testing and Jest for unit testing. At the moment there isn't a solid integration testing library for async React components
+Testing around RSC and RSA is still poorly supported. We use Playwright for e2e testing and Tap for unit testing. At the moment there isn't a solid integration testing library for async React components
 
 ## Setup
 

packages/logging-wrapper/.eslintrc.json

@@ -0,0 +1,17 @@
+{
+    "parser": "@typescript-eslint/parser",
+    "extends": [
+      "plugin:@typescript-eslint/recommended",
+      "plugin:prettier/recommended",
+      "eslint:recommended"
+    ],
+    "parserOptions": {
+      "ecmaVersion": 2020,
+      "sourceType": "module"
+    },
+    "rules": {
+    },
+    "env": {
+      "node": true
+    }
+  }

packages/logging-wrapper/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "logging-wrapper",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "test": "jest",
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint . --ext .ts",
+    "lint:fix": "eslint . --ext .ts --fix"
+  },
+  "keywords": [],
+  "author": "[email protected]",
+  "license": "ISC",
+  "dependencies": {
+    "@fastify/error": "^3.4.1",
+    "fastify": "^4.26.2",
+    "hyperid": "^3.2.0"
+  },
+  "devDependencies": {
+    "@tsconfig/node20": "^20.1.4",
+    "@types/node": "^20.12.7",
+    "@typescript-eslint/eslint-plugin": "^7.7.1",
+    "@typescript-eslint/parser": "^7.7.1",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-prettier": "^5.1.3",
+    "prettier": "^3.2.5",
+    "typescript": "^5.4.5"
+  }
+}

packages/logging-wrapper/src/fastify-logging-wrapper.ts

@@ -0,0 +1,139 @@
+import {
+  FastifyReply,
+  FastifyServerOptions,
+  FastifyInstance,
+  FastifyRequest,
+} from "fastify";
+import hyperid from "hyperid";
+import { LogMessages, REQUEST_ID_LOG_LABEL } from "./logging-wrapper-entities";
+import {
+  getLoggerConfiguration,
+  getLoggingContextError,
+  getPartialLoggingContextError,
+  parseErrorClass,
+  parseFullLoggingRequest,
+  resetLoggingContext,
+  setLoggingContext,
+} from "./logging-wrapper";
+import { pino, DestinationStream } from "pino";
+import createError, { FastifyError } from "@fastify/error";
+
+const hyperidInstance = hyperid({ fixedLength: true, urlSafe: true });
+
+const buildErrorResponse = (error: FastifyError, request: FastifyRequest) => ({
+  errors: [
+    {
+      code: parseErrorClass(error),
+      detail: error.message,
+      request_id: request.id,
+    },
+  ],
+});
+
+// The error handler below is the same as the original one in Fastify,
+// just without unwanted log entries
+// I've opened an issue to fastify to ask them if we could avoid logging
+// those entries when disableRequestLogging is true
+// https://github.com/fastify/fastify/issues/5409
+const initializeErrorHandler = (server: FastifyInstance): void => {
+  const setErrorHeaders = (
+    error: null | {
+      headers?: { [x: string]: string | number | string[] | undefined };
+      status?: number;
+      statusCode?: number;
+    },
+    reply: FastifyReply,
+  ) => {
+    const res = reply.raw;
+    let statusCode = res.statusCode;
+    statusCode = statusCode >= 400 ? statusCode : 500;
+    // treat undefined and null as same
+    if (error != null) {
+      if (error.headers !== undefined) {
+        reply.headers(error.headers);
+      }
+      if (error.status && error.status >= 400) {
+        statusCode = error.status;
+      } else if (error.statusCode && error.statusCode >= 400) {
+        statusCode = error.statusCode;
+      }
+    }
+    res.statusCode = statusCode;
+  };
+
+  server.setErrorHandler(function (error, request, reply) {
+    setErrorHeaders(error, reply);
+    if (!reply.statusCode || reply.statusCode === 200) {
+      const statusCode = error.statusCode ?? 500;
+      reply.code(statusCode >= 400 ? statusCode : 500);
+    }
+
+    reply.send(buildErrorResponse(error, request));
+  });
+};
+
+// The error handler below is the same as the original one in Fastify,
+// just without unwanted log entries
+const initializeNotFoundHandler = (server: FastifyInstance): void => {
+  server.setNotFoundHandler((request: FastifyRequest, reply: FastifyReply) => {
+    const { url, method } = request.raw;
+    const message = `Route ${method}:${url} not found`;
+
+    const error = createError("FST_ERR_NOT_FOUND", message, 404)();
+    setLoggingContext({
+      error,
+    });
+
+    request.log.error({ error: getLoggingContextError() }, LogMessages.Error);
+    reply.code(404).send(buildErrorResponse(error, request));
+  });
+};
+
+export const initializeLoggingHooks = (
+  server: FastifyInstance,
+  overrideErrorHandler: boolean = true,
+): void => {
+  server.addHook("preHandler", (request, _reply, done) => {
+    setLoggingContext({ request });
+    request.log.info(
+      { request: parseFullLoggingRequest(request) },
+      LogMessages.NewRequest,
+    );
+    done();
+  });
+
+  server.addHook("onResponse", (_req, reply, done) => {
+    setLoggingContext({ response: reply });
+    reply.log.info(LogMessages.Response);
+    // Include error in API Track if exists
+    reply.log.info(
+      { error: getPartialLoggingContextError() },
+      LogMessages.ApiTrack,
+    );
+    resetLoggingContext();
+    done();
+  });
+
+  server.addHook("onError", (request, _reply, error, done) => {
+    setLoggingContext({ error });
+
+    request.log.error({ error: getLoggingContextError() }, LogMessages.Error);
+
+    done();
+  });
+
+  if (overrideErrorHandler) {
+    initializeErrorHandler(server);
+    initializeNotFoundHandler(server);
+  }
+};
+
+export const getLoggingConfiguration = (
+  loggerDestination?: DestinationStream,
+): FastifyServerOptions => ({
+  logger: pino(getLoggerConfiguration(), loggerDestination),
+  disableRequestLogging: true,
+  genReqId: () => hyperidInstance(),
+  requestIdLogLabel: REQUEST_ID_LOG_LABEL,
+  requestIdHeader: false,
+});

packages/logging-wrapper/src/logging-wrapper-entities.ts

@@ -0,0 +1,63 @@
+export interface LoggingRequest {
+  scheme: string;
+  method: string;
+  path: string | undefined;
+  hostname: string;
+  query_params: unknown;
+  [key: string]: unknown;
+}
+
+export interface FullLoggingRequest extends LoggingRequest {
+  headers: unknown;
+  user_agent: string | undefined;
+  client_ip: string;
+}
+
+export interface LoggingResponse {
+  headers: unknown;
+  status_code: number;
+  [key: string]: unknown;
+}
+
+export interface LoggingError {
+  class: LogErrorClasses;
+  message: string;
+  trace?: string;
+  [key: string]: unknown;
+}
+
+export interface LoggingContext {
+  request?: LoggingRequest;
+  response?: LoggingResponse;
+  error?: LoggingError;
+}
+
+export enum LogMessages {
+  NewRequest = "NEW_REQUEST",
+  Response = "RESPONSE",
+  Error = "ERROR",
+  ApiTrack = "API_TRACK",
+}
+
+export enum LogErrorClasses {
+  ServerError = "SERVER_ERROR",
+  ValidationError = "VALIDATION_ERROR",
+  RequestError = "REQUEST_ERROR",
+  GatewayError = "GATEWAY_ERROR",
+  UnknownError = "UNKNOWN_ERROR",
+}
+
+export const REDACTED_VALUE = "[redacted]";
+
+export const REDACTED_PATHS = [
+  '*.headers["x-amz-security-token"]',
+  '*.headers["x-api-key"]',
+  '*.headers["authorization"]',
+  '*.headers["cookie"]',
+  '*.headers["set-cookie"]',
+  '*.headers["proxy-authorization"]',
+];
+
+export const MESSAGE_KEY = "message";
+
+export const REQUEST_ID_LOG_LABEL = "request_id";

packages/logging-wrapper/src/logging-wrapper.ts

@@ -0,0 +1,131 @@
+import { FastifyRequest, FastifyReply, FastifyError } from "fastify";
+import { hostname } from "os";
+import {
+  LoggingContext,
+  LoggingRequest,
+  FullLoggingRequest,
+  LoggingResponse,
+  LogErrorClasses,
+  LoggingError,
+  REDACTED_VALUE,
+  REDACTED_PATHS,
+  MESSAGE_KEY,
+} from "./logging-wrapper-entities";
+import { LogLevel, PinoLoggerOptions } from "fastify/types/logger";
+
+const loggingContext: LoggingContext = {};
+
+export const getLoggingContext = (params: {
+  includeError: boolean;
+}): LoggingContext =>
+  params.includeError
+    ? loggingContext
+    : { ...loggingContext, error: undefined };
+
+export const setLoggingContext = (params: {
+  request?: FastifyRequest;
+  response?: FastifyReply;
+  error?: FastifyError;
+}): void => {
+  if (params.request !== undefined) {
+    loggingContext.request = parseLoggingRequest(params.request);
+  }
+  if (params.response !== undefined) {
+    loggingContext.response = parseLoggingResponse(params.response);
+  }
+  if (params.error !== undefined) {
+    loggingContext.error = parseLoggingError(params.error);
+  }
+};
+
+export const resetLoggingContext = (): void => {
+  loggingContext.request = undefined;
+  loggingContext.response = undefined;
+  loggingContext.error = undefined;
+};
+
+export const getLoggingContextError = (): LoggingError | undefined =>
+  getLoggingContext({ includeError: true }).error;
+
+export const getPartialLoggingContextError = ():
+  | Omit<LoggingError, "trace">
+  | undefined => ({
+  ...(getLoggingContext({ includeError: true }).error ?? {}),
+  trace: undefined,
+});
+
+const getPathWithoutParams = (req: FastifyRequest): string =>
+  req.routeOptions?.url ?? req.url.split("?")[0];
+
+const parseLoggingRequest = (req: FastifyRequest): LoggingRequest => ({
+  scheme: req.protocol,
+  method: req.method,
+  path: getPathWithoutParams(req),
+  hostname: req.hostname,
+  query_params: req.query,
+});
+
+export const parseFullLoggingRequest = (
+  req: FastifyRequest,
+): FullLoggingRequest => ({
+  ...parseLoggingRequest(req),
+  headers: req.headers,
+  client_ip: req.ip,
+  user_agent: req.headers["user-agent"] ?? undefined,
+});
+
+const parseLoggingResponse = (res: FastifyReply): LoggingResponse => ({
+  status_code: res.statusCode,
+  headers: res.getHeaders(),
+});
+
+export const parseErrorClass = (error: FastifyError): LogErrorClasses => {
+  // TODO Implement the management of GATEWAY_ERROR
+
+  if (!error.statusCode) {
+    return LogErrorClasses.UnknownError;
+  }
+  const statusCode = Number(error.statusCode);
+
+  if (statusCode >= 500) {
+    return LogErrorClasses.ServerError;
+  }
+  if (statusCode === 422) {
+    return LogErrorClasses.ValidationError;
+  }
+  if (statusCode >= 400) {
+    return LogErrorClasses.RequestError;
+  }
+
+  return LogErrorClasses.UnknownError;
+};
+
+const parseLoggingError = (error: FastifyError): LoggingError => ({
+  class: parseErrorClass(error),
+  message: error.message,
+  trace: error.stack,
+  code: error.code,
+});
+
+export const getLoggerConfiguration = (
+  mininumLevel: LogLevel = "debug",
+): PinoLoggerOptions => ({
+  base: { hostname: hostname() },
+  messageKey: MESSAGE_KEY,
+  mixin: () => ({
+    timestamp: Date.now(),
+    ...getLoggingContext({ includeError: false }),
+  }),
+  redact: {
+    paths: REDACTED_PATHS,
+    censor: REDACTED_VALUE,
+  },
+  timestamp: false,
+  formatters: {
+    level: (name: string, levelVal: number) => ({
+      level: levelVal,
+      level_name: name.toUpperCase(),
+    }),
+  },
+  level: mininumLevel,
+});