Subidas directas: que el cliente suba sin pasar por tu servidor

Hay una decisión de arquitectura que casi todo el mundo toma sin darse cuenta y casi siempre mal: cuando un usuario sube una foto o un vídeo, ¿por dónde pasan esos bytes? La respuesta por inercia es que pasan por tu servidor, porque es donde vive la lógica y donde están las credenciales. Y es la peor opción disponible: pagas el tráfico de entrada y el de salida hacia el proveedor, mantienes una petición abierta durante minutos, arriesgas tiempos de espera agotados y conviertes tu backend en el punto de estrangulamiento de una operación que no necesita nada de él. Las subidas directas invierten el flujo con un artefacto sencillo y muy afilado: una URL de un solo uso, emitida por ti, que el cliente usa sin poseer ninguna credencial.

El coste de pasar por tu servidor

Enumeremos el daño con precisión, porque el argumento suele darse por sabido y no lo está. Primero, el tráfico se paga dos veces: entra a tu infraestructura y vuelve a salir hacia el almacenamiento. Segundo, ocupas un proceso o una conexión durante todo el tiempo que dure la carga, que en una conexión móvil mediocre y un vídeo de medio gigabyte son minutos; multiplícalo por la concurrencia de una hora punta y tienes un plan de capacidad dictado por la peor red de tus usuarios. Tercero, hereda todos los límites de tu capa de entrada —tamaño máximo de cuerpo, tiempo de espera del balanceador— y esos límites suelen aparecer en producción, no en pruebas.

Y hay un cuarto motivo que no es de coste sino de forma, y es el más importante. En un Worker, el proxy de subida es directamente hostil al modelo de ejecución: mantener un cuerpo enorme atravesando un isolate con límites de memoria y de tiempo de CPU es luchar contra la plataforma en lugar de usarla. La solución no es aumentar límites: es no tocar los bytes.

sequenceDiagram
participant C as cliente
participant W as tu worker
participant P as images o stream
C->>W: quiero subir un fichero
W->>W: autentica al usuario y comprueba cuota
W->>P: pide una url de un solo uso con restricciones
P-->>W: url unica mas identificador futuro
W-->>C: solo la url
C->>P: sube los bytes directamente
P-->>W: webhook cuando el recurso esta listo

Fíjate en lo que ocurre en ese diagrama: tu código participa dos veces y ninguna de ellas toca un byte del fichero. Interviene al principio, para decidir si esta persona puede subir y con qué límites, y al final, para enterarse de que el recurso existe. En medio, los bytes viajan por el camino más corto entre el dispositivo del usuario y el almacenamiento.

Images: una URL de un solo uso y un registro en borrador

El gesto es una llamada al punto de subida directa, que no sube nada: reserva. Devuelve dos cosas —el identificador que la imagen tendrá cuando exista y la URL a la que el cliente debe enviarla— y crea al mismo tiempo un registro en estado de borrador que todavía no aparece en tu listado de imágenes.

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const usuario = await autenticar(request, env);
    if (!usuario) return new Response("No autorizado", { status: 401 });
    if (await cuotaAgotada(usuario, env)) return new Response("Cuota agotada", { status: 429 });

    const respuesta = await fetch(
      `https://api.cloudflare.com/client/v4/accounts/${env.CUENTA}/images/v2/direct_upload`,
      {
        method: "POST",
        headers: { Authorization: `Bearer ${env.TOKEN}` },
        body: formulario({
          requireSignedURLs: "true",
          metadata: JSON.stringify({ usuario: usuario.id }),
          expiry: new Date(Date.now() + 10 * 60_000).toISOString(),
        }),
      },
    );

    const { result } = await respuesta.json<RespuestaSubida>();
    await registrarPendiente(usuario, result.id, env);
    return Response.json({ uploadURL: result.uploadURL });
  },
};

Del lado del cliente no hay nada que aprender: un formulario ordinario con un campo de fichero que apunta a esa dirección basta, y no viaja ninguna credencial en él.

<form action="URL_DE_UN_SOLO_USO" method="post" enctype="multipart/form-data">
  <input type="file" name="file" />
  <input type="submit" value="Subir" />
</form>

Tres detalles marcan la diferencia entre una integración correcta y una que da problemas al mes. El primero es la caducidad: el enlace vive treinta minutos por defecto, y puedes fijarla entre dos minutos y seis horas. Corta es mejor, porque el enlace es una capacidad y una capacidad que dura poco tiene menos superficie. El segundo es el campo de borrador: mientras el usuario no haya subido nada, el registro existe con esa marca y no ensucia tu listado, lo que te da un estado intermedio explícito en vez de una ausencia ambigua. Y el tercero es que puedes fijar un identificador propio en vez del generado, con una contrapartida que hay que conocer: una imagen con identificador a medida no puede exigir URL firmada.

Stream: reserva de duración y subidas reanudables

Con vídeo el patrón es el mismo pero aparece una obligación nueva, y es de facturación. Como Stream cobra el almacenamiento por minutos comprados por adelantado, al emitir el enlace tienes que declarar la duración máxima que reservas para esa subida. Esos minutos se descuentan de tu saldo en el acto y se liberan cuando el vídeo real se procesa —quedándose la duración verdadera—, cuando el enlace caduca sin usarse, o cuando la codificación falla.

const subida = await env.STREAM.createDirectUpload({ maxDurationSeconds: 600 });
return Response.json({ uploadURL: subida.uploadURL, uid: subida.uid });

El binding resuelve el caso ordinario sin token ni llamada autenticada. Pero hay un umbral que decide la arquitectura del cliente: un POST simple admite hasta doscientos megabytes, y por encima de eso —o cuando la conexión del usuario es dudosa aunque el fichero sea menor— hay que usar el protocolo reanudable tus, que trocea la carga y permite retomarla donde se cortó en vez de empezar de cero.

La variante reanudable tiene una forma distinta que conviene no descubrir a medias. Tu Worker llama al punto de creación indicando que el usuario final será quien suba, reenviando las cabeceras que el protocolo exige —la versión, la longitud total del fichero y los metadatos—, y la URL de un solo uso no llega en el cuerpo de la respuesta sino en la cabecera de ubicación. Para que el navegador del usuario pueda leerla, hay que exponerla explícitamente en las cabeceras de intercambio de origen cruzado.

const destino = await fetch(
  `https://api.cloudflare.com/client/v4/accounts/${env.CUENTA}/stream?direct_user=true`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${env.TOKEN}`,
      "Tus-Resumable": "1.0.0",
      "Upload-Length": request.headers.get("Upload-Length")!,
      "Upload-Metadata": request.headers.get("Upload-Metadata")!,
    },
  },
);

return new Response(null, {
  headers: {
    Location: destino.headers.get("Location")!,
    "Access-Control-Expose-Headers": "Location",
    "Access-Control-Allow-Origin": "https://mi-app.ejemplo.com",
  },
});

Las restricciones viajan aquí dentro de la cabecera de metadatos, con una sintaxis peculiar que causa errores silenciosos si se improvisa: pares de clave y valor donde el valor va codificado en base64, la clave se separa del valor por un espacio —nunca por un signo de igualdad— y los pares se unen con comas sin espacios. Solo se leen en la primera petición, la que hace tu Worker; en las siguientes se ignoran.

El punto donde vive tu política

Queda la idea que ordena la lección. La URL de un solo uso parece un truco de rendimiento y es en realidad un mecanismo de autorización, porque el instante en que la emites es el único instante en que tu código puede decir que no. Después ya no hay a quién preguntar: quien tenga el enlace subirá.

Por eso todo lo que sea política se decide ahí. Quién es este usuario y si su sesión es válida. Cuántas subidas lleva hoy y si le queda cupo. Qué duración máxima merece según su plan. Cuánto tiempo debe vivir el enlace. Si el recurso nacerá público o exigiendo firma. A qué entidad de tu dominio quedará asociado, escrito en los metadatos. Un Worker es el lugar natural para esa decisión porque está en el borde, responde en milisegundos y no necesita ver un solo byte del fichero para tomarla.

Y del otro lado del proceso queda una regla que evita la clase de error más común: no confíes en que el cliente te avise de que terminó. Un navegador se cierra, una pestaña se recarga, una red se cae justo al final. La confirmación fiable llega por webhook desde el proveedor, o consultando el estado con el identificador que guardaste al emitir el enlace. Todo lo que tu interfaz cuente al usuario mientras tanto es optimismo, y debe estar marcado como tal.