[squeep-api-dingus] / lib / common.js

/* eslint-disable security/detect-object-injection */
'use strict';

/**
 * Utility and miscellaneous functions.
 */

const path = require('path');
const crypto = require('crypto');
const uuid = require('uuid');
const Enum = require('./enum');

/**
 * @callback ScopeFn
 * @param {String} scope
 * @returns {String}
 */
/**
 * Return a function which prefixes a provided scope with the most-
 * relevant part of the filename, for use in logging.
 * @param {String} filename
 * @returns {ScopeFn}
 */
const fileScope = (filename) => {
  let fScope = path.basename(filename, '.js');
  if (fScope === 'index') {
    fScope = path.basename(path.dirname(filename));
  }
  return (scope) => `${fScope}:${scope}`;
};

/**
 * Simple ETag from data.
 * @param {String} filePath (currently unused)
 * @param {fs.Stats} fileStat
 * @param {crypto.BinaryLike} fileData content
 * @returns {String}
 */
const generateETag = (_filePath, fileStat, fileData) => {
  const hash = crypto.createHash('sha256');
  if (fileStat?.mtimeMs) {
    hash.update(fileStat.mtimeMs.toString());
  }
  hash.update(fileData);
  const digest = hash.digest('base64').replace('=', '');
  return `"${digest}"`;
};

/**
 * Access property with default.
 * @param {Object} obj
 * @param {String} prop
 * @param {*} def default value if prop does not exist for obj
 * @return {*}
 */
const get = (obj, prop, def) => obj && prop && (prop in obj) ? obj[prop] : def;

/**
 * @param {http.ClientRequest} req 
 * @param {http.ServerResponse} res 
 * @param {Object} ctx 
 * @deprecated after v1.2.5 (integrated into logger module)
 */
const handlerLogData = (req, res, ctx) => ({
  req: requestLogData(req),
  res: responseLogData(res),
  ctx,
});

/**
 * Determine whether a client has already requested a resource,
 * based on If-Modified-Since and If-None-Match headers.
 * @param {http.ClientRequest} req 
 * @param {Number} modifiedTimeMs 
 * @param {String} eTag 
 * @returns {Boolean}
 */
const isClientCached = (req, modifiedTimeMs, eTag) => {
  let clientCached = false;

  const ifModifiedSince = req.getHeader(Enum.Header.IfModifiedSince);
  if (ifModifiedSince) {
    const ifModifiedSinceMs = Date.parse(ifModifiedSince);
    if (modifiedTimeMs < ifModifiedSinceMs) {
      clientCached = true;
    }
  }

  const ifNoneMatch = req.getHeader(Enum.Header.IfNoneMatch);
  if (ifNoneMatch) {
    const matches = ifNoneMatch.split(',').map((m) => m.trim());
    if (matches.includes(eTag)
    ||  (ifNoneMatch === '*' && eTag)) {
      clientCached = true;
    } else {
      // If if-none-matched header is present, it takes precedence over modified-since.
      clientCached = false;
    }
  }

  return clientCached;
};

/**
 * Shallow merge for enums, to be called by derived constructor.
 * Expects only one-level deep, is not recursive!
 * @param {Object} origEnum
 * @param {Object} additionalEnum
 * @returns {Object}
 */
const mergeEnum = (origEnum, additionalEnum) => {
  for (const e of Object.keys(additionalEnum)) {
    if (typeof additionalEnum[e] === 'object') {
      if (! (e in origEnum)) {
        origEnum[e] = {};
      }
      Object.assign(origEnum[e], additionalEnum[e]);
    } else {
      origEnum[e] = additionalEnum[e];
    }
  }
  return origEnum;
};

/**
 * Isolate the general category of an http status code.
 * @param {Number} statusCode
 * @returns {Number}
 */
const httpStatusCodeClass = (statusCode) => Math.floor(statusCode / 100);

const _isObject = (obj) => obj && typeof obj === 'object';
const _isArray = (obj) => Array.isArray(obj);
/**
 * Return a new object with all objects combined, later properties taking precedence.
 * @param  {...Object} objects
 * @returns {Object}
 */
const mergeDeep = (...objects) => {
  return objects.reduce((acc, obj) => {
    const objectProperties = [...Object.getOwnPropertyNames(obj), ...Object.getOwnPropertySymbols(obj)];
    objectProperties.forEach((k) => {
      const aVal = acc[k];
      const oVal = obj[k];
      if (_isArray(oVal)) {
        acc[k] = (_isArray(aVal) ? aVal : []).concat(oVal);
      } else if (_isObject(oVal)) {
        acc[k] = mergeDeep(_isObject(aVal) ? aVal : {}, oVal);
      } else {
        acc[k] = oVal;
      }
    });
    return acc;
  }, {});
};


/**
 * Return a new object with selected props.
 * @param {Object} obj
 * @param {String[]} props
 * @returns {Object}
 */
const pick = (obj, props) => {
  const picked = {};
  props.forEach((prop) => {
    if (prop in obj) {
      picked[prop] = obj[prop];
    }
  });
  return picked;
};

/**
 * Return a subset of a request object, suitable for logging.
 * Obscures sensitive header values.
 * @param {http.ClientRequest} req 
 * @deprecated after v1.2.5 (integrated into logger module)
 */
const requestLogData = (req) => {
  const data = pick(req, [
    'method',
    'url',
    'httpVersion',
    'headers',
    'trailers',
  ]);
  scrubHeaderObject(data);
  return data;
};


/**
 * Remove sensitive header data.
 * @param {Object} data
 * @param {Object} data.headers
 * @deprecated after v1.2.5 (integrated into logger module)
 */
const scrubHeaderObject = (data) => {
  if (data?.headers && 'authorization' in data.headers) {
    data.headers = Object.assign({}, data.headers, {
      authorization: obscureAuthorizationHeader(data.headers['authorization']),
    });
  }
};


/**
 * Hide sensitive part of an Authorization header.
 * @param {String} authHeader
 * @returns {String}
 * @deprecated after v1.2.5 (integrated into logger module)
 */
const obscureAuthorizationHeader = (authHeader) => {
  if (!authHeader) {
    return authHeader;
  }
  const space = authHeader.indexOf(' ');
  // This blurs entire string if no space found, because -1.
  return authHeader.slice(0, space + 1) + '*'.repeat(authHeader.length - (space + 1));
};


/**
 * Return a subset of a response object, suitable for logging.
 * @param {http.ServerResponse} res 
 * @deprecated after v1.2.5 (integrated into logger module)
 */
const responseLogData = (res) => {
  const response = pick(res, [
    'statusCode',
    'statusMessage',
  ]);
  response.headers = res.getHeaders();
  return response;
};


/**
 * Store all properties in defaultOptions on target from either options or defaultOptions.
 * @param {Object} target 
 * @param {Object} defaultOptions 
 * @param {Object} options 
 */
const setOptions = (target, defaultOptions, options) => {
  Object.assign(target, defaultOptions, pick(options, Object.keys(defaultOptions)));
};

/**
 * Return a two-item list of src, split at first delimiter encountered.
 * @param {String} src 
 * @param {String} delimiter 
 * @param {String} fill trailing stand-in if no delimiter in src
 */
const splitFirst = (src, delimiter, fill) => {
  const idx = src.indexOf(delimiter);
  if (idx >= 0) {
    return [ src.slice(0, idx), src.slice(idx + 1) ];
  } else {
    return [ src, fill ];
  }
};

/**
 * Generate a new request identifier, a time/host-based uuid.
 * @returns {String}
 */
const requestId = () => {
  return uuid.v1();
};

/**
 * Do nothing.
 */
const nop = () => { /**/ };

/**
 * A logger object which does nothing.
 */
const nullLogger = {
  error: nop,
  warn: nop,
  info: nop,
  log: nop,
  debug: nop,
};

/**
 * Populates any absent logger level functions on a logger object.
 * @param {Object} logger
 * @returns {Object}
 * @deprecated after v1.2.9 (this is not our responsibility)
 */
const ensureLoggerLevels = (logger = {}) => {
  for (const level in nullLogger) {
    if (! (level in logger)) {
      logger[level] = nullLogger[level];
    }
  }
  return logger;
};

/**
 * Merges folded header lines
 * @param {String[]} lines
 * @returns {String}
 */
const unfoldHeaderLines = (lines) => {
  const foldedLineRE = /^(\t| +)(.*)$/;
  if (lines) {
    lines.reduceRight((_, line, idx) => { // NOSONAR
      const result = foldedLineRE.exec(line);
      if (result && idx) {
        const prevIdx = idx - 1;
        const mergedLine = `${lines[prevIdx]} ${result[2]}`;
        lines.splice(prevIdx, 2, mergedLine);
        return mergedLine;
      }
    }, null);
  }
  return lines;
};

module.exports = {
  ensureLoggerLevels,
  fileScope,
  generateETag,
  get,
  handlerLogData,
  httpStatusCodeClass,
  isClientCached,
  mergeDeep,
  mergeEnum,
  nop,
  nullLogger,
  obscureAuthorizationHeader,
  pick,
  requestId,
  requestLogData,
  responseLogData,
  scrubHeaderObject,
  setOptions,
  splitFirst,
  unfoldHeaderLines,
};