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)`

تنسيق تاريخ إلى سلسلة RFC1123 (التنسيق الموصى به من RFC6265).

### `canonicalDomain(str)`

تحويل اسم نطاق إلى اسم نطاق أساسي (canonical). اسم النطاق الأساسي هو اسم نطاق مقصوص، محول إلى أحرف صغيرة، منزوع من النقطة البادئة، واختياريًا مشفر بـ punycode (القسم 5.1.2 من RFC6265). في الغالب، هذه الدالة متطابقة (idempotent) (يمكن تشغيلها مرة أخرى على مخرجاتها دون آثار ضارة).

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

يجيب على السؤال: 'هل يتطابق هذا النطاق الحقيقي مع النطاق في الكوكي؟'. `str` هو اسم النطاق 'الحالي' و`domStr` هو اسم النطاق 'الكوكي'. يتطابق وفقًا للقسم 5.1.3 من RFC6265، لكن من المفيد التفكير فيه على أنه 'مطابقة لاحقة'.

معامل `canonicalize` سيمرر المعاملين الآخرين عبر `canonicalDomain` أم لا.

### `defaultPath(path)`

نظرًا لمسار الطلب/الاستجابة الحالي، يعطي المسار المناسب للتخزين في كوكي. هذا هو في الأساس 'دليل' 'ملف' في المسار، لكنه محدد بالقسم 5.1.4 من RFC.

يجب أن يكون معامل `path` _فقط_ جزء اسم المسار من URI (أي يستبعد اسم المضيف، الاستعلام، الجزء، إلخ). هذه هي خاصية `.pathname` لمخرجات `uri.parse()` في Node.

### `pathMatch(reqPath,cookiePath)`

يجيب على السؤال: 'هل يتطابق مسار الطلب مع مسار الكوكي المعطى؟' وفقًا للقسم 5.1.4 من RFC6265. يُرجع قيمة منطقية (boolean).

هذا هو في الأساس مطابقة بادئة حيث `cookiePath` هي بادئة لـ `reqPath`.

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

اسم مستعار لـ `Cookie.parse(cookieString[, options])`

### `fromJSON(string)`

اسم مستعار لـ `Cookie.fromJSON(string)`

### `getPublicSuffix(hostname)`

يُرجع اللاحقة العامة (public suffix) لاسم المضيف هذا. اللاحقة العامة هي أقصر اسم نطاق يمكن تعيين كوكي عليه. يُرجع `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: ملفات تعريف الارتباط الأقدم تذهب أولاً. يعمل هذا بشكل رائع مع MemoryCookieStore، حيث يتم تحليل رؤوس Set-Cookie بالترتيب، ولكنه قد لا يكون رائعًا للأنظمة الموزعة. قد ترغب Stores المتطورة في ضبط هذا على ساعة منطقية أخرى بحيث إذا تم إنشاء ملفي تعريف الارتباط A و B في نفس المللي ثانية، ولكن تم إنشاء A قبل B، فإن A.creationIndex < B.creationIndex. إذا كنت ترغب في تغيير العداد العام، وهو ما لا ينبغي عليك فعله على الأرجح، فهو مخزَّن في Cookie.cookiesCreated.

permuteDomain(domain)

ينشئ قائمة بجميع النطاقات الممكنة التي تطابقها domainMatch() مع المعامل. قد يكون مفيدًا لتنفيذ مخازن ملفات تعريف الارتباط.

permutePath(path)

ينشئ قائمة بجميع المسارات الممكنة التي تطابقها pathMatch() مع المعامل. قد يكون مفيدًا لتنفيذ مخازن ملفات تعريف الارتباط.

Cookie

تم تصديرها عبر tough.Cookie.

Cookie.parse(cookieString[, options])

يحلل رأس HTTP واحد من نوع Cookie أو Set-Cookie إلى كائن Cookie. يُرجع undefined إذا تعذر تحليل السلسلة النصية.

معامل الخيارات ليس مطلوبًا وله حاليًا خاصية واحدة فقط:

• loose - قيمة منطقية - إذا كانت true، تتيح تحليل ملفات تعريف الارتباط بدون مفتاح مثل =abc و =، والتي لا تتوافق مع RFC.

إذا لم يكن الخيارات كائنًا، يتم تجاهلها، مما يعني أنه يمكنك استخدام Array#map معها.

إليك كيفية معالجة رؤوس Set-Cookie في استجابة HTTP/HTTPS على 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'])];

_ملاحظة:_ في الإصدار 2.3.3، كان tough-cookie يحدد عدد المسافات قبل `=` بـ 256 حرفًا. تمت إزالة هذا الحد لاحقًا.  
انظر [القضية 92](https://github.com/salesforce/tough-cookie/issues/92)

### الخصائص

خصائص كائن ملف تعريف الارتباط (Cookie):

* _key_ - string - اسم أو مفتاح ملف تعريف الارتباط (القيمة الافتراضية "")
* _value_ - string - قيمة ملف تعريف الارتباط (القيمة الافتراضية "")
* _expires_ - `Date` - إذا تم تعيينه، سمة `Expires=` لملف تعريف الارتباط (القيمة الافتراضية هي السلسلة `"Infinity"`). انظر `setExpires()`
* _maxAge_ - seconds - إذا تم تعيينه، سمة `Max-Age=` _بالثواني_ لملف تعريف الارتباط. يمكن أيضًا تعيينه إلى السلسلتين `"Infinity"` و `"-Infinity"` لعدم الانتهاء والانتهاء الفوري، على التوالي. انظر `setMaxAge()`
* _domain_ - string - سمة `Domain=` لملف تعريف الارتباط
* _path_ - string - `Path=` لملف تعريف الارتباط
* _secure_ - boolean - علم `Secure` لملف تعريف الارتباط
* _httpOnly_ - boolean - علم `HttpOnly` لملف تعريف الارتباط
* _extensions_ - `Array` - أي سمات ملف تعريف ارتباط غير معروفة كسلاسل (حتى لو كانت تحتوي على علامات يساوي بالداخل)
* _creation_ - `Date` - وقت إنشاء ملف تعريف الارتباط هذا
* _creationIndex_ - number - يتم تعيينه عند الإنشاء، ويستخدم لتوفير دقة فرز أعلى (يرجى الاطلاع على `cookieCompare(a,b)` للحصول على شرح كامل)

بعد تمرير ملف تعريف الارتباط عبر `CookieJar.setCookie()`، سيكون له السمات الإضافية التالية:

* _hostOnly_ - boolean - هل هو ملف تعريف ارتباط خاص بالمضيف فقط (أي لم يتم تعيين حقل Domain، ولكن تم استنتاجه ضمنيًا)
* _pathIsDefault_ - boolean - إذا كان صحيحًا، لم يكن هناك حقل Path في ملف تعريف الارتباط وتم استخدام `defaultPath()` لاشتقاق واحد.
* _creation_ - `Date` - **معدل** من الإنشاء إلى وقت إضافة ملف تعريف الارتباط إلى الجرة
* _lastAccessed_ - `Date` - آخر مرة تم فيها الوصول إلى ملف تعريف الارتباط. سيؤثر على تنظيف ملفات تعريف الارتباط بمجرد تنفيذه. استخدام `cookiejar.getCookies(...)` سيحدث هذه السمة.

### `Cookie([{properties}])`

يستقبل كائن خيارات يمكن أن يحتوي على أي من خصائص ملف تعريف الارتباط المذكورة أعلاه، ويستخدم القيمة الافتراضية للخصائص غير المحددة.

### `.toString()`

ترميز إلى قيمة رأس Set-Cookie. يتم تعيين حقل Expires لملف تعريف الارتباط باستخدام `formatDate()`، ولكن يتم حذفه بالكامل إذا كان `.expires` يساوي `Infinity`.

### `.cookieString()`