Versionado y contratos

Cuando dos Workers se comunican por RPC, el que expone WorkerEntrypoint no publica solo unos métodos: publica una promesa. La firma de cada método, los tipos de sus argumentos y la forma serializada de lo que devuelve constituyen un contrato, y el Worker que llama construye su lógica sobre él. Mientras vivieran en el mismo despliegue, esa promesa se cumpliría siempre. Pero productor y consumidor se despliegan por separado, evolucionan por su cuenta y pueden divergir. Esta lección trata la disciplina que impide que esa divergencia rompa el sistema: qué cambios son seguros, en qué orden liberarlos y cómo mantener el contrato mientras el edificio se reforma en caliente.

La interfaz RPC es el contrato

Cada método público de tu WorkerEntrypoint es una cláusula del contrato. env.CATALOGO.ficha promete recibir un string y devolver una forma concreta; el consumidor firma esa promesa al escribir la llamada. A diferencia de un endpoint HTTP con JSON, donde el contrato es implícito y sin tipo, aquí wrangler types deriva las definiciones a partir de la clase del productor y el compilador verifica que ambos lados encajan. Parece que el problema del versionado quedó resuelto por el sistema de tipos.

No es así, y la sutileza es el corazón de la lección. Esa verificación ocurre sobre un único árbol de fuentes en el momento de compilar. En producción, el productor y el consumidor son dos artefactos que se despliegan por separado, en momentos distintos. El contrato que de verdad rige no es el que escribiste, sino la intersección de lo que hay desplegado a cada lado en cada instante. El compilador prueba que tu lado es coherente consigo mismo; nada más.

Cambios compatibles y cambios que rompen

Un cambio es compatible cuando ningún consumidor existente lo nota. Son aditivos: un método nuevo, un argumento opcional nuevo, un campo nuevo en el objeto de retorno. El consumidor viejo pedía un subconjunto de la forma y ese subconjunto sigue intacto, así que sigue funcionando sin recompilar.

// PRODUCTOR v1: el contrato original
export class Catalogo extends WorkerEntrypoint<Env> {
  async ficha(id: string): Promise<{ nombre: string; precio: number }> {
    return await cargar(this.env, id);
  }
}

// PRODUCTOR v2: evolucion ADITIVA y compatible
export class Catalogo extends WorkerEntrypoint<Env> {
  // 'moneda' es un parametro nuevo, pero OPCIONAL
  // 'stock' es un campo nuevo del retorno: el consumidor viejo lo ignora
  async ficha(id: string, moneda?: string): Promise<{
    nombre: string;
    precio: number;
    stock: number;
  }> {
    return await cargar(this.env, id, moneda);
  }
}

Un cambio rompe cuando altera lo que el consumidor ya daba por firmado: eliminar o renombrar un método, volver obligatorio un argumento que era opcional, cambiar el tipo de un parámetro o de un campo, retirar un campo del retorno. Cada uno deja a los consumidores existentes llamando a un fantasma.

// PRODUCTOR: cambios que ROMPEN el contrato
//  - 'moneda' pasa de opcional a obligatoria
//  - 'precio' se renombra a 'precioCentavos'
//  - el tipo de 'id' cambia de string a number
// Ninguno lo ve el compilador del consumidor hasta que ya es tarde.

La defensa del consumidor es el principio de robustez: pide solo lo que necesitas y sé indiferente a lo demás. Si desestructuras únicamente los campos que usas, el productor puede engordar la forma sin obligarte a recompilar en bloque.

// CONSUMIDOR tolerante: pide solo lo que necesita
const { nombre, precio } = await env.CATALOGO.ficha("sku-42");
// Si el productor agrega 'stock' u otros campos, este consumidor ni se entera.

El orden del despliegue

De la asimetría entre añadir y quitar sale un único invariante que gobierna el orden: el productor debe ofrecer una capacidad antes de que el consumidor la use, y el consumidor debe dejar de usarla antes de que el productor la retire. Para un cambio aditivo, eso significa desplegar primero el productor y luego el consumidor; si inviertes el orden, el consumidor nuevo llama a algo que el productor viejo aún no ofrece.

Un cambio que rompe nunca se libera de un tirón. Se descompone en una secuencia de pasos compatibles —el patrón de expandir y contraer—: primero el productor soporta la forma vieja y la nueva a la vez, después el consumidor migra a la nueva, y solo entonces el productor retira la vieja. Tres despliegues convierten una ruptura en tres transiciones, cada una de ellas segura por sí misma.

Detrás de este ceremonial hay un hecho incómodo: no existe un despliegue atómico que toque los dos Workers en el mismo instante. Siempre hay una ventana, por breve que sea, en la que conviven una versión de cada lado, y el orden es la única herramienta que garantiza que todo par que llegue a coexistir durante esa ventana sea compatible.

# Cambio aditivo: primero el que ofrece, despues el que usa
wrangler deploy   # productor: ya expone lo nuevo

wrangler deploy   # consumidor: recien ahora lo invoca

flowchart TD
subgraph aditivo
  A1[productor ofrece lo nuevo] --> A2[consumidor lo empieza a usar]
end
subgraph rompe
  B1[expandir productor con ambas formas] --> B2[migrar consumidor a la nueva forma]
  B2 --> B3[contraer productor quita la vieja]
end
style A1 fill:#a6e3a1,color:#11111b
style B1 fill:#89b4fa,color:#11111b
style B3 fill:#f38ba8,color:#11111b

Despliegue gradual con wrangler versions

wrangler versions te deja separar subir una versión de dirigirle tráfico. Subes el nuevo código sin que reciba ni una llamada, y luego repartes el tráfico entre versiones por porcentaje, observando las métricas antes de comprometerte.

# 1. Sube la version nueva SIN darle trafico (queda al 0%)
wrangler versions upload

# 2. Reparte el trafico entre dos versiones por su id
wrangler versions deploy <id-estable>@90% <id-nueva>@10%

# 3. Si las metricas van bien, promueve al 100%
wrangler versions deploy <id-nueva>@100%

Aquí el service binding añade un matiz decisivo. Durante el reparto, las llamadas del consumidor caen sobre ambas versiones del productor a la vez: una fracción golpea la vieja y otra la nueva. Por tanto, las dos deben honrar simultáneamente el contrato que el consumidor espera. Esto es justo lo que hace seguro un cambio aditivo —ambas versiones son compatibles— y lo que vuelve imposible canariar directamente uno que rompe: la fracción que pegue en la versión equivocada fallará sin remedio.