Cosmos: native driver distribution design + ADRs

[ananth7592]

What this is

A design doc + ADRs (documentation only — no code or pipeline changes) proposing how the Rust-built native Cosmos driver (azure_data_cosmos_driver_native → azurecosmosdriver.{dll,so,dylib} plus the cbindgen C header) is distributed to the language SDKs (.NET first, Go near-term, Java later).

The design doc carries the discussion — context, alternatives, and the "why". The ADRs record each decision in short, numbered, immutable form (Context · Decision · Consequences · Alternatives · Status). If the two ever disagree, the ADR wins.

These are proposed for design review — nothing here changes build or release behavior yet.

TL;DR of the design

• Separate provenance from distribution — the core principle the rest follows from.
• Build-once provenance (ADR 0001): one Rust build per release produces and signs all platform binaries (cdylib + staticlib + C header + ABI version) as an internal-only hand-off artifact. It is never consumer-facing and never language-shaped.
• Per-language distribution (ADR 0002): each language consumes the driver as a normal dependency on its own existing feed — no neutral cross-language bundle, no new consumer feed. A Go user never downloads a DLL or JAR.
  • .NET (ADR 0003): per-RID NuGet NativeAssets packages + a thin meta-package (the SkiaSharp / SqlClient.SNI model) — download only your RID.
  • Go (ADR 0004): cgo against a prebuilt header + lib delivered through the azure-sdk-for-go feed; no NuGet, no runtime resolver.
  • Java: JAR on Maven, later — deliberately unspecified, but the hand-off stays general enough to repackage.
• ABI handshake (ADR 0005): the lib exports cosmos_abi_version(); every host checks it before first use and fails fast on mismatch instead of corrupting memory.
• Bindings own marshalling (ADR 0006): the ABI stays bytes-in / bytes-out; each language owns serialization and buffer copy-out.
• Native is opt-in (ADR 0007): opt-in per SDK until GA on all platforms, then default-with-managed-fallback. Pure-managed / pure-Go consumers are never force-migrated by a version bump.
• Bounded platform matrix (ADR 0008) with actionable errors on unsupported targets, and one build → sign once → fan-out (ADR 0009) where per-language jobs consume the signed hand-off and never rebuild.

Rust build (ONE run, all platforms) → sign binaries
        │
        ▼
INTERNAL HAND-OFF ARTIFACT  (provenance + SBOM anchor; not consumer-facing)   ← ADR 0001
        │
   ┌────┼─────────────┐
 .NET   Go            Java        ← each job pulls the SAME signed binaries (never rebuilds)
 NuGet  cgo header+lib JAR
 → nuget.org → azure-sdk-for-go → Maven                                        ← ADR 0002

Contents

• docs/native-distribution/distribution-design.md — the discussion doc: purpose, goals/constraints, the model, per-consumer link model, platform matrix, rollout phases, and open questions.
• docs/native-distribution/adr/0000-index.md and 0001–0009 — one decision per record.

Status & open questions

Status is provisional ("proposed for review"). The main open questions the doc captures for reviewers: the internal hand-off shape (Universal Package vs pipeline artifact), packaging-pipeline ownership and its security boundary, the Go delivery model, version-mapping across the three feeds, and SBOM / component-governance ownership for the Rust crate graph.

[Copilot]

Pull request overview

This documentation-only PR adds a design document plus nine Architecture Decision Records (ADRs) describing how the future Rust-built native Cosmos driver (azure_data_cosmos_driver_native → azurecosmosdriver.{dll,so,dylib} + cbindgen C header) will be distributed to the .NET, Go, and (later) Java SDKs. The core idea is to separate provenance (one signed build → internal hand-off artifact) from distribution (per-language packages on each language's existing feed). No code, build, or pipeline behavior changes; everything is marked "proposed for review."

Changes:

• Adds distribution-design.md — the discussion doc (purpose, goals, model, per-consumer link model, platform matrix, rollout, open questions).
• Adds ADRs 0000–0009 capturing each decision (build-once hand-off, per-language feeds, .NET NuGet NativeAssets, Go cgo, ABI handshake, marshalling ownership, opt-in native, platform matrix, build/sign pipeline).
• References an existing/planned NATIVE_WRAPPER_SPEC.md as the owner of the C-ABI surface.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
docs/native-distribution/distribution-design.md	Main design discussion; links to ADRs and to a non-existent NATIVE_WRAPPER_SPEC.md; introduces many domain terms not in the cSpell dictionaries.
docs/native-distribution/adr/0000-index.md	ADR index/template overview; links resolve correctly.
docs/native-distribution/adr/0001-build-once-internal-handoff.md	Decision: single build → internal-only hand-off artifact.
docs/native-distribution/adr/0002-per-language-feed-distribution.md	Decision: distribute via each language's existing feeds.
docs/native-distribution/adr/0003-dotnet-nuget-nativeassets.md	Decision: .NET per-RID NuGet NativeAssets + meta-package.
docs/native-distribution/adr/0004-go-cgo-prebuilt.md	Decision: Go consumes prebuilt header+lib via cgo.
docs/native-distribution/adr/0005-abi-version-handshake.md	Decision: lib exports cosmos_abi_version(); hosts check before use.
docs/native-distribution/adr/0006-binding-owns-marshalling.md	Decision: bindings own marshalling/copy-out; links to non-existent NATIVE_WRAPPER_SPEC.md.
docs/native-distribution/adr/0007-native-is-opt-in.md	Decision: native is opt-in until GA, then default-with-fallback.
docs/native-distribution/adr/0008-platform-matrix.md	Decision: bounded platform matrix; clear error on unsupported targets.
docs/native-distribution/adr/0009-build-and-signing-pipeline.md	Decision: one build, sign once, fan-out; jobs never rebuild.

The two notable issues are CI-blocking: a broken relative link to NATIVE_WRAPPER_SPEC.md (referenced from the design doc and ADR 0006, but the file doesn't exist) which verify-links will fail, and numerous new domain terms missing from the cSpell dictionaries (with no per-file <!-- cspell:ignore --> comment that sibling specs use) which the ContinueOnError:false spell check will fail.

[FabianMeiswinkel]

There won't be any pure managed users - not pushing back angainst teh decision - but against this false argument. .Net vNext will require a native package.

[Pilchie]

Agreed!

[FabianMeiswinkel]

I assume MinSupported==MAxSupported always - everything else results in unreasonable test matrix. Why not just close the range and make the contract clear - that there is exactly one version targeted?

[FabianMeiswinkel]

SDKs will ALWAYS have to use a new major version when switching to Rust driver - at this point native vs. managed transport does not make sense to be hept in parallel - new maor version --> Rust native transport only - so, this is not opt-in for sure.

[Pilchie]

Yes, I also disagree with this ADR. It's true that we might face pushback in Go, and lose some scenarios in JS by relying on the driver. At this point, I think those are worth it. If we need a pure go/pure js package at some point, I think it would be clearer/easier that they be completely different packages advertised to have limited functionality, instead of trying to offer fallback in the main SDK.

[FabianMeiswinkel]

no range - should be single native version - otherwise testing becomes unreaosnable.

[Pilchie]

Agree here.

[FabianMeiswinkel]

i think this doc is duplicate? Either keep the ADRs (i like them) or this doc - not both

[Pilchie]

I think the idea is that this could keep more of the thinking that would make the ADRs too verbose, but in this case I agree that this doesn't seem to add much value.

[FabianMeiswinkel]

Rust/Native as opt-in is a no-go in my mind.

[NaluTripician]

Design review — native driver distribution

Read the whole set (design doc + ADRs 0000–0010). Overall this is a strong, well-structured design and the ADR hygiene is clean. I spot-checked the external references and they hold up: the SkiaSharp / Microsoft.Data.SqlClient.SNI per-RID runtimes/<rid>/native/ + runtime.json meta-package pattern, manylinux2014 ⇔ glibc 2.17, the cgo CFLAGS -I / LDFLAGS -L -l mechanics, cbindgen C-only header, and crate-type = ["cdylib","staticlib"] are all described correctly.

A few things I'd want resolved before these move from "proposed" to "accepted". Inline comments cover the independent ones; the three below overlap with Fabian's open CHANGES_REQUESTED, so I'm reinforcing rather than restating.

Blocking

• Opt-in / "pure-managed users" premise (ADR 0007 + G4, ADR 0003). If the next .NET major requires the native package (as Fabian notes), then "never force-migrated" / "opt-in" mis-frames the rollout, and ADR 0003's rejected-alternative argument ("bloats the flagship for pure-managed users") rests on a user class that won't exist. Independently: a NuGet <PackageReference> is not "opt-in" — it always restores transitively. Please state the actual mechanism (flagship has no dep + consumer adds the meta-package, OR hard dep that's inert behind a client flag) and reconcile 0003/0007 with "mandatory at next major."
• Linux has no signature for the integrity gate (ADR 0009 / 0007). See inline.
• ABI range vs single-version lockstep (ADR 0005 [Min,Max] vs ADR 0010 "never forked"). These two read as contradictory; if fan-out is always one coordinated version, the acceptance range only grows the test matrix. Collapse to a single targeted revision (Min==Max) or explain how a range coexists with 0010.

Important — see inline on ADR 0004 (public-Go delivery + static link flags), ADR 0010 (atomic fan-out on immutable feeds), and distribution-design.md §8 (now stale vs ADR 0009).

Also: design-doc §10 ("fallback on load failure") contradicts ADR 0007's fail-loud-on-integrity rule — §10 should mirror the benign-vs-integrity split. And the heavy §5–§11 restatement of the ADRs is what's producing these drifts (the §8 one is a concrete example); consider trimming the design body to discussion/alternatives and linking out for decisions.

Nits: status convention split (0010 "Proposed" while dependents are "Accepted"); the "Pairs with" note is on 0001/0002 only — either add it to the template or to the other coupled pairs; dangling NATIVE_WRAPPER_SPEC.md refs (add "forthcoming, #4461") and a pointer to the cosmos_free-style dealloc export behind ADR 0006's "frees the native buffer"; "download only your RID" is unconditional-sounding but differs for framework-dependent builds.

Nothing here is a showstopper for the idea — it's a genuinely good design. These are about closing the seams before downstream teams build against it.

[NaluTripician]

The signing step names Authenticode (Windows) and codesign + notarization (macOS), but nothing for the three Linux RIDs (linux-x64, linux-musl-x64, linux-arm64). That's a gap, because both this ADR and ADR 0007 make "verify signatures / fail-loud on signature failure" load-bearing — and Linux .so/.a have no platform code-signing equivalent. A checksum proves integrity but not authenticity/provenance (it's computed over whatever bytes you have). Could we name an explicit Linux authenticity mechanism — detached signatures (cosign/Sigstore/GPG), or signing + attesting the Universal Package hand-off itself as the trust root — and soften "verifies signatures" to "verifies signatures (where applicable) + provenance attestation" so the gate is actually implementable on Linux?

[NaluTripician]

Both delivery options here are problematic for public Go consumers. Azure Artifacts Universal Packages are internal-only, so an external go get user can't fetch them — that option only really covers the internal/dogfood phases. And a vendored "binaries" Go module means committing ~7 platforms of multi-MB native libs into a module the proxy pulls wholesale on every go get; that's exactly why the canonical cgo libraries (e.g. go-sqlite3) ship C source rather than prebuilt binaries. Related: Go has no package "feed" — modules resolve from VCS via the module proxy, so describing azure-sdk-for-go as a "feed" (also ADR 0002 / §6.2) is misleading. Can we add a concrete public-Go answer (GitHub Releases + a small fetch shim, or build-tag selection of a per-RID .a)? This feels bigger than Q3's internal-only "Universal Package vs vendored module" framing.

[NaluTripician]

One -lazurecosmosdriver won't be enough to statically link a Rust staticlib through cgo. A Rust staticlib isn't self-contained at link time — it pulls in the Rust std/panic/unwind runtime plus system libs (typically -lpthread -ldl -lm, often -lgcc_s/-lunwind), and static-cgo on musl is notoriously fiddly. Since linux-musl-x64 is in the GA matrix and this ADR prefers the static .a by default, worth noting the per-OS LDFLAGS must include the transitive system libs and flagging musl-static-cgo as a known-hard case (it bears on whether "static by default" is realistic on every matrix row — Q4).

[NaluTripician]

"All-or-nothing" isn't physically achievable on nuget.org or Maven Central — neither supports unpublish/retraction. Once a NativeAssets package is live on nuget.org, a later Go-publish failure can't be rolled back to restore atomicity; the only remedy is roll-forward (publish the next patch everywhere). Suggest replacing the implied transactional rollback with the achievable model: publish to internal/staging feeds atomically, gate the public push on all-green, and on a partial public failure roll forward, never retract — and say so, so implementers don't design for an impossible rollback.

[NaluTripician]

This says build-once is "enforced by discipline," but ADR 0009 (the authoritative record) upgraded this to "enforced by verification, not just discipline" with a checksum/signature gate that fails the publish on mismatch. By this doc's own "if the two disagree, the ADR wins" rule, §8 is now stale and understates the actual mechanism. Worth syncing — and a good example of why the §5–§11 restatements risk drifting from the ADRs.

[Pilchie]

Maybe semantics, but this might actually be multiple "builds/pipelines" because (for example), I don't think we can't cross-compile macOS binaries from other platforms. That said, I do think we should have a "join" task that does signing and collects all the artifacts for a given release. It just might be the case that it has to collect earlier stage artifacts from other "builds".

[Pilchie]

We should run this by the .NET/NuGet teams and see if there are any unexpected consequences to this choice.

[Pilchie]

As @FabianMeiswinkel says, we shouldn't have opt-in.

[Pilchie]

Agreed!

[Pilchie]

I think the open question here is if we decide to do string->binary encoding in the driver someday, it would require a documented string encoding, presumably UTF-8. Practically, I think that's what we want anyways. We don't really want .NET to be passing in 16-bit char values and having rust put those on the wire anyway, so while I agree with bytes in/bytes out, I think it should maybe be explicitly UTF-8 bytes in/out.

[Pilchie]

Yes, I also disagree with this ADR. It's true that we might face pushback in Go, and lose some scenarios in JS by relying on the driver. At this point, I think those are worth it. If we need a pure go/pure js package at some point, I think it would be clearer/easier that they be completely different packages advertised to have limited functionality, instead of trying to offer fallback in the main SDK.

[Pilchie]

I believe we need win-x86 since Azure App Service defaults to x86 for windows AppService instances.

[Pilchie]

See above - there is a very clear scenario where we will need this.

[Pilchie]

Agree here.

[Pilchie]

I think the idea is that this could keep more of the thinking that would make the ADRs too verbose, but in this case I agree that this doesn't seem to add much value.

[heaths]

Keep changes to sdk/cosmos and you won't need my sign-off.

[heaths]

Put all these in sdk/cosmos/cspell.json and you won't need core sign-off. Granted, some of these are generic, but we can handle that separately.