RFC6265 Cookies y CookieJar para Node.js

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

# Instalación

¡Es _tan_ fácil!

`npm install tough-cookie`

¿Por qué ese nombre?  Los módulos de NPM `cookie`, `cookies` y `cookiejar` ya estaban ocupados.

## Soporte de versiones

El soporte para versiones de node.js seguirá el del módulo [request](https://www.npmjs.com/package/request).

# API

## tough

Funciones en el módulo que obtienes de `require('tough-cookie')`.  Todas pueden usarse como funciones puras y no necesitan estar "vinculadas".

**Nota**: antes de 1.0.x, varias de estas funciones aceptaban un parámetro `strict`. Esto se eliminó de la API desde entonces, ya que no era necesario.

### `parseDate(string)`

Analiza una cadena de fecha de cookie en un `Date`.  El análisis se realiza según la RFC6265 Sección 5.1.1, no `Date.parse()`.

### `formatDate(date)`

Da formato a un Date como una cadena RFC1123 (el formato recomendado por RFC6265).

### `canonicalDomain(str)`

Transforma un nombre de dominio en un nombre de dominio canónico.  El nombre de dominio canónico es un nombre de dominio recortado, en minúsculas, sin el punto inicial y, opcionalmente, codificado en punycode (Sección 5.1.2 de RFC6265).  En su mayor parte, esta función es idempotente (puede ejecutarse nuevamente sobre su salida sin efectos adversos).

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

Responde "¿coincide este dominio real con el dominio en una cookie?".  `str` es el nombre de dominio "actual" y `domStr` es el nombre de dominio de la "cookie".  La coincidencia se determina según la RFC6265 Sección 5.1.3, pero ayuda pensar en ello como una "coincidencia por sufijo".

El parámetro `canonicalize` hará pasar los otros dos parámetros por `canonicalDomain` o no.

### `defaultPath(path)`

Dado un path de solicitud/respuesta actual, da el Path apropiado para almacenar en una cookie.  Esto es básicamente el "directorio" de un "archivo" en el path, pero está especificado por la Sección 5.1.4 de la RFC.

El parámetro `path` DEBE ser _solo_ la parte de nombre de ruta de una URI (es decir, excluye el hostname, la consulta, el fragmento, etc.).  Esta es la propiedad `.pathname` de la salida de `uri.parse()` de node.

### `pathMatch(reqPath,cookiePath)`

Responde "¿coincide el request-path con un cookie-path dado?" según la RFC6265 Sección 5.1.4.  Devuelve un booleano.

Esto es esencialmente una coincidencia de prefijo donde `cookiePath` es un prefijo de `reqPath`.

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

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

### `fromJSON(string)`

alias de `Cookie.fromJSON(string)`

### `getPublicSuffix(hostname)`

Devuelve el sufijo público de este hostname.  El sufijo público es el nombre de dominio más corto en el que se puede establecer una cookie.  Devuelve `null` si el hostname no puede tener cookies establecidas.

Por ejemplo: `www.example.com` y `www.subdomain.example.com` ambos tienen el sufijo público `example.com`.

Para más información, consulta http://publicsuffix.org/.  Este módulo deriva su lista de ese sitio.  Esta llamada es actualmente un envoltorio alrededor del [método get()](https://www.npmjs.com/package/psl#pslgetdomain) de [`psl`](https://www.npmjs.com/package/psl).

### `cookieCompare(a,b)`

Para usar con `.sort()`, ordena una lista de cookies en el orden recomendado por la RFC (Sección 5.4, paso 2).  El algoritmo de ordenamiento es, en orden de precedencia:

* `.path` más largo
* `.creation` más antiguo (que tiene una precisión de 1ms, igual que `Date`)
* `.creationIndex` más bajo (para superar la precisión de 1ms)``` javascript
var cookies = [ /* unsorted array of Cookie objects */ ];
cookies = cookies.sort(cookieCompare);

Nota: Dado que Date de JavaScript está limitado a una precisión de 1 ms, es totalmente posible que haya cookies dentro del mismo milisegundo. Esto es especialmente cierto cuando se usa la opción now con .setCookie(). La propiedad .creationIndex es un contador global por proceso, asignado durante la construcción con new Cookie(). Esto preserva el espíritu del ordenamiento RFC: las cookies más antiguas van primero. Esto funciona muy bien para MemoryCookieStore, ya que las cabeceras Set-Cookie se analizan en orden, pero puede no ser tan bueno para sistemas distribuidos. Los Stores sofisticados pueden querer establecer esto en algún otro reloj lógico de modo que si las cookies A y B se crean en el mismo milisegundo, pero la cookie A se crea antes que la cookie B, entonces A.creationIndex < B.creationIndex. Si quieres alterar el contador global, lo cual probablemente no deberías hacer, se almacena en Cookie.cookiesCreated.

permuteDomain(domain)

Genera una lista de todos los dominios posibles que domainMatch() el parámetro. Puede resultar útil para implementar almacenes de cookies.

permutePath(path)

Genera una lista de todas las rutas posibles que pathMatch() el parámetro. Puede resultar útil para implementar almacenes de cookies.

Cookie

Exportado mediante tough.Cookie.

Cookie.parse(cookieString[, options])

Analiza una única cabecera HTTP Cookie o Set-Cookie en un objeto Cookie. Devuelve undefined si la cadena no se puede analizar.

El parámetro options no es obligatorio y actualmente solo tiene una propiedad:

• loose - booleano - si es true, habilita el análisis de cookies sin clave como =abc y =, que no cumplen con RFC.

Si options no es un objeto, se ignora, lo que significa que puedes usar Array#map con él.

Así es como se procesan las cabeceras Set-Cookie en una respuesta HTTP/HTTPS de 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'])];

_Nota:_ en la versión 2.3.3, tough-cookie limitaba el número de espacios antes del `=` a 256 caracteres. Esta limitación se ha eliminado desde entonces.
Ver [Issue 92](https://github.com/salesforce/tough-cookie/issues/92)

### Propiedades

Propiedades del objeto Cookie:

  * _key_ - string - el nombre o clave de la cookie (por defecto "")
  * _value_ - string - el valor de la cookie (por defecto "")
  * _expires_ - `Date` - si se establece, el atributo `Expires=` de la cookie (por defecto la cadena `"Infinity"`). Ver `setExpires()`
  * _maxAge_ - segundos - si se establece, el atributo `Max-Age=` _en segundos_ de la cookie. También puede establecerse como las cadenas `"Infinity"` y `"-Infinity"` para no expiración y expiración inmediata, respectivamente. Ver `setMaxAge()`
  * _domain_ - string - el atributo `Domain=` de la cookie
  * _path_ - string - el `Path=` de la cookie
  * _secure_ - boolean - el indicador `Secure` de la cookie
  * _httpOnly_ - boolean - el indicador `HttpOnly` de la cookie
  * _extensions_ - `Array` - cualquier atributo de cookie no reconocido como cadenas (incluso si contienen signos igual)
  * _creation_ - `Date` - cuándo se construyó esta cookie
  * _creationIndex_ - number - se establece en la construcción, se usa para proporcionar mayor precisión de ordenación (consulte `cookieCompare(a,b)` para una explicación completa)