وظائف Edge

وظائف Edge هي معالجات JavaScript صغيرة تعمل على شبكة Kapsule الحدودية قبل وصول الطلب إلى مشروعك، بحيث يمكنك إجراء عمليات إعادة التوجيه وحقن الرؤوس وتوجيه A/B وتصفية البوتات دون رحلة ذهاب وإياب إلى تطبيقك. يغطي هذا الدليل كيفية كتابة واحدة، وأشكال نقاط الدخول المقبولة، ومطابقة المسارات، وكيفية تفاعل الوظائف المتعددة، والنشر، وما يحدث عندما تطرح وظيفة استثناءً.

حيث تعيش

افتح مشروعك في Orbit وانقر على علامة التبويب Edge functions. كل وظيفة تنتمي إلى مشروع وتُدرج مع شارة حالتها: LIVE أو PAUSED أو NOT DEPLOYED أو DEPLOY FAILED.

إنشاء وظيفة

1. انقر على New function.
2. املأ Name (حتى 120 حرفًا).
3. املأ Path pattern وهو نمط عنوان URL الذي يجب تشغيل هذه الوظيفة عليه.
4. اختر Trigger: Request (قبل الأصل)، Response (بعد الأصل)، أو Both.
5. اختر Environment scope: All environments أو Production only أو Preview only.
6. اكتب المعالج في Function body.
7. انقر على Save، ثم Deploy to edge.

كائن request يكون دائمًا في النطاق، والمصدر مقيد بـ 64 KB.

كتابة معالج

أعد Response للإجابة على الطلب في الحافة. لا تعيد شيئًا، أو أعد undefined، لتمرير الطلب من خلال إلى مشروعك دون تغيير.

export default {
  async fetch(request) {
    const url = new URL(request.url)

    // Redirect /old to /new
    if (url.pathname === '/old') {
      return new Response(null, {
        status: 301,
        headers: { Location: '/new' },
      })
    }

    // Returning nothing passes through to the origin
  },
}

يعمل نموذج الدالة المسماة أيضًا:

export default async function handler(request) {
  // Add a security header to every response
  const response = await fetch(request)
  const headers = new Headers(response.headers)
  headers.set('X-Frame-Options', 'DENY')
  return new Response(response.body, { status: response.status, headers })
}

أشكال نقاط الدخول المدعومة

أنماط المسار

يحدد Path pattern الطلبات التي تشغل الوظيفة. يجب أن يبدأ بـ / ويمكن أن يصل إلى 2048 حرفًا. * يطابق أي سلسلة من الأحرف و ? يطابق حرفًا واحدًا. يطابق النمط بدون بدل المسار الدقيق وكل شيء تحته.

كائن request

request هو معيار Fetch API Request. يمكنك قراءة عنوان URL والطريقة والرؤوس والنص:

export default {
  async fetch(request) {
    const url    = new URL(request.url)
    const cookie = request.headers.get('cookie') ?? ''
    const ua     = request.headers.get('user-agent') ?? ''

    if (ua.includes('BadBot')) {
      return new Response('Forbidden', { status: 403 })
    }
  },
}

أنماط شائعة

إعادة توجيه عناوين URL القديمة

export default {
  async fetch(request) {
    const url = new URL(request.url)
    const redirects = {
      '/old-about':   '/about',
      '/old-contact': '/contact',
    }
    const dest = redirects[url.pathname]
    if (dest) return Response.redirect(url.origin + dest, 301)
  },
}

بالنسبة لعدد قليل من عمليات نقل المسار إلى المسار المباشرة، استخدم محرك إعادة التوجيه المدمج بدلاً من ذلك: فهو لا يحتاج إلى أي رمز ويتم تكوينه في Settings. انظر Configuring Redirects and Rewrites.

إضافة رؤوس الأمان

export default async function handler(request) {
  const response = await fetch(request)
  const headers = new Headers(response.headers)
  headers.set('X-Frame-Options', 'DENY')
  headers.set('X-Content-Type-Options', 'nosniff')
  headers.set('Referrer-Policy', 'strict-origin-when-cross-origin')
  return new Response(response.body, {
    status: response.status,
    statusText: response.statusText,
    headers,
  })
}

بالنسبة لقواعد الرؤوس الثابتة، لا تحتاج إلى رمز أيضًا. Settings به قسم رؤوس الاستجابة مع إضافة سريعة مسبقة الصنع لـ HSTS و CSP و no-embed و no-sniff وسياسة المرجع و CORS.

توجيه A/B

export default {
  async fetch(request) {
    const url     = new URL(request.url)
    const variant = Math.random() < 0.5 ? 'a' : 'b'
    url.searchParams.set('variant', variant)
    return fetch(url.toString(), request)
  },
}

نطاق البيئة

كيفية تفاعل الوظائف المتعددة

يتم تقييم جميع وظائف مشروعك المُفعّلة بالترتيب الذي تم إنشاؤها فيه. لكل طلب، تمر الحافة عبر القائمة وتشغل أول وظيفة يطابق نمط مسارها مسار الطلب ونطاقها يغطي البيئة.

• إذا أعادت تلك الوظيفة Response، يتم إرسالها ويتوقف التقييم.
• إذا لم تعد شيئًا، يستمر التقييم إلى الوظيفة المطابقة التالية.
• إذا لم تعد أي منها Response، يذهب الطلب إلى مشروعك بشكل طبيعي.

هذا يعني أن دالة /* واسعة تم إنشاؤها في وقت مبكر يمكن أن تظلل واحدة أضيق تم إنشاؤها لاحقًا، إذا أعادت الواحدة الواسعة Response. أنشئ الدوال المحددة أولاً، أو اجعل الدالة الواسعة تعيد لا شيء للمسارات التي لا يجب أن تتعامل معها.

النشر

انقر على Deploy to edge. النشر يعيد إنتاج جهاز توجيه مدمج واحد لكامل شبكة الحافة من الحالة الحالية لقاعدة البيانات، لذا فإن تمكين أو تعطيل أو تحرير أو حذف أي وظيفة يعيد نشر كل شيء. التغييرات عادة ما تسري في غضون بضع ثوان.

يحتفظ كل صف وظيفة بـ Deploy log يوضح خطوات آخر نشر، وشارة DEPLOY FAILED مع الخطأ إذا لم تنجح.

Pause يأخذ وظيفة خارج الموجه دون حذفها، وهي أسرع طريقة للتراجع عن وظيفة سيئة التصرف. Resume تعيدها.

عندما تطرح وظيفة استثناءً

يتم اكتشاف استثناء داخل وظيفة في الحافة. يتم تسجيل الخطأ ويسقط الطلب إلى مشروعك كما لو أن الوظيفة لم تعد شيئًا.

الحدود

• حتى 20 وظيفة لكل مشروع. يتم رفض الـ 21.
• حتى 64 KB من المصدر لكل وظيفة.
• حتى 120 حرفًا للاسم، و 2048 حرفًا لنمط المسار.

القراءة ذات الصلة

• Configuring Redirects and Rewrites، خيار بدون رمز لقواعد المسار
• Deploying Your Project
• Branch Preview Deployments in Orbit لاختبار وظيفة قبل وصولها للإنتاج