INTEGRITY Dokumentace

← Sandbox SDK / sandbox / concepts

Architektura

Sandbox SDK umožňuje bezpečně spouštět nedůvěryhodný kód z vašich Workers. Kombinuje tři technologie Cloudflare a poskytuje tak bezpečné, stavové a izolované spouštění:

Přehled architektury

flowchart TB
    accTitle: Sandbox SDK Architecture
    accDescr: Three-layer architecture showing how Cloudflare Sandbox SDK combines Workers, Durable Objects, and Containers for secure code execution

    subgraph UserSpace["<b>Your Worker</b>"]
        Worker["Application code using the methods exposed by the Sandbox SDK"]
    end

    subgraph SDKSpace["<b>Sandbox SDK Implementation</b>"]
        DO["Sandbox Durable Object routes requests & maintains state"]
        Container["Isolated Ubuntu container executes untrusted code safely"]

        DO -->|HTTP API| Container
    end

    Worker -->|RPC call via the Durable Object stub returned by `getSandbox`| DO

    style UserSpace fill:#fff8f0,stroke:#f6821f,stroke-width:2px
    style SDKSpace fill:#f5f5f5,stroke:#666,stroke-width:2px,stroke-dasharray: 5 5
    style Worker fill:#ffe8d1,stroke:#f6821f,stroke-width:2px
    style DO fill:#dce9f7,stroke:#1d8cf8,stroke-width:2px
    style Container fill:#d4f4e2,stroke:#17b26a,stroke-width:2px

Vrstva 1: Klientský SDK

API určené pro vývojáře, které používáte ve svých Workerech:

import { getSandbox } from "@cloudflare/sandbox";

const sandbox = getSandbox(env.Sandbox, "my-sandbox");
const result = await sandbox.exec("python script.py");

Účel: Poskytuje přehledné a typově bezpečné rozhraní TypeScript pro všechny operace se sandboxem.

Vrstva 2: Durable Object

Spravuje životní cyklus sandboxu a směrování:

export class Sandbox extends DurableObject<Env> {
	// Extends Cloudflare Container for isolation
	// Routes requests between client and container
	// Manages preview URLs and state
}

Účel: Poskytuje trvalé, stavové instance sandboxu s jedinečnou identitou.

Proč Durable Objects:

Vrstva 3: Container Runtime

Spouští kód izolovaně s plnou funkcionalitou Linuxu.

Účel: Bezpečně spouští nedůvěryhodný kód.

Proč kontejnery:

Komunikační přenosové režimy

SDK podporuje tři přenosové protokoly pro komunikaci mezi Durable Object a kontejnerem:

HTTP transport (výchozí)

Každá metoda SDK provede samostatný požadavek HTTP na API kontejneru. Je to jednoduché, spolehlivé a vyhovuje většině případů užití.

// Default behavior - uses HTTP
const sandbox = getSandbox(env.Sandbox, "my-sandbox");
await sandbox.exec("python script.py");

Transport RPC

Multiplexuje všechna volání SDK přes jedno trvalé spojení. Vyhýbá se tak limity subrequestů při provádění mnoha souběžných operací.

RPC transport povolíte nastavením SANDBOX_TRANSPORT proměnnou v konfiguraci svého Workeru:

{
	"vars": {
		"SANDBOX_TRANSPORT": "rpc"
	},
}
[vars]
SANDBOX_TRANSPORT = "rpc"

WebSocket transport

WebSocket transport je zastaralý. Pro nové aplikace použijte RPC transport.

Vrstva přenosu je pro kód vaší aplikace transparentní: všechny metody SDK fungují stejně bez ohledu na typ přenosu. Podrobnosti o tom, kdy použít který typ přenosu, a příklady konfigurace najdete v Režimy transportu.

Tok požadavku

Když spustíte příkaz:

await sandbox.exec("python script.py");

Průběh HTTP transportu:

  1. Client SDK ověří parametry a odešle požadavek HTTP na Durable Object
  2. Durable Object ověří a přepošle požadavek HTTP do kontejneru
  3. Runtime kontejneru ověří vstupy, spustí příkaz a zachytí výstup
  4. Odpověď se vrací zpět všemi vrstvami se správnou transformací chyb

Průběh RPC transportu:

  1. Client SDK ověří parametry a odešle požadavek na Durable Object
  2. Durable Object udržuje trvalé připojení ke kontejneru a multiplexuje souběžné požadavky
  3. Runtime kontejneru převádí zprávy RPC na zpracování požadavků a odpovědí ve stylu HTTP
  4. Odpověď se vrací zpět přes stejné připojení se správnou transformací chyb

Durable Object naváže trvalé připojení ke kontejneru při prvním volání SDK a dál ho využívá pro všechny další operace, čímž se snižuje režie u často opakovaných operací.