RFC6265 Cookies und CookieJar für Node.js

Übersicht``` javascript

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

Das ist _so_ einfach!

`npm install tough-cookie`

Warum dieser Name? Die NPM-Module `cookie`, `cookies` und `cookiejar` waren bereits vergeben.

## Versionsunterstützung

Die Unterstützung für node.js-Versionen orientiert sich an der des [request](https://www.npmjs.com/package/request)-Moduls.

# API

## tough

Funktionen auf dem Modul, das du über `require('tough-cookie')` erhältst. Alle können als reine Funktionen verwendet werden und müssen nicht „gebunden“ werden.

**Hinweis**: Vor 1.0.x akzeptierten einige dieser Funktionen einen `strict`-Parameter. Dieser wurde inzwischen aus der API entfernt, da er nicht mehr notwendig war.

### `parseDate(string)`

Analysiert einen Cookie-Datumsstring in ein `Date`. Die Analyse erfolgt gemäß RFC6265 Abschnitt 5.1.1, nicht mit `Date.parse()`.

### `formatDate(date)`

Formatiert ein Date in einen RFC1123-String (das von RFC6265 empfohlene Format).

### `canonicalDomain(str)`

Wandelt einen Domainnamen in einen kanonischen Domainnamen um. Der kanonische Domainname ist ein getrimmter, kleingeschriebener, um einen führenden Punkt reduzierter und optional punycode-kodierter Domainname (Abschnitt 5.1.2 von RFC6265). Diese Funktion ist größtenteils idempotent (kann ohne negative Auswirkungen erneut auf ihre Ausgabe angewendet werden).

### `domainMatch(str,domStr[,canonicalize=true])`

Beantwortet die Frage „Entspricht diese echte Domain der Domain in einem Cookie?“. `str` ist der „aktuelle“ Domainname und `domStr` ist der „Cookie“-Domainname. Der Abgleich erfolgt gemäß RFC6265 Abschnitt 5.1.3, aber es hilft, sich das als „Suffix-Abgleich“ vorzustellen.

Der Parameter `canonicalize` bestimmt, ob die beiden anderen Parameter durch `canonicalDomain` verarbeitet werden oder nicht.

### `defaultPath(path)`

Gibt bei einem aktuellen Anfrage-/Antwortpfad den Pfad an, der zum Speichern in einem Cookie geeignet ist. Dies ist im Grunde das „Verzeichnis“ einer „Datei“ im Pfad, wird aber durch Abschnitt 5.1.4 der RFC festgelegt.

Der Parameter `path` MUSS _nur_ der Pfadnamens-Teil einer URI sein (d. h. ohne Hostname, Query, Fragment usw.). Dies ist die Eigenschaft `.pathname` der Ausgabe von `uri.parse()` von Node.

### `pathMatch(reqPath,cookiePath)`

Beantwortet die Frage „Entspricht der Anfragepfad einem gegebenen Cookie-Pfad?“ gemäß RFC6265 Abschnitt 5.1.4. Gibt einen booleschen Wert zurück.

Im Wesentlichen handelt es sich um einen Präfix-Abgleich, bei dem `cookiePath` ein Präfix von `reqPath` ist.

### `parse(cookieString[, options])`

Alias für `Cookie.parse(cookieString[, options])`

### `fromJSON(string)`

Alias für `Cookie.fromJSON(string)`

### `getPublicSuffix(hostname)`

Gibt den öffentlichen Suffix dieses Hostnamens zurück. Der öffentliche Suffix ist der kürzeste Domainname, für den ein Cookie gesetzt werden kann. Gibt `null` zurück, wenn für den Hostnamen keine Cookies gesetzt werden können.

Zum Beispiel: `www.example.com` und `www.subdomain.example.com` haben beide den öffentlichen Suffix `example.com`.

Weitere Informationen findest du unter http://publicsuffix.org/. Dieses Modul leitet seine Liste von dieser Website ab. Dieser Aufruf ist derzeit ein Wrapper um die [get()-Methode](https://www.npmjs.com/package/psl#pslgetdomain) von [`psl`](https://www.npmjs.com/package/psl).

### `cookieCompare(a,b)`

Zur Verwendung mit `.sort()` sortiert eine Liste von Cookies in die in der RFC empfohlene Reihenfolge (Abschnitt 5.4 Schritt 2). Der Sortieralgorithmus lautet in der Reihenfolge der Priorität:

* längster `.path`
* älteste `.creation` (mit einer Präzision von 1 ms, wie bei `Date`)
* niedrigster `.creationIndex` (um über die 1-ms-Präzision hinauszugehen)``` javascript
var cookies = [ /* unsorted array of Cookie objects */ ];
cookies = cookies.sort(cookieCompare);

Hinweis: Da die Date-Klasse von JavaScript auf eine Genauigkeit von 1 ms begrenzt ist, sind Cookies innerhalb derselben Millisekunde durchaus möglich. Dies gilt insbesondere, wenn die Option now mit .setCookie() verwendet wird. Die Eigenschaft .creationIndex ist ein prozessweiter globaler Zähler, der während der Erstellung mit new Cookie() zugewiesen wird. Dies bewahrt den Geist der RFC-Sortierung: Ältere Cookies kommen zuerst. Dies funktioniert hervorragend für MemoryCookieStore, da Set-Cookie-Header der Reihe nach geparst werden, für verteilte Systeme ist es jedoch möglicherweise nicht so gut geeignet. Anspruchsvolle Stores möchten dies möglicherweise auf eine andere logische Uhr setzen, sodass, wenn die Cookies A und B in derselben Millisekunde erstellt werden, Cookie A jedoch vor Cookie B erstellt wird, A.creationIndex < B.creationIndex gilt. Wenn Sie den globalen Zähler ändern möchten, was Sie wahrscheinlich nicht tun sollten, wird er in Cookie.cookiesCreated gespeichert.

permuteDomain(domain)

Erzeugt eine Liste aller möglichen Domains, für die domainMatch() mit dem Parameter zutrifft. Kann beim Implementieren von Cookie-Stores nützlich sein.

permutePath(path)

Erzeugt eine Liste aller möglichen Pfade, für die pathMatch() mit dem Parameter zutrifft. Kann beim Implementieren von Cookie-Stores nützlich sein.

Cookie

Exportiert über tough.Cookie.

Cookie.parse(cookieString[, options])

Parst einen einzelnen Cookie- oder Set-Cookie-HTTP-Header in ein Cookie-Objekt. Gibt undefined zurück, wenn die Zeichenfolge nicht geparst werden kann.

Der options-Parameter ist nicht erforderlich und hat derzeit nur eine Eigenschaft:

• loose - Boolescher Wert - wenn true, das Parsen von schlüssellosen Cookies wie =abc und = aktivieren, die nicht RFC-konform sind.

Wenn options kein Objekt ist, wird es ignoriert, was bedeutet, dass Sie Array#map damit verwenden können.

So verarbeiten Sie die Set-Cookie-Header in einer Node-HTTP/HTTPS-Antwort:``` javascript if (res.headers['set-cookie'] instanceof Array) cookies = res.headers['set-cookie'].map(Cookie.parse); else cookies = [Cookie.parse(res.headers['set-cookie'])];

_Note:_ in Version 2.3.3 hat tough-cookie die Anzahl der Leerzeichen vor dem `=` auf 256 Zeichen begrenzt. Diese Einschränkung wurde inzwischen entfernt.
Siehe [Issue 92](https://github.com/salesforce/tough-cookie/issues/92)

### Eigenschaften

Eigenschaften des Cookie-Objekts: