RFC6265 Cookies et CookieJar pour Node.js

Synopsis``` 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

C'est _si_ facile !

`npm install tough-cookie`

Pourquoi ce nom ?  Les modules NPM `cookie`, `cookies` et `cookiejar` étaient déjà pris.

## Prise en charge des versions

La prise en charge des versions de node.js suivra celle du module [request](https://www.npmjs.com/package/request).

# API

## tough

Fonctions du module que vous obtenez à partir de `require('tough-cookie')`.  Toutes peuvent être utilisées comme des fonctions pures et n'ont pas besoin d'être « liées ».

**Remarque** : avant 1.0.x, plusieurs de ces fonctions acceptaient un paramètre `strict`. Celui-ci a depuis été retiré de l'API car il n'était plus nécessaire.

### `parseDate(string)`

Analyse une chaîne de date de cookie en un objet `Date`.  Analyse selon la Section 5.1.1 de la RFC6265, et non `Date.parse()`.

### `formatDate(date)`

Formate un objet Date en une chaîne RFC1123 (le format recommandé par la RFC6265).

### `canonicalDomain(str)`

Transforme un nom de domaine en un nom de domaine canonique.  Le nom de domaine canonique est un nom de domaine dont les espaces de début et de fin sont supprimés, mis en minuscules, sans point initial et éventuellement encodé en punycode (Section 5.1.2 de la RFC6265).  Dans l'ensemble, cette fonction est idempotente (elle peut être exécutée à nouveau sur sa sortie sans effets néfastes).

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

Répond à la question « ce vrai domaine correspond-il au domaine dans un cookie ? ».  `str` est le nom de domaine « courant » et `domStr` est le nom de domaine « cookie ».  La correspondance est effectuée selon la Section 5.1.3 de la RFC6265, mais il est utile de la considérer comme une « correspondance par suffixe ».

Le paramètre `canonicalize` soumet les deux autres paramètres à `canonicalDomain` ou non.

### `defaultPath(path)`

Étant donné un chemin de requête/réponse actuel, renvoie le chemin approprié pour le stockage dans un cookie.  C'est essentiellement le « répertoire » d'un « fichier » dans le chemin, mais spécifié par la Section 5.1.4 de la RFC.

Le paramètre `path` DOIT être _uniquement_ la partie chemin d'une URI (c'est-à-dire qu'il exclut le nom d'hôte, la requête, le fragment, etc.).  C'est la propriété `.pathname` de la sortie de `uri.parse()` de node.

### `pathMatch(reqPath,cookiePath)`

Répond à la question « le chemin de requête correspond-il à un chemin de cookie donné ? » conformément à la Section 5.1.4 de la RFC6265.  Renvoie un booléen.

C'est essentiellement une correspondance par préfixe où `cookiePath` est un préfixe de `reqPath`.

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

alias de `Cookie.parse(cookieString[, options])`

### `fromJSON(string)`

alias de `Cookie.fromJSON(string)`

### `getPublicSuffix(hostname)`

Renvoie le suffixe public de ce nom d'hôte.  Le suffixe public est le nom de domaine le plus court sur lequel un cookie peut être défini.  Renvoie `null` si le nom d'hôte ne peut pas avoir de cookies définis pour lui.

Par exemple : `www.example.com` et `www.subdomain.example.com` ont tous deux pour suffixe public `example.com`.

Pour plus d'informations, voir http://publicsuffix.org/.  Ce module tire sa liste de ce site. Cet appel est actuellement un wrapper autour de la [méthode get()](https://www.npmjs.com/package/psl#pslgetdomain) de [`psl`](https://www.npmjs.com/package/psl).

### `cookieCompare(a,b)`

Pour une utilisation avec `.sort()`, trie une liste de cookies dans l'ordre recommandé par la RFC (Section 5.4, étape 2). L'algorithme de tri est, par ordre de priorité :

* `.path` le plus long
* `.creation` le plus ancien (avec une précision de 1 ms, identique à `Date`)
* `.creationIndex` le plus bas (pour aller au-delà de la précision de 1 ms)``` javascript
var cookies = [ /* unsorted array of Cookie objects */ ];
cookies = cookies.sort(cookieCompare);

Remarque: Comme le Date de JavaScript est limité à une précision de 1ms, des cookies créés dans la même milliseconde sont tout à fait possibles. Cela est particulièrement vrai lorsqu'on utilise l'option now avec .setCookie(). La propriété .creationIndex est un compteur global par processus, assigné lors de la construction avec new Cookie(). Cela préserve l'esprit du tri RFC: les cookies plus anciens passent en premier. Cela fonctionne très bien avec MemoryCookieStore, puisque les en-têtes Set-Cookie sont analysés dans l'ordre, mais cela peut ne pas convenir aux systèmes distribués. Les Stores sophistiqués souhaiteront peut-être définir cette valeur sur une autre horloge logique de sorte que si les cookies A et B sont créés dans la même milliseconde, mais que le cookie A est créé avant le cookie B, alors A.creationIndex < B.creationIndex. Si vous voulez modifier le compteur global, ce que vous ne devriez probablement pas faire, il est stocké dans Cookie.cookiesCreated.

permuteDomain(domain)

Génère une liste de tous les domaines possibles que domainMatch() fait correspondre au paramètre. Peut être pratique pour implémenter des stores de cookies.

permutePath(path)

Génère une liste de tous les chemins possibles que pathMatch() fait correspondre au paramètre. Peut être pratique pour implémenter des stores de cookies.

Cookie

Exporté via tough.Cookie.

Cookie.parse(cookieString[, options])

Analyse un cookie unique ou un en-tête HTTP Set-Cookie en un objet Cookie. Renvoie undefined si la chaîne ne peut pas être analysée.

Le paramètre options n'est pas requis et ne possède actuellement qu'une seule propriété:

• loose - booléen - si true, active l'analyse des cookies sans clé comme =abc et =, qui ne sont pas conformes à la RFC.

Si options n'est pas un objet, il est ignoré, ce qui signifie que vous pouvez utiliser Array#map avec lui.

Voici comment traiter le ou les en-têtes Set-Cookie dans une réponse HTTP/HTTPS node:``` 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 :_ dans la version 2.3.3, tough-cookie limitait le nombre d'espaces avant le `=` à 256 caractères. Cette limitation a depuis été supprimée.
Voir [Issue 92](https://github.com/salesforce/tough-cookie/issues/92)

### Propriétés

Propriétés de l'objet Cookie :