Azure / Azure/data-api-builder

[Enh]: Default to Cosmos Gateway mode

オープン
#3,401 コメント 0 件 リアクション 0 件 担当者 1 名 @sajeetharan が担当を希望しています GitHub で見る
cosmos known-issue
主要言語
C#
スター
1.5k
フォーク
370
平均マージ
3日 22時間
マージ済み PR(30日)
9

説明

## What?

Cosmos Gateway mode sends all data requests over HTTPS through a single endpoint, port 443 in Azure and 8081 in the emulator. Direct mode uses the SDK to discover physical partition endpoints, then opens TCP connections to replicas on ports 10250–10255.

DAB hardcodes `ConnectionMode.Direct` with no configuration override. When connecting to the Linux emulator in Docker, the SDK discovers container IPs such as `172.17.0.2:10253` and attempts TCP connections. From the host, those addresses are not reachable, so requests stall during connection retries.

`AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE=127.0.0.1` works around this by forcing the emulator to advertise a reachable address. Using Gateway mode avoids the issue entirely by keeping traffic on a single HTTPS endpoint with no direct TCP connections to replica IPs.

## Why?

An additional consequence of this is that developers must use the old Cosmos emulator which is a 3 GB download compared to the ~1.25 GB vnext emulator, requires exposing 7 ports instead of 1, and mandates a self-signed certificate install, all because DAB can't use Gateway mode.

## Configuration

```json
"data-source.options":
{
"cosmos-mode": "direct" // Enum: direct | gateway
}
```

1. Add to `CosmosDbNoSQLDataSourceOptions`
2. Read in `CosmosClientProvider.InitializeClient()` and set
`options.ConnectionMode = ConnectionMode.Gateway` or `Direct`
3. Default to Direct for backward compatibility

## Reasons

❌ Broken: The Linux Cosmos DB emulator is the standard local dev tool on macOS, Linux, and often Windows via Docker. Direct mode fails without the IP override because the emulator advertises unreachable container addresses.

⚠️ Network constraints: Some environments block outbound TCP ranges required by Direct mode. Gateway works over HTTPS and passes through firewalls and proxies more reliably.

⚖️ Tradeoff: Direct mode provides lower latency and higher throughput by connecting to replicas directly. Gateway mode introduces an extra hop through front ends, increasing latency but improving compatibility and simplicity.

コントリビューションガイド

コントリビューションガイドを開く

評価

この issue はまだ評価されていません。

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。