Rust'de çift düzlemli bir API ağ geçidi tasarlama

Veri düzlemi trafiği, SDK'dan veya bir istemci uygulamasından gelir: herhangi bir genel API'ye yakın bir kötüye kullanım profiline sahip, API anahtarıyla kimliği doğrulanan bir dizi anonim istek veya istek. Trafik yönetimi düzlemi, bir projenin yönetim arayüzü olan Studio'dan gelir ve hassas işlemleri gerçekleştirir: proje oluşturma, anahtar rotasyonu, kiracının günlüklerinin okunması. İkisi ortak bir hedefi paylaşıyor (aynı dahili hizmetlere vekil olarak geliyor: aura-auth, aura-db, aura-storage, vb.) ancak aynı risk yüzeyini paylaşmıyor.

Her ikisini de aynı yönlendiriciden geçirmek, iki kötü seçenek arasında seçim yapmayı gerektirir: Studio CORS, genel SDK (Access-Control-Allow-Origin: *) için gerekli joker karakteri devralır veya SDK, dahili bir kontrol paneli için tasarlanmış kısıtlı bir kaynak listesini devralır. Aura-gateway kodu, bu gerilimi main.rs'den ayırır: her biri kendi CorsLayer jokerine sahip iki ayrı Router- veri düzlemi tarafında yetkilendirilmiş, reddedilmiş ve yönetim düzlemi tarafında bir hata olarak günlüğe kaydedilmiş.

Ayırma ayrı bir dağıtım değildir: iki plan aynı süreçte, aynı AppState üzerinde çalışır (Postgres havuzları, NATS istemcisi, Moka önbellekleri, devre kesiciler). Yalnızca Router yapısı farklılık gösterir; her biri başlangıçta bir kez çağrılan ve iki ayrı TcpListenertarafından sunulan iki özel işlev aracılığıyla.

// İki bağlantı noktası, iki Yönlendirici, bir AppState

let data_addr: SocketAddr = format!("{}:{}", config.host, config.port).parse()?;
let mgmt_addr: SocketAddr = format!("{}:{}", config.host, config.management_port).parse()?;

let data_listener = TcpListener::bind(data_addr).await?;
let mgmt_listener = TcpListener::bind(mgmt_addr).await?;

// Aynı durum, iki farklı rota grafiği
let data_app = build_data_plane_router(state.clone(), data_cors);
let mgmt_app = build_management_plane_router(state);

tokio::join!(
    axum::serve(data_listener, data_app),
    axum::serve(mgmt_listener, mgmt_app),
);

İki rota grafiği aynı tabandan başlar, service_routes(): aynı proxy işleyicileri (db_proxy, storage_proxy, functions_proxy…), her birine özel ek rotalarla birlikte her iki plana da monte edilir. Aynı işleyicilerin yeniden kullanılması, proxy'nin iki kez uygulanmasını önler; Yalnızca ara katman yazılımında farklılık, bir güvenlik sınırı elde etmek için iş mantığının kopyalanmasını önler. Arka ucunuzun kendisi çok hizmetli bir Kargo çalışma alanı olarak yapılandırılmışsa, Kargo çalışma alanı mimarisi kılavuzumuza bakın — ağ geçidi, bu bölümdeki diğer kasalardan yalnızca biridir.

Veri düzleminde, bir avuç gerçek genel yol (/health, JWKS, kayıt uç noktaları) dışında tüm rotalarda API anahtarı zorunludur. apikey veya X-API-Key başlığı olarak veya yalnızca WebSocket ve SSE akış rotaları için ?apikey=parametresi olarak hareket eder. Kod, bir service_role anahtarı için bu son modu açıkça yasaklar: erişim günlüklerinde, OTEL izlerinde ve Yönlendiren başlığında bir URL anahtarı sızdırılır. Veri düzlemi tarafında JWT isteğe bağlı olarak kalır: JWT olmadan arayan kişi anonolarak kalır; onunla birlikte authenticatedolur.

Yönetim düzleminde API anahtarı mevcut değildir: yalnızca hedef kitlesinin tam olarak aurabase-contrololması gereken bir JWT konsolu kabul edilir. Rol, belirtecin kendisi tarafından taşınmaz; kullanıcının proje → kuruluş ilişkisi aracılığıyla devralınan, projenin sahibi kuruluştaki üyeliğinden gelen her istek üzerine yeniden hesaplanır.

axum ara yazılımı ardışık .layer() çağrılarıyla yığınlar - ve yürütme sırasını yöneten kural pratikte şaşırtıcıdır: yerleştirilen LAST .layer() OUTTERmost katmanı olur, dolayısıyla gelen bir istek tarafından ilk geçilen ve yanıt iznini en son gören katman olur. Dolayısıyla dosyanın doğrusal okunması, gerçek yürütme sırasının ters sırasını verir.

// Aşağıdaki gibi yazılmıştır (gerçek alıntı, dosya sırası):

service_routes(...).merge(data_plane_extra)
    .layer(metrics_auth_middleware)      // (1) 1. sırada → en içteki
    .layer(rate_limit_actor_middleware)  // (2)
    .layer(data_plane_auth_middleware)   // (3)
    .layer(rate_limit_middleware)        // (4)
    .layer(request_id_middleware)        // (5)
    .layer(AccessLogLayer)               // (6)
    .layer(prometheus_layer)             // (7)
    .layer(TraceLayer)                   // (8)
    .layer(RequestBodyLimitLayer)        // (9)
    .layer(security_headers_middleware)  // (10)
    .layer(cors)                         // (11) sonuncu yerleştirilmiş → en dışta

// Bu nedenle gelen bir istek (11) → (1) üzerinden geçer, asla (1) → (11) üzerinden geçer.

Hız sınırlaması, zincirde iki farklı zamanda, iki ayrı geçişte uygulanır. İlki, kimlik doğrulamadan ÖNCE çalışır ve IP adresine göre sınırlar - genel yollarda bile aktif olan genel bir taşkın önleme filtresi: bu olmadan, kimliği doğrulanmamış bir akış, bir JWT kontrolünü tetiklemeden günlük toplama gibi pahalı bir uç noktaya zarar verebilir. İkincisi, kimlik doğrulamanın SONRA çalıştırılır ve kimlik doğrulamanın az önce eklediği iddiaları kullanarak aktöre (API anahtarı veya kullanıcı) göre sınırlandırır: bu, faturalandırma ve planlar için dikkate alınan gerçek ürün kotasıdır.

Uygulama, yerel hesaplama için governor sandığına (jeton kovası), ağ geçidi örnekleri arasında dağıtım için kayan pencere Lua Redis komut dosyasına ve Redis kullanılamıyorsa yerel bir geri dönüşe (Moka önbelleği) dayanır. Depo varsayılanları: 100 istek/saniye, 1000'lik artış.

Zincirin geri kalanından farklı olarak devre kesici HİÇBİR .layer()öğesinde görünmez. AppState hizmet başına bir CircuitBreaker örneği taşır (kimlik doğrulama, veri tabanı, gerçek zamanlı, depolama, işlevler, bildirimler, yapay zeka, hazırlayıcı, kontrol) ve isteği gerçekleştirmeden önce try_acquire_probe()'yi çağıran, ardından sonuca bağlı olarak record_success() veya record_failure()'yi çağıran, yönlendirici değil, proxy kodunun kendisidir.

PostgREST'in durumu farklıdır: adanmış topolojideki projeler (projeye özel Postgres ve PostgREST) paylaşılan bir hata alanına sahip değildir; her PostgREST işlemi kendi hedefidir. Bu nedenle ağ geçidi, çözümlenmiş hedefe göre indekslenen, anında doldurulan ve etkin olmayan girişleri ortadan kaldıran bir taramayla her 60 saniyede bir temizlenen bir devre kesiciler tablosu tutar: bu temizleme olmadan, her yeni özel proje asla kaybolmayan bir giriş ekleyecektir.

let Some(probe) = circuit_breaker.try_acquire_probe() else {
    return Err(ServiceUnavailable);
};

// …NATS sorgu denemeleri, sınırlı yeniden denemeyle…

match resultat {
    Ok(Ok(_))     => match probe.take() { Some(p) => p.record_success(), _ => {} },
    Ok(Err(_))    => match probe.take() { Some(p) => p.record_failure(), _ => {} },
    Err(_timeout) => {} // prob tüketilmedi → Drop tarafından iade edildi
}

Araştırma belirteci, hiçbir zaman açıkça tüketilmediği takdirde Drop olarak döndürülür; bu, bir istekteki tüm girişimler, onu serbest bırakacak bir şubeye ulaşmadan zaman aşımına uğradığında kullanışlıdır. Ve otomatik tekrar yürütme yalnızca NATS tarafında teslim edilmediğine dair katı bir kanıt olması durumunda tetiklenir (NoResponders): basit bir ağ geçidi zaman aşımı, isteğin gerçek teslimiyle ilgili hiçbir şeyi kanıtlamaz ve tekrar oynatmak, onu iki kez çalıştırabilir.

Nihai proxy tek bir protokolü geriye doğru konuşmaz ve seçim rotaya göre sabitlenmez: HTTP yöntemine, hatta bir veritabanı aramasına bağlı olabilir. Trafiğin çoğu için (kimlik doğrulama, işlevler, bildirimler, kontrol ve veri tabanının çoğunluğu), ağ geçidi, HTTP isteğini bir NATS zarfı içinde serileştirir ve bunu hizmete ayrılmış bir konuya istek/yanıt olarak gönderir; bu, bu RPC türü trafik için klasik bir HTTP proxy'sinden önemli ölçüde daha hızlı olduğu kodda belgelenen, TCP anlaşması olmayan bir gidiş-dönüş yolculuğudur.

Depolama, gerçek zamanın üç çeşidi (yayın/kanallar/varlık için WebSocket, SSE ve REST) ve - koşullu olarak - Postgres CRUD istekleri bu yoldan çıkar ve canlı, havuza alınmış bir HTTP istemcisinden geçer. Depolama bu seçimi açıkça yaptı: Bir ikili gövdeyi bir NATS zarfı içinde kodlamak, onu serileştirmeyi, her iki uçta tamamen belleğe yüklemeyi ve NATS mesaj boyutu sınırının altında kalmayı gerektirir; bu, büyük nesneler için gerçek bir maliyettir. WebSocket ve SSE, istek/yanıt anlambilimine tolerans göstermez: bir protokol yükseltmesinin ve açık kalan bir akışın NATS eşdeğeri yoktur.

En ilginç durum, işleyicisi her istek üzerine kendisi karar veren /v1/db/*'dir: yönetim rotaları (şema, politikalar, ham SQL) her zaman NATS'de aura-db'ye gider, bir PUT her zaman NATS'ye gider (PostgREST tam değiştirmede 405 döndürür), bir MongoDB projesi her zaman NATS'ye gider - ve yalnızca özel bir PostgREST örneği çözümlenmiş bir Postgres projesindeki CRUD Direct HTTP'ye gider. Bu özel örnek çözümlenmezse ağ geçidi, paylaşılan bir PostgREST'e geri dönmek yerine 503 yanıtı verir: başarısız bir şekilde kapatıldığı varsayılır, azaltılmış bir sessiz geri dönüş değil. güvenlik üstbilgileri (katı CSP, CORS kimlik bilgileri yok), yanıt ağ geçidinden ayrılmadan önce zincirin en sonuna yerleştirilen tüm bu yollara eşit şekilde uygulanır.

Ağ geçidi, genel zaman aşımı yerine GRUBU BAŞINA TimeoutLayer rota uygular; bu, ara yazılım sırası ile aynı yığınlama mekaniğine bağlı bir seçimdir. Edge işlevleri rotası diğerlerinden çok daha uzun bir bütçeye ihtiyaç duyar (bir işlev yasal olarak birkaç dakika boyunca çalışabilir): depo varsayılanı rotaların çoğu için 30 saniyedir, /v1/functions/*için ise 380 saniyedir.

Her şeyin üstüne tek bir global TimeoutLayer istiflemek, her iki grubu da aynı sınırda keserdi: daha içeriye yerleştirilen daha uzun bir zaman aşımına bakılmaksızın, her zaman en dış konuma yerleştirilen en kısa zaman aşımı kazanır. Bu nedenle, işlevlere ayrı bir bütçe vermenin tek yolu, bunların ASLA ortak bir pakete girmemesidir: yolların her bir dalı, iki yönlendiricinin birleşmesinden önce yerleştirilen kendi TimeoutLayeröğesini taşır ve sonrasında herhangi bir genel zaman aşımı uygulanmaz.

1. Hizmete göre değil, PLAN'a (teşhir yüzeyi) göre ayırın: Güvenliği ihlal edilmiş bir genel SDK, asla yönetici kontrol panelinizin CORS kaynak listesine ulaşmamalıdır.
2. İki ayrı dağıtım yerine tek bir paylaşılan durumu koruyun; iş mantığını çoğaltmak, bir yönlendiriciyi çoğaltmaktan daha maliyetlidir.
3. GERÇEK ara yazılım sırasını, asla dosyanın doğrusal okumasından değil, son .layer()'den izleyerek kontrol edin.
4. IP başına hız sınırlamasını (kimlik doğrulamadan önce) aktör başına kotadan (sonra) ayırın; aksi takdirde, kimliği doğrulanmamış bir akış, sınırsız maliyetli doğrulamaya neden olur.
5. Kesiciyi proxy'de gerçek ağ çağrısına mümkün olduğunca yakın yerleştirin ve hata etki alanı paylaşılmadığında hedefe göre boyutlandırın.
6. Bir isteği yalnızca teslim edilmediğinin kanıtlanması durumunda yeniden oynatın; asla basit bir zaman aşımında oynatmayın.
7. Yönlendiricileri birleştirmeden önce her rota grubuna kendi zaman aşımı bütçesini verin; asla en uzun bütçenin üzerine yazacak global bir TimeoutLayer vermeyin.