RFC6265 Куки и CookieJar для Node.js

Краткий обзор``` 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('; '); });

# Установка

Это _так_ просто!

`npm install tough-cookie`

Почему такое название? Модули NPM `cookie`, `cookies` и `cookiejar` уже были заняты.

## Поддержка версий

Поддержка версий node.js будет следовать за модулем [request](https://www.npmjs.com/package/request).

# API

## tough

Функции модуля, которые вы получаете из `require('tough-cookie')`. Все могут использоваться как чистые функции и не нуждаются в «привязке».

**Примечание**: до версии 1.0.x некоторые из этих функций принимали параметр `strict`. Впоследствии он был удалён из API как больше не являющийся необходимым.

### `parseDate(string)`

Преобразует строку даты куки в `Date`. Разбор выполняется в соответствии с RFC6265, раздел 5.1.1, а не `Date.parse()`.

### `formatDate(date)`

Форматирует Date в строку RFC1123 (рекомендуемый формат RFC6265).

### `canonicalDomain(str)`

Преобразует доменное имя в каноническое доменное имя. Каноническое доменное имя — это обрезанное, приведённое к нижнему регистру, лишённое ведущей точки и, возможно, закодированное в Punycode доменное имя (раздел 5.1.2 RFC6265). По большей части эта функция идемпотентна (может быть запущена повторно на своём выводе без негативных последствий).

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

Отвечает на вопрос «соответствует ли это реальное доменное имя домену в куки?». `str` — это «текущее» доменное имя, а `domStr` — «доменное имя куки». Соответствие определяется согласно RFC6265, раздел 5.1.3, но полезно думать об этом как о «совпадении суффикса».

Параметр `canonicalize` запускает два других параметра через `canonicalDomain` или нет.

### `defaultPath(path)`

Учитывая текущий путь запроса/ответа, возвращает путь, подходящий для сохранения в куки. По сути, это «каталог» «файла» в пути, но определяется разделом 5.1.4 RFC.

Параметр `path` ДОЛЖЕН быть _только_ частью пути URI (т.е. исключает имя хоста, запрос, фрагмент и т.д.). Это свойство `.pathname` вывода `uri.parse()` в node.

### `pathMatch(reqPath,cookiePath)`

Отвечает на вопрос «соответствует ли путь запроса заданному пути куки?» в соответствии с RFC6265, раздел 5.1.4. Возвращает логическое значение.

По сути, это проверка префикса, где `cookiePath` является префиксом `reqPath`.

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

алиас для `Cookie.parse(cookieString[, options])`

### `fromJSON(string)`

алиас для `Cookie.fromJSON(string)`

### `getPublicSuffix(hostname)`

Возвращает публичный суффикс этого имени хоста. Публичный суффикс — это кратчайшее доменное имя, для которого можно установить куки. Возвращает `null`, если для имени хоста нельзя установить куки.

Например: `www.example.com` и `www.subdomain.example.com` имеют публичный суффикс `example.com`.

Дополнительную информацию см. на http://publicsuffix.org/. Этот модуль получает свой список с этого сайта. Этот вызов в настоящее время является обёрткой вокруг [метода get()](https://www.npmjs.com/package/psl#pslgetdomain) из [`psl`](https://www.npmjs.com/package/psl).

### `cookieCompare(a,b)`

Для использования с `.sort()`, сортирует список куки в рекомендуемом порядке, указанном в RFC (раздел 5.4, шаг 2). Алгоритм сортировки по порядку приоритета:

* Самый длинный `.path`
* Самое старое `.creation` (с точностью 1 мс, как у `Date`)
* Наименьший `.creationIndex` (для выхода за пределы точности 1 мс)``` javascript
var cookies = [ /* unsorted array of Cookie objects */ ];
cookies = cookies.sort(cookieCompare);

Примечание: Поскольку Date в JavaScript имеет точность до 1 мс, cookies в пределах одной миллисекунды вполне возможны. Это особенно актуально при использовании опции now в .setCookie(). Свойство .creationIndex является глобальным счетчиком процесса, присваиваемым во время создания с помощью new Cookie(). Это сохраняет дух RFC-сортировки: старые cookies идут первыми. Это отлично работает для MemoryCookieStore, поскольку заголовки Set-Cookie разбираются по порядку, но может не очень хорошо подходить для распределенных систем. Сложные Store-ы могут захотеть установить этот параметр на другие логические часы, чтобы если cookies A и B созданы в одну миллисекунду, но cookie A создана до cookie B, то A.creationIndex < B.creationIndex. Если вы хотите изменить глобальный счетчик, что вам, вероятно, не стоит делать, он хранится в Cookie.cookiesCreated.

permuteDomain(domain)

Генерирует список всех возможных доменов, которым параметр соответствует domainMatch(). Может быть полезно для реализации хранилищ cookies.

permutePath(path)

Генерирует список всех возможных путей, которым параметр соответствует pathMatch(). Может быть полезно для реализации хранилищ cookies.

Cookie

Экспортируется через tough.Cookie.

Cookie.parse(cookieString[, options])

Разбирает один HTTP-заголовок Cookie или Set-Cookie в объект Cookie. Возвращает undefined, если строку не удалось разобрать.

Параметр options не является обязательным и в настоящее время имеет только одно свойство:

• loose - boolean - если true включает разбор cookies без ключа, таких как =abc и =, что не соответствует RFC.

Если options не является объектом, он игнорируется, что означает, что вы можете использовать Array#map с ним.

Вот как обработать заголовок(и) Set-Cookie в ответе node HTTP/HTTPS:``` 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:_ в версии 2.3.3 tough-cookie ограничивал количество пробелов перед `=` до 256 символов. Это ограничение было снято. См. [Issue 92](https://github.com/salesforce/tough-cookie/issues/92)

### Свойства

Свойства объекта Cookie:

  * _key_ - строка - имя или ключ cookie (по умолчанию "")
  * _value_ - строка - значение cookie (по умолчанию "")
  * _expires_ - `Date` - если задано, атрибут `Expires=` cookie (по умолчанию строка `"Infinity"`). См. `setExpires()`
  * _maxAge_ - секунды - если задано, атрибут `Max-Age=` _в секундах_ cookie. Также может быть установлен как строки `"Infinity"` и `"-Infinity"` для бессрочного и немедленного истечения соответственно. См. `setMaxAge()`
  * _domain_ - строка - атрибут `Domain=` cookie
  * _path_ - строка - `Path=` cookie
  * _secure_ - логическое - флаг `Secure` cookie
  * _httpOnly_ - логическое - флаг `HttpOnly` cookie
  * _extensions_ - `Array` - любые нераспознанные атрибуты cookie в виде строк (даже если внутри есть знаки равенства)
  * _creation_ - `Date` - когда был создан этот cookie
  * _creationIndex_ - число - устанавливается при создании, используется для обеспечения более высокой точности сортировки (см. `cookieCompare(a,b)` для полного объяснения)

После того как cookie был передан через `CookieJar.setCookie()`, он будет иметь следующие дополнительные атрибуты: