update devDependencies, add jsdoc lint, fix lint issues

[squeep-api-dingus] / lib / content-negotiation.js

'use strict';

const common = require('./common');
const Enum = require('./enum');


// A weight value smaller than the allowed resolution, for minute wildcard de-preferencing.
const WeightIota = 0.0001;

/**
 * Methods for negotiating content types.
 */
class ContentNegotiation {

  /**
   * Convert accept clause string to object.
   * Adjust weight based on wildcards, to prefer literal matches.
   * @param {string} clause portion of an accept header
   * @returns {object|undefined} details of clause
   */
  static _unpackAcceptClause(clause) {
    let params = clause.split(';');
    const type = params.shift().trim();
    if (type) {
      let weight = 1.0;
      params = params.reduce((acc, param) => {
        const [p, v] = common.splitFirst(param, '=').map((x) => x?.trim());
        if (p && v) {
          if (p === 'q') {
            weight = Number(v);
            // Enforce max precision from spec, so that we can...
            weight = Number(weight.toFixed(3));
            // De-tune the quality slightly for wildcards.
            const blur = (type.split('*').length - 1) * WeightIota;
            if (weight) {
              weight -= blur;
            }
          } else {
            // eslint-disable-next-line security/detect-object-injection
            acc[p] = v;
          }
        }
        return acc;
      }, {});
      return { type, weight, params };
    }
  }

  /**
   * Split an accept field into clauses, return list of clauses sorted by heaviest weights first.
   * @param {string} acceptHeader collection of accept clauses
   * @returns {object[]} array of clause details sorted by desirability
   */
  static _acceptClauses(acceptHeader) {
    const clauses = (acceptHeader||'').split(',')
      .map((clause) => ContentNegotiation._unpackAcceptClause(clause))
      .filter((clause) => clause);
    return clauses.sort((a, b) => b.weight - a.weight);
  }

  /**
   * Check if an Accept-able Content-Type matches a fixed Content-Type.
   * (Allows for '*' fields in Accept-able type.)
   * @param {string} acceptableType explicit or wildcard
   * @param {string} fixedType explicit
   * @returns {boolean} matches
   */
  static _matchType(acceptableType, fixedType) {
    acceptableType = common.splitFirst(acceptableType, '/', '*');
    fixedType = common.splitFirst(fixedType, '/', '*');
    for (let i = 0; i < acceptableType.length; i++) {
      // eslint-disable-next-line security/detect-object-injection
      const v = acceptableType[i];
      // eslint-disable-next-line security/detect-object-injection
      const f = fixedType[i];
      if (v !== f && v !== '*') {
        return false;
      }
    }
    return true;
  }

  /**
   * Return the best match between available and acceptable types.
   * @param {string[]} acceptableTypes available types
   * @param {string} acceptHeader accept header
   * @returns {string|undefined} best matched type
   */
  static accept(acceptableTypes, acceptHeader) {
    const validTypesQuality = {};
    if (!acceptHeader) {
      return acceptableTypes[0];
    }
    // For each type offered in the header, from heaviest to lightest...
    ContentNegotiation._acceptClauses(acceptHeader).forEach((a) => {
      // Consider each supported type...
      acceptableTypes.forEach((t) => {
        // Remember the heaviest weighting if it matches.
        if (ContentNegotiation._matchType(a.type, t)
        // eslint-disable-next-line security/detect-object-injection
        &&  (!(t in validTypesQuality) || validTypesQuality[t] < a.weight)) {
          // eslint-disable-next-line security/detect-object-injection
          validTypesQuality[t] = a.weight;
        }
      });
    });
    return Object.keys(validTypesQuality).reduce((acc, cur) => {
      // eslint-disable-next-line security/detect-object-injection
      if (acc === undefined && validTypesQuality[cur] !== 0.0) {
        return cur;
      }
      // istanbul ignore next
      // eslint-disable-next-line security/detect-object-injection
      return validTypesQuality[acc] < validTypesQuality[cur] ? cur : acc;
    }, undefined);
  }


  /**
   * Return all viable matches between acceptable and requested encodings, ordered by highest preference first.
   * TODO: sort equal q-values by server-preference rather than header order
   * @param {string[]} acceptableEncodings e.g. ['br', 'gzip'] in order of server preference
   * @param {string} acceptHeader encoding header
   * @returns {string[]} preferred encoding
   */
  static preferred(acceptableEncodings, acceptHeader) {
    const Identity = Enum.EncodingType.Identity;
    const Any = '*';

    // Don't munge caller's list.
    acceptableEncodings = [...acceptableEncodings];

    // Server is always capable of identity encoding.
    if (!(acceptableEncodings.includes(Identity))) {
      acceptableEncodings.push(Identity);
    }

    const acceptClauses = ContentNegotiation._acceptClauses(acceptHeader);

    // Add identity as fallback clause if an Any type was not explicitly mentioned.
    const acceptTypes = acceptClauses.map((enc) => enc.type);
    if (!(acceptTypes.includes(Any)) && !(acceptTypes.includes(Identity))) {
      acceptClauses.push({
        type: Identity,
        weight: WeightIota,
        params: [],
      });
    }

    // Explicitly forbidden encodings will not be considered.
    const forbidden = acceptClauses.filter((enc) => enc.weight == 0).map((enc) => enc.type);

    acceptableEncodings = acceptableEncodings.filter((enc) => {
      // If * is forbidden, don't allow identity encoding.
      const fallbackIsForbidden = forbidden.includes(Any) && enc === Identity && !acceptTypes.includes(Identity);

      const typeIsForbidden = forbidden.includes(enc.type);
      return !typeIsForbidden && !fallbackIsForbidden;
    });

    // Strip forbidden and unsupported from working set.
    const allowedClauses = acceptClauses.filter((enc) => {
      const isAllowed = enc.weight > 0;
      const isSupported = enc.type === Any || acceptableEncodings.includes(enc.type);
      return isAllowed && isSupported;
    });

    // Only the types.
    return allowedClauses.map((enc) => enc.type);
  }

}

module.exports = ContentNegotiation;