Azure / Azure/azure-sdk-for-rust
Cosmos: support RID-addressed operations on Gateway 2.0
- Dominant language
- Rust
- Stars
- 884
- Forks
- 365
- Avg merge
- 2d 14h
- Merged PRs (30d)
- 111
Description
## Summary
RID-addressed operations currently fall back to standard Gateway (v1) instead of routing through Gateway 2.0 (thin client). This is a deliberate, conservative guard added in #4640 to avoid a hard failure; it should be replaced with real support.
## Background
Gateway 2.0 derives its `DatabaseName` / `CollectionName` RNTBD routing tokens by parsing the authorization signing link:
```rust
// driver/transport/gateway_v2_dispatch.rs
let resource_names = parse_resource_names(inputs.auth_context.resource_link.as_str())?;
```
For RID-addressed **feed** operations, `rid_signing_override(true)` intentionally makes the signing link a bare lowercased RID (this is correct — the Cosmos master-key signature for `is_name_based = false` is computed over the RID of the signing resource only, not the full resource link). That bare RID has no `dbs/` or `colls/` segments, so `parse_resource_names` fails and `transport_pipeline.rs` converts the error into a local `CLIENT_BAD_REQUEST` with `RequestSentStatus::NotSent`.
Reproduced through the production code path before the guard was added:
```text
request_path = "/dbs/lx1baa==/colls/lx1balxjyz8=/docs" (correct)
signing_link = "lx1balxjyz8=" (correct for HMAC)
result = ERR: Gateway 2.0 resource link is missing database name
```
Affected operations are the Gateway-2.0-eligible `Document` feed ops: `Query`, `SqlQuery`, `QueryPlan`, `ReadFeed`, `Create`, `Upsert`, and `Batch`. Point reads are unaffected, since their signing link remains a full resource path.
## Current mitigation
`is_operation_supported_by_gateway_v2` takes an `is_rid_addressed` flag and returns `false`, so these operations route through standard Gateway, which handles raw RID paths natively.
## Why this needs follow-up
This is a functional-parity gap, not just a safety valve: users who address containers by RID silently lose thin-client routing and its performance benefits.
## Proposed work
Carry the full (un-encoded) resource path into the Gateway 2.0 metadata parsing separately from the signing link, rather than re-deriving names from the signing link. `ResourcePaths.buf` already holds the full path (`/dbs/{db_rid}/colls/{coll_rid}/docs`) even when `signing_override` replaces the signing link, so the data is available without recomputation.
The open question is protocol-level and needs validation against a real thin-client-enabled account: `DatabaseName` / `CollectionName` are the proxy's routing-by-name tokens, and are deliberately distinct from the existing `CollectionRid` / `ResourceId` tokens. Whether the proxy accepts RIDs in the name tokens — or whether RID-addressed requests should instead populate only `CollectionRid` / `ResourceId` and omit the name tokens — is not covered by `docs/GATEWAY_V2_SPEC.md`. That should be confirmed with the Gateway 2.0 team before implementing.
## Notes
- Emulator tests do not cover this: the emulator has no thin-client endpoint, so RID-addressed emulator tests exercise Gateway v1 only.
- Regression coverage for the current fallback: `rid_addressed_operations_are_ineligible` (`gateway_v2_eligibility.rs`) and `resolve_endpoint_falls_back_to_gateway_for_rid_addressed_operations` (`operation_pipeline.rs`).
- Related epic: #4637
Contributor guide
Research direction
Start by reading driver/transport/gateway_v2_dispatch.rs, transport_pipeline.rs, gateway_v2_eligibility.rs, operation_pipeline.rs, and docs/GATEWAY_V2_SPEC.md. Run the named eligibility and endpoint-fallback tests, then validate the DatabaseName/CollectionName behavior with the Gateway 2.0 team and a thin-client-enabled account. Done means eligible RID-addressed Document feed operations route through Gateway 2.0 with regression coverage.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- backend, networking
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100