HTMLRewriter: transformar HTML en streaming con element handlers

La forma clásica de modificar una página es cargarla entera, parsearla en un árbol DOM, mutar los nodos y volver a serializarla a texto. Eso exige tener todo el documento en memoria y pagar dos travesías completas. HTMLRewriter propone lo contrario: transforma el HTML mientras atraviesa el Worker como un flujo. Tú declaras handlers asociados a selectores CSS, y el motor los llama sobre cada elemento que coincide justo cuando ese fragmento pasa por delante. Inyectar una etiqueta, reescribir cada enlace o extraer un dato dejan de requerir el árbol completo: se resuelven al vuelo, con una huella de memoria casi constante por grande que sea la página.

Transformar sin parsear el documento entero

Una librería tipo DOM en el servidor carga el HTML completo, levanta un árbol de nodos y te deja consultarlo y mutarlo con acceso aleatorio. Es cómodo, pero cuesta memoria proporcional al tamaño de la página y obliga a tener el documento entero antes de tocar nada; en un isolate con 128 MB compartidos, esa cuenta se vuelve un lujo peligroso en cuanto las páginas crecen. HTMLRewriter funciona como un analizador en streaming: dispara callbacks a medida que los tokens del HTML pasan, sin materializar el árbol.

Lo usas envolviendo una Response. Registras handlers con on, indicando un selector CSS, y llamas a transform sobre la respuesta del origen; recibes una Response nueva cuyo cuerpo es el flujo ya transformado.

export default {
  async fetch(request: Request): Promise<Response> {
    const original = await fetch("https://ejemplo.com");
    return new HTMLRewriter()
      .on("a[href]", new ReescribirEnlaces())
      .transform(original);
  },
};

El objeto HTMLRewriter es reutilizable y encadenable: cada on devuelve el propio rewriter, así que registras cuantos handlers necesites antes de llamar a transform. Y transform no ejecuta nada de inmediato; solo conecta la maquinaria, que irá disparando los handlers conforme el cuerpo de la respuesta se consuma aguas abajo.

Como la transformación es en streaming, la memoria se mantiene plana tanto si la página pesa diez kilobytes como diez megabytes: los bytes entran, pasan por los handlers y salen, sin quedarse. Y como el resultado es a su vez un flujo, encaja con todo lo demás: puedes transformar la respuesta de un fetch a un origen, la de un objeto servido desde R2 o la salida de otro Worker, porque todas son una Response con un cuerpo que fluye.

El patrón element handler

Cada on recibe un selector y un objeto handler. Si ese objeto tiene un método element, el motor lo llama una vez por cada elemento que casa con el selector, pasándole un Element sobre el que puedes operar: getAttribute, setAttribute, removeAttribute, setInnerContent, append, prepend, before, after o remove. Ese es el patrón element handler: una clase pequeña por cada transformación.

class ReescribirEnlaces {
  element(el: Element) {
    const href = el.getAttribute("href");
    if (href?.startsWith("http://")) {
      // fuerza https en cada enlace que pasa
      el.setAttribute("href", href.replace("http://", "https://"));
    }
  }
}

El handler ve un elemento cada vez y nunca sostiene el árbol completo: no puede preguntar por el hermano siguiente ni por un ancestro lejano, porque quizá aún no han llegado o ya pasaron. Esa restricción es el precio del streaming, y a cambio te da un coste en memoria independiente del tamaño del documento. Por eso los handlers se escriben como clases pequeñas con estado propio: cada una encapsula una transformación y, si necesita recordar algo entre llamadas —un contador, un búfer de texto—, lo guarda en sus campos, nunca en el documento.

flowchart LR
O[HTML del origen] --> HR[HTMLRewriter]
HR -->|coincide a href| H1[Reescribir enlace]
HR -->|coincide head| H2[Inyectar tag]
H1 --> OUT[HTML transformado en streaming]
H2 --> OUT

Inyectar, reescribir y extraer

Tres arquetipos cubren casi todo. Inyectar: añadir un nodo donde interese, como una etiqueta en la cabecera. Reescribir: cambiar atributos o contenido, como forzar https o proxiar imágenes. Extraer: leer un valor del HTML hacia una variable externa sin alterar la salida. Para inyectar HTML crudo, pasa la opción html: true; sin ella, el contenido se escapa como texto.

class InyectarEnHead {
  element(el: Element) {
    el.append(`<link rel="preconnect" href="https://cdn.example.com">`, {
      html: true,
    });
  }
}

// componer varios handlers en una sola pasada de streaming
new HTMLRewriter()
  .on("head", new InyectarEnHead())
  .on("a[href]", new ReescribirEnlaces())
  .transform(original);

Extraer datos tiene un matiz importante: el texto de un elemento no llega de una vez, sino en varios trozos, y tu handler de tipo text puede ser invocado varias veces por un mismo nodo. Para reconstruir un valor completo debes acumular esos trozos y actuar cuando el fragmento marque el final con su propiedad lastInTextNode.

class ExtraerTitulo {
  private buffer = "";
  text(trozo: Text) {
    this.buffer += trozo.text;         // llega en varios trozos
    if (trozo.lastInTextNode) {
      console.log("titulo completo:", this.buffer);
      this.buffer = "";
    }
  }
}

// el handler text se registra igual que element, por selector
new HTMLRewriter().on("title", new ExtraerTitulo()).transform(original);

Reescribir sigue el mismo molde con element. Un caso típico es proxiar imágenes: reencaminas cada src para que pase por tu dominio en vez de servirse del origen. Y eliminar es igual de directo con remove, que descarta el elemento y su contenido según pasa —útil para quitar script de terceros que no deben llegar al cliente.

class ProxiarImagenes {
  element(el: Element) {
    const src = el.getAttribute("src");
    if (src) el.setAttribute("src", `/img?u=${encodeURIComponent(src)}`);
  }
}

class QuitarScripts {
  element(el: Element) {
    el.remove();
  }
}

Un mismo HTMLRewriter puede llevar los tres a la vez —extraer el título, proxiar imágenes y quitar scripts— y resolverlos en una sola pasada, porque los selectores se evalúan sobre el mismo flujo y no en recorridos sucesivos.

Los límites del modelo en streaming

Trabajar en un flujo impone reglas que no existen en un DOM. No hay acceso aleatorio: no puedes consultar un elemento que ya pasó ni uno que aún no ha llegado, así que toda decisión es local al elemento actual. El orden importa: los handlers se aplican en el orden en que registras los on, y sobre el HTML según fluye, de arriba abajo. Y como todo ocurre sobre la marcha, una transformación no puede depender del documento entero: si necesitas eso, HTMLRewriter no es la herramienta.

A cambio, ganas propiedades que un DOM no puede darte. La memoria no crece con la página, porque nunca la tienes entera. La latencia es mínima, porque la salida empieza a fluir en cuanto pasa el primer fragmento, sin esperar al cierre del documento. Y encadenar varias transformaciones no cuesta pasadas extra: todos los handlers viven en la misma travesía única del flujo. Esa combinación —memoria plana, primer byte temprano y composición sin coste— es justo lo que el edge necesita para reescribir páginas a escala sin convertirse en un cuello de botella.