@darksheep/express 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 1.0.0 (2025-03-25)
+
+
+### 🧹 Chores
+
+* Add express as a peer dep ([f259160](https://github.com/DarkSheepSoftware/node-packages/commit/f25916067cc03e7ad0cf651e158c94f7d49e7c82))
+* Move express-logger to express package ([aaa7604](https://github.com/DarkSheepSoftware/node-packages/commit/aaa760470ff9239a43cc9124550e3325099cff06))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * devDependencies
+    * @darksheep/logger bumped from 1.0.10 to 1.1.0
+  * peerDependencies
+    * @darksheep/logger bumped from ~1.0.10 to ~1.1.0

package/README.md

@@ -0,0 +1,2 @@
+# @darksheep/express
+Automatically log your express requests.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@darksheep/express",
+  "version": "1.0.0",
+  "description": "express utilites and other bits",
+  "license": "UNLICENCED",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "types",
+    "!*.test.*"
+  ],
+  "scripts": {
+    "prepack": "yarn dlx -q -p typescript tsc",
+    "test": "node --test src/**/*.test.js",
+    "test:watch": "node --watch --test src/**/*.test.js"
+  },
+  "dependencies": {
+    "@darksheep/prune": "1.0.4",
+    "on-finished": "2.4.1"
+  },
+  "devDependencies": {
+    "@darksheep/logger": "1.1.0",
+    "@types/express": "~5.0.0",
+    "@types/on-finished": "^2",
+    "express": "~4.21.2"
+  },
+  "peerDependencies": {
+    "@darksheep/logger": "~1.0.10",
+    "express": "~4.21.2 || ~5"
+  },
+  "engines": {
+    "node": "^20.13.1 || ^22.2.0"
+  }
+}

package/src/express.d.ts

@@ -0,0 +1,18 @@
+/* eslint @typescript-eslint/consistent-type-definitions: 0, n/no-missing-import: 0 */
+
+import { type Logger } from '@darksheep/logger';
+
+declare global {
+  namespace Express {
+    interface Request {
+      id: string;
+      logger: Logger;
+    }
+  }
+}
+
+export {
+  type Handler,
+  type Request,
+  type Response,
+} from 'express';

package/src/get-trail.js

@@ -0,0 +1,29 @@
+/**
+ * @import { Request } from './express.js'
+ * @import { Logger } from '@darksheep/logger'
+ */
+import { randomUUID } from 'node:crypto';
+
+/**
+ * @param {Request} request - The express request.
+ * @param {Logger} logger - The root logger.
+ * @param {string} headerName - The name of the header used in correlation.
+ * @returns {string}
+ */
+export function getTrail(request, logger, headerName) {
+  const loggerTrail = logger.get('trail');
+  if (typeof loggerTrail === 'string') {
+    return loggerTrail;
+  }
+
+  const header = request.header(headerName);
+  if (typeof header === 'string') {
+    return header;
+  }
+
+  if (typeof request.id === 'string') {
+    return request.id;
+  }
+
+  return randomUUID();
+}

package/src/index.js

@@ -0,0 +1 @@
+export { createRequestLogger } from './request-logger.js';

package/src/request-logger.js

@@ -0,0 +1,85 @@
+/**
+ * @import { Socket } from 'node:net'
+ * @import { Handler } from './express.js'
+ * @import { Filter } from './should-filter.js'
+ */
+
+import { Logger } from '@darksheep/logger';
+import { pruneShallow } from '@darksheep/prune';
+import onFinished from 'on-finished';
+
+import { shouldFilterOutRequest } from './should-filter.js';
+
+/** @type {WeakMap<Socket, number>} */
+const sockets = new WeakMap();
+
+import { randomUUID } from 'node:crypto';
+
+/**
+ * @param {Logger} logger - A callback that can be bound to the request.
+ * @param {Filter[]} [filters] - A list of requests to not log.
+ * @param {string} [headerName] - The name of a header to include in the response with the trail.
+ * @returns {Handler}
+ */
+export function createRequestLogger(
+  logger,
+  filters,
+  headerName = 'X-Request-Id',
+) {
+  return (request, response, next) => {
+    request.id ??= (
+      request.header(headerName) ??
+      request.id ??
+      randomUUID()
+    );
+    request.logger = logger.trail(request.id);
+
+    Logger.wrap({
+      request: request,
+      trail: request.id,
+    }, () => {
+      const [ requestPath ] = request.originalUrl.split('?', 1);
+      if (
+        requestPath == null ||
+        shouldFilterOutRequest(requestPath, filters)
+      ) {
+        return next();
+      }
+
+      const startBytesRead = sockets.get(request.socket) ?? 0;
+      const startBytesWritten = request.socket.bytesWritten;
+
+      const requestStartMs = Date.now();
+      onFinished(response, (error) => {
+        sockets.set(request.socket, request.socket.bytesRead);
+
+        const message = `${request.method} ${requestPath} ${response.statusCode}`;
+        const context = pruneShallow({
+          duration: Date.now() - requestStartMs,
+          error: error,
+
+          request: request,
+          response: response,
+          socket: {
+            ip: request.ip,
+            hostname: request.hostname,
+            bytesRead: request.socket.bytesRead - startBytesRead,
+            bytesWritten: request.socket.bytesWritten - startBytesWritten,
+          },
+        });
+
+        if (response.statusCode < 400) {
+          return request.logger.info(message, context);
+        }
+
+        if (response.statusCode < 500) {
+          return request.logger.warning(message, context);
+        }
+
+        return request.logger.error(message, context);
+      });
+
+      next();
+    });
+  };
+}

package/src/should-filter.js

@@ -0,0 +1,27 @@
+const fallbackFilters = [
+  '/favicon.ico',
+  /^\/health(?:check)?z?$/u,
+  /^\/read(?:y|iness)z?$/u,
+  /^\/live(?:ness)?z?$/u,
+];
+
+/** @typedef {string|RegExp} Filter */
+
+/**
+ * @param {string} requestPath - The path to test.
+ * @param {Filter[]} [filters] - A list of paths to filter out.
+ * @returns {boolean}
+ */
+export function shouldFilterOutRequest(requestPath, filters = fallbackFilters) {
+  for (const filter of filters) {
+    if (filter instanceof RegExp && filter.test(requestPath)) {
+      return true;
+    }
+
+    if (typeof filter === 'string' && requestPath === filter) {
+      return true;
+    }
+  }
+
+  return false;
+}

package/types/index.d.ts

@@ -0,0 +1 @@
+export { createRequestLogger } from "./request-logger.js";

package/types/request-logger.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @param {Logger} logger - A callback that can be bound to the request.
+ * @param {Filter[]} [filters] - A list of requests to not log.
+ * @param {string} [headerName] - The name of a header to include in the response with the trail.
+ * @returns {Handler}
+ */
+export function createRequestLogger(logger: Logger, filters?: Filter[], headerName?: string): Handler;
+import { Logger } from '@darksheep/logger';
+import type { Filter } from './should-filter.js';
+import type { Handler } from './express.js';

package/types/should-filter.d.ts

@@ -0,0 +1,8 @@
+/** @typedef {string|RegExp} Filter */
+/**
+ * @param {string} requestPath - The path to test.
+ * @param {Filter[]} [filters] - A list of paths to filter out.
+ * @returns {boolean}
+ */
+export function shouldFilterOutRequest(requestPath: string, filters?: Filter[]): boolean;
+export type Filter = string | RegExp;