Capsule

आरंभ करें • दस्तावेज़ीकरण • समस्याएँ • योगदान

अवलोकन

Capsule एक रनटाइम है जो अविश्वसनीय कोड को पृथक वातावरण में निष्पादित करने के लिए है। प्रत्येक कार्य अपने स्वयं के WebAssembly सैंडबॉक्स के अंदर चलता है, जो प्रदान करता है:

• पृथक निष्पादन: प्रत्येक कार्य आपके होस्ट सिस्टम से पृथक चलता है
• संसाधन सीमाएँ: प्रति कार्य CPU, मेमोरी और टाइमआउट सीमाएँ निर्धारित करें
• स्वचालित पुनर्प्रयास: मैन्युअल हस्तक्षेप के बिना विफलताओं को संभालें
• जीवनचक्र ट्रैकिंग: मॉनिटर करें कि कौन से कार्य चल रहे हैं, पूर्ण हुए हैं या विफल हुए हैं

यह कैसे काम करता है

Python के साथ

अपने Python फ़ंक्शन को @task डेकोरेटर से एनोटेट करें:

from capsule import task

@task(name="analyze_data", compute="MEDIUM", ram="512MB", timeout="30s", max_retries=1)
def analyze_data(dataset: list) -> dict:
    """एक पृथक, संसाधन-नियंत्रित वातावरण में डेटा संसाधित करें।"""
    # आपका कोड सुरक्षित रूप से Wasm सैंडबॉक्स में चलता है
    return {"processed": len(dataset), "status": "complete"}

TypeScript / JavaScript के साथ

npm इकोसिस्टम तक पूर्ण पहुँच के साथ task() रैपर फ़ंक्शन का उपयोग करें:

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

export const analyzeData = task({
  name: "analyze_data",
  compute: "MEDIUM",
  ram: "512MB",
  timeout: "30s",
  maxRetries: 1
}, (dataset: number[]): object => {
  // आपका कोड सुरक्षित रूप से Wasm सैंडबॉक्स में चलता है
  return { processed: dataset.length, status: "complete" };
});

[!NOTE] रनटाइम के लिए एक कार्य का नाम "main" प्रवेश बिंदु के रूप में होना आवश्यक है। Python स्वचालित रूप से एक बनाएगा यदि कोई परिभाषित नहीं है, लेकिन इसे स्पष्ट रूप से सेट करने की अनुशंसा की जाती है।

जब आप capsule run main.py (या main.ts) चलाते हैं, तो आपका कोड WebAssembly मॉड्यूल में संकलित होता है और पृथक सैंडबॉक्स में निष्पादित होता है।

प्रत्येक कार्य अपने स्वयं के सैंडबॉक्स के भीतर कॉन्फ़िगरेबल संसाधन सीमाओं के साथ संचालित होता है, यह सुनिश्चित करता है कि विफलताएँ नियंत्रित रहें और आपके वर्कफ़्लो के अन्य भागों में न फैलें। होस्ट सिस्टम निष्पादन के हर पहलू को नियंत्रित करता है, Wasm ईंधन मीटरिंग के माध्यम से CPU आवंटन से लेकर मेमोरी बाधाओं और टाइमआउट प्रवर्तन तक।

आरंभ करें

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] TypeScript में रनर फ़ंक्शन का उपयोग करने के लिए आपको अपनी निर्भरताओं में @capsule-run/cli की आवश्यकता है।

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 एडाप्टर देखें।

दस्तावेज़ीकरण

कार्य कॉन्फ़िगरेशन विकल्प

अपने कार्यों को इन पैरामीटरों से कॉन्फ़िगर करें:

कंप्यूट स्तर (Compute Levels)

Capsule WebAssembly के ईंधन तंत्र के माध्यम से CPU उपयोग को नियंत्रित करता है, जो अनुदेश निष्पादन को मीटर करता है। कंप्यूट स्तर निर्धारित करता है कि आपके कार्य को कितना ईंधन मिलता है।

• 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 — उपयोग किए गए CPU संसाधन (देखें कंप्यूट स्तर)
  • ram_used — बाइट्स में उपयोग की गई अधिकतम मेमोरी
  • host_requests — कार्य द्वारा किए गए होस्ट अनुरोधों की सूची

नेटवर्क पहुँच

कार्य allowed_hosts में निर्दिष्ट डोमेन पर HTTP अनुरोध कर सकते हैं। डिफ़ॉल्ट रूप से, कोई आउटबाउंड अनुरोध अनुमत नहीं है ([])। पहुँच प्रदान करने के लिए डोमेन की एक अनुमति सूची प्रदान करें, या सभी डोमेन की अनुमति देने के लिए ["*"] का उपयोग करें।

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 में निर्दिष्ट निर्देशिकाओं के भीतर फ़ाइलों को पढ़ और लिख सकते हैं। इन निर्देशिकाओं के बाहर फ़ाइलों तक पहुँचने का कोई प्रयास संभव नहीं है।

[!NOTE] allowed_files केवल निर्देशिका पथों का समर्थन करता है, व्यक्तिगत फ़ाइलों का नहीं।

प्रत्येक प्रविष्टि एक सादा पथ (डिफ़ॉल्ट रूप से पढ़ने-लिखने) या स्पष्ट mode के साथ एक संरचित ऑब्जेक्ट हो सकती है:

• "read-only" (या "ro")
• "read-write" (या "rw")

Python

Python के मानक फ़ाइल संचालन सामान्य रूप से काम करते हैं। open(), os, pathlib, या किसी भी फ़ाइल हेरफेर लाइब्रेरी का उपयोग करें।

from capsule import task

@task(name="main", allowed_files=[
    {"path": "./data", "mode": "read-only"},
    {"path": "./output", "mode": "read-write"},
])
def main() -> str:
    with open("./data/input.txt") as f:
        content = f.read()
    with open("./output/result.txt", "w") as f:
        f.write(content)
    return content

सादे स्ट्रिंग अभी भी स्वीकार किए जाते हैं: allowed_files=["./output"] डिफ़ॉल्ट रूप से read-write होता है।

TypeScript / JavaScript

सामान्य Node.js बिल्ट-इन उपलब्ध हैं। मानक fs मॉड्यूल का उपयोग करें:

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

export const main = task({
    name: "main",
    allowedFiles: [
        { path: "./data", mode: "read-only" },
        { path: "./output", mode: "read-write" },
    ]
}, async () => {
    const content = await fs.readFile("./data/input.txt", "utf8");
    await fs.writeFile("./output/result.txt", content);
    return content;
});

सादे स्ट्रिंग अभी भी स्वीकार किए जाते हैं: allowedFiles: ["./output"] डिफ़ॉल्ट रूप से read-write होता है।

डायनामिक निर्देशिका उपनाम (--mount)

--mount फ़्लैग (CLI) या mounts पैरामीटर (SDK) एक होस्ट निर्देशिका को सैंडबॉक्स में एक उपनाम के तहत माउंट करता है। Mounts उप-कार्यों में प्रसारित होते हैं और नए पथों तक पहुँच जोड़ते हैं, वे allowed_files में पहले से घोषित पथों के एक्सेस मोड को नहीं बदलते हैं।

प्रारूप: HOST_PATH[::GUEST_PATH][:ro|:rw]

CLI

# एक सत्र कार्यक्षेत्र माउंट करें और इसे कार्य के अंदर "workspace" के रूप में प्रदर्शित करें
capsule run main.py --mount sessions/abc123_workspace::workspace

# एकाधिक निर्देशिकाएँ
capsule run main.py \
  --mount sessions/abc123_workspace::workspace \
  --mount sessions/bce456_workspace::workspace:ro

Python SDK

from capsule import run

result = await run(
    file="main.py",
    mounts=[".capsule/sessions/abc123_workspace::workspace"],
)

TypeScript / JavaScript SDK

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

const result = await run({
    file: "main.py",
    mounts: [".capsule/sessions/abc123_workspace::workspace"],
});

कार्य के अंदर, निर्देशिका अतिथि पथ के माध्यम से एक्सेस की जाती है:

# कार्य इसे "workspace/", पूर्ण सत्र पथ पर नहीं देखता है
with open("workspace/output.txt", "w") as f:
    f.write("done")

[!NOTE] --mount पथ सापेक्ष होने चाहिए और प्रोजेक्ट रूट से बाहर नहीं निकलने चाहिए। निरपेक्ष पथ अस्वीकार कर दिए जाते हैं।

पर्यावरण चर

कार्य कॉन्फ़िगरेशन, API कुंजी या अन्य रनटाइम सेटिंग्स पढ़ने के लिए पर्यावरण चर तक पहुँच सकते हैं।

Python

पर्यावरण चर तक पहुँचने के लिए Python के मानक os.environ का उपयोग करें:

from capsule import task
import os

@task(name="main", env_variables=["API_KEY"])
def main() -> dict:
    api_key = os.environ.get("API_KEY")
    return {"api_key": api_key}

TypeScript / JavaScript

पर्यावरण चर तक पहुँचने के लिए मानक process.env का उपयोग करें:

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

export const main = task({
    name: "main",
    envVariables: ["API_KEY"]
}, () => {
    const apiKey = process.env.API_KEY;
    return { apiKeySet: apiKey !== undefined };
});

प्रोजेक्ट कॉन्फ़िगरेशन (वैकल्पिक)

आप अपने प्रोजेक्ट रूट में एक capsule.toml फ़ाइल बना सकते हैं ताकि सभी कार्यों के लिए डिफ़ॉल्ट विकल्प सेट हो सकें और वर्कफ़्लो मेटाडेटा परिभाषित हो सके:

# capsule.toml

[workflow]
name = "My Workflow"
version = "1.0.0"
entrypoint = "src/main.py"  # `capsule run` चलाने पर डिफ़ॉल्ट फ़ाइल

[tasks]
default_compute = "MEDIUM"
default_ram = "256MB"
default_timeout = "30s"
default_max_retries = 2

एक entrypoint परिभाषित होने पर, आप बस चला सकते हैं:

capsule run

कार्य-स्तर के विकल्प हमेशा निर्दिष्ट होने पर इन डिफ़ॉल्ट को ओवरराइड करते हैं।

कैश प्रबंधन

जब आप अपना कोड चलाते हैं, तो Capsule आपके प्रोजेक्ट रूट में एक .capsule फ़ोल्डर बनाता है। यह बिल्ड कैश है। यह संकलित आर्टिफैक्ट्स को संग्रहीत करता है ताकि बाद के रन तेज़ हों (सेकंड से लेकर कुछ मिलीसेकंड तक)।

[!TIP] .capsule को .gitignore में जोड़ा जाना चाहिए। कैश आपके अपने वातावरण के लिए विशिष्ट है और स्वचालित रूप से पुनर्जीवित हो जाएगा।

.capsule/
├── wasm/
│   ├── main_a1b2c3d4.wasm    # संकलित WebAssembly मॉड्यूल
│   └── main_a1b2c3d4.cwasm   # नेटिव प्रीकंपाइल्ड कैश
├── wit/                       # इंटरफ़ेस परिभाषाएँ
└── trace.db                   # निष्पादन लॉग

पहले रन पर संकलन लागत को छोड़ने के लिए capsule build का उपयोग करके पहले से संकलित करें:

capsule build main.ts # या `main.py`

प्रोडक्शन

स्रोत कोड (जैसे .py या .ts) को सीधे चलाना आपकी फ़ाइल को रनटाइम पर मूल्यांकित और संकलित करता है। विकास के लिए बढ़िया, लेकिन यह संकलन चरण पहली कॉल पर कुछ सेकंड की विलंबता जोड़ता है। उन उपयोग मामलों के लिए जहां उप-सेकंड विलंबता महत्वपूर्ण है, आपको अपने कार्यों को पहले से बनाना चाहिए।

# एक अनुकूलित hello.wasm फ़ाइल उत्पन्न करता है
capsule build hello.py --export

# संकलित आर्टिफैक्ट को सीधे निष्पादित करें
capsule exec hello.wasm

[!NOTE] या अपने मौजूदा कोड से:

root@kitploit:~

from capsule import run

result = await run(
   file="./hello.wasm", # या `hello.py`
   args=[]
)

print(f"कार्य पूर्ण: {result['result']}")

.wasm फ़ाइल निष्पादित करना कंपाइलर को पूरी तरह से बायपास करता है, आरंभीकरण समय को मिलीसेकंड तक कम करता है, जबकि पृष्ठभूमि में एक मूल रूप से अनुकूलित (.cwasm) प्रारूप का उपयोग करता है।

संगतता

[!NOTE] TypeScript/JavaScript की Python की तुलना में व्यापक संगतता है क्योंकि यह मूल बाइंडिंग पर निर्भर नहीं करता है।

Python: अधिकांश मानक Python लाइब्रेरी पूरी तरह से काम करती हैं। C एक्सटेंशन का उपयोग करने वाले पैकेजों के लिए wasm32-wasi संकलित व्हील की आवश्यकता होती है। numpy और pandas जैसे कई लोकप्रिय पैकेज अभी तक एक शिप नहीं करते हैं, इसलिए वे सैंडबॉक्स के अंदर काम नहीं करेंगे। हालाँकि, आपका होस्ट कोड (run() का उपयोग करके) में पूर्ण Python इकोसिस्टम तक पहुँच है, जिसमें कोई भी pip पैकेज और मूल एक्सटेंशन शामिल हैं। देखें इन-कोड उपयोग

TypeScript/JavaScript: npm पैकेज और ES मॉड्यूल काम करते हैं। सामान्य Node.js बिल्ट-इन उपलब्ध हैं। यदि आपको किसी बिल्ट-इन में कोई समस्या आती है, तो एक समस्या खोलने में संकोच न करें।

योगदान

योगदान का स्वागत है!

विकास सेटअप

पूर्वापेक्षाएँ: Rust (नवीनतम स्थिर), Python 3.13+, Node.js 22+

git clone https://github.com/capsulerun/capsule.git
cd capsule

# CLI बनाएँ और इंस्टॉल करें
cargo install --path crates/capsule-cli

# Python SDK (editable install)
pip install -e crates/capsule-sdk/python

# TypeScript SDK (स्थानीय देव के लिए लिंक)
cd crates/capsule-sdk/javascript
npm install && npm run build && npm link

# फिर अपने प्रोजेक्ट में: npm link @capsule-run/sdk

योगदान कैसे करें

1. Fork रिपॉजिटरी
2. Create एक फीचर ब्रांच: git checkout -b feature/amazing-feature
3. Run tests: cargo test (केवल crates/capsule-cli या crates/capsule-core को संशोधित करने पर आवश्यक)
4. Open एक Pull Request

सहायता चाहिए? एक समस्या खोलें

श्रेय

Capsule इन ओपन सोर्स प्रोजेक्ट्स पर आधारित है:

• componentize-py – Python से WebAssembly Component संकलन
• jco – WebAssembly Components के लिए JavaScript टूलचेन
• wasmtime – WebAssembly रनटाइम
• WASI – WebAssembly सिस्टम इंटरफ़ेस

लाइसेंस

यह प्रोजेक्ट Apache License 2.0 के तहत लाइसेंस प्राप्त है - विवरण के लिए LICENSE फ़ाइल देखें।