abby-client/lib/client.js

const murmurhash = require('murmurhash');
const cookie = require('cookie');
const url = require('url');
const uuidv4 = require('uuid/v4');

const pkg = require('../package.json');
const sync = require('./sync');
const expressionEvaluator = require('expression-evaluator');

const Logger = require('./logger');

const HASH_SEED = 1;
const MAX_HASH_VALUE = Math.pow(2, 32);
const MAX_TRAFFIC_VALUE = 10000;
const COOKIE_NAME = 'ABBY_EXPERIMENTS';
const COOKIE_SESSION = 'ABBY_SESSION';
const COOKIE_MAX_AGE = 60 * 60 * 24 * 7 * 52; // 1year in seconds
const COOKIE_SESSION_MAX_AGE = 60 * 45;// 45minutes in seconds;
const CONTROL_VARIANT = 'control';
const SEPARATOR = '|';

// region typedef

/**
 * @typedef {Object} Synchroniser
 * @param {string} lastSync 
 * @param {Array.<Experiment>} data
 */

/**
 * @typedef {Object} Experiment
 * @property {Number} id
 * @property {String} name
 * @property {Boolean} active
 * @property {Array<Tag>} tags
 * @property {String} testType
 * @property {Object} targeting
 * @property {Object} audence
 * @property {Array.<Variant>} variants
 * @property {boolean?} rebalance
 */

/**
 * @typedef {Object} Variant
 * @property {String} name
 * @property {String} code
 * @property {Object.<String,String>} properties
 * 
 */

/**
 * @typedef {Object} Tag
 * @property {String} name
 * @property {String} code
 */

/**
 * @typedef {Object} Configs
 * @property {String} API_ENDPOINT
 * @property {String?} tags
 * @property {Object?} Logger
 */

/**
 * @typedef {Object} Logger
 * @function {Void} log
 * @function {Void} debug
 * @function {Void} error
 */

/**
* @typedef {Object} UserExperiment
* @property {string} experimentCode
* @property {Object} experiment
* @property {String} experiment.code
* @property {Array.<string>} experiment.tags
* @property {string} variantCode
* @property {Object} variant
* @property {String} variant.code
* @property {Object?} variant.properties
* @property {boolean} variant.original
* @property {string?} hash
* @property {boolean} paused
*
*/

/**
 * @typedef {Object} UserExperimentFilter
 * @property {Array.<String>?} tags
 */
// endregion


/**
 * will return the current hash or generated a new hash if has is not present
 * 
 * @param {string} experimentCode
 * @param {UserExperiment?} experiment
 * @returns {string}
 */
function experimentHash(experimentCode, experiment) {
    return experiment && isFinite(parseInt(experiment.hash))
        ? experiment.hash
        : generateHash(`${uuidv4()}_${experimentCode}`);
}

/**
* Helper function to generate bucket value in half-closed interval [0, MAX_TRAFFIC_VALUE)
* @param  {string} experimentID String value for experiment ID
* @return {number} the generated hash value
*/
function generateHash(experimentID) {
    let hashValue = murmurhash.v3(experimentID, HASH_SEED),
        ratio = hashValue / MAX_HASH_VALUE;
    return parseInt(ratio * MAX_TRAFFIC_VALUE, 10);
}

/**
  * Helper function to generate bucket value in half-closed interval [0, MAX_TRAFFIC_VALUE)
  * @param  {Object} Experiment Object value for experiment
  * @param  {number} hash number value of generated hash
  * @return {string} the id of available variant
  */
function getVariantCode(experiment, hash, currentExperiment) {
    var percentage = Math.floor((hash * 100) / MAX_TRAFFIC_VALUE),
        variants = experiment.variants.filter(variant => {
            let { start, end } = variant.range;
            return percentage >= start && percentage <= end;
        });

    if (variants.length === 0) {
        return CONTROL_VARIANT;
    } else if (!currentExperiment || currentExperiment.variantCode === CONTROL_VARIANT) {
        return variants[0].code;
    } else {
        return currentExperiment.variantCode;
    }
}

/**
 * will return empty object if variation is not found
 * 
 * @param {Experiment} experiment 
 * @param {string} variantCode 
 * @returns {Variation}
 */
function getVariant(experiment, variantCode) {
    let variants = experiment.variants;
    if (Array.isArray(variants)) {
        for (let i = 0, ii = variants.length; i < ii; i++) {
            if (variants[i].code === variantCode) {
                return variants[i];
            }
        }
    }
    return null;
}

/**
 * will add only the active non-paused experiments to the request
 * @param {http.ClientRequest} req 
 * @param {Array.<UserExperiment>} experiments 
 */
function assignToRequest(req, experiments) {
    req.experiments = {};
    for (let experiment of experiments) {
        if (experiment.paused) {
            continue;
        }
        req.experiments[experiment.experimentCode] = experiment;
    }
}


/**
 *  returns ths ABBY_EXPERIMENTS cookie value which expires after 1 YEAR
  * @param  {Object} http.ServerResponse object value for http response
  * @param  {Array<UserExperiment>} experiments array list of cookie data
  * @return {Void}
  */
function experimentsCookieValue(experiments) {
    let path = '/',
        maxAge = COOKIE_MAX_AGE,
        expires = new Date(Date.now() + maxAge);

    let value = experiments
        .map(item => `${item.experimentCode}${SEPARATOR}${item.variantCode}${SEPARATOR}${item.hash}`)
        .join(',');

    return cookie.serialize(COOKIE_NAME, value,
        {
            path,
            maxAge,
            expires,
            secure: true
        });
}

/**
 * sets X-Abby-Version header
 * @param {http.ServerResponse} res 
 * @param {Object} pkg 
 * @param {Synchroniser} synchroniser
 */
function assignVersion(res, pk, synchroniser) {
    if (typeof pkg.version === 'string') {
        res.setHeader('X-Abby-Version', pkg.version);
    }
    if (typeof synchroniser.lastSync === 'string') {
        res.setHeader('X-Abby-Sync', synchroniser.lastSync);
    }
}

/**
 *  returns the ABBY_SESSION cookie value
  * @param  {http.ServerResponse} object value for http response
  * @param {boolean} newSession
  * @param  {string} sessionId
  * @return {Void}
  */
function sessionCookieValue(newSession, sessionId) {
    let path = '/',
        maxAge = COOKIE_SESSION_MAX_AGE,
        expires = new Date(Date.now() + (maxAge * 1000));
    return cookie.serialize(COOKIE_SESSION, newSession ? uuidv4() : sessionId, {
        path,
        maxAge,
        expires,
        secure: true
    });
}

/**
  * @param  {http.ClientRequest} req value for http response
  * @return {Void}
  */
function getCookieData(req) {
    return req.headers.cookie ? cookie.parse(req.headers.cookie) : {};
}
/**
 * 
 * @param {string} data 
 * @returns {Object.<string, UserExperiment>}
 */
function getCurrentExperiments(data) {

    if (typeof data !== 'string') {
        return {};
    }
    let experiments = {};
    data.split(',').forEach(value => {
        let [experimentCode, variantCode, hash] = value.split(SEPARATOR);
        experiments[experimentCode] = { experimentCode, variantCode, hash };
    });
    return experiments;
}

/**
 * 
 * @param {http.ClientRequest} req 
 * @returns {Object.<string, string>}
 */
function getForcedExperimentsFromQuery(req) {
    const { query: { abby_experiment: query } } = url.parse(req.url, true);

    if (typeof query !== 'string') {
        return {};
    }

    let experiments = {};
    query.split(',').forEach(value => {
        let [experimentCode, variantCode] = value.split(SEPARATOR);
        experiments[experimentCode] = variantCode;
    });
    return experiments;
}

/**
 * 
 * @param {string} sessionId 
 */
function validateSession(sessionId) {
    return typeof sessionId !== 'string' || sessionId.trim().length === 0;
}


/**
 * 
 * @param {Experiment} experiment 
 * @param {Variant} variant 
 * @param {string} hash
 * @returns {UserExperiment}
 * 
 */
function buildUserExperiment(experiment, variant, hash) {
    return {
        experimentCode: experiment.code,
        experiment: {
            code: experiment.code,
            tags: experiment.tags.map(tag => tag.name),
            audience: experiment.audience,
            targeting: experiment.targeting
        },
        variantCode: variant.code,
        variant: {
            code: variant.code,
            properties: Object.assign({}, variant.properties),
            original: variant.original
        },
        hash,
        paused: !experiment.active
    };
}

/**
 * 
 * @param {Array.<UserExperiment>} experiments 
 * @param {UserExperimentFilter} filter 
 */
function filterUserExperiments(experiments, filter = {}) {
    let result = experiments;
    if (filter.tags) {
        result = result.filter(({ experiment }) =>
            filter.tags.every(tag => experiment.tags.find(value => value === tag))
        );
    }
    return result;
}

/**
 * 
 * returns all targetedExperiments which do not have original variant
 * original variant will not be used when implementing experiments
 * because original variants are the original view of the website/channel
 * 
 * @param {Array.<UserExperiment>} userExperiments
 * @param {Object} props
 * @param {UserExperimentFilter?} filter
 */
function getTargetedExperiments(userExperiments, props, filter = {}) {
    return filterUserExperiments(userExperiments, filter)
        .filter(({ experiment, variant }) => !variant.original && expressionEvaluator.evaluate(experiment.targeting, props));
}

/**
 * sets the cookie on the response and preserves any 
 * existing cookies that do not start with ABBY_
 * adds all experiments also the paused/non-active user experiments
 * 
 * @param {http.ServerResponse} res 
 * @param {Array.<String>} values 
 */
function assignCookies(res, ...values) {
    let cookies = [],
        cookieHeader = res.getHeader('Set-Cookie');

    if (typeof cookieHeader !== 'undefined' && cookieHeader !== null) {
        if (Array.isArray(cookieHeader)) {
            cookies = cookie.concat(cookieHeader);
        } else {
            cookies.push(cookieHeader);
        }
    }
    // remove all current abby cookies
    cookies = cookies.filter(cookie => !cookie.startsWith('ABBY_'));
    // push the new values
    cookies = cookies.concat(values);
    res.setHeader('Set-Cookie', cookies);
}

/**
 * 
 * @param {Experiment} experiment 
 * @param {Array<String>?} rebalance optional list of experimentcodes to be rebalance
 * @returns {Boolean}
 */
function rebalanceExperiment(experiment, rebalance = []) {
    if (experiment.rebalance) {
        return true;
    }
    if (Array.isArray(rebalance)) {
        return rebalance.find(code => code === experiment.code);
    }
    return false;
}

function abby(logger, synchroniser, configs) {

    /**
 * 
 * when the user already has a session cookie set than only change the forced experiments
 * otherwise validate the current experiments and migrate to different variant if needed
 * 
 * @param {http.ClientRequest} req 
 * @param {http.ServerResponse} res 
 * @param {Object?} props
 * @param {Object?} config
 * @param {Array<String>} config.rebalance 
 */
    function handle(req, res, props = {}, config = {}) {
        let cookies = getCookieData(req),
            sessionCookie = cookies[COOKIE_SESSION],
            newSession = validateSession(sessionCookie),
            currentExperiments = getCurrentExperiments(cookies[COOKIE_NAME]),
            forcedExperiments = getForcedExperimentsFromQuery(req);


        let /**Object.<string, UserExperiment>*/experimentMap = {};
        for (let /**Experiment*/ experiment of /**Array.<Experiment>*/synchroniser.data) {
            let experimentCode = experiment.code,
                hash,
                variantCode,
                /**
                 * @type {UserExperiment}
                 */
                currentExperiment = currentExperiments[experimentCode],
                forced = forcedExperiments[experimentCode];


            if (forced) {
                hash = currentExperiment ? currentExperiment.hash : experimentHash(experimentCode, currentExperiment);
                variantCode = forced;
            } else if (newSession) {
                if (!expressionEvaluator.evaluate(experiment.audience, props)) {
                    continue;
                }
                hash = experimentHash(experimentCode, currentExperiment);
                variantCode = getVariantCode(experiment, hash, currentExperiment);
            } else if (currentExperiment) {
                hash = currentExperiment.hash;
                if (rebalanceExperiment(experiment, config.rebalance)) {
                    variantCode = getVariantCode(experiment, hash, null);
                } else {
                    variantCode = currentExperiment.variantCode;
                }
            }

            let variant = getVariant(experiment, variantCode);
            if (variant === null) {
                continue;
            }

            experimentMap[experimentCode] = buildUserExperiment(experiment, variant, hash);
        }
        let userExperiments = Object.values(experimentMap);
        assignToRequest(req, userExperiments);
        assignVersion(res, pkg, synchroniser);
        // order is important otherwise experiments might not get assigned
        assignCookies(res, experimentsCookieValue(userExperiments), sessionCookieValue(newSession, sessionCookie));
    }
    handle.ready = () => synchroniser.load(configs);
    handle.getTargetedExperiments = getTargetedExperiments;
    return handle;
}

module.exports = function (/**Configs*/configs, /**Synchroniser?*/synchroniser = sync) {
    let { tags, apiEndpoint, logger } = Object.assign({}, configs);
    let logger_ = Logger.instance(logger ? logger : console);

    if (!tags) {
        logger_.error(new Error('You should pass <tags>'));
        return;
    }
    if (!apiEndpoint) {
        logger_.error(new Error('You should pass <apiEndpoint>'));
        return;
    }
    return abby(logger_, synchroniser, configs);
};