İstek hattı ve ara katmanlar

Bu sayfa bir HTTP isteğini Cluster ERP sunucusunda soketten rotaya ve geri izler. server/app.py içinde eklenen beş ara katmanı, server/middleware.py içindeki iki ara katman sınıfını, istek bağlamını, gövde sınırını ve web uygulamasının statik bağlamalarını kapsar. Kimlik doğrulama ve kiracı yönlendirmesi rota bağımlılıklarında olur ve kimlik ve erişim bölümünde belgelenir.

Kısaca¶

• create_app beş ara katman ekler: CommitBeforeResponseMiddleware, ActivityLogMiddleware, GZipMiddleware, _console_cors ve _security_headers (src/cluster_erp/server/app.py:1317-1430). Üç add_middleware çağrısı ve iki @app.middleware("http") dekoratöründen sayıldı.
• Starlette yeni eklenen her ara katmanı öncekilerin dışına yerleştirir; bu yüzden istek onlardan kayıt sırasının tersiyle geçer.
• _security_headers, max_request_body_bytes değerinden büyük bir gövdeyi okumadan HTTP 413 ile reddeder ve her yanıta güvenlik başlıkları koyar (src/cluster_erp/server/app.py:1390-1430).
• ActivityLogMiddleware, her istek için bir etkinlik günlüğü satırı, ele alınan hatalar için bir hata günlüğü satırı yazar; bunu bir arka plan görevinde yapar (src/cluster_erp/server/middleware.py:424-663).
• CommitBeforeResponseMiddleware, isteğin oturumunu ilk yanıt baytından önce onaylayan yanıt öncesi kancaları çalıştırır (src/cluster_erp/server/middleware.py:25-57).

Nasıl çalışır¶

Katmanların sırası¶

Starlette'in add_middleware işlevi her ara katmanı listesinin başına ekler ve yığın ilk girdi en dışta olacak biçimde kurulur (Starlette ara katman belgeleri). @app.middleware("http") aynı liste üzerinden kaydeder. create_app içindeki kayıt sırası CommitBeforeResponseMiddleware, ActivityLogMiddleware, GZipMiddleware, _console_cors, _security_headers'tır (src/cluster_erp/server/app.py:1317, src/cluster_erp/server/app.py:1318, src/cluster_erp/server/app.py:1323, src/cluster_erp/server/app.py:1365, src/cluster_erp/server/app.py:1390). Bu yüzden bir istek onlardan şu sırayla geçer:

flowchart TD
 client["İstemci"] --> proxy["uvicorn ProxyHeadersMiddleware, trust_proxy_headers açıkken"]
 proxy --> sec["_security_headers: gövde sınırı, güvenlik başlıkları"]
 sec --> cors["_console_cors: yalnızca filo ucu için CORS"]
 cors --> gzip["GZipMiddleware: 1 KB üzerindeki yanıtlar"]
 gzip --> act["ActivityLogMiddleware: etkinlik ve hata günlüğü"]
 act --> commit["CommitBeforeResponseMiddleware: yanıt öncesi kancalar"]
 commit --> exc["İstisna işleyicileri"]
 exc --> route["Rota ve bağımlılıklar"]

Tablo her katmanı listeler.

İçerik güvenlik politikası betiklere, stillere, görsellere, yazı tiplerine, çerçevelere ve bağlantılara yalnızca aynı kökenden, belirtilen yerlerde blob: ve data: ile izin verir; satır içi betiğe izin vermez (src/cluster_erp/server/app.py:1325-1352).

Etkinlik günlüğü¶

activity_log_skip_paths içinde olmayan her istek için ActivityLogMiddleware.dispatch:

1. POST, PUT ve PATCH isteklerinin gövdesini okur (src/cluster_erp/server/middleware.py:438-441).
2. Sonraki katmanı çağırır. O katman istisna yükseltirse istisnayı iki günlüğe de yazar, istek durumuna bir izleme kimliği koyar ve istisnayı yeniden yükseltir (src/cluster_erp/server/middleware.py:443-453, src/cluster_erp/server/middleware.py:498-528).
3. Yazma istekleri ve tek kayıt üzerindeki GET istekleri için yanıt gövdesini okur ve yanıtı ham başlık listesiyle yeniden kurar (src/cluster_erp/server/middleware.py:455-487).
4. _write_log işlevini bir görev olarak başlatır ve yanıtı döndürür (src/cluster_erp/server/middleware.py:489-496).

_write_log, activity_log_enabled kapalıysa durur (src/cluster_erp/server/middleware.py:542-543). İsteğin kiracı veritabanını seçer (src/cluster_erp/server/middleware.py:340-375, src/cluster_erp/server/middleware.py:561), işlemi yapanı ve kullanıcı adını çözer, log_sanitize_keys ve log_sanitize_path_keys içinde listelenen gövde anahtarlarını maskeler, gövde özetini log_body_max_bytes değerine kısaltır, log_redact_path_tokens açıksa jeton benzeri yol parçalarını *** ile değiştirir ve bir ActivityLog satırını, hata verisi varsa bir ErrorLog satırını onaylar (src/cluster_erp/server/middleware.py:530-663). Günlüğün yazılamaması hata ayıklama düzeyinde günlüğe yazılır ve yanıtı etkilemez (src/cluster_erp/server/middleware.py:662-663).

İstek bağlamı¶

İşlemi yapanı, ilişki kimliğini ve kullanımdan kaldırma nedenini bir ara katman değil, rotanın veritabanı bağımlılığı yayınlar (src/cluster_erp/server/dependencies.py:34-72). Bkz. veritabanı ve oturumlar.

Statik bağlamalar¶

Web uygulaması /api yollarını asla gölgelemesin diye en son bağlanır (src/cluster_erp/server/app.py:1573-1575):

• /app/v, webapp/ dosyalarını bir sürüm damgası altında sunar; damga güncelse bir yıl değişmez olarak (src/cluster_erp/server/app.py:1599-1614, src/cluster_erp/server/app.py:1635-1639).
• /app aynı dosyaları Cache-Control: no-cache ile sunar ve index.html dosyasını damgası doldurulmuş ve bir ETag ile sunar (src/cluster_erp/server/app.py:1591-1597, src/cluster_erp/server/app.py:1616-1625, src/cluster_erp/server/app.py:1640-1644).

Bkz. önbellek ve varlık damgası.

Neden böyle kurulmuştur¶

• Güvenlik başlıklarındaki yorum, içerik güvenlik politikasının depolanmış siteler arası betik çalıştırmaya karşı derinlemesine savunma desteği olduğunu ve marka yazı tipinin üçüncü taraf bir sunucu görünmesin diye yerelde barındırıldığını belirtir (src/cluster_erp/server/app.py:1325-1334).
• Gövde sınırı yorumu, denetimin belleği sınırlamak için gövde okunmadan önce Content-Length üzerinde çalıştığını belirtir (src/cluster_erp/server/app.py:1392-1395).
• _console_cors üzerindeki yorum, operatör konsolunun operatörün tarayıcısında çalıştığını ve her ülke düğümünü doğrudan okuduğunu, bu yüzden kökenler arası erişimin yalnızca küçültülmüş filo ucu için verildiğini belirtir (src/cluster_erp/server/app.py:1354-1361).
• Projenin yazılı mühendislik kuralları "app-level + middleware" mimarisinin bozulmasını yasaklar.

Kurallar ve sınırlar¶

• Her yanıt güvenlik başlıklarını setdefault ile alır; böylece bir rota önce kendi değerini koyabilir (src/cluster_erp/server/app.py:1413-1429).
• /health ve /ready, etkinlik günlüğünün varsayılan atlama listesindedir (src/cluster_erp/config/settings.py:630-637).

Diğer parçalarla etkileşim¶

• Hatalar ve istisnalar, etkinlik günlüğünün sakladığı hata gövdelerini ve izleme kimliklerini kurar.
• Veritabanı ve oturumlar onay kancasını kaydeder.
• Logs, activity_log ve error_log tablolarına ve ekranlarına sahiptir.
• Ayarlar başvurusu günlük ve gövde sınırı ayarlarını listeler.

Sınırlar ve açık noktalar¶

• Etkinlik günlüğü yanıt döndürüldükten sonra ayrı bir görevde yazılır (src/cluster_erp/server/middleware.py:491-494). O anda duran bir süreç satırı kaybedebilir.

Tanıtılan terimler¶

İlgili sayfalar¶

• Platform çekirdeği
• Sunucu açılışı ve uygulama fabrikası
• Veritabanı ve oturumlar
• Hatalar ve istisnalar
• Önbellek ve varlık damgası

92f8051 numaralı commit ile 2026-11-13 tarihinde doğrulandı.