‎@eqvps/sdk کن رن ٹائمز پر چلتا ہے؟

Node.js 18 اور نئے، Deno اور Bun۔ اس کی کوئی ڈیپنڈنسی نہیں اور یہ بلٹ اِن fetch استعمال کرتا ہے، اس لیے براؤزر میں بھی چلتا ہے، مگر اپنا اکاؤنٹ ٹوکن فرنٹ اینڈ کوڈ میں نہ رکھیں۔

اگر میری ایپ TypeScript میں ہے تو کیا سینڈباکس Python چلا سکتا ہے؟

جی ہاں۔ آپ کی ایپ کی زبان اور سینڈباکس کے کوڈ کی زبان کا آپس میں کوئی تعلق نہیں۔ run میں language کی قیمت python، node یا bash ہو سکتی ہے، اور exec کوئی بھی shell کمانڈ چلاتا ہے۔

کیسے یقینی بناؤں کہ سینڈباکس حذف ہو جائے؟

Sandbox.with(options, fn) استعمال کریں؛ fn ختم ہونے یا غلطی پھینکنے پر یہ سینڈباکس حذف کر دیتا ہے۔ TypeScript 5.2 یا نئے میں await using sb = await Sandbox.create() بھی لکھ سکتے ہیں۔

کوڈ ناکام ہو تو run کیا لوٹاتا ہے؟

صفر کے علاوہ exit_code اور stderr میں غلطی والا ExecResult۔ کچھ پھینکا نہیں جاتا۔ exceptions صرف API غلطیوں پر آتی ہیں، جیسے غلط ٹوکن یا خالی بیلنس۔

پانچ منٹ میں JavaScript کوڈ سینڈباکس SDK

‎@eqvps/sdk انسٹال کریں، Node.js، Deno یا Bun سے Firecracker سینڈباکس چلائیں، اس میں Python، Node اور shell کوڈ چلائیں، فائلیں بھیجیں اور لمبے کام کا آؤٹ پٹ لائیو دیکھیں۔ ہر لائن کوڈ کے ساتھ چھ مرحلے۔

یہ گائیڈ JavaScript یا TypeScript سے سینڈباکس چلاتی ہے۔ آپ ایک الگ تھلگ Firecracker microVM چلائیں گے، تین زبانوں میں کوڈ چلائیں گے، فائلیں بھیجیں گے اور لمبے کام کا آؤٹ پٹ دیکھیں گے۔ ہر مرحلہ ایک چھوٹا کوڈ کا ٹکڑا ہے۔

آپ کو Node.js 18+‎ (یا Deno، یا Bun) اور ایک EQVPS اکاؤنٹ چاہیے۔

1. ٹوکن لیں

SDK عام اکاؤنٹ ٹوکن سے تصدیق کرتا ہے۔ اسے ڈیش بورڈ، API یا MCP سرور سے کیسے لیں، یہ اکاؤنٹ جوڑنا صفحے پر ہے۔

export EQVPS_API_KEY="your-token"

بغیر بیلنس والا نیا اکاؤنٹ جب پہلی بار سینڈباکس بناتا ہے تو اسے $1 سینڈباکس کریڈٹ ملتا ہے۔ یہ اس گائیڈ کے لیے کئی بار کافی ہے۔

2. SDK انسٹال کریں

npm i @eqvps/sdk

مثالیں ES ماڈیولز اور ٹاپ لیول await استعمال کرتی ہیں۔ انہیں .mjs فائلوں کے طور پر محفوظ کریں، یا .ts کے طور پر محفوظ کرکے npx tsx سے چلائیں۔

3. سینڈباکس چلائیں اور کوڈ چلائیں

import { Sandbox } from "@eqvps/sdk";

await Sandbox.with({ tariff: "small" }, async (sb) => {
  console.log(sb.id);
  const r = await sb.run("import platform; print(platform.python_version())");
  console.log(r.exit_code, r.stdout);
});

آؤٹ پٹ سینڈباکس کی id (sb_ اور مزید 24 حروف) ہے، پھر 0 3.12.x۔ callback ختم ہونے پر Sandbox.with سینڈباکس حذف کر دیتا ہے، چاہے وہ غلطی پھینکے۔

ڈیفالٹ زبان Python ہے۔ باقی دو بس ایک آپشن کے فاصلے پر ہیں:

await Sandbox.with({}, async (sb) => {
  const js = await sb.run("console.log(process.version)", { language: "node" });
  const sh = await sb.run("uname -r && nproc", { language: "bash" });
  console.log(js.stdout, sh.stdout);
});

ناکام ہونے والی اسکرپٹ کچھ نہیں پھینکتی۔ r.ok چیک کریں، جو تب true ہوتا ہے جب exit_code صفر ہو اور کمانڈ ٹائم آؤٹ تک نہ پہنچی ہو۔

4. shell کمانڈز اور پیکیج

exec shell اسٹرنگ یا argv ارے لیتا ہے۔ سینڈباکس انٹرنیٹ سے جڑ سکتا ہے، اس لیے npm اور pip انسٹال کام کرتے ہیں:

await Sandbox.with({ tariff: "small" }, async (sb) => {
  await sb.exec("mkdir -p /root/app && cd /root/app && npm init -y && npm i lodash", { timeout: 55 });
  const r = await sb.exec(["node", "-e", "console.log(require('/root/app/node_modules/lodash').VERSION)"]);
  console.log(r.stdout);
});

ایک ہم وقت کال زیادہ سے زیادہ 55 سیکنڈ چلتی ہے۔ اس سے لمبا کچھ بھی بیک گراؤنڈ ٹاسک میں جاتا ہے (مرحلہ 6)۔

5. فائلیں

await Sandbox.with({}, async (sb) => {
  await sb.upload("/root/input.json", JSON.stringify({ values: [3, 5, 8] }));
  await sb.run("import json; d = json.load(open('/root/input.json')); open('/root/out.txt', 'w').write(str(sum(d['values'])))");
  console.log(await sb.downloadText("/root/out.txt"));   // 16
});

upload اسٹرنگ یا Uint8Array لیتا ہے۔ download ایک Uint8Array لوٹاتا ہے، downloadText اسٹرنگ۔ ایک ٹرانسفر 5 MB تک محدود ہے۔

6. لائیو آؤٹ پٹ والے لمبے کام

await Sandbox.with({ tariff: "standard" }, async (sb) => {
  const task = await sb.exec("for i in 1 2 3 4 5; do echo step $i; sleep 20; done", { background: true });
  const res = await task.wait({ onOutput: (out) => process.stdout.write(out) });
  console.log(res.state, res.exit_code);   // done 0
});

ٹاسک فوراً لوٹ آتا ہے اور اس میں 55 سیکنڈ کی حد نہیں۔ wait ڈیفالٹ طور پر ہر 2 سیکنڈ میں چیک کرتا ہے (pollIntervalMs سے بدلیں)۔ task.kill() اسے روکتا ہے؛ sb.task(id) کسی دوسرے پروسیس سے دوبارہ جڑتا ہے۔

غلطیاں

import { Sandbox, InsufficientBalanceError, RateLimitError } from "@eqvps/sdk";

try {
  await Sandbox.with({}, async (sb) => console.log((await sb.run("print(1)")).stdout));
} catch (e) {
  if (e instanceof InsufficientBalanceError) console.log("Top up the balance");
  else if (e instanceof RateLimitError) console.log("Busy, retry in", e.retryAfter);
  else throw e;
}

سرور Retry-After بھیجے تو SDK خود 429 اور 503 کو تین بار تک دوبارہ آزماتا ہے۔ سب سے عام 429 تب آتا ہے جب ایک اکاؤنٹ پر بیک وقت دو سے زیادہ کمانڈز چلتی ہیں۔ تمام کلاسز SDK حوالہ میں ہیں۔

اس گائیڈ کا خرچ

ہر مثال چند سیکنڈ چلی اور کم از کم 60 سیکنڈ کے حساب سے بل ہوئی: small پر $0.00055، standard پر $0.0011۔ مرحلہ 6 کا کام standard پر تقریباً 100 سیکنڈ چلا، لگ بھگ $0.002۔ سب مل کر ایک سینٹ سے بہت کم۔ مکمل قیمتوں کی فہرست سینڈباکس کی حدیں اور بلنگ میں ہے۔

آگے کیا

یہی Python میں: 5 منٹ میں سینڈباکس کے لیے Python SDK۔
ایک ماڈل جوڑیں اور اسے اپنا کوڈ خود چلانے دیں: سینڈباکس میں آپ کا پہلا ایجنٹ ٹاسک۔
ٹیرف اور $1 کا ٹرائل: سینڈباکس صفحہ۔

5 منٹ میں سینڈباکس کے لیے TypeScript SDK: npm i @eqvps/sdk سے پہلے رن تک