İçerik Kodlama ve Sıkıştırma
Genel Bakış
API Gateway, istemci ile Backend API arasındaki mesaj akışında içerik sıkıştırma ve açma işlemlerini otomatik olarak yönetir. Bu sayede:
- Politikalar her zaman açık (sıkıştırılmamış) metin üzerinde çalışır
- İstemcinin desteklediği sıkıştırma yöntemine göre yanıt otomatik olarak sıkıştırılır
- Backend API'nin hangi formatta yanıt verdiğinden bağımsız olarak doğru işlem yapılır
Bu sayfa, sıkıştırma/açma işleminin gateway düzeyinde nasıl çalıştığını açıklar. Politikaların mesaj akışındaki yeri ve çalışma sırası için Mesaj İşleme ve Politika Uygulama sayfasına bakabilirsiniz.
Desteklenen Sıkıştırma Yöntemleri
| Yöntem | Content-Encoding Değeri | Açıklama |
|---|---|---|
| gzip | gzip | En yaygın yöntem. Tüm tarayıcılar ve HTTP istemcileri destekler. |
| deflate | deflate | zlib formatında sıkıştırma. gzip'e göre daha az yaygın. |
| Brotli | br | Google tarafından geliştirilen, yüksek sıkıştırma oranına sahip yöntem. |
| Zstandard | zstd | Facebook tarafından geliştirilen, hız ve oran dengesi iyi olan yöntem. |
| compress | compress | Eski LZW tabanlı yöntem. Sadece açma (decompress) desteklenir, sıkıştırma yapılamaz. |
| identity | identity | Sıkıştırma yok. RFC 9110'a göre kullanımdan kaldırılmış (deprecated) bir değerdir. |
İstek Akışı
İstemciden gelen sıkıştırılmış bir istek mesajı şu aşamalardan geçer:
İSTEMCİ GATEWAY BACKEND API
│ │ │
│ ── İstek (CE: gzip) ──────> │ │
│ │ 1. Sıkıştırma algıla (gzip) │
│ │ 2. Mesajı aç │
│ │ 3. Politikaları uygula (açık metin) │
│ │ 4. Tekrar sıkıştır (gzip) │
│ │ ── İstek (CE: gzip) ────────────> │
│ │ │
Aşamalar
İstek mesajındaki Content-Encoding başlığı okunur ve sıkıştırma yöntemi belirlenir. Başlık değerine ek olarak, mesaj içeriğinin ilk baytları kontrol edilerek gerçekten sıkıştırılmış olduğu doğrulanır.
Belirlenen yönteme göre mesaj içeriği açılır (decompress). Açma işlemi başarısız olursa mesaj olduğu gibi bırakılır.
İstek politikaları, açılmış düz metin üzerinde çalışır. Bu sayede dönüştürme, doğrulama ve filtreleme politikaları sıkıştırma yönteminden bağımsız olarak işlem yapabilir.
Politikalar uygulandıktan sonra mesaj, orijinal sıkıştırma yöntemiyle tekrar sıkıştırılarak Backend API'ye gönderilir.
İstisnalar: multipart/form-data türündeki isteklerde sıkıştırma açılmaz. Çünkü açma işlemi multipart sınır (boundary) yapısını bozar.
İç İçe (Stacked) Sıkıştırma
Bir istek mesajı birden fazla katmanlı sıkıştırma içerebilir (örneğin Content-Encoding: gzip, br). Bu durumda gateway, katmanları sağdan sola sırayla açar: önce Brotli, sonra gzip. Backend API'ye mesaj açık metin olarak gönderilir.
Yanıt Akışı
Backend API'den gelen yanıt mesajı, istemcinin Accept-Encoding başlığına ve rota üzerinde seçilen sıkıştırma davranış moduna göre işlenir. Yeni oluşturulan proxy'lerde varsayılan mod Client Accept-Encoding'e göre Otomatik'tir; bu modda backend düz yanıt dönse bile istemcinin kabul ettiği yöntem ile sıkıştırma uygulanır. Diğer davranış modları için Yanıt Sıkıştırma Davranış Modları bölümüne bakabilirsiniz.
Senaryo 1 — Backend sıkıştırılmış yanıt döndürür
BACKEND API GATEWAY İSTEMCİ
│ │ │
│ ── Yanıt (CE: deflate) ───> │ │
│ │ 1. Sıkıştırma algıla (deflate) │
│ │ 2. Mesajı aç │
│ │ 3. Politikaları uygula (açık metin) │
│ │ 4. İstemci AE kontrol (gzip kabul) │
│ │ 5. gzip ile sıkıştır │
│ │ ── Yanıt (CE: gzip) ────────────> │
│ │ │
Senaryo 2 — Backend düz yanıt döndürür, istemci sıkıştırma kabul eder (varsayılan mod)
BACKEND API GATEWAY İSTEMCİ
│ │ │
│ ── Yanıt (düz metin) ──────> │ │
│ │ 1. Politikaları uygula (açık metin) │
│ │ 2. İstemci AE kontrol (gzip kabul) │
│ │ 3. gzip ile sıkıştır │
│ │ ── Yanıt (CE: gzip) ────────────> │
│ │ │
İstemci Accept-Encoding başlığı göndermezse veya hiçbir desteklenen yöntem kabul edilmiyorsa, yanıt düz metin olarak iletilir. Rota üzerinde Backend Yanıtını Mirror'la seçilirse 2. senaryoda gateway sıkıştırma uygulamaz; düz yanıt aynen istemciye iletilir.
Encoding Seçim Sırası
İstemcinin Accept-Encoding başlığında birden fazla yöntem varsa, gateway şu sabit sırayla seçim yapar:
- gzip
- deflate
- br (Brotli)
- zstd (Zstandard)
Accept-Encoding başlığındaki q-value (kalite) değerleri şu an için dikkate alınmaz. Bu, sektördeki diğer gateway'lerle (Nginx dahil) tutarlı bir davranıştır.
Accept-Encoding: * (Wildcard)
İstemci Accept-Encoding: * gönderdiğinde, gateway bunu "tüm yöntemleri kabul ediyorum" olarak yorumlar ve yukarıdaki sıraya göre en uygun yöntemi seçer (RFC 9110 §12.5.3 uyumlu).
Yanıt Sıkıştırma Davranış Modları
Yanıt gövdesinin gateway tarafından nasıl sıkıştırılacağını kontrol etmek için dört farklı davranış modu tanımlanabilir. Varsayılan davranış yeni oluşturulan proxy'lerde Client Accept-Encoding'e göre Otomatik'tir. Eski sürümlerden yükseltilen ortamlarda mevcut proxy'lerin davranışı veritabanı geçişi ile aynen korunmuştur.
| Mod | Açıklama | Ne Zaman Kullanılır |
|---|---|---|
| Client Accept-Encoding'e göre Otomatik (varsayılan) | İstemcinin Accept-Encoding başlığında kabul ettiği ilk yöntem ile yanıt sıkıştırılır. Backend yanıtı düz metin dönse bile gateway sıkıştırma uygular. | Bant genişliği optimizasyonu için, backend'in sıkıştırma yapmadığı durumlarda gateway'in bu işi otomatik üstlenmesi istendiğinde. |
| Backend Yanıtını Mirror'la | Backend yanıtı düz dönerse istemciye düz iletilir; sıkıştırılmış dönerse aynı yöntem ile yeniden sıkıştırılarak iletilir. Gateway encoding'i değiştirmez. | Backend'in encoding kararına saygı duyulması gereken durumlarda; ek dönüşümün istenmediği şeffaf akışlarda. |
| Belirli Bir Yöntem (GZIP / DEFLATE / BR / ZSTD) | İstemcinin Accept-Encoding başlığı veya backend'in döndürdüğü encoding ne olursa olsun, yanıt belirtilen yöntem ile sıkıştırılır. | Belirli bir istemci grubunun yalnızca tek bir yöntem desteklediği veya zorunlu sıkıştırma standardı uygulanması gereken durumlarda. |
| Uygulanmasın | Sıkıştırma hiçbir koşulda yapılmaz. Backend yanıtı düz iletilir, sıkıştırılmış geldiyse açılır ve düz iletilir. | İstemcinin sıkıştırılmamış yanıt beklediği veya hata ayıklama için sıkıştırmanın devre dışı bırakılması gereken durumlarda. |
Yeni oluşturulan proxy'ler varsayılan olarak Client Accept-Encoding'e göre Otomatik modundadır. Eski sürümlerden yükseltilen ortamlarda mevcut proxy'lerin davranışı korunur.
İkili (Binary) İçerik Davranışı
Resim, video, PDF gibi ikili içerikler metin içeriklerden farklı işlenir:
İndirme Aktif (Download Enabled)
İndirme özelliği açık olan proxy'lerde ikili içerik doğrudan akış (streaming) ile istemciye iletilir. Bu yöntemde:
- İçerik bellekte tutulmaz, parça parça aktarılır
- Büyük dosyalarda bellek tüketimi minimum kalır
- İstemcinin desteklemediği bir sıkıştırma varsa otomatik olarak açılır
- Politikalar yanıt gövdesini değiştiremez (içerik zaten gönderilmeye başlamıştır)
İndirme Kapalı
İndirme özelliği kapalı olan proxy'lerde ikili içerik Base64 formatına dönüştürülerek politika hattına girer. Politikalar Base64 kodlanmış metin üzerinde çalışır. İstemciye gönderimde orijinal ikili format geri oluşturulur.
Karakter Seti ve Kodlama Geçersiz Kılma
Yukarıda açıklanan otomatik sıkıştırma davranışı, Yönlendirme yapılandırmasındaki Karakter Seti ve Kodlama Geçersiz Kılma ayarları ile rota bazında geçersiz kılınabilir. Bir geçersiz kılma yapılandırıldığında, gateway Content-Encoding ve Content-Type başlığındaki charset değerlerini dikkate almaz; bunun yerine yapılandırılan değeri uygular.
Bu özellik şu durumlarda kullanışlıdır:
- Backend API
Content-Encodingbaşlığı göndermeden sıkıştırılmış içerik döndürüyorsa Content-Typebaşlığında belirtilen charset, içeriğin gerçek kodlamasıyla eşleşmiyorsa- Giden istek veya yanıta, içerik başlıklarından bağımsız olarak belirli bir sıkıştırma yönteminin uygulanması gerekiyorsa
Geçersiz kılma iki yön için ayrı ayrı yapılandırılır:
| Yön | Yapılandırılabilir Alanlar |
|---|---|
| İstek Hattı (İstemci → Backend) | Charset Geçersiz Kılma, Sıkıştırma Açma Geçersiz Kılma, Sıkıştırma Geçersiz Kılma |
| Yanıt Hattı (Backend → İstemci) | Charset Geçersiz K ılma, Sıkıştırma Açma Geçersiz Kılma, Sıkıştırma Geçersiz Kılma |
Sıkıştırma açma veya sıkıştırmayı o yön için açıkça atlamak istiyorsanız Uygulanmasın (atla) seçeneğini kullanın.
- Sıkıştırma Açma Geçersiz Kılma seçenekleri (her iki yön): GZIP, DEFLATE, BR (Brotli), ZSTD, Uygulanmasın (atla).
- İstek Sıkıştırma Geçersiz Kılma seçenekleri: GZIP, DEFLATE, BR (Brotli), ZSTD, Uygulanmasın (atla).
- Yanıt Sıkıştırma Geçersiz Kılma seçenekleri: Backend Yanıtını Mirror'la, Client Accept-Encoding'e göre Otomatik (varsayılan), GZIP, DEFLATE, BR (Brotli), ZSTD, Uygulanmasın (atla).
Tam yapılandırma detayları için bkz. HTTP Yönlendirme — Karakter Seti ve Kodlama Geçersiz Kılma.
no-transform Davranışı
Backend API, yanıtında Cache-Control: no-transform başlığı gönderdiğinde, gateway içerik üzerinde hiçbir sıkıştırma veya açma dönüşümü yapmaz:
- Backend'in sıkıştırma yöntemi ve içeriği olduğu gibi istemciye iletilir
Content-Encodingbaşlığı değiştirilmezVaryveWarningbaşlıkları eklenmez
Bu davranış, CDN ve önbellek katmanlarının tutarlılığını korumak için önemlidir.
Otomatik Eklenen Başlıklar
Gateway, sıkıştırma dönüşümü uyguladığında yanıta otomatik olarak iki başlık ekler:
| Başlık | Değer | Açıklama |
|---|---|---|
Vary | Accept-Encoding | Önbellek katmanlarına, yanıtın istemcinin encoding tercihine göre değiştiğini bildirir |
Warning | 214 - "Transformation Applied" | İçerik üzerinde dönüşüm yapıldığını belirtir (RFC 9111 §5.5) |
Kısıtlar ve Bilinen Davranışlar
Sabit Encoding Seçim Sırası
Gateway, istemcinin Accept-Encoding başlığındaki q-value tercihlerini dikkate almaz. Örneğin istemci br;q=1.0, gzip;q=0.5 gönderirse, gateway Brotli yerine gzip'i seçer. Bu, Nginx ve çoğu gateway ile tutarlı bir davranıştır.
Brotli Otomatik Algılama Yapılamaz
Brotli sıkıştırmasının ayırt edici bayt dizisi (magic bytes) yoktur. Content-Encoding başlığı olmadan Brotli içerik algılanamaz.
İç İçe Sıkıştırma (Binary)
İkili içeriklerde iç içe (stacked) sıkıştırma kısmen desteklenir. Metin içeriklerde tüm katmanlar sırayla açılırken, ikili streaming modunda yalnızca dış katman işlenir.
identity;q=0 Durumu
İstemci Accept-Encoding: identity;q=0 gönderirse (sıkıştırılmamış içerik istemiyorum), RFC 9110'a göre gateway 406 yanıtı verebilir. Ancak Nginx ve diğer gateway'lerle tutarlı olarak, gateway düz metin olarak yanıt verir ve 406 döndürmez.
Streaming Modunda Politika Kısıtı
İndirme aktifken ikili içerik streaming ile gönderilir. Bu modda yanıt politikaları mesaj gövdesini değiştiremez çünkü içerik zaten istemciye aktarılmaya başlamıştır. İstek politikaları bu durumdan etkilenmez.