Cosmos: Switch SDK over to using the driver

[analogrelay]

We have a basic driver skeleton in place now, so we should work on moving the SDK over to using the driver. This includes:

1. Exposing relevant options/builder APIs to construct and manage driver instances in the Rust SDK
2. Implementing existing Rust SDK APIs by constructing driver CosmosOperations and executing them, then wrapping CosmosResponse in something that allows deserialization of the body and exposes the diagnostics and other response headers.

Out of scope here:

1. Maintaining the existing SDK transport. We're not going to bother with a feature flag right now, it's extra work for little benefit.
2. C bindings to the Driver

[github-actions]

🎯 Agentic Issue Triage

This is a feature/refactoring work item to migrate the Cosmos Rust SDK from its current direct transport layer to the new azure_data_cosmos_driver abstraction. The driver skeleton is now in place, and this issue tracks the integration work.

📋 Issue Summary

Type: Internal refactoring / feature enablement
Component: azure_data_cosmos + azure_data_cosmos_driver
Author: Repo member (@analogrelay)

In scope:

1. Expose options/builder APIs to construct and manage driver instances from the Rust SDK (CosmosClientBuilder, CosmosClientOptions)
2. Reimplement existing SDK public APIs by constructing CosmosOperations, executing them via the driver, and wrapping CosmosResponse for deserialization + diagnostics exposure

Out of scope:

• Keeping the old transport around behind a feature flag
• C bindings to the driver (tracked in Cosmos: C wrapper around Driver #3907)

🔗 Related Issues

• Cosmos: C wrapper around Driver #3907 — Cosmos: C wrapper around Driver (explicitly out of scope for this issue)
• Cosmos: Implement high-availability functionality in the driver #3741 — Cosmos: Implement high-availability functionality in the driver (upstream dependency on driver readiness)
• [Cosmos] Allow access to additional response headers #3905 — Cosmos: Allow access to additional response headers (the CosmosResponse wrapping work here will need to consider this)
• Cosmos: Integrate Query Engine into Rust Driver #3507 — Cosmos: Integrate Query Engine into Rust Driver (broader driver integration context)

✅ Suggested Sub-Tasks / Checklist

• Audit CosmosClientBuilder and CosmosClientOptions to determine what driver-specific options need to be surfaced (e.g. endpoint routing, retry policies, HA config)
• Design the bridge between CosmosClientOptions and the driver's configuration (possibly a new internal helper or From impl)
• For each existing SDK operation (CRUD on databases, containers, items, queries), replace the current transport call with a CosmosOperation construction + driver execution
• Design a wrapper around CosmosResponse that:
  • Supports deserialization of the body (e.g. via serde_json / azure_core deserialization helpers)
  • Exposes diagnostics (CosmosDiagnostics)
  • Exposes standard response headers (session token, request charge, etag, activity ID, etc.)
• Remove the old direct transport code (headers_policy.rs, pipeline.rs or equivalent dead code after the switch)
• Ensure all existing integration tests pass against the driver
• Run cargo clippy and cargo fmt on all touched crates

🛠️ Implementation Notes

Current driver architecture:
The driver uses a two-level pipeline: an operation pipeline (retry evaluation + operation execution) and a transport pipeline (handles 429 throttle retries). The Rust SDK will need to call into this via CosmosOperation structs. See sdk/cosmos/azure_data_cosmos_driver/src/driver/pipeline/ for the entry points.

Response wrapping:
Consider a new type (e.g. CosmosItemResponse(T)) that owns the raw CosmosResponse, implements Deserialize lazily, and delegates header accessors. This aligns with the work tracked in #3905 for expanding exposed headers.

No feature flag:
The issue explicitly calls out that there will be no feature flag to maintain the old transport — this is a clean cutover. Coordinate timing with any in-flight PRs that touch the transport layer.

Driver crate boundary:
Per sdk/cosmos/AGENTS.md, avoid tokio-specific APIs in azure_data_cosmos and azure_data_cosmos_driver; only azure_data_cosmos_native should use tokio directly. Keep async runtime abstractions consistent with azure_core.

📚 Useful Resources

• sdk/cosmos/azure_data_cosmos_driver/docs/TRANSPORT_PIPELINE_SPEC.md — detailed spec for the driver pipeline
• sdk/cosmos/azure_data_cosmos_driver/src/driver/pipeline/operation_pipeline.rs — operation pipeline entry point
• sdk/cosmos/azure_data_cosmos/src/clients/cosmos_client_builder.rs — current builder to extend
• [Azure SDK Design Guidelines for Rust]((azure.github.io/redacted)

Generated by Agentic Triage for issue #3906 · ◷

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/issue-triage.md@8e6d7c86bba37371d2d0eee1a23563db3e561eb5