Releases, promoción y reversión

Operaciones#

Qué capacidad necesitas#

La promoción y la reversión son las dos operaciones cuya capacidad depende del entorno:

Por eso una persona con el rol developer puede vincular testing y no puede vincular production. El contrato registra la regla como x-beyond-capability-by en ambas operaciones: en la promoción el entorno se lee del cuerpo de la solicitud, y en la reversión, de la ruta.

El release#

Un release es una instantánea inmutable. La promoción y la reversión lo vuelven a vincular; nada lo resuelve ni lo compila de nuevo. En la aplicación de administración de CDN un release aparece como «versión».

Entornos#

Una aplicación tiene exactamente dos entornos, production y testing. Cada uno es una vinculación:

Promover#

La promoción vincula un entorno a un release ready con una operación atómica de comparar y establecer sobre la version de la vinculación:

{ "environment": "production", "expected_version": 7 }

Si expected_version no es el valor actual, no cambia nada y la respuesta es 409 CONFLICT_VERSION con details.current. Lee el entorno otra vez y decide otra vez; no reintentes a ciegas con el número nuevo.

// Bind the production environment to a ready release. The binding changes only
// if nobody else changed it since you read it.
const api = process.env.CDN_API_ORIGIN;
const token = process.env.CDN_TOKEN;
const application = process.env.CDN_APPLICATION;
const release = process.env.CDN_RELEASE;

const headers = { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' };

const binding = await (await fetch(new URL(`/v1/applications/${application}/environments/production`, api), { headers })).json();
console.log(`production binds ${binding.release ?? 'nothing'} at version ${binding.version}`);

const response = await fetch(new URL(`/v1/applications/${application}/releases/${release}/promote`, api), {
	method: 'POST',
	headers,
	body: JSON.stringify({ environment: 'production', expected_version: binding.version })
});
const document = await response.json();

if (response.status === 409 && document.error.code === 'CONFLICT_VERSION') {
	// Somebody rebound the environment first. Nothing changed: read it again and decide again.
	console.log(`not promoted: the binding is now at version ${document.error.details.current}`);
	process.exitCode = 1;
} else if (!response.ok) {
	console.log(`${response.status} ${document.error.code} — ${document.error.message}`);
	process.exitCode = 1;
} else {
	console.log(`production now binds ${document.release} at version ${document.version}`);
	console.log(`rollback candidates: ${document.retained.join(', ') || 'none'}`);
}

La promoción conserva el grafo y los artefactos probados. El release que probaste en testing es, byte por byte, el release que promueves a production. Un release que no está listo responde 409 STATE_INVALID.

Previsualizar y confirmar la exposición#

Un release congela sus sourcemaps y su visibility cuando se prepara. Cuando el release publica source maps, o es público mientras la aplicación pasó a ser privada, la promoción exige un miembro acknowledged que nombre exactamente esa exposición. Una solicitud sin él, o con otros valores, no cambia nada y responde 400 VALIDATION_FAILED con details.exposure:

{ "error": { "code": "VALIDATION_FAILED", "message": "…", "details": { "exposure": { "sourcemaps": "public", "visibility": "public", "acknowledgement": true } } } }

Esa negativa es la previsualización: muestra lo que expondría vincular el release, con los valores congelados en el release y no con los ajustes actuales de la aplicación. Muéstraselos a quien promueve y luego envía la solicitud otra vez con la confirmación:

{
  "environment": "production",
  "expected_version": 7,
  "acknowledged": { "sourcemaps": "public", "visibility": "public" }
}

Revertir#

La reversión es la misma operación de comparar y establecer, limitada a los releases retained del entorno:

{ "release": "rel_Prev0001x", "expected_version": 8 }

Reutiliza los bytes retenidos y nunca vuelve a resolver ni a compilar.

Retirar#

Retirar un release que ningún entorno vincula significa que ya no se puede vincular, y que deja de proteger su cierre de la recolección de basura. Un release que sigue vinculado responde 409 STATE_INVALID.

La recolección de basura calcula lo que es alcanzable desde las vinculaciones activas, los releases retenidos y los trabajos en curso, incluidas las referencias compartidas y los módulos de carga diferida. La inactividad nunca rompe un sitio publicado.