INTEGRITY Dokumentace

← Sandbox SDK / sandbox / concepts

Životní cyklus sandboxu

Sandbox je izolované prostředí pro spouštění kódu. Každý sandbox:

Stavy životního cyklu

Vytvoření

Sandbox se vytvoří při prvním odkazu na jeho ID:

const sandbox = getSandbox(env.Sandbox, "user-123");
await sandbox.exec('echo "Hello"'); // First request creates sandbox

Aktivní

Kontejner sandboxu běží a zpracovává požadavky. Veškerý stav zůstává dostupný: soubory, běžící procesy, relace shellu i proměnné prostředí.

Nečinné

Po období nečinnosti (výchozí hodnota 10 minut, lze nastavit pomocí sleepAfter), kontejner se zastaví, aby uvolnil prostředky. Jakmile přijde další požadavek, spustí se nový kontejner. Veškerý předchozí stav se ztratí a prostředí se vrátí do počátečního stavu.

Poznámka: Kontejnery s keepAlive: true nikdy nepřejdou do nečinného stavu. Automaticky odesílají heartbeat pingy každých 30 sekund, aby se zabránilo odstranění.

Zničení

Sandboxy jsou buď explicitně zničeny, nebo automaticky vyčištěny:

await sandbox.destroy();
// All files, processes, and state deleted permanently

Životnost a stav kontejneru

Stav sandboxu existuje pouze po dobu, kdy je kontejner aktivní. Pochopení tohoto principu je klíčové pro vytváření spolehlivých aplikací.

Dokud je kontejner aktivní (obvykle minuty až hodiny aktivity):

Když se kontejner zastaví (kvůli nečinnosti nebo explicitnímu zrušení):

Další požadavek vytvoří nový kontejner s čistým prostředím.

Strategie pojmenování

Sandboxy pro jednotlivé uživatele

const sandbox = getSandbox(env.Sandbox, `user-${userId}`);

Tento vzor použijte pro interaktivní prostředí, playgroundy a notebooky, kde se každý uživatel vrací do svého vlastního aktivního pracovního prostoru.

Sandboxy pro jednotlivé relace

const sessionId = `session-${Date.now()}-${Math.random()}`;
const sandbox = getSandbox(env.Sandbox, sessionId);
// Later:
await sandbox.destroy();

Tento vzor použijte pro jednorázové spuštění, CI/CD a testy, které potřebují čisté prostředí.

Sandboxy pro jednotlivé úlohy

const sandbox = getSandbox(env.Sandbox, `build-${repoName}-${commit}`);

Idempotentní operace s jasným mapováním úloh na sandboxy. Vhodné pro buildy, pipeline a úlohy na pozadí.

Směrování požadavků

První požadavek na sandbox určuje jeho geografickou polohu. Další požadavky se směrují do stejné lokality.

Pro globální aplikace:

Správa životního cyklu

Kdy zničit

try {
	const sandbox = getSandbox(env.Sandbox, sessionId);
	await sandbox.exec("npm run build");
} finally {
	await sandbox.destroy(); // Clean up temporary sandboxes
}

Zničit když: Relace končí, úkol je dokončen, zdroje již nejsou potřeba

Neničit: Osobní prostředí, dlouhodobě běžící služby

Správa kontejnerů keepAlive

Kontejnery s keepAlive: true vyžadují explicitní správu, protože jim automaticky nevyprší platnost:

const sandbox = getSandbox(env.Sandbox, 'persistent-task', {
  keepAlive: true
});

// Later, when done with long-running work
await sandbox.setKeepAlive(false); // Allow normal timeout behavior
// Or explicitly destroy:
await sandbox.destroy();

Zpracování restartů kontejneru

Kontejnery se po nečinnosti nebo selhání restartují. Navrhněte aplikaci tak, aby zvládla ztrátu stavu:

// Check if required files exist before using them
const files = await sandbox.listFiles("/workspace");
if (!files.includes("data.json")) {
	// Reinitialize: container restarted and lost previous state
	await sandbox.writeFile("/workspace/data.json", initialData);
}

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

Kompatibilita verzí

SDK automaticky kontroluje, zda verze vašeho npm balíčku odpovídá verzi image Docker kontejneru. Nesoulad verzí může způsobit, že funkce přestanou fungovat nebo se budou chovat neočekávaně.

Co se stane:

Kdy se mohou zobrazit varování:

Jak to opravit: Aktualizujte svůj Dockerfile tak, aby odpovídal verzi vašeho npm balíčku. Pokud například používáte @cloudflare/[email protected]:

# Default image (JavaScript/TypeScript)
FROM docker.io/cloudflare/sandbox:0.7.0

# Or Python image if you need Python support
FROM docker.io/cloudflare/sandbox:0.7.0-python

Viz Referenční dokumentace Dockerfile pro podrobnosti o variantách image a rozšiřování základního image.

Osvědčené postupy