Merge branch 'v2.1-dev'

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

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

/**
 * Utility and miscellaneous functions.
 */

const crypto = require('node:crypto');
const uuid = require('uuid');
const Enum = require('./enum');
const { fileScope } = require('@squeep/log-helper');

/**
 * 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;

/**
 * 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;
};

/**
 * 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();
};

/**
 * 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;
};

/**
 * Adds a new cookie.
 * @param {http.ServerResponse} res
 * @param {String} name
 * @param {String} value
 * @param {Object=} opt
 * @param {String=} opt.domain
 * @param {Date=} opt.expires
 * @param {Boolean=} opt.httpOnly
 * @param {Number=} opt.maxAge
 * @param {String=} opt.path
 * @param {String=} opt.sameSite
 * @param {Boolean=} opt.secure
 */
function addCookie(res, name, value, opt = {}) {
  const options = {
    domain: undefined,
    expires: undefined,
    httpOnly: false,
    maxAge: undefined,
    path: undefined,
    sameSite: undefined,
    secure: false,
    ...opt,
  };
  // TODO: validate name, value
  const cookieParts = [
    `${name}=${value}`,
  ];
  if (options.domain) {
    cookieParts.push(`Domain=${options.domain}`);
  }
  if (options.expires) {
    if (!(options.expires instanceof Date)) {
      throw new TypeError('cookie expires must be Date');
    }
    cookieParts.push(`Expires=${options.expires.toUTCString()}`);
  }
  if (options.httpOnly) {
    cookieParts.push('HttpOnly');
  }
  if (options.maxAge) {
    cookieParts.push(`Max-Age=${options.maxAge}`);
  }
  if (options.path) {
    cookieParts.push(`Path=${options.path}`);
  }
  if (options.sameSite) {
    if (!(['Strict', 'Lax', 'None'].includes(options.sameSite))) {
      throw new RangeError('cookie sameSite value not valid');
    }
    cookieParts.push(`SameSite=${options.sameSite}`);
  }
  if (options.secure) {
    cookieParts.push('Secure');
  }
  res.appendHeader(Enum.Header.SetCookie, cookieParts.join('; '));
}


module.exports = {
  addCookie,
  fileScope,
  generateETag,
  get,
  httpStatusCodeClass,
  isClientCached,
  mergeDeep,
  mergeEnum,
  pick,
  requestId,
  setOptions,
  splitFirst,
  unfoldHeaderLines,
};