Edge Security Acceleration:API HTMLStream

Visão geral

Exemplo

• Cenário

  Para modificar todas as tags de âncora <a/> em uma página HTML e vinculá-las a http://www.taobao.com, use o código do Edge Routine a seguir.

• Código de exemplo

  async function handleRequest(request) {
    // 1. In this example, the HTML page that you want to modify is returned. 
    const response = await fetch("http://www.example.com");
    // 2. Configure the stream processing-based parser to manage HTML content. The parser supports multiple CSS selectors.
    // Specify the method for capturing the syntax and register a callback function for rewriting. 
    const htmlStream = new HTMLStream(
      response.body, // Specify the HTML flow that you want to modify.
      [[
        "a",         // The element selector. This specifies that all the anchor tags are selected. 
        {  
          // Register a callback function. The element callback function can be called in the anchor tags or in the element nodes of the Document Object Model (DOM) API. 
          // In the callback function, you can change the event object (e). 
          element: function(e) {
            // Modify the href attribute.
            e.setAttribute("href", "http://www.taobao.com");
          }
        }
      ]]);
    
    // 3. Return the modified request to the browser. HTMLStream is a readable stream.
    // You can use HTMLStream in all scenarios that support ReadableStream. 
    return new Response(htmlStream);
  }
  
              export default {
    async fetch(request) {
      return handleRequest(request);
    }
  };            

• Análise do resultado

  O código de exemplo modifica um fluxo HTML em tempo real com a API HTMLStream. O HTMLStream funciona da seguinte maneira:

  • A Fetch API recupera uma expressão de fluxo para a requisição. O Edge Routine pode ainda não ter recuperado o corpo da resposta, o que reduz a coleta de lixo proveniente do buffer de dados.

  • O HTMLStream é um fluxo compatível com TransformStream. Ele chama funções de callback de reescrita para modificar páginas HTML em tempo real. Passe o fluxo de dados brutos para o fluxo HTMLStream conforme mostrado na Etapa 2 do código de exemplo.

    • O primeiro parâmetro é um fluxo que representa os dados HTML brutos.

    • O segundo parâmetro é um array de rewriters. Cada rewriter é um array de dois elementos: uma string de seletor e um objeto de callback. No exemplo, ["a" , {....}] declara um rewriter onde "a" seleciona todas as tags de âncora. O objeto de callback pode conter as seguintes funções:

      • element: function(e). Chamada quando os elementos correspondentes são analisados.

      • comments: function(e). Chamada quando comentários aninhados nos elementos correspondentes são analisados.

      • text: function(e). Chamada quando o texto nos elementos correspondentes é analisado. Pode ser chamada várias vezes porque o HTMLStream processa o texto em blocos.

  • Diferentemente do parse5 e do htmlparser2, o HTMLStream não armazena dados em buffer nem gera uma árvore DOM. Isso reduz o tempo de processamento e o consumo de memória, permitindo alto throughput e concorrência na análise de HTML.

Rewriter

Sintaxe dos seletores de elemento

Funções de callback para seletores de elemento

Seletor de documento

Um seletor de documento tem como alvo o documento inteiro. Defina o primeiro elemento no array do rewriter como null. Apenas um seletor de documento é permitido por operação HTMLStream.

Funções de callback para seletores de documento

Tratamento de erros

Parâmetros de callback

Cada função de callback recebe um objeto que representa as tags HTML selecionadas ou informações relacionadas. Este tópico descreve os tipos de parâmetros de callback: Element, TextChunk e Comments.

Element

• Definição

  Retornado quando a função de callback Element é chamada. Representa as tags HTML selecionadas.

• Atributos

  • tagName(string): o nome da tag.

  • attributes(iterator): retorna um iterador sobre todos os atributos no formato [name, value].

  • removed(bool): indica se o elemento foi excluído. Somente leitura. Use remove() para excluir um elemento. Verifique este atributo para ignorar elementos já excluídos.

  • namespaceURI: o URI do namespace do elemento (por exemplo, SVG ou Script). Somente leitura.

• Métodos

  • Modificar atributos

    • getAttribute(name): obtém o valor de um atributo.

    • setAttribute(name, value): define ou modifica um atributo.

    • hasAttribute(name): verifica se um atributo existe.

    • removeAttribute(name): remove um atributo.

    Nota

    Tanto o nome quanto o valor do atributo devem ser strings.

  • Modificar conteúdo

    • before(data, option): insere conteúdo antes da tag do elemento.

    • after(data, option): insere conteúdo após a tag do elemento.

    • prepend(data, option): insere conteúdo após a tag de abertura. Exemplo: <div>(prepend) |aaaa|(append)</div>.

    • append(data, option): insere conteúdo antes da tag de fechamento. Exemplo: <div>(prepend) |aaaa|(append)</div>.

    • replace(data, option): substitui todo o elemento, incluindo tags e conteúdo aninhado.

    • setInnerContent(data, option): substitui o conteúdo do elemento preservando tags e atributos.

    • remove(): exclui o elemento. Define removed como true.

    • removeAndKeepContent(): remove tags e atributos, mas preserva o conteúdo.

TextChunk

• Definição

  Retornado quando a função de callback Text é chamada. Representa um bloco do texto HTML selecionado.

• Atributos

  • removed(bool): indica se o elemento foi excluído. Somente leitura. Use remove() para excluir.

  • text(string): o conteúdo de texto. Somente leitura. Pode ser um bloco parcial. Uma string vazia indica o último bloco — una todos os blocos para obter o texto completo.

  • lastInTextNode(bool): indica se este é o último bloco. Somente leitura. Quando true, o atributo text retorna uma string vazia.

• Métodos

  Modificar conteúdo

  • before(data, option): insere conteúdo antes do elemento especificado (tag do elemento).

  • after(data, option): insere conteúdo após o elemento especificado (tag do elemento).

  • replace(data, option): substitui todo o elemento, incluindo as tags e tags aninhadas.

  • remove(): exclui o elemento especificado. Após a exclusão do elemento, o valor do atributo removed muda para true.

Comments

• Definição

  Retornado quando a função de callback Comments é chamada. Representa comentários no conteúdo HTML selecionado.

• Atributos

  • removed(bool): indica se o elemento foi excluído. Somente leitura. Use remove() para excluir.

  • text(string): o texto do comentário. Leitura e escrita — defina para sobrescrever comentários existentes.

• Métodos

  Modificar conteúdo

  • before(data, option): insere conteúdo antes do elemento especificado (tag do elemento).

  • after(data, option): insere conteúdo após o elemento especificado (tag do elemento).

  • replace(data, option): substitui todo o elemento, incluindo as tags e tags aninhadas.

  • remove(): exclui o elemento especificado. Após a exclusão do elemento, o valor do atributo removed muda para true.

Doctype

• Definição

  Retornado quando a função de callback DOCTYPE é chamada. Representa o DOCTYPE do conteúdo HTML.

• Atributos

  • name(string): o nome do DOCTYPE. Somente leitura.

  • publicId(string): o identificador público, ou null se não existir. Somente leitura.

  • systemId(string): o identificador de sistema, ou null se não existir. Somente leitura.

Docend

• Definição

  Retornado quando a função de callback Docend é chamada. Representa o fim do documento HTML.

• Métodos

  append(string, option): anexa conteúdo ao final do documento HTML.