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'])];

CookieJar

Esportato tramite tough.CookieJar.

CookieJar([store],[options])

Usa semplicemente new CookieJar(). Se desideri utilizzare un archivio personalizzato, passalo al costruttore, altrimenti verrà creato e utilizzato un MemoryCookieStore.

L'oggetto options può essere omesso e può avere le seguenti proprietà:

• rejectPublicSuffixes - booleano - default true - rifiuta i cookie con domini come "com" e "co.uk"
• looseMode - booleano - default false - accetta cookie malformati come bar e =bar, che hanno un nome vuoto implicito. Questo non è nello standard, ma viene talvolta utilizzato sul web ed è accettato dalla maggior parte dei browser.

Poiché alla fine questo modulo intende supportare CookieJar da database/remoto/ecc., per i metodi di CookieJar viene utilizzato lo stile di passaggio di continuazione.

.setCookie(cookieOrString, currentUrl, [{options},] cb(err,cookie))

Tenta di impostare il cookie nel jar dei cookie. Se l'operazione fallisce, un errore verrà passato al callback cb, altrimenti il cookie viene passato attraverso. Il cookie avrà aggiornate le proprietà .creation, .lastAccessed e .hostOnly.

L'oggetto options può essere omesso e può avere le seguenti proprietà:

• http - booleano - default true - indica se questa è un'API HTTP o non HTTP. Influenza i cookie HttpOnly.
• secure - booleano - rilevamento automatico dall'url - indica se questa è un'API "Secure". Se currentUrl inizia con https: o wss:, allora viene impostato di default a true, altrimenti false.
• now - Date - default new Date() - cosa usare per il tempo di creazione/accesso dei cookie
• ignoreError - booleano - default false - ignora silenziosamente cose come errori di parsing e domini non validi. Gli errori Store non vengono ignorati da questa opzione.

Secondo la RFC, la proprietà .hostOnly viene impostata se non c'era un parametro "Domain=" nella stringa del cookie (o .domain era nullo sull'oggetto Cookie). La proprietà .domain viene impostata al nome host completo di currentUrl in questo caso. Abbinare questo cookie richiede una corrispondenza esatta del nome host (non un domainMatch come al solito).

.setCookieSync(cookieOrString, currentUrl, [{options}])

Versione sincrona di setCookie; funziona solo con archivi sincroni (ad esempio il MemoryCookieStore predefinito).

.getCookies(currentUrl, [{options},] cb(err,cookies))

Recupera l'elenco dei cookie che possono essere inviati in un'intestazione Cookie per l'url corrente.

Se viene riscontrato un errore, questo viene passato come err al callback, altrimenti viene passato un Array di oggetti Cookie. L'array viene ordinato con cookieCompare() a meno che non venga fornita l'opzione {sort:false}.

L'oggetto options può essere omesso e può avere le seguenti proprietà:

• http - booleano - default true - indica se questa è un'API HTTP o non HTTP. Influenza i cookie HttpOnly.
• secure - booleano - rilevamento automatico dall'url - indica se questa è un'API "Secure". Se currentUrl inizia con https: o wss:, allora viene impostato di default a true, altrimenti false.
• now - Date - default new Date() - cosa usare per il tempo di creazione/accesso dei cookie
• expire - booleano - default true - esegue il controllo del tempo di scadenza dei cookie e rimuove in modo asincrono i cookie scaduti dall'archivio. Usare false restituirà i cookie scaduti e non li rimuoverà dall'archivio (il che è potenzialmente utile per riprodurre le intestazioni Set-Cookie).
• allPaths - booleano - default false - se true, non limitare i cookie per percorso. L'impostazione predefinita utilizza l'ambito del percorso conforme alla RFC. Nota: potrebbe non essere supportato dall'archivio sottostante (il MemoryCookieStore predefinito lo supporta).

La proprietà .lastAccessed dei cookie restituiti sarà stata aggiornata.

.getCookiesSync(currentUrl, [{options}])

Versione sincrona di getCookies; funziona solo con archivi sincroni (ad esempio il MemoryCookieStore predefinito).

.getCookieString(...)

Accetta le stesse opzioni di .getCookies() ma passa una stringa adatta per un'intestazione Cookie invece di un array al callback. Semplicemente mappa l'array di Cookie tramite .cookieString().

.getCookieStringSync(...)

Versione sincrona di getCookieString; funziona solo con archivi sincroni (ad esempio il MemoryCookieStore predefinito).

.getSetCookieStrings(...)

Restituisce un array di stringhe adatte per le intestazioni Set-Cookie. Accetta le stesse opzioni di .getCookies(). Semplicemente mappa l'array di cookie tramite .toString().

.getSetCookieStringsSync(...)

Versione sincrona di getSetCookieStrings; funziona solo con archivi sincroni (ad esempio il MemoryCookieStore predefinito).

.serialize(cb(err,serializedObject))

Serializza il Jar se l'archivio sottostante supporta .getAllCookies.

NOTA: Le proprietà personalizzate di Cookie verranno scartate. Se desideri che una proprietà venga serializzata, aggiungi il nome della proprietà all'array Cookie.serializableProperties.

Vedi [Serialization Format].

.serializeSync()

Versione sincrona di .serialize

.toJSON()

Alias di .serializeSync() per comodità di JSON.stringify(cookiejar).

CookieJar.deserialize(serialized, [store], cb(err,object))

Viene creato un nuovo Jar e i Cookie serializzati vengono aggiunti all'archivio sottostante. Ogni Cookie viene aggiunto tramite store.putCookie nell'ordine in cui appaiono nella serializzazione.

L'argomento store è opzionale, ma dovrebbe essere un'istanza di Store. Per impostazione predefinita, viene creata una nuova istanza di MemoryCookieStore.

Come comodità, se serialized è una stringa, viene prima passata attraverso JSON.parse. Se questo genera un errore, viene passato al callback.

CookieJar.deserializeSync(serialized, [store])

Versione sincrona di .deserialize. Nota che store deve essere sincrono per funzionare.

CookieJar.fromJSON(string)

Alias di .deserializeSync per fornire coerenza con Cookie.fromJSON().

.clone([store,]cb(err,newJar))

Produce una copia profonda di questo jar. Le modifiche all'originale non influenzeranno la copia, e viceversa.

L'argomento store è opzionale, ma dovrebbe essere un'istanza di Store. Per impostazione predefinita, viene creata una nuova istanza di MemoryCookieStore. Il trasferimento tra tipi di archivio è supportato fintanto che la sorgente implementa .getAllCookies() e la destinazione implementa .putCookie().

.cloneSync([store])

Versione sincrona di .clone, che restituisce una nuova istanza di CookieJar.

L'argomento store è opzionale, ma deve essere un'istanza sincrona di Store se specificato. Se non passato, viene utilizzata una nuova istanza di MemoryCookieStore.

La sorgente e la destinazione devono essere entrambi Store sincroni. Se uno o entrambi gli archivi sono asincroni, usa .clone invece. Ricorda che MemoryCookieStore supporta chiamate API sia sincrone che asincrone.

.removeAllCookies(cb(err))

Rimuove tutti i cookie dal jar.

Questa è una nuova funzionalità retrocompatibile di tough-cookie versione 2.5, quindi non tutti gli Store la implementeranno in modo efficiente. Per gli Store che non implementano removeAllCookies, il fallback è chiamare removeCookie dopo getAllCookies. Se getAllCookies fallisce o non è implementato nello Store, viene restituito quell'errore. Se una o più chiamate removeCookie falliscono, viene restituito solo il primo errore.

.removeAllCookiesSync()

Versione sincrona di .removeAllCookies()

Store

Classe base per gli store di CookieJar. Disponibile come tough.Store.

Store API

Il modello di archiviazione per ogni istanza di CookieJar può essere sostituito con un'implementazione personalizzata. Il predefinito è MemoryCookieStore che si trova nel file lib/memstore.js. L'API utilizza lo stile di passaggio di continuazione per consentire store asincroni.

Gli Store dovrebbero ereditare dalla classe base Store, disponibile come require('tough-cookie').Store.

Gli Store sono asincroni per impostazione predefinita, ma se store.synchronous è impostato a true, allora i metodi *Sync sul CookieJar contenitore possono essere usati (tuttavia, lo stile di passaggio di continuazione

Tutti i parametri domain saranno stati normalizzati prima della chiamata.

L'archivio dei cookie deve avere tutti i seguenti metodi.

store.findCookie(domain, path, key, cb(err,cookie))

Recupera un cookie con il dato dominio, percorso e chiave (ovvero nome). La RFC sostiene che esattamente uno di questi cookie dovrebbe esistere in un archivio. Se l'archivio utilizza il versioning, ciò significa che il cookie più recente/nuovo dovrebbe essere restituito.

Il callback riceve un errore e l'oggetto Cookie risultante. Se non viene trovato alcun cookie, allora deve essere passato null (cioè non un errore).

store.findCookies(domain, path, cb(err,cookies))

Trova i cookie che corrispondono al dato dominio e percorso. Questo viene spesso chiamato nel contesto di cookiejar.getCookies() sopra.

Se non vengono trovati cookie, al callback deve essere passato un array vuoto.

La lista risultante verrà controllata per l'applicabilità alla richiesta corrente secondo la RFC (domain-match, path-match, http-only-flag, secure-flag, expiry, ecc.), quindi va bene usare un algoritmo di ricerca ottimistico quando si implementa questo metodo. Tuttavia, l'algoritmo di ricerca utilizzato DOVREBBE cercare di trovare cookie che domainMatch() il dominio e pathMatch() il percorso per limitare la quantità di controlli da fare.

A partire dalla versione 0.9.12, l'opzione allPaths di cookiejar.getCookies() sopra farà sì che il percorso qui sia null. Se il percorso è null, la corrispondenza del percorso NON DEVE essere eseguita (cioè solo corrispondenza del dominio).

store.putCookie(cookie, cb(err))

Aggiunge un nuovo cookie all'archivio. L'implementazione DOVREBBE sostituire qualsiasi cookie esistente con le stesse proprietà .domain, .path e .key -- a seconda della natura dell'implementazione, è possibile che tra la chiamata a fetchCookie e putCookie possa verificarsi un putCookie duplicato.

L'oggetto cookie NON DEVE essere modificato; il chiamante avrà già aggiornato le proprietà .creation e .lastAccessed.

Passa un errore se il cookie non può essere memorizzato.

store.updateCookie(oldCookie, newCookie, cb(err))

Aggiorna un cookie esistente. L'implementazione DEVE aggiornare il .value per un cookie con lo stesso domain, .path e .key. L'implementazione DOVREBBE verificare che il vecchio valore nell'archivio sia equivalente a oldCookie - come viene risolto il conflitto dipende dall'archivio.

La proprietà .lastAccessed sarà sempre diversa tra i due oggetti (con la precisione possibile tramite il clock di JavaScript). Sia .creation che .creationIndex sono garantiti essere gli stessi. Gli Store POSSONO ignorare o differire la modifica di .lastAccessed a costo di influenzare come i cookie vengono selezionati per la cancellazione automatica (ad esempio, meno recentemente usati, che spetta all'archivio implementare).

Gli Store potrebbero desiderare di ottimizzare la modifica del .value del cookie nell'archivio rispetto alla memorizzazione di un nuovo cookie. Se l'implementazione non definisce questo metodo, verrà aggiunto all'oggetto store uno stub che chiama putCookie(newCookie,cb).

Gli oggetti newCookie e oldCookie NON DEVONO essere modificati.

Passa un errore se newCookie non può essere memorizzato.

store.removeCookie(domain, path, key, cb(err))

Rimuove un cookie dall'archivio (vedi note su findCookie riguardo al vincolo di unicità).

L'implementazione NON DEVE passare un errore se il cookie non esiste; passa un errore solo per il fallimento nella rimozione di un cookie esistente.

store.removeCookies(domain, path, cb(err))

Rimuove i cookie corrispondenti dall'archivio. Il parametro path è opzionale, e se mancante significa che tutti i percorsi in un dominio devono essere rimossi.

Passa un errore SOLO se la rimozione di alcuni cookie esistenti è fallita.

store.removeAllCookies(cb(err))

Opzionale. Rimuove tutti i cookie dall'archivio.

Passa un errore se uno o più cookie non possono essere rimossi.

Nota: Nuovo metodo a partire dalla versione 2.5 di tough-cookie, quindi non tutti gli Store lo implementeranno, inoltre alcuni store potrebbero scegliere di non implementarlo.

store.getAllCookies(cb(err, cookies))

Opzionale. Produce un Array di tutti i cookie durante jar.serialize(). Gli elementi nell'array possono essere oggetti Cookie reali o generici Object con la struttura dati del [Formato di serializzazione].

I cookie DOVREBBERO essere restituiti in ordine di creazione per preservare l'ordinamento tramite compareCookies(). Per riferimento, MemoryCookieStore ordinerà per .creationIndex poiché usa internamente oggetti Cookie reali. Se non restituisci i cookie in ordine di creazione, saranno comunque ordinati per tempo di creazione, ma questo ha una precisione di 1ms. Vedi compareCookies per maggiori dettagli.

Passa un errore se il recupero fallisce.

Nota: non tutti gli Store possono implementarlo a causa di limitazioni tecniche, quindi è opzionale.

MemoryCookieStore

Eredita da Store.

Un'implementazione di archivio sincrono CookieJar solo in memoria, usata per impostazione predefinita. Nonostante sia un'implementazione sincrona, è utilizzabile con entrambe le forme sincrone e asincrone dell'API CookieJar. Supporta la serializzazione, getAllCookies e removeAllCookies.

Community Cookie Stores

Queste sono alcune implementazioni di Store create e mantenute dalla community. Non sono ufficiali e non ne garantiamo il funzionamento, ma potresti essere interessato a dare un'occhiata:

• db-cookie-store: SQL inclusi database basati su SQLite
• file-cookie-store: formato file cookie Netscape su disco
• redis-cookie-store: Redis
• tough-cookie-filestore: JSON su disco
• tough-cookie-web-storage-store: DOM localStorage e sessionStorage

Formato di serializzazione

NOTA: se desideri che le proprietà personalizzate di Cookie vengano serializzate, aggiungi il nome della proprietà a Cookie.serializableProperties.```js { // The version of tough-cookie that serialized this jar. version: '[email protected]',

}