新しいPublication of @aurabase/aurabase-js v0.7.5 NPM Packages & Rust Crate v0.1.2変更履歴を参照 →

エンジニアリング · 10 分読み取り

Rust でのデュアルプレーン API ゲートウェイの設計

Affane Daylami · Fondateur · 2026年8月6日

ブログに戻る

ユーザーの SDK トラフィックとバック オフィス管理トラフィックの両方にサービスを提供するゲートウェイは、両方を同時に十分に保護できません。 Aurabase ゲートウェイ (aura-gateway、Rust/axum) は、2 つの異なるルーター、2 つのポート、2 つの認証モデル、1 つの共有状態によって、この緊張をアップストリームで解決します。このガイドでは、アーキテクチャ図の理想化されたバージョンではなく、コード内に実際に存在するこのデータ プレーン/管理プレーン パターン (ルート、ミドルウェアの順序、レート制限、サーキット ブレーカー、プロキシ) について説明します。

このページは自動翻訳されました。英語版が正式です。

必需品

2 つのポート上の 2 つの Router 軸 (8080 データ プレーン、 8090 管理プレーン)。同じ共有 AppStateから構築されます。データ プレーンにはどのルートでも API キーが必要です。プレーン管理には専用の JWT 視聴者コンソールが必要です。2 つのメカニズムが重複することはありません。レート制限は 2 回適用されます。つまり、認証前に IP によって、次に認証されたアクターによって認証されます。サーキット ブレーカーはグローバル ミドルウェアではありません。これはサービスごと (および PostgRESTの専用ターゲットごと) のオブジェクトであり、プロキシ コードで直接呼び出されます。そして、最後のプロキシは、ルートに応じて、場合によっては HTTP メソッドまたはデータベース ルックアップに従ってトランスポートを変更します。ほとんどのトラフィックの NATS 要求/応答、ストレージの直接 HTTP フロー、3 つのリアルタイム バリアント、および専用の Postgres CRUD。

#
問題

単一のゲートウェイ、まったく異なる 2 つの視聴者

データ プレーン トラフィックは、SDK またはクライアント アプリから送信されます。つまり、大量の匿名リクエスト、または API キーによって認証されたリクエストであり、パブリック API に近い悪用プロファイルが含まれます。トラフィック管理プレーンは Studio (プロジェクトの管理インターフェイス) から提供され、プロジェクトの作成、キーのローテーション、テナントのログの読み取りなどの機密性の高い操作を実行します。この 2 つは共通のターゲット (aura-auth、aura-db、aura-storage などの同じ内部サービスにプロキシ) を共有していますが、同じリスク面ではありません。

両方を同じルーターを通過させるには、2 つの不適切なオプションから選択する必要があります。Studio CORS がパブリック SDK (Access-Control-Allow-Origin: *) に必要なワイルドカードを継承するか、SDK が内部ダッシュボード用に設計されたオリジンの制限されたリストを継承するかのいずれかです。 aura-gateway コードは、このテンションを main.rsから整理します。2 つの別個の Routerは、それぞれ独自の CorsLayer を持ちます。ワイルドカードはデータ プレーン側で承認され、拒否され、管理プレーン側でエラーとして記録されます。

#
ステップ1

2 つの axum Router、1 つの共有 AppState

この分離は個別のデプロイメントではありません。2 つのプランは、同じプロセス、同じ AppState (Postgres プール、NATS クライアント、Moka キャッシュ、サーキット ブレーカー) 上で実行されます。 Router の構造のみが異なり、それぞれ起動時に 1 回呼び出され、2 つの別個の TcpListenerによって処理される 2 つの専用関数を介します。

gateway/server.rsrust
// 2 つのポート、2 つのルーター、1 つの 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?;

// 同じ状態、2 つの異なるルート グラフ
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),
);

2 つのルート グラフは同じベース service_routes()から始まります。同じプロキシ ハンドラー (db_proxy、 storage_proxy、 functions_proxy…) が両方のプランにマウントされ、それぞれに固有の追加ルートが付いています。同じハンドラーを再利用すると、プロキシの二重実装が回避されます。ミドルウェアのみを分岐させることで、セキュリティ境界を確保するためにビジネス ロジックが重複することを回避します。バックエンド自体がマルチサービス Cargo ワークスペースとして構造化されている場合は、Cargo ワークスペース アーキテクチャ ガイド を参照してください。ゲートウェイは、この部門の他のクレートの 1 つにすぎません。

#
ステップ2

入場時に認証が分岐する

データ プレーンでは、少数の真のパブリック パス (/health、JWKS、登録エンドポイント) を除き、すべてのルートで API キーが必須です。これは、apikey または X-API-Key ヘッダーとして送信されます。または、WebSocket および SSE ストリーミング ルートの場合のみ、?apikey=パラメーターとして送信されます。コードは、service_role キーに対するこの最後のモード、つまり URL キーがアクセス ログ、OTel トレース、および Referer ヘッダーに漏洩することを明示的に禁止しています。 JWT はデータ プレーン側でオプションのままです。これがないと、呼び出し元は anonのままになります。これを使用すると、 authenticatedになります。

管理プレーンでは、API キーは存在しません。 JWT コンソールのみが受け入れられます。その対象ユーザーは正確に aurabase-controlである必要があります。ロールはトークン自体によって保持されるのではなく、プロジェクトを所有する組織のユーザーのメンバーシップからリクエストごとに再計算され、プロジェクト → 組織の関係を通じて継承されます。

トークンが必要ですAPI キー (apikey / X-API-Key)、常にJWT コンソール (権限: Bearer)、常に
役割の昇格オプション JWT: anon → 認証済み組織から継承された RBAC (所有者/管理者/開発者/閲覧者)
クエリ文字列を入力しますWS/SSE でのみ許容され、service_role では許容されません該当なし
想定される聴衆対象のプロジェクト(パスのUUID)「aurabase-control」を修正しました
コルスワイルドカード * 使用可能ワイルドカードは拒否されました、Studio のオリジンのみ
#
ステップ3

ミドルウェアの実際の順序 (そしてそれが重要な理由)

axum は、連続した .layer() 呼び出しでミドルウェアをスタックします。そして、実行順序を管理するルールは実際には驚くべきものです。最後に配置された .layer() レイヤーが最も外側のレイヤーになるため、受信リクエストが最初に通過するレイヤーとなり、最後に応答が返されるレイヤーになります。したがって、ファイルを線形に読み取ると、実際の実行順序とは逆の順序になります。

gateway/router.rsrust
// 次のように記述されます (実際の抽出、ファイルの順序)。

service_routes(...).merge(data_plane_extra)
    .layer(metrics_auth_middleware)      // (1)1位→最内
    .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) 最後に配置→一番外側

// したがって、受信リクエストは (11) → (1) を通過し、(1) → (11) には通過しません。
この命令の具体的な効果

request_id ミドルウェアは、RESPONSE に X-Request-Id ヘッダーを設定するだけであり、受信リクエストには設定しません。 AccessLogLayer はファイル内でその後に配置されるため、より外部的であり、したがって前に走査されるため、request_id フィールドのキャプチャでは、チェーンのさらに先で生成された識別子ではなく、クライアントが送信したヘッダーが読み取られます。呼び出し元が X-Request-Idを提供しなかった場合、アクセス ログ行には空のフィールドが残りますが、返される応答には新しく生成された UUID が含まれます。隠れた欠陥ではありません。.layer() 文字列が書き込まれる順序は、それに帰する論理的順序について何も保証しないことを思い出させてください。

#
ステップ4

レート制限: 最初に IP、次にアクター

レート制限は、チェーン内の 2 つの異なる時点で、2 つの異なるパスで適用されます。 1 つ目は、認証前に実行され、IP アドレスによって制限されます。一般的なフラッド対策フィルターで、公道でもアクティブです。これがないと、認証されていないフローが、JWT チェックをトリガーすることなく、ログ集約などの高価なエンドポイントを攻撃する可能性があります。 2 つ目は認証後に実行され、認証によって挿入されたクレームを使用してアクター (API キーまたはユーザー) ごとに制限します。これが実際の製品のクォータであり、請求とプランにカウントされるものです。

この実装は、ローカル計算には governor クレート (トークン バケット) を使用し、ゲートウェイ インスタンス間の分散にはスライディング ウィンドウの Lua Redis スクリプトを使用し、Redis が使用できない場合はローカル フォールバック (Moka キャッシュ) に依存します。リポジトリのデフォルト: 100 リクエスト/秒、バースト 1000。

#
ステップ5

サーキット ブレーカーはレイヤーではなく、ターゲットごとのオブジェクトです

チェーンの残りの部分とは異なり、サーキット ブレーカーはどの .layer()にも表示されません。 AppState は、サービス (認証、データベース、リアルタイム、ストレージ、関数、通知、AI、プロビジョナー、コントロール) ごとに 1 つの CircuitBreaker インスタンスを運びます。リクエストを試行する前に try_acquire_probe() を呼び出し、結果に応じて record_success() または record_failure() を呼び出すのは、ルーターではなくプロキシ コード自体です。

PostgREST の場合は異なります。専用トポロジ内のプロジェクト (プロジェクト固有の Postgres および PostgREST) には共有フォールト ドメインがありません。各 PostgREST プロセスは独自のターゲットです。したがって、ゲートウェイは、解決されたターゲットによってインデックス付けされたサーキット ブレーカーのテーブルを維持し、オンザフライで設定され、非アクティブなエントリを削除するスイープによって 60 秒ごとにパージされます。このパージがなければ、新しい専用プロジェクトごとに、決して消えることのないエントリが追加されることになります。

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

// …NATS クエリ試行、制限付き再試行…

match resultat {
    Ok(Ok(_))     => match probe.take() { Some(p) => p.record_success(), _ => {} },
    Ok(Err(_))    => match probe.take() { Some(p) => p.record_failure(), _ => {} },
    Err(_timeout) => {} // プローブが消費されない → Drop によって返される
}

プローブ トークンが明示的に消費されない場合、プローブ トークンは Drop として返されます。これは、解放されるブランチに到達せずにリクエストのすべての試行がタイムアウトになった場合に役立ちます。また、自動再実行は、 NATS 側 (NoResponders) での不達が厳密に証明された場合にのみトリガーされます。単純なゲートウェイ タイムアウトでは、リクエストの実際の配信については何も証明されず、再実行するとリクエストが 2 回実行される可能性があります。

#
ステップ6

最後のリンク: NATS または直接 HTTP、決してランダムではない

最終的なプロキシは、単一のプロトコルを逆方向に話すことはなく、選択はルートによって固定されません。HTTP メソッド、さらにはデータベース検索に依存する可能性があります。ほとんどのトラフィック (認証、機能、通知、制御、および DB の大部分) について、ゲートウェイは HTTP リクエストを NATS エンベロープでシリアル化し、サービス専用のサブジェクトへのリクエスト/応答として送信します。これは、TCP ハンドシェイクなしの往復であり、この RPC タイプのトラフィックでは従来の HTTP プロキシよりも大幅に高速であることがコードに記載されています。

ストレージ、リアルタイムの 3 つのバリアント (WebSocket、SSE、およびブロードキャスト/チャネル/プレゼンスの REST)、および条件付きの Postgres CRUD リクエストは、このパスを出て、ライブのプールされた HTTP クライアントを通過します。ストレージはこの選択を明示的に行いました。バイナリ本体を NATS エンベロープにエンコードするには、シリアル化し、両端のメモリに完全にロードし、NATS メッセージ サイズの上限を超えないようにする必要があります。これは、大きなオブジェクトにとっては実際のコストとなります。 WebSocket と SSE は、単純に要求/応答セマンティクスを許容しません。プロトコルのアップグレードとオープンのままのフローには、NATS に相当するものはありません。

最も興味深いケースは /v1/db/*で、そのハンドラーはリクエストごとに自ら決定します。管理ルート (スキーマ、ポリシー、生 SQL) は常に NATS で aura-db に入り、 PUT は常に NATS (完全な置換の場合PostgREST は 405 を返します)、MongoDB プロジェクトは常に NATS に入ります。専用の PostgREST インスタンスが解決された Postgres プロジェクトは、ダイレクト HTTP に移行します。この専用インスタンスが解決されない場合、ゲートウェイは共有 PostgRESTにフォールバックするのではなく、503 に応答します。機能低下したサイレント フォールバックではなく、フェイルクローズが想定されます。 セキュリティ ヘッダー (厳密な CSP、CORS 資格情報なし) は、応答がゲートウェイから送信される前のチェーンの最後に配置され、これらすべてのパスに均一に適用されます。

#
ステップ7

グローバル タイムアウトではなく、ルートごとのタイムアウト バジェット

ゲートウェイは、グローバル タイムアウトではなく、ルートのグループごとに TimeoutLayer を適用します。これは、ミドルウェアの順序と同じスタッキング メカニズムにリンクされた選択です。エッジ関数のルートには、残りのルートよりもはるかに長いバジェットが必要です (関数は正当に数分間実行できます)。リポジトリのデフォルトは、ほとんどのルートで 30 秒ですが、 /v1/functions/*の場合は 380 秒です。

単一のグローバル TimeoutLayer をすべての上に積み重ねると、両方のグループが同じ制限でカットされます。内側に配置されたより長いタイムアウトに関係なく、最も外側の位置に配置された最も短いタイムアウトが常に勝ちとなります。したがって、関数に別個のバジェットを付与する唯一の方法は、関数が決して共通ラップに入らないことです。ルートの各ブランチは独自の TimeoutLayerを持ち、2 つのルーターが結合される前に配置されます。その後、グローバル タイムアウトは適用されません。

#
思い出すために

このパターンを別の場所 (チェックリスト) で再現します。

  1. サービスごとではなく、PLAN (公開サーフェス) ごとに分離します。侵害されたパブリック SDK が管理ダッシュボードの CORS オリジン リストに到達することはありません。
  2. 2 つの個別の展開ではなく、単一の共有状態を維持します。ビジネス ロジックの複製には、ルーターの複製よりもコストがかかります。
  3. 実際のミドルウェアの順序を確認するには、ファイルの線形読み取りからではなく、最後の .layer()から追跡します。
  4. IP ごとのレート制限 (認証前) とアクターごとのクォータ (後) を分離します。そうしないと、認証されていないフローによりコストのかかる検証が無制限に強制されます。
  5. プロキシ内の実際のネットワーク呼び出しのできるだけ近くにブレーカーを配置し、フォールト ドメインが共有されていない場合はターゲットごとにブレーカーのサイズを決定します。
  6. 単純なタイムアウトではなく、不達が証明された場合にのみリクエストを再実行してください。
  7. ルーターを結合する前に、各ルート グループに独自のタイムアウト バジェット セットを与えます。最長のバジェットを上書きするようなグローバル TimeoutLayer を設定しないでください。

導入の準備はできていますか?

5 分でバックエンドが完成します。

クレジット カードは不要 · 500 MB 無料 · 50,000 MAU