← All writingEngineering notes

Sebagian besar isi web crawler itu rejection handling ​

3 Agustus 2026

robots.txt, challenge Cloudflare, circuit breaker, dan antrean yang tak pernah membuang job.

Mengambil satu halaman cuma satu baris kode. Yang sulit adalah semua usaha server supaya tidak diambil.

Log saya penuh 403 dan soft-200, yaitu respons 200 OK yang isinya halaman challenge Cloudflare, bukan konten. Sebagian besar pekerjaan adalah mengurus belasan cara berbeda sebuah server berkata "tidak".

Di bawah ini saya bahas membaca robots.txt, mengatur jeda request per host, naik ke pertahanan bot yang lebih berat hanya kalau terpaksa, mengenali challenge page yang pura-pura sukses, dan tahu kapan berhenti retry. Semuanya pernah saya kerjakan dengan salah dulu.

Sopan santun dulu, karena kasar bikin diblokir ​

Awalnya saya menganggap ini adu licik: situs yang memblokir pasti mendeteksi trik yang kurang rapi saya sembunyikan. Ternyata terbalik. Kebanyakan blokir itu cuma rate limiter yang bereaksi pada seratus request yang saya kirim dalam satu detik. Obatnya berhenti bersikap kasar, bukan menyamar lebih baik.

Tiga hal mengerjakan sebagian besar urusannya.

robots.txt, dengan cache yang membedakan kegagalan definitif dari yang sementara. Saya mem-parse-nya dengan temoto/robotstxt dan menyimpan hasilnya 24 jam. 404 artinya "tidak ada aturan", jawaban yang pasti, jadi saya cache sebagai boleh-semua. 5xx atau timeout artinya "saya belum sempat bertanya", jadi tidak ada yang di-cache dan saya coba lagi nanti. Salah ke arah mana pun merugikan. Kalau 5xx sesaat di-cache sebagai blokir, kita terkunci dari situs yang cuma mati sepuluh detik. Kalau disallow yang asli dianggap gangguan sementara, kita terus menembus path yang jelas diminta untuk dijauhi.

Jam jeda per host. Tiap host mendapat max(default saya 1000ms, Crawl-delay milik situs), dibatasi 60 detik supaya situs yang memasang Crawl-delay: 3600 tidak bisa membekukan worker. Kode jeda mengklaim slot di dalam lock, lalu tidur setelah lock dilepas:

go
// Satu "waktu boleh berikutnya" per host. Klaim slot Anda di dalam lock,
// lalu lepas dan tidur. Goroutine yang menuju host yang sama tetap dapat
// jeda yang benar, dan tak ada yang macet di sleep.
func (p *politeness) pace(host string, delay time.Duration) time.Duration {
    p.mu.Lock()
    hp := p.hosts[host]
    now := time.Now()
    if hp.next.Before(now) {
        hp.next = now
    }
    wait := hp.next.Sub(now)
    hp.next = hp.next.Add(delay) // klaim slot berikutnya sebelum lepas lock
    p.mu.Unlock()
    return wait // pemanggil tidur selama `wait` di luar lock
}

Frontier dipartisi per domain. Domain tiap URL di-hash dengan FNV-1a lalu diarahkan ke partisi yang tetap, jadi semua URL example.com selalu jatuh ke worker yang sama. Dengan begitu pengaturan jeda per host cukup disimpan di memori lokal, dan tidak ada worker yang perlu berkoordinasi dengan worker lain untuk tahu kapan sebuah host terakhir disentuh. Alternatifnya, shared token bucket di Redis, menambah satu round-trip jaringan dan satu dependensi untuk sesuatu yang sebenarnya cuma timestamp di sebuah map. (Map-nya dibatasi LRU di 50.000 host.)

Tanpa ini, rentang IP crawler diblokir dalam satu sore.

Tangga eskalasi ​

Sebagian situs butuh lebih dari sopan santun. Mereka berada di belakang Cloudflare atau pertahanan bot sejenis. Naluri pertama adalah langsung mengeluarkan alat terberat: headless browser penuh yang me-render semuanya. Tapi itu lambat dan boros sumber daya, dan sistem challenge memang dibuat untuk mengenali otomasi, jadi memulai dari browser lebih mahal tanpa lebih andal.

Karena itu fetcher naik bertingkat, mulai dari yang termurah.

Tier 1: HTTP polos. Request net/http, timeout 20 detik, body dibatasi 16 MiB. Setiap redirect divalidasi ulang lewat penjaga SSRF yang memblokir skema selain HTTP dan, setelah resolusi DNS, menolak tersambung ke loopback, alamat privat, link-local, dan alamat metadata cloud 169.254.169.254. Sebagian besar request tidak pernah keluar dari tier ini.

Tier 2, di atas kertas: meniru TLS fingerprint. Anak tangga tengah yang lazim adalah membuat TLS handshake (JA3/JA4) mirip Chrome asli dan menyimpan cookie cf_clearance supaya host yang sudah lolos berhenti menantang. Tier ini sudah dirancang tapi belum dibangun. Hari ini fetcher melompat dari tier 1 ke tier 3. Siapa pun yang mengaku punya bypass Cloudflare yang sudah jadi biasanya sedang menjual sesuatu.

Tier 3: browser sungguhan, di luar proses. Kalau request kena challenge, URL dikirim lewat HTTP ke browser sidecar eksternal (layanan ala FlareSolverr), bukan ke headless Chrome di dalam proses crawler. Karena terpisah, browser yang crash atau bocor memori tidak ikut menjatuhkan crawler. Panggilannya dibatasi semaphore 2 dan timeout 30 detik.

Eskalasi hanya terjadi pada dua sinyal: HTTP 403, atau respons 200 yang sebenarnya challenge page (bagian berikutnya). 5xx biasa tidak memicu eskalasi. Server yang sedang down itu urusan retry dan backoff, dan menghabiskan slot browser yang terbatas untuk itu cuma pemborosan.

Mendeteksi respons yang berbohong ​

Soft-200 paling banyak makan waktu saya. Kalau percaya pada status code, kita akan menyimpan sejuta challenge page dan mengira crawl berjalan lancar.

Deteksinya dua bagian:

go
var challengeMarkers = []string{
    "just a moment", "challenge-platform", "cf_chl",
    "/cdn-cgi/challenge", "attention required",
    "enable javascript and cookies", "cf-browser-verification", "turnstile",
}

func needsEscalation(body []byte) bool {
    lower := bytes.ToLower(body)
    for _, m := range challengeMarkers {
        if bytes.Contains(lower, []byte(m)) {
            return true
        }
    }
    // Density check: halaman yang cukup besar tapi byte-nya nyaris semua
    // script/markup dan nyaris tanpa teks tampak. JS shell yang belum
    // ter-render.
    return len(body) > 2048 && visibleTextLen(body) < 200
}

Bagian pertama adalah daftar string yang hampir selalu muncul di challenge page. Bagian kedua pengecekan kepadatan yang kasar: buang <script> dan <style>, buang sisa tag, lalu hitung teks yang tersisa. Kalau HTML mentahnya di atas 2 KB tapi teks yang terlihat kurang dari 200 byte, hampir pasti itu JavaScript shell yang belum ter-render. Serahkan ke tier browser, yang bisa menunggu halamannya terisi.

Pengecekan kepadatan ini sengaja tidak presisi. Sesekali ia salah menilai halaman yang memang tipis, tapi murah dan benar hampir selalu. Itu pertukaran yang saya mau, karena alternatifnya me-render setiap halaman di browser hanya demi memastikan.

Tahu kapan berhenti retry ​

Ini yang paling lama saya pelajari. Kadang tier browser pun tidak bisa melewati challenge. Bukan salah konfigurasi, tapi pertahanan situs itu memang belum bisa ditembus hari ini. Naluri saya waktu itu adalah mencoba lagi.

Suatu malam sebuah browser sidecar tidak bisa menyelesaikan challenge Cloudflare yang modern. Ia tidak crash. Ia hidup dan gagal pelan-pelan, menghabiskan timeout penuh di setiap URL: 48 dari 49 percobaan timeout di atas 60 detik. Panggilan-panggilan itu menumpuk sampai menyentuh batas in-flight antrean, dan seluruh crawl consumer macet. Pukul 02:45, 722 job sudah masuk dead-letter. Satu host yang tidak tertembus menghentikan semuanya, karena setiap worker ikut menunggu di situ.

Perbaikannya circuit breaker, tapi ia tidak boleh sekadar menghitung kegagalan per target: situs sulit yang tetap mengembalikan halaman asli tidak seharusnya di-blacklist. Jadi breaker ini memutus berdasarkan kesehatan backend, bukan tingkat kesulitan target:

go
// Putus karena sidecar-nya sakit, bukan karena target-nya keras.
// Backend mati: timeout, connection refused, challenge tak terpecahkan (Status == 0).
// Backend sehat yang me-render halaman yang memang berat (Status != 0)
// TIDAK dihitung melawan breaker.
func browserBackendFailure(err error, status int) bool {
    return err != nil || status == 0
}

Lima kegagalan backend berturut-turut membuka breaker selama dua menit. Setelah itu ia meloloskan tepat satu probe untuk menguji pemulihan. Saya juga memangkas timeout browser dari 90 detik jadi 30. Panggilan macet yang gagal cepat mengembalikan slot-nya ke URL yang mungkin masih bisa diselesaikan.

Antrean tak pernah membuang job ​

Di bawah semua ini ada work queue NATS JetStream: satu durable stream per tahap pipeline, dengan retensi WorkQueuePolicy supaya pesan hilang begitu di-ack. Job yang gagal di-retry dengan jadwal sisi klien 2s, 10s, 30s, 60s, 120s, sampai 8 kali pengiriman, lalu masuk status dead-letter.

JetStream punya field BackOff per consumer yang tampaknya persis untuk mengatur jarak retry. Saya membiarkannya kosong. Kalau diisi, BackOff[0] menimpa AckWait, sehingga backoff pertama 2 detik mengecilkan jendela ack jadi 2 detik, dan handler yang butuh lebih lama dikirim ulang saat masih bekerja. Job yang sama lalu jalan beberapa kali dan sulit dilacak sebabnya. Karena itu backoff saya taruh di kode sendiri, dan AckWait tetap 30 detik penuh.

NATS mengirim at-least-once, sedangkan saya mau setiap efek terjadi sekali. Jadi setiap worker menulis outputnya dan job tahap berikutnya ke Postgres dalam satu transaksi (pola transactional outbox). Sebuah relay mem-poll tabel itu tiap 500ms dan mem-publish dengan message ID deterministik supaya race tidak menghasilkan duplikat. Job yang kehabisan retry tidak dibuang. Ia ditandai failed dan dibiarkan di tempatnya, dan ada perintah operator untuk me-redrive satu batch setelah penyebab macetnya diperbaiki.

Menemukan halaman baru tanpa menggeledah search engine ​

Cara paling jelas menemukan URL baru adalah bertanya ke search engine besar. Itu juga cara tercepat untuk diblokir. Search engine paling ketat soal lalu lintas otomatis, dan IP datacenter adalah yang pertama mereka tolak. Jadi saya tidak men-scrape hasil pencarian. Saya memakai API resmi yang memang dibuat untuk dipanggil: satu API web-search berbayar ditambah beberapa API ensiklopedis dan akademis tanpa kunci, dipanggil paralel, hasilnya digabung dan di-dedup berdasarkan URL yang sudah dinormalisasi. Kalau satu mati, yang lain tetap jalan. Lead dari jalur ini mendapat relevance prior lebih rendah (0.5) daripada curated seed (0.9).

Bug terburuk proyek ini juga ada di sini. Sumber link baru terkaya saya adalah halaman kategori ensiklopedia, yang bukan konten, cuma daftar link. Saya menjalankan relevance filter pada halaman sebelum memanen link-nya. Halaman kategori dalam bahasa daerah, yang judul dan isinya tidak cocok dengan kosakata relevansi saya yang satu bahasa, gagal di filter itu dan dibuang beserta semua link di dalamnya. Saya mematikan multilingual discovery di sumbernya, dan tidak ada yang error.

Perbaikannya, tentukan dulu halaman itu apa, baru tentukan relevan atau tidak:

go
// Putuskan halaman ini APA sebelum memutuskan apakah ia relevan.
// Halaman lead/listing selalu dipanen link-nya, dalam bahasa apa pun.
// Hanya kandidat konten sungguhan yang lewat relevance gate.
func routePage(isDoc, isLead, isListing, relevant bool) disposition {
    switch {
    case isDoc:      return dispExtract      // dokumen asli (termasuk PDF)
    case isLead:     return dispHarvestOnly  // mis. hub ensiklopedia
    case isListing:  return dispHarvestOnly  // halaman indeks/paginasi
    case relevant:   return dispExtract
    default:         return dispReject
    }
}

Supaya hub berbahasa daerah bisa di-parse, saya juga harus mengajari harvester kata setempat untuk "Kategori" di belasan bahasa: tumbung di Banjar, kawan di Aceh, dalala di Gorontalo, ditambah kata serumpun untuk bahasa-bahasa tetangganya. Satu kelompok halaman yang tadinya tak terlihat, karena saya tidak bisa membaca labelnya, jadi terjangkau.