قرصان

قرصان

تطبيق متوافق مع البرامج الوسيطة وقابل للتكوين بدرجة كبيرة لـ CORS لـ Node.js.

سجل التغيير

2.0.1 (16 أغسطس 2016)

• أضف حلاً بديلاً لـ Chrome 52 بإرسال رأس Access-Control-Request-Headers الفارغ.

2.0.0 (22 مارس 2014)

• يتم إغلاق طلبات الاختبار المبدئي تلقائيًا. إذا كانت هناك حاجة للتعامل مع طلبات OPTIONS ، فحدد خيار endPreflightRequests .
• معلمات وظيفة رد الاتصال في التحقق من الأصل الديناميكي أصبحت الآن (err, matches) بدلاً من (matches) فقط.

أمثلة

كيفية استخدام Corser كبرنامج وسيط في Express

انظر example/express/ للحصول على مثال عملي.

 var express, corser, app;

express = require("express");
corser = require("corser");

app = express();

app.use(corser.create());

app.get("/", function (req, res) {
    res.writeHead(200);
    res.end("Nice weather today, huh?");
});

app.listen(1337);

كيفية استخدام Corser كبرنامج وسيط في Connect

انظر example/connect/ للحصول على مثال عملي.

 var connect, corser, app;

connect = require("connect");
corser = require("corser");

app = connect();

app.use(corser.create());

app.use(function (req, res) {
    res.writeHead(200);
    res.end("Nice weather today, huh?");
});

app.listen(1337);

كيفية استخدام Corser مع http عادي

 var http, corser, corserRequestListener;

http = require("http");
corser = require("corser");

// Create Corser request listener.
corserRequestListener = corser.create();

http.createServer(function (req, res) {
    // Route req and res through the request listener.
    corserRequestListener(req, res, function () {
        res.writeHead(200);
        res.end("Nice weather today, huh?");
    });
}).listen(1337);

واجهة برمجة التطبيقات

إنشاء مستمع طلب Corser

يعد إنشاء مستمع طلب Corser الذي يقوم بإنشاء رؤوس الاستجابة المناسبة لتمكين CORS أمرًا بسيطًا مثل:

 corser.create()

وهذا يعادل تعيين رأس استجابة لـ Access-Control-Allow-Origin: * . إذا كنت تريد تقييد الأصول، أو السماح برؤوس طلبات أو استجابة أكثر تعقيدًا، فيجب عليك تمرير كائن تكوين إلى corser.create .

سيقوم Corser تلقائيًا بإنهاء طلبات الاختبار المبدئي لك. طلب الاختبار المبدئي هو طلب OPTIONS خاص يرسله المتصفح في ظل ظروف معينة للتفاوض مع الخادم بشأن الأساليب ورؤوس الطلبات ورؤوس الاستجابة المسموح بها لطلب CORS. إذا كنت بحاجة إلى استخدام التابع OPTIONS لأشياء أخرى، فما عليك سوى ضبط endPreflightRequests على false وإنهاء تلك الطلبات بنفسك:

 var corserRequestListener;

corserRequestListener = corser.create({
    endPreflightRequests: false
});

corserRequestListener(req, res, function () {
    if (req.method === "OPTIONS") {
        // End CORS preflight request.
        res.writeHead(204);
        res.end();
    } else {
        // Implement other HTTP methods.
    }
});

كائن التكوين

يمكن تمرير كائن التكوين بالخصائص التالية إلى corser.create .

origins

قائمة بيضاء حساسة لحالة الأحرف للأصول. إذا كان الطلب يأتي من أصل غير موجود في هذه القائمة، فلن يتم التعامل معه بواسطة CORS. لقبول جميع الأصول (سلوك Access-Control-Allow-Origin: * )، احذف الخاصية أو قم بتعيينها على مصفوفة فارغة ( [] ).

للسماح بالتحقق من الأصل الديناميكي، يمكن تمرير دالة (origin, callback) بدلاً من المصفوفة. origin هو رأس الأصل، callback هو وظيفة (err, matches) ، حيث matches هي علامة منطقية تشير إلى ما إذا كان رأس الأصل المحدد متطابقًا أم لا.

الافتراضي: يتم قبول جميع الأصول.

methods

قائمة بيضاء كبيرة من الأساليب. إذا كان الطلب يستخدم طريقة غير موجودة في هذه القائمة، فلن تتم معالجتها بواسطة CORS.

سيؤدي تعيين قيمة هنا إلى استبدال قائمة الطرق البسيطة الافتراضية. لكي لا تفقدها، قم بربط الطرق التي تريد إضافتها باستخدام corser.simpleMethods : corser.simpleMethods.concat(["PUT", "DELETE"]) .

الافتراضي: الطرق البسيطة ( GET ، HEAD ، POST ).

requestHeaders

قائمة بيضاء غير حساسة لحالة الأحرف لرؤوس الطلب. إذا كان الطلب يستخدم رأس طلب غير موجود في هذه القائمة، فلن تتم معالجته بواسطة CORS.

سيؤدي تعيين قيمة هنا إلى استبدال قائمة رؤوس الطلبات البسيطة الافتراضية. لكي لا تفقدها، قم بربط رؤوس الطلب التي تريد إضافتها باستخدام corser.simpleRequestHeaders : corser.simpleRequestHeaders.concat(["Authorization"]) .

الافتراضي: رؤوس الطلبات البسيطة ( Accept ، Accept-Language ، Content-Language ، Content-Type ، Last-Event-ID ).

responseHeaders

قائمة بيضاء غير حساسة لحالة الأحرف لرؤوس الاستجابة. سيتم تصفية أي رأس استجابة غير موجود في هذه القائمة بواسطة وكيل المستخدم (المتصفح).

سيؤدي تعيين قيمة هنا إلى استبدال قائمة رؤوس الاستجابة البسيطة الافتراضية. لكي لا تفقدها، قم بربط رؤوس الاستجابة التي تريد إضافتها باستخدام corser.simpleResponseHeaders : corser.simpleResponseHeaders.concat(["ETag"]) .

الافتراضي: رؤوس الاستجابة البسيطة ( Cache-Control ، Content-Language ، Content-Type ، Expires ، Last-Modified ، Pragma ).

supportsCredentials

قيمة منطقية تشير إلى ما إذا كان من الممكن نقل بيانات اعتماد ملف تعريف الارتباط كجزء من طلب CORS. حاليًا، يمكن لعدد قليل فقط من عناصر HTML5 الاستفادة من هذا الإعداد.

الافتراضي: false .

maxAge

عدد صحيح يشير إلى الحد الأقصى للوقت بالثواني الذي يتم فيه الاحتفاظ بطلب الاختبار المبدئي في ذاكرة التخزين المؤقت لنتائج الاختبار المبدئي من جانب العميل.

الافتراضي: غير محدد.

endPreflightRequests

قيمة منطقية تشير إلى ما إذا كان يجب إغلاق طلبات الاختبار المبدئي لـ CORS تلقائيًا.

الافتراضي: true .

التعليمات

طلب إرجاع Origin X is not allowed by Access-Control-Allow-Origin

تحقق مما إذا كان رأس Origin لطلبك يتطابق مع أحد الأصول المتوفرة في خاصية origins لكائن التكوين. إذا لم تقم بتعيين أي خاصية origins ، فانتقل إلى السؤال التالي.

إذا لم يساعد ذلك، فقد يستخدم طلبك طريقة غير بسيطة أو واحدًا أو أكثر من الرؤوس غير البسيطة (راجع السؤال التالي). وفقًا للمواصفات، مجموعة الطرق البسيطة هي GET و HEAD و POST ، ومجموعة رؤوس الطلب البسيطة هي Accept و Accept-Language و Content-Language و Content-Type و Last-Event-ID . إذا كان طلبك يستخدم أي طريقة أو رأس آخر، فيجب عليك إدراجها بشكل صريح في methods أو خاصية requestHeaders لكائن التكوين.

مثال

تريد السماح بالطلبات التي تستخدم رأس X-Requested-With . قم بتمرير كائن التكوين التالي إلى corser.create :

 corser.create({
    requestHeaders: corser.simpleRequestHeaders.concat(["X-Requested-With"])
});

طلب إرجاع Request header field Content-Type is not allowed by Access-Control-Allow-Headers

لن يعمل التكوين الافتراضي إلا إذا أرسل العميل طلبًا "بسيطًا"، على سبيل المثال، GET و HEAD و POST كطريقة، وبعض الرؤوس مثل Accept و Accept-Language و Content-Language و Content-Type وما إلى ذلك Content-Type له قيود مهمة: يُسمح فقط application/x-www-form-urlencoded و multipart/form-data و text/plain .

عادةً ما يكون Content-Type لواجهة برمجة التطبيقات هو application/json ، وهذا غير مسموح به افتراضيًا. يجب تحديد Content-Type بشكل صريح في كائن التكوين ضمن مفتاح requestHeaders :

مثال

 corser.create({
    requestHeaders: corser.simpleRequestHeaders.concat(["Content-Type"])
});

الحصول على إرجاع رأس الاستجابة Refused to get unsafe header "X"

يحظر متصفحك كل رؤوس الاستجابة غير البسيطة التي لم يتم السماح بها صراحةً في طلب الاختبار المبدئي. مجموعة رؤوس الاستجابة البسيطة هي Cache-Control ، Content-Language ، Content-Type ، Expires ، Last-Modified ، Pragma . إذا كنت تريد الوصول إلى أي رأس استجابة آخر، فيجب عليك إدراجها بشكل صريح في خاصية responseHeaders لكائن التكوين.

مثال

تريد السماح للعملاء بقراءة رأس ETag للاستجابة. قم بتمرير كائن التكوين التالي إلى corser.create :

 corser.create({
    responseHeaders: corser.simpleResponseHeaders.concat(["ETag"])
});