RFC6265 Cookie e CookieJar per Node.js

Sinossi``` 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('; '); });

## Installazione

È _così_ facile!

`npm install tough-cookie`

Perché il nome? I moduli NPM `cookie`, `cookies` e `cookiejar` erano già occupati.

## Supporto delle versioni

Il supporto per le versioni di node.js seguirà quello del modulo [request](https://www.npmjs.com/package/request).

# API

## tough

Funzioni sul modulo ottenuto con `require('tough-cookie')`. Tutte possono essere usate come funzioni pure e non necessitano di essere "legate".

**Nota**: prima della versione 1.0.x, diverse di queste funzioni accettavano un parametro `strict`. Questo è stato poi rimosso dall'API poiché non era più necessario.

### `parseDate(string)`

Analizza una stringa di data di cookie in un oggetto `Date`. Analizza secondo RFC6265 Sezione 5.1.1, non `Date.parse()`.

### `formatDate(date)`

Formatta un oggetto Date in una stringa RFC1123 (il formato raccomandato da RFC6265).

### `canonicalDomain(str)`

Trasforma un nome di dominio in un nome di dominio canonico. Il nome di dominio canonico è un nome di dominio tagliato, in minuscolo, senza il punto iniziale e opzionalmente codificato in punycode (Sezione 5.1.2 di RFC6265). Per la maggior parte, questa funzione è idempotente (può essere eseguita nuovamente sul suo output senza effetti negativi).

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

Risponde "questo dominio reale corrisponde al dominio in un cookie?". `str` è il nome di dominio "corrente" e `domStr` è il nome di dominio "del cookie". Corrisponde secondo RFC6265 Sezione 5.1.3, ma è utile pensarla come una "corrispondenza di suffisso".

Il parametro `canonicalize` eseguirà o meno gli altri due parametri tramite `canonicalDomain`.

### `defaultPath(path)`

Dato un percorso corrente di richiesta/risposta, restituisce il Path appropriato per l'archiviazione in un cookie. Questo è fondamentalmente la "directory" di un "file" nel percorso, ma è specificato dalla Sezione 5.1.4 del RFC.

Il parametro `path` DEVE essere _solo_ la parte del pathname di un URI (cioè esclude il nome host, query, frammento, ecc.). Questa è la proprietà `.pathname` dell'output di `uri.parse()` di node.

### `pathMatch(reqPath,cookiePath)`

Risponde "il path della richiesta corrisponde al path del cookie?" secondo RFC6265 Sezione 5.1.4. Restituisce un valore booleano.

Questa è essenzialmente una corrispondenza di prefisso in cui `cookiePath` è un prefisso di `reqPath`.

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

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

### `fromJSON(string)`

alias per `Cookie.fromJSON(string)`

### `getPublicSuffix(hostname)`

Restituisce il suffisso pubblico di questo nome host. Il suffisso pubblico è il nome di dominio più breve su cui può essere impostato un cookie. Restituisce `null` se non è possibile impostare cookie per quel nome host.

Ad esempio: `www.example.com` e `www.subdomain.example.com` hanno entrambi suffisso pubblico `example.com`.

Per ulteriori informazioni, vedere http://publicsuffix.org/. Questo modulo deriva la sua lista da quel sito. Questa chiamata è attualmente un wrapper attorno al [metodo get()](https://www.npmjs.com/package/psl#pslgetdomain) di [`psl`](https://www.npmjs.com/package/psl).

### `cookieCompare(a,b)`

Per l'uso con `.sort()`, ordina un elenco di cookie nell'ordine raccomandato dal RFC (Sezione 5.4 passo 2). L'algoritmo di ordinamento è, in ordine di precedenza:

* `.path` più lungo
* `.creation` più vecchio (che ha una precisione di 1ms, uguale a `Date`)
* `.creationIndex` più basso (per superare la precisione di 1ms)``` javascript
var cookies = [ /* unsorted array of Cookie objects */ ];
cookies = cookies.sort(cookieCompare);

Nota: Poiché Date in JavaScript ha una precisione di 1 ms, è del tutto possibile avere cookie nello stesso millisecondo. Questo è particolarmente vero quando si utilizza l'opzione now con .setCookie(). La proprietà .creationIndex è un contatore globale per processo, assegnato durante la costruzione con new Cookie(). Questo preserva lo spirito dell'ordinamento RFC: i cookie più vecchi vanno per primi. Funziona benissimo per MemoryCookieStore, poiché le intestazioni Set-Cookie vengono analizzate in ordine, ma potrebbe non essere altrettanto valido per sistemi distribuiti. I Store sofisticati potrebbero voler impostare questo valore su un altro orologio logico in modo tale che se i cookie A e B vengono creati nello stesso millisecondo, ma il cookie A viene creato prima del cookie B, allora A.creationIndex < B.creationIndex. Se si desidera alterare il contatore globale, cosa che probabilmente non si dovrebbe fare, è memorizzato in Cookie.cookiesCreated.

permuteDomain(domain)

Genera un elenco di tutti i possibili domini che soddisfano domainMatch() con il parametro. Può essere utile per implementare store di cookie.

permutePath(path)

Genera un elenco di tutti i possibili percorsi che soddisfano pathMatch() con il parametro. Può essere utile per implementare store di cookie.

Cookie

Esportato tramite tough.Cookie.

Cookie.parse(cookieString[, options])

Analizza una singola intestazione HTTP Cookie o Set-Cookie in un oggetto Cookie. Restituisce undefined se la stringa non può essere analizzata.

Il parametro options non è obbligatorio e attualmente ha una sola proprietà:

• loose - booleano - se true abilita l'analisi di cookie senza chiave come =abc e =, che non sono conformi alla RFC.

Se options non è un oggetto, viene ignorato, il che significa che puoi usare Array#map con esso.

Ecco come elaborare le intestazioni Set-Cookie in una risposta HTTP/HTTPS di 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:_ nella versione 2.3.3, tough-cookie limitava il numero di spazi prima di `=` a 256 caratteri. Questa limitazione è stata successivamente rimossa.
Vedi [Issue 92](https://github.com/salesforce/tough-cookie/issues/92)

### Proprietà

Proprietà dell'oggetto Cookie: