La API de R2 desde el Worker

Desde tu Worker no hablas con R2 por HTTP ni con claves de acceso: hablas por un binding, env.BUCKET, una capacidad declarada que aparece cableada al desplegar. Y toda la potencia del almacén cabe en cinco verbos —put, get, delete, head y list—. Aprenderlos bien es aprender R2 entero, porque no hay una sexta operación escondida. Pero hay un matiz que separa a quien copia el ejemplo de quien entiende la máquina: get no te trae los bytes, te trae un asa a un flujo. Interiorizar esa diferencia es lo que te permite servir un vídeo de un gigabyte desde un isolate que apenas tiene memoria.

El binding y los cinco verbos

Un bucket llega a tu Worker como cualquier otra capacidad: lo declaras en la configuración y lo recibes en env. La lista de r2_buckets es, a la vez, el permiso y el mapa de qué almacenes toca este Worker.

{
  "r2_buckets": [
    { "binding": "BUCKET", "bucket_name": "mi-bucket" }
  ]
}

A partir de ahí, env.BUCKET es un objeto R2Bucket con cinco métodos. put escribe un objeto bajo una clave; acepta una cadena, un ArrayBuffer, un Blob o —clave para lo que viene— un ReadableStream. delete borra por clave, y admite un array para barrer varias de un golpe. head recupera los metadatos sin el cuerpo. get recupera metadatos y cuerpo. list enumera claves. Nada más.

// Escribir. put devuelve un R2Object con los metadatos resultantes.
const subido = await env.BUCKET.put("informe.pdf", request.body, {
  httpMetadata: { contentType: "application/pdf" },
  customMetadata: { autor: "willy", version: "3" },
});

// Borrar una clave, o muchas de una vez.
await env.BUCKET.delete("informe.pdf");
await env.BUCKET.delete(["tmp/a.bin", "tmp/b.bin", "tmp/c.bin"]);

Fíjate en los dos tipos de metadatos que acepta put. El httpMetadata son cabeceras estándar —contentType, cacheControl, contentDisposition— que R2 guarda y sabe devolver. El customMetadata es un diccionario tuyo, de cadena a cadena, para lo que quieras anotar. Esa distinción importará al servir el objeto: uno se convierte en cabeceras HTTP de vuelta; el otro es contexto privado de tu aplicación.

El objeto es un flujo, no una copia

Aquí está la idea que de verdad hay que agarrar. Cuando llamas a get, lo que recibes —si la clave existe— es un R2ObjectBody: un objeto de metadatos cuyo campo body es un ReadableStream. No has descargado el fichero a la memoria del Worker; tienes un asa a un flujo que R2 empezará a bombear cuando alguien lo consuma. Si la clave no existe, get devuelve null, y ese chequeo es obligatorio.

La forma canónica de servir un objeto encadena ese flujo directo a la respuesta. R2 lee del almacén y el cliente recibe los bytes en tránsito, sin que ni un solo megabyte se acumule en el isolate:

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const objeto = await env.BUCKET.get("video.mp4");
    if (objeto === null) {
      return new Response("no encontrado", { status: 404 });
    }
    const headers = new Headers();
    objeto.writeHttpMetadata(headers);       // vuelca contentType, cacheControl...
    headers.set("etag", objeto.httpEtag);    // el etag entrecomillado, listo para cabecera
    return new Response(objeto.body, { headers });
  },
} satisfies ExportedHandler<Env>;

El método writeHttpMetadata es un detalle elegante: toma el httpMetadata que guardaste al subir y lo escribe como cabeceras sobre un objeto Headers. El objeto recuerda cómo debía servirse. Y si solo necesitas saber de un fichero —su tamaño, su fecha, su tipo— sin traerte los bytes, head te da el mismo R2Object de metadatos pagando una lectura barata en vez de mover el cuerpo entero.

const meta = await env.BUCKET.head("video.mp4");
if (meta) {
  console.log(meta.size, meta.uploaded, meta.httpMetadata.contentType);
}

flowchart LR
Cliente[cliente] --> Worker[worker]
Worker --> Get[get del binding]
Get --> Body[R2ObjectBody con body como stream]
Body --> Resp[Response en streaming]
Resp --> Cliente
style Body fill:#a6e3a1,color:#11111b

Tanto get como put aceptan además una condición, onlyIf, que hace la operación dependiente del estado del objeto: ejecútala solo si el etag coincide, o si no coincide, o según la fecha de subida. Es concurrencia optimista para objetos. Si la condición de un get falla, R2 te devuelve los metadatos sin el cuerpo —una lectura más rápida—; si la de un put falla, devuelve null en vez del R2Object, señal de que otro escritor se te adelantó.

// Escribe solo si el objeto no ha cambiado desde el etag que conoces.
const resultado = await env.BUCKET.put(clave, cuerpo, {
  onlyIf: { etagMatches: etagConocido },
});
if (resultado === null) {
  return new Response("conflicto: alguien escribió antes", { status: 412 });
}

Listar: recorrer un catálogo perezoso

list enumera las claves del bucket, ordenadas lexicográficamente, pero con una cautela deliberada: devuelve como mucho mil entradas por llamada, y a veces menos para no presionar la memoria del isolate. Un bucket puede tener millones de objetos; ninguna llamada te los dará todos. El recorrido completo es, por diseño, una paginación con cursor.

let cursor: string | undefined;
do {
  const pagina = await env.BUCKET.list({ prefix: "fotos/", cursor, limit: 1000 });
  for (const obj of pagina.objects) {
    console.log(obj.key, obj.size);
  }
  cursor = pagina.truncated ? pagina.cursor : undefined;
} while (cursor);

Dos opciones gobiernan la forma del listado. El prefix acota a las claves que empiezan por una cadena —tu única herramienta para simular carpetas—. El delimiter, combinado con el prefijo, colapsa todo lo que hay bajo un nivel en delimitedPrefixes, devolviéndote algo parecido a “las subcarpetas de aquí” sin recorrer su contenido. Y el par truncated/cursor es el motor de la paginación: mientras truncated sea verdadero, hay más, y cursor es el marcador para reanudar.

Hay un coste que conviene tener presente. Cada verbo cuenta como una operación facturable: put, delete, list y las escrituras son de clase A; get y head, lecturas, son de clase B, diez veces más baratas. Listar un bucket enorme página a página no es gratis, y por eso el patrón maduro guarda su propio índice de claves —en KV o en D1— cuando necesita consultarlo a menudo, y reserva list para barridos ocasionales o reconciliaciones.