@vingitonga/elysia-winston-logger 0.1.0

package/README.md

@@ -0,0 +1,15 @@
+# elysia-winston-logger
+
+To install dependencies:
+
+```bash
+bun install
+```
+
+To run:
+
+```bash
+bun run index.ts
+```
+
+This project was created using `bun init` in bun v1.3.11. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.

package/dist/elysiaLogging.js

@@ -0,0 +1,115 @@
+import process from 'node:process';
+import { Elysia } from 'elysia';
+import { getFormattingMethodName, getIP } from './helpers';
+import { Log } from './log';
+/**
+ * List of IP headers to check in order of priority.
+ *
+ * @remarks
+ * The order of the headers in this list determines the priority of the headers to use when determining the client IP address.
+ * If the first header is not present, the second header is checked, and so on.
+ */
+export const headersToCheck = [
+    'x-forwarded-for', // X-Forwarded-For is the de-facto standard header
+    'x-real-ip', // Nginx proxy/FastCGI
+    'x-client-ip', // Apache [mod_remoteip](https://httpd.apache.org/docs/2.4/mod/mod_remoteip.html#page-header)
+    'cf-connecting-ip', // Cloudflare
+    'fastly-client-ip', // Fastly
+    'x-cluster-client-ip', // GCP
+    'x-forwarded', // RFC 7239
+    'forwarded-for', // RFC 7239
+    'forwarded', // RFC 7239
+    'appengine-user-ip', // GCP
+    'true-client-ip', // Akamai and Cloudflare
+    'cf-pseudo-ipv4', // Cloudflare
+];
+/**
+ * Creates a middleware function that logs incoming requests and outgoing responses.
+ *
+ * @param logger - The logger object to use for logging. Defaults to console.
+ * @param options - The options object to configure the middleware.
+ * @param options.level - The log level to use. Defaults to "info".
+ * @param options.format - The log format to use. Can be a string or a function. Defaults to "json".
+ * @param options.skip - A function that returns true to skip logging for a specific request.
+ * @param options.includeHeaders - An array of headers to include in the log.
+ * @param options.ipHeaders - An array of headers to check for the client IP address.
+ *
+ * @returns A middleware function that logs incoming requests and outgoing responses.
+ */
+export function ElysiaLogging(logger = console, options = {}) {
+    const { level = 'info', format = 'json', skip = undefined, includeHeaders = ['x-forwarded-for', 'authorization'], ipHeaders = headersToCheck } = options;
+    if (typeof format === 'string' && getFormattingMethodName(format) in Log.prototype === false) {
+        throw new Error(`Formatter '${format}' not found!`);
+    }
+    return new Elysia({ name: 'logger' })
+        .derive({ as: 'global' }, ({ request, server }) => {
+        const clientIP = server ? (getIP(request.headers, ipHeaders) ?? server.requestIP(request)?.address ?? undefined) : undefined;
+        return { ip: clientIP };
+    })
+        .onError(({ store, error }) => {
+        ;
+        store.error = error;
+    })
+        .onRequest(({ store }) => {
+        ;
+        store.requestStart = process.hrtime.bigint();
+    })
+        .onAfterHandle(({ store }) => {
+        ;
+        store.responseSize = undefined;
+    })
+        .onAfterResponse((ctx) => {
+        if (skip && typeof skip === 'function' && skip(ctx)) {
+            return;
+        }
+        let duration = 0;
+        if (ctx.store.requestStart !== undefined && typeof ctx.store.requestStart === 'bigint') {
+            duration = Number(process.hrtime.bigint() - ctx.store.requestStart);
+        }
+        const logObject = new Log({
+            request: {
+                ip: ctx.ip,
+                method: ctx.request.method,
+                url: {
+                    path: ctx.path,
+                    params: Object.fromEntries(new URLSearchParams(new URL(ctx.request.url).search)),
+                },
+            },
+            response: {
+                status_code: ctx.set.status,
+                time: duration,
+            },
+        });
+        if (ctx.store.error !== undefined) {
+            logObject.error = ctx.store.error;
+        }
+        // Add request ID if it exists
+        if (ctx.request.headers.has('x-request-id')) {
+            logObject.log.request.requestID = ctx.request.headers.get('x-request-id');
+        }
+        // Include headers
+        for (const header of includeHeaders) {
+            if (ctx.request.headers.has(header)) {
+                logObject.log.request.headers = {
+                    ...logObject.log.request.headers,
+                    [header]: ctx.request.headers.get(header),
+                };
+            }
+        }
+        let logOutput;
+        // If the log format is a function, call it and log the output
+        if (typeof format === 'function') {
+            logOutput = format(logObject.log);
+        }
+        else if (typeof format === 'string') {
+            const formattingMethod = getFormattingMethodName(format);
+            logOutput = logObject[formattingMethod]();
+        }
+        else {
+            throw new Error(`Invalid formatting method type '${typeof format}'!`);
+        }
+        // This invokes, e.g. `logger.info(logOutput)` for any given level
+        logger[level](logOutput);
+    })
+        .as('global');
+}

package/dist/helpers.js

@@ -0,0 +1,89 @@
+import { headersToCheck } from './elysiaLogging';
+const NANOSECOND = 1;
+const MICROSECOND = 1e3 * NANOSECOND;
+const MILLISECOND = 1e3 * MICROSECOND;
+const SECOND = 1e3 * MILLISECOND;
+/**
+ * Parses a Basic Authentication header string and returns an object containing the username and password.
+ *
+ * @param header - The Basic Authentication header string to parse.
+ *
+ * @returns An object containing the username and password, or undefined if the header is invalid.
+ */
+export function parseBasicAuthHeader(header) {
+    const [type, authString] = header.split(' ');
+    // Check if authType is Basic and authString is valid base64
+    if (type !== 'Basic')
+        return undefined;
+    if (!isValidBase64(authString))
+        return undefined;
+    const authStringDecoded = Buffer.from(authString, 'base64').toString();
+    const [username, password] = authStringDecoded.includes(':') ? authStringDecoded.split(':', 2) : [undefined, undefined];
+    return {
+        type: type,
+        username: username ?? '',
+        password: password ?? '',
+    };
+}
+/**
+ * Formats a duration in nanoseconds to a human-readable string.
+ *
+ * @param durationInNanoseconds - The duration in nanoseconds to format.
+ *
+ * @returns A string representing the formatted duration.
+ */
+export function formatDuration(durationInNanoseconds) {
+    if (durationInNanoseconds >= SECOND) {
+        return `${(durationInNanoseconds / SECOND).toPrecision(2)}s`;
+    }
+    else if (durationInNanoseconds >= MILLISECOND) {
+        return `${(durationInNanoseconds / MILLISECOND).toPrecision(4)}ms`;
+    }
+    else if (durationInNanoseconds >= MICROSECOND) {
+        return `${(durationInNanoseconds / MICROSECOND).toPrecision(4)}µs`;
+    }
+    else {
+        return `${durationInNanoseconds.toPrecision(4)}ns`;
+    }
+}
+/**
+ * Returns the IP address of the client making the request.
+ *
+ * @param headers - The headers object from the request.
+ * @param ipHeaders - An array of header names to check for the IP address. Defaults to common IP headers.
+ *
+ * @returns The IP address of the client, or undefined if not found.
+ */
+export function getIP(headers, ipHeaders = headersToCheck) {
+    let clientIP = null;
+    for (const header of ipHeaders) {
+        clientIP = headers.get(header);
+        if (clientIP !== null && typeof clientIP === 'string') {
+            if (clientIP.includes(',')) {
+                clientIP = clientIP.split(',')[0];
+            }
+            break;
+        }
+    }
+    return clientIP;
+}
+/**
+ * Returns the name of the formatting method for a given format string.
+ *
+ * @param format - The format string to get the formatting method name for.
+ *
+ * @returns The name of the formatting method.
+ */
+export function getFormattingMethodName(format) {
+    return `format${format.charAt(0).toUpperCase() + format.slice(1)}`;
+}
+/**
+ * Checks if a given string is a valid base64 encoded string.
+ *
+ * @param str - The string to be checked.
+ *
+ * @returns A boolean indicating whether the string is a valid base64 encoded string.
+ */
+function isValidBase64(str) {
+    return Buffer.from(str, 'base64').toString('base64') === str;
+}

package/dist/index.js

@@ -0,0 +1,45 @@
+import util from 'node:util';
+import { createLogger, format, transports } from 'winston';
+import { ElysiaLogging } from './elysiaLogging';
+import { LogFormat } from './logger-types';
+const inspect = (value) => util.inspect(value, {
+    colors: true,
+    depth: null,
+    compact: false,
+    breakLength: 120,
+});
+const prettyMeta = format((info) => {
+    // Pretty-print the primary message if it's an object
+    if (typeof info.message !== 'string') {
+        info.message = inspect(info.message);
+    }
+    // Pretty-print every metadata field
+    for (const [key, value] of Object.entries(info)) {
+        if (['level', 'message', 'timestamp', 'stack'].includes(key))
+            continue;
+        if (value instanceof Error) {
+            info[key] = value.stack ?? value.message;
+        }
+        else if (typeof value === 'object' && value !== null) {
+            info[key] = inspect(value);
+        }
+    }
+    return info;
+});
+export const defaultLogger = createLogger({
+    level: Bun.env.LOG_LEVEL ?? 'info', // Note: process.env.LOG_LEVEL is more standard if you want Node compatibility, but Bun.env is fine for pure Bun
+    format: format.combine(format.colorize(), prettyMeta(), format.errors({ stack: true }), format.splat(), format.timestamp({ format: 'YYYY-MM-DD hh:mm:ss.SSS A' }), format.printf(({ timestamp, level, message }) => {
+        return `[${timestamp}] ${level}: ${message}`;
+    })),
+    transports: [new transports.Console()],
+});
+export const winstonLogger = (customLogger, options) => {
+    // If they pass their own logger, use it. Otherwise use your default.
+    const loggerToUse = customLogger ?? defaultLogger;
+    // Provide sensible defaults if they don't pass options
+    const pluginOptions = {
+        level: options?.level ?? 'info',
+        format: options?.format ?? LogFormat.JSON,
+    };
+    return ElysiaLogging(loggerToUse, pluginOptions);
+};

package/dist/log.js

@@ -0,0 +1,83 @@
+import { format } from 'date-fns';
+import { toZonedTime } from 'date-fns-tz';
+import { formatDuration, parseBasicAuthHeader } from './helpers';
+/**
+ * Log class
+ *
+ * This class is used to format the log object in different ways.
+ *  - formatJson() returns the log object as is
+ * - formatCommon() returns the log object as a common log format (NCSA) string
+ * - formatShort() returns the log object as a short string (perfect for dev console)
+ *
+ * @param log Log object
+ *
+ * @returns Log object
+ *
+ * @example
+ * const log = new Log(logObject);
+ * console.log(log.formatCommon());
+ * console.log(log.formatShort());
+ * console.log(log.formatJson());
+ **/
+export class Log {
+    // Properties
+    logObject;
+    // Constructor
+    constructor(log) {
+        this.logObject = log;
+    }
+    // Getters and setters
+    set error(error) {
+        this.logObject.error = error;
+    }
+    get log() {
+        return this.logObject;
+    }
+    /**
+     * Simply return the log object and let the logger pretty print it
+     *
+     * @returns Log object as is
+     */
+    formatJson() {
+        return {
+            ...{
+                message: `${this.logObject.request.method} ${this.logObject.request.url.path} completed with status ${this.logObject.response.status_code} in ${formatDuration(this.logObject.response.time)}`,
+            },
+            ...this.logObject,
+        };
+    }
+    /**
+     * Formats the log object as a common log format (NCSA) string
+     *
+     * @see https://en.wikipedia.org/wiki/Common_Log_Format
+     *
+     *
+     * @returns Log object as a common log format (NCSA) string
+     */
+    formatCommon() {
+        // Get basic auth user if set, else "-"
+        const basicAuthUser = parseBasicAuthHeader(this.logObject.request.headers?.authorization ?? '')?.username ?? '-';
+        // @TODO: This is not yet exposed by Elysia (https://github.com/elysiajs/elysia/issues/324)
+        const requestProtocol = this.logObject.request.headers?.['x-forwarded-proto'] ?? 'HTTP/1.1';
+        // Formate date/time of the request (%d/%b/%Y:%H:%M:%S %z)
+        const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+        const zonedDate = toZonedTime(Date.now(), timeZone);
+        const formattedDate = format(zonedDate, 'dd/MMM/yyyy:HH:mm:ss xx');
+        // @TODO: This is not yet exposed by Elysia (https://github.com/elysiajs/elysia/issues/324)
+        const responseSize = undefined;
+        // Return formatted log string
+        return `${this.logObject.request.ip} - ${basicAuthUser} [${formattedDate}] "${this.logObject.request.method} ${this.logObject.request.url.path} ${requestProtocol}" ${this.logObject.response.status_code} ${responseSize ?? '-'}`;
+    }
+    /**
+     * Formats the log object as a short string (perfect for dev console)
+     *
+     * @returns Log object as a short string (perfect for dev console)
+     */
+    formatShort() {
+        const durationInNanoseconds = this.logObject.response.time;
+        const timeMessage = formatDuration(durationInNanoseconds);
+        const queryString = Object.keys(this.logObject.request.url.params).length ? `?${new URLSearchParams(this.logObject.request.url.params).toString()}` : '';
+        const requestUri = this.logObject.request.url.path + queryString;
+        return `[${this.logObject.request.ip}] ${this.logObject.request.method} ${requestUri} ${this.logObject.response.status_code} (${timeMessage})`;
+    }
+}

package/dist/logger-types.js

@@ -0,0 +1,7 @@
+//
+export const LogFormat = {
+    JSON: 'json',
+    COMMON: 'common',
+    SHORT: 'short',
+    // Add other methods here
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+	"name": "@vingitonga/elysia-winston-logger",
+	"version": "0.1.0",
+	"description": "Winston logger plugin for Elysia",
+	"main": "./dist/index.js",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"type": "module",
+	"scripts": {
+		"build": "rm -rf dist && bun build ./src/index.ts --outdir ./dist --target node && tsc",
+		"prepublishOnly": "bun run build",
+		"format": "biome format --write .",
+		"lint": "biome lint --write ."
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.5.3",
+		"@types/bun": "latest",
+		"elysia": "^1.4.29",
+		"typescript": "^5",
+		"winston": "^3.19.0"
+	},
+	"peerDependencies": {
+		"elysia": ">=1.4.0",
+		"winston": ">=3.0.0"
+	},
+	"dependencies": {
+		"date-fns": "^4.4.0",
+		"date-fns-tz": "^3.2.0"
+	}
+}