Commit 98d01c8
authored
[Cosmos] Use ContainerReference in Cosmos Client SDK, initial driver dependency for caches (#4005)
# Summary
Adds `azure_data_cosmos_driver` as a dependency to the SDK and
introduces the `ContainerReference` pattern for eager container metadata
resolution. This is the first step toward using the driver as the SDK's
internal transport/routing layer.
This PR is *not* the full cutover into the driver under the hood - its
main purpose is to start that process with the bare minimum (current
caches) without fully replacing the transport pipeline. That will be
done in an entirely separate issue/PR. The cutover from the SDK's fault
injection into the Driver's fault injection for end-to-end testing
against the driver will also be in a separate issue/PR. This work is
meant to unblock other work as well, like
#3987.
## Design
`ContainerClient` construction now eagerly resolves immutable container
metadata (RID, partition key definition) via the driver's
`resolve_container()`, rather than doing per-operation cache lookups in
`send()`. This mirrors how the driver's own `ContainerReference` works.
```
CosmosClient::build()
|
v
CosmosDriverRuntime → CosmosDriver (per-account singleton)
|
v
DatabaseClient::container_client("name").await?
|
v
driver.resolve_container(db, name) → ContainerReference
|
v
ContainerConnection stores ContainerReference
→ send() uses stored RID + PK def (no per-op cache lookup)
```
### SDK `ContainerReference` (No Model Sharing)
The SDK defines its own `pub(crate) ContainerReference` adapted from the
driver's type via `from_driver_ref()`. This follows the versioning
strategy in `AGENTS.md` — `azure_data_cosmos` cannot expose
`azure_data_cosmos_driver` types directly.
## Changes
### SDK (`azure_data_cosmos`)
| File | Change |
|------|--------|
| `models/container_reference.rs` | New — `ContainerReference` with
`from_driver_ref()`, `from_parts()`, accessors |
| `clients/cosmos_client.rs` | Added `driver: Arc<CosmosDriver>` field,
passes to `DatabaseClient` |
| `clients/cosmos_client_builder.rs` | Creates `CosmosDriverRuntime` +
`CosmosDriver` in `build()`, commented out 5 builder unit tests (need
fault injection linked from SDK to driver) |
| `clients/database_client.rs` | Added `driver` field,
`container_client()` now returns `azure_core::Result<ContainerClient>`
(breaking) |
| `clients/container_client.rs` | `new()` calls
`driver.resolve_container()`, builds `ContainerReference`, returns
`Result` |
| `handler/container_connection.rs` | Stores `ContainerReference`,
`send()` uses stored metadata, fixed dual-cache-key bug |
### Dependency alignment
| File | Change |
|------|--------|
| Root `Cargo.toml` | Added `azure_data_cosmos_driver` workspace
dependency |
| SDK `Cargo.toml` | Added driver dep, `azure_core` → workspace,
`reqwest` feature forwards `driver/reqwest_native_tls` |
| Native `Cargo.toml` | `azure_core` → workspace |
| Perf `Cargo.toml` | `azure_core` + `azure_identity` → workspace |
### Call site updates (~59 sites across 19 files)
All `.container_client()` calls updated to `.container_client().await?`
across tests, examples, native crate, and perf crate.
### Bug fix
`send()` previously used the container name (e.g., `"MyContainer"`) as
the `pk_range_cache` key, while the cache parameter is named
`collection_rid` and expects a RID. All lookups now consistently use
`ContainerReference::collection_rid()`.
## Architecture notes
- The driver is only used for `resolve_container()` in this PR. The
SDK's `GatewayPipeline` still handles all data plane operations. Full
transport cutover is planned for a future PR.
- Both the SDK and driver maintain independent HTTP transports —
acceptable overhead for this phase.
- Delete+recreate of a same-name container will cause existing
`ContainerClient` instances to fail — this will be addressed in a follow
up taking care of container re-creation scenarios.1 parent f3c5db5 commit 98d01c8
45 files changed
Lines changed: 491 additions & 1352 deletions
File tree
- sdk/cosmos
- azure_data_cosmos_driver
- src
- driver/transport
- models
- azure_data_cosmos_native
- src/clients
- azure_data_cosmos_perf
- src
- azure_data_cosmos
- examples/cosmos
- src
- clients
- handler
- models
- routing
- tests
- emulator_tests
- framework
- multi_write_tests
Some content is hidden
Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.
0 commit comments