strong-tie/inbound-calls

1# cookie2 3[![NPM Version][npm-version-image]][npm-url]4[![NPM Downloads][npm-downloads-image]][npm-url]5[![Build Status][ci-image]][ci-url]6[![Coverage Status][coverage-image]][coverage-url]7 8Basic HTTP cookie parser and serializer for HTTP servers.9 10## Installation11 12```sh13$ npm install cookie14```15 16## API17 18```js19const cookie = require("cookie");20// import * as cookie from 'cookie';21```22 23### cookie.parse(str, options)24 25Parse a HTTP `Cookie` header string and returning an object of all cookie name-value pairs.26The `str` argument is the string representing a `Cookie` header value and `options` is an27optional object containing additional parsing options.28 29```js30const cookies = cookie.parse("foo=bar; equation=E%3Dmc%5E2");31// { foo: 'bar', equation: 'E=mc^2' }32```33 34#### Options35 36`cookie.parse` accepts these properties in the options object.37 38##### decode39 40Specifies a function that will be used to decode a [cookie-value](https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1).41Since the value of a cookie has a limited character set (and must be a simple string), this function can be used to decode42a previously-encoded cookie value into a JavaScript string.43 44The default function is the global `decodeURIComponent`, wrapped in a `try..catch`. If an error45is thrown it will return the cookie's original value. If you provide your own encode/decode46scheme you must ensure errors are appropriately handled.47 48### cookie.serialize(name, value, options)49 50Serialize a cookie name-value pair into a `Set-Cookie` header string. The `name` argument is the51name for the cookie, the `value` argument is the value to set the cookie to, and the `options`52argument is an optional object containing additional serialization options.53 54```js55const setCookie = cookie.serialize("foo", "bar");56// foo=bar57```58 59#### Options60 61`cookie.serialize` accepts these properties in the options object.62 63##### encode64 65Specifies a function that will be used to encode a [cookie-value](https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1).66Since value of a cookie has a limited character set (and must be a simple string), this function can be used to encode67a value into a string suited for a cookie's value, and should mirror `decode` when parsing.68 69The default function is the global `encodeURIComponent`.70 71##### maxAge72 73Specifies the `number` (in seconds) to be the value for the [`Max-Age` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.2).74 75The [cookie storage model specification](https://tools.ietf.org/html/rfc6265#section-5.3) states that if both `expires` and76`maxAge` are set, then `maxAge` takes precedence, but it is possible not all clients by obey this,77so if both are set, they should point to the same date and time.78 79##### expires80 81Specifies the `Date` object to be the value for the [`Expires` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.1).82When no expiration is set clients consider this a "non-persistent cookie" and delete it the current session is over.83 84The [cookie storage model specification](https://tools.ietf.org/html/rfc6265#section-5.3) states that if both `expires` and85`maxAge` are set, then `maxAge` takes precedence, but it is possible not all clients by obey this,86so if both are set, they should point to the same date and time.87 88##### domain89 90Specifies the value for the [`Domain` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.3).91When no domain is set clients consider the cookie to apply to the current domain only.92 93##### path94 95Specifies the value for the [`Path` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.4).96When no path is set, the path is considered the ["default path"](https://tools.ietf.org/html/rfc6265#section-5.1.4).97 98##### httpOnly99 100Enables the [`HttpOnly` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.6).101When enabled, clients will not allow client-side JavaScript to see the cookie in `document.cookie`.102 103##### secure104 105Enables the [`Secure` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.5).106When enabled, clients will only send the cookie back if the browser has a HTTPS connection.107 108##### partitioned109 110Enables the [`Partitioned` `Set-Cookie` attribute](https://tools.ietf.org/html/draft-cutler-httpbis-partitioned-cookies/).111When enabled, clients will only send the cookie back when the current domain _and_ top-level domain matches.112 113This is an attribute that has not yet been fully standardized, and may change in the future.114This also means clients may ignore this attribute until they understand it. More information115about can be found in [the proposal](https://github.com/privacycg/CHIPS).116 117##### priority118 119Specifies the value for the [`Priority` `Set-Cookie` attribute](https://tools.ietf.org/html/draft-west-cookie-priority-00#section-4.1).120 121- `'low'` will set the `Priority` attribute to `Low`.122- `'medium'` will set the `Priority` attribute to `Medium`, the default priority when not set.123- `'high'` will set the `Priority` attribute to `High`.124 125More information about priority levels can be found in [the specification](https://tools.ietf.org/html/draft-west-cookie-priority-00#section-4.1).126 127##### sameSite128 129Specifies the value for the [`SameSite` `Set-Cookie` attribute](https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-09#section-5.4.7).130 131- `true` will set the `SameSite` attribute to `Strict` for strict same site enforcement.132- `'lax'` will set the `SameSite` attribute to `Lax` for lax same site enforcement.133- `'none'` will set the `SameSite` attribute to `None` for an explicit cross-site cookie.134- `'strict'` will set the `SameSite` attribute to `Strict` for strict same site enforcement.135 136More information about enforcement levels can be found in [the specification](https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-09#section-5.4.7).137 138## Example139 140The following example uses this module in conjunction with the Node.js core HTTP server141to prompt a user for their name and display it back on future visits.142 143```js144var cookie = require("cookie");145var escapeHtml = require("escape-html");146var http = require("http");147var url = require("url");148 149function onRequest(req, res) {150  // Parse the query string151  var query = url.parse(req.url, true, true).query;152 153  if (query && query.name) {154    // Set a new cookie with the name155    res.setHeader(156      "Set-Cookie",157      cookie.serialize("name", String(query.name), {158        httpOnly: true,159        maxAge: 60 * 60 * 24 * 7, // 1 week160      }),161    );162 163    // Redirect back after setting cookie164    res.statusCode = 302;165    res.setHeader("Location", req.headers.referer || "/");166    res.end();167    return;168  }169 170  // Parse the cookies on the request171  var cookies = cookie.parse(req.headers.cookie || "");172 173  // Get the visitor name set in the cookie174  var name = cookies.name;175 176  res.setHeader("Content-Type", "text/html; charset=UTF-8");177 178  if (name) {179    res.write("<p>Welcome back, <b>" + escapeHtml(name) + "</b>!</p>");180  } else {181    res.write("<p>Hello, new visitor!</p>");182  }183 184  res.write('<form method="GET">');185  res.write(186    '<input placeholder="enter your name" name="name"> <input type="submit" value="Set Name">',187  );188  res.end("</form>");189}190 191http.createServer(onRequest).listen(3000);192```193 194## Testing195 196```sh197npm test198```199 200## Benchmark201 202```sh203npm run bench204```205 206```207     name                   hz     min     max    mean     p75     p99    p995    p999     rme  samples208   · simple       8,566,313.09  0.0000  0.3694  0.0001  0.0001  0.0002  0.0002  0.0003  ±0.64%  4283157   fastest209   · decode       3,834,348.85  0.0001  0.2465  0.0003  0.0003  0.0003  0.0004  0.0006  ±0.38%  1917175210   · unquote      8,315,355.96  0.0000  0.3824  0.0001  0.0001  0.0002  0.0002  0.0003  ±0.72%  4157880211   · duplicates   1,944,765.97  0.0004  0.2959  0.0005  0.0005  0.0006  0.0006  0.0008  ±0.24%   972384212   · 10 cookies     675,345.67  0.0012  0.4328  0.0015  0.0015  0.0019  0.0020  0.0058  ±0.75%   337673213   · 100 cookies     61,040.71  0.0152  0.4092  0.0164  0.0160  0.0196  0.0228  0.2260  ±0.71%    30521   slowest214   ✓ parse top-sites (15) 22945ms215     name                                  hz     min     max    mean     p75     p99    p995    p999     rme   samples216   · parse accounts.google.com   7,164,349.17  0.0000  0.0929  0.0001  0.0002  0.0002  0.0002  0.0003  ±0.09%   3582184217   · parse apple.com             7,817,686.84  0.0000  0.6048  0.0001  0.0001  0.0002  0.0002  0.0003  ±1.05%   3908844218   · parse cloudflare.com        7,189,841.70  0.0000  0.0390  0.0001  0.0002  0.0002  0.0002  0.0003  ±0.06%   3594921219   · parse docs.google.com       7,051,765.61  0.0000  0.0296  0.0001  0.0002  0.0002  0.0002  0.0003  ±0.06%   3525883220   · parse drive.google.com      7,349,104.77  0.0000  0.0368  0.0001  0.0001  0.0002  0.0002  0.0003  ±0.05%   3674553221   · parse en.wikipedia.org      1,929,909.49  0.0004  0.3598  0.0005  0.0005  0.0007  0.0007  0.0012  ±0.16%    964955222   · parse linkedin.com          2,225,658.01  0.0003  0.0595  0.0004  0.0005  0.0005  0.0005  0.0006  ±0.06%   1112830223   · parse maps.google.com       4,423,511.68  0.0001  0.0942  0.0002  0.0003  0.0003  0.0003  0.0005  ±0.08%   2211756224   · parse microsoft.com         3,387,601.88  0.0002  0.0725  0.0003  0.0003  0.0004  0.0004  0.0005  ±0.09%   1693801225   · parse play.google.com       7,375,980.86  0.0000  0.1994  0.0001  0.0001  0.0002  0.0002  0.0003  ±0.12%   3687991226   · parse support.google.com    4,912,267.94  0.0001  2.8958  0.0002  0.0002  0.0003  0.0003  0.0005  ±1.28%   2456134227   · parse www.google.com        3,443,035.87  0.0002  0.2783  0.0003  0.0003  0.0004  0.0004  0.0007  ±0.51%   1721518228   · parse youtu.be              1,910,492.87  0.0004  0.3490  0.0005  0.0005  0.0007  0.0007  0.0011  ±0.46%    955247229   · parse youtube.com           1,895,082.62  0.0004  0.7454  0.0005  0.0005  0.0006  0.0007  0.0013  ±0.64%    947542   slowest230   · parse example.com          21,582,835.27  0.0000  0.1095  0.0000  0.0000  0.0001  0.0001  0.0001  ±0.13%  10791418231```232 233## References234 235- [RFC 6265: HTTP State Management Mechanism](https://tools.ietf.org/html/rfc6265)236- [Same-site Cookies](https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-09#section-5.4.7)237 238## License239 240[MIT](LICENSE)241 242[ci-image]: https://img.shields.io/github/actions/workflow/status/jshttp/cookie/ci.yml243[ci-url]: https://github.com/jshttp/cookie/actions/workflows/ci.yml?query=branch%3Amaster244[coverage-image]: https://img.shields.io/codecov/c/github/jshttp/cookie/master245[coverage-url]: https://app.codecov.io/gh/jshttp/cookie246[npm-downloads-image]: https://img.shields.io/npm/dm/cookie247[npm-url]: https://npmjs.org/package/cookie248[npm-version-image]: https://img.shields.io/npm/v/cookie249