@darksheep/logger 1.0.0

package/src/logger.js

@@ -0,0 +1,369 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { deepmerge } from 'deepmerge-ts';
+
+import { environment } from './utilities/environment.js';
+import { getLastCallsite } from './utilities/last-callsite.js';
+import { LogLevels } from './utilities/log-types.js';
+import { checkLogLevel, checkLogFilters } from './utilities/log-filters.js';
+
+import { replace } from './replacer.js';
+import { ErrorReplacer } from './replacers/error.js';
+import { stdoutWrite } from './stdout-write.js';
+import { formatter } from './formatter.js';
+
+/**
+ * @typedef {Object} Options
+ * @property {typeof replace} [replace] The replacer function to use
+ * @property {import('./replacer.js').Replacer<any, any>[]} [replacers] The replacers to use in the replacer
+ * @property {typeof formatter} [format] The formatter function to use (eg console or json formatter)
+ * @property {typeof stdoutWrite} [write] The place to write the log to
+ */
+
+export class Logger {
+  /** @type {AsyncLocalStorage<import('./utilities/log-types.js').LogContext[]>} */
+  static storage = new AsyncLocalStorage();
+
+  /**
+   * @template [R=unknown]
+   * @overload
+   * @param {() => R} callback The function to wrap the context in
+   * @returns {R}
+   */
+  /**
+   * @template [R=unknown]
+   * @overload
+   * @param {import('./utilities/log-types.js').LogContext} context Context to bind ot the async context
+   * @param {() => R} callback The function to wrap the context in
+   * @returns {R}
+   */
+  /**
+   * @template [R=unknown]
+   * @param {unknown} context Context to bind ot the async context
+   * @param {unknown} [callback] The function to wrap the context in
+   * @returns {R}
+   */
+  static wrap(context, callback) {
+    // If there is already some context, keep it around
+    const store = Logger.storage.getStore() ?? [];
+
+    if (typeof context === 'function') {
+      return Logger.storage.run(
+        [ ...store ],
+        /** @type {() => R} */ (context),
+      );
+    }
+
+    return Logger.storage.run(
+      [ ...store, /** @type {import('./utilities/log-types.js').LogContext} */ (context) ],
+      /** @type {() => R} */ (callback),
+    );
+  }
+
+  /**
+   * @template [R=unknown]
+   * @param {() => R} callback The function to wrap the context in
+   * @returns {R}
+   */
+  wrap(callback) {
+    return Logger.wrap(this.#context, callback);
+  }
+
+  /**
+   * @param {import('./utilities/log-types.js').LogContext} context Context to bind ot the async context
+   * @returns {void}
+   */
+  static addAsyncContext(context) {
+    const store = Logger.storage.getStore();
+
+    if (store == null) {
+      throw new Error('Context not inside Context#wrap');
+    }
+
+    store.push(context);
+  }
+
+  /** @type {import('./replacer.js').Replacer[]} */
+  replacers = [];
+
+  /** @type {typeof formatter} */
+  #format = formatter;
+  /** @type {typeof replace} */
+  #replace = replace;
+  /** @type {typeof stdoutWrite} */
+  #write = stdoutWrite;
+  /** @type {import('./utilities/log-types.js').LogContext} */
+  #context;
+
+  /**
+   * @param {import('./utilities/log-types.js').LogContext} [context] Context to add to the logger
+   * @param {Options} [options] Options for the loggers output
+   */
+  constructor(context, options) {
+    this.#context = context ?? {};
+    if (options?.replace != null) {
+      this.#replace = options.replace;
+    }
+    if (options?.replacers != null) {
+      this.replacers = options.replacers;
+    }
+    if (options?.format != null) {
+      this.#format = options.format;
+    }
+    if (options?.write != null) {
+      this.#write = options.write;
+    }
+  }
+
+  /**
+   * Write a new log entry
+   * @param {import('./utilities/log-types.js').LogLevel} level the log level of the message to log
+   * @param {Error | string} message The message to log
+   * @param {import('./utilities/log-types.js').LogContext} [context] Context to add to the log (merged with this.context, and Logger.contexts)
+   * @returns {void}
+   */
+  write(level, message, context) {
+    /** @type {import('./utilities/log-types.js').LogContext[]} */
+    const contexts = [];
+
+    const asyncContexts = Logger.storage.getStore();
+    if (asyncContexts instanceof Array) {
+      contexts.push(...asyncContexts);
+    }
+
+    contexts.push(this.#context);
+    if (context instanceof Object) {
+      contexts.push(context);
+    }
+
+    const fullContext =
+      /** @type {import('./utilities/log-types.js').LogContext} */
+      (deepmerge(...contexts));
+
+    if (
+      checkLogLevel(level) === false ||
+      checkLogFilters(fullContext?.channel) === false
+    ) {
+      return;
+    }
+
+    /** @type {import('./utilities/log-types.js').LogEntry} */
+    const entry = (
+      typeof message === 'string'
+        ? { ...fullContext, message, level }
+        : { ...fullContext, ...ErrorReplacer.replace(message), level }
+    );
+
+    if (environment.includeCallsite === true) {
+      entry.source = getLastCallsite();
+    }
+
+    const normalised =
+      /** @type {import('./utilities/log-types.js').LogEntry} */
+      (this.#replace(entry, this.replacers));
+
+    const formatted = this.#format(normalised);
+
+    return this.#write(formatted);
+  }
+
+  // =========
+  //   Level
+  // =========
+
+  /**
+   * Write a log with the level 'critical' - A crucial part of the application is not working
+   *
+   * @param {Error | string} message The message to log
+   * @param {import('./utilities/log-types.js').LogContext} [context] Additional context
+   * @returns {void}
+   */
+  critical(message, context) {
+    return this.write(LogLevels.critical, message, context);
+  }
+
+  /**
+   * Write a log with the level 'error' - A non critical operation fails
+   * @param {Error | string} message The message to log
+   * @param {import('./utilities/log-types.js').LogContext} [context] Additional context
+   * @returns {void}
+   */
+  error(message, context) {
+    return this.write(LogLevels.error, message, context);
+  }
+
+  /**
+   * Write a log with the level 'warning' - An operation might fail in the future
+   * @param {Error | string} message The message to log
+   * @param {import('./utilities/log-types.js').LogContext} [context] Additional context
+   * @returns {void}
+   */
+  warning(message, context) {
+    return this.write(LogLevels.warning, message, context);
+  }
+
+  /**
+   * Write a log with the level 'notice' - Information about events that may be unusual
+   * @param {Error | string} message The message to log
+   * @param {import('./utilities/log-types.js').LogContext} [context] Additional context
+   * @returns {void}
+   */
+  notice(message, context) {
+    return this.write(LogLevels.notice, message, context);
+  }
+
+  /**
+   * Write a log with the level 'info' - Information about successful operations
+   * @param {Error | string} message The message to log
+   * @param {import('./utilities/log-types.js').LogContext} [context] Additional context
+   * @returns {void}
+   */
+  info(message, context) {
+    return this.write(LogLevels.info, message, context);
+  }
+
+  /**
+   * Write a log with the level 'debug' - Information that is unlikely to help in production
+   * @param {Error | string} message The message to log
+   * @param {import('./utilities/log-types.js').LogContext} [context] Additional context
+   * @returns {void}
+   */
+  debug(message, context) {
+    return this.write(LogLevels.debug, message, context);
+  }
+
+  /**
+   * Write a log with the level 'silly' - Information to help resolve complex logic issues
+   * @param {Error | string} message The message to log
+   * @param {import('./utilities/log-types.js').LogContext} [context] Additional context
+   * @returns {void}
+   */
+  silly(message, context) {
+    return this.write(LogLevels.silly, message, context);
+  }
+
+  // =========
+  //  Context
+  // =========
+
+  /**
+   * @param {import('./utilities/log-types.js').LogContext} context The new context
+   * @param {import('./utilities/log-types.js').LogLevel} [level] The log level at which we allow this context
+   * @returns {Logger}
+   */
+  #overrideContext(context, level) {
+    if (
+      typeof level === 'number' &&
+      checkLogLevel(level) === false
+    ) {
+      return this;
+    }
+
+    return new Logger(
+      deepmerge(this.#context, context),
+      {
+        replace: this.#replace,
+        replacers: this.replacers,
+        format: this.#format,
+        write: this.#write,
+      },
+    );
+  }
+
+  /**
+   * Creating a new logger with {context, ...this.context}
+   * @overload
+   * @param {import('./utilities/log-types.js').LogContext} context The new context
+   * @returns {Logger}
+   */
+  /**
+   * Creating a new logger with {context, ...this.context}
+   * @overload
+   * @param {import('./utilities/log-types.js').LogContext} context The new context
+   * @param {import('./utilities/log-types.js').LogLevel} level The log level at which we allow this context
+   * @returns {Logger}
+   */
+  /**
+   * Creating a new logger with {context, ...this.context}
+   * @overload
+   * @param {import('./utilities/log-types.js').LogLevel} level The log level at which we allow this context
+   * @param {import('./utilities/log-types.js').LogContext} context The new context
+   * @returns {Logger}
+   */
+  /**
+   * Creating a new logger with {context, ...this.context}
+   * @param {import('./utilities/log-types.js').LogContext | import('./utilities/log-types.js').LogLevel} contextOrLevel The log level at which we allow this context
+   * @param {import('./utilities/log-types.js').LogLevel | import('./utilities/log-types.js').LogContext} [levelOrContext] The new context
+   * @returns {Logger}
+   */
+  context(contextOrLevel, levelOrContext) {
+    if (
+      levelOrContext instanceof Object &&
+      (
+        contextOrLevel == null ||
+        typeof contextOrLevel === 'number'
+      )
+    ) {
+      return this.#overrideContext(
+        levelOrContext,
+        contextOrLevel,
+      );
+    }
+
+    if (
+      contextOrLevel instanceof Object &&
+      (
+        levelOrContext == null ||
+        typeof levelOrContext === 'number'
+      )
+    ) {
+      return this.#overrideContext(
+        contextOrLevel,
+        levelOrContext,
+      );
+    }
+
+    throw new TypeError('Invalid LogContext in Logger#context()');
+  }
+
+  /**
+   * Get a value from the context by key
+   * @param {string} key The key to get from the context
+   * @returns {unknown}
+   */
+  get(key) {
+    return this.#context[key];
+  }
+
+  /**
+   * Set a value into a new context by key
+   * @param {string} key The key to set
+   * @param {unknown} value The value to set
+   * @returns {Logger}
+   */
+  set(key, value) {
+    return this.context({ [key]: value });
+  }
+
+  /**
+   * Set the channel in the new logger
+   * @param {string} channel The channel name
+   * @returns {Logger}
+   */
+  channel(channel) {
+    return this.set('channel', channel);
+  }
+
+  /**
+   * Set the trail in the new logger
+   * @param {string} [trail] The trail id
+   * @returns {Logger}
+   */
+  trail(trail) {
+    trail ??= Math
+      .random()
+      .toString(16)
+      .slice(2, 10);
+
+    return this.set('trail', trail);
+  }
+}

package/src/replacer.js

@@ -0,0 +1,68 @@
+/* eslint no-invalid-this: 0 */
+
+import Traverse from 'traverse';
+import { nodesToPath } from './utilities/json-path.js';
+
+/**
+ * @template [T=unknown]
+ * @template [O=unknown]
+ * @typedef {Object} Replacer
+ * @property {string} name The name of the replacer
+ * @property {(input: unknown, path?: string[]) => boolean} shouldReplace Check to see if input can be replaced
+ * @property {(input: T, path?: string[]) => O} replace The replace function if shouldReplace returns true
+ * @property {boolean} [stopHere] Should the traverse stop here
+ */
+
+/**
+ * @param {unknown} object The object we're replacing
+ * @param {Replacer[]} replacers The Replacer array to execute
+ * @returns {unknown}
+ */
+export function replace(object, replacers = []) {
+  /** @type {import('traverse').Traverse<unknown>} */
+  const traverse = Traverse(object);
+
+  return traverse.forEach(function (value) {
+    if (value == null) {
+      return this.remove();
+    }
+
+    if (this.circular != null) {
+      return this.update({ $ref: nodesToPath(this.circular.path) });
+    }
+
+    for (const replacer of replacers) {
+      if (replacer.shouldReplace(value, this.path)) {
+        const replaced = replacer.replace(value, this.path);
+
+        if (replaced == null) {
+          return this.remove(replacer.stopHere);
+        }
+
+        return this.update(replaced, replacer.stopHere);
+      }
+    }
+
+    if (typeof value.toJSON === 'function') {
+      try {
+        return this.update(value.toJSON());
+      } catch { }
+    }
+
+    if (
+      value instanceof Object &&
+      Object.getPrototypeOf(value) !== Object.getPrototypeOf({}) &&
+      Object.getPrototypeOf(value) !== Object.getPrototypeOf([])
+    ) {
+      return this.update({ $class: value.constructor.name });
+    }
+
+    if (Object.getPrototypeOf(value).constructor === Object) {
+      this.update({ ...value });
+    }
+
+    if (Object.getPrototypeOf(value).constructor === Array) {
+      this.update([ ...value ]);
+    }
+  });
+}

package/src/replacers/buffers.js

@@ -0,0 +1,18 @@
+/**
+ * @param {Buffer} buffer the buffer to convert to a string
+ * @returns {string}
+ */
+function stringBuffer(buffer) {
+  return buffer.toString('utf8');
+}
+
+/** @type {import('../replacer.js').Replacer<Buffer>} */
+export const BufferReplacer = {
+  name: 'Buffer',
+  stopHere: true,
+  shouldReplace: (input) => input instanceof Buffer,
+  replace: (value) => ({
+    $class: 'Buffer',
+    text: stringBuffer(value),
+  }),
+};

package/src/replacers/error.js

@@ -0,0 +1,40 @@
+import { parseStack } from '../utilities/stacktrace.js';
+
+/**
+ * @typedef {Object} BaseError
+ * @property {string} type The error type or name
+ * @property {string} message The error message
+ * @property {import('../utilities/stacktrace.js').Callsite[]} stack The stacktrace of the error
+ */
+
+/**
+ * @typedef {BaseError & { [k: string]: unknown }} NormalisedError
+ */
+
+/** @type {import('../replacer.js').Replacer<Error, NormalisedError>} */
+export const ErrorReplacer = {
+  name: 'Error',
+  shouldReplace: (input) => input instanceof Error,
+  replace: (value) => {
+    /** @type {Partial<NormalisedError>} */
+    const error = {
+      type: undefined,
+      message: undefined,
+      stack: undefined,
+    };
+
+    for (const key of Object.getOwnPropertyNames(value)) {
+      if (Object.hasOwn(value, key)) {
+        // @ts-ignore - This is always going to be defined
+        error[key] = value[key];
+      }
+    }
+
+    const type = Object.getPrototypeOf(value).constructor.name;
+    error.type ??= type;
+    error.message = `(${type}) ${value.message}`;
+    error.stack = parseStack(value.stack);
+
+    return /** @type {NormalisedError} */ (error);
+  },
+};

package/src/replacers/http-client-request.js

@@ -0,0 +1,18 @@
+import { ClientRequest } from 'node:http';
+
+/** @type {import('../replacer.js').Replacer<ClientRequest>} */
+export const HttpClientRequestReplacer = {
+  name: 'HttpClientRequest',
+  shouldReplace: (input) => input instanceof ClientRequest,
+  replace: (request) => ({
+    method: request.method,
+    protocol: request.protocol,
+    host: request.host ?? request.getHeaders()?.host,
+    url: request.path,
+
+    headers: { ...request.getHeaders() },
+    headersSent: request.headersSent,
+    writableEnded: request.writableEnded,
+    destroyed: request.destroyed,
+  }),
+};

package/src/replacers/http-incoming-message.js

@@ -0,0 +1,26 @@
+import { IncomingMessage } from 'node:http';
+
+/**
+ * @type {import('../replacer.js').Replacer<
+ *    IncomingMessage & {
+ *      hostname?: string,
+ *      originalUrl?: string,
+ *      req?: import('node:http').ClientRequest
+ *    }
+ * >}
+ */
+export const HttpIncomingMessageReplacer = {
+  name: 'HttpIncomingMessage',
+  shouldReplace: (input) => input instanceof IncomingMessage,
+  replace: (input) => ({
+    httpVersion: input.httpVersion,
+    method: input.method,
+    host: input?.hostname ?? input?.req?.host,
+    url: input.originalUrl ?? input?.req?.path ?? input.url,
+
+    headers: input.headers,
+    complete: input.complete,
+    destroyed: input.destroyed,
+  })
+  ,
+};

package/src/replacers/http-server-response.js

@@ -0,0 +1,16 @@
+import { ServerResponse, STATUS_CODES } from 'node:http';
+
+/** @type {import('../replacer.js').Replacer<ServerResponse>} */
+export const HttpServerResponseReplacer = {
+  name: 'HttpServerResponse',
+  shouldReplace: (input) => input instanceof ServerResponse,
+  replace: (response) => ({
+    statusCode: response.statusCode,
+    statusMessage: response.statusMessage ?? STATUS_CODES[response.statusCode],
+
+    headers: response.getHeaders(),
+    headersSent: response.headersSent,
+    writableEnded: response.writableEnded,
+    destroyed: response.destroyed,
+  }),
+};

package/src/replacers/index.js

@@ -0,0 +1,8 @@
+export { BufferReplacer } from './buffers.js';
+export { ErrorReplacer } from './error.js';
+export { HttpClientRequestReplacer } from './http-client-request.js';
+export { HttpIncomingMessageReplacer } from './http-incoming-message.js';
+export { HttpServerResponseReplacer } from './http-server-response.js';
+export { LongStringReplacer } from './long-strings.js';
+export { SecretDelete, SecretObscure } from './secrets.js';
+export { NetSocketReplacer } from './net-socket.js';

package/src/replacers/long-strings.js

@@ -0,0 +1,11 @@
+import { environment } from '../utilities/environment.js';
+
+/** @type {import('../replacer.js').Replacer<string>} */
+export const LongStringReplacer = {
+  name: 'LongString',
+  shouldReplace: (input) => (
+    typeof input === 'string' &&
+    input.length > environment.stringMaxLength
+  ),
+  replace: (value) => `${value.slice(0, environment.stringMaxLength)} ... (truncated)`,
+};

package/src/replacers/net-socket.js

@@ -0,0 +1,21 @@
+import { Socket } from 'node:net';
+
+/** @type {import('../replacer.js').Replacer<Socket>} */
+export const NetSocketReplacer = {
+  name: 'NetSocket',
+  shouldReplace: (input) => input instanceof Socket,
+  replace: (socket) => ({
+    bytesRead: socket.bytesRead,
+    bytesWritten: socket.bytesWritten,
+
+    connecting: socket.connecting,
+    pending: socket.pending,
+    destroyed: socket.destroyed,
+    local: typeof socket.localAddress === 'string' && typeof socket.localPort === 'number'
+      ? `${socket.localAddress}:${socket.localPort}`
+      : null,
+    remote: typeof socket.remoteAddress === 'string' && typeof socket.remotePort === 'number'
+      ? `${socket.remoteAddress}:${socket.remotePort}`
+      : null,
+  }),
+};

package/src/replacers/secrets.js

@@ -0,0 +1,50 @@
+import { environment } from '../utilities/environment.js';
+import { nodesToPath } from '../utilities/json-path.js';
+
+/** @type {import('../replacer.js').Replacer} */
+export const SecretDelete = {
+  name: 'SecretDelete',
+  stopHere: true,
+  shouldReplace: (_, original) => {
+    if (original == null) {
+      return false;
+    }
+
+    const path = original.join('.');
+    for (const filter of environment.secretFilters.blocked) {
+      if (filter.test(path)) {
+        return true;
+      }
+    }
+
+    return false;
+  },
+  replace: () => null,
+};
+
+/** @type {import('../replacer.js').Replacer} */
+export const SecretObscure = {
+  name: 'SecretObscure',
+  stopHere: true,
+  shouldReplace: (_, original) => {
+    if (original == null) {
+      return false;
+    }
+
+    const path = original.join('.');
+    for (const filter of environment.secretFilters.allowed) {
+      if (filter.test(path)) {
+        return true;
+      }
+    }
+
+    return false;
+  },
+  replace: (_, path) => {
+    if (path == null) {
+      return `[secret]`;
+    }
+
+    return `[secret ${nodesToPath(path)}]`;
+  },
+};

package/src/stdout-write.js

@@ -0,0 +1,7 @@
+/**
+ * @param {string} output What should be written to stdout
+ * @returns {void}
+ */
+export function stdoutWrite(output) {
+  console.info(output);
+}