Subrequests con fetch: proxy, agregación de APIs y caché del edge

El mismo fetch que usarías en el navegador vive también dentro del Worker, pero con el sentido invertido: ya no pide recursos para pintar una página, sino que sale desde el edge hacia cualquier origen de Internet o servicio de Cloudflare para traerte datos que compondrás en tu respuesta. Cada una de esas llamadas salientes es un subrequest, y ahí empieza el oficio: los subrequests se cuentan, tienen un techo por invocación y solo seis pueden viajar en paralelo. Sobre esa primitiva se construyen los dos patrones que convierten a tu Worker en un intermediario de verdad —el proxy inverso y la agregación de varias APIs— y la caché que hace que repetirlos apenas cueste.

El fetch que sale del Worker

Cuando llamas a fetch dentro de un handler, usas la misma API estándar de siempre, pero el Worker actúa ahora como cliente: abre una conexión desde el edge de Cloudflare hacia el origen que le indiques y espera su Response. Esa llamada saliente es un subrequest, y da igual que apunte a una API pública de Internet o a un binding de R2, KV o D1: todas nacen del mismo gesto y todas se contabilizan.

El caso más simple es traer datos de una API y reexponerlos. Fíjate en que la Response que recibes de fetch es de solo lectura en sus cabeceras: si quieres tocarlas, construye una nueva a partir de ella en lugar de mutarla.

export default {
  async fetch(request: Request): Promise<Response> {
    // fetch saliente: el Worker es el cliente de otro servidor
    const origen = await fetch("https://api.example.com/datos");
    const datos = await origen.json();
    return Response.json(datos);
  },
};

Nada distingue en la firma a este fetch del que usa un navegador; lo que cambia es el contexto de ejecución. Corre en el centro de datos que atendió la petición, así que la latencia hacia el origen se mide desde el edge y no desde el dispositivo del usuario, y por eso agregar varias APIs cerca del origen suele salir más barato que hacerlo desde el cliente.

Ese gesto se generaliza enseguida. Si en lugar de fabricar una URL fija quieres reenviar la propia petición entrante, pásale el Request original a fetch: copiará método, cabeceras y cuerpo. Y si necesitas cambiar algo por el camino —la ruta, una cabecera de autorización— construyes un Request nuevo a partir del original antes de enviarlo, porque el que recibes también es inmutable.

El presupuesto: subrequests y conexiones

Cada fetch saliente gasta de un presupuesto acotado, y el número exacto depende del plan. Además, cada salto de una cadena de redirecciones cuenta como un subrequest más, así que el total real puede superar a las llamadas que ves escritas.

La cifra que de verdad moldea tu diseño no es el techo total, sino ese límite de seis conexiones simultáneas. Puedes hacer miles de subrequests a lo largo de una petición, pero nunca más de seis viajando a la vez. Por eso un abanico ingenuo de cien llamadas en paralelo no acelera nada: se encola contra esa barrera y conviene agruparlo en oleadas. El corolario práctico es que la latencia de una agregación la fija la oleada más lenta, no la suma de todas: seis llamadas de cien milisegundos lanzadas juntas tardan cien, no seiscientos.

Proxy inverso y agregación de APIs

Dos arquetipos cubren casi todo. El proxy inverso reenvía la petición entrante a un origen, quizá retocando la ruta o las cabeceras, y devuelve su respuesta como si el Worker fuera el servidor. La agregación dispara varios subrequests, espera a todos y combina sus resultados en una sola respuesta, ahorrándole al cliente varias rondas de red.

Un proxy inverso mínimo compone la URL del origen a partir de la ruta entrante y reenvía la petición tal cual; a la vuelta, envuelve la respuesta para anotar una cabecera propia sin mutar la original.

// proxy inverso: reescribe la ruta y reenvia al origen
export default {
  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);
    const destino = `https://origen.example.com${url.pathname}`;
    const arriba = await fetch(destino, request);
    const respuesta = new Response(arriba.body, arriba);
    respuesta.headers.set("X-Servido-Por", "mi-worker");
    return respuesta;
  },
};

La agregación cambia la forma: en vez de un origen, varios, lanzados a la vez y fundidos en una sola carga útil.

export default {
  async fetch(request: Request): Promise<Response> {
    // agregar tres APIs en una sola respuesta
    const [perfil, pedidos, pagos] = await Promise.all([
      fetch("https://api.example.com/perfil").then((r) => r.json()),
      fetch("https://api.example.com/pedidos").then((r) => r.json()),
      fetch("https://api.example.com/pagos").then((r) => r.json()),
    ]);
    return Response.json({ perfil, pedidos, pagos });
  },
};

El Promise.all lanza las tres a la vez, y como son tres caben holgadas bajo el techo de seis conexiones. Si fueran cien, tendrías que trocear el abanico en lotes; ese detalle lo profundizas en la lección de memoria y subrequests del nivel de límites. La diferencia con el proxy es de intención: el proxy preserva y reenvía una respuesta ajena, mientras que la agregación fabrica una respuesta nueva a partir de varias.

Ambos patrones se combinan a menudo: un mismo Worker proxia el HTML de un origen y, en paralelo, agrega los datos de dos APIs para inyectarlos en esa página. El presupuesto de subrequests y el techo de conexiones son el marco dentro del cual esa orquestación se mantiene sana.

flowchart LR
C[Cliente] --> W[Worker]
W --> A1[API perfil]
W --> A2[API pedidos]
W --> A3[API pagos]
A1 --> J[Combinar en un JSON]
A2 --> J
A3 --> J
J --> R[Respuesta unica]

Cachear subrequests con cf

Cada fetch saliente admite un objeto cf en su init que controla cómo lo trata la caché de Cloudflare. Por defecto, un GET respeta las cabeceras de caché del origen; con cacheTtl fuerzas un tiempo de vida, con cacheEverything guardas incluso respuestas que el origen no marcó como cacheables, y con cacheKey normalizas la clave para que peticiones distintas compartan la misma entrada.

const res = await fetch("https://api.example.com/catalogo", {
  cf: {
    cacheTtl: 300,          // cachea 300 segundos en el edge
    cacheEverything: true,  // aun si el origen no lo marco cacheable
  },
});

Conviene entender el comportamiento por defecto antes de forzar nada: sin objeto cf, Cloudflare ya cachea las respuestas GET que el origen marca como cacheables y respeta las que declara privadas o los POST. El objeto cf no enciende la caché, sino que la reajusta cuando el criterio del origen no te sirve.

Cachear un subrequest lo convierte, tras la primera vez, en un acierto de caché que no vuelve a salir a la red ni gasta una conexión: el segundo visitante en ese centro de datos recibe la respuesta guardada. Es la palanca más barata para que un proxy o una agregación escalen sin machacar al origen.