cloudflare/sandbox-migrate-to-next

Migration von "stable" zur Sandbox SDK 1.0 Vorschau (@next)

Führe den Port durch. Befolge die Schritte in der richtigen Reihenfolge. Die Tiefe steckt in den Dokumenten – rufe die verlinkte Seite auf, wenn ein Schritt mehr Details benötigt.

Anleitung für Menschen: Migrieren · 1.0 Vorschau

Neue Projekte sollten mit @next (sandbox-next) beginnen, nicht mit diesem Skill. Tägliche stabile Arbeit → sandbox-stable. Bereinigung von veralteten APIs ohne Wechsel zu @next → zuerst Anleitung zur Abkündigung 2026 falls nötig.

Bestehende Apps sollten migrieren, wann immer möglich, damit sie bereit sind, wenn 1.0 zum stabilen Release wird. Erzwinge keinen Produktiv-Umstieg ohne Zustimmung des Benutzers.

Bevorzuge installierte @next-Typen und das Migrationsdokument gegenüber dem Gedächtnis.

Arbeitsablauf

1. Überprüfe die harten Regeln und die Ersetzungstabelle
2. Prüfe die Codebasis; liste Treffer und Zielstrukturen auf
3. Klärung mit dem Benutzer (Umstieg, Bridge, Python-Image, unklare Stellen)
4. Aktualisiere Paket, Image und Code
5. Validiere

Halte nach jedem Schritt an, der eine Benutzerentscheidung erfordert.

Harte Regeln

• Worker-Paket und Container-Image müssen auf der gleichen @next-Linie sein.
• Der Produktiv-Umstieg verwendet sofortiges Container-Rollout. Stabile und @next-Steuerprotokolle sind in beide Richtungen inkompatibel; schrittweises Rollout hinterlässt ein kaputtes Mischfenster. Laufende Container-Arbeiten können unterbrochen werden.
• Nach dem Umstieg bedeutet await sandbox.exec(...), dass der Prozess gestartet wurde, nicht dass der Befehl beendet ist.
• Argv wird unverändert übernommen (keine implizite Shell). Shell-Syntax benötigt ein explizites Shell-Binary.
• Prozess-Handles haben kein stdin → Terminals für interaktive Eingaben.
• Beobachtungs-timeout / AbortSignal brechen nur das Warten ab, nicht den Prozess.
• Keine einzelne Wiederholungsschleife für jeden Fehler.
• Keine erfundenen APIs (gitCheckout auf Kern, Prozess-Stdin, String-Exec-Abschlusshelfer).
• Selbst bereitgestellte Bridge bleibt auf stable (noch nicht Teil der Vorschau-Linie).

Ersetzungstabelle

Stable	@next
SANDBOX_TRANSPORT / transport / setTransport	Entfernen – nur RPC
await sandbox.exec("cmd") → gepuffertes Ergebnis	await sandbox.exec(argv) → Handle, dann output / waits
execStream / startProcess	Gleiches Handle: logs, waitFor*, kill
Standard-/benannte Sessions	Weg – cwd/env pro Start oder ein Shell-Skript
sandbox.terminal(request) / Session-Terminal	createTerminal + terminal.connect(request)
xterm sessionId	terminalId
Interpreter-Methoden auf Sandbox	withInterpreter → sandbox.interpreter.*
gitCheckout	argv git via exec
String-Kill-Signale	Nur numerisch
Dateien, Mounts, Backups, Ports, Tunnels, proxyToSandbox	Meist unverändert (Session-/Transport-Teile auf stable-Seiten ignorieren)

Tiefe: Migrieren · nach dem Port, tägliche Arbeit → sandbox-next

Prüfung

rg 'SANDBOX_TRANSPORT|transport:|setTransport|enableDefaultSession|createSession|getSession|deleteSession|execStream\(|startProcess\(|killProcess\(|sandbox\.terminal\(|sessionId|gitCheckout\(|SandboxTransport|ExecutionSession'

Auch: String exec(, cd gefolgt von einem späteren exec, nacktes createCodeContext / runCode auf Sandbox.

Klärung (bei Bedarf nachfragen)

• OK, die Produktion mit --containers-rollout=immediate umzustellen (laufende Prozesse/Terminals/Streams können stoppen)?
• Selbst bereitgestellte Bridge? Auf stable belassen.
• Python-Interpreter → -python-Image-Variante?
• Aufrufstellen, die nicht von der Tabelle abgedeckt werden?

Aktualisierung

Paket und Image

npm install @cloudflare/sandbox@next

FROM cloudflare/sandbox:next
# Python: cloudflare/sandbox:next-python

Gleicher Vorab-Release-Tag auf Worker und Image, wenn nicht auf dem floating next.

Code nach Bereich

Wende die Ersetzungen aus der Tabelle an. Implementiere jeden Bereich aus dem Dokument – nicht aus stable-Gewohnheiten:

Bereich	Dokument
Befehle / Handles / Waits	Prozesse · Prozesse API
cwd / env / Secrets	Umgebung · Ausgehender Traffic
Sessions entfernen	Migrieren · Lebenszyklus
Terminals	Terminals
Interpreter	Interpreter
Fehler	Fehler
Dauerhafter Job über Anfragen hinweg	Prozessausführung – Lebensdauer / Haltbarkeit

Befehle (Struktur):

// Vorher (stable)
const result = await sandbox.exec("npm test");

// Nachher (@next)
const process = await sandbox.exec(["/bin/bash", "-lc", "npm test"]);
const result = await process.output({ encoding: "utf8" });

const server = await sandbox.exec(["/bin/bash", "-lc", "npm run dev"], {
  cwd: "/workspace/app",
});
await server.waitForPort(3000, { timeout: 60_000 });
await server.kill(); // numerisch; Standard 15

Terminals (Struktur):

const terminal = await sandbox.createTerminal({ command: ["bash"], cwd: "/workspace" });
const t = await sandbox.getTerminal(terminal.id);
if (!t) return new Response("Terminal nicht mehr vorhanden", { status: 410 });
return t.connect(request, { cursor, cols, rows });

Interpreter (Struktur):

import { Sandbox as BaseSandbox } from "@cloudflare/sandbox";
import { withInterpreter } from "@cloudflare/sandbox/interpreter";

export class Sandbox extends BaseSandbox<Env> {
  interpreter = withInterpreter(this);
}

Git (Struktur):

const clone = await sandbox.exec(
  ["git", "clone", "--depth", "1", "--", repoUrl, "/workspace/repo"],
  { cwd: "/workspace" },
);
const result = await clone.output({ encoding: "utf8" });

Entferne Transport-Einstellungen vollständig. Entferne Session-APIs. Isoliere Benutzer mit getrennten Sandbox-IDs.

Umstieg bereitstellen

Zuerst Staging/Branch. Produktion ist ein Deploy von passendem Worker + Image:

npx wrangler deploy --containers-rollout=immediate

Lasse rollout_active_grace_period auf Standard 0 (oder setze es auf 0, wenn es erhöht wurde). Nach dem Umstieg sind vor dem Deploy existierende Prozess-/Terminal-IDs ungültig. Details: Migrieren · Container-Rollouts

Validierung

1. Lockfile + Dockerfile auf der gleichen @next-Linie
2. Typprüfung gegen @next
3. Rauchtest mit argv exec + output({ encoding: "utf8" })
4. Rauchtest mit langem Prozess / Terminal / Interpreter, falls verwendet
5. Fehler unterschieden: nicht verfügbar / unterbrochener RPC / veraltet / lokales Warten
6. Keine Live-Secrets in der Sandbox-Umgebung
7. Erneute Suche nach entfernten APIs
8. Produktion verwendete --containers-rollout=immediate

Dann tägliche Arbeit mit sandbox-next.

Warnsignale – anhalten und korrigieren

• Mischen von @next-Worker mit stabilem Image (oder umgekehrt)
• Schrittweises Container-Rollout für diesen Umstieg
• await exec als Befehlsabschluss behandeln
• Annahme, dass cd / Exporte über exec-Aufrufe hinweg bestehen bleiben
• Eine einzige Wiederholungsschleife für jeden Fehler
• Erfinden von gitCheckout, Prozess-Stdin oder undokumentierten APIs
• Beibehalten von vor dem Umstieg existierenden Prozess-/Terminal-IDs nach dem Deploy
• Erzwingen des Produktiv-Umstiegs ohne Zustimmung des Benutzers
• Platzieren von Live-Secrets in setEnvVars / env beim Start