cloudflare/sandbox-migrate-to-next

Migrar estável → Prévia do SDK 1.0 do Sandbox (@next)

Realize a migração. Siga as etapas em ordem. A profundidade está na documentação — acesse a página vinculada quando uma etapa precisar de detalhes.

Guia humano: Migrar · Prévia 1.0

Novos projetos devem começar em @next (sandbox-next), não esta habilidade. Trabalho estável do dia a dia → sandbox-stable. Limpeza de APIs obsoletas sem migrar para @next → guia de descontinuação 2026 primeiro, se necessário.

Os aplicativos existentes devem migrar quando possível, para que estejam prontos quando a versão 1.0 se tornar a versão estável. Não force a migração em produção sem a concordância do usuário.

Prefira os tipos @next instalados e o documento de migração em vez da memória.

Fluxo de trabalho

1. Revise as regras rígidas e o mapa de substituições
2. Audite o código; liste ocorrências e formatos alvo
3. Esclareça com o usuário (migração, bridge, imagem Python, sites pouco claros)
4. Atualize pacote, imagem e código
5. Valide

Pare após qualquer etapa que precise de uma decisão do usuário.

Regras rígidas

• O pacote Worker e a imagem do container devem estar na mesma linha @next.
• A migração de produção usa rollout imediato do container. Os protocolos de controle estável e @next são incompatíveis em ambos os sentidos; rollout gradual deixa uma janela mista quebrada. Trabalho em andamento no container pode parar.
• Após a migração, await sandbox.exec(...) significa processo iniciado, não comando finalizado.
• Argv é como está (sem shell implícito). A sintaxe de shell precisa de um binário de shell explícito.
• Handles de processo não têm stdin → terminais para entrada interativa.
• O timeout / AbortSignal da observação cancelam apenas a espera, não o processo.
• Nenhum loop de repetição único para todos os erros.
• Não invente APIs (gitCheckout no core, stdin de processo, auxiliar de conclusão de execução de string).
• Bridge auto-implementada permanece na estável (ainda não faz parte da linha de prévia).

Mapa de substituições

Estável	@next
SANDBOX_TRANSPORT / transport / setTransport	Remover — apenas RPC
await sandbox.exec("cmd") → resultado em buffer	await sandbox.exec(argv) → handle, depois output / esperas
execStream / startProcess	Mesmo handle: logs, waitFor*, kill
Sessões padrão/nomeadas	Removidas — cwd/env por lançamento, ou um script de shell
sandbox.terminal(request) / terminal de sessão	createTerminal + terminal.connect(request)
xterm sessionId	terminalId
Métodos de interpretador em Sandbox	withInterpreter → sandbox.interpreter.*
gitCheckout	git via exec com argv
Sinais de kill em string	Apenas numéricos
Arquivos, montagens, backups, portas, túneis, proxyToSandbox	Principalmente inalterados (ignore partes de sessão/transporte em páginas estáveis)

Profundidade: Migrar · após a migração, dia a dia → sandbox-next

Auditoria

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

Também: exec( com string, cd seguido de exec, createCodeContext / runCode puro em Sandbox.

Esclarecer (perguntar quando necessário)

• OK migrar produção com --containers-rollout=immediate (processos/terminais/streams ativos podem parar)?
• Bridge auto-implementada? Deixar na estável.
• Interpretador Python → variante de imagem -python?
• Locais de chamada não cobertos pelo mapa?

Atualização

Pacote e imagem

npm install @cloudflare/sandbox@next

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

Mesma tag de pré-lançamento no Worker e na imagem quando não estiver usando next flutuante.

Código por área

Aplique as substituições do mapa. Para cada área, implemente a partir da documentação — não dos hábitos estáveis:

Área	Documentação
Comandos / handles / esperas	Processos · API de Processos
cwd / env / segredos	Ambiente · Tráfego de saída
Remover sessões	Migrar · Ciclo de vida
Terminais	Terminais
Interpretador	Interpretador
Erros	Erros
Job durável entre requisições	Execução de processo — tempo de vida / durabilidade

Comandos (formato):

// Antes (estável)
const result = await sandbox.exec("npm test");

// Depois (@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; padrão 15

Terminais (formato):

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

Interpretador (formato):

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

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

Git (formato):

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

Remova as configurações de transporte completamente. Remova as APIs de sessão. Isole usuários com IDs de sandbox separados.

Migração de deploy

Primeiro em staging/branch. Produção é um deploy do Worker + imagem correspondentes:

npx wrangler deploy --containers-rollout=immediate

Deixe rollout_active_grace_period no padrão 0 (ou defina 0 se foi aumentado). Após a migração, IDs de processo/terminal pré-deploy são inválidos. Detalhes: Migrar · Rollouts de container

Validação

1. Lockfile + Dockerfile na mesma linha @next
2. Verificação de tipos contra @next
3. Teste de fumaça com argv exec + output({ encoding: "utf8" })
4. Teste de fumaça com processo longo / terminal / interpretador se usado
5. Erros diferenciados: indisponível / RPC interrompido / obsoleto / espera local
6. Nenhum segredo ativo no ambiente do sandbox
7. Grep novamente por APIs removidas
8. Produção usou --containers-rollout=immediate

Em seguida, o trabalho do dia a dia usa sandbox-next.

Bandeiras vermelhas — pare e corrija

• Misturar Worker @next com imagem estável (ou vice-versa)
• Rollout gradual de container para esta migração
• Tratar await exec como conclusão de comando
• Assumir que cd / exportações persistem entre chamadas exec
• Um wrapper de repetição para todos os erros
• Inventar gitCheckout, stdin de processo ou APIs não documentadas
• Manter IDs de processo/terminal pré-migração após o deploy
• Forçar migração de produção sem concordância do usuário
• Colocar segredos ativos em setEnvVars / env de lançamento