Debug Backend Migrasi Arsip GIF: URL Rusak, MIME Salah, dan Cache CDN Basi

Debug backend migrasi arsip GIF biasanya bukan soal satu bug besar, melainkan gabungan beberapa masalah kecil yang efeknya terlihat acak: banyak URL menjadi 404, sebagian GIF tampil sebagai file unduhan, dan beberapa tetap rusak walaupun file sebenarnya sudah benar di origin. Pada migrasi aset statis skala besar, gejala seperti ini hampir selalu berkaitan dengan path mapping, metadata objek, aturan redirect, perbedaan huruf besar-kecil pada nama file, atau cache CDN yang belum bersih.

Kalau Anda sedang menangani migrasi arsip GIF lama ke storage atau hosting baru, pendekatan paling aman adalah memecah masalah berdasarkan gejalanya, lalu memverifikasi setiap lapisan secara terurut: aplikasi, web server, object storage, redirect, dan CDN. Artikel ini membahas studi kasus nyata debugging backend untuk kasus tersebut, lengkap dengan langkah investigasi, root cause per kategori, dan tindakan perbaikan yang bisa langsung diterapkan.

Gejala yang Muncul Setelah Migrasi

Dalam studi kasus ini, arsip GIF lama dipindahkan ke storage baru dengan tujuan menyederhanakan hosting aset statis. Secara umum file sudah tersalin, tetapi setelah cutover muncul tiga gejala utama:

• Banyak URL GIF mengembalikan 404, terutama pada arsip lama atau path yang tidak mengikuti pola baru.
• Sebagian GIF tidak tampil inline di browser, tetapi justru diunduh sebagai file biner atau ditampilkan sebagai konten rusak karena header Content-Type salah.
• Beberapa URL tetap bermasalah walaupun file sudah dibetulkan di storage, karena CDN atau cache perantara masih menyajikan respons lama.

Masalah seperti ini sering menipu karena satu URL bisa terlihat benar saat diuji langsung ke origin, tetapi salah saat diakses lewat domain publik. Artinya, debugging harus dilakukan lintas lapisan.

Langkah Investigasi yang Terurut

Urutan investigasi penting agar Anda tidak memperbaiki gejala di lapisan yang salah. Berikut alur yang praktis dan dapat diulang.

1. Cek log akses dan kelompokkan berdasarkan status

Mulailah dari access log aplikasi, web server, atau CDN. Tujuannya bukan hanya mencari 404, tetapi juga menemukan pola.

• URL mana yang paling sering gagal
• Apakah kegagalan hanya terjadi pada direktori tertentu
• Apakah ada perbedaan antara GET dan HEAD
• Apakah 404 berasal dari origin atau dari cache/CDN

Contoh pola yang berguna:

203.0.113.10 - - [12/Jul/2026:09:11:20 +0000] "GET /gifs/2004/fun/catdance.gif HTTP/1.1" 404 153 "-" "Mozilla/5.0"
203.0.113.10 - - [12/Jul/2026:09:11:23 +0000] "GET /GIFs/2004/fun/CatDance.gif HTTP/1.1" 301 0 "-" "Mozilla/5.0"
203.0.113.10 - - [12/Jul/2026:09:11:24 +0000] "GET /archive/catdance.gif HTTP/1.1" 200 48213 "-" "Mozilla/5.0"

Dari log seperti ini, Anda bisa langsung curiga ada masalah pada normalisasi path atau case sensitivity.

2. Ambil sampel URL rusak, jangan hanya satu

Jangan debug berdasarkan satu contoh. Ambil sampel yang mewakili tiap gejala:

• 5-10 URL 404
• 5-10 URL yang memicu unduhan
• 5-10 URL yang kadang benar, kadang salah

Masukkan ke tabel sederhana: URL lama, URL baru yang diharapkan, status saat ini, header aktual, dan checksum file jika tersedia. Ini membantu membedakan apakah masalah sistemik atau hanya subset data.

3. Periksa header HTTP, bukan hanya isi file

Banyak tim berhenti setelah memastikan file fisik ada di storage. Itu belum cukup. Browser dan CDN bereaksi pada header HTTP.

curl -I https://cdn.example.com/gifs/2004/fun/catdance.gif

HTTP/2 200
content-type: application/octet-stream
content-length: 48213
cache-control: public, max-age=31536000
etag: "abc123"

Jika Content-Type adalah application/octet-stream alih-alih image/gif, browser bisa memperlakukan respons sebagai file unduhan atau gagal merender sesuai harapan. Periksa juga:

• Location pada respons 301/302
• Cache-Control, ETag, Last-Modified
• Header CDN seperti X-Cache, Age, atau indikator hit/miss lain yang tersedia

4. Diff manifest file lama vs hasil migrasi

Jika migrasi dilakukan dari daftar file, database, atau manifest build, lakukan diff antara sumber lama dan target baru. Fokus pada:

• Path lengkap
• Ukuran file
• Checksum
• Metadata MIME jika storage mendukungnya

Contoh struktur manifest yang berguna:

old_path,new_path,size_bytes,sha256,content_type
/gifs/2004/fun/catdance.gif,archive/2004/fun/catdance.gif,48213,5f2...,image/gif
/gifs/2005/memes/Dance.GIF,archive/2005/memes/Dance.GIF,91220,a91...,image/gif

Dengan manifest, Anda bisa mendeteksi apakah file memang hilang, dipindah ke lokasi berbeda, atau hanya salah metadata.

5. Verifikasi checksum untuk membedakan file rusak vs penyajian rusak

Checksum penting agar Anda tidak salah mengira. Jika checksum origin sesuai dengan sumber lama, tetapi browser tetap gagal menampilkan file, besar kemungkinan masalah ada di header, redirect, atau cache. Jika checksum berbeda, migrasi datanya sendiri bermasalah.

6. Uji dengan curl mengikuti redirect

Gunakan curl untuk melihat rantai respons secara eksplisit:

curl -I https://example.com/gifs/2004/fun/catdance.gif
curl -IL https://example.com/gifs/2004/fun/catdance.gif
curl -sSvo /dev/null https://example.com/gifs/2004/fun/catdance.gif

-I membantu memeriksa header, -L mengikuti redirect, dan -v memperlihatkan detail request/response. Ini sangat berguna untuk membongkar redirect relatif yang salah atau loop redirect yang tidak terlihat dari browser biasa.

Root Cause 1: Rewrite Path Keliru

Kasus 404 paling umum setelah migrasi arsip GIF adalah aturan rewrite atau mapping path yang tidak cocok dengan struktur arsip lama. Biasanya tim mengasumsikan semua file mengikuti pola seragam, padahal arsip historis sering punya pengecualian.

Contoh masalah

Misalnya path lama:

/gifs/2004/fun/catdance.gif

dipetakan ke storage baru menjadi:

/archive/fun/2004/catdance.gif

padahal file sebenarnya disalin ke:

/archive/2004/fun/catdance.gif

Selisih urutan direktori seperti ini cukup untuk menghasilkan banyak 404 walaupun file ada.

Mengapa ini terjadi

• Logika migrasi dan logika rewrite ditulis terpisah
• Aturan dibuat berdasarkan sampel file modern, bukan seluruh arsip
• Ada normalisasi path yang menghapus segmen tertentu
• Trailing slash atau URL decoding tidak diperlakukan konsisten

Cara memperbaiki

1. Ekstrak aturan rewrite aktual dari konfigurasi reverse proxy atau aplikasi.
2. Bandingkan dengan manifest migrasi, bukan dengan asumsi manual.
3. Tambahkan tes untuk path historis yang tidak standar.
4. Jika perlu, gunakan tabel mapping eksplisit untuk subset arsip lama yang memang tidak konsisten.

Contoh pseudocode validasi mapping:

for each legacy_url in sample_urls:
  expected_storage_key = map_legacy_to_storage(legacy_url)
  assert expected_storage_key in migrated_manifest

Jika arsip lama punya banyak anomali, aturan rewrite tunggal sering tidak cukup. Dalam kasus seperti itu, lebih aman mempertahankan lookup berbasis manifest daripada memaksakan transformasi string yang rapuh.

Root Cause 2: Metadata MIME Tidak Terbawa

GIF yang ada secara fisik tetapi diunduh sebagai file biasanya bukan masalah file rusak, melainkan masalah metadata. Saat file diunggah ke object storage atau dilayani oleh server baru, Content-Type bisa jatuh ke nilai default seperti application/octet-stream.

Gejala khas

• Browser membuka dialog unduhan
• Tag <img> gagal menampilkan gambar di sebagian klien
• Respons 200, ukuran file benar, checksum cocok, tetapi perilaku browser salah

Mengapa ini terjadi

• Proses copy hanya memindahkan byte file tanpa metadata objek
• Uploader baru tidak mendeteksi MIME berdasarkan ekstensi
• Metadata sumber lama tidak tersedia atau hilang saat sinkronisasi
• Beberapa file memakai ekstensi campuran seperti .GIF dan pipeline tidak menormalkannya

Cara verifikasi

curl -I https://cdn.example.com/archive/2004/fun/catdance.gif

HTTP/2 200
content-type: application/octet-stream

Lalu bandingkan dengan file yang benar:

HTTP/2 200
content-type: image/gif

Cara memperbaiki

1. Jalankan skrip backfill metadata untuk seluruh objek GIF.
2. Saat upload ulang, setel Content-Type: image/gif secara eksplisit.
3. Tambahkan validasi pasca-migrasi yang menolak objek dengan MIME default generik.

Contoh alur sederhana saat upload dari backend:

putObject({
  key: 'archive/2004/fun/catdance.gif',
  body: fileBuffer,
  contentType: 'image/gif'
})

Poin pentingnya bukan nama API spesifik, melainkan prinsip bahwa metadata harus dianggap bagian dari data yang dimigrasikan, bukan detail opsional.

Root Cause 3: Redirect Relatif yang Salah

Masalah lain yang sering luput adalah redirect dari URL lama ke URL baru memakai path relatif yang salah. Hasilnya bisa berupa 404, loop redirect, atau URL akhir yang tampak aneh.

Contoh gejala

HTTP/1.1 301 Moved Permanently
Location: archive/2004/fun/catdance.gif

Header di atas tampak sepele, tetapi tanpa awalan yang benar, klien dapat menafsirkannya relatif terhadap path saat ini, bukan root situs atau host baru yang dimaksud.

Mengapa ini terjadi

• Aturan redirect dibangun dari penggabungan string yang tidak konsisten
• Perpindahan dari satu host ke host lain tidak mengubah format Location
• Pengujian hanya dilakukan pada homepage atau beberapa path dangkal

Cara memperbaiki

• Gunakan redirect absolut bila berpindah host atau domain
• Jika memakai redirect relatif, pastikan bentuknya valid dan diuji pada nested path
• Uji dengan curl -IL agar rantai redirect terlihat jelas

Contoh header yang lebih aman:

Location: /archive/2004/fun/catdance.gif

atau jika lintas domain:

Location: https://static.example.com/archive/2004/fun/catdance.gif

Root Cause 4: Filename Case-Sensitive

Arsip lama sering berasal dari lingkungan yang tidak ketat terhadap huruf besar-kecil, sementara storage baru atau server Linux memperlakukan CatDance.gif dan catdance.gif sebagai file berbeda. Di sinilah sebagian URL hanya gagal untuk subset aset lama.

Contoh kasus

• URL lama mereferensikan /GIFs/Fun/CatDance.gif
• Objek yang tersalin berada di /gifs/fun/catdance.gif
• Redirect atau rewrite tidak melakukan normalisasi yang konsisten

Mengapa ini berbahaya

Masalah ini sering tidak terlihat di pengujian manual karena developer mengetik URL versi baru yang sudah dinormalisasi. Sementara itu, halaman lama, feed, atau arsip HTML masih memuat nama file dengan kapitalisasi asli.

Cara investigasi

• Cari 404 yang path-nya sama jika diubah kapitalisasinya
• Bandingkan manifest sumber dengan target secara case-sensitive
• Periksa apakah sistem migrasi melakukan lowercasing otomatis

Cara memperbaiki

1. Tentukan strategi canonical path sejak awal: pertahankan nama asli atau normalisasi semuanya.
2. Jika dinormalisasi, sediakan lapisan lookup/redirect dari variasi lama ke canonical path.
3. Tambahkan audit yang mendeteksi collision, misalnya dua file berbeda yang menjadi sama setelah lowercasing.

Normalisasi huruf besar-kecil terdengar sederhana, tetapi dapat menyebabkan data loss logis jika dua nama file berbeda hanya pada kapitalisasi. Audit collision wajib dilakukan sebelum migrasi final.

Root Cause 5: Invalidasi Cache Tidak Lengkap

Setelah file, path, dan metadata sudah benar, kadang masalah tetap muncul karena CDN masih menyajikan respons lama: 404 yang sudah tidak relevan, header MIME lama, atau redirect lama. Ini menjelaskan kenapa origin terlihat sehat tetapi domain publik belum pulih.

Gejala khas

• Origin mengembalikan 200 image/gif, tetapi URL publik masih 404
• Perbaikan muncul di satu lokasi, tetapi tidak di lokasi lain
• Header menunjukkan respons datang dari cache, bukan origin

Mengapa ini terjadi

• Invalidasi hanya dilakukan untuk sebagian prefix
• Query string atau variasi host tidak ikut dipurge
• Redirect 301 lama tersimpan lebih lama dari yang diperkirakan
• Negative caching menyimpan 404 dari fase migrasi awal

Cara verifikasi

Bandingkan respons origin dan CDN secara langsung jika memungkinkan. Perhatikan indikator cache seperti umur respons dan status hit/miss. Lalu uji beberapa URL yang sebelumnya bermasalah:

curl -I https://origin.example.internal/archive/2004/fun/catdance.gif
curl -I https://cdn.example.com/archive/2004/fun/catdance.gif

Cara memperbaiki

1. Lakukan invalidasi berdasarkan daftar URL bermasalah atau prefix arsip terkait.
2. Jika ada perubahan metadata, pastikan purge berlaku untuk objek yang sama, bukan hanya path yang di-redirect.
3. Tinjau TTL untuk 404 dan 301 agar fase migrasi tidak meninggalkan cache basi terlalu lama.
4. Setelah purge, verifikasi dari beberapa lokasi atau jaringan bila CDN bersifat global.

Trade-off-nya jelas: purge global lebih cepat menyelesaikan masalah, tetapi bisa mahal atau menimbulkan lonjakan beban ke origin. Jika arsip sangat besar, purge selektif berbasis manifest biasanya lebih aman.

Contoh Workflow Debugging End-to-End

Berikut workflow yang bisa dipakai developer saat menerima laporan “GIF lama rusak setelah migrasi”:

1. Kumpulkan 10-20 URL contoh dari laporan pengguna, crawler error, atau access log.
2. Kelompokkan gejala: 404, unduhan tak semestinya, atau hasil tidak konsisten.
3. Uji dengan curl untuk melihat status, redirect, dan header.
4. Bandingkan dengan manifest apakah file ada di target dan path-nya sesuai.
5. Verifikasi checksum untuk memastikan file yang tersaji sama dengan sumber lama.
6. Periksa metadata objek, terutama Content-Type.
7. Bandingkan origin vs CDN untuk membedakan masalah data dari masalah cache.
8. Perbaiki per kategori, jangan campur semua dalam satu asumsi.
9. Retest URL sampel dan jalankan audit batch pada seluruh arsip.

Yang penting, jangan langsung menyimpulkan “migrasi gagal total”. Pada praktiknya, setiap kategori bug biasanya punya solusi spesifik dan dapat diperbaiki bertahap.

Langkah Perbaikan yang Bisa Diterapkan Developer

1. Bangun audit otomatis pasca-migrasi

Setelah copy selesai, jalankan job verifikasi yang memeriksa keberadaan file, checksum, dan metadata penting. Jangan menunggu laporan pengguna.

for url in sample_or_manifest:
  response = fetch_head(public_url(url))
  assert response.status == 200
  assert response.content_type == 'image/gif'

Audit bisa dimulai dari sampel, lalu diperluas ke seluruh manifest bila volume memungkinkan.

2. Simpan manifest sebagai sumber kebenaran

Manifest memudahkan rollback, diff, audit, dan purge selektif CDN. Tanpa manifest, debugging akan bergantung pada tebakan dan inspeksi manual.

3. Pisahkan logika mapping dari logika upload

Jika transformasi path tertanam di beberapa tempat, risiko inkonsistensi meningkat. Gunakan satu fungsi atau satu tabel mapping yang dipakai oleh proses migrasi, rewrite, dan validasi.

4. Perlakukan metadata sebagai bagian dari kontrak

Untuk aset statis seperti GIF, metadata minimum yang harus konsisten biasanya mencakup:

• Content-Type
• Cache-Control
• ETag atau indikator versi lain jika digunakan

Jika storage baru tidak otomatis mewarisi metadata, isi secara eksplisit saat upload.

5. Siapkan strategi purge cache sebelum cutover

Jangan menunggu cache basi muncul. Tentukan sejak awal:

• Prefix mana yang akan dipurge
• Kapan purge dilakukan
• Bagaimana memverifikasi cache sudah bersih
• Siapa yang berwenang menjalankan invalidasi darurat

Checklist Pencegahan Saat Migrasi Aset Statis Skala Besar

• Buat inventory aset: path lama, path baru, ukuran, checksum, metadata.
• Audit anomali nama file: spasi, URL encoding, huruf besar-kecil, ekstensi campuran.
• Definisikan aturan canonical path sebelum migrasi dimulai.
• Satukan fungsi mapping untuk migrasi, redirect, dan validasi.
• Pastikan metadata objek ikut dimigrasikan, terutama Content-Type.
• Uji redirect pada path dalam, bukan hanya root-level URL.
• Jalankan verifikasi checksum untuk membedakan file hilang dari file salah saji.
• Siapkan audit HEAD/GET batch ke URL publik setelah cutover.
• Rencanakan invalidasi CDN, termasuk untuk 404 dan 301 yang sempat tercache.
• Monitor access log dan error report selama beberapa hari setelah migrasi.
• Simpan daftar URL gagal sebagai bahan retest dan purge selektif.
• Siapkan rollback parsial jika subset arsip historis ternyata memerlukan penanganan khusus.

Penutup

Dalam debug backend migrasi arsip GIF, gejala 404, MIME salah, dan cache basi hampir selalu punya akar masalah yang berbeda. URL rusak biasanya berasal dari rewrite path keliru atau perbedaan case-sensitive. GIF yang terunduh alih-alih tampil umumnya disebabkan metadata Content-Type yang tidak ikut termigrasi. Sementara kasus yang “sudah diperbaiki tapi tetap salah” hampir selalu menunjuk ke cache CDN yang belum terinvalidasi dengan benar.

Pendekatan yang paling efektif adalah investigasi berlapis: cek log akses, ambil sampel URL, inspeksi header HTTP, diff manifest, verifikasi checksum, lalu uji origin dan CDN secara terpisah. Dengan proses ini, Anda bisa mengubah migrasi aset statis yang semula terasa kacau menjadi serangkaian masalah teknis yang jelas, terukur, dan bisa diselesaikan satu per satu.