RFC6265 Cookies e CookieJar para Node.js

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

# Instalação

É _tão_ fácil!

`npm install tough-cookie`

Por que esse nome? Os módulos NPM `cookie`, `cookies` e `cookiejar` já estavam ocupados.

## Suporte de Versão

O suporte para versões do node.js seguirá o do módulo [request](https://www.npmjs.com/package/request).

# API

## tough

Funções no módulo que você obtém de `require('tough-cookie')`. Todas podem ser usadas como funções puras e não precisam ser "ligadas".

**Nota**: antes da versão 1.0.x, várias dessas funções aceitavam um parâmetro `strict`. Isso foi removido da API desde então, pois não era mais necessário.

### `parseDate(string)`

Analisa uma string de data de cookie em um `Date`. A análise segue a RFC6265 Seção 5.1.1, não `Date.parse()`.

### `formatDate(date)`

Formata uma Data em uma string RFC1123 (o formato recomendado pela RFC6265).

### `canonicalDomain(str)`

Transforma um nome de domínio em um nome de domínio canônico. O nome de domínio canônico é um nome de domínio com espaços removidos, em minúsculas, sem ponto inicial e opcionalmente codificado em punycode (Seção 5.1.2 da RFC6265). Na maioria dos casos, esta função é idempotente (pode ser executada novamente em sua saída sem efeitos adversos).

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

Responde "este domínio real corresponde ao domínio em um cookie?". O `str` é o nome de domínio "atual" e o `domStr` é o nome de domínio do "cookie". A correspondência segue a RFC6265 Seção 5.1.3, mas ajuda pensar nisso como uma "correspondência de sufixo".

O parâmetro `canonicalize` executará os outros dois parâmetros através de `canonicalDomain` ou não.

### `defaultPath(path)`

Dado um caminho de solicitação/resposta atual, fornece o Caminho apropriado para armazenar em um cookie. Isso é basicamente o "diretório" de um "arquivo" no caminho, mas é especificado pela Seção 5.1.4 da RFC.

O parâmetro `path` DEVE ser _apenas_ a parte do nome do caminho de uma URI (ou seja, exclui o nome do host, consulta, fragmento, etc.). Esta é a propriedade `.pathname` da saída de `uri.parse()` do node.

### `pathMatch(reqPath,cookiePath)`

Responde "o caminho da solicitação corresponde a um determinado caminho de cookie?" conforme RFC6265 Seção 5.1.4. Retorna um booleano.

Isso é essencialmente uma correspondência de prefixo onde `cookiePath` é um prefixo de `reqPath`.

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

atalho para `Cookie.parse(cookieString[, options])`

### `fromJSON(string)`

atalho para `Cookie.fromJSON(string)`

### `getPublicSuffix(hostname)`

Retorna o sufixo público deste nome de host. O sufixo público é o nome de domínio mais curto no qual um cookie pode ser definido. Retorna `null` se o nome de host não puder ter cookies definidos para ele.

Por exemplo: `www.example.com` e `www.subdomain.example.com` ambos têm o sufixo público `example.com`.

Para mais informações, veja http://publicsuffix.org/. Este módulo obtém sua lista desse site. Esta chamada é atualmente um invólucro em torno do [método get()](https://www.npmjs.com/package/psl#pslgetdomain) do [`psl`](https://www.npmjs.com/package/psl).

### `cookieCompare(a,b)`

Para uso com `.sort()`, ordena uma lista de cookies na ordem recomendada dada pela RFC (Seção 5.4 passo 2). O algoritmo de ordenação é, em ordem de precedência:

* `.path` mais longo
* `.creation` mais antigo (que tem precisão de 1ms, igual a `Date`)
* menor `.creationIndex` (para superar a precisão de 1ms)``` javascript
var cookies = [ /* unsorted array of Cookie objects */ ];
cookies = cookies.sort(cookieCompare);

Nota: Como o Date do JavaScript tem precisão limitada a 1 ms, cookies dentro do mesmo milissegundo são totalmente possíveis. Isso é especialmente verdade ao usar a opção now em .setCookie(). A propriedade .creationIndex é um contador global por processo, atribuído durante a construção com new Cookie(). Isso preserva o espírito da ordenação RFC: cookies mais antigos vão primeiro. Isso funciona muito bem para MemoryCookieStore, já que os cabeçalhos Set-Cookie são analisados em ordem, mas talvez não seja tão bom para sistemas distribuídos. Stores sofisticados podem desejar definir isso como algum outro relógio lógico de modo que, se os cookies A e B forem criados no mesmo milissegundo, mas o cookie A for criado antes do cookie B, então A.creationIndex < B.creationIndex. Se você quiser alterar o contador global, o que provavelmente não deveria fazer, ele está armazenado em Cookie.cookiesCreated.

permuteDomain(domain)

Gera uma lista de todos os domínios possíveis que correspondem a domainMatch() no parâmetro. Pode ser útil para implementar armazenamentos de cookies.

permutePath(path)

Gera uma lista de todos os caminhos possíveis que correspondem a pathMatch() no parâmetro. Pode ser útil para implementar armazenamentos de cookies.

Cookie

Exportado via tough.Cookie.

Cookie.parse(cookieString[, options])

Analisa um único cabeçalho HTTP Cookie ou Set-Cookie em um objeto Cookie. Retorna undefined se a string não puder ser analisada.

O parâmetro options não é obrigatório e atualmente tem apenas uma propriedade:

• loose - booleano - se true ativa a análise de cookies sem chave como =abc e =, que não estão em conformidade com a RFC.

Se options não for um objeto, ele é ignorado, o que significa que você pode usar Array#map com ele.

Veja como processar o(s) cabeçalho(s) Set-Cookie em uma resposta HTTP/HTTPS do 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:_ na versão 2.3.3, tough-cookie limitou o número de espaços antes do `=` a 256 caracteres. Essa limitação foi removida desde então.
Veja [Issue 92](https://github.com/salesforce/tough-cookie/issues/92)

### Propriedades

Propriedades do objeto Cookie:

  * _key_ - string - o nome ou chave do cookie (padrão "")
  * _value_ - string - o valor do cookie (padrão "")
  * _expires_ - `Date` - se definido, o atributo `Expires=` do cookie (padrão é a string `"Infinity"`). Veja `setExpires()`
  * _maxAge_ - segundos - se definido, o atributo `Max-Age=` _em segundos_ do cookie. Também pode ser definido como as strings `"Infinity"` e `"-Infinity"` para não expiração e expiração imediata, respectivamente. Veja `setMaxAge()`
  * _domain_ - string - o atributo `Domain=` do cookie
  * _path_ - string - o `Path=` do cookie
  * _secure_ - boolean - a flag `Secure` do cookie
  * _httpOnly_ - boolean - a flag `HttpOnly` do cookie
  * _extensions_ - `Array` - quaisquer atributos de cookie não reconhecidos como strings (mesmo que contenham sinais de igual)
  * _creation_ - `Date` - quando este cookie foi construído
  * _creationIndex_ - number - definido na construção, usado para fornecer maior precisão de ordenação (veja `cookieCompare(a,b)` para uma explicação completa)

Após um cookie ter passado por `CookieJar.setCookie()`, ele terá os seguintes atributos adicionais: