guy2610/tough-cookie-patch-cve-2023-26136مكتبة تحليل الكوكيز وإدارة CookieJar متوافقة مع RFC6265 لبيئة Node.js، مع تصحيح أمني لـ CVE-2023-26136. تدعم إنشاء الكوكيز والتحقق منها وتخزينها واسترجاعها لعملاء HTTP.
RFC6265 ملفات تعريف الارتباط وCookieJar لـ Node.js
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() مع المعامل. قد يكون مفيدًا لتنفيذ مخازن ملفات تعريف الارتباط.
تم تصديرها عبر tough.Cookie.
Cookie.parse(cookieString[, options])يحلل رأس HTTP واحد من نوع Cookie أو Set-Cookie إلى كائن Cookie. يُرجع undefined إذا تعذر تحليل السلسلة النصية.
معامل الخيارات ليس مطلوبًا وله حاليًا خاصية واحدة فقط:
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()`
ترميز إلى قيمة رأس Cookie (أي خاصيتا `.key` و `.value` متصلتان بـ '=').
### `.setExpires(String)`
تعيين تاريخ الانتهاء بناءً على سلسلة تاريخ تم تمريرها عبر `parseDate()`. إذا أعادت `parseDate` قيمة `null` (أي لا يمكن تحليل سلسلة التاريخ هذه)، يتم تعيين `.expires` على `"Infinity"` (سلسلة).
### `.setMaxAge(number)`
تعيين maxAge بالثواني. يحول `-Infinity` إلى `"-Infinity"` و `Infinity` إلى `"Infinity"` بحيث يتم تسلسل JSON بشكل صحيح.
### `.expiryTime([now=Date.now()])`
### `.expiryDate([now=Date.now()])`
`expiryTime()` تحسب المللي ثانية المطلقة من عصر Unix التي ينتهي عندها ملف تعريف الارتباط هذا. تعمل `expiryDate()` بالمثل، لكنها تعيد كائن `Date`. لاحظ أنه في كلتا الحالتين يجب أن تكون معلمة `now` بالمللي ثانية.
Max-Age له الأسبقية على Expires (وفقًا لـ RFC). يتم استخدام السمة `.creation` - أو افتراضيًا، المعلمة `now` - لتعويض السمة `.maxAge`.
إذا تم تعيين Expires (`.expires`)، يتم إرجاع ذلك.
خلاف ذلك، تعيد `expiryTime()` قيمة `Infinity` وتعيد `expiryDate()` كائن `Date` لـ "Tue, 19 Jan 2038 03:14:07 GMT" (أحدث تاريخ يمكن التعبير عنه بواسطة `time_t` 32 بت؛ الحد الشائع لمعظم وكلاء المستخدم).
### `.TTL([now=Date.now()])`
حساب TTL بالنسبة لـ `now` (بالمللي ثانية). تنطبق نفس قواعد الأسبقية كما في `expiryTime`/`expiryDate`.
يتم إرجاع الرقم `Infinity` لملفات تعريف الارتباط دون انتهاء صريح ويتم إرجاع `0` إذا كان ملف تعريف الارتباط منتهي الصلاحية. خلاف ذلك، يتم إرجاع وقت البقاء بالمللي ثانية.
### `.canonicalizedDomain()`
### `.cdomain()`
إرجاع حقل `.domain` المقنن. هذا يتم تحويله إلى أحرف صغيرة وترميز punycode (RFC3490) إذا كان المجال يحتوي على أي أحرف غير ASCII.
### `.toJSON()`
لتسهيل استخدام `JSON.serialize(cookie)`. يعيد كائن `Object` عادي يمكن تسلسله JSON.
يتم تصدير أي خصائص `Date` (أي `.expires` و `.creation` و `.lastAccessed`) بتنسيق ISO (`.toISOString()`).
**ملاحظة**: سيتم تجاهل خصائص `Cookie` المخصصة. في tough-cookie 1.x، نظرًا لعدم وجود طريقة `.toJSON` محددة صراحة، تم التقاط جميع الخصائص القابلة للعد. إذا كنت تريد تسلسل خاصية، أضف اسم الخاصية إلى مصفوفة `Cookie.serializableProperties`.
### `Cookie.fromJSON(strOrObj)
يقوم بعكس `cookie.toJSON()`. إذا تم تمرير سلسلة، فسيتم تحليل `JSON.parse()` أولاً.
يتم تحليل أي خصائص `Date` (أي `.expires` و `.creation` و `.lastAccessed`) عبر `Date.parse()`، وليس عبر `parseDate` الخاص بـ tough-cookie، نظرًا لأنها طوابع زمنية بتنسيق JavaScript/JSON يتم التعامل معها في هذه الطبقة.
يعيد `null` عند خطأ تحليل JSON.
### `.clone()`
يقوم بنسخ عميق لملف تعريف الارتباط هذا، منفذ تمامًا كـ `Cookie.fromJSON(cookie.toJSON())`.
### `.validate()`
الحالة: *قيد التقدم*. يعمل لبعض الأشياء، لكنه ليس شاملاً بأي حال من الأحوال.
يتحقق من صحة سمات ملف تعريف الارتباط للصحة الدلالية. مفيد لفحص "lint" لأي رؤوس Set-Cookie التي تنشئها. في الوقت الحالي، يعيد قيمة منطقية، لكنه قد يعيد في النهاية سلسلة سبب - يمكنك التحضير للمستقبل بهذا البناء:``` javascript
if (cookie.validate() === true) {
// it's tasty
} else {
// yuck!
}
مُصَدَّر عبر tough.CookieJar.
CookieJar([store],[options])استخدم ببساطة new CookieJar(). إذا كنت ترغب في استخدام مخزن مخصص، قم بتمريره إلى المُنشئ وإلا سيتم إنشاء واستخدام MemoryCookieStore.
يمكن حذف كائن options ويمكن أن يحتوي على الخصائص التالية:
true - رفض ملفات تعريف الارتباط ذات النطاقات مثل "com" و "co.uk"false - قبول ملفات تعريف الارتباط غير الصحيحة مثل bar و =bar، والتي لها اسم فارغ ضمني.
هذا ليس في المعيار، ولكنه يُستخدم أحيانًا على الويب ويُقبل من قبل معظم المتصفحات.نظرًا لأن هذه الوحدة ترغب في النهاية في دعم قواعد البيانات / البعيد / إلخ من CookieJars، يتم استخدام نمط تمرير الاستمرارية لطرق CookieJar.
.setCookie(cookieOrString, currentUrl, [{options},] cb(err,cookie))حاول تعيين ملف تعريف الارتباط في جرة ملفات تعريف الارتباط. إذا فشلت العملية، سيتم إعطاء خطأ لرد الاتصال cb، وإلا يتم تمرير ملف تعريف الارتباط. سيكون لملف تعريف الارتباط خصائص .creation و .lastAccessed و .hostOnly المحدثة.
يمكن حذف كائن options ويمكن أن يحتوي على الخصائص التالية:
true - يشير إلى ما إذا كانت هذه واجهة برمجة تطبيقات HTTP أو غير HTTP. يؤثر على ملفات تعريف الارتباط HttpOnly.https: أو wss: فسيتم تعيين هذا افتراضيًا إلى true، وإلا false.new Date() - ما يجب استخدامه لوقت إنشاء / الوصول إلى ملفات تعريف الارتباطfalse - تجاهل بصمت أشياء مثل أخطاء التحليل والنطاقات غير الصالحة. لا يتم تجاهل أخطاء Store بواسطة هذا الخيار.وفقًا لـ RFC، يتم تعيين الخاصية .hostOnly إذا لم تكن هناك معلمة "Domain=" في سلسلة ملف تعريف الارتباط (أو كانت .domain فارغة على كائن Cookie). يتم تعيين الخاصية .domain إلى اسم المضيف المؤهل بالكامل لـ currentUrl في هذه الحالة. تتطلب مطابقة ملف تعريف الارتباط هذا تطابقًا دقيقًا لاسم المضيف (وليس domainMatch كالمعتاد).
.setCookieSync(cookieOrString, currentUrl, [{options}])إصدار متزامن من setCookie؛ يعمل فقط مع المخازن المتزامنة (على سبيل المثال، MemoryCookieStore الافتراضي).
.getCookies(currentUrl, [{options},] cb(err,cookies))استرجع قائمة ملفات تعريف الارتباط التي يمكن إرسالها في رأس Cookie لعنوان url الحالي.
إذا تمت مواجهة خطأ، يتم تمريره كـ err إلى رد الاتصال، وإلا يتم تمرير Array من كائنات Cookie. يتم فرز المصفوفة باستخدام cookieCompare() ما لم يتم إعطاء الخيار {sort:false}.
يمكن حذف كائن options ويمكن أن يحتوي على الخصائص التالية:
true - يشير إلى ما إذا كانت هذه واجهة برمجة تطبيقات HTTP أو غير HTTP. يؤثر على ملفات تعريف الارتباط HttpOnly.https: أو wss: فسيتم تعيين هذا افتراضيًا إلى true، وإلا false.new Date() - ما يجب استخدامه لوقت إنشاء / الوصول إلى ملفات تعريف الارتباطtrue - إجراء فحص وقت انتهاء صلاحية ملفات تعريف الارتباط وإزالة ملفات تعريف الارتباط منتهية الصلاحية بشكل غير متزامن من المخزن. استخدام false سيعيد ملفات تعريف الارتباط منتهية الصلاحية و لن يزيلها من المخزن (وهو مفيد لإعادة تشغيل رؤوس Set-Cookie، ربما).false - إذا كان true، لا تقم بنطاق ملفات تعريف الارتباط حسب المسار. الافتراضي يستخدم نطاق المسار المتوافق مع RFC. ملاحظة: قد لا يكون مدعومًا من قبل المخزن الأساسي (يدعمه MemoryCookieStore الافتراضي).سيتم تحديث الخاصية .lastAccessed لملفات تعريف الارتباط التي تم إرجاعها.
.getCookiesSync(currentUrl, [{options}])إصدار متزامن من getCookies؛ يعمل فقط مع المخازن المتزامنة (على سبيل المثال، MemoryCookieStore الافتراضي).
.getCookieString(...)يقبل نفس خيارات .getCookies() ولكنه يمرر سلسلة مناسبة لرأس Cookie بدلاً من مصفوفة إلى رد الاتصال. يقوم ببساطة بتعيين مصفوفة Cookie عبر .cookieString().
.getCookieStringSync(...)إصدار متزامن من getCookieString؛ يعمل فقط مع المخازن المتزامنة (على سبيل المثال، MemoryCookieStore الافتراضي).
.getSetCookieStrings(...)يعيد مصفوفة من السلاسل المناسبة لرؤوس Set-Cookie. يقبل نفس خيارات .getCookies(). يقوم ببساطة بتعيين مصفوفة ملفات تعريف الارتباط عبر .toString().
.getSetCookieStringsSync(...)إصدار متزامن من getSetCookieStrings؛ يعمل فقط مع المخازن المتزامنة (على سبيل المثال، MemoryCookieStore الافتراضي).
.serialize(cb(err,serializedObject))تسلسل الجرة إذا كان المخزن الأساسي يدعم .getAllCookies.
ملاحظة: سيتم تجاهل خصائص Cookie المخصصة. إذا كنت تريد تسلسل خاصية، أضف اسم الخاصية إلى مصفوفة Cookie.serializableProperties.
انظر [تنسيق التسلسل].
.serializeSync()إصدار متزامن من .serialize
.toJSON()اسم مستعار لـ .serializeSync() لتسهيل استخدام JSON.stringify(cookiejar).
CookieJar.deserialize(serialized, [store], cb(err,object))يتم إنشاء جرة جديدة وإضافة ملفات تعريف الارتباط المسلسلة إلى المخزن الأساسي. يتم إضافة كل Cookie عبر store.putCookie بالترتيب الذي تظهر به في التسلسل.
الوسيطة store اختيارية، ولكن يجب أن تكون مثيلًا لـ Store. افتراضيًا، يتم إنشاء مثيل جديد لـ MemoryCookieStore.
لتسهيل الأمر، إذا كان serialized سلسلة نصية، فسيتم تمريرها عبر JSON.parse أولاً. إذا ألقى ذلك خطأ، فسيتم تمريره إلى رد الاتصال.
CookieJar.deserializeSync(serialized, [store])إصدار متزامن من .deserialize. ملاحظة يجب أن يكون store متزامنًا حتى يعمل هذا.
CookieJar.fromJSON(string)اسم مستعار لـ .deserializeSync لتوفير الاتساق مع Cookie.fromJSON().
.clone([store,]cb(err,newJar))ينتج نسخة عميقة من هذه الجرة. لن تؤثر التعديلات على الأصل على النسخة، والعكس صحيح.
الوسيطة store اختيارية، ولكن يجب أن تكون مثيلًا لـ Store. افتراضيًا، يتم إنشاء مثيل جديد لـ MemoryCookieStore. يتم دعم النقل بين أنواع المخازن طالما أن المصدر يطبق .getAllCookies() والوجهة تطبق .putCookie().
.cloneSync([store])إصدار متزامن من .clone، يعيد مثيلًا جديدًا لـ CookieJar.
الوسيطة store اختيارية، ولكن يجب أن تكون مثيل Store متزامن إذا تم تحديدها. إذا لم يتم تمريرها، يتم استخدام مثيل جديد من MemoryCookieStore.
يجب أن يكون كل من المصدر و الوجهة مخازن Store متزامنة. إذا كان أحد المخازن أو كلاهما غير متزامن، استخدم .clone بدلاً من ذلك. تذكر أن MemoryCookieStore يدعم مكالمات API المتزامنة وغير المتزامنة.
.removeAllCookies(cb(err))يزيل جميع ملفات تعريف الارتباط من الجرة.
هذه ميزة جديدة متوافقة مع الإصدارات السابقة من tough-cookie الإصدار 2.5، لذلك لن تنفذها جميع المخازن بكفاءة. بالنسبة للمخازن التي لا تنفذ removeAllCookies، يكون الحل البديل هو استدعاء removeCookie بعد getAllCookies. إذا فشل getAllCookies أو لم يتم تنفيذه في المخزن، يتم إرجاع هذا الخطأ. إذا فشلت واحدة أو أكثر من استدعاءات removeCookie، فسيتم إرجاع الخطأ الأول فقط.
.removeAllCookiesSync()إصدار متزامن من .removeAllCookies()
الفئة الأساسية لمخازن CookieJar. متاحة كـ tough.Store.
يمكن استبدال نموذج التخزين لكل مثيل CookieJar بتطبيق مخصص. الافتراضي هو MemoryCookieStore الموجود في ملف lib/memstore.js. تستخدم API نمط تمرير الاستمرارية للسماح بالمخازن غير المتزامنة.
يجب أن ترث المخازن من الفئة الأساسية Store، المتاحة كـ require('tough-cookie').Store.
المخازن غير متزامنة بشكل افتراضي، ولكن إذا تم تعيين store.synchronous على true، فيمكن استخدام طرق *Sync الموجودة على CookieJar المحتوي (ومع ذلك، فإن نمط تمرير الاستمرارية
سيتم تسوية جميع معاملات domain قبل الاتصال.
يجب أن يحتوي مخزن ملفات تعريف الارتباط على جميع الطرق التالية.
store.findCookie(domain, path, key, cb(err,cookie))استرجع ملف تعريف ارتباط بالنطاق والمسار والمفتاح (أي الاسم) المحددين. تنص RFC على أنه يجب أن يكون هناك بالضبط واحد من ملفات تعريف الارتباط هذه في المخزن. إذا كان المخزن يستخدم الإصدارات، فهذا يعني أنه يجب إرجاع أحدث / أحدث ملف تعريف ارتباط من هذا القبيل.
يأخذ رد الاتصال خطأ وكائن Cookie الناتج. إذا لم يتم العثور على ملف تعريف ارتباط، فيجب تمرير null بدلاً من ذلك (أي ليس خطأ).
store.findCookies(domain, path, cb(err,cookies))يحدد موقع ملفات تعريف الارتباط المطابقة للنطاق والمسار المحددين. غالبًا ما يتم استدعاء هذا في سياق cookiejar.getCookies() أعلاه.
إذا لم يتم العثور على ملفات تعريف ارتباط، فيجب تمرير مصفوفة فارغة إلى رد الاتصال.
سيتم فحص القائمة الناتجة للتأكد من ملاءمتها للطلب الحالي وفقًا لـ RFC (مطابقة النطاق، مطابقة المسار، علامة http-only، علامة secure، انتهاء الصلاحية، إلخ)، لذلك لا بأس من استخدام خوارزمية بحث متفائلة عند تنفيذ هذه الطريقة. ومع ذلك، يجب أن تحاول خوارزمية البحث المستخدمة العثور على ملفات تعريف الارتباط التي تطابق domainMatch() النطاق و pathMatch() المسار من أجل الحد من مقدار الفحص الذي يجب القيام به.
اعتبارًا من الإصدار 0.9.12، سيتسبب الخيار allPaths في cookiejar.getCookies() أعلاه في أن يكون المسار هنا null. إذا كان المسار null، فلا يجب إجراء مطابقة المسار (أي مطابقة النطاق فقط).
store.putCookie(cookie, cb(err))يضيف ملف تعريف ارتباط جديد إلى المخزن. يجب أن يستبدل التنفيذ أي ملف تعريف ارتباط موجود بنفس خصائص .domain و .path و .key - اعتمادًا على طبيعة التنفيذ، من الممكن أن يحدث putCookie مكرر بين استدعاء fetchCookie و putCookie.
يجب عدم تعديل كائن cookie؛ سيكون المتصل قد قام بالفعل بتحديث خصائص .creation و .lastAccessed.
مرر خطأ إذا تعذر تخزين ملف تعريف الارتباط.
store.updateCookie(oldCookie, newCookie, cb(err))تحديث ملف تعريف ارتباط موجود. يجب أن يقوم التنفيذ بتحديث .value لملف تعريف ارتباط بنفس domain و .path و .key. يجب أن يتحقق التنفيذ من أن القيمة القديمة في المخزن مكافئة لـ oldCookie - كيفية حل التعارض متروك للمخزن.
ستكون الخاصية .lastAccessed مختلفة دائمًا بين الكائنين (للدقة الممكنة عبر ساعة JavaScript). كل من .creation و .creationIndex مضمونان ليكونوا متماثلين. قد تتجاهل المخازن أو تؤجل تغيير .lastAccessed على حساب التأثير على كيفية اختيار ملفات تعريف الارتباط للحذف التلقائي (على سبيل المثال، الأقل استخدامًا مؤخرًا، وهو أمر متروك للمخزن لتنفيذه).
قد ترغب المخازن في تحسين تغيير .value لملف تعريف الارتباط في المخزن بدلاً من تخزين ملف تعريف ارتباط جديد. إذا لم يحدد التنفيذ هذه الطريقة، فسيتم إضافة كعب روتين يستدعي putCookie(newCookie,cb) إلى كائن المخزن.
يجب عدم تعديل كائني newCookie و oldCookie.
مرر خطأ إذا تعذر تخزين newCookie.
store.removeCookie(domain, path, key, cb(err))إزالة ملف تعريف ارتباط من المخزن (انظر الملاحظات على findCookie حول قيد التفرد).
يجب ألا يمرر التنفيذ خطأ إذا كان ملف تعريف الارتباط غير موجود؛ مرر خطأ فقط بسبب فشل إزالة ملف تعريف ارتباط موجود.
store.removeCookies(domain, path, cb(err))يزيل ملفات تعريف الارتباط المطابقة من المخزن. المعلمة path اختيارية، وإذا كانت مفقودة فهذا يعني أنه يجب إزالة جميع المسارات في نطاق.
مرر خطأ فقط إذا فشلت إزالة أي ملفات تعريف ارتباط موجودة.
store.removeAllCookies(cb(err))اختياري. يزيل جميع ملفات تعريف الارتباط من المخزن.
مرر خطأ إذا تعذرت إزالة ملف تعريف ارتباط واحد أو أكثر.
ملاحظة: طريقة جديدة اعتبارًا من tough-cookie الإصدار 2.5، لذلك لن تنفذها جميع المخازن، بالإضافة إلى أن بعض المخازن قد تختار عدم تنفيذها.
store.getAllCookies(cb(err, cookies))اختياري. ينتج Array من جميع ملفات تعريف الارتباط أثناء jar.serialize(). يمكن أن تكون العناصر في المصفوفة كائنات Cookie حقيقية أو كائنات Object عامة بهيكل بيانات [تنسيق التسلسل].
يجب إرجاع ملفات تعريف الارتباط بترتيب الإنشاء للحفاظ على الفرز عبر compareCookies(). كمرجع، سيقوم MemoryCookieStore بالفرز حسب .creationIndex لأنه يستخدم كائنات Cookie حقيقية داخليًا. إذا لم تقم بإرجاع ملفات تعريف الارتباط بترتيب الإنشاء، فسيتم فرزها حسب وقت الإنشاء، لكن هذا له دقة 1 مللي ثانية فقط. راجع compareCookies لمزيد من التفاصيل.
مرر خطأ إذا فشل الاسترجاع.
ملاحظة: ليست كل المخازن يمكنها تنفيذ هذا بسبب قيود تقنية، لذلك فهو اختياري.
يرث من Store.
تنفيذ مخزن متزامن في الذاكرة فقط لـ CookieJar، يُستخدم افتراضيًا. على الرغم من كونه تنفيذًا متزامنًا، إلا أنه قابل للاستخدام مع كل من الأشكال المتزامنة وغير المتزامنة لواجهة برمجة تطبيقات CookieJar. يدعم التسلسل و getAllCookies و removeAllCookies.
هذه بعض تطبيقات المخازن التي ألفها وصيانتها المجتمع. إنها ليست رسمية ولا نضمنها لكن قد تكون مهتمًا بإلقاء نظرة:
db-cookie-store: SQL بما في ذلك قواعد البيانات المستندة إلى SQLitefile-cookie-store: تنسيق ملف ملفات تعريف الارتباط Netscape على القرصredis-cookie-store: Redistough-cookie-filestore: JSON على القرصtough-cookie-web-storage-store: DOM localStorage و sessionStorageملاحظة: إذا كنت تريد تسلسل خصائص Cookie مخصصة، أضف اسم الخاصية إلى Cookie.serializableProperties.```js
{
// The version of tough-cookie that serialized this jar.
version: '[email protected]',
// add the store type, to make humans happy:
storeType: 'MemoryCookieStore',
// CookieJar configuration:
rejectPublicSuffixes: true,
// ... future items go here
// Gets filled from jar.store.getAllCookies():
cookies: [
{
key: 'string',
value: 'string',
// ...
/* other Cookie.serializableProperties go here */
}
]
}
# حقوق النشر والترخيص
BSD-3-Clause:```text
Copyright (c) 2015, Salesforce.com, Inc.
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
3. Neither the name of Salesforce.com nor the names of its contributors may
be used to endorse or promote products derived from this software without
specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.