التقديم باستخدام ⁦Elide⁩

لديك تطبيق ويب، أو واجهة برمجية، أو مجلد ملفات ثابتة وتحتاج إلى تقديمه. ليس "لاحقاً، بعد كتابة ⁦Dockerfile⁩ وإعداد ⁦nginx⁩." الآن. يمنحك ⁦elide serve⁩ خادم ⁦HTTP⁩ بمستوى إنتاجي -- مع ⁦HTTP/2⁩ و⁦HTTP/3⁩ والضغط التلقائي و⁦ETags⁩ ولوحة تحكم تفاعلية -- في أمر واحد. وعندما تتجاوز الإعدادات الافتراضية، يتوسع نفس الأمر ليشمل طوبولوجيات متعددة المضيفين مع الوكيل العكسي و⁦TLS⁩ والبرمجيات الوسيطة وموازنة الأحمال عبر ملف إعداد ⁦Pkl⁩.

البداية السريعة

تقديم مجلد بناء

قمت للتو بتشغيل ⁦npm run build⁩ ولديك مجلد ⁦dist/⁩. قدّمه:

 elide serve ./dist

يربط ⁦Elide⁩ على ⁦127.0.0.1:3000⁩، ويكتشف ⁦index.html⁩ تلقائياً، ويقدّم كل ملف بأنواع ⁦MIME⁩ الصحيحة، وينشئ ⁦ETags⁩ للتحقق من ذاكرة التخزين المؤقت، ويتفاوض على ضغط ⁦Brotli⁩/⁦Zstandard⁩/⁦Gzip⁩ مع العميل. افتح ⁦http://localhost:3000⁩ وستكون جاهزاً.

تشغيل معالج جلب ⁦TypeScript⁩

تريد استجابات ديناميكية. اكتب معالجاً:

// api.ts
export default {
  fetch(request: Request): Response {
    const url = new URL(request.url);

    if (url.pathname === "/api/greeting") {
      return Response.json({ hello: "world", ts: Date.now() });
    }

    return new Response("Not Found", { status: 404 });
  }
};

ثم قدّمه:

 elide serve api.ts

يحمّل ⁦Elide⁩ السكريبت الخاص بك، ويستدعي ⁦fetch()⁩ لكل طلب وارد، ويعيد أي ⁦Response⁩ تقدمه. العقد هو نفسه المستخدم في ⁦Cloudflare Workers⁩ و⁦Deno Deploy⁩ -- إذا كتبت معالج جلب من قبل، فأنت تعرف الواجهة البرمجية بالفعل.

استخدام إعداد ⁦Pkl⁩ لطوبولوجيا كاملة

عندما تحتاج إلى مضيفين افتراضيين أو وكيل عكسي أو برمجيات وسيطة أو ⁦TLS⁩، استخدم ملف إعداد:

amends "elide:serve/ElideServer.pkl"

servers {
  ["app"] {
    domains { "myapp.example.com" }

    routes {
      new {
        match { path = "/api/**" }
        handler = new ReverseProxy {
          upstreams { new { address = "localhost:4000" } }
        }
      }
      new {
        handler = new StaticFiles {
          root = "./dist"
          spaFallback = true
        }
      }
    }
  }
}

 elide serve --config server.pkl

يوجّه هذا ⁦/api/**⁩ إلى خادم خلفي على المنفذ ⁦4000⁩ ويقدّم كل شيء آخر من ⁦./dist⁩، مع احتياطي ⁦SPA⁩ لكي يعمل التوجيه من جانب العميل. تحقق من صحة الإعداد قبل البدء:

 elide serve --check-config --config server.pkl

---

تقديم الملفات الثابتة

في وضع المجلد، يتعامل ⁦Elide⁩ مع التفاصيل التي ستضطر لإعدادها يدوياً:

• أنواع ⁦MIME⁩ -- تُكتشف من امتدادات الملفات، مع ⁦charset=utf-8⁩ الصحيح لأنواع النصوص
• ⁦ETags⁩ -- مبنية على المحتوى، لكي تتخطى المتصفحات إعادة تحميل الملفات غير المتغيرة
• الضغط -- يُتفاوض على ⁦Brotli⁩ و⁦Zstandard⁩ و⁦Gzip⁩ عبر ⁦Accept-Encoding⁩. تُقدَّم الملفات المضغوطة مسبقاً الموجودة على القرص (مثل ⁦app.js.br⁩) مباشرة عند توفرها
• طلبات النطاق -- تعمل التنزيلات القابلة للاستئناف مباشرة
• اكتشاف الفهرس -- يُقدَّم ⁦index.html⁩ لمسارات المجلدات

وضع التطوير

عندما تعمل على موقع محلي بشكل تكراري، أضف ⁦--dev⁩:

 elide serve --dev ./dist

يحقن هذا سكريبت إعادة التحميل المباشر في استجابات ⁦HTML⁩ ويبدأ نقطة نهاية ⁦SSE⁩ على ⁦/__elide_dev/livereload⁩. عندما يتغير أي ملف تحت الجذر، تُعاد تحميل المتصفحات المتصلة تلقائياً. يُخفَّف التخزين المؤقت لكي ترى دائماً أحدث إصدار.

احتياطي ⁦SPA⁩

تطبيقات الصفحة الواحدة التي تتعامل مع التوجيه من جانب العميل تحتاج إلى أن يعيد كل مسار ⁦index.html⁩. في وضع المجلد يتطلب هذا إعداد ⁦Pkl⁩:

handler = new StaticFiles {
  root = "./dist"
  spaFallback = true
  cacheControl = "public, max-age=300"
}

أي طلب لا يطابق ملفاً حقيقياً يعيد ⁦index.html⁩ بدلاً من ⁦404⁩.

الضغط المسبق

عندما يكون ⁦preCompress = true⁩، يضغط ⁦Elide⁩ الملفات عند الطلب الأول ويخزّن النتيجة في الذاكرة. تتخطى الطلبات اللاحقة الضغط بالكامل. بالاقتران مع الملفات المضغوطة مسبقاً على القرص (⁦app.js.br⁩، ⁦app.js.gz⁩)، يُلغي هذا عبء الضغط لكل طلب في بيئة الإنتاج.

قوائم المجلدات

لحالات استعراض الملفات، فعّل الفهرسة التلقائية:

handler = new StaticFiles {
  root = "./files"
  autoindex = true
  autoindexShowSizes = true
  autoindexShowMtime = true
}

تقدّم الفهرسة التلقائية قوائم مجلدات متفاوض عليها حسب المحتوى -- ⁦HTML⁩ أو ⁦JSON⁩ أو نص عادي حسب ترويسة ⁦Accept⁩.

---

وضع السكريبت

يشغّل وضع السكريبت ملف ⁦JavaScript⁩ أو ⁦TypeScript⁩ كخادمك. يجب أن يصدّر الملف دالة ⁦fetch⁩ (أو تصدير افتراضي بأسلوب ⁦fetch⁩) تستقبل ⁦Request⁩ وتعيد ⁦Response⁩:

// handler.ts
export default {
  fetch(request: Request): Response {
    const { method, url } = request;
    const { pathname, searchParams } = new URL(url);

    if (method === "POST" && pathname === "/api/echo") {
      return new Response(request.body, {
        headers: { "Content-Type": request.headers.get("Content-Type") ?? "application/octet-stream" }
      });
    }

    return new Response("Method Not Allowed", { status: 405 });
  }
};

 elide serve handler.ts

تتبع كائنات ⁦Request⁩ و⁦Response⁩ معيار ⁦Fetch API⁩. تعمل الترويسات والمحتويات ورموز الحالة والبث كما تتوقع.

مرّر وسائط إلى السكريبت بعد ⁦--⁩:

 elide serve handler.ts -- --env production --verbose

---

وضع الإعداد

عندما تحتاج أكثر من مجلد واحد أو سكريبت واحد -- مضيفين افتراضيين، وكيل عكسي، ⁦TLS⁩، مكدسات برمجيات وسيطة، خلفيات ⁦CGI⁩/⁦FastCGI⁩ -- عرّف الطوبولوجيا في ⁦Pkl⁩:

amends "elide:serve/ElideServer.pkl"

tls {
  auto = true
  acmeEmail = "admin@example.com"
}

servers {
  ["site"] {
    domains { "example.com"; "www.example.com" }

    middleware {
      new Compress { algorithms { "zstd"; "br"; "gzip" } }
      new SecurityHeaders {}
      new RateLimit { requests = 100; window = 1.s }
    }

    routes {
      new {
        match { host = "www.example.com" }
        handler = new Redirect {
          target = "https:<<>>
          status = 308
        }
      }
      new {
        handler = new StaticFiles {
          root = "./dist"
          spaFallback = true
          preCompress = true
        }
      }
    }
  }
}

تتجاوز خيارات سطر الأوامر (⁦--host⁩، ⁦--port⁩، ⁦--reactors⁩، ⁦--workers⁩، ⁦--dev⁩) قيم ⁦Pkl⁩ المقابلة عند توفر كليهما، لكي تتمكن من الاحتفاظ بإعداد الإنتاج وتعديل الربط محلياً.

---

واجهة المستخدم النصية التفاعلية

افتراضياً، يُطلق ⁦elide serve⁩ لوحة تحكم طرفية تعرض:

• شريط الحالة -- عنوان الربط، البروتوكول، حالة الخادم، مدة التشغيل، والمجلد الجذر
• جدول الطلبات -- بث مباشر لكل طلب مع الأسلوب والمسار والحالة وزمن الاستجابة
• لوحة المقاييس -- طلبات في الثانية الحالية، الاتصالات النشطة، وزمن الاستجابة ⁦p50⁩/⁦p95⁩/⁦p99⁩
• رسم بياني للطلبات -- رسم بياني متدحرج للإنتاجية لمدة ⁦60⁩ ثانية
• لوحة السجلات -- سجلات خادم منظمة مع تصفية حسب الخطورة

---

مرجع سطر الأوامر

elide serve [OPTIONS] [SUBJECT] [-- SCRIPT_ARGS...]

الربط

الإعداد

الأداء

واجهة الإدارة البرمجية

---

ما التالي

• ⁦elide expose⁩ -- ضع خادمك المحلي على الإنترنت مع ⁦TLS⁩ تلقائي وعنوان ⁦URL⁩ عام
• ⁦elide share⁩ -- قدّم مجلداً واكشفه في خطوة واحدة
• مرجع إعداد التقديم -- مخطط ⁦Pkl⁩ الكامل للمعالجات والبرمجيات الوسيطة و⁦TLS⁩ والمستمعين وواجهة الإدارة
• مرجع سطر الأوامر -- جميع أوامر ⁦Elide⁩ والخيارات العامة