Debug bug encoding chat lama yang merusak log dan JSON API biasanya bukan masalah satu baris kode, melainkan gabungan data legacy, decoder yang tidak konsisten, dan pipeline backend yang diam-diam membuat asumsi berbeda. Gejalanya sering terlihat acak: karakter aneh seperti ’, request JSON gagal diproses, log penuh simbol rusak, dan pencarian teks di database tidak menemukan hasil yang seharusnya cocok.

Studi kasus ini terinspirasi dari konteks dibukanya source code Microsoft Comic Chat, tetapi fokusnya adalah pelajaran modern untuk backend saat memproses arsip chat lama. Inti masalahnya: sebagian data tersimpan atau dikirim sebagai Windows-1252, sebagian lain diasumsikan UTF-8, newline tidak dinormalisasi, dan tiap service memakai strategi decoding yang berbeda. Jika tidak ditangani secara sistematis, bug seperti ini akan menyebar ke API, observability, indexing, sampai migrasi data.

Studi kasus: gejala yang terlihat di produksi

Bayangkan sebuah tim membuka arsip chat lama dari aplikasi era desktop dan memasukkannya ke backend modern. Data lama ini kemudian dipakai untuk tiga kebutuhan sekaligus:

  • ditampilkan lewat JSON API,
  • disimpan ke database untuk pencarian,
  • dan dicatat ke log untuk audit dan debugging.

Masalah mulai muncul dengan pola yang tampaknya tidak berhubungan:

  • Beberapa pesan tampil sebagai François atau don’t alih-alih François dan don’t.
  • Service tertentu gagal mem-parse payload JSON dengan error karakter tidak valid.
  • Log agregator menampilkan potongan baris yang terbelah, sehingga satu event terlihat seperti beberapa event berbeda.
  • Pencarian database untuk kata dengan aksen atau tanda kutip tipografi sering tidak cocok.
  • Hanya sebagian pesan yang rusak, sehingga tim awalnya mengira ini bug rendering di frontend.

Inilah ciri khas bug encoding: gejalanya menyebar lintas lapisan, dan akar masalahnya sering muncul jauh sebelum data masuk ke komponen yang terlihat rusak.

Contoh payload bermasalah

Kasus paling umum adalah teks yang awalnya berasal dari byte Windows-1252, tetapi ada service yang langsung menganggapnya sebagai UTF-8. Selain itu, data chat lama sering membawa newline \r\n ala Windows, kadang bercampur dengan \n atau bahkan byte kontrol lain.

Contoh data mentah

user=Renée
message=I can’t join at 10:00
room=general

Jika byte di atas sebenarnya disimpan sebagai Windows-1252 lalu dibaca sebagai UTF-8 tanpa konversi yang benar, karakter seperti é atau ’ bisa berubah menjadi karakter rusak atau memicu error decoder.

Contoh payload JSON yang tampak benar tetapi gagal di downstream

{
  "user": "Renée",
  "message": "I can’t join at 10:00",
  "source": "legacy-import"
}

Secara visual payload ini tampak normal. Namun jika service A membuat string dari byte non-UTF-8 lalu service B menganggap seluruh body JSON harus valid UTF-8, parser JSON standar bisa menolak payload tersebut. Dalam banyak runtime modern, JSON text diasumsikan berbasis Unicode, dan implementasi praktisnya hampir selalu mengharapkan UTF-8 pada transport HTTP.

Contoh gejala mojibake

Renée   -> Renée
can’t   -> can’t
“hello” -> “helloâ€

Mojibake seperti ini terjadi ketika byte yang valid pada satu encoding ditafsirkan memakai encoding lain. Ini bukan sekadar masalah tampilan; data yang sudah terlanjur rusak akan ikut rusak saat di-log, di-index, dan dicari.

Root cause: campuran encoding, newline, dan kontrak yang kabur

1. Campuran Windows-1252 dan UTF-8

Masalah inti biasanya bukan “teks rusak”, melainkan byte ditafsirkan dengan aturan yang salah. Pada data chat lama, Windows-1252 sering muncul karena asalnya dari aplikasi desktop Windows, file ekspor lawas, atau komponen C/C++ yang tidak menyimpan metadata charset dengan jelas.

Masalah umum yang terjadi:

  • Importer membaca file sebagai UTF-8, padahal aslinya Windows-1252.
  • Service perantara menyimpan teks apa adanya tanpa menandai encoding sumber.
  • Service downstream menganggap semua string dari upstream sudah bersih dan valid UTF-8.

Windows-1252 sangat bermasalah untuk karakter “pintar” seperti kutip tipografi, dash, simbol euro, dan beberapa karakter Eropa Barat. Karakter inilah yang sering memicu gejala paling mencolok.

2. Normalisasi newline yang tidak konsisten

Chat lama sering mengandung \r\n. Service modern kadang:

  • menyimpan apa adanya,
  • mengubah menjadi \n,
  • atau melakukan parsing baris sebelum decoding selesai.

Jika normalisasi newline dilakukan terlambat atau di tempat yang salah, dampaknya bisa serius:

  • log collector menganggap satu pesan sebagai beberapa baris log,
  • parser berbasis delimiter memotong payload di posisi yang salah,
  • signature atau checksum payload berubah sehingga validasi gagal.

Masalah ini makin sulit dideteksi jika hanya sebagian service yang mengubah newline.

3. Asumsi decoder berbeda antar service

Dalam arsitektur microservice atau pipeline ETL, masalah encoding sering memburuk karena setiap komponen memakai asumsi sendiri:

  • service ingest menerima byte mentah,
  • service transform mengubah ke string dengan default runtime,
  • queue menyimpan payload JSON,
  • worker logging menulis string ke stdout,
  • indexer database melakukan normalisasi tambahan.

Jika kontrak tidak eksplisit, maka ada tiga kemungkinan buruk:

  1. byte yang salah dipromosikan menjadi string “rusak tapi lolos”,
  2. error muncul terlambat di service lain,
  3. data rusak tersimpan permanen sehingga sulit dibedakan dari data asli.

Langkah investigasi yang benar

Saat menghadapi bug encoding, target pertama bukan memperbaiki tampilan, melainkan menemukan di titik mana byte berubah makna. Itu berarti kita harus melacak data dari sumber ke tujuan.

1. Kumpulkan sampel yang benar-benar rusak

Jangan mulai dari screenshot. Ambil contoh nyata dari:

  • payload HTTP mentah,
  • message di queue,
  • baris log asli,
  • record database sebelum dan sesudah diproses.

Idealnya simpan bentuk byte mentah atau representasi heksadesimal. Untuk bug encoding, melihat string hasil akhir saja sering menyesatkan.

2. Bedakan masalah byte, string, dan rendering

Ada tiga lapisan yang sering tercampur:

  • Byte salah: data sudah rusak sejak awal.
  • Decoding salah: byte benar, tapi diubah ke string dengan charset yang salah.
  • Rendering salah: string benar, tapi terminal, logger, atau UI menampilkannya salah.

Bedakan ketiganya dengan membandingkan:

  • byte mentah,
  • hasil decode eksplisit,
  • hasil serialisasi kembali ke JSON atau database.

3. Instrumentasi sementara di titik masuk

Tambahkan logging atau metrik sementara di boundary sistem, misalnya saat file diimpor atau request diterima. Jangan langsung log teks mentah yang mungkin rusak; log informasi diagnostik yang aman:

  • panjang byte dan panjang string hasil decode,
  • apakah decode valid UTF-8,
  • apakah ada byte kontrol non-printable,
  • apakah newline mengandung \r\n atau campuran format.

4. Periksa header dan metadata, tetapi jangan terlalu percaya

Header seperti Content-Type atau metadata file bisa membantu, tetapi data legacy sering tidak konsisten. Banyak sistem lama menulis text/plain tanpa charset, atau bahkan menandai UTF-8 padahal isi sebenarnya bukan UTF-8.

5. Cari pola karakter yang khas

Beberapa pola mojibake cukup diagnostik:

  • ’ sering berarti apostrof tipografi UTF-8 dibaca sebagai Windows-1252 atau Latin-1.
  • é sering berarti karakter aksen UTF-8 dibaca sebagai single-byte charset.
  • error parser JSON pada byte tertentu sering berarti body bukan UTF-8 valid.

Pola ini tidak cukup untuk bukti final, tetapi sangat berguna untuk mempersempit hipotesis.

Strategi reproduksi agar bug tidak “menghilang”

Bug encoding sering sulit direproduksi karena developer menguji dengan data UTF-8 bersih dari editor modern. Untuk menemukan akar masalah, buat fixture yang meniru data legacy secara sengaja.

Buat fixture byte-level, bukan hanya string literal

Jika test hanya berisi string literal di source code, editor dan compiler biasanya sudah menyimpannya sebagai UTF-8. Itu tidak mewakili kasus sebenarnya. Lebih aman menyimpan fixture sebagai file biner kecil atau membuat byte array eksplisit.

// Pseudocode netral bahasa
bytes = [0x52, 0x65, 0x6E, 0xE9, 0x65, 0x0D, 0x0A,
         0x49, 0x20, 0x63, 0x61, 0x6E, 0x92, 0x74]
// 0xE9 dan 0x92 adalah byte khas Windows-1252 untuk é dan apostrof tipografi

Lalu uji beberapa skenario:

  1. decode sebagai UTF-8 dan pastikan gagal atau menghasilkan gejala yang diprediksi,
  2. decode sebagai Windows-1252 lalu konversi ke UTF-8,
  3. normalisasi newline setelah decoding berhasil,
  4. serialisasi ke JSON dan kirim ke service downstream.

Reproduksi lintas komponen

Jangan berhenti di unit test. Jika bug aslinya terjadi antar service, reproduksi juga alurnya:

  • importer membaca fixture,
  • payload dikirim ke API internal atau queue,
  • worker menulis log dan menyimpan ke database,
  • endpoint pencarian mencoba mengambil data tersebut.

Tujuannya adalah memastikan Anda menemukan semua titik yang membuat asumsi berbeda.

Perbaikan bertahap yang aman

Memperbaiki bug encoding paling aman dilakukan bertahap. Mengganti semua decoder sekaligus sering memperburuk keadaan, terutama jika sudah ada data rusak yang telanjur tersimpan.

1. Tetapkan satu kontrak internal: semua string aplikasi harus UTF-8 valid

Kontrak ini harus berlaku di semua boundary internal:

  • setelah ingest, string harus sudah valid Unicode,
  • payload JSON internal harus diserialisasi dari string valid,
  • database dan log pipeline mengonsumsi format yang konsisten.

Intinya, konversi dilakukan sedekat mungkin dengan sumber data. Jangan biarkan byte legacy berkeliaran terlalu jauh di sistem.

2. Pisahkan tahap decode, validasi, dan normalisasi

Kesalahan umum adalah melakukan semuanya sekaligus. Urutan yang lebih aman:

  1. terima byte mentah,
  2. tentukan encoding sumber berdasarkan kontrak atau heuristik terbatas,
  3. decode ke string Unicode,
  4. validasi karakter tak valid atau byte kontrol,
  5. normalisasi newline ke satu bentuk, biasanya \n,
  6. baru serialisasi ke JSON atau simpan ke database.

Urutan ini penting karena normalisasi string sebelum decoding yang benar dapat menyebabkan kehilangan informasi atau parsing yang salah.

3. Fail fast untuk input ambigu, tetapi sediakan jalur karantina

Tidak semua data legacy bisa diinterpretasikan dengan pasti. Jika sistem tidak yakin apakah suatu byte stream adalah UTF-8 atau Windows-1252, ada dua pilihan:

  • strict mode: tolak dan kirim ke jalur review,
  • quarantine mode: simpan byte asli dan metadata, lalu proses manual atau batch remediation.

Ini lebih baik daripada mendecode “semampunya” lalu menyebarkan data rusak ke seluruh sistem.

4. Simpan bentuk asli saat migrasi

Untuk impor data lama, pertimbangkan menyimpan:

  • payload byte asli,
  • encoding yang diasumsikan,
  • hasil teks terkonversi,
  • status validasi.

Trade-off-nya adalah penyimpanan bertambah dan pipeline lebih kompleks, tetapi manfaatnya besar untuk audit dan rollback. Jika nanti heuristik encoding diperbaiki, Anda bisa memproses ulang dari sumber asli, bukan dari data yang sudah rusak.

5. Jangan “memperbaiki” mojibake dengan replace acak

Misalnya mengganti semua ’ menjadi ’ mungkin terlihat berhasil untuk satu kasus, tetapi berbahaya sebagai solusi umum. Itu hanya menutup gejala, bukan memperbaiki jalur decoding. Solusi seperti ini juga bisa merusak data yang sebenarnya valid.

Contoh implementasi pipeline yang lebih aman

Berikut pseudocode netral bahasa untuk boundary importer. Fokusnya bukan pada syntax framework tertentu, tetapi pada urutan penanganan yang benar.

function ingestLegacyMessage(rawBytes, metadata) {
  let sourceEncoding = detectOrChooseEncoding(metadata, rawBytes)

  if (!sourceEncoding) {
    quarantine(rawBytes, metadata, "unknown-encoding")
    return
  }

  let text = decodeBytes(rawBytes, sourceEncoding, { strict: true })
  if (text == null) {
    quarantine(rawBytes, metadata, "decode-failed")
    return
  }

  text = normalizeNewlines(text)      // \r\n dan \r menjadi \n
  text = stripUnsafeControlChars(text) // sisakan tab/newline jika memang diizinkan

  if (!isValidUnicodeForJson(text)) {
    quarantine(rawBytes, metadata, "invalid-unicode")
    return
  }

  let payload = {
    source: "legacy-import",
    source_encoding: sourceEncoding,
    message: text
  }

  sendJson(payload)
}

Mengapa pendekatan ini bekerja:

  • byte mentah ditangani hanya di satu tempat,
  • encoding sumber diputuskan eksplisit, bukan default implisit runtime,
  • normalisasi dilakukan setelah teks menjadi Unicode valid,
  • JSON hanya dibentuk dari string yang sudah tervalidasi.

Contoh guard di boundary API

function acceptInternalJson(bodyBytes, contentType) {
  if (!isUtf8(bodyBytes)) {
    reject(400, "request body must be valid UTF-8 JSON")
    return
  }

  let obj = parseJson(bodyBytes)
  obj.message = normalizeNewlines(obj.message)
  store(obj)
}

Boundary API internal sebaiknya tegas: jika kontraknya UTF-8 JSON, jangan diam-diam menerima byte campuran lalu berharap layer lain akan memperbaikinya.

Dampak ke log, database, dan pencarian

Log yang kacau

Jika message masih mengandung byte atau newline yang tidak dinormalisasi, satu event log bisa pecah menjadi beberapa baris. Ini menyulitkan korelasi antar service dan bisa mengacaukan parser log berbasis baris. Solusi praktis:

  • normalisasi newline sebelum logging,
  • gunakan structured logging berbasis JSON jika memungkinkan,
  • escape karakter kontrol yang tidak perlu tampil mentah di log.

Structured logging tidak otomatis menyelesaikan bug encoding, tetapi sangat membantu membatasi kerusakan dibanding log plain text multi-baris.

Pencarian database meleset

Pencarian teks bisa gagal karena dua hal berbeda:

  • data sudah tersimpan dalam bentuk mojibake,
  • data benar tetapi kueri dan normalisasi pencarian berbeda.

Contoh masalah umum:

  • Renée tersimpan sebagai Renée, sehingga pencarian nama asli gagal total.
  • Tanda kutip tipografi dan apostrof lurus diperlakukan berbeda oleh pipeline indexing.
  • Newline campuran membuat tokenisasi teks tidak konsisten.

Setelah fix, jangan hanya memperbaiki ingest baru. Audit juga index lama, materialized view, cache pencarian, dan record yang sudah tercemar. Dalam banyak kasus, Anda perlu reindex atau backfill data terkonversi.

Validasi pasca-fix

Perbaikan encoding belum selesai saat test hijau. Anda perlu membuktikan bahwa alur lama dan baru sama-sama aman.

Apa yang perlu divalidasi

  1. Payload masuk: body non-UTF-8 ditolak atau dikarantina sesuai desain.
  2. Data legacy valid: file Windows-1252 yang diketahui benar berhasil dikonversi ke Unicode yang diharapkan.
  3. JSON downstream: tidak ada parse error pada service penerima.
  4. Log: satu event tetap satu event, tanpa pecah karena newline liar.
  5. Database: hasil query dan pencarian cocok untuk karakter aksen, kutip, dan simbol umum.
  6. Idempoten: data yang sudah UTF-8 tidak rusak karena dikonversi ulang.

Contoh test yang layak dipertahankan

  • fixture Windows-1252 dengan karakter aksen dan smart quote,
  • fixture UTF-8 valid yang tidak boleh berubah,
  • fixture dengan newline \r\n, \r, dan \n,
  • fixture ambigu atau rusak yang harus masuk quarantine.

Guardrail agar bug yang sama tidak kembali

1. Contract test antar service

Jika ada beberapa service yang saling bertukar JSON, buat contract test yang menegaskan:

  • request dan response harus valid UTF-8,
  • field teks tidak boleh mengandung kontrol terlarang,
  • newline dinormalisasi sesuai kontrak.

Ini mencegah satu service diam-diam berubah perilaku dan merusak service lain.

2. Sanitasi input di boundary, bukan di mana-mana

Sanitasi yang tersebar di banyak layer mudah tidak konsisten. Pilih satu atau beberapa titik boundary yang bertanggung jawab untuk:

  • decode input,
  • normalisasi newline,
  • memfilter karakter kontrol yang tidak diizinkan,
  • menolak input yang tidak sesuai kontrak.

Layer lain cukup mengasumsikan input sudah valid dan fokus pada logika bisnis.

3. Observability yang spesifik untuk encoding

Tambahkan metrik dan event observability yang relevan, misalnya:

  • jumlah payload yang gagal validasi UTF-8,
  • jumlah item quarantine per sumber data,
  • distribusi encoding sumber pada proses migrasi,
  • jumlah karakter kontrol yang dibersihkan,
  • parse error JSON yang terkait body tidak valid.

Tanpa metrik seperti ini, bug encoding sering baru terlihat saat pengguna melaporkan data aneh.

4. Checklist migrasi data lama

Sebelum memindahkan arsip chat lawas ke sistem modern, gunakan checklist praktis berikut:

  • Inventaris semua sumber data: file, dump database, export tool, queue lama.
  • Catat encoding yang diduga untuk tiap sumber, jangan diasumsikan sama.
  • Ambil sampel byte mentah dari masing-masing sumber.
  • Tentukan kontrak internal target: UTF-8 valid dan newline konsisten.
  • Buat fixture test dari kasus nyata, bukan hanya string contoh.
  • Sediakan quarantine path untuk data ambigu atau rusak.
  • Simpan payload asli selama fase migrasi bila memungkinkan.
  • Validasi output di API, log, dan pencarian, bukan hanya di database.
  • Rencanakan reindex atau backfill jika ada data lama yang sudah tercemar.
  • Dokumentasikan keputusan encoding agar tidak hilang saat tim berganti.

Kesalahan umum yang sering terjadi

  • Mengandalkan default runtime: default charset berbeda antar lingkungan atau berubah saat runtime/library berganti.
  • Memperbaiki gejala di frontend: jika akar masalah ada di backend, perbaikan UI hanya menyamarkan kerusakan data.
  • Mengganti karakter rusak satu per satu: ini rapuh dan berisiko merusak data valid.
  • Tidak menyimpan sumber asli saat migrasi: Anda kehilangan kesempatan untuk reparsing dengan strategi yang benar.
  • Menganggap JSON parser akan “mengerti sendiri”: parser JSON bukan detektor encoding universal.

Penutup

Pelajaran utama dari debug bug encoding chat lama yang merusak log dan JSON API adalah bahwa masalah ini harus ditangani di level kontrak data, bukan sekadar tampilan teks. Campuran Windows-1252 dan UTF-8, normalisasi newline yang tidak konsisten, dan asumsi decoder berbeda antar service dapat menghasilkan kerusakan berantai: API gagal, log berantakan, dan pencarian database tidak akurat.

Pendekatan yang paling aman adalah memperlakukan byte mentah sebagai input yang harus diputuskan encoding-nya secara eksplisit, mengonversinya sedekat mungkin ke sumber, menormalisasi newline setelah decoding berhasil, lalu menegakkan kontrak UTF-8 di seluruh pipeline internal. Tambahkan contract test, quarantine path, sanitasi boundary, dan observability yang spesifik. Dengan begitu, data legacy tetap bisa dihidupkan kembali tanpa membawa bug masa lalu ke sistem modern.