Azure / Azure/azure-sdk-for-rust

Cosmos: support RID-addressed operations on Gateway 2.0

Open
#4,921 0 comments 1 reaction 0 assignees View on GitHub
Cosmos
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.