YENİPublication of @aurabase/aurabase-js v0.7.5 NPM Packages & Rust Crate v0.1.2Değişiklik günlüğüne bakın →

Mühendislik · 10 dk. okuma

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

Affane Daylami · Fondateur · 6 Ağustos 2026

Bloga geri dön

Hem kullanıcılarınızın SDK trafiğine hem de arka ofis yönetici trafiğinize hizmet veren bir ağ geçidi, her ikisini de aynı anda yeterince korumaz. Aurabase ağ geçidi (aura-gateway, Rust/axum) bu gerilimi yukarı yönde çözer: iki farklı Yönlendirici, iki bağlantı noktası, iki kimlik doğrulama modeli, tek bir paylaşılan durum. Bu kılavuz, bu veri düzlemi/yönetim düzlemi modelini, bir mimari diyagramın idealize edilmiş bir versiyonu değil, kodda gerçekte var olduğu şekliyle - rotalar, ara yazılım sırası, hız sınırlama, devre kesici ve proxy - açıklar.

Bu sayfa otomatik olarak çevrildi. İngilizce versiyonu yetkilidir.

Temeller

İki bağlantı noktasındaki iki Router ekseni (8080 veri düzlemi, 8090 yönetim düzlemi), aynı paylaşılan AppState öğesinden oluşturulmuştur. Veri düzlemi herhangi bir rotada bir API anahtarı gerektirir; Düzlem yönetimi özel bir JWT izleyici konsolu gerektirir; iki mekanizma asla örtüşmez. Hız sınırlaması iki kez uygulanır: kimlik doğrulamadan önce IP'ye göre, ardından kimlik doğrulaması yapılan aktöre göre. Devre kesici genel bir ara yazılım değildir: hizmet başına (ve PostgREST için ayrılmış hedef başına) doğrudan proxy kodunda çağrılan bir nesnedir. Ve son proxy, rotaya bağlı olarak aktarımı değiştirir - bazen HTTP yöntemine veya veritabanı aramasına göre: trafiğin çoğu için NATS istek/yanıt, depolama için doğrudan HTTP akışı, üç gerçek zamanlı değişken ve özel Postgres CRUD.

#
Sorun

Tek bir ağ geçidi, iki farklı hedef kitle

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ş.

#
1. Adım

İki axum Yönlendirici, bir paylaşılan AppState

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

gateway/server.rsrust
// İ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.

#
2. Adım

Kimlik doğrulama girişte farklılaşıyor

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 bir JWT isteğe bağlı olarak kalır: o olmadan arayan anon olarak kalır; onunla birlikte authenticated olur.

Yönetim düzleminde API anahtarı mevcut değildir: yalnızca hedef kitlesi tam olarak aurabase-control olması 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.

Jeton gerekliAPI anahtarı (apikey / X-API-Key), her zamanJWT konsolu (Yetkilendirme: Taşıyıcı), her zaman
Rol yükseltmesiİsteğe bağlı JWT: anon → kimliği doğrulanmışKuruluştan devralınan RBAC (sahip/yönetici/geliştirici/görüntüleyici)
Sorgu dizesini girinYalnızca WS/SSE'de tolere edilir; service_role için asla kabul edilmezGeçerli değil
Beklenen kitleHedeflenen proje (yolun UUID'si)"aurabase kontrolü" düzeltildi
CORSJoker karaktere * izin verildiJoker karakter reddedildi, yalnızca Studio kökenleri
#
3. Adım

Ara Yazılımın Gerçek Düzeni (Ve Neden Önemlidir)

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.

gateway/router.rsrust
// 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.
Bu emrin somut bir etkisi

request_id ara yazılımı, X-Request-Id üstbilgisini yalnızca RESPONSE'da ayarlar, hiçbir zaman gelen istekte ayarlamaz. AccessLogLayer dosyada kendisinden sonra yerleştirildiğinden (bu nedenle daha harici olduğundan daha önce geçildiği için) request_id alanının yakalanması, zincirin ilerisinde oluşturulan tanımlayıcıyı değil, istemcinin gönderdiği şekilde başlığı okur. Arayan herhangi bir X-Request-Id sağlamadıysa, erişim günlüğü satırı boş bir alanla ayrılır, geri dönen yanıt ise yeni oluşturulmuş bir UUID taşır. Gizli bir kusur değil — bir .layer() dizesinin yazılma sırasının, ona atfettiğimiz mantıksal sıra hakkında hiçbir şeyi garanti etmediğini hatırlatmak isteriz.

#
4. Adım

Hız sınırlaması: Önce IP, sonra aktör

Hız sınırlaması, zincirde iki farklı zamanda, iki ayrı geçişte uygulanır. Bunlardan ilki, kimlik doğrulamadan ÖNCE çalışır ve IP adresine göre sınırlar - kamuya açık yollarda bile aktif olan genel bir taşma önleyici filtre: 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ış.

#
Adım 5

Devre kesici bir katman değildir, hedef başına bir nesnedir

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, veritabanı, 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 durumu farklıdır: adanmış topolojideki projeler (projeye özgü Postgres ve PostgREST) paylaşılan bir hata etki 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.

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

// …NATS sorgu deneme(ler)i, 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 (NoResponders) tarafında teslim edilmediğine dair kesin bir kanıt olması durumunda tetiklenir: basit bir ağ geçidi zaman aşımı, isteğin gerçek teslimiyle ilgili hiçbir şeyi kanıtlamaz ve yeniden oynatmak, onu iki kez çalıştırabilir.

#
Adım 6

Son bağlantı: NATS veya doğrudan HTTP, asla rastgele değil

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 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 yolları (şema, politikalar, ham SQL) her zaman NATS ile aura-db'ye gider, bir PUT her zaman NATS içine gider (PostgREST tam değiştirmede 405 değerini döndürür), bir MongoDB projesi her zaman NATS içine gider - ve yalnızca bir CRUD adanmış bir PostgREST örneğinin çözüldüğü bir Postgres projesi Doğrudan HTTP'ye gider. Bu tahsis edilmiş örnek çözülmezse, ağ geçidi paylaşılan bir PostgREST'ye geri dönmek yerine 503 yanıtı verir: arıza kapalı varsayılır, bozulmuş 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 aynı şekilde uygulanır.

#
Adım 7

Genel bir zaman aşımı değil, rota başına bir zaman aşımı bütçesi

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, buna karşılık /v1/functions/* için 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.

#
Hatırlamak

Bu modeli başka bir yerde yeniden üretin: kontrol listesi

  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 tekrar 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.

DAĞITILMAYA HAZIR MISINIZ?

Beş dakika içinde arka ucunuz.

Kredi kartı gerekmez · 500 MB ücretsiz · 50.000 MAU