RFC6265 Cookies と CookieJar for Node.js
var tough = require('tough-cookie'); var Cookie = tough.Cookie; var cookie = Cookie.parse(header); cookie.value = 'somethingdifferent'; header = cookie.toString();
var cookiejar = new tough.CookieJar(); cookiejar.setCookie(cookie, 'http://currentdomain.example.com/path', cb); // ... cookiejar.getCookies('http://example.com/otherpath',function(err,cookies) { res.headers['cookie'] = cookies.join('; '); });
# Installation
とても簡単です！
`npm install tough-cookie`
なぜこの名前なのか？ NPMモジュールの `cookie`、`cookies`、`cookiejar` はすでに使われていました。
## バージョンサポート
node.jsのバージョンサポートは、[request](https://www.npmjs.com/package/request) モジュールに準拠します。
# API
## tough
`require('tough-cookie')` から取得したモジュールの関数です。すべて純粋関数として使用でき、「バインド」する必要はありません。
**注**: 1.0.xより前のバージョンでは、これらの関数のいくつかは `strict` パラメータを受け付けていました。これは不要になったためAPIから削除されました。
### `parseDate(string)`
クッキーの日付文字列を `Date` にパースします。`Date.parse()` ではなく RFC6265 セクション5.1.1に従ってパースします。
### `formatDate(date)`
Date を RFC1123 文字列（RFC6265 推奨形式）にフォーマットします。
### `canonicalDomain(str)`
ドメイン名を正規ドメイン名に変換します。正規ドメイン名は、トリミング、小文字化、先頭ドットの除去、およびオプションでPunycodeエンコードされたドメイン名です（RFC6265 セクション5.1.2）。ほとんどの場合、この関数は冪等性があります（出力に対して再度実行しても悪影響はありません）。
### `domainMatch(str,domStr[,canonicalize=true])`
「この実際のドメインはクッキーのドメインと一致しますか？」という問いに答えます。`str` は「現在の」ドメイン名、`domStr` は「クッキー」ドメイン名です。RFC6265 セクション5.1.3に従ってマッチングしますが、「サフィックス一致」と考えるとわかりやすいです。
`canonicalize` パラメータは、他の2つのパラメータに対して `canonicalDomain` を適用するかどうかを指定します。
### `defaultPath(path)`
現在のリクエスト/レスポンスパスが与えられたとき、クッキーに保存するのに適切なPathを返します。これは基本的にパス中の「ファイル」の「ディレクトリ」ですが、RFCのセクション5.1.4で指定されています。
`path` パラメータは URI のパス名部分 _のみ_ でなければなりません（つまり、ホスト名、クエリ、フラグメントなどを除きます）。これは Node の `uri.parse()` 出力の `.pathname` プロパティです。
### `pathMatch(reqPath,cookiePath)`
「リクエストパスは指定されたクッキーパスとパスマッチしますか？」という問いにRFC6265 セクション5.1.4に従って答えます。真偽値を返します。
これは基本的に、`cookiePath` が `reqPath` のプレフィックスであるようなプレフィックス一致です。
### `parse(cookieString[, options])`
`Cookie.parse(cookieString[, options])` のエイリアス
### `fromJSON(string)`
`Cookie.fromJSON(string)` のエイリアス
### `getPublicSuffix(hostname)`
このホスト名のパブリックサフィックスを返します。パブリックサフィックスとは、クッキーを設定できる最短のドメイン名です。ホスト名にクッキーを設定できない場合は `null` を返します。
例: `www.example.com` と `www.subdomain.example.com` はどちらもパブリックサフィックス `example.com` を持ちます。
詳細については、http://publicsuffix.org/ を参照してください。このモジュールはそのサイトからリストを取得しています。この呼び出しは現在、[`psl`](https://www.npmjs.com/package/psl) の [get() メソッド](https://www.npmjs.com/package/psl#pslgetdomain) のラッパーです。
### `cookieCompare(a,b)`
`.sort()` で使用するために、クッキーのリストをRFC（セクション5.4 ステップ2）で推奨される順序に並べ替えます。ソートアルゴリズムは、優先順位は次のとおりです：
* 最も長い `.path`
* 最も古い `.creation`（精度は1ms、`Date`と同じ）
* 最小の `.creationIndex`（1msの精度を超えるため）``` javascript
var cookies = [ /* unsorted array of Cookie objects */ ];
cookies = cookies.sort(cookieCompare);
注記: JavaScriptの Date は1ms精度に制限されているため、同一ミリ秒内に複数のCookieが作成される可能性は十分にあります。これは特に .setCookie() で now オプションを使用する場合に当てはまります。.creationIndex プロパティはプロセス全体のグローバルカウンターで、new Cookie() による構築時に割り当てられます。これはRFCソートの精神を維持します: 古いCookieが先に来ます。この動作は MemoryCookieStore では有効に機能します（Set-Cookie ヘッダーが順番に解析されるため）が、分散システムではあまり適切でない可能性があります。高度な Store は、Cookie A と Cookie B が同じミリ秒で作成された場合でも、Cookie A が Cookie B より先に作成されていれば A.creationIndex < B.creationIndex となるように、別の 論理クロック を設定したい場合があります。グローバルカウンターを変更したい場合（おそらく すべきではありません が）、それは Cookie.cookiesCreated に保存されています。
permuteDomain(domain)domainMatch() がパラメータに一致する可能性のあるすべてのドメインのリストを生成します。Cookieストアの実装に便利です。
permutePath(path)pathMatch() がパラメータに一致する可能性のあるすべてのパスのリストを生成します。Cookieストアの実装に便利です。
tough.Cookie からエクスポートされます。
Cookie.parse(cookieString[, options])単一のCookieまたはSet-Cookie HTTPヘッダーを解析して Cookie オブジェクトに変換します。文字列を解析できない場合は undefined を返します。
optionsパラメーターは必須ではなく、現在は1つのプロパティのみを持ちます。
true の場合、=abc や = のようなキーなしCookieの解析を有効にします（これらはRFCに準拠していません）。optionsがオブジェクトでない場合は無視されるため、Array#map と併用できます。
以下は、NodeのHTTP/HTTPSレスポンスでSet-Cookieヘッダーを処理する方法です。``` javascript if (res.headers['set-cookie'] instanceof Array) cookies = res.headers['set-cookie'].map(Cookie.parse); else cookies = [Cookie.parse(res.headers['set-cookie'])];
_注:_ バージョン2.3.3では、tough-cookieは`=`の前のスペースの数を256文字に制限していました。この制限はその後削除されました。
詳細は[Issue 92](https://github.com/salesforce/tough-cookie/issues/92)を参照してください。
### プロパティ
Cookieオブジェクトのプロパティ:
* _key_ - 文字列 - クッキーの名前またはキー（デフォルト ""）
* _value_ - 文字列 - クッキーの値（デフォルト ""）
* _expires_ - `Date` - 設定されている場合、クッキーの `Expires=` 属性（デフォルトは文字列 `"Infinity"`）。`setExpires()` を参照してください。
* _maxAge_ - 秒 - 設定されている場合、クッキーの `Max-Age=` 属性（秒単位）。非期限切れの場合は `"Infinity"`、即時期限切れの場合は `"-Infinity"` という文字列も設定可能。`setMaxAge()` を参照してください。
* _domain_ - 文字列 - クッキーの `Domain=` 属性
* _path_ - 文字列 - クッキーの `Path=` 属性
* _secure_ - 真偽値 - `Secure` クッキーフラグ
* _httpOnly_ - 真偽値 - `HttpOnly` クッキーフラグ
* _extensions_ - `Array` - 認識されないクッキー属性（等号が内部にあっても文字列として）
* _creation_ - `Date` - このクッキーが構築された日時
* _creationIndex_ - 数値 - 構築時に設定され、より詳細なソート精度を提供するために使用されます（詳しい説明は `cookieCompare(a,b)` を参照してください）
クッキーが `CookieJar.setCookie()` を通過した後、以下の追加属性を持ちます:
* _hostOnly_ - 真偽値 - ホストオンリークッキーかどうか（つまり、Domainフィールドが設定されず、暗黙的に決定された場合）
* _pathIsDefault_ - 真偽値 - trueの場合、クッキーにPathフィールドがなく、`defaultPath()` を使って導出されたことを示します。
* _creation_ - `Date` - **変更**: 構築時から、クッキーが jar に追加された時点に変更されます。
* _lastAccessed_ - `Date` - 最後にクッキーにアクセスした時刻。実装されればクッキーのクリーンアップに影響します。`cookiejar.getCookies(...)` を使用するとこの属性が更新されます。
### `Cookie([{properties}])`
上記のCookieプロパティのいずれかを含むオプションオブジェクトを受け取り、指定されていないプロパティにはデフォルト値を使用します。
### `.toString()`
Set-Cookieヘッダー値にエンコードします。Expiresクッキーフィールドは `formatDate()` を使用して設定されますが、`.expires` が `Infinity` の場合は完全に省略されます。
### `.cookieString()`
Cookieヘッダー値（つまり `.key` と `.value` のプロパティを '=' で結合したもの）にエンコードします。
### `.setExpires(String)`
`parseDate()` に渡された日付文字列に基づいて有効期限を設定します。parseDate が `null` を返す場合（つまりこの日付文字列を解析できない場合）、`.expires` は `"Infinity"`（文字列）に設定されます。
### `.setMaxAge(number)`
maxAge を秒単位で設定します。`-Infinity` を `"-Infinity"` に、`Infinity` を `"Infinity"` に変換するので、JSON で正しくシリアライズされます。
### `.expiryTime([now=Date.now()])`
### `.expiryDate([now=Date.now()])`
expiryTime() は、このクッキーが期限切れになる絶対 Unix エポックミリ秒を計算します。expiryDate() も同様に動作しますが、`Date` オブジェクトを返します。どちらの場合も `now` パラメータはミリ秒単位であることに注意してください。
Max-Age は Expires よりも優先されます（RFC に従います）。`.creation` 属性、またはデフォルトでは `now` パラメータを使用して、`.maxAge` 属性をオフセットします。
Expires（`.expires`）が設定されている場合は、それが返されます。
それ以外の場合、`expiryTime()` は `Infinity` を返し、`expiryDate()` は "Tue, 19 Jan 2038 03:14:07 GMT"（32ビット `time_t` で表現可能な最新の日付；ほとんどのユーザーエージェントの一般的な上限）の `Date` オブジェクトを返します。
### `.TTL([now=Date.now()])`
`now`（ミリ秒）に対する TTL を計算します。`expiryTime`/`expiryDate` と同じ優先順位ルールが適用されます。
明示的な有効期限がないクッキーには数値 `Infinity` が返され、期限切れのクッキーには `0` が返されます。それ以外の場合は、ミリ秒単位の Time-To-Live が返されます。
### `.canonicalizedDomain()`
### `.cdomain()`
正規化された `.domain` フィールドを返します。これは小文字化され、ドメインに非ASCII文字が含まれる場合は punycode（RFC3490）でエンコードされます。
### `.toJSON()`
`JSON.serialize(cookie)` で使用するための利便性のため。JSON シリアライズ可能なプレーンな `Object` を返します。
`Date` プロパティ（つまり `.expires`、`.creation`、`.lastAccessed`）は ISO 形式（`.toISOString()`）でエクスポートされます。
**注**: カスタム `Cookie` プロパティは破棄されます。tough-cookie 1.x では、`.toJSON` メソッドが明示的に定義されていなかったため、すべての列挙可能なプロパティがキャプチャされていました。プロパティをシリアライズしたい場合は、そのプロパティ名を `Cookie.serializableProperties` 配列に追加してください。
### `Cookie.fromJSON(strOrObj)`
`cookie.toJSON()` の逆を行います。文字列が渡された場合は、最初に `JSON.parse()` します。
`Date` プロパティ（つまり `.expires`、`.creation`、`.lastAccessed`）は `Date.parse()` を介して解析されます。tough-cookie の `parseDate` ではありません。このレイヤーでは JavaScript/JSON 的なタイムスタンプが扱われるためです。
JSON 解析エラーの場合は `null` を返します。
### `.clone()`