cloudflare/sandbox-migrate-to-next

Migrar de estable a vista previa del SDK 1.0 de Sandbox (@next)

Realiza la migración. Sigue los pasos en orden. La profundidad está en los documentos—consulta la página enlazada cuando un paso necesite detalle.

Guía para humanos: Migrar · Vista previa 1.0

Los proyectos nuevos deben comenzar en @next (sandbox-next), no en esta skill. El trabajo estable del día a día → sandbox-stable. La limpieza de APIs obsoletas sin migrar a @next → guía de obsolescencia 2026 primero si es necesario.

Las aplicaciones existentes deben migrar cuando puedas, para que estés listo cuando la versión 1.0 se convierta en la estable. No fuerces el corte de producción sin el acuerdo del usuario.

Prefiere los tipos instalados de @next y el documento de migración antes que la memoria.

Flujo de trabajo

1. Revisa las reglas estrictas y el mapa de reemplazo
2. Audita el código base; lista las coincidencias y las formas destino
3. Aclara con el usuario (corte, puente, imagen de Python, sitios poco claros)
4. Actualiza paquete, imagen y código
5. Valida

Detente después de cualquier paso que necesite una decisión del usuario.

Reglas estrictas

• El paquete del Worker y la imagen del contenedor deben estar en la misma línea @next.
• El corte de producción utiliza el despliegue inmediato del contenedor. Los protocolos de control de estable y @next son incompatibles en ambos sentidos; un despliegue gradual deja una ventana mixta rota. El trabajo de contenedores en curso puede detenerse.
• Después del corte, await sandbox.exec(...) significa proceso iniciado, no comando finalizado.
• Argv se pasa tal cual (sin shell implícito). La sintaxis de shell necesita un binario de shell explícito.
• Los manejos de proceso no tienen stdin → terminales para entrada interactiva.
• El timeout / AbortSignal de observación cancelan solo la espera, no el proceso.
• No hay un bucle de reintento único para cada error.
• No inventes APIs (gitCheckout en el núcleo, stdin de proceso, helper de finalización de string-exec).
• El puente autodesplegado permanece en estable (aún no forma parte de la línea de vista previa).

Mapa de reemplazo

Estable	@next
SANDBOX_TRANSPORT / transport / setTransport	Eliminar — solo RPC
await sandbox.exec("cmd") → resultado almacenado en búfer	await sandbox.exec(argv) → manejo, luego output / esperas
execStream / startProcess	Mismo manejo: logs, waitFor*, kill
Sesiones por defecto / nombradas	Desaparecidas — cwd/env por lanzamiento, o un script de shell
sandbox.terminal(request) / sesión terminal	createTerminal + terminal.connect(request)
sessionId de xterm	terminalId
Métodos de intérprete en Sandbox	withInterpreter → sandbox.interpreter.*
gitCheckout	argv git mediante exec
Señales de kill en string	Solo numéricas
Archivos, montajes, copias de seguridad, puertos, túneles, proxyToSandbox	Mayormente sin cambios (ignora partes de sesión/transporte en páginas estables)

Profundidad: Migrar · después de la migración, trabajo diario → sandbox-next

Auditar

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

También: string exec(, cd seguido de un exec, createCodeContext / runCode sin parámetros en Sandbox.

Aclarar (pregunta cuando sea necesario)

• ¿Está bien cortar producción con --containers-rollout=immediate (los procesos/terminales/flujos en vivo pueden detenerse)?
• ¿Puente autodesplegado? Déjalo en estable.
• ¿Intérprete de Python → variante de imagen -python?
• ¿Puntos de llamada no cubiertos por el mapa?

Actualizar

Paquete e imagen

npm install @cloudflare/sandbox@next

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

Misma etiqueta de prerelease en el Worker y la imagen cuando no esté en next flotante.

Código por área

Aplica los reemplazos del mapa. Para cada área, implementa desde el documento—no desde los hábitos estables:

Área	Documento
Comandos / manejos / esperas	Procesos · API de procesos
cwd / env / secretos	Entorno · Tráfico saliente
Eliminar sesiones	Migrar · Ciclo de vida
Terminales	Terminales
Intérprete	Intérprete
Errores	Errores
Trabajo durable entre solicitudes	Ejecución de procesos — vida útil / durabilidad

Comandos (forma):

// Antes (estable)
const result = await sandbox.exec("npm test");

// Despué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érico; predeterminado 15

Terminales (forma):

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

Intérprete (forma):

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

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

Git (forma):

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

Elimina por completo los ajustes de transporte. Elimina las APIs de sesión. Aísla a los usuarios con IDs de sandbox separados.

Corte de despliegue

Primero staging/rama. La producción es un despliegue de Worker + imagen coincidentes:

npx wrangler deploy --containers-rollout=immediate

Deja rollout_active_grace_period en su valor predeterminado 0 (o establécelo en 0 si se incrementó). Después del corte, los IDs de procesos/terminales previos al despliegue son inválidos. Detalles: Migrar · Despliegues de contenedores

Validar

1. Archivo de bloqueo + Dockerfile en la misma línea @next
2. Verificación de tipos contra @next
3. Prueba de argv exec + output({ encoding: "utf8" })
4. Prueba de proceso largo / terminal / intérprete si se usa
5. Errores distinguidos: no disponible / RPC interrumpido / obsoleto / espera local
6. Sin secretos vivos en el entorno de sandbox
7. Grep nuevamente para APIs eliminadas
8. Producción usó --containers-rollout=immediate

Luego, el trabajo diario usa sandbox-next.

Señales de alerta — detente y corrige

• Mezclar Worker @next con imagen estable (o viceversa)
• Despliegue gradual de contenedores para este corte
• Tratar await exec como finalización de comando
• Asumir que cd / exportaciones persisten entre llamadas exec
• Un envoltorio de reintento único para cada error
• Inventar gitCheckout, stdin de proceso o APIs no documentadas
• Mantener IDs de procesos/terminales previos al corte después del despliegue
• Forzar el corte de producción sin el acuerdo del usuario
• Poner secretos vivos en setEnvVars / env de lanzamiento