| 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][github-actions-ci-image]][github-actions-ci-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 | ##### priority
|
|---|
| 116 |
|
|---|
| 117 | Specifies the `string` to be the value for the [`Priority` `Set-Cookie` attribute][rfc-west-cookie-priority-00-4.1].
|
|---|
| 118 |
|
|---|
| 119 | - `'low'` will set the `Priority` attribute to `Low`.
|
|---|
| 120 | - `'medium'` will set the `Priority` attribute to `Medium`, the default priority when not set.
|
|---|
| 121 | - `'high'` will set the `Priority` attribute to `High`.
|
|---|
| 122 |
|
|---|
| 123 | More information about the different priority levels can be found in
|
|---|
| 124 | [the specification][rfc-west-cookie-priority-00-4.1].
|
|---|
| 125 |
|
|---|
| 126 | **note** This is an attribute that has not yet been fully standardized, and may change in the future.
|
|---|
| 127 | This also means many clients may ignore this attribute until they understand it.
|
|---|
| 128 |
|
|---|
| 129 | ##### sameSite
|
|---|
| 130 |
|
|---|
| 131 | Specifies the `boolean` or `string` to be the value for the [`SameSite` `Set-Cookie` attribute][rfc-6265bis-09-5.4.7].
|
|---|
| 132 |
|
|---|
| 133 | - `true` will set the `SameSite` attribute to `Strict` for strict same site enforcement.
|
|---|
| 134 | - `false` will not set the `SameSite` attribute.
|
|---|
| 135 | - `'lax'` will set the `SameSite` attribute to `Lax` for lax same site enforcement.
|
|---|
| 136 | - `'none'` will set the `SameSite` attribute to `None` for an explicit cross-site cookie.
|
|---|
| 137 | - `'strict'` will set the `SameSite` attribute to `Strict` for strict same site enforcement.
|
|---|
| 138 |
|
|---|
| 139 | More information about the different enforcement levels can be found in
|
|---|
| 140 | [the specification][rfc-6265bis-09-5.4.7].
|
|---|
| 141 |
|
|---|
| 142 | **note** This is an attribute that has not yet been fully standardized, and may change in the future.
|
|---|
| 143 | This also means many clients may ignore this attribute until they understand it.
|
|---|
| 144 |
|
|---|
| 145 | ##### secure
|
|---|
| 146 |
|
|---|
| 147 | Specifies the `boolean` value for the [`Secure` `Set-Cookie` attribute][rfc-6265-5.2.5]. When truthy,
|
|---|
| 148 | the `Secure` attribute is set, otherwise it is not. By default, the `Secure` attribute is not set.
|
|---|
| 149 |
|
|---|
| 150 | **note** be careful when setting this to `true`, as compliant clients will not send the cookie back to
|
|---|
| 151 | the server in the future if the browser does not have an HTTPS connection.
|
|---|
| 152 |
|
|---|
| 153 | ## Example
|
|---|
| 154 |
|
|---|
| 155 | The following example uses this module in conjunction with the Node.js core HTTP server
|
|---|
| 156 | to prompt a user for their name and display it back on future visits.
|
|---|
| 157 |
|
|---|
| 158 | ```js
|
|---|
| 159 | var cookie = require('cookie');
|
|---|
| 160 | var escapeHtml = require('escape-html');
|
|---|
| 161 | var http = require('http');
|
|---|
| 162 | var url = require('url');
|
|---|
| 163 |
|
|---|
| 164 | function onRequest(req, res) {
|
|---|
| 165 | // Parse the query string
|
|---|
| 166 | var query = url.parse(req.url, true, true).query;
|
|---|
| 167 |
|
|---|
| 168 | if (query && query.name) {
|
|---|
| 169 | // Set a new cookie with the name
|
|---|
| 170 | res.setHeader('Set-Cookie', cookie.serialize('name', String(query.name), {
|
|---|
| 171 | httpOnly: true,
|
|---|
| 172 | maxAge: 60 * 60 * 24 * 7 // 1 week
|
|---|
| 173 | }));
|
|---|
| 174 |
|
|---|
| 175 | // Redirect back after setting cookie
|
|---|
| 176 | res.statusCode = 302;
|
|---|
| 177 | res.setHeader('Location', req.headers.referer || '/');
|
|---|
| 178 | res.end();
|
|---|
| 179 | return;
|
|---|
| 180 | }
|
|---|
| 181 |
|
|---|
| 182 | // Parse the cookies on the request
|
|---|
| 183 | var cookies = cookie.parse(req.headers.cookie || '');
|
|---|
| 184 |
|
|---|
| 185 | // Get the visitor name set in the cookie
|
|---|
| 186 | var name = cookies.name;
|
|---|
| 187 |
|
|---|
| 188 | res.setHeader('Content-Type', 'text/html; charset=UTF-8');
|
|---|
| 189 |
|
|---|
| 190 | if (name) {
|
|---|
| 191 | res.write('<p>Welcome back, <b>' + escapeHtml(name) + '</b>!</p>');
|
|---|
| 192 | } else {
|
|---|
| 193 | res.write('<p>Hello, new visitor!</p>');
|
|---|
| 194 | }
|
|---|
| 195 |
|
|---|
| 196 | res.write('<form method="GET">');
|
|---|
| 197 | res.write('<input placeholder="enter your name" name="name"> <input type="submit" value="Set Name">');
|
|---|
| 198 | res.end('</form>');
|
|---|
| 199 | }
|
|---|
| 200 |
|
|---|
| 201 | http.createServer(onRequest).listen(3000);
|
|---|
| 202 | ```
|
|---|
| 203 |
|
|---|
| 204 | ## Testing
|
|---|
| 205 |
|
|---|
| 206 | ```sh
|
|---|
| 207 | $ npm test
|
|---|
| 208 | ```
|
|---|
| 209 |
|
|---|
| 210 | ## Benchmark
|
|---|
| 211 |
|
|---|
| 212 | ```
|
|---|
| 213 | $ npm run bench
|
|---|
| 214 |
|
|---|
| 215 | > cookie@0.4.2 bench
|
|---|
| 216 | > node benchmark/index.js
|
|---|
| 217 |
|
|---|
| 218 | node@16.14.0
|
|---|
| 219 | v8@9.4.146.24-node.20
|
|---|
| 220 | uv@1.43.0
|
|---|
| 221 | zlib@1.2.11
|
|---|
| 222 | brotli@1.0.9
|
|---|
| 223 | ares@1.18.1
|
|---|
| 224 | modules@93
|
|---|
| 225 | nghttp2@1.45.1
|
|---|
| 226 | napi@8
|
|---|
| 227 | llhttp@6.0.4
|
|---|
| 228 | openssl@1.1.1m+quic
|
|---|
| 229 | cldr@40.0
|
|---|
| 230 | icu@70.1
|
|---|
| 231 | tz@2021a3
|
|---|
| 232 | unicode@14.0
|
|---|
| 233 | ngtcp2@0.1.0-DEV
|
|---|
| 234 | nghttp3@0.1.0-DEV
|
|---|
| 235 |
|
|---|
| 236 | > node benchmark/parse-top.js
|
|---|
| 237 |
|
|---|
| 238 | cookie.parse - top sites
|
|---|
| 239 |
|
|---|
| 240 | 15 tests completed.
|
|---|
| 241 |
|
|---|
| 242 | parse accounts.google.com x 2,421,245 ops/sec ±0.80% (188 runs sampled)
|
|---|
| 243 | parse apple.com x 2,684,710 ops/sec ±0.59% (189 runs sampled)
|
|---|
| 244 | parse cloudflare.com x 2,231,418 ops/sec ±0.76% (186 runs sampled)
|
|---|
| 245 | parse docs.google.com x 2,316,357 ops/sec ±1.28% (187 runs sampled)
|
|---|
| 246 | parse drive.google.com x 2,363,543 ops/sec ±0.49% (189 runs sampled)
|
|---|
| 247 | parse en.wikipedia.org x 839,414 ops/sec ±0.53% (189 runs sampled)
|
|---|
| 248 | parse linkedin.com x 553,797 ops/sec ±0.63% (190 runs sampled)
|
|---|
| 249 | parse maps.google.com x 1,314,779 ops/sec ±0.72% (189 runs sampled)
|
|---|
| 250 | parse microsoft.com x 153,783 ops/sec ±0.53% (190 runs sampled)
|
|---|
| 251 | parse play.google.com x 2,249,574 ops/sec ±0.59% (187 runs sampled)
|
|---|
| 252 | parse plus.google.com x 2,258,682 ops/sec ±0.60% (188 runs sampled)
|
|---|
| 253 | parse sites.google.com x 2,247,069 ops/sec ±0.68% (189 runs sampled)
|
|---|
| 254 | parse support.google.com x 1,456,840 ops/sec ±0.70% (187 runs sampled)
|
|---|
| 255 | parse www.google.com x 1,046,028 ops/sec ±0.58% (188 runs sampled)
|
|---|
| 256 | parse youtu.be x 937,428 ops/sec ±1.47% (190 runs sampled)
|
|---|
| 257 | parse youtube.com x 963,878 ops/sec ±0.59% (190 runs sampled)
|
|---|
| 258 |
|
|---|
| 259 | > node benchmark/parse.js
|
|---|
| 260 |
|
|---|
| 261 | cookie.parse - generic
|
|---|
| 262 |
|
|---|
| 263 | 6 tests completed.
|
|---|
| 264 |
|
|---|
| 265 | simple x 2,745,604 ops/sec ±0.77% (185 runs sampled)
|
|---|
| 266 | decode x 557,287 ops/sec ±0.60% (188 runs sampled)
|
|---|
| 267 | unquote x 2,498,475 ops/sec ±0.55% (189 runs sampled)
|
|---|
| 268 | duplicates x 868,591 ops/sec ±0.89% (187 runs sampled)
|
|---|
| 269 | 10 cookies x 306,745 ops/sec ±0.49% (190 runs sampled)
|
|---|
| 270 | 100 cookies x 22,414 ops/sec ±2.38% (182 runs sampled)
|
|---|
| 271 | ```
|
|---|
| 272 |
|
|---|
| 273 | ## References
|
|---|
| 274 |
|
|---|
| 275 | - [RFC 6265: HTTP State Management Mechanism][rfc-6265]
|
|---|
| 276 | - [Same-site Cookies][rfc-6265bis-09-5.4.7]
|
|---|
| 277 |
|
|---|
| 278 | [rfc-west-cookie-priority-00-4.1]: https://tools.ietf.org/html/draft-west-cookie-priority-00#section-4.1
|
|---|
| 279 | [rfc-6265bis-09-5.4.7]: https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-09#section-5.4.7
|
|---|
| 280 | [rfc-6265]: https://tools.ietf.org/html/rfc6265
|
|---|
| 281 | [rfc-6265-5.1.4]: https://tools.ietf.org/html/rfc6265#section-5.1.4
|
|---|
| 282 | [rfc-6265-5.2.1]: https://tools.ietf.org/html/rfc6265#section-5.2.1
|
|---|
| 283 | [rfc-6265-5.2.2]: https://tools.ietf.org/html/rfc6265#section-5.2.2
|
|---|
| 284 | [rfc-6265-5.2.3]: https://tools.ietf.org/html/rfc6265#section-5.2.3
|
|---|
| 285 | [rfc-6265-5.2.4]: https://tools.ietf.org/html/rfc6265#section-5.2.4
|
|---|
| 286 | [rfc-6265-5.2.5]: https://tools.ietf.org/html/rfc6265#section-5.2.5
|
|---|
| 287 | [rfc-6265-5.2.6]: https://tools.ietf.org/html/rfc6265#section-5.2.6
|
|---|
| 288 | [rfc-6265-5.3]: https://tools.ietf.org/html/rfc6265#section-5.3
|
|---|
| 289 |
|
|---|
| 290 | ## License
|
|---|
| 291 |
|
|---|
| 292 | [MIT](LICENSE)
|
|---|
| 293 |
|
|---|
| 294 | [coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/cookie/master
|
|---|
| 295 | [coveralls-url]: https://coveralls.io/r/jshttp/cookie?branch=master
|
|---|
| 296 | [github-actions-ci-image]: https://img.shields.io/github/workflow/status/jshttp/cookie/ci/master?label=ci
|
|---|
| 297 | [github-actions-ci-url]: https://github.com/jshttp/cookie/actions/workflows/ci.yml
|
|---|
| 298 | [node-version-image]: https://badgen.net/npm/node/cookie
|
|---|
| 299 | [node-version-url]: https://nodejs.org/en/download
|
|---|
| 300 | [npm-downloads-image]: https://badgen.net/npm/dm/cookie
|
|---|
| 301 | [npm-url]: https://npmjs.org/package/cookie
|
|---|
| 302 | [npm-version-image]: https://badgen.net/npm/v/cookie
|
|---|
