Capabilities and frames

الدرز بين Faber وكل طريقة يمكن لنظام التشغيل بها تنفيذ الإدخال/الإخراج.

اتصل هو بدائي استدعاء القدرة منخفض المستوى في Faber — الحد الفاصل بين كود Faber والعالم الخارجي. يفتح محادثة مُنمَّطة (قناة) مع مورد مضيف يُعرَّف بسلسلة مسار، ثم يتبادل إطارات مهيكلة (إطار) عبر أنصاف تيارات موجَّهة. يُرسل نواة المضيف كل مسار إلى صندوق مزود قابل للتوصيل، والذي ينفذ الإدخال/الإخراج الفعلي — نظام الملفات، الشبكات، الطرفية، الوقت، العشوائية، أو أي شيء آخر يمكن لنظام التشغيل فعله.

بدائي `اتصل`#

اتصل كلمة مفتاحية، وليس دالة. يفتح محادثة معتمة مع مسار يُسمَّى بثابت أسكي وبيانات افتتاحية اختيارية:

# Simple materialized call: open, send opener, drain response
ثابت نص content ← اتصل 'solum:lege' ("config.toml") ↦ نص

# Typed conversation handle for streaming interaction
ثابت قناة s ← اتصل 'processus:curre' ("ls", ["-la"])

تتبع سلسلة المسار نمط prefix:verb. تطابق نواة المضيف على البادئة فقط — يمتلك المزود كل الأفعال تحت تلك البادئة:

solum:lege   ─┐
solum:modum  ─┼─►  prefix "solum"  ──►  فقط provider crate
solum:vincula─┘

اتصل ليس واجهة دوال أجنبية. لا يستدعي دوال C، ولا يحمّل مكتبات ديناميكية، ولا يضمّن تجميعًا مضمّنًا. إنه حد تمرير رسائل مهيكل: يرسل Faber إطارات مُنمَّطة ويستقبل إطارات مُنمَّطة، دون معرفة ما إذا كان المزود منفذًا بلغة Rust، أو يعمل داخل العملية، أو يفوض إلى استدعاء نظام، أو يعيد التوجيه إلى مضيف بعيد.

أنواع الإطارات#

تشكل خمسة أنواع مملوكة للمصرّف نظام الإطارات:

النوع	الدور	السطح الرئيسي
`قناة`	مقبض محادثة — تبادل ثنائي الاتجاه قيد التنفيذ	يُنشأ بواسطة `اتصل`؛ يُستنزف عبر `↦ T` أو يُقسَّم إلى مناظير
`إطار<T>`	غلاف إطار — رسالة مهيكلة واحدة في محادثة	حقول: `id`، `call`، `status`، `data`، `created_ms`، `from`، `trace`
`status`	تعداد علامة دورة الحياة	`request`، `item`، `byte`، `bulk`، `done`، `error`، `cancel`
`إرسال<T>`	نصف تيار صادر — إرسال إطارات إلى المزود	`da(T)`، `fini() → status`
`استقبال<T>`	نصف تيار وارد — استقبال إطارات من المزود	`accipe()`، `cursor()`، `exhauri()`، `fini()`

استخدام المناظير الموجهة#

# Open a conversation, get directional views
ثابت قناة s ← اتصل 'solum:scribe' ("output.txt")
ثابت إرسال<نص> out ← s.meus<نص>()
ثابت استقبال<نص> input ← s.tuus<نص>()

# Send content frames
out.da("line one")
out.da("line two")
out.fini()

# Read response frames
كرر من input.cursor() ثابت frame {
    اعرض frame.data
}
ثابت status inbound ← input.fini()

التجسيد البسيط#

للحالة الشائعة — فتح، إرسال بيانات افتتاحية، استنزاف كل إطارات الاستجابة إلى قيمة واحدة — يطوي قناة ↦ T المحادثة:

# Read a file: open + drain into نص
ثابت نص body ← اتصل 'solum:lege' ("config.toml") ↦ نص

# Parse JSON from an HTTP response
ثابت جسون data ← اتصل 'http:peti' ("https://api.example.com/data") ↦ جسون

يستخدم التجسيد جامعًا موجَّهًا بالنوع: ↦ نص يربط كل الإطارات الواردة، ↦ جسون يحلل الحمولة المربوطة، ↦ قائمة<T> يجمع الإطارات في قائمة.

مزودو المضيف#

تُنفذ عائلات التأثير كصناديق مزود منفصلة تحت faberlang/host-providers-rs. يمتلك كل مزود كل الأفعال تحت بادئته:

المزود	البادئة	نطاق الإدخال/الإخراج
`فقط`	`فقط:*`	نظام الملفات: قراءة، كتابة، بيانات وصفية، عمليات الأدلة
`processus`	`processus:*`	تنفيذ العمليات: تشغيل، أنابيب، رموز خروج
`consolum`	`consolum:*`	إدخال/إخراج الطرفية: stdin، stdout، stderr
`tempus`	`tempus:*`	الوقت: الآن، إسبات، مؤقتات
`aleator`	`aleator:*`	العشوائية: إنتروبيا، توزيعات
`http`	`http:*`	عميل HTTP (المستوى د، عند الهبوط)

المزودات صناديق منفصلة بتبعيَّاتها الخاصة — فقط لا يسحب HTTP، وhttp لا يسحب كود نظام الملفات. يصدّر كل مزود دالة register() يستدعيها بيان المضيف المُولَّد عند بدء التشغيل.

مكدس الطبقات#

Faber source:     اتصل 'solum:lege' (path) ↦ نص
Compiler:         قناة open + generic attach (no provider crate names)
Runtime:          HostDispatch + conversation protocol (faber-runtime)
Kernel:           route(frame) → provider for prefix
Provider:         فقط provider reads file, returns content

يُصدر المصرّف إرسالًا عامًا — لا يضمّن أبدًا أسماء صناديق المزود في الكود المُولَّد. يوفر وقت التشغيل HostDispatch وبروتوكول المحادثة. توجه النواة (من host-kernel-rs) الإطارات إلى المزود الصحيح بناءً على البادئة. ينفذ المزود (من host-providers-rs) الإدخال/الإخراج الفعلي.

هذا يعني أن كود Faber المُولَّد محايد تجاه المزود. يمكن ربط نفس الثنائي المجمَّع بتطبيقات مزود مختلفة — مزود نظام ملفات حقيقي للإنتاج، ومزود وهمي للاختبار — بتغيير بيان التجميع.

بيان التجميع#

يُتحكم في أي المزودات تُربط بواسطة بيان التجميع المُولَّد وجدول [dispatch] في faber.toml:

[target.rust]
host = "native"

[dispatch]
providers = ["solum", "processus", "consolum", "tempus", "aleator"]

[dispatch.providers.http]
enabled = true

أثناء التأليف، تنتج المزودات المفقودة خطأ وقت تشغيل E_NO_ROUTE. في الوضع الصارم (مستقبلًا)، يجب أن يظهر كل بادئة اتصل في البرنامج في بيان التجميع، ويتحقق المصرّف من أن بيان قدرة المزود يغطي المسارات المستخدمة.

المعمارية#

تنقسم منصة المضيف عبر ثلاثة مستودعات في منظمة faberlang:

المستودع	الدور
`host-kernel-rs`	موجِّه رفيع — يمتلك `Frame`، `Conversation`، دورة حياة الطرفية، إرسال البادئات، الأخطاء المهيكلة (`E_NO_ROUTE`)، تجميع بيان القدرة
`host-native-rs`	إرفاق أصلي — عمال، خطاف بدء `register_providers`، تكامل `host_register.rs` المُولَّد
`host-providers-rs`	تطبيقات المزود — مساحة عمل Cargo بصناديق لكل عائلة (`فقط`، `processus`، إلخ)

يمتلك كل صندوق مزود تبعيَّاته الأصلية الخاصة. يسحب مزود http hyper وtokio فقط عند تمكين HTTP. يستخدم مزود فقط واجهات برمجة ملفات قياسية دون تبعيات شبكة إضافية.

نفس المسار، أي مضيف. لأن اتصل يرسل على سلاسل المسار والمزودات قابلة للتوصيل، يمكن لنفس مصدر Faber استهداف ثنائي أصلي (host-native-rs)، أو وقت تشغيل WASM (host-kernel كمحوّل Frame/Wasm)، أو عملية TypeScript Node.js (host-providers-ts) دون تغيير سطر واحد من كود Faber.

مغلّفات Norma#

معظم كود Faber لا يستدعي اتصل مباشرة. تغلّف مكتبة Norma القياسية مسارات اتصل الشائعة في دوال مُنمَّطة:

# Norma wraps اتصل in typed, reviewed functions
دالة اقرأ(نص عبر) → نص {
    أعد اتصل 'solum:lege' (عبر) ↦ نص
}

دالة اكتب(نص عبر, نص content) → فراغ {
    ثابت فراغ _ ← اتصل 'solum:scribe' (عبر, content) ↦ فراغ
}

دالة curre(نص command, قائمة<نص> args) → نص {
    أعد اتصل 'processus:curre' (command, args) ↦ نص
}

توفر هذه الدوال المغلفة أمان الأنواع، والتوثيق، ومعالجة الأخطاء دون إخفاء حقيقة أن الإدخال/الإخراج يعبر حد اتصل. مغلفات Norma مفتوحة المصدر وتوجد تحت norma/src/.

المراجع#

radix/docs/design/frame-stream-types.md — المواصفة الكاملة لـ قناة، إطار، status، إرسال، استقبال
radix/docs/design/host-provider-gateway.md — معمارية الموجه الرفيع، عقود المزود، بيان التجميع
faberlang/host-kernel-rs/ — تطبيق موجه النواة
faberlang/host-native-rs/ — الإرفاق الأصلي والتسجيل
faberlang/host-providers-rs/ — صناديق المزود (فقط، processus، consolum، tempus، aleator، http)
examples/corpus/ad/ — ملفات أمثلة قناة