diff options
Diffstat (limited to 'node_modules/cookie/README.md')
| -rw-r--r-- | node_modules/cookie/README.md | 220 |
1 files changed, 0 insertions, 220 deletions
diff --git a/node_modules/cookie/README.md b/node_modules/cookie/README.md deleted file mode 100644 index db0d078..0000000 --- a/node_modules/cookie/README.md +++ /dev/null @@ -1,220 +0,0 @@ -# cookie - -[![NPM Version][npm-image]][npm-url] -[![NPM Downloads][downloads-image]][downloads-url] -[![Node.js Version][node-version-image]][node-version-url] -[![Build Status][travis-image]][travis-url] -[![Test Coverage][coveralls-image]][coveralls-url] - -Basic HTTP cookie parser and serializer for HTTP servers. - -## Installation - -```sh -$ npm install cookie -``` - -## API - -```js -var cookie = require('cookie'); -``` - -### cookie.parse(str, options) - -Parse an HTTP `Cookie` header string and returning an object of all cookie name-value pairs. -The `str` argument is the string representing a `Cookie` header value and `options` is an -optional object containing additional parsing options. - -```js -var cookies = cookie.parse('foo=bar; equation=E%3Dmc%5E2'); -// { foo: 'bar', equation: 'E=mc^2' } -``` - -#### Options - -`cookie.parse` accepts these properties in the options object. - -##### decode - -Specifies a function that will be used to decode a cookie's value. Since the value of a cookie -has a limited character set (and must be a simple string), this function can be used to decode -a previously-encoded cookie value into a JavaScript string or other object. - -The default function is the global `decodeURIComponent`, which will decode any URL-encoded -sequences into their byte representations. - -**note** if an error is thrown from this function, the original, non-decoded cookie value will -be returned as the cookie's value. - -### cookie.serialize(name, value, options) - -Serialize a cookie name-value pair into a `Set-Cookie` header string. The `name` argument is the -name for the cookie, the `value` argument is the value to set the cookie to, and the `options` -argument is an optional object containing additional serialization options. - -```js -var setCookie = cookie.serialize('foo', 'bar'); -// foo=bar -``` - -#### Options - -`cookie.serialize` accepts these properties in the options object. - -##### domain - -Specifies the value for the [`Domain` `Set-Cookie` attribute][rfc-6266-5.2.3]. By default, no -domain is set, and most clients will consider the cookie to apply to only the current domain. - -##### encode - -Specifies a function that will be used to encode a cookie's value. Since value of a cookie -has a limited character set (and must be a simple string), this function can be used to encode -a value into a string suited for a cookie's value. - -The default function is the global `ecodeURIComponent`, which will encode a JavaScript string -into UTF-8 byte sequences and then URL-encode any that fall outside of the cookie range. - -##### expires - -Specifies the `Date` object to be the value for the [`Expires` `Set-Cookie` attribute][rfc-6266-5.2.1]. -By default, no expiration is set, and most clients will consider this a "non-persistent cookie" and -will delete it on a condition like exiting a web browser application. - -**note** the [cookie storage model specification][rfc-6266-5.3] states that if both `expires` and -`magAge` are set, then `maxAge` takes precedence, but it is possiblke not all clients by obey this, -so if both are set, they should point to the same date and time. - -##### httpOnly - -Specifies the `boolean` value for the [`HttpOnly` `Set-Cookie` attribute][rfc-6266-5.2.6]. When truthy, -the `HttpOnly` attribute is set, otherwise it is not. By default, the `HttpOnly` attribute is not set. - -**note** be careful when setting this to `true`, as compliant clients will not allow client-side -JavaScript to see the cookie in `document.cookie`. - -##### maxAge - -Specifies the `number` (in seconds) to be the value for the [`Max-Age` `Set-Cookie` attribute][rfc-6266-5.2.2]. -The given number will be converted to an integer by rounding down. By default, no maximum age is set. - -**note** the [cookie storage model specification][rfc-6266-5.3] states that if both `expires` and -`magAge` are set, then `maxAge` takes precedence, but it is possiblke not all clients by obey this, -so if both are set, they should point to the same date and time. - -##### path - -Specifies the value for the [`Path` `Set-Cookie` attribute][rfc-6266-5.2.4]. By default, the path -is considered the ["default path"][rfc-6266-5.1.4]. By default, no maximum age is set, and most -clients will consider this a "non-persistent cookie" and will delete it on a condition like exiting -a web browser application. - -##### sameSite - -Specifies the `boolean` or `string` to be the value for the [`SameSite` `Set-Cookie` attribute][draft-west-first-party-cookies-07]. - - - `true` will set the `SameSite` attribute to `Strict` for strict same site enforcement. - - `false` will not set the `SameSite` attribute. - - `'lax'` will set the `SameSite` attribute to `Lax` for lax same site enforcement. - - `'strict'` will set the `SameSite` attribute to `Strict` for strict same site enforcement. - -More information about the different enforcement levels can be found in the specification -https://tools.ietf.org/html/draft-west-first-party-cookies-07#section-4.1.1 - -**note** This is an attribute that has not yet been fully standardized, and may change in the future. -This also means many clients may ignore this attribute until they understand it. - -##### secure - -Specifies the `boolean` value for the [`Secure` `Set-Cookie` attribute][rfc-6266-5.2.5]. When truthy, -the `Secure` attribute is set, otherwise it is not. By default, the `Secure` attribute is not set. - -**note** be careful when setting this to `true`, as compliant clients will not send the cookie back to -the server in the future if the browser does not have an HTTPS connection. - -## Example - -The following example uses this module in conjunction with the Node.js core HTTP server -to prompt a user for their name and display it back on future visits. - -```js -var cookie = require('cookie'); -var escapeHtml = require('escape-html'); -var http = require('http'); -var url = require('url'); - -function onRequest(req, res) { - // Parse the query string - var query = url.parse(req.url, true, true).query; - - if (query && query.name) { - // Set a new cookie with the name - res.setHeader('Set-Cookie', cookie.serialize('name', String(query.name), { - httpOnly: true, - maxAge: 60 * 60 * 24 * 7 // 1 week - })); - - // Redirect back after setting cookie - res.statusCode = 302; - res.setHeader('Location', req.headers.referer || '/'); - res.end(); - return; - } - - // Parse the cookies on the request - var cookies = cookie.parse(req.headers.cookie || ''); - - // Get the visitor name set in the cookie - var name = cookies.name; - - res.setHeader('Content-Type', 'text/html; charset=UTF-8'); - - if (name) { - res.write('<p>Welcome back, <b>' + escapeHtml(name) + '</b>!</p>'); - } else { - res.write('<p>Hello, new visitor!</p>'); - } - - res.write('<form method="GET">'); - res.write('<input placeholder="enter your name" name="name"> <input type="submit" value="Set Name">'); - res.end('</form'); -} - -http.createServer(onRequest).listen(3000); -``` - -## Testing - -```sh -$ npm test -``` - -## References - -- [RFC 6266: HTTP State Management Mechanism][rfc-6266] -- [Same-site Cookies][draft-west-first-party-cookies-07] - -[draft-west-first-party-cookies-07]: https://tools.ietf.org/html/draft-west-first-party-cookies-07 -[rfc-6266]: https://tools.ietf.org/html/rfc6266 -[rfc-6266-5.1.4]: https://tools.ietf.org/html/rfc6266#section-5.1.4 -[rfc-6266-5.2.1]: https://tools.ietf.org/html/rfc6266#section-5.2.1 -[rfc-6266-5.2.2]: https://tools.ietf.org/html/rfc6266#section-5.2.2 -[rfc-6266-5.2.3]: https://tools.ietf.org/html/rfc6266#section-5.2.3 -[rfc-6266-5.2.4]: https://tools.ietf.org/html/rfc6266#section-5.2.4 -[rfc-6266-5.3]: https://tools.ietf.org/html/rfc6266#section-5.3 - -## License - -[MIT](LICENSE) - -[npm-image]: https://img.shields.io/npm/v/cookie.svg -[npm-url]: https://npmjs.org/package/cookie -[node-version-image]: https://img.shields.io/node/v/cookie.svg -[node-version-url]: https://nodejs.org/en/download -[travis-image]: https://img.shields.io/travis/jshttp/cookie/master.svg -[travis-url]: https://travis-ci.org/jshttp/cookie -[coveralls-image]: https://img.shields.io/coveralls/jshttp/cookie/master.svg -[coveralls-url]: https://coveralls.io/r/jshttp/cookie?branch=master -[downloads-image]: https://img.shields.io/npm/dm/cookie.svg -[downloads-url]: https://npmjs.org/package/cookie |