[Enh]: Default to Cosmos Gateway mode

[JerryNixon]

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

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