Vpod

البدء • التوثيق • المشكلات • المساهمة

ما هو vpod؟

vpod هو صندوق رمل (sandbox) خفيف الوزن وقابل للنقل يمنح عملية غير موثوقة بيئة لينكس فورية. يستخدم بنية RISC‑V ويعمل بالكامل داخل WebAssembly.

• إقلاع سريع: الإقلاع في أقل من ثانية.
• قابل للنقل: يعمل في أي مكان دون الحاجة إلى أي إعداد.
• معزول: تبقى كل حالة التنفيذ داخل صناديق الرمل WASM.

كيف يعمل

يشغّل vpod نظام RISC‑V كاملاً (RV64GC، وحدة معالجة افتراضية واحدة) مترجمًا إلى WebAssembly. بداخله يُقلع نواة لينكس حقيقية مع فضاء مستخدم حقيقي، لذا تتصرف الصدفات والأدوات والخدمات الخلفية كما لو كانت على عتاد حقيقي.

اللقطات (Snapshots). بدلاً من إقلاع لينكس من الصفر، يستعيد vpod لقطة: حالة جهاز محفوظة (مسجلات وحدة المعالجة، الذاكرة العشوائية، نظام الملفات) مأخوذة بعد الإقلاع مباشرة. يستغرق استعادتها أقل من ثانية بكثير. يعمل الإيقاف المؤقت بنفس الطريقة بالعكس، إذ تُكتب صفحات الذاكرة المتسخة فقط مرة أخرى إلى القرص، لذا يمكنك إيقاف صندوق الرمل مؤقتًا واستئنافه لاحقًا، حتى من عملية أخرى.

الترجمة المسبقة (Ahead-of-time translation). المحاكاة الخالصة تعليمةً بتعليمة بطيئة، كما تستبعد WebAssembly ترجمة JIT في وقت التشغيل. لذا في وقت بناء اللقطة، تُترجم مسارات الكود الضيف الأكثر استهلاكًا من RISC‑V إلى كود أصلي يُدمج في وحدة WASM نفسها. في وقت التشغيل يوجّه المحاكي التنفيذ إلى هذه الكتل المترجمة عندما يطابق كود الضيف، ويعود إلى المفسّر عندما لا يطابق. هذا يحقق تسريعًا يقارب 5 أضعاف في الأعمال المعتمدة على وحدة المعالجة، دون أي تأثير على العزل: يمر الكود المترجم عبر نفس فحوصات MMU والذاكرة التي يمر بها الكود المفسَّر.

حدود WASI. تتواصل مكوّنات WASM مع المضيف حصريًا عبر WASI 0.2. لا يطّلع الضيف أبدًا على واصفات ملفات المضيف أو مقابسه أو ذاكرته: يمر الوصول إلى نظام الملفات عبر أدلة مُثبَّتة صراحة، ويمر التواصل الشبكي عبر حزمة شبكة في وضع المستخدم داخل المكوّن لا تطلب من المضيف سوى مقابس صادرة عادية. كل شيء آخر (نواة الضيف وعملياته وذاكرته) يعيش داخل الذاكرة الخطية لـ WASM ويموت بموتها.

مواصفات RV64GC

G (إضافات الأغراض العامة)

• I: مجموعة تعليمات الأعداد الصحيحة الأساسية 64-بت.
• M: الضرب والقسمة عتادياً، مفيدان للتجزئة والتشفير.
• A: عمليات ذرية للبرامج الآمنة في تعدد الخيوط.
• F/D: الفاصلة العائمة بدقة مفردة ومزدوجة، مناسبتان للحوسبة العلمية واستدلال التعلم الآلي.

C (التعليمات المضغوطة) يقلل حجم الكود بنسبة 30%، محسنًا سرعة جلب التعليمات وكفاءة الذاكرة. يهمّ هذا عند تشغيل فضاء مستخدم لينكس كامل داخل بيئة WASM المقيدة بالذاكرة.

[!NOTE] إضافة V (المتجهات) غير منفَّذة. ستُنفَّذ تعليمات RVV كـ RISC-V مُحاكى؛ لا يوجد تمرير SIMD إلى وحدة معالجة المضيف. إضافة V ستزيد عبء المحاكاة دون أي فائدة أداء لأحمال العمل الموجهة للمتجهات.

البدء

حزمة تطوير Python SDK

pip install vpod

from vpod import Sandbox

# Run a command
sandbox = Sandbox.create()
result = sandbox.commands.run("whoami")
print(result.stdout)  # root
sandbox.close()

# Persistent session — state preserved across calls
with Sandbox.create() as sandbox:
    sandbox.commands.run("export API_KEY=secret")
    result = sandbox.commands.run("echo $API_KEY")
    print(result.stdout)  # secret

# Python REPL — variables persist
with Sandbox.create() as sandbox:
    sandbox.code.run("import requests")
    sandbox.code.run("data = [1, 2, 3]")
    result = sandbox.code.run("print(sum(data))")
    print(result.text)  # 6

[!IMPORTANT] الاستدعاء الأول لـ Sandbox.create() ينزّل اللقطة الافتراضية (alpine) ويخزّنها مؤقتًا محليًا إذا لم تكن موجودة مسبقًا.

واجهة سطر الأوامر CLI

curl -fsSL https://install.vpod.sh | sh

أو ثبّت عبر PowerShell (ويندوز)

root@kitploit:~

irm https://install.vpod.sh | iex

# Pull a snapshot
vpod pull alpine:latest

# Start an interactive shell
vpod

التوثيق

تفضل بزيارة توثيق Vpod.

القيود

• عبء المحاكاة: لا توجد افتراضية عتادية داخل WebAssembly، لذا يُحاكى كل كود الضيف. يعتمد العبء كليًا على حمل العمل: يعمل العمل المعتمد على الإدخال/الإخراج وعلى الشبكة بسرعة قريبة من السرعة الأصلية، بينما يكون العمل المكثّف على وحدة المعالجة أبطأ بشكل ملحوظ حتى مع الترجمة المسبقة AOT. إذا كان حمل عملك غالبًا "شغّل أداة، اقرأ ملفًا، استدعِ واجهة برمجة تطبيقات"، فلن تلاحظ الفرق.
• لا وصول إلى GPU: لا تتوفر CUDA وMetal ومسرعات التعلم الآلي العتادية. قد تُضاف البرمجية الداعمة مستقبلًا عبر wasi-nn.

المساهمة

المساهمات مرحب بها، من تقارير الأخطاء إلى دعم الأجهزة الجديدة. افتح تقرير مشكلة (issue) لمناقشة أي شيء جوهري قبل بنائه.

المتطلبات الأساسية

• Rust (أحدث نسخة مستقرة) مع هدف wasm32-wasip2: rustup target add wasm32-wasip2
• Python 3.10+ لحزمة التطوير SDK
• Zig (0.16) وbsdtar، اللازمان فقط إذا كنت تبني اللقطات بنفسك

إعداد التطوير

# One-time: generate the AOT stub (a fresh clone has no translated blocks)
./scripts/aot-stub.sh

# Build the WASM component (library + CLI)
./scripts/build-wasm.sh

# Install the host CLI
cargo install --path crates/vpod

# Install the Python SDK in dev mode
pip install -e "sdks/python[dev]"

تشغيل الاختبارات

يشغّل التكامل المستمر CI هذه الاختبارات في كل طلب سحب، لذا شغّلها قبل الدفع:

cargo fmt --all -- --check                        # formatting
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all                                  # Rust tests

# Python SDK integration tests (needs the WASM library in place)
cp target/wasm32-wasip2/release/vpod_wasi_lib.wasm sdks/python/vpod/
pytest sdks/python/tests/ -v -m integration

بناء اللقطات

يستخدم المشروع لقطات Alpine مبنية مسبقًا من registry.vpod.sh، لذا لا تحتاج لهذا عادةً. لبناء واحدة محليًا:

./scripts/build-default-snapshot.sh   # dist/alpine-3.23.0-256mb.snap
./scripts/build-data-snapshot.sh      # 512 MB variant with numpy/pandas/scipy

[!IMPORTANT] لاستخدام لقطة مبنية محليًا، أزل التعليق عن الأسطر في resolve_snapshot() داخل crates/vpod/src/main.rs.

يمكن لبناءات اللقطات أيضًا تشغيل مرحلة AOT (scripts/aot-snapshot.sh <snapshot>) التي تتعقّب حمل عمل تمثيليًا، وتترجم الكتل الساخنة، وتعيد بناء المحاكي مع تضمينها. يستغرق هذا بعض الوقت؛ كعب aot-stub.sh يكفي للتطوير اليومي، إذ يعمل كل شيء بنفس الطريقة، فقط أبطأ.

طلبات السحب

• أبقِ طلبات السحب مركّزة: تغيير واحد لكل طلب سحب.
• يجب أن تنجح fmt وclippy ومجموعة الاختبارات (يفرض CI الثلاثة جميعًا).
• إذا لمست مسارات التنفيذ أو الذاكرة في المحاكي، فاذكر كيف تحققت من صحة العمل (مجموعة الاختبارات على الأقل؛ بالنسبة للتغييرات الدقيقة، يُعد الإقلاع مع حمل عمل حقيقي داخل الضيف فحصًا جيدًا للسلامة).

الترخيص

هذا المشروع مرخّص بموجب رخصة Apache 2.0. راجع ملف الترخيص (LICENSE) للتفاصيل.