Refactor Azure Core from Driver Spec#3838

Closed

tvaron3 wants to merge 9 commits intoAzure:release/azure_data_cosmos-previewsfrom

tvaron3:tvaron3/coreDependency

Member

tvaron3 commented Mar 2, 2026 •

edited

Loading

Documents the 149 azure_core references across 4 categories (HTTP pipeline, errors, credentials, utilities) and proposes a 4-phase migration plan using direct ecosystem crates (http, hmac, sha2, time, bytes) plus driver-owned abstractions.

Relates to #3845


          Add spec for removing azure_core from driver

Documents the 149 azure_core references across 4 categories
(HTTP pipeline, errors, credentials, utilities) and proposes
a 4-phase migration plan using direct ecosystem crates (http,
hmac, sha2, time, bytes) plus driver-owned abstractions.

Relates to Azure/azure-sdk-for-python#45463

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions bot added the Cosmos label

github-project-automation bot added this to CosmosDB Go/Rust Crew

github-project-automation bot moved this to Todo in CosmosDB Go/Rust Crew

tvaron3 changed the title ~~Removing Azure Core from Driver Spec~~ [DO Not Review] Removing Azure Core from Driver Spec


          Merge branch 'release/azure_data_cosmos-previews' of https://github.c…

23eb615

…om/Azure/azure-sdk-for-rust into tvaron3/coreDependency

tvaron3 changed the title ~~[DO Not Review] Removing Azure Core from Driver Spec~~ Removing Azure Core from Driver Spec


          Revise spec: extract shared crates from azure_core

bfec10c

Shifts approach from driver duplicating types to extracting
azure_core_credentials and azure_core_hmac crates that both
azure_core and the driver can share. The driver then depends
on typespec_client_core directly for HTTP pipeline types.

No breaking changes to azure_core consumers since it
re-exports the new crates.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

tvaron3 changed the title ~~Removing Azure Core from Driver Spec~~ Refactor Azure Core from Driver Spec

tvaron3 and others added 3 commits

March 3, 2026 12:03


          Revise spec: single azure_core_shared crate

2b61b45

Replaces the 3-crate approach (typespec_client_core +
azure_core_credentials + azure_core_hmac) with a single
azure_core_shared crate that re-exports only the HTTP
primitives the driver needs plus credentials and HMAC.

Key change: instead of exposing all of typespec_client_core
(including unused retry policies, pipeline builder, streaming,
etc.), the new crate provides a controlled API surface with
only the types the driver actually uses.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>


          Rename spec to refactor-azure-core-dependency-spec

3ec3033

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>


          Update spec to reference Azure SDK for Rust issue Azure#3845

c3aba31

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

tvaron3 commented

View reviewed changes

sdk/cosmos/azure_data_cosmos_driver/doc/refactor-azure-core-dependency-spec.md Outdated Show resolved Hide resolved

tvaron3 marked this pull request as ready for review

March 3, 2026 20:20

tvaron3 requested a review from a team as a code owner

March 3, 2026 20:20

Copilot AI review requested due to automatic review settings

March 3, 2026 20:20

tvaron3 linked an issue

that may be closed by this pull request

Decouple azure_data_cosmos_driver from azure_core dependency #3845

Closed

Copilot started reviewing on behalf of tvaron3

March 3, 2026 20:21

Copilot AI reviewed

View reviewed changes

Contributor

Copilot AI left a comment

Pull request overview

Adds a design/spec document for decoupling azure_data_cosmos_driver from azure_core to reduce version coupling and better support the driver’s independent versioning and cross-language consumption.

Changes:

Introduces a spec describing current azure_core usage in the driver (HTTP, errors, credentials, utilities).
Proposes a new azure_core_shared crate as a lean dependency surface for the driver (plus a re-export strategy for azure_core).
Lays out a phased migration plan for introducing the crate and switching the driver.

sdk/cosmos/azure_data_cosmos_driver/doc/refactor-azure-core-dependency-spec.md Outdated Show resolved Hide resolved

sdk/cosmos/azure_data_cosmos_driver/doc/refactor-azure-core-dependency-spec.md Outdated Show resolved Hide resolved

sdk/cosmos/azure_data_cosmos_driver/doc/refactor-azure-core-dependency-spec.md Outdated Show resolved Hide resolved

sdk/cosmos/azure_data_cosmos_driver/doc/refactor-azure-core-dependency-spec.md Outdated Show resolved Hide resolved

sdk/cosmos/azure_data_cosmos_driver/doc/refactor-azure-core-dependency-spec.md Show resolved Hide resolved

tvaron3 and others added 3 commits

March 3, 2026 12:27


          Address review feedback in spec

e7b3f88

- Re-export ClientMethodOptions (TokenRequestOptions public field)
- Add Type Compatibility Guarantee section explaining
  re-export identity across crate boundaries
- Document feature flag passthrough as known tradeoff
- Clarify azure_identity compatibility path
- Note base64 is internal-only in azure_core_shared
- Add workspace Cargo.toml step to Phase 1
- Fix cspell: versionable → versioned

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>


          Address PR Azure#3838 review comments in spec

b8e54a3

- Include sleep/async_runtime in azure_core_shared (driver is runtime-agnostic)
- Correct inaccurate 'uses tokio directly' claims
- Reshape TokenRequestOptions to use Context instead of ClientMethodOptions
- Document ClientOptions leak (RetryOptions/LoggingOptions present but ignored)
- Use portable perl command instead of macOS-specific sed
- Update risk assessment for reshaped TokenRequestOptions

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>


          Apply suggestion from @Copilot

e281e54

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

FabianMeiswinkel reviewed

View reviewed changes

sdk/cosmos/azure_data_cosmos_driver/doc/refactor-azure-core-dependency-spec.md


		## Problem Statement

		The `azure_data_cosmos_driver` crate depends on `azure_core` for HTTP infrastructure, credentials, error types, and utilities. Per the multi-crate versioning strategy (AGENTS.md), the driver should be independently versioned from the SDK layer. The `azure_core` dependency creates version coupling — breaking changes in `azure_core` force driver major version bumps even when the driver's own API is stable.

Member

FabianMeiswinkel Mar 4, 2026

At least from my perspective major version changes in azure_core requiring major updates in azure_data_cosmos_driver is not a big problem - it would happen rarely anyway.

And any SDK layering on to of azure_data_cosmos_native will likely use binaries anyway?

FabianMeiswinkel reviewed

View reviewed changes

sdk/cosmos/azure_data_cosmos_driver/doc/refactor-azure-core-dependency-spec.md


		Since the driver is consumed by `azure_data_cosmos_native` (C FFI for Java/.NET/Python SDKs), minimizing heavy Azure-specific dependencies reduces binary size and cross-language complexity.

		The previous revision of this spec proposed having the driver depend on `typespec_client_core` directly, but `typespec_client_core` includes significant functionality the driver never uses (retry policies, pipeline builder, logging policies, streaming, sleep abstractions, tracing module, etc.). The driver only needs the HTTP primitive types and a handful of Azure-specific types (credentials + HMAC).

Member

FabianMeiswinkel Mar 4, 2026

+1 on this - this is the main concern from my perspective

FabianMeiswinkel reviewed

View reviewed changes

sdk/cosmos/azure_data_cosmos_driver/doc/refactor-azure-core-dependency-spec.md

+                │                           # FixedRetryPolicy, RetryOptions, Pipeline struct,
+                │                           # TransportPolicy, logging policy, PipelineOptions,
+                │                           # LoggingOptions, ClientMethodOptions,
+                │                           # sleep, async_runtime, stream/BytesStream,

Member

FabianMeiswinkel Mar 4, 2026

I think async_runtime will actually be used (ifnot yet very soon)

FabianMeiswinkel approved these changes

View reviewed changes

Member

FabianMeiswinkel left a comment

LGTM

Member

analogrelay commented Mar 4, 2026 •

edited

Loading

This looks good to me, and is a good trigger for having a discussion about whether we actually need this abstraction. If this is just a "proxy" package that mostly just re-exports things from other layers, I'm not sure we actually need it. The driver will be a self-contained dynamic library that only includes the code it actually used from azure_core (and descendants) and not any of the extra code. The Rust SDK already references azure_core and should use azure_core. The azure_core_shared crate boundary isn't actually giving us any new isolation there.

The spec is good, but it's definitely making me wonder if we need a hard boundary of a crate here or if we can just be disciplined about what we use from azure_core in the driver. I think we could get away with only using the TokenCredential trait, theError type, the async_runtime abstraction, and perhaps some integration of the HTTP pipeline, but as we've noted a few times we don't really want to use that pipeline.

Let's chat about it at the next sync

tvaron3 closed this

github-project-automation bot moved this from Todo to Done in CosmosDB Go/Rust Crew

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Cosmos