مرجع المعالجات

التسلسل الهرمي لأنواع المعالجات لمسارات خادم ⁦Elide⁩.

كل ⁦Route⁩ لديه ⁦Handler⁩ واحد بالضبط، وكل ⁦ServerBlock⁩ لديه معالج افتراضي للطلبات غير المطابقة. المعالجات هي أصناف مفتوحة تُشكل اتحاداً مُمَيزاً عبر ⁦typealias Handler⁩. اختر الصنف الفرعي المحدد الذي يطابق السلوك المطلوب:

StaticFiles⁩ — تقديم ملفات من مجلد محلي ⁦ReverseProxy⁩ — تمرير الطلبات إلى خادم علوي واحد أو أكثر ⁦Redirect⁩ — إصدار استجابة إعادة توجيه ⁦HTTP⁩ ⁦Cgi⁩ — تنفيذ برنامج لكل طلب عبر ⁦CGI⁩ (⁦RFC 3875⁩) ⁦Respond⁩ — إصدار استجابة ثابتة مُضمنة (مفيد لفحوصات الصحة وصفحات الصيانة ومسارات الأخطاء الشاملة)

يمكن أيضاً تعيين المعالجات مباشرةً على ⁦ServerBlock.handler⁩ باستخدام عدد صحيح لكود الحالة (مثل ⁦404⁩) كاختصار لـ⁦Respond⁩ بذلك الكود.

> هذه الصفحة مُولَّدة تلقائياً من مخطط ⁦PKL⁩. راجع الدليل لأمثلة الاستخدام.

الأنواع

HttpStatus

كود حالة ⁦HTTP⁩ (⁦100⁩–⁦599⁩ شامل).

pkl
typealias HttpStatus = UInt(isBetween(100, 599))

CompressionAlgo

خوارزمية ضغط لأجسام الاستجابة. مرتبة بالأولوية النموذجية (أفضل نسبة ضغط أولاً):

  • "zstd"⁩ — ⁦Zstandard⁩؛ أفضل نسبة ضغط وسرعة لمعظم أحمال العمل
  • "br"⁩ — ⁦Brotli⁩؛ ممتاز للنصوص/⁦HTML⁩ لكنه أبطأ في الضغط
  • "gzip"⁩ — دعم عالمي من العملاء؛ أقل نسبة ضغط بين الثلاثة
pkl
typealias CompressionAlgo = "gzip" | "br" | "zstd"

LoadBalancingPolicy

سياسة موازنة الحمل لتوزيع الطلبات عبر مجموعة الخوادم العلوية لـ⁦ReverseProxy⁩.

  • "round_robin"⁩ — التدوير بين الخوادم العلوية بالتتابع (يحترم ⁦Upstream.weight⁩ للتوزيع المُرجّح)
  • "least_connections"⁩ — الإرسال إلى الخادم العلوي ذي أقل عدد اتصالات نشطة
  • "random"⁩ — اختيار عشوائي منتظم
  • "ip_hash"⁩ — تجزئة عنوان ⁦IP⁩ للعميل للجلسات الثابتة
  • "first"⁩ — الإرسال دائماً إلى أول خادم علوي سليم
  • "cookie"⁩ — جلسات ثابتة عبر ملف تعريف ارتباط يُعينه الخادم
  • "consistent_hash"⁩ — تجزئة متسقة على ⁦URI⁩ الطلب؛ تُقلل إعادة التوزيع عند إضافة أو إزالة خوادم علوية
pkl
typealias LoadBalancingPolicy = "round_robin" | "least_connections" | "random" | "ip_hash" | "first" | "cookie" | "consistent_hash"

RedirectStatus

أكواد حالة ⁦HTTP⁩ الصالحة لاستجابات إعادة التوجيه.

  • 301⁩ ⁦Moved Permanently⁩ — قابل للتخزين المؤقت، قد تتغير الطريقة إلى ⁦GET⁩
  • 302⁩ ⁦Found⁩ — لا يُخزن مؤقتاً افتراضياً، قد تتغير الطريقة إلى ⁦GET⁩
  • 307⁩ ⁦Temporary Redirect⁩ — يحتفظ بطريقة الطلب وجسمه
  • 308⁩ ⁦Permanent Redirect⁩ — قابل للتخزين المؤقت، يحتفظ بالطريقة والجسم
pkl
typealias RedirectStatus = UInt(this == 301 || this == 302 || this == 307 || this == 308)

CacheControlPreset

قيمة ترويسة ⁦Cache-Control⁩ لاستجابات الأصول الثابتة. تُقدَّم إعدادات مسبقة شائعة كخيارات حرفية، لكن أي سلسلة ⁦Cache-Control⁩ صالحة مقبولة:

  • "no-store"⁩ — لا تخزين مؤقت أبداً (بيانات حساسة)
  • "no-cache"⁩ — تخزين مؤقت لكن مع إعادة التحقق دائماً
  • "private"⁩ — تخزين مؤقت في المتصفح فقط، ليس في ⁦CDN⁩/الوكيل
  • "public, max-age=3600"⁩ — تخزين مؤقت لمدة ساعة
  • "public, max-age=86400"⁩ — تخزين مؤقت لمدة يوم
  • "public, max-age=31536000, immutable"⁩ — تخزين مؤقت لمدة سنة، بدون إعادة تحقق أبداً (أصول ببصمة)

مثال مخصص:

pkl
cacheControl = "public, max-age=600, stale-while-revalidate=60"
pkl
typealias CacheControlPreset = "no-store" | "no-cache" | "private" | "public, max-age=3600" | "public, max-age=86400" | "public, max-age=31536000, immutable" | String

Handler

اتحاد جميع أنواع المعالجات الصالحة. استخدم أحد: ⁦StaticFiles⁩، ⁦ReverseProxy⁩، ⁦Redirect⁩، ⁦Cgi⁩، أو ⁦Respond⁩.

pkl
typealias Handler = StaticFiles | ReverseProxy | Redirect | Cgi | Respond

---

HeaderOps

عمليات تعديل الترويسات المُطبقة على طلب أو استجابة وكيل.

تُطبق التعديلات بالترتيب: ⁦set⁩، ثم ⁦add⁩، ثم ⁦remove⁩. تُستخدم بواسطة ⁦ReverseProxy.requestHeaders⁩ و⁦ReverseProxy.responseHeaders⁩.

pkl
requestHeaders {
  set { ["X-Forwarded-Proto"] = "https" }
  remove { "Cookie" }
}
الحقلالنوعالافتراضيالوصف
setMapping(فارغ)ترويسات تُعيَّن بدون شرط. تكتب فوق أي قيمة موجودة بـ
addMapping(فارغ)ترويسات تُلحق. تضيف قيمة ترويسة جديدة بدون إزالة أي
removeListing(فارغ)أسماء الترويسات المراد إزالتها بالكامل من الطلب أو الاستجابة.

set

ترويسات تُعيَّن بدون شرط. تكتب فوق أي قيمة موجودة بنفس الاسم.

add

ترويسات تُلحق. تضيف قيمة ترويسة جديدة بدون إزالة أي قيم موجودة بنفس الاسم.

---

Upstream

خادم علوي مفرد في مجموعة ⁦ReverseProxy⁩.

في الحالات البسيطة، يمكن استخدام نص عادي (مثل ⁦"backend:8080"⁩) بدلاً من كائن ⁦Upstream⁩ كامل. استخدم صيغة الكائن عندما تحتاج لتعيين الوزن أو حدود الاتصالات أو حالة النسخ الاحتياطي.
الحقلالنوعالافتراضيالوصف
addressString(!isEmpty)(مطلوب)عنوان الخادم العلوي. يقبل ⁦host:port⁩ أو عنوان ⁦URL⁩ كامل:
weightUInt(isPositive)1الوزن النسبي لموازنة الحمل المُرجّحة. القيم الأعلى تتلقى
maxConnectionsUInt0الحد الأقصى للاتصالات المتزامنة لهذا الخادم العلوي. ⁦0⁩ (الافتراضي)
backupBooleanfalseتعليم هذا الخادم العلوي كنسخة احتياطية. النسخ الاحتياطية تتلقى الحركة فقط

address

عنوان الخادم العلوي. يقبل ⁦host:port⁩ أو عنوان ⁦URL⁩ كامل:

pkl
`"backend-1:8080"`
`"http:<<>>
`"https://internal.example.com"`

عند تضمين المخطط، يُستخدم ⁦TLS⁩ للأهداف من نوع ⁦https://⁩.

weight

الوزن النسبي لموازنة الحمل المُرجّحة. القيم الأعلى تتلقى حصة أكبر نسبياً من الحركة. ذو معنى فقط مع السياسات التي تدعم الأوزان (مثل ⁦"round_robin"⁩).

maxConnections

الحد الأقصى للاتصالات المتزامنة لهذا الخادم العلوي. ⁦0⁩ (الافتراضي) يعني بدون حدود. عيّن هذا لحماية الخوادم العلوية من التحميل الزائد.

backup

تعليم هذا الخادم العلوي كنسخة احتياطية. النسخ الاحتياطية تتلقى الحركة فقط عندما تكون جميع الخوادم العلوية الأساسية (غير الاحتياطية) غير سليمة.

---

HealthCheck

إعدادات فحص الصحة النشط والسلبي لمجموعات الخوادم العلوية في ⁦ReverseProxy⁩.

ترسل الفحوصات النشطة طلبات استقصاء دورية لكل خادم علوي. تراقب الفحوصات السلبية الحركة الحقيقية وتعلم الخادم العلوي كغير سليم عند فشل الطلبات الموكلة. يمكن تشغيل كليهما في وقت واحد.

pkl
healthCheck { path = "/healthz"; interval = 5.s }
الحقلالنوعالافتراضيالوصف
pathString"/health"مسار ⁦HTTP⁩ الذي يستقصيه فاحص الصحة النشط. يُصدر الاستقصاء طلب
intervalDuration10.sالفاصل الزمني بين استقصاءات فحص الصحة النشط لكل خادم علوي.
timeoutDuration5.sالحد الأقصى لانتظار استجابة الاستقصاء قبل اعتبارها
unhealthyThresholdUInt(isPositive)3عدد فشل الاستقصاء المتتالية المطلوبة لتعليم خادم علوي كغير سليم.
healthyThresholdUInt(isPositive)2عدد نجاحات الاستقصاء المتتالية المطلوبة لاستعادة خادم علوي إلى
passiveBooleantrueتفعيل فحوصات الصحة السلبية. عند ⁦true⁩، يُعلَّم خادم علوي
circuitBreakerThresholdUInt?nullعدد حالات الفشل السلبية ضمن نافذة المراقبة التي تُفعّل

path

مسار ⁦HTTP⁩ الذي يستقصيه فاحص الصحة النشط. يُصدر الاستقصاء طلب ⁦GET⁩ لهذا المسار؛ استجابة ⁦2xx⁩ تُعتبر سليمة.

timeout

الحد الأقصى لانتظار استجابة الاستقصاء قبل اعتبارها فشلاً.

unhealthyThreshold

عدد فشل الاستقصاء المتتالية المطلوبة لتعليم خادم علوي كغير سليم. قيمة أعلى تجعل فاحص الصحة أكثر تسامحاً مع الأخطاء المؤقتة لكنه أبطأ في اكتشاف الأعطال الحقيقية.

healthyThreshold

عدد نجاحات الاستقصاء المتتالية المطلوبة لاستعادة خادم علوي إلى الحالة السليمة بعد تعليمه كغير سليم.

passive

تفعيل فحوصات الصحة السلبية. عند ⁦true⁩، يُعلَّم خادم علوي كغير سليم بعد فشل طلب موكل بدون تلقي أي استجابة (رفض الاتصال، انتهاء المهلة، إلخ.). الفحوصات السلبية تتفاعل أسرع من الاستقصاءات النشطة لكنها قد تُحفَّز بمشاكل شبكة مؤقتة.

circuitBreakerThreshold

عدد حالات الفشل السلبية ضمن نافذة المراقبة التي تُفعّل قاطع الدائرة، مما يوقف كل الحركة إلى الخادم العلوي حتى ينجح الاستقصاء النشط التالي. ⁦null⁩ (الافتراضي) يُعطل قاطع الدائرة.

---

StaticFiles

صنف مفتوح — يمكن توسيعه.

يقدم ملفات من مجلد محلي.

تُقدَّم الأصول الثابتة مع ترويسات ⁦ETag⁩ و⁦Last-Modified⁩ لدعم الطلبات المشروطة. عند تفعيل ⁦preCompress⁩ (الافتراضي)، يضغط ⁦Elide⁩ جميع الملفات مسبقاً عند بدء التشغيل ويقدم النسخة المضغوطة مباشرةً، مما يُلغي تكلفة الضغط لكل طلب.

pkl
handler = new StaticFiles { root = "./dist"; spaFallback = true }
الحقلالنوعالافتراضيالوصف
typeString"static" (ثابت)(ثابت)
rootString(!isEmpty)(مطلوب)المجلد الجذر الذي تُحل منه الملفات. تُحل المسارات
indexString"index.html"ملف الفهرس الرئيسي المُرجع عند طلب مسار مجلد مجرد.
spaFallbackBooleanfalseتقديم ⁦index⁩ لأي مسار لا يُحل إلى ملف موجود.
preCompressBooleantrueضغط جميع الملفات مسبقاً عند بدء التشغيل وتخزين النسخ المضغوطة
compressionListingnew { "zstd"; "br"; "gzip" }خوارزميات الضغط المُقدمة. عندما يدعم ترويسة ⁦Accept-Encoding⁩ للعميل
etagBooleantrueإصدار ترويسات ⁦ETag⁩ لدعم الطلبات المشروطة (⁦If-None-Match⁩).
rangeRequestsBooleantrueقبول ترويسات طلب ⁦Range⁩ لاستجابات المحتوى الجزئي
cacheControlCacheControlPreset?nullقيمة ترويسة ⁦Cache-Control⁩ المُرسلة مع كل استجابة ملف. ⁦null
tryFilesListing(فارغ)قائمة مرتبة من مسارات الملفات لتجربتها لكل طلب (مشابه لـ⁦nginx⁩
indexFilesListingnew { "index.html"; "index.htm" }ملفات الفهرس المُبحث عنها عند طلب مسار مجلد، تُجرب بـ
directoryListingBooleanfalseتفعيل قوائم المجلدات ⁦HTML⁩ المُولَّدة تلقائياً للمسارات التي تُحل
directoryTemplateString?nullقالب ⁦HTML⁩ مخصص لصفحات قائمة المجلدات. ⁦null⁩ يستخدم القالب
autoindexSortString"name_asc"ترتيب الفرز لقوائم المجلدات. القيم المقبولة:

root

المجلد الجذر الذي تُحل منه الملفات. تُحل المسارات نسبةً إلى مجلد عمل عملية ⁦elide serve⁩.

pkl
root = "./public"
root = "/var/www/html"

index

ملف الفهرس الرئيسي المُرجع عند طلب مسار مجلد مجرد. تُستخدم هذه القيمة أيضاً كهدف احتياطي لتطبيق الصفحة الواحدة عند ⁦spaFallback = true⁩.

spaFallback

تقديم ⁦index⁩ لأي مسار لا يُحل إلى ملف موجود. مطلوب لتطبيقات الصفحة الواحدة التي تتعامل مع التوجيه من جانب العميل (مثل ⁦React Router⁩، ⁦Vue Router⁩). تحمل الاستجابة عنوان ⁦URL⁩ الطلب الأصلي ليتمكن الموجه من جانب العميل من مطابقته.

preCompress

ضغط جميع الملفات مسبقاً عند بدء التشغيل وتخزين النسخ المضغوطة في الذاكرة. مُوصى به بشدة للإنتاج — يُلغي تكلفة الضغط لكل طلب على حساب زيادة وقت بدء التشغيل واستهلاك الذاكرة.

compression

خوارزميات الضغط المُقدمة. عندما تدعم ترويسة ⁦Accept-Encoding⁩ للعميل خوارزميات متعددة، يفوز أول تطابق في هذه القائمة. رتّب من أفضل نسبة ضغط إلى أوسع دعم.

etag

إصدار ترويسات ⁦ETag⁩ لدعم الطلبات المشروطة (⁦If-None-Match⁩). تُحسب علامات ⁦ETag⁩ من تجزئات محتوى الملفات، مما يُتيح استجابات ⁦304 Not Modified⁩ التي توفر عرض النطاق.

rangeRequests

قبول ترويسات طلب ⁦Range⁩ لاستجابات المحتوى الجزئي (⁦206 Partial Content⁩). مطلوب للتنزيلات القابلة للاستئناف والتنقل في الوسائط.

cacheControl

قيمة ترويسة ⁦Cache-Control⁩ المُرسلة مع كل استجابة ملف. ⁦null⁩ (الافتراضي) يحذف الترويسة، تاركاً سلوك التخزين المؤقت للعميل أو ⁦CDN⁩ المتدفق. راجع ⁦CacheControlPreset⁩ للقيم الشائعة.

tryFiles

قائمة مرتبة من مسارات الملفات لتجربتها لكل طلب (مشابه لـ⁦try_files⁩ في ⁦nginx⁩). أول مسار يُحل إلى ملف موجود يُقدَّم. قائمة فارغة (الافتراضي) تُعطل هذا السلوك.

indexFiles

ملفات الفهرس المُبحث عنها عند طلب مسار مجلد، تُجرب بالترتيب المُدرج. أول ملف يُعثر عليه يُقدَّم.

directoryListing

تفعيل قوائم المجلدات ⁦HTML⁩ المُولَّدة تلقائياً للمسارات التي تُحل إلى مجلد بدون ملف فهرس مطابق. عند ⁦false⁩ (الافتراضي)، تُرجع هذه الطلبات ⁦404⁩.

directoryTemplate

قالب ⁦HTML⁩ مخصص لصفحات قائمة المجلدات. ⁦null⁩ يستخدم القالب المُدمج. يُتجاهل عند ⁦directoryListing = false⁩. يتلقى القالب بيانات القائمة كمتغيرات قالب.

autoindexSort

ترتيب الفرز لقوائم المجلدات. القيم المقبولة: ⁦"name_asc"⁩، ⁦"name_desc"⁩، ⁦"size_asc"⁩، ⁦"size_desc"⁩، ⁦"mtime_asc"⁩، ⁦"mtime_desc"⁩.

---

ReverseProxy

صنف مفتوح — يمكن توسيعه.

يُمرر الطلبات إلى خادم علوي واحد أو أكثر مع موازنة الحمل وفحص الصحة وتخزين الاستجابة المؤقت الاختياري.

pkl
handler = new ReverseProxy {
  upstreams { "backend-a:8080"; "backend-b:8080" }
  loadBalancing = "least_connections"
  healthCheck {}
}
الحقلالنوعالافتراضيالوصف
typeString"proxy" (ثابت)(ثابت)
upstreamsListingUpstream>(!isEmpty)(مطلوب)مجموعة الخوادم العلوية. خادم علوي واحد على الأقل مطلوب. يقبل نصوصاً
stripPrefixBooleanfalseإزالة بادئة المسار المطابق قبل التمرير إلى الخادم العلوي.
loadBalancingLoadBalancingPolicy"round_robin"سياسة موازنة الحمل لتوزيع الطلبات عبر الخوادم العلوية.
healthCheckHealthCheck?nullإعدادات فحص الصحة النشط والسلبي. ⁦null⁩ (الافتراضي)
timeoutDuration30.sالحد الأقصى لانتظار الخادم العلوي لبدء إرسال ترويسات
responseTimeoutDuration5.minالحد الأقصى لإرسال الخادم العلوي لجسم الاستجابة الكامل
bufferResponseBooleanfalseتخزين استجابة الخادم العلوي الكاملة في الذاكرة قبل إرسالها إلى
requestHeadersHeaderOps(فارغ)تعديلات الترويسات المُطبقة على الطلب الصادر المُرسل إلى
responseHeadersHeaderOps(فارغ)تعديلات الترويسات المُطبقة على استجابة الخادم العلوي قبل
websocketBooleantrueتفعيل وكيل ⁦WebSocket⁩ عبر معالجة ⁦HTTP⁩ ⁦Upgrade⁩. عند ⁦true
preserveHostBooleantrueالحفاظ على ترويسة ⁦Host⁩ الأصلية للعميل عند التمرير إلى
cacheProxyCache?nullذاكرة تخزين مؤقت للاستجابات لهذا الوكيل العكسي. عند تعيينها

upstreams

مجموعة الخوادم العلوية. خادم علوي واحد على الأقل مطلوب. يقبل نصوصاً عادية (⁦"host:port"⁩) أو كائنات ⁦Upstream⁩ كاملة للتحكم بالوزن وحدود الاتصالات.

pkl
upstreams { "backend:8080" }
upstreams { new Upstream { address = "backend:8080"; weight = 2 } }

stripPrefix

إزالة بادئة المسار المطابق قبل التمرير إلى الخادم العلوي. على سبيل المثال، مسار يطابق ⁦"/api/**"⁩ مع ⁦stripPrefix = true⁩ يُمرر ⁦/api/users⁩ كـ⁦/users⁩.

loadBalancing

سياسة موازنة الحمل لتوزيع الطلبات عبر الخوادم العلوية. راجع ⁦LoadBalancingPolicy⁩ لجميع الخيارات.

healthCheck

إعدادات فحص الصحة النشط والسلبي. ⁦null⁩ (الافتراضي) يُعطل فحوصات الصحة بالكامل — تُفترض جميع الخوادم العلوية سليمة. راجع ⁦HealthCheck⁩ لمسار الاستقصاء والفواصل الزمنية وخيارات قاطع الدائرة.

timeout

الحد الأقصى لانتظار الخادم العلوي لبدء إرسال ترويسات الاستجابة. إذا انتهت هذه المهلة، يفشل الطلب بالاستجابة ⁦504 Gateway Timeout⁩.

responseTimeout

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

bufferResponse

تخزين استجابة الخادم العلوي الكاملة في الذاكرة قبل إرسالها إلى العميل. يُتيح فحص وإعادة كتابة جسم الاستجابة عبر الوسيط، لكنه يزيد استخدام الذاكرة بما يتناسب مع حجم الاستجابة.

requestHeaders

تعديلات الترويسات المُطبقة على الطلب الصادر المُرسل إلى الخادم العلوي. راجع ⁦HeaderOps⁩ لعمليات الإعداد/الإلحاق/الإزالة.

responseHeaders

تعديلات الترويسات المُطبقة على استجابة الخادم العلوي قبل تمريرها إلى العميل. راجع ⁦HeaderOps⁩ لعمليات الإعداد/الإلحاق/الإزالة.

websocket

تفعيل وكيل ⁦WebSocket⁩ عبر معالجة ⁦HTTP⁩ ⁦Upgrade⁩. عند ⁦true⁩ (الافتراضي)، تُمرر طلبات ⁦Upgrade: websocket⁩ إلى الخادم العلوي ويُبقى الاتصال مفتوحاً ثنائي الاتجاه.

preserveHost

الحفاظ على ترويسة ⁦Host⁩ الأصلية للعميل عند التمرير إلى الخادم العلوي. عند ⁦false⁩، تُعاد كتابة ترويسة ⁦Host⁩ إلى عنوان الخادم العلوي. معظم الخوادم العلوية تتوقع المضيف الأصلي؛ عيّنه إلى ⁦false⁩ فقط عندما يُنفذ الخادم العلوي توجيه المضيف الافتراضي الخاص به.

cache

ذاكرة تخزين مؤقت للاستجابات لهذا الوكيل العكسي. عند تعيينها، تُخزن استجابات الخادم العلوي القابلة للتخزين المؤقت وتُقدم من ذاكرة تخزين مؤقت ذات مستويين (ذاكرة + قرص). ⁦null⁩ (الافتراضي) يُعطل التخزين المؤقت.

راجع ⁦ProxyCache⁩ لخيارات المنطقة وحد الحجم والتجميع.

pkl
cache = new ProxyCache {}
cache = new ProxyCache { lock = true }

---

Redirect

صنف مفتوح — يمكن توسيعه.

يُصدر إعادة توجيه ⁦HTTP⁩ إلى عنوان ⁦URL⁩ مستهدف.

pkl
handler = new Redirect {
  target = "https://new.example.com{path}"
  status = 301
}
الحقلالنوعالافتراضيالوصف
typeString"redirect" (ثابت)(ثابت)
targetUri(مطلوب)عنوان ⁦URL⁩ الوجهة لإعادة التوجيه. يدعم متغيرات القالب التي
statusRedirectStatus308كود حالة ⁦HTTP⁩ لاستجابة إعادة التوجيه. الافتراضي (⁦308⁩)

target

عنوان ⁦URL⁩ الوجهة لإعادة التوجيه. يدعم متغيرات القالب التي تُوسَّع من الطلب الأصلي:

{path}⁩ — مسار الطلب المطابق (مثل ⁦/old/page⁩) ⁦{query}⁩ — سلسلة الاستعلام الخام (مثل ⁦?foo=bar⁩)

مثال: ⁦"https://new.example.com{path}{query}"

status

كود حالة ⁦HTTP⁩ لاستجابة إعادة التوجيه. الافتراضي (⁦308⁩) يُصدر إعادة توجيه دائمة تحتفظ بطريقة الطلب. راجع ⁦RedirectStatus⁩ لجميع الخيارات.

---

Cgi

صنف مفتوح — يمكن توسيعه.

ينفذ برنامجاً لكل طلب باستخدام بروتوكول ⁦CGI⁩ (⁦Common Gateway Interface⁩) (⁦RFC 3875⁩).

يتلقى البرنامج بيانات الطلب الوصفية عبر متغيرات البيئة (⁦REQUEST_METHOD⁩، ⁦PATH_INFO⁩، ⁦QUERY_STRING⁩، إلخ.)، ويقرأ جسم الطلب من الإدخال القياسي، ويكتب ترويسات الاستجابة + الجسم إلى الإخراج القياسي.

يمكن لهذا المعالج تشغيل أي ملف قابل للتنفيذ: نصوص شل أو ⁦Python⁩ أو ⁦Ruby⁩ أو ⁦PHP⁩ أو ملفات ثنائية مُجمعة أو نصوص ⁦JS/TS⁩ لـ⁦Elide⁩ (عبر حقل ⁦interpreter⁩).

pkl
handler = new Cgi {
  script = "./cgi-bin/report.py"
  interpreter = "/usr/bin/python3"
  timeout = 60.s
}
الحقلالنوعالافتراضيالوصف
typeString"cgi" (ثابت)(ثابت)
scriptString(!isEmpty)(مطلوب)مسار نص ⁦CGI⁩ أو الملف القابل للتنفيذ. يُحل نسبةً إلى
interpreterString?nullالمُفسر المُستخدم لتنفيذ النص (مثل ⁦"/usr/bin/python3"⁩،
envMapping(فارغ)متغيرات بيئة إضافية تُمرر لعملية ⁦CGI⁩، بالإضافة
timeoutDuration30.sالحد الأقصى لوقت تنفيذ عملية ⁦CGI⁩. إذا كانت العملية لا تزال
workingDirString?nullمجلد العمل لعملية ⁦CGI⁩. عند ⁦null⁩ (الافتراضي)، يُستخدم

script

مسار نص ⁦CGI⁩ أو الملف القابل للتنفيذ. يُحل نسبةً إلى ⁦workingDir⁩ (أو مجلد عمل الخادم إذا كان ⁦workingDir⁩ يساوي ⁦null⁩).

interpreter

المُفسر المُستخدم لتنفيذ النص (مثل ⁦"/usr/bin/python3"⁩، ⁦"/usr/bin/env ruby"⁩). عند ⁦null⁩، يُنفذ النص مباشرةً ويجب أن يكون قابلاً للتنفيذ أو يحتوي سطر ⁦#!/...⁩ (⁦shebang⁩).

env

متغيرات بيئة إضافية تُمرر لعملية ⁦CGI⁩، بالإضافة إلى متغيرات ⁦CGI⁩ القياسية. مفيدة لتمرير الإعدادات أو الأسرار بدون وسائط سطر الأوامر.

timeout

الحد الأقصى لوقت تنفيذ عملية ⁦CGI⁩. إذا كانت العملية لا تزال تعمل بعد هذه المدة، تُقتل بإشارة ⁦SIGKILL⁩ ويتلقى العميل استجابة ⁦504 Gateway Timeout⁩.

workingDir

مجلد العمل لعملية ⁦CGI⁩. عند ⁦null⁩ (الافتراضي)، يُستخدم مجلد عمل الخادم نفسه.

---

Respond

صنف مفتوح — يمكن توسيعه.

يُصدر استجابة ⁦HTTP⁩ ثابتة مُضمنة بدون استدعاء أي خادم علوي أو القراءة من القرص. مفيد لنقاط نهاية فحص الصحة وصفحات الصيانة وواجهات ⁦API⁩ المُؤقتة ومسارات الأخطاء الشاملة.

pkl
handler = new Respond {
  status = 503
  contentType = "text/html; charset=utf-8"
  body = "<h1>Down for maintenance</h1>"
  headers { ["Retry-After"] = "3600" }
}
الحقلالنوعالافتراضيالوصف
typeString"respond" (ثابت)(ثابت)
statusHttpStatus200كود حالة ⁦HTTP⁩ للاستجابة.
bodyString?nullنص جسم الاستجابة. ⁦null⁩ يُرسل جسماً فارغاً (⁦content-length 0⁩).
contentTypeString"text/plain; charset=utf-8"قيمة ترويسة ⁦Content-Type⁩ للاستجابة.
headersMapping(فارغ)ترويسات استجابة إضافية. تُرسل بجانب الترويسات القياسية

headers

ترويسات استجابة إضافية. تُرسل بجانب الترويسات القياسية (⁦Content-Type⁩، ⁦Content-Length⁩).

---

ProxyCache

صنف مفتوح — يمكن توسيعه.

ذاكرة تخزين مؤقت للاستجابات لمعالج ⁦ReverseProxy⁩.

تُخزن استجابات الخادم العلوي القابلة للتخزين المؤقت في ذاكرة تخزين مؤقت ذات مستويين (طبقة ذاكرة ساخنة + طبقة قرص باردة). تُقدم الطلبات اللاحقة لنفس المورد من الذاكرة المؤقتة بدون الاتصال بالخادم العلوي.

جميع الحقول لها قيم افتراضية معقولة — ⁦cache = new ProxyCache {}⁩ يُفعل التخزين المؤقت الذي يعمل لمعظم أحمال العمل. تُشتق مفاتيح الذاكرة المؤقتة من طريقة الطلب و⁦URI⁩ والترويسات المُحددة بـ⁦Vary⁩.
الحقلالنوعالافتراضيالوصف
zoneString"default"اسم منطقة الذاكرة المؤقتة. يُستخدم كمجلد فرعي للتجزئة على القرص تحت ⁦path⁩.
pathString"/var/cache/elide/proxy"المجلد الأساسي لملفات الذاكرة المؤقتة على القرص. يجب أن يكون قابلاً للكتابة بواسطة
maxMemoryDataSize64.mbالحد الأقصى لحجم ذاكرة التخزين المؤقت في الطبقة الساخنة. الإدخالات المُتكررة
maxDiskDataSize512.mbالحد الأقصى لحجم ذاكرة التخزين المؤقت على القرص في الطبقة الباردة. الإدخالات المُخرجة
maxBodySizeDataSize10.mbالحد الأقصى لحجم جسم استجابة فردي للتخزين المؤقت. الاستجابات الأكبر
maxTtlDuration0.sالحد الأقصى لعمر الإدخالات المُخزنة مؤقتاً، بغض النظر عن
forceCacheBooleanfalseتخزين الاستجابات مؤقتاً حتى عند عدم وجود ترويسات ⁦Cache-Control⁩ أو
lockBooleanfalseتفعيل تجميع الطلبات (قفل الذاكرة المؤقتة) لمنع اندفاع القطيع
lockTimeoutDuration5.sالحد الأقصى لانتظار طلب مُجمع حتى اكتمال الطلب الأول.

zone

اسم منطقة الذاكرة المؤقتة. يُستخدم كمجلد فرعي للتجزئة على القرص تحت ⁦path⁩. استخدم أسماء مناطق مختلفة عندما تتشارك معالجات ⁦ReverseProxy⁩ متعددة نفس مجلد ⁦path⁩.

path

المجلد الأساسي لملفات الذاكرة المؤقتة على القرص. يجب أن يكون قابلاً للكتابة بواسطة عملية الخادم.

maxMemory

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

maxDisk

الحد الأقصى لحجم ذاكرة التخزين المؤقت على القرص في الطبقة الباردة. تُكتب الإدخالات المُخرجة من الذاكرة إلى القرص. عند الوصول إلى هذا الحد، تُخرج الإدخالات الأقل استخداماً مؤخراً.

maxBodySize

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

maxTtl

الحد الأقصى لعمر الإدخالات المُخزنة مؤقتاً، بغض النظر عن توجيهات ⁦Cache-Control⁩ من الخادم العلوي. ⁦0.s⁩ (الافتراضي) يعني أن الذاكرة المؤقتة تحترم عمر الخادم العلوي بدون فرض حد أعلى.

forceCache

تخزين الاستجابات مؤقتاً حتى عند عدم وجود ترويسات ⁦Cache-Control⁩ أو ⁦Expires⁩ صريحة. تُخزن هذه الاستجابات بعمر افتراضي قدره ⁦60⁩ ثانية. مفيد للخوادم العلوية التي تحذف ترويسات التخزين المؤقت لكنها تقدم محتوى قابلاً للتخزين.

lock

تفعيل تجميع الطلبات (قفل الذاكرة المؤقتة) لمنع اندفاعات القطيع. عند تفعيله، تُجمع الطلبات المتزامنة لنفس المورد غير المُخزن — يُمرر الطلب الأول فقط إلى الخادم العلوي وينتظر المتصلون الباقون نتيجته.

lockTimeout

الحد الأقصى لانتظار طلب مُجمع حتى اكتمال الطلب الأول. إذا لم يُحرر القفل خلال هذه المدة، يُمرر الطلب المنتظر إلى الخادم العلوي بشكل مستقل. يعمل فقط عند ⁦lock = true⁩.

---