← Sandbox SDK / sandbox / bridge

Referenční dokumentace HTTP API

Tato stránka dokumentuje všechny trasy, které zpřístupňuje sandbox bridge na stabilní šabloně.

Všechny routes pod /v1/sandbox/* a /v1/openapi.* vyžadují Bearer token:

Authorization: Bearer <SANDBOX_API_KEY>

Když SANDBOX_API_KEY není nastaven, autentizace se kvůli pohodlí při lokálním vývoji přeskočí. Před nasazením do produkce vždy nastavte tajnou hodnotu.

Bridge poskytuje vlastní dokumentaci API:

Obě trasy přijímají ověření pomocí hlavičky Bearer nebo ?token= parametr dotazu.

Při lokálním spuštění s npm run dev, otevřete http://localhost:8787/v1/openapi ve vašem prohlížeči a interaktivně prozkoumejte všechny koncové body.

/exec endpoint přijímá tělo požadavku ve formátu JSON:

{
  "argv": ["sh", "-lc", "echo hello"],
  "timeout_ms": 10000,
  "cwd": "/workspace"
}

Každý prvek argv pole je escapováno pomocí ANSI-C $'...' uvozovky, než se spojí do příkazu shellu. Tokeny, které obsahují pouze bezpečné znaky (A-Za-z0-9@%+=:,./-) se předávají beze změny. Všechny ostatní tokeny jsou obaleny do $'...' s escapovanými zpětnými lomítky, jednoduchými uvozovkami, znaky nového řádku, znaky návratu na začátek řádku a tabulátory. Tím se zabraňuje shell injection a zároveň zůstávají zachovány argumenty obsahující mezery, uvozovky nebo speciální znaky.

Odpověď je text/event-stream s následujícími typy událostí:

Cesta k souboru je zakódovaná v URL za /file/. Všechny cesty se musí přeložit v rámci /workspace. Pokusy o path traversal (například ../../etc/passwd) jsou odmítnuty.

/persist endpoint přijímá volitelný excludes parametr dotazu, seznam relativních cest oddělených čárkami, které se z archivu vyloučí.

/hydrate endpoint přijímá nezpracovaný tar payload o velikosti až 32 MiB.

/mount endpoint přijímá tělo požadavku ve formátu JSON. Podporovány jsou dva postupy:

Vynechte endpoint a předejte název R2 bindingu Workeru v bucket:

{
  "bucket": "MY_BUCKET",
  "mountPath": "/mnt/data",
  "options": {
    "readOnly": false,
    "prefix": "/subdir"
  }
}

Když options.endpoint je vynechán, bucket znamená název vazby R2 ve Workeru.

Pro explicitní připojení koncového bodu kompatibilního s S3 přidejte endpoint a volitelně credentials:

{
  "bucket": "my-r2-bucket",
  "mountPath": "/mnt/data",
  "options": {
    "endpoint": "https://ACCOUNT_ID.r2.cloudflarestorage.com",
    "readOnly": false,
    "prefix": "/subdir",
    "credentials": {
      "accessKeyId": "...",
      "secretAccessKey": "..."
    }
  }
}

Když endpoint je zadán, bucket znamená název vzdáleného bucketu. Přihlašovací údaje jsou volitelné pouze v tomto režimu: bridge je automaticky rozpozná ze secrets Workeru (R2_ACCESS_KEY_ID / R2_SECRET_ACCESS_KEY nebo AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY) pokud není uvedeno.

Relace v rámci sandboxu izolují pracovní adresář, proměnné prostředí a stav spouštění příkazů. Předejte Session-Id hlavičku na /exec, /file/*, a /pty požadavky, aby byly omezeny na danou relaci.

Pokud není Session-Id hlavička je poskytnuta, požadavky používají implicitní režim provádění sandboxu. Ve výchozím nastavení jde o výchozí relaci, ale SDK nakonfigurovaná s enableDefaultSession: false tyto implicitní operace spouštějte místo toho bez relace.

Parametry dotazu:

WebSocket přenáší binární rámce pro vstup a výstup terminálu a textové rámce JSON pro řídicí zprávy:

Warm pool předem spouští kontejnery sandboxu, takže nové relace naběhnou okamžitě. Nakonfigurujete ho pomocí proměnných prostředí v wrangler.jsonc:

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "vars": {
    "WARM_POOL_TARGET": "3",
    "WARM_POOL_REFRESH_INTERVAL": "10000"
  }
}

[vars]
WARM_POOL_TARGET = "3"           # Number of idle containers to keep warm (0 = disabled)
WARM_POOL_REFRESH_INTERVAL = "10000"  # Health-check interval in milliseconds

Cron trigger (* * * * *) po nasazení automaticky předehřeje fond. Nastavte WARM_POOL_TARGET na "0" (výchozí hodnota), aby se fond deaktivoval a předešlo se neočekávaným nákladům.

• Přehled Bridge : Co je bridge, jeho nasazení a příklady použití.
• Referenční dokumentace Sandbox API : Úplná referenční dokumentace metod Sandbox SDK.
• Zdrojový kód Bridge na GitHubu ↗ : Worker, Dockerfile a schéma OpenAPI.