Osamu Nakamura
/
GR-PEACH_mbed-os-QRCode-ShoppingCart-node
Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
node_modules/mbed-connector-api/node_modules/request/node_modules/tough-cookie/README.md@0:a40b9a259b52, 2018-01-12 (annotated)
- Committer:
- Osamu Nakamura
- Date:
- Fri Jan 12 19:05:14 2018 +0900
- Revision:
- 0:a40b9a259b52
Initial commit
Who changed what in which revision?
| User | Revision | Line number | New contents of line |
|---|---|---|---|
| Osamu Nakamura |
0:a40b9a259b52 | 1 | [RFC6265](https://tools.ietf.org/html/rfc6265) Cookies and CookieJar for Node.js |
| Osamu Nakamura |
0:a40b9a259b52 | 2 | |
| Osamu Nakamura |
0:a40b9a259b52 | 3 | [](https://nodei.co/npm/tough-cookie/) |
| Osamu Nakamura |
0:a40b9a259b52 | 4 | |
| Osamu Nakamura |
0:a40b9a259b52 | 5 | [](https://travis-ci.org/salesforce/tough-cookie) |
| Osamu Nakamura |
0:a40b9a259b52 | 6 | |
| Osamu Nakamura |
0:a40b9a259b52 | 7 | # Synopsis |
| Osamu Nakamura |
0:a40b9a259b52 | 8 | |
| Osamu Nakamura |
0:a40b9a259b52 | 9 | ``` javascript |
| Osamu Nakamura |
0:a40b9a259b52 | 10 | var tough = require('tough-cookie'); |
| Osamu Nakamura |
0:a40b9a259b52 | 11 | var Cookie = tough.Cookie; |
| Osamu Nakamura |
0:a40b9a259b52 | 12 | var cookie = Cookie.parse(header); |
| Osamu Nakamura |
0:a40b9a259b52 | 13 | cookie.value = 'somethingdifferent'; |
| Osamu Nakamura |
0:a40b9a259b52 | 14 | header = cookie.toString(); |
| Osamu Nakamura |
0:a40b9a259b52 | 15 | |
| Osamu Nakamura |
0:a40b9a259b52 | 16 | var cookiejar = new tough.CookieJar(); |
| Osamu Nakamura |
0:a40b9a259b52 | 17 | cookiejar.setCookie(cookie, 'http://currentdomain.example.com/path', cb); |
| Osamu Nakamura |
0:a40b9a259b52 | 18 | // ... |
| Osamu Nakamura |
0:a40b9a259b52 | 19 | cookiejar.getCookies('http://example.com/otherpath',function(err,cookies) { |
| Osamu Nakamura |
0:a40b9a259b52 | 20 | res.headers['cookie'] = cookies.join('; '); |
| Osamu Nakamura |
0:a40b9a259b52 | 21 | }); |
| Osamu Nakamura |
0:a40b9a259b52 | 22 | ``` |
| Osamu Nakamura |
0:a40b9a259b52 | 23 | |
| Osamu Nakamura |
0:a40b9a259b52 | 24 | # Installation |
| Osamu Nakamura |
0:a40b9a259b52 | 25 | |
| Osamu Nakamura |
0:a40b9a259b52 | 26 | It's _so_ easy! |
| Osamu Nakamura |
0:a40b9a259b52 | 27 | |
| Osamu Nakamura |
0:a40b9a259b52 | 28 | `npm install tough-cookie` |
| Osamu Nakamura |
0:a40b9a259b52 | 29 | |
| Osamu Nakamura |
0:a40b9a259b52 | 30 | Why the name? NPM modules `cookie`, `cookies` and `cookiejar` were already taken. |
| Osamu Nakamura |
0:a40b9a259b52 | 31 | |
| Osamu Nakamura |
0:a40b9a259b52 | 32 | ## Version Support |
| Osamu Nakamura |
0:a40b9a259b52 | 33 | |
| Osamu Nakamura |
0:a40b9a259b52 | 34 | Support for versions of node.js will follow that of the [request](https://www.npmjs.com/package/request) module. |
| Osamu Nakamura |
0:a40b9a259b52 | 35 | |
| Osamu Nakamura |
0:a40b9a259b52 | 36 | # API |
| Osamu Nakamura |
0:a40b9a259b52 | 37 | |
| Osamu Nakamura |
0:a40b9a259b52 | 38 | ## tough |
| Osamu Nakamura |
0:a40b9a259b52 | 39 | |
| Osamu Nakamura |
0:a40b9a259b52 | 40 | Functions on the module you get from `require('tough-cookie')`. All can be used as pure functions and don't need to be "bound". |
| Osamu Nakamura |
0:a40b9a259b52 | 41 | |
| Osamu Nakamura |
0:a40b9a259b52 | 42 | **Note**: prior to 1.0.x, several of these functions took a `strict` parameter. This has since been removed from the API as it was no longer necessary. |
| Osamu Nakamura |
0:a40b9a259b52 | 43 | |
| Osamu Nakamura |
0:a40b9a259b52 | 44 | ### `parseDate(string)` |
| Osamu Nakamura |
0:a40b9a259b52 | 45 | |
| Osamu Nakamura |
0:a40b9a259b52 | 46 | Parse a cookie date string into a `Date`. Parses according to RFC6265 Section 5.1.1, not `Date.parse()`. |
| Osamu Nakamura |
0:a40b9a259b52 | 47 | |
| Osamu Nakamura |
0:a40b9a259b52 | 48 | ### `formatDate(date)` |
| Osamu Nakamura |
0:a40b9a259b52 | 49 | |
| Osamu Nakamura |
0:a40b9a259b52 | 50 | Format a Date into a RFC1123 string (the RFC6265-recommended format). |
| Osamu Nakamura |
0:a40b9a259b52 | 51 | |
| Osamu Nakamura |
0:a40b9a259b52 | 52 | ### `canonicalDomain(str)` |
| Osamu Nakamura |
0:a40b9a259b52 | 53 | |
| Osamu Nakamura |
0:a40b9a259b52 | 54 | Transforms a domain-name into a canonical domain-name. The canonical domain-name is a trimmed, lowercased, stripped-of-leading-dot and optionally punycode-encoded domain-name (Section 5.1.2 of RFC6265). For the most part, this function is idempotent (can be run again on its output without ill effects). |
| Osamu Nakamura |
0:a40b9a259b52 | 55 | |
| Osamu Nakamura |
0:a40b9a259b52 | 56 | ### `domainMatch(str,domStr[,canonicalize=true])` |
| Osamu Nakamura |
0:a40b9a259b52 | 57 | |
| Osamu Nakamura |
0:a40b9a259b52 | 58 | Answers "does this real domain match the domain in a cookie?". The `str` is the "current" domain-name and the `domStr` is the "cookie" domain-name. Matches according to RFC6265 Section 5.1.3, but it helps to think of it as a "suffix match". |
| Osamu Nakamura |
0:a40b9a259b52 | 59 | |
| Osamu Nakamura |
0:a40b9a259b52 | 60 | The `canonicalize` parameter will run the other two paramters through `canonicalDomain` or not. |
| Osamu Nakamura |
0:a40b9a259b52 | 61 | |
| Osamu Nakamura |
0:a40b9a259b52 | 62 | ### `defaultPath(path)` |
| Osamu Nakamura |
0:a40b9a259b52 | 63 | |
| Osamu Nakamura |
0:a40b9a259b52 | 64 | Given a current request/response path, gives the Path apropriate for storing in a cookie. This is basically the "directory" of a "file" in the path, but is specified by Section 5.1.4 of the RFC. |
| Osamu Nakamura |
0:a40b9a259b52 | 65 | |
| Osamu Nakamura |
0:a40b9a259b52 | 66 | The `path` parameter MUST be _only_ the pathname part of a URI (i.e. excludes the hostname, query, fragment, etc.). This is the `.pathname` property of node's `uri.parse()` output. |
| Osamu Nakamura |
0:a40b9a259b52 | 67 | |
| Osamu Nakamura |
0:a40b9a259b52 | 68 | ### `pathMatch(reqPath,cookiePath)` |
| Osamu Nakamura |
0:a40b9a259b52 | 69 | |
| Osamu Nakamura |
0:a40b9a259b52 | 70 | Answers "does the request-path path-match a given cookie-path?" as per RFC6265 Section 5.1.4. Returns a boolean. |
| Osamu Nakamura |
0:a40b9a259b52 | 71 | |
| Osamu Nakamura |
0:a40b9a259b52 | 72 | This is essentially a prefix-match where `cookiePath` is a prefix of `reqPath`. |
| Osamu Nakamura |
0:a40b9a259b52 | 73 | |
| Osamu Nakamura |
0:a40b9a259b52 | 74 | ### `parse(cookieString[, options])` |
| Osamu Nakamura |
0:a40b9a259b52 | 75 | |
| Osamu Nakamura |
0:a40b9a259b52 | 76 | alias for `Cookie.parse(cookieString[, options])` |
| Osamu Nakamura |
0:a40b9a259b52 | 77 | |
| Osamu Nakamura |
0:a40b9a259b52 | 78 | ### `fromJSON(string)` |
| Osamu Nakamura |
0:a40b9a259b52 | 79 | |
| Osamu Nakamura |
0:a40b9a259b52 | 80 | alias for `Cookie.fromJSON(string)` |
| Osamu Nakamura |
0:a40b9a259b52 | 81 | |
| Osamu Nakamura |
0:a40b9a259b52 | 82 | ### `getPublicSuffix(hostname)` |
| Osamu Nakamura |
0:a40b9a259b52 | 83 | |
| Osamu Nakamura |
0:a40b9a259b52 | 84 | Returns the public suffix of this hostname. The public suffix is the shortest domain-name upon which a cookie can be set. Returns `null` if the hostname cannot have cookies set for it. |
| Osamu Nakamura |
0:a40b9a259b52 | 85 | |
| Osamu Nakamura |
0:a40b9a259b52 | 86 | For example: `www.example.com` and `www.subdomain.example.com` both have public suffix `example.com`. |
| Osamu Nakamura |
0:a40b9a259b52 | 87 | |
| Osamu Nakamura |
0:a40b9a259b52 | 88 | For further information, see http://publicsuffix.org/. This module derives its list from that site. |
| Osamu Nakamura |
0:a40b9a259b52 | 89 | |
| Osamu Nakamura |
0:a40b9a259b52 | 90 | ### `cookieCompare(a,b)` |
| Osamu Nakamura |
0:a40b9a259b52 | 91 | |
| Osamu Nakamura |
0:a40b9a259b52 | 92 | For use with `.sort()`, sorts a list of cookies into the recommended order given in the RFC (Section 5.4 step 2). The sort algorithm is, in order of precedence: |
| Osamu Nakamura |
0:a40b9a259b52 | 93 | |
| Osamu Nakamura |
0:a40b9a259b52 | 94 | * Longest `.path` |
| Osamu Nakamura |
0:a40b9a259b52 | 95 | * oldest `.creation` (which has a 1ms precision, same as `Date`) |
| Osamu Nakamura |
0:a40b9a259b52 | 96 | * lowest `.creationIndex` (to get beyond the 1ms precision) |
| Osamu Nakamura |
0:a40b9a259b52 | 97 | |
| Osamu Nakamura |
0:a40b9a259b52 | 98 | ``` javascript |
| Osamu Nakamura |
0:a40b9a259b52 | 99 | var cookies = [ /* unsorted array of Cookie objects */ ]; |
| Osamu Nakamura |
0:a40b9a259b52 | 100 | cookies = cookies.sort(cookieCompare); |
| Osamu Nakamura |
0:a40b9a259b52 | 101 | ``` |
| Osamu Nakamura |
0:a40b9a259b52 | 102 | |
| Osamu Nakamura |
0:a40b9a259b52 | 103 | **Note**: Since JavaScript's `Date` is limited to a 1ms precision, cookies within the same milisecond are entirely possible. This is especially true when using the `now` option to `.setCookie()`. The `.creationIndex` property is a per-process global counter, assigned during construction with `new Cookie()`. This preserves the spirit of the RFC sorting: older cookies go first. This works great for `MemoryCookieStore`, since `Set-Cookie` headers are parsed in order, but may not be so great for distributed systems. Sophisticated `Store`s may wish to set this to some other _logical clock_ such that if cookies A and B are created in the same millisecond, but cookie A is created before cookie B, then `A.creationIndex < B.creationIndex`. If you want to alter the global counter, which you probably _shouldn't_ do, it's stored in `Cookie.cookiesCreated`. |
| Osamu Nakamura |
0:a40b9a259b52 | 104 | |
| Osamu Nakamura |
0:a40b9a259b52 | 105 | ### `permuteDomain(domain)` |
| Osamu Nakamura |
0:a40b9a259b52 | 106 | |
| Osamu Nakamura |
0:a40b9a259b52 | 107 | Generates a list of all possible domains that `domainMatch()` the parameter. May be handy for implementing cookie stores. |
| Osamu Nakamura |
0:a40b9a259b52 | 108 | |
| Osamu Nakamura |
0:a40b9a259b52 | 109 | ### `permutePath(path)` |
| Osamu Nakamura |
0:a40b9a259b52 | 110 | |
| Osamu Nakamura |
0:a40b9a259b52 | 111 | Generates a list of all possible paths that `pathMatch()` the parameter. May be handy for implementing cookie stores. |
| Osamu Nakamura |
0:a40b9a259b52 | 112 | |
| Osamu Nakamura |
0:a40b9a259b52 | 113 | |
| Osamu Nakamura |
0:a40b9a259b52 | 114 | ## Cookie |
| Osamu Nakamura |
0:a40b9a259b52 | 115 | |
| Osamu Nakamura |
0:a40b9a259b52 | 116 | Exported via `tough.Cookie`. |
| Osamu Nakamura |
0:a40b9a259b52 | 117 | |
| Osamu Nakamura |
0:a40b9a259b52 | 118 | ### `Cookie.parse(cookieString[, options])` |
| Osamu Nakamura |
0:a40b9a259b52 | 119 | |
| Osamu Nakamura |
0:a40b9a259b52 | 120 | Parses a single Cookie or Set-Cookie HTTP header into a `Cookie` object. Returns `undefined` if the string can't be parsed. |
| Osamu Nakamura |
0:a40b9a259b52 | 121 | |
| Osamu Nakamura |
0:a40b9a259b52 | 122 | The options parameter is not required and currently has only one property: |
| Osamu Nakamura |
0:a40b9a259b52 | 123 | |
| Osamu Nakamura |
0:a40b9a259b52 | 124 | * _loose_ - boolean - if `true` enable parsing of key-less cookies like `=abc` and `=`, which are not RFC-compliant. |
| Osamu Nakamura |
0:a40b9a259b52 | 125 | |
| Osamu Nakamura |
0:a40b9a259b52 | 126 | If options is not an object, it is ignored, which means you can use `Array#map` with it. |
| Osamu Nakamura |
0:a40b9a259b52 | 127 | |
| Osamu Nakamura |
0:a40b9a259b52 | 128 | Here's how to process the Set-Cookie header(s) on a node HTTP/HTTPS response: |
| Osamu Nakamura |
0:a40b9a259b52 | 129 | |
| Osamu Nakamura |
0:a40b9a259b52 | 130 | ``` javascript |
| Osamu Nakamura |
0:a40b9a259b52 | 131 | if (res.headers['set-cookie'] instanceof Array) |
| Osamu Nakamura |
0:a40b9a259b52 | 132 | cookies = res.headers['set-cookie'].map(Cookie.parse); |
| Osamu Nakamura |
0:a40b9a259b52 | 133 | else |
| Osamu Nakamura |
0:a40b9a259b52 | 134 | cookies = [Cookie.parse(res.headers['set-cookie'])]; |
| Osamu Nakamura |
0:a40b9a259b52 | 135 | ``` |
| Osamu Nakamura |
0:a40b9a259b52 | 136 | |
| Osamu Nakamura |
0:a40b9a259b52 | 137 | ### Properties |
| Osamu Nakamura |
0:a40b9a259b52 | 138 | |
| Osamu Nakamura |
0:a40b9a259b52 | 139 | Cookie object properties: |
| Osamu Nakamura |
0:a40b9a259b52 | 140 | |
| Osamu Nakamura |
0:a40b9a259b52 | 141 | * _key_ - string - the name or key of the cookie (default "") |
| Osamu Nakamura |
0:a40b9a259b52 | 142 | * _value_ - string - the value of the cookie (default "") |
| Osamu Nakamura |
0:a40b9a259b52 | 143 | * _expires_ - `Date` - if set, the `Expires=` attribute of the cookie (defaults to the string `"Infinity"`). See `setExpires()` |
| Osamu Nakamura |
0:a40b9a259b52 | 144 | * _maxAge_ - seconds - if set, the `Max-Age=` attribute _in seconds_ of the cookie. May also be set to strings `"Infinity"` and `"-Infinity"` for non-expiry and immediate-expiry, respectively. See `setMaxAge()` |
| Osamu Nakamura |
0:a40b9a259b52 | 145 | * _domain_ - string - the `Domain=` attribute of the cookie |
| Osamu Nakamura |
0:a40b9a259b52 | 146 | * _path_ - string - the `Path=` of the cookie |
| Osamu Nakamura |
0:a40b9a259b52 | 147 | * _secure_ - boolean - the `Secure` cookie flag |
| Osamu Nakamura |
0:a40b9a259b52 | 148 | * _httpOnly_ - boolean - the `HttpOnly` cookie flag |
| Osamu Nakamura |
0:a40b9a259b52 | 149 | * _extensions_ - `Array` - any unrecognized cookie attributes as strings (even if equal-signs inside) |
| Osamu Nakamura |
0:a40b9a259b52 | 150 | * _creation_ - `Date` - when this cookie was constructed |
| Osamu Nakamura |
0:a40b9a259b52 | 151 | * _creationIndex_ - number - set at construction, used to provide greater sort precision (please see `cookieCompare(a,b)` for a full explanation) |
| Osamu Nakamura |
0:a40b9a259b52 | 152 | |
| Osamu Nakamura |
0:a40b9a259b52 | 153 | After a cookie has been passed through `CookieJar.setCookie()` it will have the following additional attributes: |
| Osamu Nakamura |
0:a40b9a259b52 | 154 | |
| Osamu Nakamura |
0:a40b9a259b52 | 155 | * _hostOnly_ - boolean - is this a host-only cookie (i.e. no Domain field was set, but was instead implied) |
| Osamu Nakamura |
0:a40b9a259b52 | 156 | * _pathIsDefault_ - boolean - if true, there was no Path field on the cookie and `defaultPath()` was used to derive one. |
| Osamu Nakamura |
0:a40b9a259b52 | 157 | * _creation_ - `Date` - **modified** from construction to when the cookie was added to the jar |
| Osamu Nakamura |
0:a40b9a259b52 | 158 | * _lastAccessed_ - `Date` - last time the cookie got accessed. Will affect cookie cleaning once implemented. Using `cookiejar.getCookies(...)` will update this attribute. |
| Osamu Nakamura |
0:a40b9a259b52 | 159 | |
| Osamu Nakamura |
0:a40b9a259b52 | 160 | ### `Cookie([{properties}])` |
| Osamu Nakamura |
0:a40b9a259b52 | 161 | |
| Osamu Nakamura |
0:a40b9a259b52 | 162 | Receives an options object that can contain any of the above Cookie properties, uses the default for unspecified properties. |
| Osamu Nakamura |
0:a40b9a259b52 | 163 | |
| Osamu Nakamura |
0:a40b9a259b52 | 164 | ### `.toString()` |
| Osamu Nakamura |
0:a40b9a259b52 | 165 | |
| Osamu Nakamura |
0:a40b9a259b52 | 166 | encode to a Set-Cookie header value. The Expires cookie field is set using `formatDate()`, but is omitted entirely if `.expires` is `Infinity`. |
| Osamu Nakamura |
0:a40b9a259b52 | 167 | |
| Osamu Nakamura |
0:a40b9a259b52 | 168 | ### `.cookieString()` |
| Osamu Nakamura |
0:a40b9a259b52 | 169 | |
| Osamu Nakamura |
0:a40b9a259b52 | 170 | encode to a Cookie header value (i.e. the `.key` and `.value` properties joined with '='). |
| Osamu Nakamura |
0:a40b9a259b52 | 171 | |
| Osamu Nakamura |
0:a40b9a259b52 | 172 | ### `.setExpires(String)` |
| Osamu Nakamura |
0:a40b9a259b52 | 173 | |
| Osamu Nakamura |
0:a40b9a259b52 | 174 | sets the expiry based on a date-string passed through `parseDate()`. If parseDate returns `null` (i.e. can't parse this date string), `.expires` is set to `"Infinity"` (a string) is set. |
| Osamu Nakamura |
0:a40b9a259b52 | 175 | |
| Osamu Nakamura |
0:a40b9a259b52 | 176 | ### `.setMaxAge(number)` |
| Osamu Nakamura |
0:a40b9a259b52 | 177 | |
| Osamu Nakamura |
0:a40b9a259b52 | 178 | sets the maxAge in seconds. Coerces `-Infinity` to `"-Infinity"` and `Infinity` to `"Infinity"` so it JSON serializes correctly. |
| Osamu Nakamura |
0:a40b9a259b52 | 179 | |
| Osamu Nakamura |
0:a40b9a259b52 | 180 | ### `.expiryTime([now=Date.now()])` |
| Osamu Nakamura |
0:a40b9a259b52 | 181 | |
| Osamu Nakamura |
0:a40b9a259b52 | 182 | ### `.expiryDate([now=Date.now()])` |
| Osamu Nakamura |
0:a40b9a259b52 | 183 | |
| Osamu Nakamura |
0:a40b9a259b52 | 184 | expiryTime() Computes the absolute unix-epoch milliseconds that this cookie expires. expiryDate() works similarly, except it returns a `Date` object. Note that in both cases the `now` parameter should be milliseconds. |
| Osamu Nakamura |
0:a40b9a259b52 | 185 | |
| Osamu Nakamura |
0:a40b9a259b52 | 186 | Max-Age takes precedence over Expires (as per the RFC). The `.creation` attribute -- or, by default, the `now` paramter -- is used to offset the `.maxAge` attribute. |
| Osamu Nakamura |
0:a40b9a259b52 | 187 | |
| Osamu Nakamura |
0:a40b9a259b52 | 188 | If Expires (`.expires`) is set, that's returned. |
| Osamu Nakamura |
0:a40b9a259b52 | 189 | |
| Osamu Nakamura |
0:a40b9a259b52 | 190 | Otherwise, `expiryTime()` returns `Infinity` and `expiryDate()` returns a `Date` object for "Tue, 19 Jan 2038 03:14:07 GMT" (latest date that can be expressed by a 32-bit `time_t`; the common limit for most user-agents). |
| Osamu Nakamura |
0:a40b9a259b52 | 191 | |
| Osamu Nakamura |
0:a40b9a259b52 | 192 | ### `.TTL([now=Date.now()])` |
| Osamu Nakamura |
0:a40b9a259b52 | 193 | |
| Osamu Nakamura |
0:a40b9a259b52 | 194 | compute the TTL relative to `now` (milliseconds). The same precedence rules as for `expiryTime`/`expiryDate` apply. |
| Osamu Nakamura |
0:a40b9a259b52 | 195 | |
| Osamu Nakamura |
0:a40b9a259b52 | 196 | The "number" `Infinity` is returned for cookies without an explicit expiry and `0` is returned if the cookie is expired. Otherwise a time-to-live in milliseconds is returned. |
| Osamu Nakamura |
0:a40b9a259b52 | 197 | |
| Osamu Nakamura |
0:a40b9a259b52 | 198 | ### `.canonicalizedDoman()` |
| Osamu Nakamura |
0:a40b9a259b52 | 199 | |
| Osamu Nakamura |
0:a40b9a259b52 | 200 | ### `.cdomain()` |
| Osamu Nakamura |
0:a40b9a259b52 | 201 | |
| Osamu Nakamura |
0:a40b9a259b52 | 202 | return the canonicalized `.domain` field. This is lower-cased and punycode (RFC3490) encoded if the domain has any non-ASCII characters. |
| Osamu Nakamura |
0:a40b9a259b52 | 203 | |
| Osamu Nakamura |
0:a40b9a259b52 | 204 | ### `.toJSON()` |
| Osamu Nakamura |
0:a40b9a259b52 | 205 | |
| Osamu Nakamura |
0:a40b9a259b52 | 206 | For convenience in using `JSON.serialize(cookie)`. Returns a plain-old `Object` that can be JSON-serialized. |
| Osamu Nakamura |
0:a40b9a259b52 | 207 | |
| Osamu Nakamura |
0:a40b9a259b52 | 208 | Any `Date` properties (i.e., `.expires`, `.creation`, and `.lastAccessed`) are exported in ISO format (`.toISOString()`). |
| Osamu Nakamura |
0:a40b9a259b52 | 209 | |
| Osamu Nakamura |
0:a40b9a259b52 | 210 | **NOTE**: Custom `Cookie` properties will be discarded. In tough-cookie 1.x, since there was no `.toJSON` method explicitly defined, all enumerable properties were captured. If you want a property to be serialized, add the property name to the `Cookie.serializableProperties` Array. |
| Osamu Nakamura |
0:a40b9a259b52 | 211 | |
| Osamu Nakamura |
0:a40b9a259b52 | 212 | ### `Cookie.fromJSON(strOrObj)` |
| Osamu Nakamura |
0:a40b9a259b52 | 213 | |
| Osamu Nakamura |
0:a40b9a259b52 | 214 | Does the reverse of `cookie.toJSON()`. If passed a string, will `JSON.parse()` that first. |
| Osamu Nakamura |
0:a40b9a259b52 | 215 | |
| Osamu Nakamura |
0:a40b9a259b52 | 216 | Any `Date` properties (i.e., `.expires`, `.creation`, and `.lastAccessed`) are parsed via `Date.parse()`, not the tough-cookie `parseDate`, since it's JavaScript/JSON-y timestamps being handled at this layer. |
| Osamu Nakamura |
0:a40b9a259b52 | 217 | |
| Osamu Nakamura |
0:a40b9a259b52 | 218 | Returns `null` upon JSON parsing error. |
| Osamu Nakamura |
0:a40b9a259b52 | 219 | |
| Osamu Nakamura |
0:a40b9a259b52 | 220 | ### `.clone()` |
| Osamu Nakamura |
0:a40b9a259b52 | 221 | |
| Osamu Nakamura |
0:a40b9a259b52 | 222 | Does a deep clone of this cookie, exactly implemented as `Cookie.fromJSON(cookie.toJSON())`. |
| Osamu Nakamura |
0:a40b9a259b52 | 223 | |
| Osamu Nakamura |
0:a40b9a259b52 | 224 | ### `.validate()` |
| Osamu Nakamura |
0:a40b9a259b52 | 225 | |
| Osamu Nakamura |
0:a40b9a259b52 | 226 | Status: *IN PROGRESS*. Works for a few things, but is by no means comprehensive. |
| Osamu Nakamura |
0:a40b9a259b52 | 227 | |
| Osamu Nakamura |
0:a40b9a259b52 | 228 | validates cookie attributes for semantic correctness. Useful for "lint" checking any Set-Cookie headers you generate. For now, it returns a boolean, but eventually could return a reason string -- you can future-proof with this construct: |
| Osamu Nakamura |
0:a40b9a259b52 | 229 | |
| Osamu Nakamura |
0:a40b9a259b52 | 230 | ``` javascript |
| Osamu Nakamura |
0:a40b9a259b52 | 231 | if (cookie.validate() === true) { |
| Osamu Nakamura |
0:a40b9a259b52 | 232 | // it's tasty |
| Osamu Nakamura |
0:a40b9a259b52 | 233 | } else { |
| Osamu Nakamura |
0:a40b9a259b52 | 234 | // yuck! |
| Osamu Nakamura |
0:a40b9a259b52 | 235 | } |
| Osamu Nakamura |
0:a40b9a259b52 | 236 | ``` |
| Osamu Nakamura |
0:a40b9a259b52 | 237 | |
| Osamu Nakamura |
0:a40b9a259b52 | 238 | |
| Osamu Nakamura |
0:a40b9a259b52 | 239 | ## CookieJar |
| Osamu Nakamura |
0:a40b9a259b52 | 240 | |
| Osamu Nakamura |
0:a40b9a259b52 | 241 | Exported via `tough.CookieJar`. |
| Osamu Nakamura |
0:a40b9a259b52 | 242 | |
| Osamu Nakamura |
0:a40b9a259b52 | 243 | ### `CookieJar([store],[options])` |
| Osamu Nakamura |
0:a40b9a259b52 | 244 | |
| Osamu Nakamura |
0:a40b9a259b52 | 245 | Simply use `new CookieJar()`. If you'd like to use a custom store, pass that to the constructor otherwise a `MemoryCookieStore` will be created and used. |
| Osamu Nakamura |
0:a40b9a259b52 | 246 | |
| Osamu Nakamura |
0:a40b9a259b52 | 247 | The `options` object can be omitted and can have the following properties: |
| Osamu Nakamura |
0:a40b9a259b52 | 248 | |
| Osamu Nakamura |
0:a40b9a259b52 | 249 | * _rejectPublicSuffixes_ - boolean - default `true` - reject cookies with domains like "com" and "co.uk" |
| Osamu Nakamura |
0:a40b9a259b52 | 250 | * _looseMode_ - boolean - default `false` - accept malformed cookies like `bar` and `=bar`, which have an implied empty name. |
| Osamu Nakamura |
0:a40b9a259b52 | 251 | This is not in the standard, but is used sometimes on the web and is accepted by (most) browsers. |
| Osamu Nakamura |
0:a40b9a259b52 | 252 | |
| Osamu Nakamura |
0:a40b9a259b52 | 253 | Since eventually this module would like to support database/remote/etc. CookieJars, continuation passing style is used for CookieJar methods. |
| Osamu Nakamura |
0:a40b9a259b52 | 254 | |
| Osamu Nakamura |
0:a40b9a259b52 | 255 | ### `.setCookie(cookieOrString, currentUrl, [{options},] cb(err,cookie))` |
| Osamu Nakamura |
0:a40b9a259b52 | 256 | |
| Osamu Nakamura |
0:a40b9a259b52 | 257 | Attempt to set the cookie in the cookie jar. If the operation fails, an error will be given to the callback `cb`, otherwise the cookie is passed through. The cookie will have updated `.creation`, `.lastAccessed` and `.hostOnly` properties. |
| Osamu Nakamura |
0:a40b9a259b52 | 258 | |
| Osamu Nakamura |
0:a40b9a259b52 | 259 | The `options` object can be omitted and can have the following properties: |
| Osamu Nakamura |
0:a40b9a259b52 | 260 | |
| Osamu Nakamura |
0:a40b9a259b52 | 261 | * _http_ - boolean - default `true` - indicates if this is an HTTP or non-HTTP API. Affects HttpOnly cookies. |
| Osamu Nakamura |
0:a40b9a259b52 | 262 | * _secure_ - boolean - autodetect from url - indicates if this is a "Secure" API. If the currentUrl starts with `https:` or `wss:` then this is defaulted to `true`, otherwise `false`. |
| Osamu Nakamura |
0:a40b9a259b52 | 263 | * _now_ - Date - default `new Date()` - what to use for the creation/access time of cookies |
| Osamu Nakamura |
0:a40b9a259b52 | 264 | * _ignoreError_ - boolean - default `false` - silently ignore things like parse errors and invalid domains. `Store` errors aren't ignored by this option. |
| Osamu Nakamura |
0:a40b9a259b52 | 265 | |
| Osamu Nakamura |
0:a40b9a259b52 | 266 | As per the RFC, the `.hostOnly` property is set if there was no "Domain=" parameter in the cookie string (or `.domain` was null on the Cookie object). The `.domain` property is set to the fully-qualified hostname of `currentUrl` in this case. Matching this cookie requires an exact hostname match (not a `domainMatch` as per usual). |
| Osamu Nakamura |
0:a40b9a259b52 | 267 | |
| Osamu Nakamura |
0:a40b9a259b52 | 268 | ### `.setCookieSync(cookieOrString, currentUrl, [{options}])` |
| Osamu Nakamura |
0:a40b9a259b52 | 269 | |
| Osamu Nakamura |
0:a40b9a259b52 | 270 | Synchronous version of `setCookie`; only works with synchronous stores (e.g. the default `MemoryCookieStore`). |
| Osamu Nakamura |
0:a40b9a259b52 | 271 | |
| Osamu Nakamura |
0:a40b9a259b52 | 272 | ### `.getCookies(currentUrl, [{options},] cb(err,cookies))` |
| Osamu Nakamura |
0:a40b9a259b52 | 273 | |
| Osamu Nakamura |
0:a40b9a259b52 | 274 | Retrieve the list of cookies that can be sent in a Cookie header for the current url. |
| Osamu Nakamura |
0:a40b9a259b52 | 275 | |
| Osamu Nakamura |
0:a40b9a259b52 | 276 | If an error is encountered, that's passed as `err` to the callback, otherwise an `Array` of `Cookie` objects is passed. The array is sorted with `cookieCompare()` unless the `{sort:false}` option is given. |
| Osamu Nakamura |
0:a40b9a259b52 | 277 | |
| Osamu Nakamura |
0:a40b9a259b52 | 278 | The `options` object can be omitted and can have the following properties: |
| Osamu Nakamura |
0:a40b9a259b52 | 279 | |
| Osamu Nakamura |
0:a40b9a259b52 | 280 | * _http_ - boolean - default `true` - indicates if this is an HTTP or non-HTTP API. Affects HttpOnly cookies. |
| Osamu Nakamura |
0:a40b9a259b52 | 281 | * _secure_ - boolean - autodetect from url - indicates if this is a "Secure" API. If the currentUrl starts with `https:` or `wss:` then this is defaulted to `true`, otherwise `false`. |
| Osamu Nakamura |
0:a40b9a259b52 | 282 | * _now_ - Date - default `new Date()` - what to use for the creation/access time of cookies |
| Osamu Nakamura |
0:a40b9a259b52 | 283 | * _expire_ - boolean - default `true` - perform expiry-time checking of cookies and asynchronously remove expired cookies from the store. Using `false` will return expired cookies and **not** remove them from the store (which is useful for replaying Set-Cookie headers, potentially). |
| Osamu Nakamura |
0:a40b9a259b52 | 284 | * _allPaths_ - boolean - default `false` - if `true`, do not scope cookies by path. The default uses RFC-compliant path scoping. **Note**: may not be supported by the underlying store (the default `MemoryCookieStore` supports it). |
| Osamu Nakamura |
0:a40b9a259b52 | 285 | |
| Osamu Nakamura |
0:a40b9a259b52 | 286 | The `.lastAccessed` property of the returned cookies will have been updated. |
| Osamu Nakamura |
0:a40b9a259b52 | 287 | |
| Osamu Nakamura |
0:a40b9a259b52 | 288 | ### `.getCookiesSync(currentUrl, [{options}])` |
| Osamu Nakamura |
0:a40b9a259b52 | 289 | |
| Osamu Nakamura |
0:a40b9a259b52 | 290 | Synchronous version of `getCookies`; only works with synchronous stores (e.g. the default `MemoryCookieStore`). |
| Osamu Nakamura |
0:a40b9a259b52 | 291 | |
| Osamu Nakamura |
0:a40b9a259b52 | 292 | ### `.getCookieString(...)` |
| Osamu Nakamura |
0:a40b9a259b52 | 293 | |
| Osamu Nakamura |
0:a40b9a259b52 | 294 | Accepts the same options as `.getCookies()` but passes a string suitable for a Cookie header rather than an array to the callback. Simply maps the `Cookie` array via `.cookieString()`. |
| Osamu Nakamura |
0:a40b9a259b52 | 295 | |
| Osamu Nakamura |
0:a40b9a259b52 | 296 | ### `.getCookieStringSync(...)` |
| Osamu Nakamura |
0:a40b9a259b52 | 297 | |
| Osamu Nakamura |
0:a40b9a259b52 | 298 | Synchronous version of `getCookieString`; only works with synchronous stores (e.g. the default `MemoryCookieStore`). |
| Osamu Nakamura |
0:a40b9a259b52 | 299 | |
| Osamu Nakamura |
0:a40b9a259b52 | 300 | ### `.getSetCookieStrings(...)` |
| Osamu Nakamura |
0:a40b9a259b52 | 301 | |
| Osamu Nakamura |
0:a40b9a259b52 | 302 | Returns an array of strings suitable for **Set-Cookie** headers. Accepts the same options as `.getCookies()`. Simply maps the cookie array via `.toString()`. |
| Osamu Nakamura |
0:a40b9a259b52 | 303 | |
| Osamu Nakamura |
0:a40b9a259b52 | 304 | ### `.getSetCookieStringsSync(...)` |
| Osamu Nakamura |
0:a40b9a259b52 | 305 | |
| Osamu Nakamura |
0:a40b9a259b52 | 306 | Synchronous version of `getSetCookieStrings`; only works with synchronous stores (e.g. the default `MemoryCookieStore`). |
| Osamu Nakamura |
0:a40b9a259b52 | 307 | |
| Osamu Nakamura |
0:a40b9a259b52 | 308 | ### `.serialize(cb(err,serializedObject))` |
| Osamu Nakamura |
0:a40b9a259b52 | 309 | |
| Osamu Nakamura |
0:a40b9a259b52 | 310 | Serialize the Jar if the underlying store supports `.getAllCookies`. |
| Osamu Nakamura |
0:a40b9a259b52 | 311 | |
| Osamu Nakamura |
0:a40b9a259b52 | 312 | **NOTE**: Custom `Cookie` properties will be discarded. If you want a property to be serialized, add the property name to the `Cookie.serializableProperties` Array. |
| Osamu Nakamura |
0:a40b9a259b52 | 313 | |
| Osamu Nakamura |
0:a40b9a259b52 | 314 | See [Serialization Format]. |
| Osamu Nakamura |
0:a40b9a259b52 | 315 | |
| Osamu Nakamura |
0:a40b9a259b52 | 316 | ### `.serializeSync()` |
| Osamu Nakamura |
0:a40b9a259b52 | 317 | |
| Osamu Nakamura |
0:a40b9a259b52 | 318 | Sync version of .serialize |
| Osamu Nakamura |
0:a40b9a259b52 | 319 | |
| Osamu Nakamura |
0:a40b9a259b52 | 320 | ### `.toJSON()` |
| Osamu Nakamura |
0:a40b9a259b52 | 321 | |
| Osamu Nakamura |
0:a40b9a259b52 | 322 | Alias of .serializeSync() for the convenience of `JSON.stringify(cookiejar)`. |
| Osamu Nakamura |
0:a40b9a259b52 | 323 | |
| Osamu Nakamura |
0:a40b9a259b52 | 324 | ### `CookieJar.deserialize(serialized, [store], cb(err,object))` |
| Osamu Nakamura |
0:a40b9a259b52 | 325 | |
| Osamu Nakamura |
0:a40b9a259b52 | 326 | A new Jar is created and the serialized Cookies are added to the underlying store. Each `Cookie` is added via `store.putCookie` in the order in which they appear in the serialization. |
| Osamu Nakamura |
0:a40b9a259b52 | 327 | |
| Osamu Nakamura |
0:a40b9a259b52 | 328 | The `store` argument is optional, but should be an instance of `Store`. By default, a new instance of `MemoryCookieStore` is created. |
| Osamu Nakamura |
0:a40b9a259b52 | 329 | |
| Osamu Nakamura |
0:a40b9a259b52 | 330 | As a convenience, if `serialized` is a string, it is passed through `JSON.parse` first. If that throws an error, this is passed to the callback. |
| Osamu Nakamura |
0:a40b9a259b52 | 331 | |
| Osamu Nakamura |
0:a40b9a259b52 | 332 | ### `CookieJar.deserializeSync(serialized, [store])` |
| Osamu Nakamura |
0:a40b9a259b52 | 333 | |
| Osamu Nakamura |
0:a40b9a259b52 | 334 | Sync version of `.deserialize`. _Note_ that the `store` must be synchronous for this to work. |
| Osamu Nakamura |
0:a40b9a259b52 | 335 | |
| Osamu Nakamura |
0:a40b9a259b52 | 336 | ### `CookieJar.fromJSON(string)` |
| Osamu Nakamura |
0:a40b9a259b52 | 337 | |
| Osamu Nakamura |
0:a40b9a259b52 | 338 | Alias of `.deserializeSync` to provide consistency with `Cookie.fromJSON()`. |
| Osamu Nakamura |
0:a40b9a259b52 | 339 | |
| Osamu Nakamura |
0:a40b9a259b52 | 340 | ### `.clone([store,]cb(err,newJar))` |
| Osamu Nakamura |
0:a40b9a259b52 | 341 | |
| Osamu Nakamura |
0:a40b9a259b52 | 342 | Produces a deep clone of this jar. Modifications to the original won't affect the clone, and vice versa. |
| Osamu Nakamura |
0:a40b9a259b52 | 343 | |
| Osamu Nakamura |
0:a40b9a259b52 | 344 | The `store` argument is optional, but should be an instance of `Store`. By default, a new instance of `MemoryCookieStore` is created. Transferring between store types is supported so long as the source implements `.getAllCookies()` and the destination implements `.putCookie()`. |
| Osamu Nakamura |
0:a40b9a259b52 | 345 | |
| Osamu Nakamura |
0:a40b9a259b52 | 346 | ### `.cloneSync([store])` |
| Osamu Nakamura |
0:a40b9a259b52 | 347 | |
| Osamu Nakamura |
0:a40b9a259b52 | 348 | Synchronous version of `.clone`, returning a new `CookieJar` instance. |
| Osamu Nakamura |
0:a40b9a259b52 | 349 | |
| Osamu Nakamura |
0:a40b9a259b52 | 350 | The `store` argument is optional, but must be a _synchronous_ `Store` instance if specified. If not passed, a new instance of `MemoryCookieStore` is used. |
| Osamu Nakamura |
0:a40b9a259b52 | 351 | |
| Osamu Nakamura |
0:a40b9a259b52 | 352 | The _source_ and _destination_ must both be synchronous `Store`s. If one or both stores are asynchronous, use `.clone` instead. Recall that `MemoryCookieStore` supports both synchronous and asynchronous API calls. |
| Osamu Nakamura |
0:a40b9a259b52 | 353 | |
| Osamu Nakamura |
0:a40b9a259b52 | 354 | ## Store |
| Osamu Nakamura |
0:a40b9a259b52 | 355 | |
| Osamu Nakamura |
0:a40b9a259b52 | 356 | Base class for CookieJar stores. Available as `tough.Store`. |
| Osamu Nakamura |
0:a40b9a259b52 | 357 | |
| Osamu Nakamura |
0:a40b9a259b52 | 358 | ## Store API |
| Osamu Nakamura |
0:a40b9a259b52 | 359 | |
| Osamu Nakamura |
0:a40b9a259b52 | 360 | The storage model for each `CookieJar` instance can be replaced with a custom implementation. The default is `MemoryCookieStore` which can be found in the `lib/memstore.js` file. The API uses continuation-passing-style to allow for asynchronous stores. |
| Osamu Nakamura |
0:a40b9a259b52 | 361 | |
| Osamu Nakamura |
0:a40b9a259b52 | 362 | Stores should inherit from the base `Store` class, which is available as `require('tough-cookie').Store`. |
| Osamu Nakamura |
0:a40b9a259b52 | 363 | |
| Osamu Nakamura |
0:a40b9a259b52 | 364 | Stores are asynchronous by default, but if `store.synchronous` is set to `true`, then the `*Sync` methods on the of the containing `CookieJar` can be used (however, the continuation-passing style |
| Osamu Nakamura |
0:a40b9a259b52 | 365 | |
| Osamu Nakamura |
0:a40b9a259b52 | 366 | All `domain` parameters will have been normalized before calling. |
| Osamu Nakamura |
0:a40b9a259b52 | 367 | |
| Osamu Nakamura |
0:a40b9a259b52 | 368 | The Cookie store must have all of the following methods. |
| Osamu Nakamura |
0:a40b9a259b52 | 369 | |
| Osamu Nakamura |
0:a40b9a259b52 | 370 | ### `store.findCookie(domain, path, key, cb(err,cookie))` |
| Osamu Nakamura |
0:a40b9a259b52 | 371 | |
| Osamu Nakamura |
0:a40b9a259b52 | 372 | Retrieve a cookie with the given domain, path and key (a.k.a. name). The RFC maintains that exactly one of these cookies should exist in a store. If the store is using versioning, this means that the latest/newest such cookie should be returned. |
| Osamu Nakamura |
0:a40b9a259b52 | 373 | |
| Osamu Nakamura |
0:a40b9a259b52 | 374 | Callback takes an error and the resulting `Cookie` object. If no cookie is found then `null` MUST be passed instead (i.e. not an error). |
| Osamu Nakamura |
0:a40b9a259b52 | 375 | |
| Osamu Nakamura |
0:a40b9a259b52 | 376 | ### `store.findCookies(domain, path, cb(err,cookies))` |
| Osamu Nakamura |
0:a40b9a259b52 | 377 | |
| Osamu Nakamura |
0:a40b9a259b52 | 378 | Locates cookies matching the given domain and path. This is most often called in the context of `cookiejar.getCookies()` above. |
| Osamu Nakamura |
0:a40b9a259b52 | 379 | |
| Osamu Nakamura |
0:a40b9a259b52 | 380 | If no cookies are found, the callback MUST be passed an empty array. |
| Osamu Nakamura |
0:a40b9a259b52 | 381 | |
| Osamu Nakamura |
0:a40b9a259b52 | 382 | The resulting list will be checked for applicability to the current request according to the RFC (domain-match, path-match, http-only-flag, secure-flag, expiry, etc.), so it's OK to use an optimistic search algorithm when implementing this method. However, the search algorithm used SHOULD try to find cookies that `domainMatch()` the domain and `pathMatch()` the path in order to limit the amount of checking that needs to be done. |
| Osamu Nakamura |
0:a40b9a259b52 | 383 | |
| Osamu Nakamura |
0:a40b9a259b52 | 384 | As of version 0.9.12, the `allPaths` option to `cookiejar.getCookies()` above will cause the path here to be `null`. If the path is `null`, path-matching MUST NOT be performed (i.e. domain-matching only). |
| Osamu Nakamura |
0:a40b9a259b52 | 385 | |
| Osamu Nakamura |
0:a40b9a259b52 | 386 | ### `store.putCookie(cookie, cb(err))` |
| Osamu Nakamura |
0:a40b9a259b52 | 387 | |
| Osamu Nakamura |
0:a40b9a259b52 | 388 | Adds a new cookie to the store. The implementation SHOULD replace any existing cookie with the same `.domain`, `.path`, and `.key` properties -- depending on the nature of the implementation, it's possible that between the call to `fetchCookie` and `putCookie` that a duplicate `putCookie` can occur. |
| Osamu Nakamura |
0:a40b9a259b52 | 389 | |
| Osamu Nakamura |
0:a40b9a259b52 | 390 | The `cookie` object MUST NOT be modified; the caller will have already updated the `.creation` and `.lastAccessed` properties. |
| Osamu Nakamura |
0:a40b9a259b52 | 391 | |
| Osamu Nakamura |
0:a40b9a259b52 | 392 | Pass an error if the cookie cannot be stored. |
| Osamu Nakamura |
0:a40b9a259b52 | 393 | |
| Osamu Nakamura |
0:a40b9a259b52 | 394 | ### `store.updateCookie(oldCookie, newCookie, cb(err))` |
| Osamu Nakamura |
0:a40b9a259b52 | 395 | |
| Osamu Nakamura |
0:a40b9a259b52 | 396 | Update an existing cookie. The implementation MUST update the `.value` for a cookie with the same `domain`, `.path` and `.key`. The implementation SHOULD check that the old value in the store is equivalent to `oldCookie` - how the conflict is resolved is up to the store. |
| Osamu Nakamura |
0:a40b9a259b52 | 397 | |
| Osamu Nakamura |
0:a40b9a259b52 | 398 | The `.lastAccessed` property will always be different between the two objects (to the precision possible via JavaScript's clock). Both `.creation` and `.creationIndex` are guaranteed to be the same. Stores MAY ignore or defer the `.lastAccessed` change at the cost of affecting how cookies are selected for automatic deletion (e.g., least-recently-used, which is up to the store to implement). |
| Osamu Nakamura |
0:a40b9a259b52 | 399 | |
| Osamu Nakamura |
0:a40b9a259b52 | 400 | Stores may wish to optimize changing the `.value` of the cookie in the store versus storing a new cookie. If the implementation doesn't define this method a stub that calls `putCookie(newCookie,cb)` will be added to the store object. |
| Osamu Nakamura |
0:a40b9a259b52 | 401 | |
| Osamu Nakamura |
0:a40b9a259b52 | 402 | The `newCookie` and `oldCookie` objects MUST NOT be modified. |
| Osamu Nakamura |
0:a40b9a259b52 | 403 | |
| Osamu Nakamura |
0:a40b9a259b52 | 404 | Pass an error if the newCookie cannot be stored. |
| Osamu Nakamura |
0:a40b9a259b52 | 405 | |
| Osamu Nakamura |
0:a40b9a259b52 | 406 | ### `store.removeCookie(domain, path, key, cb(err))` |
| Osamu Nakamura |
0:a40b9a259b52 | 407 | |
| Osamu Nakamura |
0:a40b9a259b52 | 408 | Remove a cookie from the store (see notes on `findCookie` about the uniqueness constraint). |
| Osamu Nakamura |
0:a40b9a259b52 | 409 | |
| Osamu Nakamura |
0:a40b9a259b52 | 410 | The implementation MUST NOT pass an error if the cookie doesn't exist; only pass an error due to the failure to remove an existing cookie. |
| Osamu Nakamura |
0:a40b9a259b52 | 411 | |
| Osamu Nakamura |
0:a40b9a259b52 | 412 | ### `store.removeCookies(domain, path, cb(err))` |
| Osamu Nakamura |
0:a40b9a259b52 | 413 | |
| Osamu Nakamura |
0:a40b9a259b52 | 414 | Removes matching cookies from the store. The `path` parameter is optional, and if missing means all paths in a domain should be removed. |
| Osamu Nakamura |
0:a40b9a259b52 | 415 | |
| Osamu Nakamura |
0:a40b9a259b52 | 416 | Pass an error ONLY if removing any existing cookies failed. |
| Osamu Nakamura |
0:a40b9a259b52 | 417 | |
| Osamu Nakamura |
0:a40b9a259b52 | 418 | ### `store.getAllCookies(cb(err, cookies))` |
| Osamu Nakamura |
0:a40b9a259b52 | 419 | |
| Osamu Nakamura |
0:a40b9a259b52 | 420 | Produces an `Array` of all cookies during `jar.serialize()`. The items in the array can be true `Cookie` objects or generic `Object`s with the [Serialization Format] data structure. |
| Osamu Nakamura |
0:a40b9a259b52 | 421 | |
| Osamu Nakamura |
0:a40b9a259b52 | 422 | Cookies SHOULD be returned in creation order to preserve sorting via `compareCookies()`. For reference, `MemoryCookieStore` will sort by `.creationIndex` since it uses true `Cookie` objects internally. If you don't return the cookies in creation order, they'll still be sorted by creation time, but this only has a precision of 1ms. See `compareCookies` for more detail. |
| Osamu Nakamura |
0:a40b9a259b52 | 423 | |
| Osamu Nakamura |
0:a40b9a259b52 | 424 | Pass an error if retrieval fails. |
| Osamu Nakamura |
0:a40b9a259b52 | 425 | |
| Osamu Nakamura |
0:a40b9a259b52 | 426 | ## MemoryCookieStore |
| Osamu Nakamura |
0:a40b9a259b52 | 427 | |
| Osamu Nakamura |
0:a40b9a259b52 | 428 | Inherits from `Store`. |
| Osamu Nakamura |
0:a40b9a259b52 | 429 | |
| Osamu Nakamura |
0:a40b9a259b52 | 430 | A just-in-memory CookieJar synchronous store implementation, used by default. Despite being a synchronous implementation, it's usable with both the synchronous and asynchronous forms of the `CookieJar` API. |
| Osamu Nakamura |
0:a40b9a259b52 | 431 | |
| Osamu Nakamura |
0:a40b9a259b52 | 432 | ## Community Cookie Stores |
| Osamu Nakamura |
0:a40b9a259b52 | 433 | |
| Osamu Nakamura |
0:a40b9a259b52 | 434 | These are some Store implementations authored and maintained by the community. They aren't official and we don't vouch for them but you may be interested to have a look: |
| Osamu Nakamura |
0:a40b9a259b52 | 435 | |
| Osamu Nakamura |
0:a40b9a259b52 | 436 | - [`db-cookie-store`](https://github.com/JSBizon/db-cookie-store): SQL including SQLite-based databases |
| Osamu Nakamura |
0:a40b9a259b52 | 437 | - [`file-cookie-store`](https://github.com/JSBizon/file-cookie-store): Netscape cookie file format on disk |
| Osamu Nakamura |
0:a40b9a259b52 | 438 | - [`redis-cookie-store`](https://github.com/benkroeger/redis-cookie-store): Redis |
| Osamu Nakamura |
0:a40b9a259b52 | 439 | - [`tough-cookie-filestore`](https://github.com/mitsuru/tough-cookie-filestore): JSON on disk |
| Osamu Nakamura |
0:a40b9a259b52 | 440 | - [`tough-cookie-web-storage-store`](https://github.com/exponentjs/tough-cookie-web-storage-store): DOM localStorage and sessionStorage |
| Osamu Nakamura |
0:a40b9a259b52 | 441 | |
| Osamu Nakamura |
0:a40b9a259b52 | 442 | |
| Osamu Nakamura |
0:a40b9a259b52 | 443 | # Serialization Format |
| Osamu Nakamura |
0:a40b9a259b52 | 444 | |
| Osamu Nakamura |
0:a40b9a259b52 | 445 | **NOTE**: if you want to have custom `Cookie` properties serialized, add the property name to `Cookie.serializableProperties`. |
| Osamu Nakamura |
0:a40b9a259b52 | 446 | |
| Osamu Nakamura |
0:a40b9a259b52 | 447 | ```js |
| Osamu Nakamura |
0:a40b9a259b52 | 448 | { |
| Osamu Nakamura |
0:a40b9a259b52 | 449 | // The version of tough-cookie that serialized this jar. |
| Osamu Nakamura |
0:a40b9a259b52 | 450 | version: 'tough-cookie@1.x.y', |
| Osamu Nakamura |
0:a40b9a259b52 | 451 | |
| Osamu Nakamura |
0:a40b9a259b52 | 452 | // add the store type, to make humans happy: |
| Osamu Nakamura |
0:a40b9a259b52 | 453 | storeType: 'MemoryCookieStore', |
| Osamu Nakamura |
0:a40b9a259b52 | 454 | |
| Osamu Nakamura |
0:a40b9a259b52 | 455 | // CookieJar configuration: |
| Osamu Nakamura |
0:a40b9a259b52 | 456 | rejectPublicSuffixes: true, |
| Osamu Nakamura |
0:a40b9a259b52 | 457 | // ... future items go here |
| Osamu Nakamura |
0:a40b9a259b52 | 458 | |
| Osamu Nakamura |
0:a40b9a259b52 | 459 | // Gets filled from jar.store.getAllCookies(): |
| Osamu Nakamura |
0:a40b9a259b52 | 460 | cookies: [ |
| Osamu Nakamura |
0:a40b9a259b52 | 461 | { |
| Osamu Nakamura |
0:a40b9a259b52 | 462 | key: 'string', |
| Osamu Nakamura |
0:a40b9a259b52 | 463 | value: 'string', |
| Osamu Nakamura |
0:a40b9a259b52 | 464 | // ... |
| Osamu Nakamura |
0:a40b9a259b52 | 465 | /* other Cookie.serializableProperties go here */ |
| Osamu Nakamura |
0:a40b9a259b52 | 466 | } |
| Osamu Nakamura |
0:a40b9a259b52 | 467 | ] |
| Osamu Nakamura |
0:a40b9a259b52 | 468 | } |
| Osamu Nakamura |
0:a40b9a259b52 | 469 | ``` |
| Osamu Nakamura |
0:a40b9a259b52 | 470 | |
| Osamu Nakamura |
0:a40b9a259b52 | 471 | # Copyright and License |
| Osamu Nakamura |
0:a40b9a259b52 | 472 | |
| Osamu Nakamura |
0:a40b9a259b52 | 473 | (tl;dr: BSD-3-Clause with some MPL/2.0) |
| Osamu Nakamura |
0:a40b9a259b52 | 474 | |
| Osamu Nakamura |
0:a40b9a259b52 | 475 | ```text |
| Osamu Nakamura |
0:a40b9a259b52 | 476 | Copyright (c) 2015, Salesforce.com, Inc. |
| Osamu Nakamura |
0:a40b9a259b52 | 477 | All rights reserved. |
| Osamu Nakamura |
0:a40b9a259b52 | 478 | |
| Osamu Nakamura |
0:a40b9a259b52 | 479 | Redistribution and use in source and binary forms, with or without |
| Osamu Nakamura |
0:a40b9a259b52 | 480 | modification, are permitted provided that the following conditions are met: |
| Osamu Nakamura |
0:a40b9a259b52 | 481 | |
| Osamu Nakamura |
0:a40b9a259b52 | 482 | 1. Redistributions of source code must retain the above copyright notice, |
| Osamu Nakamura |
0:a40b9a259b52 | 483 | this list of conditions and the following disclaimer. |
| Osamu Nakamura |
0:a40b9a259b52 | 484 | |
| Osamu Nakamura |
0:a40b9a259b52 | 485 | 2. Redistributions in binary form must reproduce the above copyright notice, |
| Osamu Nakamura |
0:a40b9a259b52 | 486 | this list of conditions and the following disclaimer in the documentation |
| Osamu Nakamura |
0:a40b9a259b52 | 487 | and/or other materials provided with the distribution. |
| Osamu Nakamura |
0:a40b9a259b52 | 488 | |
| Osamu Nakamura |
0:a40b9a259b52 | 489 | 3. Neither the name of Salesforce.com nor the names of its contributors may |
| Osamu Nakamura |
0:a40b9a259b52 | 490 | be used to endorse or promote products derived from this software without |
| Osamu Nakamura |
0:a40b9a259b52 | 491 | specific prior written permission. |
| Osamu Nakamura |
0:a40b9a259b52 | 492 | |
| Osamu Nakamura |
0:a40b9a259b52 | 493 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" |
| Osamu Nakamura |
0:a40b9a259b52 | 494 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| Osamu Nakamura |
0:a40b9a259b52 | 495 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| Osamu Nakamura |
0:a40b9a259b52 | 496 | ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE |
| Osamu Nakamura |
0:a40b9a259b52 | 497 | LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
| Osamu Nakamura |
0:a40b9a259b52 | 498 | CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
| Osamu Nakamura |
0:a40b9a259b52 | 499 | SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
| Osamu Nakamura |
0:a40b9a259b52 | 500 | INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
| Osamu Nakamura |
0:a40b9a259b52 | 501 | CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
| Osamu Nakamura |
0:a40b9a259b52 | 502 | ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
| Osamu Nakamura |
0:a40b9a259b52 | 503 | POSSIBILITY OF SUCH DAMAGE. |
| Osamu Nakamura |
0:a40b9a259b52 | 504 | ``` |
| Osamu Nakamura |
0:a40b9a259b52 | 505 | |
| Osamu Nakamura |
0:a40b9a259b52 | 506 | Portions may be licensed under different licenses (in particular `public_suffix_list.dat` is MPL/2.0); please read that file and the LICENSE file for full details. |