Edge Security Acceleration:API HTMLStream

Contexte

Exemple

• Scénario

  Pour modifier toutes les balises d'ancrage <a/> d'une page HTML afin qu'elles pointent vers http://www.taobao.com, utilisez le code suivant dans Edge Routine.

• Exemple de code

  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);
    }
  };            

• Analyse des résultats

  L'exemple de code ci-dessus illustre la modification en temps réel d'un flux HTML via l'API HTMLStream. La section suivante explique le fonctionnement de HTMLStream :

  • L'API Fetch récupère une expression de flux pour la requête. Toutefois, Edge Routine n'a pas nécessairement reçu le corps de la réponse depuis la couche réseau. Par conséquent, la fréquence du garbage collection provoquée par la mise en tampon des données est réduite.

  • HTMLStream constitue également un flux compatible avec l'opération TransformStream. Dès qu'il reçoit un flux, HTMLStream appelle la fonction de rappel de réécriture pour modifier la page HTML spécifiée en temps réel. Pour modifier une page HTML, obtenez son flux de données brut. Intégrez ensuite ce flux brut dans le flux HTML que vous avez créé, comme indiqué à l'étape 2 de l'exemple de code précédent.

    • Le premier paramètre de HTMLStream est un flux, qui représente le flux de données brut de la page HTML.

    • Le deuxième paramètre de HTMLStream est un tableau, qui représente un groupe de réécriveurs. Un réécriveur est un tableau contenant un sélecteur. Le sélecteur sert à spécifier le contenu HTML à modifier et à sélectionner un objet. Certaines propriétés de l'objet seront appelées en tant que fonctions de rappel. ["a" , {....}] dans l'exemple précédent déclare un réécriveur, soit un tableau dont l'élément est 2. La chaîne « a » dans l'exemple précédent représente le sélecteur d'élément utilisé pour localiser toutes les balises d'ancrage du document. L'objet dans l'exemple précédent spécifie l'objet de rappel. Si vous choisissez d'utiliser un sélecteur d'élément, l'objet peut contenir les fonctions de rappel suivantes :

      • La fonction de rappel element. Sa signature est function(e). Cette fonction de rappel est appelée lorsque les éléments sélectionnés par le sélecteur d'élément sont analysés.

      • La fonction de rappel comments. Sa signature est function(e). Cette fonction de rappel est appelée lorsque les commentaires imbriqués dans les éléments sont analysés.

      • La fonction de rappel text. Sa signature est function(e). Cette fonction de rappel est appelée lorsque le texte des éléments est analysé. Elle peut être appelée plusieurs fois. En raison du traitement par flux, HTMLStream peut traiter un fragment d'une chaîne.

  • Vous pouvez répondre directement via HTMLStream. Cependant, HTMLStream ne met pas les données en tampon. Contrairement à parse5 et htmlparser2, HTMLStream ne génère pas d'arborescence DOM, ce qui réduit considérablement le temps de traitement et la consommation de mémoire. Ainsi, HTMLStream offre un débit élevé et une forte concurrence lors de l'analyse du contenu HTML.

Réécriveur

Syntaxe des sélecteurs d'élément

Fonctions de rappel pour les sélecteurs d'élément

Sélecteur de document

Un sélecteur de document sert à sélectionner un document spécifié. Pour utiliser un sélecteur de document, définissez le premier élément du tableau du réécriveur sur null. Dans l'opération HTMLStream, vous ne pouvez configurer qu'un seul sélecteur de document.

Fonctions de rappel pour les sélecteurs de document

Gestion des erreurs

Paramètres de rappel

Chaque fonction de rappel reçoit un objet représentant les balises HTML sélectionnées ou d'autres informations pertinentes. Cet objet est également appelé paramètre de rappel. Cette rubrique décrit les paramètres de rappel tels que Element, TextChunk et Comments.

Element

• Définition

  Cet objet est renvoyé lorsque la fonction de rappel Element est appelée. Il représente les balises HTML sélectionnées.

• Attributs

  • tagName(string) : spécifie le nom de la balise.

  • attributes(iterator) : renvoie un itérateur qui localise tous les attributs spécifiés au format [name, value].

  • removed(bool) : indique si l'élément doit être supprimé. Cet attribut est en lecture seule. Vous pouvez appeler la méthode remove() pour supprimer un élément. En général, vous devez configurer cet attribut pour ignorer les éléments déjà supprimés.

  • namespaceURI : l'URI de l'espace de noms d'un élément, par exemple l'élément SVG ou Script. Cet attribut est en lecture seule.

• Méthodes

  • Modifier les attributs

    • getAttribute(name) : interroge le nom d'un attribut d'un élément spécifié.

    • setAttribute(name, value) : définit un nom d'attribut pour un élément spécifié et modifie le nom d'attribut d'un élément spécifié.

    • hasAttribute(name) : vérifie si un nom d'attribut existe dans un élément spécifié.

    • removeAttribute(name) : supprime un nom d'attribut d'un élément spécifié.

    Remarque

    Le nom et la valeur de l'attribut doivent être de type chaîne.

  • Modifier le contenu

    • before(data, option) : insère du contenu avant l'élément spécifié (balise d'élément).

    • after(data, option) : insère du contenu après l'élément spécifié (balise d'élément).

    • prepend(data, option) : insère du contenu avant le contenu de l'élément spécifié (après la balise ouvrante de l'élément). Exemple : <div>(prepend) |aaaa|(append)</div>.

    • append(data, option) : insère du contenu après le contenu de l'élément spécifié (avant la balise fermante de l'élément). Exemple : <div>(prepend) |aaaa|(append)</div>.

    • replace(data, option) : remplace l'élément entier, y compris les balises et les balises imbriquées.

    • setInnerContent(data, option) : spécifie le contenu de l'élément et conserve les balises et les attributs.

    • remove() : supprime l'élément spécifié. Après la suppression de l'élément, la valeur de l'attribut removed passe à true.

    • removeAndKeepContent() : supprime les balises et les attributs de l'élément spécifié et conserve le contenu.

TextChunk

• Définition

  Cet objet est renvoyé lorsque la fonction de rappel Text est appelée. Il représente un fragment du texte HTML sélectionné.

• Attributs

  • removed(bool) : indique si l'élément doit être supprimé. Cet attribut est en lecture seule. Vous pouvez appeler la méthode remove() pour supprimer un élément. En général, vous devez configurer cet attribut pour ignorer les éléments déjà supprimés.

  • text(string) : spécifie le contenu textuel. Cet attribut est en lecture seule. Le texte peut être un fragment. Si la chaîne est vide, cela indique que le dernier fragment de texte est renvoyé. Dans ce cas, vous pouvez fusionner tous les fragments de texte.

  • lastInTextNode(bool) : indique s'il s'agit du dernier fragment de texte. Cet attribut est en lecture seule. Si la valeur de cet attribut est true, l'attribut text renvoie une chaîne vide.

• Méthodes

  Modifier le contenu

  • before(data, option) : insère du contenu avant l'élément spécifié (balise d'élément).

  • after(data, option) : insère du contenu après l'élément spécifié (balise d'élément).

  • replace(data, option) : remplace l'élément entier, y compris les balises et les balises imbriquées.

  • remove() : supprime l'élément spécifié. Après la suppression de l'élément, la valeur de l'attribut removed passe à true.

Comments

• Définition

  Cet objet est renvoyé lorsque la fonction de rappel Comments est appelée. Il représente les commentaires du contenu HTML sélectionné.

• Attributs

  • removed(bool) : indique si l'élément doit être supprimé. Cet attribut est en lecture seule. Vous pouvez appeler la méthode remove() pour supprimer un élément. En général, vous devez configurer cet attribut pour ignorer les éléments déjà supprimés.

  • text(string) : spécifie les commentaires existants ou les commentaires destinés à remplacer les existants. Cet attribut est en lecture et écriture.

• Méthodes

  Modifier le contenu

  • before(data, option) : insère du contenu avant l'élément spécifié (balise d'élément).

  • after(data, option) : insère du contenu après l'élément spécifié (balise d'élément).

  • replace(data, option) : remplace l'élément entier, y compris les balises et les balises imbriquées.

  • remove() : supprime l'élément spécifié. Après la suppression de l'élément, la valeur de l'attribut removed passe à true.

Doctype

• Définition

  Cet objet est renvoyé lorsque la fonction de rappel DOCTYPE est appelée. Il représente le DOCTYPE du contenu HTML sélectionné.

• Attributs

  • name(string) : spécifie le nom du DOCTYPE. Cet attribut est en lecture seule.

  • publicId(string) : renvoie un identifiant public. Si aucun identifiant public n'existe, la valeur null est renvoyée. Cet attribut est en lecture seule.

  • systemId(string) : renvoie un identifiant système. Si aucun identifiant système n'existe, la valeur null est renvoyée. Cet attribut est en lecture seule.

Docend

• Définition

  Cet objet est renvoyé lorsque la fonction de rappel Docend est appelée. Il représente la fin d'un document HTML.

• Méthodes

  append(string, option) : ajoute du contenu à la fin du document HTML.