Azure / Azure/data-api-builder

[Enh]: Default to Cosmos Gateway mode

Open
#3,401 0 comments 0 reactions 1 assignee Claimed by @sajeetharan View on GitHub
cosmos known-issue
Dominant language
C#
Stars
1.5k
Forks
370
Avg merge
3d 17h
Merged PRs (30d)
8

Description

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

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.