resources/src/mediawiki.experiments.js

   1 ( function () {
   2
   3         var CONTROL_BUCKET = 'control',
   4                 MAX_INT32_UNSIGNED = 4294967295;
   5
   6         /**
   7          * An implementation of Jenkins' one-at-a-time hash.
   8          *
   9          * @see https://en.wikipedia.org/wiki/Jenkins_hash_function
  10          *
  11          * @param {string} string String to hash
  12          * @return {number} The hash as a 32-bit unsigned integer
  13          * @ignore
  14          *
  15          * @author Ori Livneh <ori@wikimedia.org>
  16          * @see https://jsbin.com/kejewi/4/watch?js,console
  17          */
  18         function hashString( string ) {
  19                 /* eslint-disable no-bitwise */
  20                 var hash = 0,
  21                         i = string.length;
  22
  23                 while ( i-- ) {
  24                         hash += string.charCodeAt( i );
  25                         hash += ( hash << 10 );
  26                         hash ^= ( hash >> 6 );
  27                 }
  28                 hash += ( hash << 3 );
  29                 hash ^= ( hash >> 11 );
  30                 hash += ( hash << 15 );
  31
  32                 return hash >>> 0;
  33                 /* eslint-enable no-bitwise */
  34         }
  35
  36         /**
  37          * Provides an API for bucketing users in experiments.
  38          *
  39          * @class mw.experiments
  40          * @singleton
  41          */
  42         mw.experiments = {
  43
  44                 /**
  45                  * Gets the bucket for the experiment given the token.
  46                  *
  47                  * The name of the experiment and the token are hashed. The hash is converted
  48                  * to a number which is then used to get a bucket.
  49                  *
  50                  * Consider the following experiment specification:
  51                  *
  52                  * ```
  53                  * {
  54                  *   name: 'My first experiment',
  55                  *   enabled: true,
  56                  *   buckets: {
  57                  *     control: 0.5
  58                  *     A: 0.25,
  59                  *     B: 0.25
  60                  *   }
  61                  * }
  62                  * ```
  63                  *
  64                  * The experiment has three buckets: control, A, and B. The user has a 50%
  65                  * chance of being assigned to the control bucket, and a 25% chance of being
  66                  * assigned to either the A or B buckets. If the experiment were disabled,
  67                  * then the user would always be assigned to the control bucket.
  68                  *
  69                  * @param {Object} experiment
  70                  * @param {string} experiment.name The name of the experiment
  71                  * @param {boolean} experiment.enabled Whether or not the experiment is
  72                  *  enabled. If the experiment is disabled, then the user is always assigned
  73                  *  to the control bucket
  74                  * @param {Object} experiment.buckets A map of bucket name to probability
  75                  *  that the user will be assigned to that bucket
  76                  * @param {string} token A token that uniquely identifies the user for the
  77                  *  duration of the experiment
  78                  * @return {string} The bucket
  79                  */
  80                 getBucket: function ( experiment, token ) {
  81                         var buckets = experiment.buckets,
  82                                 key,
  83                                 range = 0,
  84                                 hash,
  85                                 max,
  86                                 acc = 0;
  87
  88                         if ( !experiment.enabled || $.isEmptyObject( experiment.buckets ) ) {
  89                                 return CONTROL_BUCKET;
  90                         }
  91
  92                         for ( key in buckets ) {
  93                                 range += buckets[ key ];
  94                         }
  95
  96                         hash = hashString( experiment.name + ':' + token );
  97                         max = ( hash / MAX_INT32_UNSIGNED ) * range;
  98
  99                         for ( key in buckets ) {
 100                                 acc += buckets[ key ];
 101
 102                                 if ( max <= acc ) {
 103                                         return key;
 104                                 }
 105                         }
 106                 }
 107         };
 108
 109 }() );