Migration stable → Sandbox SDK 1.0 preview (@next)

Effectuez le portage. Suivez les étapes dans l'ordre. Les détails vivent dans la documentation—consultez la page liée quand une étape nécessite des précisions.

Guide humain : Migrate · 1.0 preview

Les nouveaux projets doivent commencer sur @next (sandbox-next), pas cette skill. Le travail quotidien stable → sandbox-stable. Nettoyage des API dépréciées sans migration vers @next → consultez d'abord le guide de dépréciation 2026 si nécessaire.

Les applications existantes doivent migrer quand vous pouvez, pour être prêtes quand 1.0 devient la version stable. Ne forcez pas le passage en production sans l'accord de l'utilisateur.

Préférez les types @next installés et la documentation de migration à la mémoire.

Workflow

1. Examinez les règles strictes et la table de remplacement
2. Auditez la codebase ; listez les correspondances et les formes cibles
3. Clarifiez avec l'utilisateur (cutover, bridge, image Python, sites peu clairs)
4. Mettez à jour le package, l'image et le code
5. Validez

Arrêtez après toute étape qui nécessite une décision de l'utilisateur.

Règles strictes

• Le package Worker et l'image conteneur doivent être sur la même ligne @next.
• Le cutover en production utilise un déploiement de conteneur immédiat. Les protocoles de contrôle stable et @next sont incompatibles dans les deux sens ; un déploiement progressif laisse une fenêtre mixte cassée. Le travail en conteneur en vol peut s'arrêter.
• Après le cutover, await sandbox.exec(...) signifie processus lancé, 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 stdin → terminaux pour l'entrée interactive.
• L'observation timeout / AbortSignal annule l'attente seulement, pas le processus.
• Pas de boucle de retry unique pour chaque erreur.
• N'inventez pas d'APIs (gitCheckout sur core, stdin du processus, helper de complétion string-exec).
• Le bridge auto-déployé reste sur stable (pas encore partie de la ligne preview).

Table de remplacement

Détails : Migrate · 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.

Clarifier (demandez quand nécessaire)

• OK de faire le cutover en production avec --containers-rollout=immediate (les processus/terminaux/flux en direct peuvent s'arrêter) ?
• Bridge auto-déployé ? Laissez sur stable.
• Interpréteur Python → variante d'image -python ?
• Des sites d'appel non couverts par la table ?

Mise à jour

Package et image

npm install @cloudflare/sandbox@next

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

Même tag prérelease sur Worker et image quand pas sur next flottant.

Code par domaine

Appliquez les remplaçants de la table. Pour chaque domaine, implémentez depuis la doc—pas depuis les habitudes stable :

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ériquement ; 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 gone", { 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 entièrement les paramètres de transport. Supprimez les APIs de session. Isolez les utilisateurs avec des IDs sandbox séparés.

Cutover du déploiement

Staging/branche d'abord. Production est un seul déploiement de Worker + image correspondants :

npx wrangler deploy --containers-rollout=immediate

Laissez rollout_active_grace_period au défaut 0 (ou mettez 0 si augmenté). Après le cutover, les IDs de processus/terminal pré-déploiement sont invalides. Détails : Migrate · Container rollouts

Valider

1. Lockfile + Dockerfile sur la même ligne @next
2. Vérification des types contre @next
3. Smoke argv exec + output({ encoding: "utf8" })
4. Smoke long process / terminal / interpreter si utilisé
5. Erreurs distinguées : unavailable / interrupted-RPC / stale / local wait
6. Pas de secrets en direct dans l'env sandbox
7. Grep à nouveau pour les APIs supprimées
8. Production a utilisé --containers-rollout=immediate

Puis le travail quotidien utilise sandbox-next.

Drapeaux rouges — arrêtez et corrigez

• Mélanger Worker @next avec image stable (ou inversement)
• Déploiement de conteneur progressif pour ce cutover
• Traiter await exec comme une complétion de commande
• Supposer que cd / exports persistent entre appels exec
• Un wrapper retry pour chaque erreur
• Inventer gitCheckout, stdin du processus, ou APIs non documentées
• Garder les IDs de processus/terminal pré-cutover après déploiement
• Forcer le cutover en production sans accord de l'utilisateur
• Mettre des secrets en direct dans setEnvVars / launch env