signaling_server/service/node_modules/engine.io/node_modules/cookie/README.md

   1 # cookie
   2
   3 [![NPM Version][npm-version-image]][npm-url]
   4 [![NPM Downloads][npm-downloads-image]][npm-url]
   5 [![Node.js Version][node-version-image]][node-version-url]
   6 [![Build Status][travis-image]][travis-url]
   7 [![Test Coverage][coveralls-image]][coveralls-url]
   8
   9 Basic HTTP cookie parser and serializer for HTTP servers.
  10
  11 ## Installation
  12
  13 This is a [Node.js](https://nodejs.org/en/) module available through the
  14 [npm registry](https://www.npmjs.com/). Installation is done using the
  15 [`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):
  16
  17 ```sh
  18 $ npm install cookie
  19 ```
  20
  21 ## API
  22
  23 ```js
  24 var cookie = require('cookie');
  25 ```
  26
  27 ### cookie.parse(str, options)
  28
  29 Parse an HTTP `Cookie` header string and returning an object of all cookie name-value pairs.
  30 The `str` argument is the string representing a `Cookie` header value and `options` is an
  31 optional object containing additional parsing options.
  32
  33 ```js
  34 var cookies = cookie.parse('foo=bar; equation=E%3Dmc%5E2');
  35 // { foo: 'bar', equation: 'E=mc^2' }
  36 ```
  37
  38 #### Options
  39
  40 `cookie.parse` accepts these properties in the options object.
  41
  42 ##### decode
  43
  44 Specifies a function that will be used to decode a cookie's value. Since the value of a cookie
  45 has a limited character set (and must be a simple string), this function can be used to decode
  46 a previously-encoded cookie value into a JavaScript string or other object.
  47
  48 The default function is the global `decodeURIComponent`, which will decode any URL-encoded
  49 sequences into their byte representations.
  50
  51 **note** if an error is thrown from this function, the original, non-decoded cookie value will
  52 be returned as the cookie's value.
  53
  54 ### cookie.serialize(name, value, options)
  55
  56 Serialize a cookie name-value pair into a `Set-Cookie` header string. The `name` argument is the
  57 name for the cookie, the `value` argument is the value to set the cookie to, and the `options`
  58 argument is an optional object containing additional serialization options.
  59
  60 ```js
  61 var setCookie = cookie.serialize('foo', 'bar');
  62 // foo=bar
  63 ```
  64
  65 #### Options
  66
  67 `cookie.serialize` accepts these properties in the options object.
  68
  69 ##### domain
  70
  71 Specifies the value for the [`Domain` `Set-Cookie` attribute][rfc-6265-5.2.3]. By default, no
  72 domain is set, and most clients will consider the cookie to apply to only the current domain.
  73
  74 ##### encode
  75
  76 Specifies a function that will be used to encode a cookie's value. Since value of a cookie
  77 has a limited character set (and must be a simple string), this function can be used to encode
  78 a value into a string suited for a cookie's value.
  79
  80 The default function is the global `encodeURIComponent`, which will encode a JavaScript string
  81 into UTF-8 byte sequences and then URL-encode any that fall outside of the cookie range.
  82
  83 ##### expires
  84
  85 Specifies the `Date` object to be the value for the [`Expires` `Set-Cookie` attribute][rfc-6265-5.2.1].
  86 By default, no expiration is set, and most clients will consider this a "non-persistent cookie" and
  87 will delete it on a condition like exiting a web browser application.
  88
  89 **note** the [cookie storage model specification][rfc-6265-5.3] states that if both `expires` and
  90 `maxAge` are set, then `maxAge` takes precedence, but it is possible not all clients by obey this,
  91 so if both are set, they should point to the same date and time.
  92
  93 ##### httpOnly
  94
  95 Specifies the `boolean` value for the [`HttpOnly` `Set-Cookie` attribute][rfc-6265-5.2.6]. When truthy,
  96 the `HttpOnly` attribute is set, otherwise it is not. By default, the `HttpOnly` attribute is not set.
  97
  98 **note** be careful when setting this to `true`, as compliant clients will not allow client-side
  99 JavaScript to see the cookie in `document.cookie`.
 100
 101 ##### maxAge
 102
 103 Specifies the `number` (in seconds) to be the value for the [`Max-Age` `Set-Cookie` attribute][rfc-6265-5.2.2].
 104 The given number will be converted to an integer by rounding down. By default, no maximum age is set.
 105
 106 **note** the [cookie storage model specification][rfc-6265-5.3] states that if both `expires` and
 107 `maxAge` are set, then `maxAge` takes precedence, but it is possible not all clients by obey this,
 108 so if both are set, they should point to the same date and time.
 109
 110 ##### path
 111
 112 Specifies the value for the [`Path` `Set-Cookie` attribute][rfc-6265-5.2.4]. By default, the path
 113 is considered the ["default path"][rfc-6265-5.1.4].
 114
 115 ##### sameSite
 116
 117 Specifies the `boolean` or `string` to be the value for the [`SameSite` `Set-Cookie` attribute][rfc-6265bis-03-4.1.2.7].
 118
 119   - `true` will set the `SameSite` attribute to `Strict` for strict same site enforcement.
 120   - `false` will not set the `SameSite` attribute.
 121   - `'lax'` will set the `SameSite` attribute to `Lax` for lax same site enforcement.
 122   - `'none'` will set the `SameSite` attribute to `None` for an explicit cross-site cookie.
 123   - `'strict'` will set the `SameSite` attribute to `Strict` for strict same site enforcement.
 124
 125 More information about the different enforcement levels can be found in
 126 [the specification][rfc-6265bis-03-4.1.2.7].
 127
 128 **note** This is an attribute that has not yet been fully standardized, and may change in the future.
 129 This also means many clients may ignore this attribute until they understand it.
 130
 131 ##### secure
 132
 133 Specifies the `boolean` value for the [`Secure` `Set-Cookie` attribute][rfc-6265-5.2.5]. When truthy,
 134 the `Secure` attribute is set, otherwise it is not. By default, the `Secure` attribute is not set.
 135
 136 **note** be careful when setting this to `true`, as compliant clients will not send the cookie back to
 137 the server in the future if the browser does not have an HTTPS connection.
 138
 139 ## Example
 140
 141 The following example uses this module in conjunction with the Node.js core HTTP server
 142 to prompt a user for their name and display it back on future visits.
 143
 144 ```js
 145 var cookie = require('cookie');
 146 var escapeHtml = require('escape-html');
 147 var http = require('http');
 148 var url = require('url');
 149
 150 function onRequest(req, res) {
 151   // Parse the query string
 152   var query = url.parse(req.url, true, true).query;
 153
 154   if (query && query.name) {
 155     // Set a new cookie with the name
 156     res.setHeader('Set-Cookie', cookie.serialize('name', String(query.name), {
 157       httpOnly: true,
 158       maxAge: 60 * 60 * 24 * 7 // 1 week
 159     }));
 160
 161     // Redirect back after setting cookie
 162     res.statusCode = 302;
 163     res.setHeader('Location', req.headers.referer || '/');
 164     res.end();
 165     return;
 166   }
 167
 168   // Parse the cookies on the request
 169   var cookies = cookie.parse(req.headers.cookie || '');
 170
 171   // Get the visitor name set in the cookie
 172   var name = cookies.name;
 173
 174   res.setHeader('Content-Type', 'text/html; charset=UTF-8');
 175
 176   if (name) {
 177     res.write('<p>Welcome back, <b>' + escapeHtml(name) + '</b>!</p>');
 178   } else {
 179     res.write('<p>Hello, new visitor!</p>');
 180   }
 181
 182   res.write('<form method="GET">');
 183   res.write('<input placeholder="enter your name" name="name"> <input type="submit" value="Set Name">');
 184   res.end('</form>');
 185 }
 186
 187 http.createServer(onRequest).listen(3000);
 188 ```
 189
 190 ## Testing
 191
 192 ```sh
 193 $ npm test
 194 ```
 195
 196 ## Benchmark
 197
 198 ```
 199 $ npm run bench
 200
 201 > cookie@0.3.1 bench cookie
 202 > node benchmark/index.js
 203
 204   http_parser@2.8.0
 205   node@6.14.2
 206   v8@5.1.281.111
 207   uv@1.16.1
 208   zlib@1.2.11
 209   ares@1.10.1-DEV
 210   icu@58.2
 211   modules@48
 212   napi@3
 213   openssl@1.0.2o
 214
 215 > node benchmark/parse.js
 216
 217   cookie.parse
 218
 219   6 tests completed.
 220
 221   simple      x 1,200,691 ops/sec ±1.12% (189 runs sampled)
 222   decode      x 1,012,994 ops/sec ±0.97% (186 runs sampled)
 223   unquote     x 1,074,174 ops/sec ±2.43% (186 runs sampled)
 224   duplicates  x   438,424 ops/sec ±2.17% (184 runs sampled)
 225   10 cookies  x   147,154 ops/sec ±1.01% (186 runs sampled)
 226   100 cookies x    14,274 ops/sec ±1.07% (187 runs sampled)
 227 ```
 228
 229 ## References
 230
 231 - [RFC 6265: HTTP State Management Mechanism][rfc-6265]
 232 - [Same-site Cookies][rfc-6265bis-03-4.1.2.7]
 233
 234 [rfc-6265bis-03-4.1.2.7]: https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7
 235 [rfc-6265]: https://tools.ietf.org/html/rfc6265
 236 [rfc-6265-5.1.4]: https://tools.ietf.org/html/rfc6265#section-5.1.4
 237 [rfc-6265-5.2.1]: https://tools.ietf.org/html/rfc6265#section-5.2.1
 238 [rfc-6265-5.2.2]: https://tools.ietf.org/html/rfc6265#section-5.2.2
 239 [rfc-6265-5.2.3]: https://tools.ietf.org/html/rfc6265#section-5.2.3
 240 [rfc-6265-5.2.4]: https://tools.ietf.org/html/rfc6265#section-5.2.4
 241 [rfc-6265-5.2.5]: https://tools.ietf.org/html/rfc6265#section-5.2.5
 242 [rfc-6265-5.2.6]: https://tools.ietf.org/html/rfc6265#section-5.2.6
 243 [rfc-6265-5.3]: https://tools.ietf.org/html/rfc6265#section-5.3
 244
 245 ## License
 246
 247 [MIT](LICENSE)
 248
 249 [coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/cookie/master
 250 [coveralls-url]: https://coveralls.io/r/jshttp/cookie?branch=master
 251 [node-version-image]: https://badgen.net/npm/node/cookie
 252 [node-version-url]: https://nodejs.org/en/download
 253 [npm-downloads-image]: https://badgen.net/npm/dm/cookie
 254 [npm-url]: https://npmjs.org/package/cookie
 255 [npm-version-image]: https://badgen.net/npm/v/cookie
 256 [travis-image]: https://badgen.net/travis/jshttp/cookie/master
 257 [travis-url]: https://travis-ci.org/jshttp/cookie