capsule

---

Capsule هو بيئة تشغيل لتنفيذ التعليمات البرمجية غير الموثوقة في بيئات معزولة. تعمل كل مهمة داخل صندوق رمل WebAssembly خاص بها، مما يوفر:

• تنفيذ معزول: تعمل كل مهمة بمعزل عن نظام المضيف الخاص بك
• حدود الموارد: حدد حدود المعالج والذاكرة والمهلة الزمنية لكل مهمة
• إعادة المحاولة التلقائية: تعامل مع حالات الفشل دون تدخل يدوي
• تتبع دورة الحياة: راقب المهام التي قيد التشغيل أو المكتملة أو الفاشلة

كيف يعمل

مع Python

ما عليك سوى إضافة التعليق التوضيحي @task إلى دوال Python الخاصة بك:

from capsule import task

@task(name="analyze_data", compute="MEDIUM", ram="512MB", timeout="30s", max_retries=1)
def analyze_data(dataset: list) -> dict:
    """Process data in an isolated, resource-controlled environment."""
    # Your code runs safely in a Wasm sandbox
    return {"processed": len(dataset), "status": "complete"}

مع TypeScript / JavaScript

استخدم دالة التغليف task() مع وصول كامل إلى نظام npm البيئي:

import { task } from "@capsule-run/sdk";

export const analyzeData = task({
  name: "analyze_data",
  compute: "MEDIUM",
  ram: "512MB",
  timeout: "30s",
  maxRetries: 1
}, (dataset: number[]): object => {
  // Your code runs safely in a Wasm sandbox
  return { processed: dataset.length, status: "complete" };
});

[!NOTE] تتطلب بيئة التشغيل مهمة باسم "main" كنقطة دخول. ستنشئ Python واحدة تلقائيًا إذا لم يتم تعريف أي منها، لكن يُوصى بتعيينها بشكل صريح.

عند تشغيل capsule run main.py (أو main.ts)، يتم تجميع التعليمات البرمجية الخاصة بك إلى وحدة WebAssembly وتنفيذها في صناديق رمل معزولة.

تعمل كل مهمة داخل صندوق الرمل الخاص بها مع حدود موارد قابلة للتكوين، مما يضمن احتواء حالات الفشل وعدم انتشارها إلى أجزاء أخرى من سير عملك. يتحكم نظام المضيف في كل جانب من جوانب التنفيذ، من تخصيص المعالج عبر قياس وقود Wasm إلى قيود الذاكرة وفرض المهلة الزمنية.

البدء

Python

pip install capsule-run

أنشئ hello.py:

from capsule import task

@task(name="main", compute="LOW", ram="64MB")
def main() -> str:
    return "Hello from Capsule!"

شغّله:

capsule run hello.py

TypeScript / JavaScript

npm install -g @capsule-run/cli
npm install @capsule-run/sdk

أنشئ hello.ts:

import { task } from "@capsule-run/sdk";

export const main = task({
  name: "main",
  compute: "LOW",
  ram: "64MB"
}, (): string => {
  return "Hello from Capsule!";
});

شغّله:

capsule run hello.ts

[!TIP] أضف --verbose لرؤية تفاصيل تنفيذ المهمة في الوقت الفعلي.

التشغيل من التعليمات البرمجية الخاصة بك

تتيح لك دالة run() تنفيذ المهام برمجيًا من التعليمات البرمجية الخاصة بك بدلاً من استخدام CLI. يتم تمرير args تلقائيًا كمعاملات إلى مهمة main.

Python

from capsule import run

result = await run(
    file="./sandbox.py",
    args=["code to execute"]
)

أنشئ sandbox.py:

from capsule import task

@task(name="main", compute="LOW", ram="64MB")
def main(code: str) -> str:
    return eval(code)

TypeScript / JavaScript

[!IMPORTANT] تحتاج إلى @capsule-run/cli في تبعياتك لاستخدام دوال المشغّل في TypeScript.

import { run } from '@capsule-run/sdk/runner';

const result = await run({
  file: './sandbox.ts',
  args: ['code to execute']
});

أنشئ sandbox.ts:

import { task } from "@capsule-run/sdk";

export const main = task({
  name: "main",
  compute: "LOW",
  ram: "64MB"
}, (code: string): string => {
  return eval(code);
});

[!TIP] إذا كنت تبحث عن حل جاهز ومُهيأ مسبقًا، تحقق من محوّل Python أو محوّل TypeScript.

التوثيق

خيارات تكوين المهمة

قم بتكوين مهامك باستخدام هذه المعاملات:

المعامل	الوصف	النوع	الافتراضي	مثال
name	معرّف المهمة	str	اسم الدالة (Python) / مطلوب (TS)	"process_data"
compute	مستوى تخصيص المعالج: "LOW" أو "MEDIUM" أو "HIGH"	str	"MEDIUM"	"HIGH"
ram	حد الذاكرة للمهمة	str	غير محدود	"512MB", "2GB"
timeout	الحد الأقصى لوقت التنفيذ	str	غير محدود	"30s", "5m", "1h"
max_retries / maxRetries	عدد محاولات إعادة المحاولة عند الفشل	int	0	3
allowed_files / allowedFiles	المجلدات التي يمكن الوصول إليها في صندوق الرمل (مع وضع وصول اختياري)	list	[]	["./data"], [{"path": "./data", "mode": "ro"}]
allowed_hosts / allowedHosts	النطاقات التي يمكن الوصول إليها في صندوق الرمل	list	[]	["api.openai.com", "*.anthropic.com"]
env_variables / envVariables	متغيرات البيئة التي يمكن الوصول إليها في صندوق الرمل	list	[]	["API_KEY"]

مستويات الحوسبة

تتحكم Capsule في استخدام المعالج من خلال آلية الوقود في WebAssembly، والتي تقيس تنفيذ التعليمات. يحدد مستوى الحوسبة مقدار الوقود الذي تتلقاه مهمتك.

• يوفر LOW تخصيصًا أدنى للمهام الخفيفة
• يوفر MEDIUM موارد متوازنة لأحمال العمل النموذجية
• يمنح HIGH أقصى قدر من الوقود للعمليات كثيفة الحوسبة
• CUSTOM لتحديد قيمة وقود دقيقة (مثل compute="1000000") للتحكم الدقيق في حدود التنفيذ.

تنسيق الاستجابة

تُرجع كل مهمة غلاف JSON منظمًا يحتوي على كل من النتيجة وبيانات التنفيذ الوصفية:

{
  "success": true,
  "result": "Hello from Capsule!",
  "error": null,
  "execution": {
    "task_name": "data_processor",
    "duration_ms": 1523,
    "retries": 0,
    "fuel_consumed": 45000,
    "ram_used": 1200000,
    "host_requests": [{...}]
  }
}

حقول الاستجابة:

• success — قيمة منطقية تشير إلى ما إذا كانت المهمة قد اكتملت بنجاح
• result — القيمة الفعلية المُرجعة من مهمتك (json، string، null عند الفشل، إلخ)
• error — تفاصيل الخطأ إذا فشلت المهمة ({ error_type: string, message: string })
• execution — مقاييس الأداء:
  • task_name — اسم المهمة المنفذة
  • duration_ms — وقت التنفيذ بالمللي ثانية
  • retries — عدد محاولات إعادة المحاولة التي حدثت
  • fuel_consumed — موارد المعالج المستخدمة (انظر مستويات الحوسبة)
  • ram_used — ذروة الذاكرة المستخدمة بالبايت
  • host_requests — قائمة طلبات المضيف التي أجرتها المهمة

الوصول إلى الشبكة

يمكن للمهام إجراء طلبات HTTP إلى النطاقات المحددة في allowed_hosts. بشكل افتراضي، لا يُسمح بأي طلبات صادرة ([]). قدّم قائمة نطاقات مسموح بها لمنح الوصول، أو استخدم ["*"] للسماح بجميع النطاقات.

Python

import json
from capsule import task
from urllib.request import urlopen

@task(name="main", allowed_hosts=["api.openai.com", "*.anthropic.com"])
def main() -> dict:
    with urlopen("https://api.openai.com/v1/models") as response:
        return json.loads(response.read().decode("utf-8"))

TypeScript / JavaScript

import { task } from "@capsule-run/sdk";

export const main = task({
    name: "main",
    allowedHosts: ["api.openai.com", "*.anthropic.com"]
}, async () => {
    const response = await fetch("https://api.openai.com/v1/models");
    return response.json();
});

الوصول إلى الملفات

يمكن للمهام قراءة وكتابة الملفات داخل المجلدات المحددة في allowed_files. أي محاولة للوصول إلى ملفات خارج هذه المجلدات غير ممكنة.