Hydration drift terjadi ketika server-rendered UI memiliki status atau markup yang berbeda saat dijalankan ulang di klien, sehingga menimbulkan efek visual tiba-tiba atau interaksi yang gagal. Untuk tim Rust yang membangun SSR, observability bukan sekadar memantau error, melainkan menangkap perbedaan state antara render server dan hydration klien agar bisa mendeteksi mismatch lebih awal.

Artikel ini membahas akar penyebab, metrik observability yang efektif (log, trace, snapshot state), pendekatan debugging berlapis, dan validasi akhir. Termasuk contoh pencatatan state minimal dengan Dioxus/Perseus serta checklist pencegahan regresi UI.

Penyebab Render Mismatch dan Hydration Drift di SSR Rust

Hydration drift muncul ketika server dan klien tidak membagikan determinisme state atau siklus hidup yang sama. Penyebab umum:

  • State non-deterministik: misalnya timestamp, UUID, hasil request bergantung waktu yang berbeda antara server dan browser.
  • Side effect saat render: komponen melakukan fetch atau mengupdate state yang tidak dikontrol, menyisipkan markup berbeda.
  • Perbedaan konfigurasi environment: feature flag, locale, atau preferensi user yang tidak disinkronisasi saat render di server dan klien.
  • Waktu asynchronous: efek yang selesai setelah render server dapat merusak struktur DOM saat hydration klien berjalan.

Di Rust, framework seperti Dioxus atau Perseus menawarkan pendekatan SSR yang konsisten, tetapi observability tambahan diperlukan untuk mendeteksi drift sebelum pengguna merasakannya.

Observability Praktis untuk Deteksi Hydration Drift

Observability terdiri dari tiga lapis: log, trace, dan snapshot state. Masing-masing memberikan bukti yang berbeda.

1. Log Terstruktur untuk Mencatat State Penting

Catat nilai kritikal saat render server selesai. Gunakan logger terstruktur (misalnya tracing) untuk menyertakan metadata seperti komponen, route, dan payload.

use dioxus::prelude::*;
use tracing::{info_span, Instrument};

fn app(cx: Scope) -> Element {
    let user_id = 42; // contoh data

    let span = info_span!("render", component = "Home", user_id);
    cx.render(rsx! {
        div { "Halo" }
    }).instrument(span)
}

Log yang lengkap membantu memverifikasi bahwa data yang sama dipakai saat klien mencoba hydration—lebih baik jika ada request ID atau nonce untuk membandingkan log server dan event klien.

2. Trace End-to-End untuk Memetakan Lifecycle Hydration

Gunakan trace (misalnya tracing + opentelemetry) untuk menjaring timeline render dan hydration. Label seperti server_render, send_html, dan hydration_start memungkinkan mendeteksi delay atau mismatch antara state server dan klien.

Trace juga membantu mengidentifikasi apakah state yang dilihat server berbeda pada saat hydration klien dimulai (misalnya menandai cache yang sudah kadaluarsa).

3. Snapshot State untuk Verifikasi Konsistensi

Setelah render, rekam snapshot state yang kritikal (misalnya props, computed value). Kirim snapshot tersebut sebagai JSON ter-enkripsi di DOM (meta tag atau script type="application/json"). Klien membaca dan membandingkan saat hydration.

fn serialize_state(cx: Scope) -> String {
    let state = serde_json::json!({
        "user_id": 42,
        "theme": "light",
    });
    serde_json::to_string(&state).unwrap()
}

cx.render(rsx! {
    script { "type": "application/json", "data-state": "{serialize_state(cx)}" }
})

Biarkan klien mem-parsing data ini saat inisialisasi untuk memastikan state awalnya identik.

Pendekatan Debugging Berlapis hingga Validasi Akhir

Hydration drift bisa sulit direproduksi. Gunakan pendekatan bertingkat berikut:

  1. Repro via logs: cek log server untuk rute bermasalah, bandingkan dengan log event hydration (klien harus mengirim event khusus saat hydration selesai).
  2. Trace correlation: pastikan spans memiliki ID request yang sama, lalu bandingkan timeline render server dan langkah hydration klien.
  3. Snapshot compare: klien menulis state snapshot terakhir ke console; bila berbeda dengan server, catat perbedaan field per field.
  4. Simulasi environment: jalankan build SSR + hydration di lingkungan staging dengan data terkontrol (mock waktu, feature flag) untuk menghilangkan nondeterministic.
  5. Regression test: buat test snapshot yang menjalankan hydration untuk route kritis, memeriksa DOM dan state.

Contoh Observability Hydration Minimal

Berikut contoh kecil untuk mencatat state server dan memverifikasinya saat hydration di Dioxus.

fn server_render(cx: Scope) -> Element {
    let state = ServerState { count: 5 };
    let serialized = serde_json::to_string(&state).unwrap();

    cx.render(rsx! {
        div { "Count: {state.count}" }
        script { "type": "application/json", "id": "ssr-state", {serialized} }
    })
}

#[derive(Serialize)]
struct ServerState { count: u32 }

fn hydrate(cx: Scope) -> Element {
    use web_sys::window;
    if let Some(window) = window() {
        if let Some(element) = window.document().get_element_by_id("ssr-state") {
            let text = element.text_content().unwrap_or_default();
            tracing::info!("hydration state", data = %text);
        }
    }
    cx.render(rsx!(div { "Hydrated" }))
}

Log dari hydration di atas bisa dibandingkan dengan log server untuk memastikan count sama.

Checklist Pencegahan Regresi Hydration Drift

  • Catat state deterministik di server dan sertakan identifikasi request.
  • Pastikan side effect terkontrol (hindari fetch data acak selama render).
  • Gunakan trace untuk menghubungkan lifecycle SSR dan hydration.
  • Verifikasi snapshot state yang dikirim ke klien sebelum hydration.
  • Jalankan test integral yang memeriksa DOM akhir setelah hydration.
  • Buat alert bila field snapshot di klien berbeda dari referensi server.
  • Dokumentasikan state-flow utama dan kontrak SSR-hydration.

Dengan observability berlapis dan validasi sistematis, tim Rust dapat mendeteksi dan mencegah hydration drift sebelum sampai ke pengguna akhir tanpa bergantung pada tebakan.