Transformar en el Worker: redimensionar y recortar al vuelo

La lección anterior servía imágenes que Cloudflare guardaba. Esta trata del caso mucho más común: las imágenes ya viven en algún sitio tuyo —un bucket de R2, un servidor heredado, un proveedor del que no piensas moverte— y lo único que quieres es que lleguen al navegador con el tamaño correcto y en un formato de este siglo. Para eso no hace falta migrar nada. El motor de optimización se invoca como una opción de una subpetición ordinaria, lo que significa que el Worker deja de ser un intermediario que reenvía bytes y pasa a ser el sitio donde se decide, por petición y con toda tu lógica delante, qué imagen exactamente merece este visitante.

La transformación como opción de una subpetición

El mecanismo es de una sencillez que desarma. Cuando pides una imagen con fetch desde un Worker, el segundo argumento admite un objeto cf con opciones específicas de la plataforma, y dentro de él una clave image describe la transformación que quieres aplicar mientras la respuesta pasa por el edge. No hay servicio intermedio, no hay cola, no hay fichero temporal: es la misma subpetición de siempre con una descripción del resultado.

export default {
  async fetch(request: Request): Promise<Response> {
    const original = "https://origen.ejemplo.com/fotos/a-142.jpg";
    return fetch(original, {
      cf: {
        image: { fit: "scale-down", width: 800, height: 600, quality: 82 },
      },
    });
  },
};

Tres detalles gobiernan el despliegue. El primero es que cf.image está disponible en cualquier zona que aloje un Worker, incluidos los subdominios de workers.dev, pero la zona debe tener activadas las transformaciones. El segundo es que cada transformación se factura a la cuenta dueña del Worker, no a la del origen, lo cual importa cuando sirves imágenes de terceros. Y el tercero es el que más disgustos evita: el objeto cf solo tiene efecto en subpeticiones salientes, así que devolver la respuesta de ese fetch es lo que funciona, no adornar la petición entrante.

Existe una segunda cara del mismo motor, la interfaz por URL, con un prefijo fijo /cdn-cgi/image/ seguido de las opciones y del origen. Es más rápida de probar desde la barra del navegador y no requiere escribir código, pero expone la ruta real de la imagen y deja el catálogo de transformaciones abierto a quien sepa componer una dirección. El Worker existe precisamente para cerrar eso: tú decides el esquema de URL que el mundo ve, y el origen real puede ser un bucket privado cuya dirección nunca sale al exterior.

Ajuste, gravedad y calidad

Redimensionar es trivial; recortar bien no lo es. Cuando la proporción del original no coincide con la del hueco hay que sacrificar algo, y las opciones del motor son precisamente la enumeración de qué se sacrifica. Los cinco modos de ajuste —scale-down, contain, cover, crop y pad— ya aparecieron en la lección anterior, y aquí funcionan idénticos porque es el mismo motor. Lo nuevo es lo que solo tiene sentido cuando recortas.

Con cover o con crop hay que decidir qué parte de la imagen sobrevive. Por defecto se conserva el centro geométrico, que es una apuesta razonable y frecuentemente equivocada: en un retrato vertical llevado a una tira apaisada, el centro suele ser el torso. La opción de gravedad acepta un lado, unas coordenadas relativas o dos valores automáticos que resuelven el caso real —auto, que busca la región con más detalle, y face, que busca caras—.

const opciones = {
  cf: {
    image: {
      fit: "cover",
      width: 320,
      height: 320,
      gravity: "face",
      quality: "medium-high",
      metadata: "none",
    },
  },
} satisfies RequestInit;

La calidad admite dos vocabularios. El numérico va de uno a cien con ochenta y cinco por defecto, y es el que conoces de cualquier compresor. El perceptual —high, medium-high, medium-low, low— es más interesante porque no fija un número sino un objetivo de calidad aparente, y deja que el motor gaste más bits en una fotografía con textura fina y menos en una ilustración plana. En un catálogo heterogéneo suele dar mejores resultados que cualquier número que elijas a mano.

Dos opciones más merecen sitio en el vocabulario. Los dibujos superpuestos, disponibles solo desde Workers, aceptan una lista de imágenes con posición, ajuste y opacidad, y son la vía canónica para marcas de agua, logotipos y viñetas sin generar variantes nuevas. Y el formato especial de salida que devuelve un objeto de datos en vez de una imagen es la herramienta de diagnóstico que casi nadie conoce: te dice dimensiones antes y después, tipo original y tamaño en bytes, y sirve para instrumentar el ahorro real que estás consiguiendo.

Negociar el formato a mano

Aquí está la diferencia práctica más importante entre las dos interfaces. Cuando sirves una imagen alojada por su URL de entrega, la negociación de formato viene resuelta. Cuando transformas desde un Worker, la responsabilidad es tuya: el valor automático de formato no se aplica solo, porque quien conoce las capacidades del cliente es tu código, que tiene la petición entrante en la mano. La cabecera Accept que manda el navegador es la declaración de qué sabe descodificar, y traducirla a una opción de formato son cuatro líneas.

export default {
  async fetch(request: Request): Promise<Response> {
    const acepta = request.headers.get("Accept") ?? "";
    const image: Record<string, unknown> = { fit: "scale-down", width: 1200 };

    if (acepta.includes("image/avif")) image.format = "avif";
    else if (acepta.includes("image/webp")) image.format = "webp";

    const url = new URL(request.url);
    const origen = `https://origen.ejemplo.com${url.pathname}`;
    const respuesta = await fetch(origen, { cf: { image } });

    const salida = new Response(respuesta.body, respuesta);
    salida.headers.append("Vary", "Accept");
    return salida;
  },
};

Fíjate en la última línea, que es la que separa un ejemplo de juguete de algo que puedes desplegar. Si una misma dirección devuelve bytes distintos según una cabecera de la petición, cualquier caché intermedia necesita saberlo o servirá AVIF a un cliente que solo entiende JPEG. Declarar esa dependencia con la cabecera Vary no es un detalle de purista: es la condición para que el resultado sea correcto a través de proxies que no controlas.

sequenceDiagram
participant N as navegador
participant W as worker en el edge
participant O as origen privado
N->>W: GET /fotos/a-142 con cabecera accept
W->>W: valida el preajuste y elige formato
W->>O: subpeticion con opciones de imagen
O-->>W: bytes originales
W-->>N: imagen redimensionada y recodificada
Note over W: la ruta real del origen nunca sale

El binding: bytes en lugar de URL

Todo lo anterior parte de una premisa que a veces no se cumple: que la imagen es alcanzable por una URL que el motor pueda pedir. Cuando el original vive en un bucket privado de R2, o llega en el cuerpo de una petición de subida, o lo acaba de generar un modelo, no hay dirección pública que ofrecer. Para ese caso existe el binding de Images, que opera sobre un flujo de bytes y encadena operaciones hasta producir una salida.

{
  "images": { "binding": "IMAGES" },
  "r2_buckets": [{ "binding": "BUCKET", "bucket_name": "originales" }]
}

const objeto = await env.BUCKET.get("originales/a-142.jpg");
if (!objeto) return new Response("No existe", { status: 404 });

const salida = await env.IMAGES.input(objeto.body)
  .transform({ width: 640 })
  .transform({ blur: 12 })
  .output({ format: "image/avif", quality: 80 });

return salida.response();

Las diferencias con la subpetición son tres y todas importan. La entrada admite bytes de cualquier procedencia hasta un tamaño máximo del orden de veinte megabytes, así que sirve para subidas y para orígenes privados por igual. El formato de salida es obligatorio: aquí no hay negociación implícita porque no hay petición entrante que interrogar, y eres tú quien decide. Y el encadenamiento de transformaciones es ordenado, lo que permite componer secuencias —rotar, luego recortar, luego difuminar— que la interfaz por URL no expresa. Hay además un método de inspección que devuelve dimensiones y formato sin producir imagen y sin facturarse, útil para rechazar una subida antes de gastar nada en ella.