cloudflare/sandbox-migrate-to-next

Migrer de stable vers l'aperçu SDK 1.0 Sandbox (@next)

Effectuez le portage. Suivez les étapes dans l'ordre. Les détails se trouvent dans la documentation—récupérez la page liée lorsqu'une étape a besoin de détails.

Guide humain : Migrer · Aperçu 1.0

Les nouveaux projets doivent démarrer sur @next (sandbox-next), pas cette compétence. Travail quotidien stable → sandbox-stable. Nettoyage d'API dépréciée sans passer à @next → Guide de dépréciation 2026 d'abord si nécessaire.

Les applications existantes doivent migrer quand vous le pouvez, afin d'être prêtes lorsque la version 1.0 deviendra la version stable. Ne forcez pas la bascule de production sans l'accord de l'utilisateur.

Privilégiez les types @next installés et le document de migration plutôt que la mémoire.

Flux de travail

1. Examinez les règles strictes et la carte de remplacement
2. Auditez le codebase ; listez les correspondances et les formes cibles
3. Clarifiez avec l'utilisateur (bascule, pont, image Python, sites flous)
4. Mettez à niveau le paquet, l'image et le code
5. Validez

Arrêtez-vous après toute étape nécessitant une décision de l'utilisateur.

Règles strictes

• Le paquet Worker et l'image conteneur doivent être sur la même ligne @next.
• La bascule de production utilise un déploiement immédiat du conteneur. Les protocoles de contrôle stable et @next sont incompatibles dans les deux sens ; un déploiement progressif laisse une fenêtre de panachage cassée. Les travaux de conteneur en cours peuvent s'arrêter.
• Après la bascule, await sandbox.exec(...) signifie processus démarré, pas commande terminée.
• Argv est tel quel (pas de shell implicite). La syntaxe shell nécessite un binaire shell explicite.
• Les handles de processus n'ont pas d'entrée standard → terminaux pour l'entrée interactive.
• Le timeout / AbortSignal d'observation annulent l'attente seulement, pas le processus.
• Pas de boucle de réessai unique pour chaque erreur.
• N'inventez pas d'API (gitCheckout sur le noyau, entrée standard de processus, helper de complétion d'exécution de chaîne).
• Le pont auto-déployé reste sur la version stable (pas encore inclus dans la ligne d'aperçu).

Carte de remplacement

Stable	@next
SANDBOX_TRANSPORT / transport / setTransport	Supprimer — RPC uniquement
await sandbox.exec("cmd") → résultat mis en mémoire tampon	await sandbox.exec(argv) → handle, puis output / attentes
execStream / startProcess	Même handle : logs, waitFor*, kill
Sessions par défaut / nommées	Disparues — cwd/env par lancement, ou un script shell
sandbox.terminal(request) / terminal de session	createTerminal + terminal.connect(request)
sessionId xterm	terminalId
Méthodes d'interpréteur sur Sandbox	withInterpreter → sandbox.interpreter.*
gitCheckout	argv git via exec
Signaux de kill par chaîne	Numériques uniquement
Fichiers, montages, sauvegardes, ports, tunnels, proxyToSandbox	Principalement inchangés (ignorez les parties session/transport sur les pages stables)

Détails : Migrer · après le portage, travail quotidien → sandbox-next

Audit

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

Aussi : exec( en chaîne, cd puis un exec ultérieur, createCodeContext / runCode nu sur Sandbox.

Clarifiez (demandez quand nécessaire)

• OK pour basculer la production avec --containers-rollout=immediate (les processus/terminaux/flux en direct peuvent s'arrêter) ?
• Pont auto-déployé ? Laissez sur stable.
• Interpréteur Python → variante d'image -python ?
• Sites d'appel non couverts par la carte ?

Mise à niveau

Paquet et image

npm install @cloudflare/sandbox@next

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

Même tag de préversion sur le Worker et l'image lorsqu'ils ne sont pas sur next flottant.

Code par zone

Appliquez les remplacements de la carte. Pour chaque zone, implémentez à partir de la documentation—pas à partir des habitudes stables :

Zone	Doc
Commandes / handles / attentes	Processus · API Processus
cwd / env / secrets	Environnement · Trafic sortant
Supprimer les sessions	Migrer · Cycle de vie
Terminaux	Terminaux
Interpréteur	Interpréteur
Erreurs	Erreurs
Tâche durable entre requêtes	Exécution de processus — durée de vie / durabilité

Commandes (forme) :

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

// Après (@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(); // numérique ; défaut 15

Terminaux (forme) :

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

Interpréteur (forme) :

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

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

Git (forme) :

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

Supprimez complètement les paramètres de transport. Supprimez les API de session. Isolez les utilisateurs avec des ID de sandbox séparés.

Bascule de déploiement

D'abord un environnement de préproduction / branche. La production est un déploiement du Worker + image correspondants :

npx wrangler deploy --containers-rollout=immediate

Laissez rollout_active_grace_period à la valeur par défaut 0 (ou mettez 0 si elle a été augmentée). Après la bascule, les ID de processus/terminal pré-déploiement sont invalides. Détails : Migrer · Déploiements de conteneurs

Validez

1. Fichier de verrouillage + Dockerfile sur la même ligne @next
2. Vérification de types avec @next
3. Test rapide argv exec + output({ encoding: "utf8" })
4. Test rapide d'un processus long / terminal / interpréteur si utilisé
5. Erreurs distinguées : indisponible / RPC interrompu / obsolète / attente locale
6. Pas de secrets en direct dans l'environnement sandbox
7. Cherchez à nouveau les API supprimées
8. La production a utilisé --containers-rollout=immediate

Ensuite, le travail quotidien utilise sandbox-next.

Drapeaux rouges — arrêtez et corrigez

• Mélanger un Worker @next avec une image stable (ou l'inverse)
• Déploiement progressif de conteneur pour cette bascule
• Considérer await exec comme une fin de commande
• Supposer que cd / les exports persistent entre les appels exec
• Un seul wrapper de réessai pour chaque erreur
• Inventer gitCheckout, entrée standard de processus ou API non documentées
• Conserver des ID de processus/terminal pré-bascule après le déploiement
• Forcer la bascule de production sans l'accord de l'utilisateur
• Mettre des secrets en direct dans setEnvVars / env de lancement