resources/src/mediawiki.cookie/index.js

   1 'use strict';
   2
   3 const config = require( './config.json' ),
   4         jar = require( './jar.js' );
   5 let defaults = {
   6         prefix: config.prefix,
   7         domain: config.domain,
   8         path: config.path,
   9         expires: config.expires,
  10         secure: false,
  11         sameSite: ''
  12 };
  13
  14 // define jQuery Cookie methods
  15 require( './jquery.js' );
  16
  17 /**
  18  * Manage cookies in a way that is syntactically and functionally similar
  19  * to the `WebRequest#getCookie` and `WebResponse#setcookie` methods in PHP.
  20  *
  21  * @author Sam Smith <samsmith@wikimedia.org>
  22  * @author Matthew Flaschen <mflaschen@wikimedia.org>
  23  *
  24  * @module mediawiki.cookie
  25  * @example
  26  * mw.loader.using( 'mediawiki.cookie' ).then( () => {
  27  *   mw.cookie.set('hello', 'world' );
  28  * })
  29  */
  30 mw.cookie = {
  31         /**
  32          * Set or delete a cookie.
  33          *
  34          * **Note:** If explicitly passing `null` or `undefined` for an options key,
  35          * that will override the default. This is natural in JavaScript, but noted
  36          * here because it is contrary to MediaWiki's `WebResponse#setcookie()` method
  37          * in PHP.
  38          *
  39          * When using this for persistent storage of identifiers (e.g. for tracking
  40          * sessions), be aware that persistence may vary slightly across browsers and
  41          * browser versions, and can be affected by a number of factors such as
  42          * storage limits (cookie eviction) and session restore features.
  43          *
  44          * Without an expiry, this creates a session cookie. In a browser, session cookies persist
  45          * for the lifetime of the browser *process*. Including across tabs, page views, and windows,
  46          * until the browser itself is *fully* closed, or until the browser clears all storage for
  47          * a given website. An exception to this is if the user evokes a "restore previous
  48          * session" feature that some browsers have.
  49          *
  50          * @param {string} key
  51          * @param {string|null} value Value of cookie. If `value` is `null` then this method will
  52          *   instead remove a cookie by name of `key`.
  53          * @param {module:mediawiki.cookie~CookieOptions|Date|number} [options] Options object, or expiry date
  54          * @memberof module:mediawiki.cookie
  55          */
  56
  57         set: function ( key, value, options ) {
  58                 // The 'options' parameter may be a shortcut for the expiry.
  59                 if ( arguments.length > 2 && ( !options || options instanceof Date || typeof options === 'number' ) ) {
  60                         options = { expires: options };
  61                 }
  62                 // Apply defaults
  63                 options = Object.assign( {}, defaults, options );
  64
  65                 // Don't pass invalid option to jar.cookie
  66                 const prefix = options.prefix;
  67                 delete options.prefix;
  68
  69                 if ( !options.expires ) {
  70                         // Session cookie (null or zero)
  71                         // Normalize to absent (undefined) for jar.cookie.
  72                         delete options.expires;
  73                 } else if ( typeof options.expires === 'number' ) {
  74                         // Lifetime in seconds
  75                         const date = new Date();
  76                         date.setTime( Number( date ) + ( options.expires * 1000 ) );
  77                         options.expires = date;
  78                 }
  79
  80                 // Ignore sameSiteLegacy (T344791)
  81                 delete options.sameSiteLegacy;
  82
  83                 if ( value !== null ) {
  84                         value = String( value );
  85                 }
  86
  87                 jar.cookie( prefix + key, value, options );
  88         },
  89
  90         /**
  91          * Get the value of a cookie.
  92          *
  93          * @param {string} key
  94          * @param {string} [prefix=wgCookiePrefix] The prefix of the key. If `prefix` is
  95          *   `undefined` or `null`, then `wgCookiePrefix` is used
  96          * @param {null|string} [defaultValue] defaults to null
  97          * @return {string|null} If the cookie exists, then the value of the
  98          *   cookie, otherwise `defaultValue`
  99          * @memberof module:mediawiki.cookie
 100          */
 101         get: function ( key, prefix, defaultValue ) {
 102                 if ( prefix === undefined || prefix === null ) {
 103                         prefix = defaults.prefix;
 104                 }
 105
 106                 // Was defaultValue omitted?
 107                 if ( arguments.length < 3 ) {
 108                         defaultValue = null;
 109                 }
 110
 111                 const result = jar.cookie( prefix + key );
 112
 113                 return result !== null ? result : defaultValue;
 114         },
 115
 116         /**
 117          * Get the value of a cookie.
 118          *
 119          * @deprecated since 1.43, use {@link module:mediawiki.cookie.get mw.cookie.get}
 120          *
 121          * @param {string} key
 122          * @param {string} [prefix=wgCookiePrefix] The prefix of the key. If `prefix` is
 123          *   `undefined` or `null`, then `wgCookiePrefix` is used
 124          * @param {null|string} [defaultValue]
 125          * @return {string|null} If the cookie exists, then the value of the
 126          *   cookie, otherwise `defaultValue`
 127          * @memberof module:mediawiki.cookie
 128          */
 129         getCrossSite: function ( key, prefix, defaultValue ) {
 130                 return this.get( key, prefix, defaultValue );
 131         }
 132 };
 133
 134 mw.log.deprecate( mw.cookie, 'getCrossSite', mw.cookie.getCrossSite,
 135         'Use mw.cookie.get instead.', 'mw.cookie.getCrossSite' );
 136
 137 if ( window.QUnit ) {
 138         module.exports = {
 139                 jar,
 140                 setDefaults: function ( value ) {
 141                         const prev = defaults;
 142                         defaults = value;
 143                         return prev;
 144                 }
 145         };
 146 }