مرجع إعدادات الخادم

مخطط الإعدادات الرئيسي لخادم ⁦Elide⁩ لبروتوكول ⁦HTTP⁩.

هذا الوحدة هي جذر إعدادات ⁦elide serve⁩. تغطي المستمعين والتوجيه والوكيل الأمامي و⁦TLS⁩ وواجهة الإدارة البرمجية والوسيط العام والمراقبة. كل حقل له قيمة افتراضية معقولة، لذا يحتاج الإعداد الأدنى فقط إلى تحديد ما يختلف عن الإعدادات الافتراضية.

مفاتيح كتلة الخادم

يستخدم تعيين ⁦servers⁩ المفتاح كهوية للخادم. يحدد المفتاح إعدادات المستمع والنطاق الافتراضية:

• مفتاح النطاق (يحتوي على ⁦.⁩، بدون ⁦:⁩): يستنتج ⁦listen :443⁩ و⁦domains { key }⁩ مع ⁦TLS⁩ تلقائي. أمثلة: ⁦"example.com"⁩، ⁦"api.example.com"⁩.

• مفتاح العنوان (يبدأ بـ ⁦:⁩ أو يطابق ⁦host:port⁩): يستنتج ⁦listen { key }⁩. أمثلة: ⁦":8080"⁩، ⁦"0.0.0.0:3128"⁩.

• مفتاح التسمية (أي شيء آخر): لا يوجد استنتاج؛ يجب تعيين ⁦listen⁩ و⁦domains⁩ صراحةً. أمثلة: ⁦"main"⁩، ⁦"internal"⁩.

تصريحات ⁦listen⁩ أو ⁦domains⁩ الصريحة تتجاوز الاستنتاج دائماً.

أمثلة سريعة

موقع ثابت مع ⁦TLS⁩ تلقائي (مستنتج من مفتاح النطاق):

amends "elide:serve/ElideServer.pkl"
servers {
  ["example.com"] {
    handler = new StaticFiles { root = "./dist"; spaFallback = true }
  }
}

وكيل عكسي:

servers {
  ["api.example.com"] {
    handler = new ReverseProxy { upstreams { "backend:8080" } }
  }
}

وكيل أمامي مع ⁦MITM⁩:

servers {
  [":8080"] {
    proxy { mitm {}; recording {} }
  }
}

مختلط — تقديم ملفات، ووكيل عكسي لواجهة برمجية، ووكيل أمامي على منفذ واحد:

servers {
  ["app.example.com"] {
    routes {
      new { match = "/api/**"; handler = new ReverseProxy { upstreams { "backend:9000" } } }
    }
    handler = new StaticFiles { root = "./dist"; spaFallback = true }
    proxy { mitm {}; recording {} }
  }
}

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

صفحات مرجع الخادم

صفحات مرجع الوكيل

إعادة تصدير الأنواع

الأنواع المشتركة

ServerTransport

الواجهة الخلفية للنقل المستخدمة لقبول الاتصالات.

⁦"auto"⁩ يختار أفضل واجهة خلفية متاحة للمنصة الحالية.

typealias ServerTransport = "auto" | "io_uring" | "kqueue" | "epoll" | "nio" | "iocp"

LogLevel

مستوى الخطورة لمخرجات السجل المُهيكل. يتم تجاهل الرسائل التي تقل عن المستوى المُعدّ. مرتبة من الأكثر إلى الأقل تفصيلاً: ⁦"trace"⁩، ⁦"debug"⁩، ⁦"info"⁩، ⁦"warn"⁩، ⁦"error"⁩.

typealias LogLevel = "trace" | "debug" | "info" | "warn" | "error"

LogFormat

تنسيق مخرجات السجل المُهيكل.

• ⁦"json"⁩ — كائن ⁦JSON⁩ واحد لكل سطر (مُوصى به لخطوط أنابيب السجلات)
• ⁦"text"⁩ — نص مضغوط في سطر واحد
• ⁦"pretty"⁩ — مخرجات متعددة الأسطر سهلة القراءة

typealias LogFormat = "json" | "text" | "pretty"

Http3Policy

سياسة تفعيل ⁦HTTP/3⁩ (⁦QUIC⁩).

• ⁦"ifTls"⁩ (الافتراضي): تفعيل ⁦HTTP/3⁩ بشفافية عند إعداد ⁦TLS⁩؛ وتعطيله بصمت في حالة عدم وجوده.
• ⁦"required"⁩: يتطلب ⁦HTTP/3⁩ — يرفض الخادم البدء إذا لم يكن ⁦TLS⁩ مُعدّاً.
• ⁦"disabled"⁩: لا يُفعَّل ⁦HTTP/3⁩ أبداً، حتى عند توفر ⁦TLS⁩.

typealias Http3Policy = "ifTls" | "required" | "disabled"

ListenEntry

إدخال المستمع — إما كائن ⁦Listen⁩ كامل أو اختصار نصي.

⁦"0.0.0.0:443"⁩ — عنوان مع البروتوكولات الافتراضية ⁦new Listen { address = "0.0.0.0:443" }⁩ — الصيغة الكاملة

typealias ListenEntry = String | _listen.Listen

UpstreamEntry

إدخال الخادم العلوي — إما كائن ⁦Upstream⁩ كامل أو اختصار نصي.

⁦"backend-1:8080"⁩ — عنوان مع الوزن الافتراضي ⁦new Upstream { address = "backend-1:8080" }⁩ — الصيغة الكاملة

typealias UpstreamEntry = String | _handler.Upstream

HandlerEntry

المعالج لكتلة الخادم — إما ⁦Handler⁩ كامل، أو اختصار كود حالة ⁦UInt⁩.

⁦new StaticFiles { root = "./dist" }⁩ — تقديم ملفات ⁦new ReverseProxy { upstreams { "back:8080" } }⁩ — وكيل خادم علوي ⁦404⁩ — كود حالة ثابت

typealias HandlerEntry = UInt(isBetween(100, 599)) | _handler.Handler

---

الخصائص الجذرية

global

إعدادات عامة تُطبَّق على جميع كتل الخوادم. راجع ⁦GlobalSettings⁩ للحقول المتاحة (العمال، حدود الاتصالات، النقل، الاتصال المستمر، ⁦DNS⁩).

servers

كتل الخوادم، مفهرسة بالنطاق أو العنوان أو التسمية.

عندما تكون القيمة ⁦null⁩، تُستخدم كتلة خادم ضمنية واحدة مع الإعدادات الافتراضية. راجع ⁦ServerBlock⁩ لخيارات كل كتلة والتعليق على مستوى الوحدة لقواعد الاستنتاج من المفتاح.

servers {
  ["example.com"] {
    handler = new StaticFiles { root = "./dist" }
  }
  [":8080"] {
    proxy { mitm {}; recording {} }
  }
}

tls

إعدادات ⁦TLS⁩ وإدارة الشهادات المُطبَّقة على جميع كتل الخوادم افتراضياً. يمكن للكتل الفردية تجاوز حقول محددة عبر ⁦ServerBlock.tls⁩. راجع ⁦TlsConfig⁩ لخيارات ⁦ACME⁩ وتخزين الشهادات وتدبيس ⁦OCSP⁩ ومجموعات التشفير.

networks

ارتباطات الشبكة المُسماة (⁦Tailscale⁩ أو ⁦WireGuard⁩ أو كليهما).

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

networks {
  ["production"] {
    tailscale { direct = true; authKey = env("TS_PROD_KEY") }
    tunnel { bridgeInbound = true }
  }
  ["office-vpn"] {
    wireguard { configFile = "./wg-office.conf" }
    tunnel { bridgeOutbound = true }
  }
}

devMode

تفعيل وضع التطوير. عند تعيينه إلى ⁦true⁩، يحقن الخادم نقطة نهاية ⁦SSE⁩ لإعادة التحميل المباشر ومقتطف ⁦