guy2610/tough-cookie-patch-cve-2023-26136RFC6265-अनुरूप कुकी पार्सिंग और CookieJar प्रबंधन लाइब्रेरी Node.js के लिए, CVE-2023-26136 सुरक्षा पैच के साथ। HTTP क्लाइंट्स के लिए कुकी निर्माण, सत्यापन, भंडारण और पुनर्प्राप्ति का समर्थन करता है।
RFC6265 कुकीज़ और Node.js के लिए CookieJar
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)`
एक डोमेन-नाम को विहित डोमेन-नाम में रूपांतरित करता है। विहित डोमेन-नाम एक छंटा हुआ, लोअरकेस, अग्रणी डॉट हटाया हुआ और वैकल्पिक रूप से पनीकोड-एन्कोडेड डोमेन-नाम है (RFC6265 का खंड 5.1.2)। अधिकांश भाग के लिए, यह फ़ंक्शन आइडेम्पोटेंट है (बिना किसी प्रतिकूल प्रभाव के इसके आउटपुट पर फिर से चलाया जा सकता है)।
### `domainMatch(str,domStr[,canonicalize=true])`
उत्तर देता है 'क्या यह वास्तविक डोमेन कुकी में डोमेन से मेल खाता है?'। `str` 'वर्तमान' डोमेन-नाम है और `domStr` 'कुकी' डोमेन-नाम है। RFC6265 खंड 5.1.3 के अनुसार मेल खाता है, लेकिन इसे 'सफ़िक्स मैच' के रूप में सोचना सहायक है।
`canonicalize` पैरामीटर अन्य दो पैरामीटर को `canonicalDomain` के माध्यम से चलाएगा या नहीं।
### `defaultPath(path)`
एक वर्तमान अनुरोध/प्रतिक्रिया पथ दिए जाने पर, कुकी में संग्रहीत करने के लिए उपयुक्त पथ देता है। यह मूल रूप से पथ में 'फ़ाइल' की 'निर्देशिका' है, लेकिन RFC के खंड 5.1.4 द्वारा निर्दिष्ट है।
`path` पैरामीटर URI का _केवल_ पथनाम भाग होना चाहिए (अर्थात होस्टनाम, क्वेरी, फ्रैगमेंट आदि को शामिल नहीं करता)। यह node के `uri.parse()` आउटपुट की `.pathname` प्रॉपर्टी है।
### `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/ देखें। यह मॉड्यूल अपनी सूची उस साइट से प्राप्त करता है। यह कॉल वर्तमान में [`psl`](https://www.npmjs.com/package/psl) की [get() विधि](https://www.npmjs.com/package/psl#pslgetdomain) के आसपास एक रैपर है।
### `cookieCompare(a,b)`
`.sort()` के साथ उपयोग के लिए, कुकीज़ की एक सूची को RFC में दिए गए अनुशंसित क्रम में क्रमबद्ध करता है (खंड 5.4 चरण 2)। क्रमबद्ध एल्गोरिथ्म प्राथमिकता के क्रम में है:
* सबसे लंबा `.path`
* सबसे पुराना `.creation` (जिसमें 1ms सटीकता है, `Date` के समान)
* सबसे कम `.creationIndex` (1ms सटीकता से परे जाने के लिए)``` javascript
var cookies = [ /* unsorted array of Cookie objects */ ];
cookies = cookies.sort(cookieCompare);
नोट: चूंकि JavaScript का Date 1ms सटीकता तक सीमित है, एक ही मिलीसेकंड के भीतर कुकीज़ पूरी तरह से संभव हैं। यह विशेष रूप से तब सच है जब .setCookie() पर now विकल्प का उपयोग किया जाता है। .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])एकल Cookie या Set-Cookie HTTP हेडर को एक Cookie ऑब्जेक्ट में पार्स करता है। यदि स्ट्रिंग पार्स नहीं की जा सकती है तो undefined लौटाता है।
options पैरामीटर आवश्यक नहीं है और वर्तमान में केवल एक प्रॉपर्टी है:
true है तो कुंजी-रहित कुकीज़ जैसे =abc और = का पार्सिंग सक्षम करता है, जो RFC-अनुरूप नहीं हैं।यदि options एक ऑब्जेक्ट नहीं है, तो इसे अनदेखा किया जाता है, जिसका अर्थ है कि आप इसके साथ Array#map का उपयोग कर सकते हैं।
यहाँ बताया गया है कि नोड HTTP/HTTPS प्रतिक्रिया पर Set-Cookie हेडर(s) को कैसे संसाधित किया जाए:``` 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 वर्णों तक सीमित कर दिया था। यह सीमा अब हटा दी गई है।
देखें [Issue 92](https://github.com/salesforce/tough-cookie/issues/92)
### गुण (Properties)
कुकी ऑब्जेक्ट के गुण:
* _key_ - स्ट्रिंग - कुकी का नाम या कुंजी (डिफ़ॉल्ट "")
* _value_ - स्ट्रिंग - कुकी का मान (डिफ़ॉल्ट "")
* _expires_ - `Date` - यदि सेट किया गया हो, तो कुकी का `Expires=` गुण (डिफ़ॉल्ट स्ट्रिंग `"Infinity"`)। देखें `setExpires()`
* _maxAge_ - सेकंड - यदि सेट किया गया हो, तो कुकी का `Max-Age=` गुण _सेकंड में_। गैर-समाप्ति और तत्काल-समाप्ति के लिए क्रमशः स्ट्रिंग `"Infinity"` और `"-Infinity"` पर भी सेट किया जा सकता है। देखें `setMaxAge()`
* _domain_ - स्ट्रिंग - कुकी का `Domain=` गुण
* _path_ - स्ट्रिंग - कुकी का `Path=` गुण
* _secure_ - बूलियन - `Secure` कुकी फ़्लैग
* _httpOnly_ - बूलियन - `HttpOnly` कुकी फ़्लैग
* _extensions_ - `Array` - कोई भी अपरिचित कुकी गुण स्ट्रिंग के रूप में (भले ही उनमें बराबर के चिह्न हों)
* _creation_ - `Date` - यह कुकी कब बनाई गई थी
* _creationIndex_ - संख्या - निर्माण के समय सेट किया गया, बेहतर छँटाई सटीकता प्रदान करने के लिए उपयोग किया जाता है (पूर्ण स्पष्टीकरण के लिए कृपया `cookieCompare(a,b)` देखें)
कुकी को `CookieJar.setCookie()` के माध्यम से पारित करने के बाद, इसमें निम्नलिखित अतिरिक्त गुण होंगे:
* _hostOnly_ - बूलियन - क्या यह केवल-होस्ट कुकी है (अर्थात कोई Domain फ़ील्ड सेट नहीं किया गया था, बल्कि निहित था)
* _pathIsDefault_ - बूलियन - यदि सत्य है, तो कुकी पर कोई 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() उस पूर्ण यूनिक्स-युग मिलीसेकंड की गणना करता है जिस पर यह कुकी समाप्त होती है। expiryDate() समान रूप से काम करता है, सिवाय इसके कि यह एक `Date` ऑब्जेक्ट लौटाता है। ध्यान दें कि दोनों मामलों में `now` पैरामीटर मिलीसेकंड में होना चाहिए।
Max-Age Expires (RFC के अनुसार) पर पूर्वता लेता है। `.creation` गुण — या, डिफ़ॉल्ट रूप से, `now` पैरामीटर — का उपयोग `.maxAge` गुण को ऑफसेट करने के लिए किया जाता है।
यदि Expires (`.expires`) सेट है, तो वह लौटाया जाता है।
अन्यथा, `expiryTime()` `Infinity` लौटाता है और `expiryDate()` "Tue, 19 Jan 2038 03:14:07 GMT" के लिए एक `Date` ऑब्जेक्ट लौटाता है (सबसे नवीनतम तिथि जिसे 32-बिट `time_t` द्वारा व्यक्त किया जा सकता है; अधिकांश उपयोगकर्ता-एजेंटों के लिए सामान्य सीमा)।
### `.TTL([now=Date.now()])`
`now` (मिलीसेकंड) के सापेक्ष TTL की गणना करें। `expiryTime`/`expiryDate` के समान पूर्वता नियम लागू होते हैं।
संख्या `Infinity` स्पष्ट समाप्ति के बिना कुकीज़ के लिए लौटाई जाती है और `0` लौटाया जाता है यदि कुकी समाप्त हो गई है। अन्यथा मिलीसेकंड में जीवनकाल लौटाया जाता है।
### `.canonicalizedDomain()`
### `.cdomain()`
विहितीकृत `.domain` फ़ील्ड लौटाएँ। यह लोअर-केस किया जाता है और यदि डोमेन में कोई गैर-ASCII वर्ण हैं तो पनीकोड (RFC3490) एन्कोड किया जाता है।
### `.toJSON()`
`JSON.serialize(cookie)` का उपयोग करने की सुविधा के लिए। एक सादा-पुराना `Object` लौटाता है जिसे JSON-सीरियलाइज़ किया जा सकता है।
कोई भी `Date` गुण (अर्थात `.expires`, `.creation`, और `.lastAccessed`) ISO प्रारूप (`.toISOString()`) में निर्यात किए जाते हैं।
**नोट:** कस्टम `Cookie` गुण त्याग दिए जाएंगे। tough-cookie 1.x में, चूंकि कोई `.toJSON` विधि स्पष्ट रूप से परिभाषित नहीं थी, सभी गणनीय गुण कैप्चर किए गए थे। यदि आप चाहते हैं कि कोई गुण सीरियलाइज़ हो, तो गुण नाम को `Cookie.serializableProperties` Array में जोड़ें।
### `Cookie.fromJSON(strOrObj)`
`cookie.toJSON()` का उल्टा करता है। यदि एक स्ट्रिंग पारित किया गया है, तो पहले `JSON.parse()` करेगा।
कोई भी `Date` गुण (अर्थात `.expires`, `.creation`, और `.lastAccessed`) `Date.parse()` के माध्यम से पार्स किए जाते हैं, tough-cookie के `parseDate` के माध्यम से नहीं, क्योंकि इस परत पर JavaScript/JSON-y टाइमस्टैम्प संभाले जा रहे हैं।
JSON पार्सिंग त्रुटि पर `null` लौटाता है।
### `.clone()`
इस कुकी का एक डीप क्लोन करता है, बिल्कुल `Cookie.fromJSON(cookie.toJSON())` के रूप में कार्यान्वित।
### `.validate()`
स्थिति: *प्रगति पर*। कुछ चीज़ों के लिए काम करता है, लेकिन किसी भी तरह से व्यापक नहीं है।
अर्थगत शुद्धता के लिए कुकी गुणों को मान्य करता है। आपके द्वारा उत्पन्न किसी भी 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 विधियों के लिए निरंतरता-पासिंग शैली (continuation-passing style) का उपयोग किया जाता है।
.setCookie(cookieOrString, currentUrl, [{options},] cb(err,cookie))कुकी जार में कुकी सेट करने का प्रयास। यदि ऑपरेशन विफल होता है, तो कॉलबैक cb को एक त्रुटि दी जाएगी, अन्यथा कुकी को पास कर दिया जाता है। कुकी में अद्यतन .creation, .lastAccessed और .hostOnly गुण होंगे।
options ऑब्जेक्ट को छोड़ा जा सकता है और इसमें निम्नलिखित गुण हो सकते हैं:
true - इंगित करता है कि यह HTTP या गैर-HTTP API है या नहीं। HttpOnly कुकीज़ को प्रभावित करता है।https: या wss: से शुरू होता है तो यह डिफ़ॉल्ट रूप से true होता है, अन्यथा false।new Date() - कुकीज़ के निर्माण/पहुँच समय के लिए क्या उपयोग करना हैfalse - पार्स त्रुटियों और अमान्य डोमेन जैसी चीज़ों को चुपचाप अनदेखा करें। Store की त्रुटियाँ इस विकल्प से अनदेखा नहीं की जाती हैं।RFC के अनुसार, .hostOnly गुण सेट किया जाता है यदि कुकी स्ट्रिंग में कोई "Domain=" पैरामीटर नहीं था (या Cookie ऑब्जेक्ट पर .domain null था)। इस स्थिति में .domain गुण currentUrl के पूर्णतः योग्य होस्टनाम पर सेट किया जाता है। इस कुकी का मिलान करने के लिए सटीक होस्टनाम मिलान की आवश्यकता होती है (न कि सामान्य रूप से domainMatch)।
.setCookieSync(cookieOrString, currentUrl, [{options}])setCookie का सिंक्रोनस संस्करण; केवल सिंक्रोनस स्टोर्स के साथ काम करता है (जैसे डिफ़ॉल्ट MemoryCookieStore)।
.getCookies(currentUrl, [{options},] cb(err,cookies))वर्तमान url के लिए Cookie हेडर में भेजी जा सकने वाली कुकीज़ की सूची प्राप्त करें।
यदि कोई त्रुटि आती है, तो वह कॉलबैक को err के रूप में पास की जाती है, अन्यथा Cookie ऑब्जेक्ट्स की एक Array पास की जाती है। सरणी को cookieCompare() के साथ क्रमबद्ध किया जाता है जब तक कि {sort:false} विकल्प न दिया गया हो।
options ऑब्जेक्ट को छोड़ा जा सकता है और इसमें निम्नलिखित गुण हो सकते हैं:
true - इंगित करता है कि यह HTTP या गैर-HTTP API है या नहीं। 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 Array में गुण का नाम जोड़ें।
[Serialization Format] देखें।
.serializeSync().serialize का सिंक संस्करण
.toJSON()JSON.stringify(cookiejar) की सुविधा के लिए .serializeSync() का उपनाम।
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)Cookie.fromJSON() के साथ संगति प्रदान करने के लिए .deserializeSync का उपनाम।
.clone([store,]cb(err,newJar))इस जार की गहरी प्रतिलिपि (deep clone) बनाता है। मूल में संशोधन प्रतिलिपि को प्रभावित नहीं करेंगे, और इसके विपरीत।
store तर्क वैकल्पिक है, लेकिन Store का एक उदाहरण होना चाहिए। डिफ़ॉल्ट रूप से, MemoryCookieStore का एक नया उदाहरण बनाया जाता है। स्टोर प्रकारों के बीच स्थानांतरण तब तक समर्थित है जब तक स्रोत .getAllCookies() लागू करता है और गंतव्य .putCookie() लागू करता है।
.cloneSync([store]).clone का सिंक्रोनस संस्करण, एक नया CookieJar उदाहरण लौटाता है।
store तर्क वैकल्पिक है, लेकिन यदि निर्दिष्ट किया गया है तो एक सिंक्रोनस Store उदाहरण होना चाहिए। यदि पास नहीं किया गया है, तो MemoryCookieStore का एक नया उदाहरण उपयोग किया जाता है।
स्रोत और गंतव्य दोनों सिंक्रोनस Stores होने चाहिए। यदि एक या दोनों स्टोर एसिंक्रोनस हैं, तो इसके बजाय .clone का उपयोग करें। याद रखें कि MemoryCookieStore सिंक्रोनस और एसिंक्रोनस दोनों API कॉल का समर्थन करता है।
.removeAllCookies(cb(err))जार से सभी कुकीज़ हटाता है।
यह tough-cookie संस्करण 2.5 की एक नई पिछड़ा-संगत सुविधा है, इसलिए सभी स्टोर इसे कुशलतापूर्वक लागू नहीं करेंगे। उन स्टोर्स के लिए जो removeAllCookies लागू नहीं करते हैं, फॉलबैक getAllCookies के बाद removeCookie को कॉल करना है। यदि getAllCookies विफल होता है या स्टोर में लागू नहीं किया गया है, तो वह त्रुटि वापस आती है। यदि एक या अधिक removeCookie कॉल विफल होते हैं, तो केवल पहली त्रुटि वापस आती है।
.removeAllCookiesSync().removeAllCookies() का सिंक संस्करण
CookieJar स्टोर्स के लिए आधार वर्ग। tough.Store के रूप में उपलब्ध।
प्रत्येक CookieJar उदाहरण के लिए भंडारण मॉडल को एक कस्टम कार्यान्वयन से बदला जा सकता है। डिफ़ॉल्ट MemoryCookieStore है जो lib/memstore.js फ़ाइल में पाया जा सकता है। API एसिंक्रोनस स्टोर्स की अनुमति देने के लिए निरंतरता-पासिंग-शैली (continuation-passing-style) का उपयोग करता है।
स्टोर्स को आधार Store वर्ग से इनहेरिट करना चाहिए, जो require('tough-cookie').Store के रूप में उपलब्ध है।
स्टोर्स डिफ़ॉल्ट रूप से एसिंक्रोनस होते हैं, लेकिन यदि store.synchronous को true पर सेट किया जाता है, तो कंटेनिंग CookieJar पर *Sync विधियों का उपयोग किया जा सकता है (हालाँकि, निरंतरता-पासिंग शैली
कॉल करने से पहले सभी domain पैरामीटर सामान्यीकृत (normalized) कर दिए जाएँगे।
Cookie स्टोर में निम्नलिखित सभी विधियाँ होनी चाहिए।
store.findCookie(domain, path, key, cb(err,cookie))दिए गए डोमेन, पथ और कुंजी (उर्फ नाम) के साथ एक कुकी प्राप्त करें। RFC बनाए रखता है कि स्टोर में इनमें से ठीक एक कुकी मौजूद होनी चाहिए। यदि स्टोर वर्जनिंग का उपयोग कर रहा है, तो इसका मतलब है कि ऐसी नवीनतम/नवीनतम कुकी वापस की जानी चाहिए।
कॉलबैक एक त्रुटि और परिणामी Cookie ऑब्जेक्ट लेता है। यदि कोई कुकी नहीं मिलती है तो उसके स्थान पर null पास किया जाना चाहिए (अर्थात त्रुटि नहीं)।
store.findCookies(domain, path, cb(err,cookies))दिए गए डोमेन और पथ से मेल खाने वाली कुकीज़ ढूँढता है। यह अक्सर ऊपर cookiejar.getCookies() के संदर्भ में कॉल किया जाता है।
यदि कोई कुकी नहीं मिलती है, तो कॉलबैक को एक खाली सरणी पास की जानी चाहिए।
परिणामी सूची को RFC के अनुसार वर्तमान अनुरोध के लिए प्रयोज्यता के लिए जाँचा जाएगा (डोमेन-मिलान, पथ-मिलान, http-केवल-ध्वज, सुरक्षित-ध्वज, समाप्ति, आदि), इसलिए इस विधि को लागू करते समय एक आशावादी खोज एल्गोरिथ्म का उपयोग करना ठीक है। हालाँकि, उपयोग किए गए खोज एल्गोरिथ्म को उन कुकीज़ को खोजने का प्रयास करना चाहिए जो domainMatch() डोमेन और pathMatch() पथ से मेल खाती हैं ताकि किए जाने वाले जाँच की मात्रा को सीमित किया जा सके।
संस्करण 0.9.12 के अनुसार, ऊपर cookiejar.getCookies() का allPaths विकल्प यहाँ पथ को null कर देगा। यदि पथ null है, तो पथ-मिलान नहीं किया जाना चाहिए (अर्थात केवल डोमेन-मिलान)।
store.putCookie(cookie, cb(err))स्टोर में एक नई कुकी जोड़ता है। कार्यान्वयन को समान .domain, .path, और .key गुणों वाली किसी भी मौजूदा कुकी को बदलना चाहिए -- कार्यान्वयन की प्रकृति के आधार पर, यह संभव है कि fetchCookie और putCookie के बीच कॉल के बीच एक डुप्लिकेट putCookie हो सकता है।
cookie ऑब्जेक्ट को संशोधित नहीं किया जाना चाहिए; कॉल करने वाले ने पहले ही .creation और .lastAccessed गुणों को अपडेट कर दिया होगा।
यदि कुकी संग्रहीत नहीं की जा सकती तो एक त्रुटि पास करें।
store.updateCookie(oldCookie, newCookie, cb(err))एक मौजूदा कुकी को अपडेट करें। कार्यान्वयन को समान domain, .path और .key वाली कुकी के लिए .value को अपडेट करना चाहिए। कार्यान्वयन को जाँचना चाहिए कि स्टोर में पुराना मान oldCookie के बराबर है या नहीं - संघर्ष को कैसे हल किया जाता है यह स्टोर पर निर्भर है।
.lastAccessed गुण हमेशा दो ऑब्जेक्ट्स के बीच भिन्न होगा (जावास्क्रिप्ट की घड़ी के माध्यम से संभव सटीकता तक)। .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))वैकल्पिक. jar.serialize() के दौरान सभी कुकीज़ की एक Array तैयार करता है। सरणी में आइटम सही Cookie ऑब्जेक्ट या [Serialization Format] डेटा संरचना वाले सामान्य Objects हो सकते हैं।
compareCookies() के माध्यम से छँटाई को संरक्षित करने के लिए कुकीज़ को निर्माण क्रम में वापस किया जाना चाहिए। संदर्भ के लिए, MemoryCookieStore .creationIndex द्वारा क्रमबद्ध होगा क्योंकि यह आंतरिक रूप से सही Cookie ऑब्जेक्ट का उपयोग करता है। यदि आप कुकीज़ को निर्माण क्रम में वापस नहीं करते हैं, तब भी उन्हें निर्माण समय के अनुसार क्रमबद्ध किया जाएगा, लेकिन इसकी केवल 1ms की सटीकता है। अधिक जानकारी के लिए compareCookies देखें।
यदि पुनर्प्राप्ति विफल होती है तो एक त्रुटि पास करें।
नोट: सभी स्टोर तकनीकी सीमाओं के कारण इसे लागू नहीं कर सकते, इसलिए यह वैकल्पिक है।
Store से इनहेरिट करता है।
एक सिर्फ-इन-मेमोरी CookieJar सिंक्रोनस स्टोर कार्यान्वयन, डिफ़ॉल्ट रूप से उपयोग किया जाता है। सिंक्रोनस कार्यान्वयन होने के बावजूद, यह CookieJar API के सिंक्रोनस और एसिंक्रोनस दोनों रूपों के साथ उपयोग योग्य है। सीरियलाइज़ेशन, getAllCookies और removeAllCookies का समर्थन करता है।
ये कुछ स्टोर कार्यान्वयन हैं जो समुदाय द्वारा लिखे और बनाए रखे गए हैं। वे आधिकारिक नहीं हैं और हम उनके लिए प्रतिज्ञा नहीं करते हैं, लेकिन आपको उन पर एक नज़र डालने में रुचि हो सकती है:
db-cookie-store: SQLite-आधारित डेटाबेस सहित SQLfile-cookie-store: डिस्क पर Netscape कुकी फ़ाइल स्वरूपredis-cookie-store: Redistough-cookie-filestore: डिस्क पर JSONtough-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.