opusdev/vector-similarity-api

1# cookie2 3[![NPM Version][npm-version-image]][npm-url]4[![NPM Downloads][npm-downloads-image]][npm-url]5[![Node.js Version][node-image]][node-url]6[![Build Status][ci-image]][ci-url]7[![Coverage Status][coveralls-image]][coveralls-url]8 9Basic HTTP cookie parser and serializer for HTTP servers.10 11## Installation12 13This is a [Node.js](https://nodejs.org/en/) module available through the14[npm registry](https://www.npmjs.com/). Installation is done using the15[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):16 17```sh18$ npm install cookie19```20 21## API22 23```js24var cookie = require('cookie');25```26 27### cookie.parse(str, options)28 29Parse an HTTP `Cookie` header string and returning an object of all cookie name-value pairs.30The `str` argument is the string representing a `Cookie` header value and `options` is an31optional object containing additional parsing options.32 33```js34var cookies = cookie.parse('foo=bar; equation=E%3Dmc%5E2');35// { foo: 'bar', equation: 'E=mc^2' }36```37 38#### Options39 40`cookie.parse` accepts these properties in the options object.41 42##### decode43 44Specifies a function that will be used to decode a cookie's value. Since the value of a cookie45has a limited character set (and must be a simple string), this function can be used to decode46a previously-encoded cookie value into a JavaScript string or other object.47 48The default function is the global `decodeURIComponent`, which will decode any URL-encoded49sequences into their byte representations.50 51**note** if an error is thrown from this function, the original, non-decoded cookie value will52be returned as the cookie's value.53 54### cookie.serialize(name, value, options)55 56Serialize a cookie name-value pair into a `Set-Cookie` header string. The `name` argument is the57name for the cookie, the `value` argument is the value to set the cookie to, and the `options`58argument is an optional object containing additional serialization options.59 60```js61var setCookie = cookie.serialize('foo', 'bar');62// foo=bar63```64 65#### Options66 67`cookie.serialize` accepts these properties in the options object.68 69##### domain70 71Specifies the value for the [`Domain` `Set-Cookie` attribute][rfc-6265-5.2.3]. By default, no72domain is set, and most clients will consider the cookie to apply to only the current domain.73 74##### encode75 76Specifies a function that will be used to encode a cookie's value. Since value of a cookie77has a limited character set (and must be a simple string), this function can be used to encode78a value into a string suited for a cookie's value.79 80The default function is the global `encodeURIComponent`, which will encode a JavaScript string81into UTF-8 byte sequences and then URL-encode any that fall outside of the cookie range.82 83##### expires84 85Specifies the `Date` object to be the value for the [`Expires` `Set-Cookie` attribute][rfc-6265-5.2.1].86By default, no expiration is set, and most clients will consider this a "non-persistent cookie" and87will 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` and90`maxAge` are set, then `maxAge` takes precedence, but it is possible not all clients by obey this,91so if both are set, they should point to the same date and time.92 93##### httpOnly94 95Specifies the `boolean` value for the [`HttpOnly` `Set-Cookie` attribute][rfc-6265-5.2.6]. When truthy,96the `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-side99JavaScript to see the cookie in `document.cookie`.100 101##### maxAge102 103Specifies the `number` (in seconds) to be the value for the [`Max-Age` `Set-Cookie` attribute][rfc-6265-5.2.2].104The 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` and107`maxAge` are set, then `maxAge` takes precedence, but it is possible not all clients by obey this,108so if both are set, they should point to the same date and time.109 110##### partitioned111 112Specifies the `boolean` value for the [`Partitioned` `Set-Cookie`](rfc-cutler-httpbis-partitioned-cookies)113attribute. When truthy, the `Partitioned` attribute is set, otherwise it is not. By default, the114`Partitioned` attribute is not set.115 116**note** This is an attribute that has not yet been fully standardized, and may change in the future.117This also means many clients may ignore this attribute until they understand it.118 119More information about can be found in [the proposal](https://github.com/privacycg/CHIPS).120 121##### path122 123Specifies the value for the [`Path` `Set-Cookie` attribute][rfc-6265-5.2.4]. By default, the path124is considered the ["default path"][rfc-6265-5.1.4].125 126##### priority127 128Specifies the `string` to be the value for the [`Priority` `Set-Cookie` attribute][rfc-west-cookie-priority-00-4.1].129 130  - `'low'` will set the `Priority` attribute to `Low`.131  - `'medium'` will set the `Priority` attribute to `Medium`, the default priority when not set.132  - `'high'` will set the `Priority` attribute to `High`.133 134More information about the different priority levels can be found in135[the specification][rfc-west-cookie-priority-00-4.1].136 137**note** This is an attribute that has not yet been fully standardized, and may change in the future.138This also means many clients may ignore this attribute until they understand it.139 140##### sameSite141 142Specifies the `boolean` or `string` to be the value for the [`SameSite` `Set-Cookie` attribute][rfc-6265bis-09-5.4.7].143 144  - `true` will set the `SameSite` attribute to `Strict` for strict same site enforcement.145  - `false` will not set the `SameSite` attribute.146  - `'lax'` will set the `SameSite` attribute to `Lax` for lax same site enforcement.147  - `'none'` will set the `SameSite` attribute to `None` for an explicit cross-site cookie.148  - `'strict'` will set the `SameSite` attribute to `Strict` for strict same site enforcement.149 150More information about the different enforcement levels can be found in151[the specification][rfc-6265bis-09-5.4.7].152 153**note** This is an attribute that has not yet been fully standardized, and may change in the future.154This also means many clients may ignore this attribute until they understand it.155 156##### secure157 158Specifies the `boolean` value for the [`Secure` `Set-Cookie` attribute][rfc-6265-5.2.5]. When truthy,159the `Secure` attribute is set, otherwise it is not. By default, the `Secure` attribute is not set.160 161**note** be careful when setting this to `true`, as compliant clients will not send the cookie back to162the server in the future if the browser does not have an HTTPS connection.163 164## Example165 166The following example uses this module in conjunction with the Node.js core HTTP server167to prompt a user for their name and display it back on future visits.168 169```js170var cookie = require('cookie');171var escapeHtml = require('escape-html');172var http = require('http');173var url = require('url');174 175function onRequest(req, res) {176  // Parse the query string177  var query = url.parse(req.url, true, true).query;178 179  if (query && query.name) {180    // Set a new cookie with the name181    res.setHeader('Set-Cookie', cookie.serialize('name', String(query.name), {182      httpOnly: true,183      maxAge: 60 * 60 * 24 * 7 // 1 week184    }));185 186    // Redirect back after setting cookie187    res.statusCode = 302;188    res.setHeader('Location', req.headers.referer || '/');189    res.end();190    return;191  }192 193  // Parse the cookies on the request194  var cookies = cookie.parse(req.headers.cookie || '');195 196  // Get the visitor name set in the cookie197  var name = cookies.name;198 199  res.setHeader('Content-Type', 'text/html; charset=UTF-8');200 201  if (name) {202    res.write('<p>Welcome back, <b>' + escapeHtml(name) + '</b>!</p>');203  } else {204    res.write('<p>Hello, new visitor!</p>');205  }206 207  res.write('<form method="GET">');208  res.write('<input placeholder="enter your name" name="name"> <input type="submit" value="Set Name">');209  res.end('</form>');210}211 212http.createServer(onRequest).listen(3000);213```214 215## Testing216 217```sh218$ npm test219```220 221## Benchmark222 223```224$ npm run bench225 226> cookie@0.5.0 bench227> node benchmark/index.js228 229  node@18.18.2230  acorn@8.10.0231  ada@2.6.0232  ares@1.19.1233  brotli@1.0.9234  cldr@43.1235  icu@73.2236  llhttp@6.0.11237  modules@108238  napi@9239  nghttp2@1.57.0240  nghttp3@0.7.0241  ngtcp2@0.8.1242  openssl@3.0.10+quic243  simdutf@3.2.14244  tz@2023c245  undici@5.26.3246  unicode@15.0247  uv@1.44.2248  uvwasi@0.0.18249  v8@10.2.154.26-node.26250  zlib@1.2.13.1-motley251 252> node benchmark/parse-top.js253 254  cookie.parse - top sites255 256  14 tests completed.257 258  parse accounts.google.com x 2,588,913 ops/sec ±0.74% (186 runs sampled)259  parse apple.com           x 2,370,002 ops/sec ±0.69% (186 runs sampled)260  parse cloudflare.com      x 2,213,102 ops/sec ±0.88% (188 runs sampled)261  parse docs.google.com     x 2,194,157 ops/sec ±1.03% (184 runs sampled)262  parse drive.google.com    x 2,265,084 ops/sec ±0.79% (187 runs sampled)263  parse en.wikipedia.org    x   457,099 ops/sec ±0.81% (186 runs sampled)264  parse linkedin.com        x   504,407 ops/sec ±0.89% (186 runs sampled)265  parse maps.google.com     x 1,230,959 ops/sec ±0.98% (186 runs sampled)266  parse microsoft.com       x   926,294 ops/sec ±0.88% (184 runs sampled)267  parse play.google.com     x 2,311,338 ops/sec ±0.83% (185 runs sampled)268  parse support.google.com  x 1,508,850 ops/sec ±0.86% (186 runs sampled)269  parse www.google.com      x 1,022,582 ops/sec ±1.32% (182 runs sampled)270  parse youtu.be            x   332,136 ops/sec ±1.02% (185 runs sampled)271  parse youtube.com         x   323,833 ops/sec ±0.77% (183 runs sampled)272 273> node benchmark/parse.js274 275  cookie.parse - generic276 277  6 tests completed.278 279  simple      x 3,214,032 ops/sec ±1.61% (183 runs sampled)280  decode      x   587,237 ops/sec ±1.16% (187 runs sampled)281  unquote     x 2,954,618 ops/sec ±1.35% (183 runs sampled)282  duplicates  x   857,008 ops/sec ±0.89% (187 runs sampled)283  10 cookies  x   292,133 ops/sec ±0.89% (187 runs sampled)284  100 cookies x    22,610 ops/sec ±0.68% (187 runs sampled)285```286 287## References288 289- [RFC 6265: HTTP State Management Mechanism][rfc-6265]290- [Same-site Cookies][rfc-6265bis-09-5.4.7]291 292[rfc-cutler-httpbis-partitioned-cookies]: https://tools.ietf.org/html/draft-cutler-httpbis-partitioned-cookies/293[rfc-west-cookie-priority-00-4.1]: https://tools.ietf.org/html/draft-west-cookie-priority-00#section-4.1294[rfc-6265bis-09-5.4.7]: https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-09#section-5.4.7295[rfc-6265]: https://tools.ietf.org/html/rfc6265296[rfc-6265-5.1.4]: https://tools.ietf.org/html/rfc6265#section-5.1.4297[rfc-6265-5.2.1]: https://tools.ietf.org/html/rfc6265#section-5.2.1298[rfc-6265-5.2.2]: https://tools.ietf.org/html/rfc6265#section-5.2.2299[rfc-6265-5.2.3]: https://tools.ietf.org/html/rfc6265#section-5.2.3300[rfc-6265-5.2.4]: https://tools.ietf.org/html/rfc6265#section-5.2.4301[rfc-6265-5.2.5]: https://tools.ietf.org/html/rfc6265#section-5.2.5302[rfc-6265-5.2.6]: https://tools.ietf.org/html/rfc6265#section-5.2.6303[rfc-6265-5.3]: https://tools.ietf.org/html/rfc6265#section-5.3304 305## License306 307[MIT](LICENSE)308 309[ci-image]: https://badgen.net/github/checks/jshttp/cookie/master?label=ci310[ci-url]: https://github.com/jshttp/cookie/actions/workflows/ci.yml311[coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/cookie/master312[coveralls-url]: https://coveralls.io/r/jshttp/cookie?branch=master313[node-image]: https://badgen.net/npm/node/cookie314[node-url]: https://nodejs.org/en/download315[npm-downloads-image]: https://badgen.net/npm/dm/cookie316[npm-url]: https://npmjs.org/package/cookie317[npm-version-image]: https://badgen.net/npm/v/cookie318