From 72e70985e331ee0bb17a2f88cdb9f9cacbcf3a3c Mon Sep 17 00:00:00 2001 From: Ananth Mudumba Date: Fri, 17 Jul 2026 13:23:56 -0700 Subject: [PATCH 1/8] docs(cosmos): add Go v2 FFI decision Record the Go v2 decision to proceed with the Rust-driver FFI path for the current delivery window. The document captures the pure-Go port alternative, packaging implications, tentative platform matrix, and native-library market precedent without folding the decision into the native distribution ADR PR. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: f7d60272-a96c-48e4-9a85-6e918db6ac26 --- .../docs/GO_V2_FFI_DECISION.md | 155 ++++++++++++++++++ 1 file changed, 155 insertions(+) create mode 100644 sdk/cosmos/azure_data_cosmos_driver/docs/GO_V2_FFI_DECISION.md diff --git a/sdk/cosmos/azure_data_cosmos_driver/docs/GO_V2_FFI_DECISION.md b/sdk/cosmos/azure_data_cosmos_driver/docs/GO_V2_FFI_DECISION.md new file mode 100644 index 00000000000..7a241afa2a3 --- /dev/null +++ b/sdk/cosmos/azure_data_cosmos_driver/docs/GO_V2_FFI_DECISION.md @@ -0,0 +1,155 @@ +# Go v2 SDK decision: use the Rust driver through FFI + +**Status:** Proposed +**Decision:** Go v2 proceeds with the Rust-driver FFI path for the current delivery window. + +## Context + +The team evaluated two implementation paths for the next-generation Go SDK: + +- **FFI path:** Go calls the prebuilt Rust driver through cgo and a C ABI. +- **Pure-Go port:** Go reimplements the driver behavior directly in Go. + +Both paths were shown to be technically feasible. The pure-Go spike proved that a +gateway-mode core path can be ported in idiomatic Go: `CGO_ENABLED=0`, zero +third-party dependencies, point create/read, retry/routing behavior, basic +failover behavior, cross-partition unordered query fan-out, and unsupported-query +rejection parity. + +The spike was validated with a scenario-based differential harness. The harness +put an HTTP endpoint in front of the Rust driver's in-memory emulator so the Go +port and the Rust driver could run against the same emulator-backed state and +compare caller-visible outcomes. + +That result is important: the Go port is credible. The decision is therefore not +"can we port it?" The real trade-off is: + +> Is avoiding cgo and native packaging worth re-owning driver logic that Rust +> already implements? + +For the current Go v2 timeframe, the answer is **no**. FFI gives faster delivery, +stronger parity with the Rust driver, and lower short-term implementation risk. + +## Decision + +- Go v2 will use the **Rust driver through FFI** for the current delivery window. +- The Go binding will consume the **prebuilt native driver** through cgo and the + C ABI surface. +- The pure-Go port remains useful as validation evidence and as a reference for + Go-visible behavior, but it is not the Go v2 delivery path. + +## Why FFI for Go v2 + +FFI has the better short-term delivery shape: + +- **Parity:** Go consumes the same driver implementation as Rust. +- **Velocity:** new Rust-driver behavior does not need to be re-ported into Go + before Go can benefit. +- **Risk containment:** the hard driver logic stays in one implementation. +- **Testing leverage:** the Go binding can validate language-level behavior + against the Rust driver's known behavior instead of re-proving the full driver. + +The main cost is not binary size. The main cost is **Go packaging and customer +deployment experience**. + +## Packaging implications + +Cosmos Go v1 is consumed like a normal Go SDK: + +```bash +go get github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos +go build ./... +``` + +There is no Rust compiler, C compiler, native shared library, or post-install +step in the customer path. If Go v2 uses FFI, the packaging bar is therefore: + +> Can the Go SDK still feel like one normal Go module across the supported +> Windows, macOS, and Linux targets? + +That means native Rust driver artifacts must be produced, versioned, selected, +and linked for the supported Go OS/architecture matrix. + +The platform discussion quickly reaches roughly ten target combinations: + +| OS family | Target combinations discussed | +|---|---| +| Windows | x64/amd64, ARM64, possibly x86 as a consideration | +| macOS | ARM64/Apple Silicon, x64/Intel | +| Linux glibc | x64/amd64, ARM64 | +| Linux musl/Alpine | x64/amd64, ARM64 | + +The Linux callout is especially important: supporting both glibc and musl means +likely needing **four Linux binaries**: amd64/arm64 × glibc/musl. + +With an estimated **~5 MB optimized native binary per platform**, the +all-platform packaging footprint can reach roughly **~50 MB** before compression +or packaging refinements. This is manageable for an initial release, but it is a +real packaging design point and should not be treated as an implementation +detail. + +## Packaging models to evaluate + +Two practical models are on the table: + +| Model | Customer experience | Trade-off | +|---|---|---| +| **Bundle the full platform matrix in the Go package** | Closest to `go get` / `go build` just working everywhere | Larger module/package footprint; all platform binaries travel together | +| **Per-platform native dependency** | Customer obtains only the platform-specific binary they need | Smaller per-customer footprint, but more setup burden and more room for install mistakes | + +The second model has industry precedent. For example, +[`confluent-kafka-go`](https://github.com/confluentinc/confluent-kafka-go/blob/master/README.md#librdkafka) +bundles prebuilt `librdkafka` binaries for common platforms, requires +`CGO_ENABLED` to remain enabled, uses a `musl` build tag for Alpine, and asks +customers to install `librdkafka` manually when they need unsupported platforms +or special features such as GSSAPI/Kerberos. + +That reference shows a viable market pattern for a Go library backed by native +code: **bundle the common path, document unsupported/special paths clearly, and +make native requirements explicit**. It also confirms that this is a materially +different customer experience from a pure-Go Azure SDK. + +## Pure-Go port trade-off + +The pure-Go path has a strong developer-experience story: + +- `CGO_ENABLED=0` +- normal Go cross-compilation +- no native runtime dependency +- Go standard library transport/TLS/runtime + +But it moves the cost into ownership: + +- driver behavior must be reimplemented in Go +- every Rust-driver change has to be tracked, ported, and revalidated +- long-term drift becomes the main risk +- the hardest remaining areas still need evidence: richer query execution, + continuation/split-resume behavior, broader multi-region behavior, change feed, + and bulk/batch + +The pure-Go spike remains valuable because it proved the fallback is not +fictional. It also produced a useful differential-validation approach. But for +Go v2, it is better treated as evidence and risk retirement, not the shipping +plan. + +## Consequences + +- Go v2 takes a dependency on cgo for the Rust-driver path. +- The Go SDK packaging design must be treated as part of the product decision, + not as an afterthought. +- The native distribution plan must explicitly cover Windows, macOS, Linux + glibc, Linux musl/Alpine, amd64, and ARM64 targets. +- Customer-facing docs must clearly state the native dependency model, + `CGO_ENABLED` expectations, supported platform matrix, and unsupported-platform + behavior. +- Differential validation should continue so Go-visible behavior can be tested + against the Rust driver. + +## Non-goals + +- This decision does not define the final Go packaging shape. +- This decision does not require customers to manually install native libraries. +- This decision does not introduce direct mode; both the Rust and Go v2 paths are + gateway-mode SDKs. +- This decision does not remove the pure-Go spike as a reference or validation + asset. From 57988cdf8d95173243129058423bff9b92693625 Mon Sep 17 00:00:00 2001 From: Ananth Mudumba Date: Fri, 17 Jul 2026 13:28:59 -0700 Subject: [PATCH 2/8] docs(cosmos): shape Go v2 decision as ADR Restructure the Go v2 FFI decision PR to match the ADR pattern used by the native distribution design. Keep the decision itself short and move the exploration, platform matrix, packaging discussion, and market reference into a separate discussion document. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: f7d60272-a96c-48e4-9a85-6e918db6ac26 --- .../docs/go-v2-ffi/adr/0000-index.md | 19 +++ .../docs/go-v2-ffi/adr/0001-go-v2-uses-ffi.md | 49 ++++++++ .../go-v2-ffi-exploration.md} | 112 +++++++++--------- 3 files changed, 125 insertions(+), 55 deletions(-) create mode 100644 sdk/cosmos/azure_data_cosmos_driver/docs/go-v2-ffi/adr/0000-index.md create mode 100644 sdk/cosmos/azure_data_cosmos_driver/docs/go-v2-ffi/adr/0001-go-v2-uses-ffi.md rename sdk/cosmos/azure_data_cosmos_driver/docs/{GO_V2_FFI_DECISION.md => go-v2-ffi/go-v2-ffi-exploration.md} (62%) diff --git a/sdk/cosmos/azure_data_cosmos_driver/docs/go-v2-ffi/adr/0000-index.md b/sdk/cosmos/azure_data_cosmos_driver/docs/go-v2-ffi/adr/0000-index.md new file mode 100644 index 00000000000..e05c3a9c532 --- /dev/null +++ b/sdk/cosmos/azure_data_cosmos_driver/docs/go-v2-ffi/adr/0000-index.md @@ -0,0 +1,19 @@ +# Architecture Decision Records — Go v2 FFI direction + +ADRs (Architecture Decision Records) capture **what we decided** and a brief +**why**, in a minimal, easy-to-reference form. They are **numbered and +immutable**: once accepted, an ADR is not edited; a later ADR may supersede it. +Detailed discussion and exploration live in +[`../go-v2-ffi-exploration.md`](../go-v2-ffi-exploration.md), not here. + +**Format (template):** Status (immediately under the title) · Context (2-4 +sentences) · Decision (1-3 bullets) · Consequences (2-4 bullets) · Alternatives +considered (1 line each). + +| # | Title | Status | +|---|-------|--------| +| [0001](0001-go-v2-uses-ffi.md) | Go v2 uses the Rust driver through FFI | Proposed | + +> This ADR is proposed for review. Packaging mechanics are intentionally left to +> the native distribution ADRs; this record captures the Go v2 implementation +> direction. diff --git a/sdk/cosmos/azure_data_cosmos_driver/docs/go-v2-ffi/adr/0001-go-v2-uses-ffi.md b/sdk/cosmos/azure_data_cosmos_driver/docs/go-v2-ffi/adr/0001-go-v2-uses-ffi.md new file mode 100644 index 00000000000..9f93b997438 --- /dev/null +++ b/sdk/cosmos/azure_data_cosmos_driver/docs/go-v2-ffi/adr/0001-go-v2-uses-ffi.md @@ -0,0 +1,49 @@ +# ADR 0001 — Go v2 uses the Rust driver through FFI + +**Status:** Proposed + +## Context + +Go v2 needs a path that can deliver in the current timeframe while staying close +to the Rust driver's behavior. A time-boxed pure-Go spike proved that a +gateway-mode core path can be ported and validated, but it also clarified the +central trade-off: avoiding cgo and native packaging means re-owning driver +logic in Go and carrying long-term Rust-to-Go drift risk. + +## Decision + +- Go v2 proceeds with the **Rust-driver FFI path** for the current delivery + window. +- The Go binding consumes the **prebuilt Rust native driver** through cgo and the + C ABI surface. +- Packaging mechanics, platform matrix, signing, ABI versioning, and fan-out are + handled by the native distribution design and ADRs. + +## Consequences + +- Go v2 gets the same driver implementation as Rust, reducing short-term feature + drift and implementation risk. +- Go v2 takes a dependency on `CGO_ENABLED=1` for the native driver path. +- The Go packaging model becomes part of the product decision: customers should + not manually install Rust/C toolchains or copy native libraries for the common + path. +- Differential validation remains important so Go-visible behavior can be tested + against the Rust driver. + +## Alternatives considered + +- **Pure-Go driver port** — technically feasible for the core path tested, but + not selected for Go v2 because it shifts cost from packaging to long-term Go + ownership and Rust-to-Go drift. +- **Manual native-library installation** — rejected for the common path because + it breaks the normal `go get` / `go build` expectation for a first-party Go + SDK. +- **Pure-Go downloader shim** — rejected by the native distribution ADRs; the + native driver must be packaged and linked through the FFI path, not fetched by + a downloader stub. + +## Discussion + +See [`../go-v2-ffi-exploration.md`](../go-v2-ffi-exploration.md) for the +meeting context, pure-Go spike evidence, packaging concerns, tentative platform +matrix, and market reference points. diff --git a/sdk/cosmos/azure_data_cosmos_driver/docs/GO_V2_FFI_DECISION.md b/sdk/cosmos/azure_data_cosmos_driver/docs/go-v2-ffi/go-v2-ffi-exploration.md similarity index 62% rename from sdk/cosmos/azure_data_cosmos_driver/docs/GO_V2_FFI_DECISION.md rename to sdk/cosmos/azure_data_cosmos_driver/docs/go-v2-ffi/go-v2-ffi-exploration.md index 7a241afa2a3..12545b6a621 100644 --- a/sdk/cosmos/azure_data_cosmos_driver/docs/GO_V2_FFI_DECISION.md +++ b/sdk/cosmos/azure_data_cosmos_driver/docs/go-v2-ffi/go-v2-ffi-exploration.md @@ -1,50 +1,64 @@ -# Go v2 SDK decision: use the Rust driver through FFI +# Go v2 FFI exploration notes -**Status:** Proposed -**Decision:** Go v2 proceeds with the Rust-driver FFI path for the current delivery window. +> **Status:** Discussion notes for ADR review. The decision is recorded in +> [`adr/0001-go-v2-uses-ffi.md`](adr/0001-go-v2-uses-ffi.md). -## Context +## 1. Purpose -The team evaluated two implementation paths for the next-generation Go SDK: +This document captures the exploration behind the Go v2 decision to proceed with +the Rust-driver FFI path in the current delivery window. It is intentionally more +descriptive than the ADR: it records the trade-offs, pure-Go spike evidence, +packaging implications, and market reference points that informed the decision. -- **FFI path:** Go calls the prebuilt Rust driver through cgo and a C ABI. -- **Pure-Go port:** Go reimplements the driver behavior directly in Go. +## 2. Implementation paths evaluated -Both paths were shown to be technically feasible. The pure-Go spike proved that a -gateway-mode core path can be ported in idiomatic Go: `CGO_ENABLED=0`, zero -third-party dependencies, point create/read, retry/routing behavior, basic -failover behavior, cross-partition unordered query fan-out, and unsupported-query -rejection parity. +The team evaluated two paths: -The spike was validated with a scenario-based differential harness. The harness -put an HTTP endpoint in front of the Rust driver's in-memory emulator so the Go -port and the Rust driver could run against the same emulator-backed state and -compare caller-visible outcomes. +| Path | Shape | +|---|---| +| **FFI path** | Go calls the prebuilt Rust driver through cgo and a C ABI. | +| **Pure-Go port** | Go reimplements the driver behavior directly in Go. | -That result is important: the Go port is credible. The decision is therefore not -"can we port it?" The real trade-off is: +Both were technically feasible. The decision is not "can we port it?" The +decision is: > Is avoiding cgo and native packaging worth re-owning driver logic that Rust > already implements? -For the current Go v2 timeframe, the answer is **no**. FFI gives faster delivery, -stronger parity with the Rust driver, and lower short-term implementation risk. +For the Go v2 timeframe, the team aligned on **FFI** because it gives faster +delivery, stronger parity with the Rust driver, and lower short-term +implementation risk. + +## 3. What the pure-Go spike proved + +The pure-Go spike showed that a gateway-mode core path can be ported in +idiomatic Go: -## Decision +- `CGO_ENABLED=0` +- zero third-party dependencies +- point create/read +- retry and routing behavior +- basic failover behavior +- cross-partition unordered query fan-out +- unsupported-query rejection parity -- Go v2 will use the **Rust driver through FFI** for the current delivery window. -- The Go binding will consume the **prebuilt native driver** through cgo and the - C ABI surface. -- The pure-Go port remains useful as validation evidence and as a reference for - Go-visible behavior, but it is not the Go v2 delivery path. +The spike was validated with a scenario-based differential harness. The harness +put an HTTP endpoint in front of the Rust driver's in-memory emulator so the Go +port and the Rust driver could run against the same emulator-backed state and +compare caller-visible outcomes. + +This is valuable evidence: the Go port is credible. It is also a useful +validation reference for Go-visible behavior. It is not the selected Go v2 +delivery path because every Rust-driver change would need to be tracked, ported, +and revalidated in Go. -## Why FFI for Go v2 +## 4. Why FFI for Go v2 FFI has the better short-term delivery shape: - **Parity:** Go consumes the same driver implementation as Rust. -- **Velocity:** new Rust-driver behavior does not need to be re-ported into Go - before Go can benefit. +- **Velocity:** new Rust-driver behavior does not need to be re-ported before Go + can benefit. - **Risk containment:** the hard driver logic stays in one implementation. - **Testing leverage:** the Go binding can validate language-level behavior against the Rust driver's known behavior instead of re-proving the full driver. @@ -52,7 +66,7 @@ FFI has the better short-term delivery shape: The main cost is not binary size. The main cost is **Go packaging and customer deployment experience**. -## Packaging implications +## 5. Packaging implications Cosmos Go v1 is consumed like a normal Go SDK: @@ -88,9 +102,9 @@ or packaging refinements. This is manageable for an initial release, but it is a real packaging design point and should not be treated as an implementation detail. -## Packaging models to evaluate +## 6. Packaging models to evaluate -Two practical models are on the table: +Two practical models were discussed: | Model | Customer experience | Trade-off | |---|---|---| @@ -109,7 +123,7 @@ code: **bundle the common path, document unsupported/special paths clearly, and make native requirements explicit**. It also confirms that this is a materially different customer experience from a pure-Go Azure SDK. -## Pure-Go port trade-off +## 7. Pure-Go port trade-off The pure-Go path has a strong developer-experience story: @@ -124,32 +138,20 @@ But it moves the cost into ownership: - every Rust-driver change has to be tracked, ported, and revalidated - long-term drift becomes the main risk - the hardest remaining areas still need evidence: richer query execution, - continuation/split-resume behavior, broader multi-region behavior, change feed, - and bulk/batch + continuation/split-resume behavior, broader multi-region behavior, change + feed, and bulk/batch The pure-Go spike remains valuable because it proved the fallback is not fictional. It also produced a useful differential-validation approach. But for Go v2, it is better treated as evidence and risk retirement, not the shipping plan. -## Consequences - -- Go v2 takes a dependency on cgo for the Rust-driver path. -- The Go SDK packaging design must be treated as part of the product decision, - not as an afterthought. -- The native distribution plan must explicitly cover Windows, macOS, Linux - glibc, Linux musl/Alpine, amd64, and ARM64 targets. -- Customer-facing docs must clearly state the native dependency model, - `CGO_ENABLED` expectations, supported platform matrix, and unsupported-platform - behavior. -- Differential validation should continue so Go-visible behavior can be tested - against the Rust driver. - -## Non-goals - -- This decision does not define the final Go packaging shape. -- This decision does not require customers to manually install native libraries. -- This decision does not introduce direct mode; both the Rust and Go v2 paths are - gateway-mode SDKs. -- This decision does not remove the pure-Go spike as a reference or validation +## 8. Non-goals + +- This discussion does not define the final Go packaging shape. +- This discussion does not require customers to manually install native + libraries. +- This discussion does not introduce direct mode; both the Rust and Go v2 paths + are gateway-mode SDKs. +- This discussion does not remove the pure-Go spike as a reference or validation asset. From 4bb21b3b58dca1bee85120e28bda01ed5090f403 Mon Sep 17 00:00:00 2001 From: Ananth Mudumba Date: Fri, 17 Jul 2026 13:32:46 -0700 Subject: [PATCH 3/8] docs(cosmos): move Go FFI ADR under native docs Move the Go v2 FFI ADR set under docs/native-driver-distribution/go-native-distribution so it shares the same native-driver distribution root as the broader packaging ADRs. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: f7d60272-a96c-48e4-9a85-6e918db6ac26 --- .../go-native-distribution}/adr/0000-index.md | 0 .../go-native-distribution}/adr/0001-go-v2-uses-ffi.md | 0 .../go-native-distribution}/go-v2-ffi-exploration.md | 0 3 files changed, 0 insertions(+), 0 deletions(-) rename sdk/cosmos/azure_data_cosmos_driver/docs/{go-v2-ffi => native-driver-distribution/go-native-distribution}/adr/0000-index.md (100%) rename sdk/cosmos/azure_data_cosmos_driver/docs/{go-v2-ffi => native-driver-distribution/go-native-distribution}/adr/0001-go-v2-uses-ffi.md (100%) rename sdk/cosmos/azure_data_cosmos_driver/docs/{go-v2-ffi => native-driver-distribution/go-native-distribution}/go-v2-ffi-exploration.md (100%) diff --git a/sdk/cosmos/azure_data_cosmos_driver/docs/go-v2-ffi/adr/0000-index.md b/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/adr/0000-index.md similarity index 100% rename from sdk/cosmos/azure_data_cosmos_driver/docs/go-v2-ffi/adr/0000-index.md rename to sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/adr/0000-index.md diff --git a/sdk/cosmos/azure_data_cosmos_driver/docs/go-v2-ffi/adr/0001-go-v2-uses-ffi.md b/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/adr/0001-go-v2-uses-ffi.md similarity index 100% rename from sdk/cosmos/azure_data_cosmos_driver/docs/go-v2-ffi/adr/0001-go-v2-uses-ffi.md rename to sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/adr/0001-go-v2-uses-ffi.md diff --git a/sdk/cosmos/azure_data_cosmos_driver/docs/go-v2-ffi/go-v2-ffi-exploration.md b/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/go-v2-ffi-exploration.md similarity index 100% rename from sdk/cosmos/azure_data_cosmos_driver/docs/go-v2-ffi/go-v2-ffi-exploration.md rename to sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/go-v2-ffi-exploration.md From 5e1210673d23623231fa9a5a58442817baafef22 Mon Sep 17 00:00:00 2001 From: Ananth Mudumba Date: Fri, 17 Jul 2026 13:43:40 -0700 Subject: [PATCH 4/8] docs(cosmos): clarify Go FFI packaging caveats Address review feedback by making the cgo C-toolchain requirement explicit and by describing confluent-kafka-go as a bundle-first hybrid rather than precedent for a pure per-platform/manual dependency model. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: f7d60272-a96c-48e4-9a85-6e918db6ac26 --- .../adr/0001-go-v2-uses-ffi.md | 4 ++-- .../go-v2-ffi-exploration.md | 22 +++++++++++-------- 2 files changed, 15 insertions(+), 11 deletions(-) diff --git a/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/adr/0001-go-v2-uses-ffi.md b/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/adr/0001-go-v2-uses-ffi.md index 9f93b997438..56c7a96b072 100644 --- a/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/adr/0001-go-v2-uses-ffi.md +++ b/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/adr/0001-go-v2-uses-ffi.md @@ -25,8 +25,8 @@ logic in Go and carrying long-term Rust-to-Go drift risk. drift and implementation risk. - Go v2 takes a dependency on `CGO_ENABLED=1` for the native driver path. - The Go packaging model becomes part of the product decision: customers should - not manually install Rust/C toolchains or copy native libraries for the common - path. + not manually install a Rust toolchain or copy native libraries for the common + path, but cgo still requires an available C build toolchain. - Differential validation remains important so Go-visible behavior can be tested against the Rust driver. diff --git a/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/go-v2-ffi-exploration.md b/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/go-v2-ffi-exploration.md index 12545b6a621..161716b59df 100644 --- a/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/go-v2-ffi-exploration.md +++ b/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/go-v2-ffi-exploration.md @@ -75,8 +75,10 @@ go get github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos go build ./... ``` -There is no Rust compiler, C compiler, native shared library, or post-install -step in the customer path. If Go v2 uses FFI, the packaging bar is therefore: +There is no Rust compiler, native shared library, or post-install step in the +customer path. If Go v2 uses FFI, prebuilt Rust artifacts can preserve that part +of the experience, but cgo still requires a C build toolchain. The packaging bar +is therefore: > Can the Go SDK still feel like one normal Go module across the supported > Windows, macOS, and Linux targets? @@ -111,17 +113,19 @@ Two practical models were discussed: | **Bundle the full platform matrix in the Go package** | Closest to `go get` / `go build` just working everywhere | Larger module/package footprint; all platform binaries travel together | | **Per-platform native dependency** | Customer obtains only the platform-specific binary they need | Smaller per-customer footprint, but more setup burden and more room for install mistakes | -The second model has industry precedent. For example, +A bundle-first hybrid has industry precedent. For example, [`confluent-kafka-go`](https://github.com/confluentinc/confluent-kafka-go/blob/master/README.md#librdkafka) -bundles prebuilt `librdkafka` binaries for common platforms, requires -`CGO_ENABLED` to remain enabled, uses a `musl` build tag for Alpine, and asks -customers to install `librdkafka` manually when they need unsupported platforms -or special features such as GSSAPI/Kerberos. +includes prebuilt `librdkafka` binaries for common platforms, requires +`CGO_ENABLED` to remain enabled, and uses a +[`musl` build tag](https://github.com/confluentinc/confluent-kafka-go/blob/master/kafka/README.md#build-tags) +for Alpine. It falls back to a manual dynamic install only when customers need +unsupported platforms or special features such as GSSAPI/Kerberos. That reference shows a viable market pattern for a Go library backed by native code: **bundle the common path, document unsupported/special paths clearly, and -make native requirements explicit**. It also confirms that this is a materially -different customer experience from a pure-Go Azure SDK. +make native requirements explicit**. It aligns most closely with the first model, +with a manual native dependency as an escape hatch. It also confirms that this +is a materially different customer experience from a pure-Go Azure SDK. ## 7. Pure-Go port trade-off From a8dcdf2da442fd70ed4c2494b386f6e5dc3d8e01 Mon Sep 17 00:00:00 2001 From: Ananth Mudumba Date: Fri, 17 Jul 2026 13:46:05 -0700 Subject: [PATCH 5/8] docs(cosmos): adjust Go FFI platform notes Remove musl/Alpine from the fixed Go FFI platform matrix and clarify that platform footprint grows with supported targets. Also switch internal documentation links to absolute GitHub links for the repository link checker. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: f7d60272-a96c-48e4-9a85-6e918db6ac26 --- .../go-native-distribution/adr/0000-index.md | 5 ++-- .../adr/0001-go-v2-uses-ffi.md | 7 +++--- .../go-v2-ffi-exploration.md | 23 ++++++++----------- 3 files changed, 16 insertions(+), 19 deletions(-) diff --git a/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/adr/0000-index.md b/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/adr/0000-index.md index e05c3a9c532..e563243c812 100644 --- a/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/adr/0000-index.md +++ b/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/adr/0000-index.md @@ -4,7 +4,8 @@ ADRs (Architecture Decision Records) capture **what we decided** and a brief **why**, in a minimal, easy-to-reference form. They are **numbered and immutable**: once accepted, an ADR is not edited; a later ADR may supersede it. Detailed discussion and exploration live in -[`../go-v2-ffi-exploration.md`](../go-v2-ffi-exploration.md), not here. +[`go-v2-ffi-exploration.md`](https://github.com/Azure/azure-sdk-for-rust/blob/main/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/go-v2-ffi-exploration.md), +not here. **Format (template):** Status (immediately under the title) · Context (2-4 sentences) · Decision (1-3 bullets) · Consequences (2-4 bullets) · Alternatives @@ -12,7 +13,7 @@ considered (1 line each). | # | Title | Status | |---|-------|--------| -| [0001](0001-go-v2-uses-ffi.md) | Go v2 uses the Rust driver through FFI | Proposed | +| [0001](https://github.com/Azure/azure-sdk-for-rust/blob/main/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/adr/0001-go-v2-uses-ffi.md) | Go v2 uses the Rust driver through FFI | Proposed | > This ADR is proposed for review. Packaging mechanics are intentionally left to > the native distribution ADRs; this record captures the Go v2 implementation diff --git a/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/adr/0001-go-v2-uses-ffi.md b/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/adr/0001-go-v2-uses-ffi.md index 56c7a96b072..72fbe962129 100644 --- a/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/adr/0001-go-v2-uses-ffi.md +++ b/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/adr/0001-go-v2-uses-ffi.md @@ -44,6 +44,7 @@ logic in Go and carrying long-term Rust-to-Go drift risk. ## Discussion -See [`../go-v2-ffi-exploration.md`](../go-v2-ffi-exploration.md) for the -meeting context, pure-Go spike evidence, packaging concerns, tentative platform -matrix, and market reference points. +See +[`go-v2-ffi-exploration.md`](https://github.com/Azure/azure-sdk-for-rust/blob/main/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/go-v2-ffi-exploration.md) +for the meeting context, pure-Go spike evidence, packaging concerns, tentative +platform matrix, and market reference points. diff --git a/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/go-v2-ffi-exploration.md b/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/go-v2-ffi-exploration.md index 161716b59df..6ab657f9266 100644 --- a/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/go-v2-ffi-exploration.md +++ b/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/go-v2-ffi-exploration.md @@ -1,7 +1,7 @@ # Go v2 FFI exploration notes > **Status:** Discussion notes for ADR review. The decision is recorded in -> [`adr/0001-go-v2-uses-ffi.md`](adr/0001-go-v2-uses-ffi.md). +> [`ADR 0001`](https://github.com/Azure/azure-sdk-for-rust/blob/main/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/adr/0001-go-v2-uses-ffi.md). ## 1. Purpose @@ -86,23 +86,19 @@ is therefore: That means native Rust driver artifacts must be produced, versioned, selected, and linked for the supported Go OS/architecture matrix. -The platform discussion quickly reaches roughly ten target combinations: +The fixed platform discussion should start with the mainstream OS/architecture +targets: | OS family | Target combinations discussed | |---|---| | Windows | x64/amd64, ARM64, possibly x86 as a consideration | | macOS | ARM64/Apple Silicon, x64/Intel | | Linux glibc | x64/amd64, ARM64 | -| Linux musl/Alpine | x64/amd64, ARM64 | - -The Linux callout is especially important: supporting both glibc and musl means -likely needing **four Linux binaries**: amd64/arm64 × glibc/musl. With an estimated **~5 MB optimized native binary per platform**, the -all-platform packaging footprint can reach roughly **~50 MB** before compression -or packaging refinements. This is manageable for an initial release, but it is a -real packaging design point and should not be treated as an implementation -detail. +all-platform packaging footprint grows with every supported target. This is +manageable for an initial release, but it is a real packaging design point and +should not be treated as an implementation detail. ## 6. Packaging models to evaluate @@ -116,10 +112,9 @@ Two practical models were discussed: A bundle-first hybrid has industry precedent. For example, [`confluent-kafka-go`](https://github.com/confluentinc/confluent-kafka-go/blob/master/README.md#librdkafka) includes prebuilt `librdkafka` binaries for common platforms, requires -`CGO_ENABLED` to remain enabled, and uses a -[`musl` build tag](https://github.com/confluentinc/confluent-kafka-go/blob/master/kafka/README.md#build-tags) -for Alpine. It falls back to a manual dynamic install only when customers need -unsupported platforms or special features such as GSSAPI/Kerberos. +`CGO_ENABLED` to remain enabled, and falls back to a manual dynamic install only +when customers need unsupported platforms or special features such as +GSSAPI/Kerberos. That reference shows a viable market pattern for a Go library backed by native code: **bundle the common path, document unsupported/special paths clearly, and From 0cc2ded54f4897f5811cca2c475d13b11a707dd0 Mon Sep 17 00:00:00 2001 From: ananth7592 Date: Fri, 17 Jul 2026 16:12:07 -0700 Subject: [PATCH 6/8] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- .../go-native-distribution/go-v2-ffi-exploration.md | 1 + 1 file changed, 1 insertion(+) diff --git a/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/go-v2-ffi-exploration.md b/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/go-v2-ffi-exploration.md index 6ab657f9266..d5e07af1b02 100644 --- a/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/go-v2-ffi-exploration.md +++ b/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/go-v2-ffi-exploration.md @@ -1,3 +1,4 @@ + # Go v2 FFI exploration notes > **Status:** Discussion notes for ADR review. The decision is recorded in From 6abaaed6dedb809d9e15b592d3dc04b159cb4a06 Mon Sep 17 00:00:00 2001 From: Ananth Mudumba Date: Fri, 17 Jul 2026 16:14:57 -0700 Subject: [PATCH 7/8] docs(cosmos): scope Go FFI platform matrix Clarify that the Go FFI exploration scopes the initial packaging estimate to the mainstream Windows, macOS, and Linux glibc targets. Linux musl/Alpine is not counted until the packaging plan decides whether it is in scope. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: f7d60272-a96c-48e4-9a85-6e918db6ac26 --- .../go-v2-ffi-exploration.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/go-v2-ffi-exploration.md b/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/go-v2-ffi-exploration.md index d5e07af1b02..db2dd025188 100644 --- a/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/go-v2-ffi-exploration.md +++ b/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/go-v2-ffi-exploration.md @@ -87,8 +87,8 @@ is therefore: That means native Rust driver artifacts must be produced, versioned, selected, and linked for the supported Go OS/architecture matrix. -The fixed platform discussion should start with the mainstream OS/architecture -targets: +This discussion scopes the initial packaging estimate to the mainstream +OS/architecture targets: | OS family | Target combinations discussed | |---|---| @@ -96,10 +96,15 @@ targets: | macOS | ARM64/Apple Silicon, x64/Intel | | Linux glibc | x64/amd64, ARM64 | -With an estimated **~5 MB optimized native binary per platform**, the -all-platform packaging footprint grows with every supported target. This is -manageable for an initial release, but it is a real packaging design point and -should not be treated as an implementation detail. +That is **six firm targets**, or **seven** if Windows x86 is included. Linux +musl/Alpine is intentionally not counted here until the Go packaging plan +decides whether it is in scope for the initial release. + +With an estimated **~5 MB optimized native binary per platform**, this scoped +matrix is roughly **~30-35 MB before compression**. Any additional targets, such +as musl/Alpine, add to that footprint. This is manageable for an initial release, +but it is a real packaging design point and should not be treated as an +implementation detail. ## 6. Packaging models to evaluate From 3d68382ab7d3da886013679ec7d1b1efa0958bad Mon Sep 17 00:00:00 2001 From: Ananth Mudumba Date: Fri, 17 Jul 2026 16:18:59 -0700 Subject: [PATCH 8/8] docs(cosmos): fix Go FFI Kafka reference Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: f7d60272-a96c-48e4-9a85-6e918db6ac26 --- .../go-native-distribution/go-v2-ffi-exploration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/go-v2-ffi-exploration.md b/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/go-v2-ffi-exploration.md index db2dd025188..b2b6f482a6c 100644 --- a/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/go-v2-ffi-exploration.md +++ b/sdk/cosmos/azure_data_cosmos_driver/docs/native-driver-distribution/go-native-distribution/go-v2-ffi-exploration.md @@ -116,7 +116,7 @@ Two practical models were discussed: | **Per-platform native dependency** | Customer obtains only the platform-specific binary they need | Smaller per-customer footprint, but more setup burden and more room for install mistakes | A bundle-first hybrid has industry precedent. For example, -[`confluent-kafka-go`](https://github.com/confluentinc/confluent-kafka-go/blob/master/README.md#librdkafka) +[`confluent-kafka-go`](https://github.com/confluentinc/confluent-kafka-go/blob/master/kafka/README.md#librdkafka) includes prebuilt `librdkafka` binaries for common platforms, requires `CGO_ENABLED` to remain enabled, and falls back to a manual dynamic install only when customers need unsupported platforms or special features such as