Edge Security Acceleration:HTMLStream API

Informasi latar belakang

Contoh

• Skenario

  Jika Anda ingin memodifikasi semua tag jangkar <a/> dalam halaman HTML untuk menghubungkannya ke http://www.taobao.com, gunakan kode berikut di Edge Routine.

• Kode Contoh

  async function handleRequest(request) {
    // 1. Dalam contoh ini, halaman HTML yang ingin Anda modifikasi dikembalikan.
    const response = await fetch("http://www.example.com");
    // 2. Konfigurasikan parser berbasis pemrosesan aliran untuk mengelola konten HTML. Parser ini mendukung beberapa pemilih CSS.
    // Tentukan metode untuk menangkap sintaksis dan daftarkan fungsi callback untuk penulisan ulang.
    const htmlStream = new HTMLStream(
      response.body, // Tentukan aliran HTML yang ingin Anda modifikasi.
      [[
        "a",         // Pemilih elemen. Ini menentukan bahwa semua tag jangkar dipilih.
        {  
          // Daftarkan fungsi callback. Fungsi callback elemen dapat dipanggil di dalam tag jangkar atau di dalam node elemen dari API DOM (Document Object Model).
          // Di dalam fungsi callback, Anda dapat mengubah objek event (e).
          element: function(e) {
            // Modifikasi atribut href.
            e.setAttribute("href", "http://www.taobao.com");
          }
        }
      ]]);
    
    // 3. Kembalikan permintaan yang telah dimodifikasi ke browser. HTMLStream adalah aliran yang dapat dibaca.
    // Anda dapat menggunakan HTMLStream di semua skenario yang mendukung ReadableStream.
    return new Response(htmlStream);
  }
  
              export default {
    async fetch(request) {
      return handleRequest(request);
    }
  };            

• Analisis Hasil

  Kode contoh di atas menunjukkan cara memodifikasi aliran HTML secara real-time menggunakan HTMLStream API. Berikut adalah penjelasan tentang cara kerja HTMLStream:

  • API Fetch mengambil ekspresi aliran untuk permintaan. Namun, Edge Routine mungkin belum mengambil badan respons dari lapisan jaringan. Akibatnya, frekuensi pengumpulan sampah akibat penyanggaan data berkurang.

  • HTMLStream juga merupakan aliran yang mendukung operasi TransformStream. Setelah HTMLStream menerima aliran, HTMLStream memanggil fungsi callback penulisan ulang untuk memodifikasi halaman HTML yang ditentukan secara real-time. Jika Anda ingin memodifikasi halaman HTML, Anda harus mendapatkan aliran data mentah dari halaman tersebut. Kemudian, Anda dapat meletakkan aliran data mentah ke dalam aliran HTML yang telah Anda buat, seperti yang dijelaskan pada Langkah 2 dalam kode contoh di atas.

    • Parameter pertama dari HTMLStream adalah aliran, yang mewakili aliran data mentah dari halaman HTML.

    • Parameter kedua dari HTMLStream adalah array, yang mewakili sekelompok penulis ulang. Penulis ulang adalah array yang mencakup pemilih. Pemilih digunakan untuk menentukan konten HTML yang ingin Anda modifikasi dan memilih objek. Beberapa atribut dari objek akan dipanggil sebagai fungsi callback. ["a" , {....}] dalam contoh di atas digunakan untuk mendeklarasikan penulis ulang, yang mewakili array dengan dua elemen. String "a" dalam contoh di atas mewakili pemilih elemen yang digunakan untuk menemukan semua tag jangkar dalam dokumen. Objek dalam contoh di atas menentukan objek callback. Jika Anda memilih untuk menggunakan pemilih elemen, objek tersebut dapat mencakup fungsi callback berikut:

      • Fungsi callback element. Tanda tangan dari fungsi callback ini adalah function(e). Fungsi callback ini dipanggil ketika elemen-elemen yang dipilih oleh pemilih elemen diuraikan.

      • Fungsi callback comments. Tanda tangan dari fungsi callback ini adalah function(e). Fungsi callback ini dipanggil ketika komentar-komentar yang bersarang di dalam elemen diuraikan.

      • Fungsi callback text. Tanda tangan dari fungsi callback ini adalah function(e). Fungsi callback ini dipanggil ketika teks di dalam elemen diuraikan. Fungsi callback ini dapat dipanggil beberapa kali karena pemrosesan aliran, HTMLStream mungkin sedang memproses sebagian dari string.

  • Anda dapat langsung merespons HTMLStream. Namun, HTMLStream tidak menyangga data. Berbeda dengan parse5 dan htmlparser2, HTMLStream tidak menghasilkan pohon DOM, yang secara signifikan mengurangi waktu pemrosesan dan konsumsi memori. Dengan cara ini, HTMLStream dapat memberikan throughput tinggi dan konkurensi saat mem-parsing konten HTML.

Penulis Ulang

Sintaks pemilih elemen

Fungsi callback untuk pemilih elemen

Pemilih dokumen

Pemilih dokumen digunakan untuk memilih dokumen tertentu. Untuk menggunakan pemilih dokumen, atur elemen pertama dalam array penulis ulang ke null. Dalam operasi HTMLStream, Anda hanya dapat mengonfigurasi satu pemilih dokumen.

Fungsi callback untuk pemilih dokumen

Penanganan kesalahan

Parameter callback

Setiap fungsi callback menerima objek yang mewakili tag HTML yang dipilih atau informasi relevan lainnya. Objek ini juga dikenal sebagai parameter callback. Topik ini menjelaskan parameter callback seperti Element, TextChunk, dan Comments.

Element

• Definisi

  Objek ini dikembalikan ketika fungsi callback Element dipanggil. Objek ini mewakili tag HTML yang dipilih.

• Atribut

  • tagName(string): menentukan nama tag.

  • attributes(iterator): mengembalikan iterator yang menemukan semua atribut yang ditentukan dalam format [name, value].

  • removed(bool): menentukan apakah elemen dihapus. Atribut ini hanya-baca. Anda dapat memanggil metode remove() untuk menghapus elemen. Biasanya, Anda harus mengonfigurasi atribut ini untuk mengabaikan elemen yang sudah dihapus.

  • namespaceURI: URI namespace dari elemen, seperti elemen SVG atau Script. Atribut ini hanya-baca.

• Metode

  • Modifikasi Atribut

    • getAttribute(name): meminta nama atribut elemen tertentu.

    • setAttribute(name, value): menetapkan nama atribut untuk elemen tertentu dan memodifikasi nama atribut elemen tertentu.

    • hasAttribute(name): meminta apakah nama atribut ada dalam elemen tertentu.

    • removeAttribute(name): menghapus nama atribut dari elemen tertentu.

    null

    Nama atribut dan nilai harus bertipe string.

  • Modifikasi Konten

    • before(data, option): menyisipkan konten sebelum elemen tertentu (tag elemen).

    • after(data, option): menyisipkan konten setelah elemen tertentu (tag elemen).

    • prepend(data, option): menyisipkan konten sebelum konten elemen tertentu (setelah tag pembuka elemen). Contoh: <div>(prepend) |aaaa|(append)</div>.

    • append(data, option): menyisipkan konten setelah konten elemen tertentu (sebelum tag penutup elemen). Contoh: <div>(prepend) |aaaa|(append)</div>.

    • replace(data, option): mengganti seluruh elemen, termasuk tag dan tag bersarang.

    • setInnerContent(data, option): menentukan konten elemen dan mempertahankan tag dan atribut.

    • remove(): menghapus elemen tertentu. Setelah elemen dihapus, nilai atribut removed berubah menjadi true.

    • removeAndKeepContent(): menghapus tag dan atribut elemen tertentu dan mempertahankan konten.

TextChunk

• Definisi

  Objek ini dikembalikan ketika fungsi callback Text dipanggil. Objek ini mewakili potongan teks HTML yang dipilih.

• Atribut

  • removed(bool): menentukan apakah elemen dihapus. Atribut ini hanya-baca. Anda dapat memanggil metode remove() untuk menghapus elemen. Biasanya, Anda harus mengonfigurasi atribut ini untuk mengabaikan elemen yang sudah dihapus.

  • text(string): menentukan konten teks. Atribut ini hanya-baca. Teks mungkin merupakan potongan teks. Jika string kosong, itu menunjukkan bahwa potongan teks terakhir dikembalikan. Dalam hal ini, Anda dapat menggabungkan semua potongan teks.

  • lastInTextNode(bool): menentukan apakah ini adalah potongan teks terakhir. Atribut ini hanya-baca. Jika nilai atribut ini adalah true, atribut text mengembalikan string kosong.

• Metode

  Modifikasi Konten

  • before(data, option): menyisipkan konten sebelum elemen tertentu (tag elemen).

  • after(data, option): menyisipkan konten setelah elemen tertentu (tag elemen).

  • replace(data, option): mengganti seluruh elemen, termasuk tag dan tag bersarang.

  • remove(): menghapus elemen tertentu. Setelah elemen dihapus, nilai atribut removed berubah menjadi true.

Comments

• Definisi

  Objek ini dikembalikan ketika fungsi callback Comments dipanggil. Objek ini mewakili komentar dalam konten HTML yang dipilih.

• Atribut

  • removed(bool): menentukan apakah elemen dihapus. Atribut ini hanya-baca. Anda dapat memanggil metode remove() untuk menghapus elemen. Biasanya, Anda harus mengonfigurasi atribut ini untuk mengabaikan elemen yang sudah dihapus.

  • text(string): menentukan komentar yang ada atau komentar untuk menimpa yang sudah ada. Atribut ini dapat dibaca dan ditulis.

• Metode

  Modifikasi Konten

  • before(data, option): menyisipkan konten sebelum elemen tertentu (tag elemen).

  • after(data, option): menyisipkan konten setelah elemen tertentu (tag elemen).

  • replace(data, option): mengganti seluruh elemen, termasuk tag dan tag bersarang.

  • remove(): menghapus elemen tertentu. Setelah elemen dihapus, nilai atribut removed berubah menjadi true.

Doctype

• Definisi

  Objek ini dikembalikan ketika fungsi callback DOCTYPE dipanggil. Objek ini mewakili DOCTYPE dari konten HTML yang dipilih.

• Atribut

  • name(string): menentukan nama DOCTYPE. Atribut ini hanya-baca.

  • publicId(string): mengembalikan pengenal publik. Jika tidak ada pengenal publik, nilai null dikembalikan. Atribut ini hanya-baca.

  • systemId(string): mengembalikan pengenal sistem. Jika tidak ada pengenal sistem, nilai null dikembalikan. Atribut ini hanya-baca.

Docend

• Definisi

  Objek ini dikembalikan ketika fungsi callback Docend dipanggil. Objek ini mewakili akhir dokumen HTML.

• Metode

  append(string, option): menambahkan konten ke akhir dokumen HTML.