Büyük Bir PDF Yüklemesi Reddedildiğinde: 100 MiB İstek Gövdesi Sınırı ve Sizi Yanlış Yöne Saptıran Hata

Yüklenmeyen büyük bir PDF genellikle bozuk bir dosya değildir. İstek gövdesi istek başına sınıra dayanmıştır: 100 MiB, yani 104,857,600 bayt. Bu sınır tüm gövde üzerinden ölçülür; multipart sınırlayıcıları ve alan başlıkları dahildir ve tam bu sayı geçerken bir bayt fazlası reddedilir.

Geri dönen hata başka bir yeri işaret eder. İşlem uç noktaları code değeri bad_request olan bir 400 ve bir multipart alanının okunamadığını söyleyen bir ayrıntı döndürür; boyuttan hiçbir yerde söz edilmez. code değerine göre dallanan bir istemci bunu parametre hatası olarak kaydeder ve alan adlarını denetlemeye gider; oysa değiştirilmesi gereken dosya boyutudur.

Aynı 100 MiB karşı yönü de yönetir. Idempotency-Key taşıyan bir istek, önbelleğe almadan önce yanıtı belleğe okur; burada da aynı sayı geçerlidir ve aşılırsa çağıran, işlem çoktan bitmiş olmasına karşın 500 alır. Tek sayı, iki karşıt arıza biçimi.

                     100 MiB = 104,857,600 bayt (tam bu sayı geçer)
                                   |
                +------------------+------------------+
                |                                     |
   gelen (istek gövdesi)                   giden (yanıt gövdesi)
   tüm gövde, multipart sınırlayıcıları    yalnızca Idempotency-Key ile,
   ve alan başlıkları dahil; tek bir       önbellekte bulunamama ve
   işlem ile bir ardışık düzen paylaşır    kaynakta 2xx
   aşılırsa: 400 + bad_request             aşılırsa: 500, önbelleğe yazılmaz
   (ayrıntı: multipart alanı okunamadı)

Şekil notu: tek bir sınır ve bu sınırın gelen ile giden tarafları farklı durum kodları ve karşıt sonuçlar döndürür.

Sınır tüm istek gövdesini sayar, sınırlayıcılar dahil

100 MiB tek bir isteğin gövdesini sınırlar; ne tek bir dosyanın boyutunu ne de açıldıktan sonraki boyutu.

• Tek bir işlem ile çok adımlı bir ardışık düzen bu sayıyı paylaşır. İşi tek bir /api/v1/pipeline çağrısı içinde 10 adıma bölmek tavanı 1 GB yapmaz; adım sayısı yalnızca çalışma süresini etkiler.
• Sınır değerinin kendisi geçer: 104,857,600 baytlık bir istek gövdesi geçer, 104,857,601 bayt geçmez.
• Gövde, dosya baytlarının yanı sıra her alanın başlıklarını ve sınırlayıcı işaretlerini de taşır; bu yüzden tek bir dosyaya kalan pay kesinlikle 100 MiB’ın altındadır. Tam olarak 104,857,600 baytlık bir dosya reddedilir.

Son nokta, uygulamanın en kolay tökezlediği yerdir: curl -F sınırlayıcıları sizin yerinize ekler, bu yüzden bir dosya boyutunu o çizgiyle karşılaştırmak hiçbir zaman doğru sonuç vermez.

Sınır aşıldığında 400 ve bad_request alırsınız

Sınırı aşan bir yanıt 413 kullanmaz ve boyuttan söz eden hiçbir ifade taşımaz. Bir bayt aşan bir gövdeyle yeniden üretin:

head -c 104857601 /dev/zero > /tmp/over.bin
curl -s -X POST "$API_BASE/api/v1/misc/compress-pdf" \
  -H "X-API-KEY: $API_KEY" \
  -F "fileInput=@/tmp/over.bin"

HTTP/1.1 400 Bad Request
content-type: application/problem+json

{ "code": "bad_request",
  "detail": "failed to read multipart field: Error parsing `multipart/form-data` request",
  "hint": "Fix request parameters or upload a valid PDF.",
  "status": 400,
  "title": "Bad Request",
  "type": "https://pdf123.xyz/developers/errors#bad_request" }

Birlikte okunacak üç şey:

• Durum kodu 400. Burada başarısız bir gövde okuması bad_request olarak sınıflandırılır ve yine problem+json üzerinden gider; yani “sınır aşıldıysa 413 gelir” diye yazılmış bir istemci yanlış dala sapar.
• code değeri, hata kodu tablosunda gerçek bir girdi olan bad_request değeridir. Bir genel yakalama dalına düşmez; yanlış yazılmış bir alan adıyla ya da bozuk bir multipart kodlamasıyla aynı kodu paylaşır ve o tabloda boyutla ilgili hiçbir şey yoktur.
• hint size geçerli bir PDF yüklemenizi söyler. Yüklediğiniz dosya büyük olasılıkla geçerli bir PDF’tir, yalnızca birkaç yüz bayt fazladır.

İşaret öyleyse durum kodunda değil, gövdenin bayt sayısındadır: detail alanında failed to read multipart field geçen bir 400 aldığınızda, formu baştan gözden geçirmek yerine bir sonraki adımda boyutu ölçün.

413 bu sitede de görülür, yalnızca işlem uç noktalarında değil. Dosya yüklemesi kabul eden her giriş noktası 100 MiB’a yükseltilmiştir; yükleme almayan uç noktalar ise hâlâ HTTP çerçevesinin (Rust’ın axum’u) varsayılan 2 MiB sınırıyla çalışır ve orada sınırı aşan bir gövde 413 ile tek satır düz metin alır:

head -c 2097153 /dev/zero > /tmp/big.json
curl -s -w '\n%{http_code}\n' -X POST "$API_BASE/api/v1/auth/login" \
  -H 'Content-Type: application/json' \
  --data-binary @/tmp/big.json

Failed to buffer the request body: length limit exceeded
413

Tek bir olgu, uç noktaya bağlı olarak iki durum kodu ve iki yanıt gövdesi. İki deneyimden birini diğerine taşımak sizi yanıltır.

Aynı sayının öbür arızası: dönüş yönünde

Idempotency-Key içeren bir istek, bir yeniden denemenin onu yeniden oynatabilmesi için yanıtını önbelleğe alır. Önbelleğe almak, yanıt gövdesinin önce belleğe okunması demektir ve bu okuma da aynı 100 MiB ile sınırlıdır; ancak çok daha dar bir koşul kümesiyle:

1. İstek Idempotency-Key taşıyordu
2. Önbellekte bulunamadı, yani bu anahtar yeni
3. Üst akıştaki işlem 2xx döndürdü

Başarısız yanıtlar önbelleğe alınmaz ve doğrudan geçer; bu yüzden bu sınıra yalnızca başarılı ve büyük bir çıktı ulaşır.

Orada olan şey hatırlanmaya değer: 500 alırsınız ve önbelleğe hiçbir şey yazılmaz. İşlem çoktan çalışmıştır, ama çağıran bir hata görür; hiçbir şey önbelleğe alınmadığı için yeniden deneme her şeyi baştan çalıştırır. Idempotency anahtarı yinelenen işi ortadan kaldırmak için vardır ve tam da en çok gerektiği anda başarısız olur, bitmiş bir işi sunucu arızası gibi gösterir. Önbellek süreç belleğinde yaşar ve hiçbir zaman diske yazılmaz, dolayısıyla yeniden başlatma onu temizler; anlambilim için bkz. Idempotency-Key: PDF İşleri için Güvenli Yeniden Denemeler.

100 MiB yapılandırılabilir bir platform ayarı değildir

Sayı değiştirilemez. Hiçbir ortam değişkeni onu ne yükseltir ne düşürür, her iki yönde de olmaz; farklı bir sayı kodu değiştirip imajı yeniden derlemek demektir. Onu bir dağıtım ayarı olarak ararsanız bulamazsınız.

Aynı zamanda bir kotadan fazlasıdır. İstek gövdesinin baytları işlenmeden önce tamamen belleğe okunur, dolayısıyla her eşzamanlı büyük yükleme yanında benzer büyüklükte bir yer tutar. Tavanı yükseltmek, beraberinde daha yüksek bir bellek zirvesini kabul etmek demektir: bu sayı aynı zamanda tek bir isteğin süreci aşağı çekmesini engelleyen şeydir.

Varsayılan bir kendi kendine barındırılan dağıtımda ters vekil sunucu yoktur ve portal göndermeden önce boyutu denetlemez; bu yüzden o ret sunucunun kendi sınırından gelir. Önüne nginx koyarsanız ilk önce nginx’e çarparsınız: client_max_body_size varsayılan olarak yalnızca 1 MiB’a izin verir ve 413 döndürür; yukarıdaki karşılaştırmadakine yakın bir biçimdir ve aynı sınırla karıştırılması kolaydır.

Bu sınıra çarptığınızda ne yapmalı

En ucuzdan başlayarak:

1. Göndermeden önce ölçün. İstek çıkmadan önce istek gövdesinin bayt sayısını 104,857,600 ile karşılaştırın ve sınırlayıcılar için pay bırakın. Bu, sonradan bir durum kodu okumaktan iyidir.
2. Dosyayı sınırın altına sıkıştırın. Bir taramanın boyutu çoğunlukla görüntü katmanından gelir ve yeniden sıkıştırma düzenli olarak bunun görünür bir bölümünü kaldırır. PDF Sıkıştır tarayıcıda çalışır, betiğe gerek yoktur.
3. İşi birkaç çağrıya bölün. İçerik bölünebiliyorsa bölün ve birkaç istekte gönderin: tavanı yükseltmekten daha az zahmetlidir ve tek bir isteğin tuttuğu belleği artırmaz.
4. Sınırı yalnızca tek istekte karşılanması zorunlu bir gereksinim için değiştirin. Bu, kodu değiştirip yeniden derlemek ve önceki bölümdeki bellek maliyetini kabul etmek demektir.

Bu sınır istemciden önceden karar vermesini ister

Her iki arıza da tek bir sonuca işaret eder: 100 MiB sayısını istemcinin göndermeden önce hesaplaması gerekir. Gelen yönde size bad_request ile yanıt verilir; bu kod boyut hakkında hiçbir şey söylemez; giden yönde ise sunucu arızası gibi görünen 500 ile. İstek çıkmadan önce baytları saymak, bir hata iletisinin ne dediğine bağlı olmayan tek yargı yoludur.