Debug Backend: Parser EPUB Gagal karena Perbedaan Validator

Masalah inti pada kasus ini adalah file EPUB terlihat valid di pipeline backend internal atau lulus di satu validator, tetapi gagal dibuka atau ditolak oleh reader/vendor lain. Dalam praktik produksi, ini hampir selalu berarti satu hal: valid bukan status absolut, melainkan hasil dari kombinasi parser, aturan validasi, toleransi implementasi, dan kadang warisan engine lama yang tidak sepenuhnya mengikuti interpretasi spesifikasi yang sama.

Kalau Anda sedang debug backend parser EPUB gagal karena perbedaan validator, pendekatan yang paling aman bukan langsung menyalahkan file atau vendor. Yang dibutuhkan adalah isolasi artefak, reproduksi deterministik, perbandingan lintas engine, dan perubahan pipeline validasi agar perbedaan parser tidak lolos lagi ke produksi.

Gejala Nyata di Produksi

Kasus semacam ini biasanya tidak muncul sebagai error tunggal yang rapi. Gejalanya tersebar di beberapa lapisan:

• Ingest service menerima upload EPUB dan menandainya validated=true.
• QA internal bisa membuka file di satu reader desktop.
• Vendor distribusi atau perangkat tertentu menolak file saat impor.
• Tiket support masuk dengan pesan samar seperti file corrupt, cannot open book, atau unsupported format.

Contoh log produksi yang realistis biasanya tampak seperti ini:

[ingest] job_id=8f31b upload_id=up_2198 step=container-parse status=ok
[ingest] job_id=8f31b step=opf-parse status=ok package_path=OEBPS/content.opf
[ingest] job_id=8f31b step=validation engine=internal status=passed warnings=1
[delivery] export_id=exp_772 vendor=kobo status=rejected
[delivery] export_id=exp_772 vendor_message="E_BOOK_PROCESSING_ERROR"
[support] ticket=CS-1842 device=Aura note="book opens on app X but not on device Y"

Atau pada sistem yang sudah memiliki hook validasi eksternal:

[validator:epubcheck] result=passed errors=0 warnings=2
[validator:vendor-adapter] result=failed error="content document parse error"
[reader-sim] engine=legacy-adept result=failed error="unexpected token near nav landmark"

Perhatikan pola pentingnya: backend menganggap file aman, tetapi parser lain gagal pada tahap yang lebih rendah, misalnya XML parsing, OPF resolution, NCX/nav handling, atau resource lookup.

Hipotesis Awal yang Sering Salah

Saat insiden baru muncul, tim biasanya mengajukan hipotesis yang masuk akal tetapi keliru. Beberapa yang paling umum:

• "Vendor sedang bug." Bisa saja, tetapi terlalu dini menyimpulkan ini tanpa reproduksi yang bersih.
• "File pasti rusak saat upload." Padahal checksum file sumber dan artefak kiriman bisa identik.
• "Kalau lolos epubcheck berarti pasti benar." Ini asumsi yang berbahaya. Validator formal membantu, tetapi tidak menjamin semua reader akan menerima file.
• "Masalahnya di DRM atau jaringan distribusi." Sering kali akar masalah justru ada pada struktur EPUB yang ditoleransi oleh satu parser dan ditolak parser lain.

Kesalahan paling mahal adalah menambal gejala di sisi distribusi tanpa memahami perbedaan perilaku antar engine. Akibatnya, file yang sama akan terus lolos dari ingest lalu gagal di hilir.

Langkah Isolasi Bug yang Praktis

1. Bekukan artefak dan checksum

Jangan debug pada file yang terus berubah. Ambil satu salinan EPUB yang gagal, hitung checksum, lalu gunakan artefak itu untuk semua pengujian.

sha256sum problematic.epub
unzip -t problematic.epub

Tujuannya sederhana: memastikan problem bukan korupsi transport atau perubahan file selama pipeline berlangsung.

2. Catat hasil dari beberapa engine, bukan satu tool

Buat matriks sederhana untuk membandingkan hasil:

Matriks ini membantu mengubah diskusi dari opini menjadi bukti. Yang dicari bukan sekadar siapa yang benar, tetapi di bagian mana interpretasi berbeda.

3. Unzip dan periksa struktur minimum EPUB

Untuk EPUB, beberapa hal dasar harus benar secara konsisten:

• File mimetype harus berada di awal archive dan tidak terkompres.
• META-INF/container.xml harus menunjuk ke package document yang benar.
• Manifest, spine, metadata, dan semua resource yang dirujuk harus resolvable.
• Dokumen XHTML/XML harus well-formed.

Contoh pengecekan cepat:

unzip -l problematic.epub
unzip -p problematic.epub META-INF/container.xml
unzip -p problematic.epub OEBPS/content.opf | sed -n '1,120p'

Pada fase ini, banyak tim berhenti terlalu cepat karena struktur terlihat normal. Padahal masalah sering ada pada detail yang valid menurut satu parser, tetapi ditolak parser lain.

4. Validasi setiap dokumen konten sebagai XML/XHTML sebenarnya

Reader yang lebih tua atau berbasis parser XML ketat sering gagal bukan karena OPF utama, tetapi karena satu file XHTML yang punya markup ambigu, namespace aneh, entity tak dikenali, atau urutan elemen yang masih ditoleransi parser HTML modern.

Contoh error yang bisa muncul dari parser ketat:

ERROR content/chapter1.xhtml: line 47: Opening and ending tag mismatch: meta line 12 and head
ERROR content/nav.xhtml: line 19: Namespace prefix epub for type on nav is not defined
ERROR content/chapter3.xhtml: line 88: xmlParseEntityRef: no name

Kalau backend Anda hanya memeriksa keberadaan file dan relasi manifest, bug seperti ini akan lolos.

Perbandingan Hasil Antar Validator dan Parser

Bagian paling penting dari debugging ini adalah memahami bahwa validator dan parser punya tujuan berbeda:

• Validator formal memeriksa kesesuaian terhadap aturan spesifikasi.
• Parser runtime fokus pada kemampuan memuat dan merender dokumen nyata.
• Engine legacy sering membawa asumsi lama, workaround historis, atau keterbatasan parser XML/CSS/HTML tertentu.

Dalam banyak kasus mirip referensi tentang file yang "baik-baik saja" di satu tempat tetapi ditolak ekosistem lain, problemnya bukan semata file rusak, melainkan perbedaan interpretasi spesifikasi atau kompatibilitas terhadap parser lama yang masih dipakai di rantai distribusi tertentu.

Contoh skenario yang realistis:

• epubcheck tidak menganggap struktur tertentu fatal karena masih sesuai atau hanya warning.
• Reader modern berbasis WebKit/Blink cukup toleran terhadap XHTML yang nyaris HTML5.
• Vendor memakai engine rendering lama berbasis Adobe RMSDK atau turunan parser yang lebih sensitif pada well-formedness, namespace, atau urutan resource tertentu.

Akibatnya, file yang secara formal tidak terlalu bermasalah tetap gagal di perangkat nyata.

Root Cause: Perbedaan Interpretasi Spesifikasi atau Parser Legacy

Root cause yang paling sering saya temui pada kasus seperti ini jatuh ke salah satu kelompok berikut:

1. XHTML tidak benar-benar well-formed

Parser HTML modern mungkin memaafkan tag yang tidak tertutup, atribut tanpa escaping yang tepat, atau struktur elemen yang ambigu. Parser XML ketat tidak akan memaafkannya.

2. Namespace EPUB atau atribut khusus tidak dideklarasikan konsisten

Misalnya file nav memakai atribut seperti epub:type tetapi deklarasi namespacenya hilang pada elemen root. Sebagian validator mungkin hanya memberi warning bergantung konteks, sementara parser tertentu gagal total.

3. Manifest/spine valid secara minimal, tetapi resource resolution berbeda

Contohnya path relatif yang technically resolvable di satu tool, tetapi gagal di engine lain karena normalisasi path, case sensitivity, atau base path yang diasumsikan berbeda.

4. Fitur EPUB modern diproses oleh engine lama

Ini area yang sering menipu. Secara spesifikasi file benar, tetapi vendor target masih bergantung pada parser legacy yang ekspektasinya mendekati EPUB 2 atau subset tertentu dari EPUB 3.

5. Metadata atau fallback item tidak sesuai ekspektasi implementasi tertentu

Bukan berarti file ilegal, tetapi implementasi tertentu memerlukan bentuk yang lebih konservatif agar kompatibel.

Yang penting: jangan memaksa kesimpulan bahwa spesifikasi salah atau vendor bodoh. Dalam backend produksi, pertanyaan yang benar adalah: format mana yang paling aman untuk seluruh target distribusi kita?

Contoh Investigasi Sampai Menemukan Akar Masalah

Misalkan sebuah EPUB ditolak vendor B, tetapi lolos di validator internal dan bisa dibuka di reader desktop A. Setelah diekstrak, ditemukan file nav.xhtml seperti ini:

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Navigation</title>
  </head>
  <body>
    <nav epub:type="toc" id="toc">
      <ol>
        <li><a href="chapter1.xhtml">Bab 1</a></li>
      </ol>
    </nav>
  </body>
</html>

Secara visual tampak normal, tetapi atribut epub:type memakai prefix epub tanpa deklarasi namespace. Parser toleran bisa mengabaikannya atau tetap merender konten. Parser XML ketat dapat gagal saat memuat dokumen.

Perbaikannya sederhana dan aman:

<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:epub="http://www.idpf.org/2007/ops">
  <head>
    <title>Navigation</title>
  </head>
  <body>
    <nav epub:type="toc" id="toc">
      <ol>
        <li><a href="chapter1.xhtml">Bab 1</a></li>
      </ol>
    </nav>
  </body>
</html>

Kenapa ini aman? Karena perubahan tersebut tidak mengubah isi, urutan spine, atau perilaku pembaca yang sudah berhasil. Kita hanya membuat dokumen lebih eksplisit dan kompatibel terhadap parser yang memerlukan namespace valid.

Contoh lain yang juga sering terjadi adalah file XHTML yang diperlakukan seperti HTML biasa oleh generator konten. Misalnya ada <br> atau karakter ampersand yang tidak di-escape pada konteks XML. Browser modern mungkin membetulkannya diam-diam, tetapi parser XML tidak.

Perbaikan Aman di Sisi Backend

Setelah root cause ditemukan, godaan terbesar adalah menambahkan patch sempit khusus vendor. Itu boleh sebagai mitigasi jangka pendek, tetapi untuk jangka panjang backend perlu perbaikan yang lebih sistematis.

1. Pisahkan tahap ingest, lint, dan compatibility validation

Jangan gabungkan semua menjadi status tunggal valid. Lebih aman punya status seperti:

• archive_ok
• spec_validation_ok
• compatibility_profile_ok
• vendor_target_ok[kobo|adept-like|generic]

Dengan begitu, file bisa tetap tersimpan tetapi diberi label risiko kompatibilitas.

2. Tambahkan normalisasi konservatif bila sumber EPUB berasal dari generator yang tidak konsisten

Misalnya:

• Pastikan semua XHTML well-formed.
• Pastikan namespace penting dideklarasikan.
• Pastikan referensi manifest dan href konsisten.
• Pastikan struktur ZIP mengikuti aturan dasar EPUB.

Trade-off: normalisasi otomatis harus sangat hati-hati. Jangan mengubah isi atau struktur semantik tanpa bukti kuat, karena patch agresif bisa merusak file yang sebelumnya valid.

3. Simpan artefak hasil transformasi dan diff

Kalau backend melakukan repair, simpan:

• file asli
• file hasil normalisasi
• ringkasan perubahan
• hasil validator sebelum/sesudah

Ini penting untuk audit dan rollback.

4. Fail closed untuk kasus fatal, fail soft untuk kasus kompatibilitas terbatas

Contohnya:

• XML tidak well-formed: tolak.
• Warning kompatibilitas legacy: terima tetapi tandai.
• Vendor target tertentu gagal: blok distribusi ke target itu, bukan membatalkan seluruh ingest jika target lain masih aman.

Checklist Reproduksi Bug

Gunakan checklist ini agar debugging tidak berubah menjadi trial-and-error:

1. Ambil satu file EPUB dan bekukan checksum.
2. Verifikasi file ZIP dan struktur dasar archive.
3. Ekstrak container.xml dan package document.
4. Validasi semua file XHTML/XML sebagai dokumen well-formed.
5. Bandingkan hasil minimal pada 2-3 engine: validator formal, parser internal, dan simulator/adapter vendor bila ada.
6. Catat file atau elemen pertama yang memicu divergence.
7. Buat patch terkecil yang menjelaskan perubahan perilaku.
8. Jalankan ulang seluruh matriks validator/parser setelah patch.

Strategi Observability yang Seharusnya Ada

Banyak tim kesulitan karena pipeline validasi terlalu gelap. Agar insiden serupa lebih cepat diusut, tambahkan observability sejak awal.

Field log yang berguna

• upload_id, book_id, job_id
• source_checksum, normalized_checksum
• validator_engine, parser_engine
• stage: archive, container, opf, xhtml, nav, packaging
• result, error_code, error_excerpt
• vendor_target bila distribusi spesifik

Praktik observability yang membantu

• Simpan 20-50 baris konteks di sekitar file/line yang gagal diparse.
• Emit event terstruktur, jangan hanya string bebas.
• Pisahkan metrik spec failed dan compat failed.
• Buat dashboard rasio lolos per engine, bukan hanya total success rate ingest.

Contoh log terstruktur:

{
  "job_id": "8f31b",
  "stage": "xhtml-parse",
  "file": "OEBPS/nav.xhtml",
  "engine": "legacy-reader-profile",
  "result": "failed",
  "line": 12,
  "column": 14,
  "error_code": "XML_NAMESPACE_UNDECLARED_PREFIX",
  "excerpt": "<nav epub:type=\"toc\" id=\"toc\">"
}

Regression Test yang Layak Ditambahkan

Setelah bug ditemukan, jangan berhenti pada hotfix. Tambahkan regression test pada level yang tepat.

1. Fixture EPUB nyata

Simpan satu fixture EPUB yang mereproduksi bug asli. Kalau ukuran file besar, setidaknya simpan fixture minimal yang mempertahankan struktur pemicu.

2. Snapshot hasil multi-engine

Untuk setiap fixture, simpan ekspektasi seperti:

• validator formal: pass
• profile legacy: fail sebelum fix, pass sesudah fix
• normalizer: menambahkan namespace, tidak mengubah spine

3. Test pada level file, bukan hanya API

API test penting, tetapi bug ini sering berada di level parser. Buat unit/integration test yang langsung menjalankan pipeline validasi terhadap fixture EPUB.

case "nav.xhtml missing epub namespace should be repaired safely":
  input = fixture("missing-epub-namespace.epub")
  result = ingestAndValidate(input)

  assert(result.archive_ok == true)
  assert(result.spec_validation_ok == true)
  assert(result.compatibility_profile_ok == true)
  assert(result.repairs.contains("declared epub namespace in nav.xhtml"))

Intinya bukan sintaks testnya, tetapi memastikan bug lama tidak kembali saat pipeline berubah.

Fallback Saat Perbaikan Belum Bisa Dirilis Penuh

Di sistem produksi, Anda kadang perlu mengurangi dampak insiden sebelum redesign selesai. Beberapa fallback yang aman:

• Quarantine lane: file yang lolos validator formal tetapi gagal profile kompatibilitas masuk antrean manual review.
• Vendor-specific block: hentikan distribusi hanya ke target yang gagal, bukan semua target.
• Read-only repair flag: jalankan normalizer dalam mode dry-run untuk mengukur cakupan sebelum auto-fix diaktifkan.
• Progressive rollout: aktifkan repair hanya untuk subset publisher atau traffic kecil dulu.

Keterbatasannya: fallback tidak boleh menjadi pengganti analisis akar masalah. Kalau tidak, pipeline akan dipenuhi exception dan aturan ad hoc yang sulit dipelihara.

Mendesain Pipeline Validasi Multi-Engine agar Bug Serupa Tidak Lolos Lagi

Inilah pelajaran utama dari studi kasus debug backend parser EPUB gagal karena perbedaan validator: satu validator tidak cukup untuk menjamin interoperabilitas.

Arsitektur yang lebih aman

1. Static checks: verifikasi ZIP, mimetype, container, OPF, manifest, spine.
2. Spec validator: jalankan validator formal untuk aturan standar.
3. XML/XHTML strict parse: parse semua konten sebagai XML yang ketat.
4. Compatibility profiles: sekumpulan aturan konservatif berdasarkan target distribusi utama.
5. Optional repair stage: normalisasi aman yang dapat diaudit.
6. Decision engine: menentukan accept, accept-with-warning, block-target, atau reject.

Kenapa multi-engine lebih efektif?

Karena tiap lapisan menangkap kelas bug yang berbeda:

• Validator formal menemukan pelanggaran aturan umum.
• Parser XML ketat menemukan file yang tidak benar-benar well-formed.
• Compatibility profile menangkap pola yang secara teori valid tetapi rawan gagal di parser legacy.

Contoh model hasil validasi

{
  "archive_ok": true,
  "spec_validation": { "status": "passed", "warnings": 1 },
  "strict_xml": { "status": "passed" },
  "compatibility_profiles": {
    "generic": "passed",
    "legacy_reader": "passed",
    "vendor_kobo_like": "warning"
  },
  "repairs": [
    "declared missing epub namespace in nav.xhtml"
  ],
  "decision": "accept_with_warning"
}

Model seperti ini jauh lebih berguna daripada boolean tunggal valid=true.

Kesalahan Desain yang Perlu Dihindari

• Menganggap pass di satu tool sebagai kebenaran final.
• Menyembunyikan warning validator dari pipeline keputusan.
• Tidak menyimpan artefak asli dan hasil transformasi.
• Melakukan auto-fix tanpa audit trail.
• Tidak punya fixture regression dari insiden produksi.
• Menggabungkan validasi spesifikasi dan kompatibilitas ke satu status biner.

Penutup

Pada layanan ingest EPUB, bug paling menjebak justru muncul saat semua terlihat baik-baik saja: file lulus validasi internal, QA tidak menemukan masalah, tetapi vendor atau reader tertentu menolak. Penyebabnya sering bukan korupsi file, melainkan perbedaan validator, parser yang lebih ketat, atau engine legacy dengan interpretasi spesifikasi yang berbeda.

Pendekatan yang efektif adalah membekukan artefak, membandingkan hasil lintas engine, mengisolasi file atau elemen yang memicu divergence, lalu menerapkan perbaikan paling kecil yang aman. Setelah itu, ubah pipeline agar validasi tidak lagi bergantung pada satu tool saja. Dengan observability yang baik, regression test berbasis fixture nyata, dan compatibility profile multi-engine, insiden serupa akan jauh lebih sulit lolos ke produksi.