Patrones reales: webhooks, subidas, proxys y rate-limit

Ya tienes las piezas: handlers por verbo, lectura del cuerpo, params, cabeceras, estados, streaming. Este cierre las ensambla en cuatro patrones que aparecen en casi cualquier proyecto serio. Recibir un webhook de un servicio externo y confiar en él sin ser engañado. Aceptar la subida de un fichero sin dejar que te desborde. Hacer de proxy hacia una API de pago para que su clave nunca salga del servidor. Y frenar el abuso con un límite de peticiones. Los cuatro comparten una moraleja: un endpoint bajo demanda es una puerta abierta a internet, y la diferencia entre uno de juguete y uno de producción está casi toda en cómo trata lo que entra por ella.

Webhooks: confiar sin ser engañado

Un webhook es un POST que un servicio externo —una pasarela de pago, un repositorio— lanza a tu endpoint cuando ocurre algo. El problema es la confianza: cualquiera puede enviarte un POST fingiendo ser ese servicio. La defensa es una firma HMAC: el emisor firma el cuerpo con un secreto compartido y adjunta la firma en una cabecera; tú recomputas la firma y compruebas que coincide. Clave: hay que firmar el cuerpo crudo, byte a byte, así que lo lees con request.text antes de parsear nada.

// src/pages/api/webhook.ts
import type { APIRoute } from 'astro';

export const prerender = false;
const secret = import.meta.env.WEBHOOK_SECRET;

export const POST: APIRoute = async ({ request }) => {
  const firma = request.headers.get('x-signature') ?? '';
  const crudo = await request.text();            // cuerpo sin parsear

  if (!(await firmaValida(crudo, firma, secret))) {
    return new Response('firma invalida', { status: 401 });
  }

  const evento = JSON.parse(crudo);
  await encolarProceso(evento);                  // trabajo pesado, fuera del ciclo
  return new Response(null, { status: 200 });    // acuse de recibo inmediato
};

// la firma se recomputa con la Web Crypto API, estandar en todo runtime
async function firmaValida(cuerpo: string, firma: string, secret: string) {
  const key = await crypto.subtle.importKey(
    'raw',
    new TextEncoder().encode(secret),
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['sign'],
  );
  const mac = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(cuerpo));
  const esperada = [...new Uint8Array(mac)]
    .map((b) => b.toString(16).padStart(2, '0'))
    .join('');
  return esperada === firma;
}

Dos disciplinas más hacen a un receptor de webhooks robusto. Primera: acusa recibo rápido —un 200 en cuanto validas— y delega el trabajo pesado a una cola o a una tarea de fondo; si tardas, el emisor reintentará y procesarás el evento dos veces. Segunda: la idempotencia, tratar cada evento por su identificador único para que un reintento no duplique efectos. Un webhook mal hecho cobra dos veces la misma tarjeta.

Subidas: aceptar un fichero sin desbordarte

Un formulario multipart con un fichero se lee con request.formData, que devuelve un FormData donde cada campo de tipo archivo es un objeto File. Desde ahí tienes su nombre, su tamaño y sus bytes vía arrayBuffer. La regla de oro: valida antes de guardar, porque el cliente controla lo que manda.

export const prerender = false;

export const POST: APIRoute = async ({ request }) => {
  const form = await request.formData();
  const fichero = form.get('archivo');

  if (!(fichero instanceof File)) {
    return Response.json({ error: 'falta el archivo' }, { status: 400 });
  }
  if (fichero.size > 2_000_000) {
    return Response.json({ error: 'demasiado grande' }, { status: 413 });
  }
  if (!fichero.type.startsWith('image/')) {
    return Response.json({ error: 'tipo no permitido' }, { status: 415 });
  }

  const bytes = await fichero.arrayBuffer();
  const url = await guardarEnAlmacen(fichero.name, bytes);
  return Response.json({ url }, { status: 201 });
};

El tamaño se rechaza con 413, el tipo no admitido con 415. Nunca confíes solo en la extensión del nombre —se falsifica en un segundo—; comprueba el type y, para datos sensibles, inspecciona los primeros bytes. Y no guardes el fichero en tu servidor de aplicación: súbelo a un almacén de objetos —R2, S3— para no llenar el disco de la función.

Proxy: ocultar la clave en el servidor

Muchas APIs de terceros exigen una clave secreta. Si tu JavaScript de cliente la usara directamente, esa clave viajaría al navegador y quedaría expuesta a la vista de cualquiera. El patrón proxy lo resuelve: tu endpoint recibe la petición del cliente, llama a la API de terceros desde el servidor con la clave, y devuelve el resultado. La clave nunca sale de tu backend.

export const prerender = false;
const KEY = import.meta.env.CLIMA_API_KEY;

export const GET: APIRoute = async ({ url }) => {
  const ciudad = url.searchParams.get('ciudad') ?? 'madrid';
  const arriba = await fetch(`https://api.clima.example/v1?q=${ciudad}&key=${KEY}`);

  if (!arriba.ok) {
    return Response.json({ error: 'servicio no disponible' }, { status: 502 });
  }
  const datos = await arriba.json();
  return Response.json(datos, {
    headers: { 'Cache-Control': 'public, max-age=600' },
  });
};

El proxy es además el sitio natural para cachear —un Cache-Control ahorra llamadas de pago a la API de arriba—, para filtrar qué campos expones y para transformar la respuesta. Un fallo del servicio de terceros se traduce a un 502 Bad Gateway, que dice la verdad: no fallaste tú, falló aquel de quien dependes.

Rate-limit: frenar el abuso

Un endpoint público sin freno es una invitación al abuso. Un rate-limit básico cuenta las peticiones por origen —clientAddress te da la IP, disponible solo bajo demanda— dentro de una ventana de tiempo, y responde 429 Too Many Requests con Retry-After cuando se pasa.

export const prerender = false;
const ventana = 60_000;      // 1 minuto
const limite = 30;           // peticiones por ventana
const cubos = new Map<string, { n: number; hasta: number }>();

export const POST: APIRoute = async ({ clientAddress }) => {
  const ahora = Date.now();
  const cubo = cubos.get(clientAddress);

  if (!cubo || ahora > cubo.hasta) {
    cubos.set(clientAddress, { n: 1, hasta: ahora + ventana });
  } else if (cubo.n >= limite) {
    const espera = Math.ceil((cubo.hasta - ahora) / 1000);
    return new Response('demasiadas peticiones', {
      status: 429,
      headers: { 'Retry-After': String(espera) },
    });
  } else {
    cubo.n += 1;
  }
  return Response.json({ ok: true });
};

flowchart LR
EXT[servicio externo] -->|POST firmado| EP[endpoint webhook]
EP --> V{firma valida}
V -->|no| R401[401 rechazado]
V -->|si| ACK[200 acuse rapido]
ACK --> COLA[procesa en segundo plano]
style EXT fill:#89b4fa,color:#11111b
style ACK fill:#a6e3a1,color:#11111b
style R401 fill:#f38ba8,color:#11111b