Deploy Viewer OOXML Browser: Canary, Rollback, dan Observability

Deploy viewer OOXML browser tidak boleh diperlakukan seperti merilis komponen UI biasa. Viewer dokumen Office/OOXML berurusan dengan file berukuran besar, variasi format yang luas, rendering kompleks, serta ekspektasi pengguna bahwa dokumen dapat dibuka dengan benar. Strategi rilis yang aman perlu menggabungkan feature flag, canary bertahap, fallback ke download atau preview lama, rollback cepat, dan observability yang cukup detail untuk membedakan bug render, masalah performa, dan dokumen yang memang tidak didukung.

Artikel ini membahas pendekatan praktis untuk merilis fitur viewer dokumen Office/OOXML di browser, terinspirasi dari proyek seperti Silurus/ooxml atau office-open-xml-viewer. Fokusnya bukan pada implementasi parser OOXML secara internal, melainkan pada cara mengoperasionalkan fitur tersebut agar risiko produksi tetap terkendali.

Arsitektur rilis yang aman untuk viewer OOXML browser

Sebelum membahas canary dan rollback, tentukan batas tanggung jawab sistem. Viewer OOXML di browser biasanya terdiri dari beberapa bagian:

Frontend viewer: mengambil file, memproses OOXML, dan merender halaman atau struktur dokumen ke DOM/canvas/SVG.
Backend metadata: menyediakan informasi file seperti MIME type, ukuran, hak akses, URL bertanda tangan, dan versi dokumen.
Feature flag service: menentukan apakah user tertentu memakai viewer baru, viewer lama, atau fallback download.
Telemetry pipeline: menerima event render, error, metrik performa, dan log korelasi.
Fallback path: jalur aman ketika viewer baru gagal, misalnya preview lama, PDF hasil konversi, atau tombol download.

Pemisahan ini penting karena rollback tidak selalu berarti deploy ulang. Dalam insiden ringan, Anda seharusnya bisa mematikan viewer baru dari feature flag tanpa menunggu pipeline build dan deploy selesai.

Catatan: Jika viewer berjalan sepenuhnya di browser, beban CPU dan memori berpindah ke perangkat pengguna. Itu mengurangi beban server, tetapi memperbesar variasi performa karena perangkat, browser, dan ukuran dokumen sangat beragam.

Feature flag sebagai pagar utama rilis

Feature flag memungkinkan rilis kode terpisah dari aktivasi fitur. Kode viewer baru boleh sudah ada di production, tetapi hanya aktif untuk segmen tertentu. Untuk viewer OOXML browser, flag sebaiknya tidak hanya berupa boolean global. Minimal, flag perlu mempertimbangkan segmen user, tipe file, ukuran file, browser, dan organisasi atau tenant.

Contoh kontrak flag dari backend

Backend dapat mengembalikan keputusan yang eksplisit agar frontend tidak menebak-nebak. Contoh respons berikut bersifat generik dan dapat diterapkan dengan service flag internal maupun vendor feature flag.

{
  "documentId": "doc_123",
  "viewer": {
    "mode": "ooxml_browser",
    "reason": "canary_internal_users",
    "fallbackMode": "legacy_preview",
    "maxFileSizeBytes": 10485760,
    "telemetrySampleRate": 1.0
  },
  "correlationId": "req_9f2c1b"
}

Beberapa hal yang sengaja dibuat eksplisit:

mode: menentukan jalur render, misalnya ooxml_browser, legacy_preview, atau download_only.
reason: membantu debugging ketika user tertentu masuk atau keluar dari canary.
fallbackMode: menentukan perilaku ketika render gagal.
maxFileSizeBytes: mencegah dokumen besar diproses oleh viewer yang belum siap.
correlationId: menghubungkan log frontend, backend, dan telemetry.

Urutan evaluasi flag yang disarankan

Gunakan urutan evaluasi yang konservatif. Contohnya:

Validasi hak akses dokumen.
Tolak file yang jelas tidak didukung, misalnya format di luar target.
Cek batas ukuran file dan kebijakan tenant.
Cek kill switch global.
Cek allowlist internal atau QA.
Cek canary berdasarkan segmen user.
Jika tidak memenuhi, arahkan ke preview lama atau download.

Urutan ini menghindari kasus di mana user masuk canary tetapi dokumennya terlalu besar atau tidak sesuai format.

Canary per segmen user, bukan hanya persentase acak

Canary yang baik tidak hanya “aktifkan 5% user”. Untuk viewer dokumen, segmen canary harus mencerminkan variasi risiko. Persentase acak berguna, tetapi perlu dilengkapi dengan segmentasi yang lebih bermakna.

Segmentasi yang praktis

Internal users: engineer, QA, support, dan tim produk. Cocok untuk mendeteksi error kasar sebelum user eksternal terkena dampak.
Tenant kecil atau low-risk: organisasi dengan volume dokumen rendah dan jalur support yang jelas.
Tipe dokumen tertentu: misalnya mulai dari DOCX sederhana sebelum menyalakan PPTX atau XLSX jika kompleksitas renderer berbeda.
Ukuran file: mulai dari file kecil, lalu naikkan batas ukuran secara bertahap.
Browser modern yang didukung: hindari mengaktifkan di browser yang belum diuji.
Region atau bahasa: berguna jika dokumen memiliki variasi font, locale, atau jaringan CDN yang berbeda.

Contoh tahapan rilis yang aman:

Dark launch: kode sudah ter-deploy, tetapi viewer baru belum digunakan user. Telemetry dasar dan endpoint metadata diuji.
Internal canary: aktif untuk user internal dan dokumen uji.
External canary terbatas: aktif untuk tenant tertentu, ukuran file kecil, dan format terbatas.
Progressive rollout: perluas persentase user dan variasi dokumen jika metrik stabil.
Default on: viewer baru menjadi default, tetapi fallback dan kill switch tetap dipertahankan.

Fallback dan rollback cepat

Viewer baru harus gagal dengan aman. Pengguna yang gagal membuka dokumen sebaiknya tetap memiliki jalur untuk mengakses file, misalnya preview lama atau download. Jangan menampilkan error buntu tanpa opsi lanjutan.

Pola fallback di frontend

Contoh berikut menunjukkan wrapper render yang mencatat telemetry, membatasi jalur error, dan memindahkan user ke fallback jika viewer baru gagal.

async function openDocument(documentId) {
  const decision = await fetchViewerDecision(documentId);
  const ctx = {
    documentId,
    correlationId: decision.correlationId,
    viewerMode: decision.viewer.mode
  };

  if (decision.viewer.mode !== 'ooxml_browser') {
    return openFallback(documentId, decision.viewer.fallbackMode, ctx);
  }

  const startedAt = performance.now();

  try {
    const file = await fetchDocumentBlob(documentId, decision.correlationId);

    if (file.size > decision.viewer.maxFileSizeBytes) {
      reportEvent('viewer_ooxml_skipped_file_too_large', {
        ...ctx,
        fileSizeBytes: file.size
      });
      return openFallback(documentId, decision.viewer.fallbackMode, ctx);
    }

    await renderOoxmlInBrowser(file, {
      correlationId: decision.correlationId
    });

    reportEvent('viewer_ooxml_render_success', {
      ...ctx,
      fileSizeBytes: file.size,
      renderTimeMs: Math.round(performance.now() - startedAt)
    });
  } catch (error) {
    reportEvent('viewer_ooxml_render_error', {
      ...ctx,
      errorName: error?.name || 'UnknownError',
      errorMessage: String(error?.message || error).slice(0, 300),
      renderTimeMs: Math.round(performance.now() - startedAt)
    });

    return openFallback(documentId, decision.viewer.fallbackMode, ctx);
  }
}

Prinsip penting dari contoh tersebut:

Error render tidak menghentikan akses dokumen.
Keputusan fallback berasal dari backend atau flag, bukan hardcode tersebar di banyak komponen.
Telemetry dikirim untuk sukses, gagal, dan skip karena kebijakan.
Log membawa correlationId agar investigasi tidak hanya mengandalkan screenshot user.

Rollback tanpa deploy ulang

Siapkan minimal tiga tuas rollback:

Kill switch global: mematikan viewer OOXML browser untuk semua user.
Rollback per segmen: mematikan hanya untuk tenant, browser, format, atau batas ukuran tertentu.
Rollback per versi viewer: jika bundle viewer baru bermasalah, arahkan user ke versi sebelumnya atau fallback.

Rollback yang baik harus bisa dilakukan oleh engineer on-call atau release manager dengan prosedur tertulis. Hindari rollback yang hanya bisa dilakukan oleh satu orang yang memahami detail feature flag.

Observability yang wajib dipasang

Tanpa observability, canary hanya menjadi tebakan bertahap. Untuk viewer OOXML browser, observability perlu menjawab pertanyaan: berapa banyak dokumen berhasil dibuka, mengapa gagal, dokumen seperti apa yang bermasalah, dan apakah performa pengguna memburuk.

Metrik utama

Error render: jumlah dan rasio error saat parsing, layouting, fetching asset, atau rendering.
Dokumen gagal dibuka: bedakan gagal karena permission, network, format tidak didukung, file rusak, timeout, dan error renderer.
Ukuran file: catat bucket ukuran, bukan hanya rata-rata. File besar sering menjadi sumber memory pressure.
Waktu render: ukur dari klik buka dokumen sampai halaman pertama terlihat, serta sampai render selesai jika relevan.
Memory pressure: pantau sinyal seperti crash, tab reload, out-of-memory yang dapat terdeteksi, atau fallback karena batas memori internal. API memori browser tidak selalu tersedia, jadi desain telemetry harus tahan terhadap data yang kosong.
Core Web Vitals: pantau LCP, INP, dan CLS di halaman viewer. Viewer yang memblokir main thread dapat memperburuk interaksi.
Log korelasi: gunakan ID yang sama dari request backend sampai event frontend.

Event telemetry yang berguna

Gunakan nama event yang stabil dan field yang tidak mengandung isi dokumen. Jangan mengirim teks dokumen, nama file sensitif, atau konten OOXML ke telemetry.

{
  "event": "viewer_ooxml_render_error",
  "timestamp": "2026-08-30T10:15:00Z",
  "correlationId": "req_9f2c1b",
  "documentIdHash": "7b8f...",
  "tenantIdHash": "a19c...",
  "viewerVersion": "2026.08.30",
  "browser": "Chromium-based",
  "fileType": "docx",
  "fileSizeBucket": "5mb_10mb",
  "renderTimeMs": 4210,
  "errorName": "RenderError",
  "fallbackMode": "legacy_preview"
}

Perhatikan penggunaan hash atau bucket. Untuk observability produksi, Anda biasanya tidak membutuhkan nama file asli atau isi dokumen. Data yang terlalu detail dapat menciptakan risiko privasi dan kepatuhan.

Trace dan log korelasi

Jika sistem Anda menggunakan distributed tracing, buat span untuk proses pengambilan metadata dan file. Di frontend, tidak semua organisasi mengirim trace penuh dari browser, tetapi setidaknya sertakan correlationId di header dan event telemetry.

async function fetchDocumentBlob(documentId, correlationId) {
  const response = await fetch(`/api/documents/${documentId}/content`, {
    headers: {
      'X-Correlation-Id': correlationId
    }
  });

  if (!response.ok) {
    throw new Error(`Document fetch failed: ${response.status}`);
  }

  return response.blob();
}

Dengan pola ini, investigasi dapat menghubungkan laporan user, log API, status storage, CDN, dan error render di frontend.

Checklist rilis viewer OOXML browser

Checklist berikut dapat digunakan sebelum menaikkan canary ke segmen yang lebih luas.

Sebelum rilis

Feature flag memiliki kill switch global dan rollback per segmen.
Fallback ke preview lama atau download sudah diuji dari jalur error nyata, bukan hanya dari kondisi manual.
Batas ukuran file dan tipe file sudah didefinisikan.
Dataset regresi berisi dokumen nyata yang sudah disanitasi: tabel, gambar, font berbeda, header/footer, komentar, hyperlink, dan dokumen besar.
Telemetry sukses, gagal, skip, dan fallback sudah masuk dashboard.
Dashboard memisahkan error berdasarkan viewer version, file type, file size bucket, browser, dan tenant.
Alert disiapkan untuk kenaikan error render, fallback rate, dan waktu render yang memburuk.
Support dan on-call mengetahui cara mematikan flag.
Dokumentasi perilaku fallback sudah tersedia untuk tim support.

Saat canary

Mulai dari internal user dan dokumen kecil.
Naikkan canary berdasarkan data, bukan jadwal semata.
Periksa sample error secara manual untuk memastikan klasifikasi error benar.
Bandingkan keluhan support dengan telemetry.
Jangan menaikkan canary jika fallback rate naik tanpa penjelasan.

Setelah rilis

Verifikasi rasio dokumen berhasil dibuka.
Periksa p95 atau percentile tinggi waktu render, bukan hanya rata-rata.
Periksa Core Web Vitals khusus halaman viewer.
Audit apakah fallback masih berfungsi setelah viewer baru menjadi default.
Tambahkan dokumen bermasalah ke suite regresi setelah disanitasi.

Skenario insiden ringan dan responsnya

Misalnya setelah canary dinaikkan ke tenant eksternal terbatas, dashboard menunjukkan kenaikan viewer_ooxml_render_error pada DOCX berukuran 5-10 MB di browser tertentu. User masih bisa mengunduh dokumen, tetapi preview gagal.

Langkah respons

Konfirmasi dampak: lihat jumlah tenant, jumlah user, tipe file, ukuran file, dan browser yang terkena.
Aktifkan rollback terarah: matikan viewer baru hanya untuk kombinasi file size bucket atau browser yang bermasalah jika memungkinkan.
Pastikan fallback bekerja: cek event fallback dan laporan support. Jika fallback gagal, gunakan kill switch global.
Kumpulkan artefak aman: correlationId, versi viewer, errorName, ukuran bucket, dan dokumen contoh yang sudah mendapat izin atau sudah disanitasi.
Reproduksi di lingkungan staging: gunakan build dan flag yang sama dengan production.
Perbaiki dan uji regresi: tambahkan kasus dokumen ke test suite sebelum rilis ulang.

Poin penting: jangan langsung menaikkan timeout atau batas memori tanpa memahami penyebab. Masalah render sering kali berasal dari struktur dokumen tertentu, font fallback, gambar besar, atau operasi sinkron yang memblokir main thread.

Format postmortem singkat

Untuk insiden ringan, postmortem tidak perlu panjang, tetapi harus cukup spesifik agar tindakan pencegahan jelas.

Judul:
Render DOCX gagal pada canary viewer OOXML browser untuk file 5-10 MB

Ringkasan:
Pada tanggal ..., sebagian user canary mengalami kegagalan preview DOCX.
Fallback download tetap tersedia, tetapi preview lama tidak aktif untuk sebagian segmen.

Dampak:
- Tenant terdampak: ...
- User terdampak: ...
- Durasi: ...
- Jalur akses dokumen yang masih tersedia: download / legacy preview

Timeline:
- 10:05 Canary dinaikkan ke segmen eksternal
- 10:20 Alert render error meningkat
- 10:27 Rollback per file size bucket diterapkan
- 11:10 Penyebab direproduksi di staging

Penyebab utama:
Renderer gagal menangani kombinasi layout tertentu pada dokumen besar.

Faktor pendukung:
- Dataset regresi belum mencakup pola dokumen tersebut
- Alert fallback rate belum dipisahkan per ukuran file

Yang berjalan baik:
- Kill switch per segmen berfungsi
- CorrelationId mempermudah investigasi

Yang perlu diperbaiki:
- Tambah dokumen regresi tersanitasi
- Pisahkan dashboard berdasarkan file size bucket
- Uji fallback legacy preview pada semua segmen canary

Action items:
- [Owner] Tambah test fixture layout terkait
- [Owner] Tambah alert render error per file size bucket
- [Owner] Perbarui checklist rilis fallback

Mencegah regresi render sebelum masuk produksi

Regresi render sulit dihindari karena variasi dokumen OOXML sangat besar. Tujuannya adalah memperkecil kemungkinan regresi lolos dan mempercepat deteksi ketika terjadi.

Strategi pengujian yang efektif

Golden document set: kumpulkan dokumen uji yang mewakili tabel kompleks, gambar, style, font, header/footer, list bertingkat, dan dokumen besar. Pastikan dokumen disanitasi dan boleh digunakan untuk testing.
Visual regression test: bandingkan screenshot render untuk halaman atau bagian tertentu. Gunakan toleransi yang realistis karena perbedaan font dan platform bisa menghasilkan variasi kecil.
Contract test metadata: pastikan backend selalu mengirim mode, fallbackMode, batas ukuran, dan correlationId.
Failure injection: uji kondisi fetch gagal, file terlalu besar, parser throw error, dan timeout agar fallback benar-benar berjalan.
Performance budget: tetapkan ambang internal untuk waktu render dan ukuran bundle. Nilainya harus berdasarkan baseline aplikasi Anda, bukan angka generik.
Browser matrix: uji browser yang secara resmi Anda dukung. Jangan mengandalkan satu browser lokal developer.

Kesalahan umum

Mengaktifkan viewer baru secara global tanpa kill switch.
Menganggap sukses render di dokumen contoh berarti aman untuk semua DOCX/PPTX/XLSX.
Hanya mengukur error JavaScript global, bukan error domain seperti render gagal atau fallback terpakai.
Mengirim konten dokumen ke log untuk debugging.
Tidak membedakan file rusak, format tidak didukung, dan bug renderer.
Melakukan rollback dengan deploy ulang padahal feature flag bisa menyelesaikan dampak lebih cepat.

Trade-off pendekatan browser-based viewer

Viewer OOXML di browser memberi kontrol UX yang baik dan dapat mengurangi ketergantungan pada konversi server-side. Namun, pendekatan ini memiliki trade-off yang perlu diterima sejak desain:

Performa bervariasi karena perangkat pengguna berbeda-beda.
Kompatibilitas dokumen tidak selalu sempurna, terutama untuk fitur Office yang kompleks.
Bundle dan parsing bisa berat, sehingga lazy loading dan Web Worker layak dipertimbangkan.
Observability frontend lebih sulit dibanding backend karena browser dapat menutup tab, memblokir request telemetry, atau crash sebelum event terkirim.
Keamanan dan privasi tetap penting: batasi URL dokumen, gunakan authorization yang benar, hindari logging konten, dan perhatikan kebijakan penyimpanan cache.

Karena trade-off tersebut, strategi deployment aman bukan tambahan opsional. Feature flag, canary, fallback, rollback, dan observability adalah bagian dari desain produk viewer itu sendiri.

Kesimpulan

Deploy viewer OOXML browser yang aman membutuhkan lebih dari sekadar menambahkan library renderer ke frontend. Mulailah dengan feature flag yang eksplisit, canary berdasarkan segmen risiko, fallback yang selalu tersedia, dan rollback yang bisa dilakukan tanpa deploy ulang. Lengkapi dengan observability untuk error render, dokumen gagal dibuka, ukuran file, waktu render, memory pressure, Core Web Vitals, dan log korelasi.

Jika setiap insiden ringan menghasilkan test fixture baru, dashboard yang lebih tajam, atau checklist yang lebih baik, kualitas viewer akan meningkat secara bertahap tanpa menempatkan seluruh pengguna pada risiko yang tidak perlu.

Quick Search

shopping_cart Keranjang