Initial C Bindings for Cosmos DB SDK for Rust by analogrelay · Pull Request #3347 · Azure/azure-sdk-for-rust

Ashley Stanton-Nurse (analogrelay) · 2025-11-14T00:21:29Z

This PR introduces C language bindings (FFI) for the azure_data_cosmos Rust SDK, enabling C/C++ applications to interact with Azure Cosmos DB.

Key Changes

New azure_data_cosmos_native Package:

Complete C API with FFI layer exposing core Cosmos DB operations (originally developed by a partner team)
Runtime and call context management for async/sync bridging. The Runtime Context defines the threads on which async operations will run, and the Call Context provides a place for call-specific reporting of error details. This is based on the pattern found in the AMQP package for C++
Comprehensive error handling with optional detailed error information
CRUD operations for databases, containers, and items
Connection string support

C Tests:

Shared test infrastructure (test_common.h) with automatic test discovery
Basic tests of item/container/database CRUD.
Integration with CMake/CTest

Build System:

CMake build configuration with organized output directories
cbindgen integration for automatic header generation
pkg-config file generation for library integration
Cross-platform support (Linux, macOS, Windows)

Closes #3444

github-actions · 2025-11-14T00:34:02Z

API Change Check

APIView identified API level changes in this PR and created the following API reviews

azure_data_cosmos

Copilot

Pull Request Overview

This PR introduces C bindings for the Azure Cosmos DB SDK for Rust, allowing the SDK to be used from C and other languages. Key changes include:

New FFI layer with runtime context, call context, and error handling infrastructure
C bindings for CosmosClient, DatabaseClient, and ContainerClient
Support for CRUD operations, queries, and resource management
Auto-generated C header file (azurecosmos.h)
Comprehensive C test suite covering CRUD operations, error handling, and memory management

Reviewed Changes

Copilot reviewed 22 out of 23 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
`src/string.rs`	String utilities and FFI string conversion helpers
`src/runtime/tokio.rs`	Tokio runtime wrapper for async operations
`src/runtime/mod.rs`	Runtime context FFI functions
`src/options/mod.rs`	Empty option structs for future extensibility
`src/lib.rs`	Main library entry, version function, and tracing setup
`src/error.rs`	Error types, codes, and conversion from Azure SDK errors
`src/context.rs`	Call context for FFI operations and helper macros
`src/clients/mod.rs`	Client module exports
`src/clients/database_client.rs`	Database operations FFI functions
`src/clients/cosmos_client.rs`	Cosmos client creation and database operations
`src/clients/container_client.rs`	Container and item operations FFI functions
`include/azurecosmos.h`	Auto-generated C header file
`c_tests/*.c`	C test suite for FFI functionality
`build.rs`	cbindgen configuration for header generation
`Cargo.toml`	Dependencies and features for native bindings
`CMakeLists.txt`	CMake build configuration for C tests

Comments suppressed due to low confidence (1)

sdk/cosmos/azure_data_cosmos_native/src/string.rs:37

The safe_cstring_new function calls expect() which can panic, but this panic behavior is not documented. Add a # Panics section to the function documentation explaining when this function panics (when the string contains interior NUL bytes).

Ashley Stanton-Nurse (analogrelay) · 2025-12-09T18:38:33Z

/azp run rust - pullrequest

azure-pipelines · 2025-12-09T18:38:50Z

Azure Pipelines successfully started running 1 pipeline(s).

Tomas Varon (tvaron3)

LGTM

Ashley Stanton-Nurse (analogrelay) · 2025-12-19T17:43:46Z

/azp run rust - pullrequest

azure-pipelines · 2025-12-19T17:44:03Z

Azure Pipelines successfully started running 1 pipeline(s).

Ashley Stanton-Nurse (analogrelay) · 2025-12-19T17:44:05Z

Hopefully, a simple rebuild should catch the fixes from #3461 and give us a green build 🤞🏻

Heath Stewart (heaths)

Signing off on Cargo.lock (only non-Cosmos change) and to unblock the PR.

This PR just deletes the `cosmosclient.h` header file, which was the name prior to #3347 . I just forgot to properly delete the old file in that PR.

This PR introduces C language bindings (FFI) for the `azure_data_cosmos` Rust SDK, enabling C/C++ applications to interact with Azure Cosmos DB. ### Key Changes **New `azure_data_cosmos_native` Package:** - Complete C API with FFI layer exposing core Cosmos DB operations (originally developed by a partner team) - Runtime and call context management for async/sync bridging. The Runtime Context defines the threads on which async operations will run, and the Call Context provides a place for call-specific reporting of error details. This is based on the pattern found in the [AMQP package](https://github.com/Azure/azure-sdk-for-cpp/blob/main/sdk/core/azure-core-amqp/src/impl/rust_amqp/rust_amqp/rust_wrapper/src/call_context.rs) for C++ - Comprehensive error handling with optional detailed error information - CRUD operations for databases, containers, and items - Connection string support **C Tests:** - Shared test infrastructure (`test_common.h`) with automatic test discovery - Basic tests of item/container/database CRUD. - Integration with CMake/CTest **Build System:** - CMake build configuration with organized output directories - `cbindgen` integration for automatic header generation - pkg-config file generation for library integration - Cross-platform support (Linux, macOS, Windows) Closes #3444

This PR just deletes the `cosmosclient.h` header file, which was the name prior to #3347 . I just forgot to properly delete the old file in that PR.

…PER_SPEC Blocking fixes: - §6 / §4.7: bind cosmos_driver_execute to execute_singleton_operation, document Result<Option<CosmosResponse>> handling and FEED_EXHAUSTED. - §4.6: remove cosmos_operation_with_partition_key; PK now lives on item / feed factory args (ItemReference::from_name requires PK at construction). - §4.4: add normative driver-cache documentation (endpoint-only key, options dropped on cache hit, credential collision caveat) plus a new COSMOS_ERROR_CODE_OPTIONS_IGNORED_ON_CACHE_HIT advisory. - §3.5 / §6: rewrite error model for azure_data_cosmos::Error from #4442 (Kind enum, typed accessors, predicates, synthetic sub-status codes, non_exhaustive future-proofing via COSMOS_ERROR_KIND_UNKNOWN). - §4.2: fix DriverOptions surface to mirror the actual 3-field type; builder takes account, with_operation_options for per-call defaults; removed allow_emulator_invalid_certs (lives on runtime instead). - §5.2: fix Cargo features (default = tokio + rustls; drop fake reqwest_native_tls / tracing feature; native_tls is the correct name). - §4.6.3: normative execute-consumption contract (sentinel, free always safe, failed execute does not consume, double-execute returns 4005). Recommended fixes: - §4.6.2: split with_precondition into IF_MATCH / IF_NONE_MATCH with a PRECONDITION_ALREADY_SET error to enforce single-precondition rule. - §4.3: document resource-token routing via master-key Secret path; add with_credential mirror. - §4.6.1: add missing factories — read_all_items_cross_partition, query_items, batch, query/read/replace_offer. - §4.3 / §4.5 / §3.4: define cosmos_*_clone functions promised in §3.4. - §5.3: Phase 0 ancillary-tooling re-introduction checklist for entries PR #4103 removed (cbindgen as [build-dependencies] only per heaths, dict files, .cspell.json, verify-dependencies.rs, AGENTS.md, skills). - §3 / §5.1: tighten inheritance attribution between #2906 and #3347. - §7: loosen strict ABI version equality to major-equal / minor->= so the spec's additive-growth promise actually holds. - §2.2: add cbindgen export.rename / item_types policy so the generated header matches the naming table (avoids cosmos_cosmos_* double-prefix and prevents driver-internal types from leaking). Other: - §9: replaced single open question on RuntimeAlreadyInitialized with 9 questions covering implementation parking-lot items (header-visitor borrow vs copy, continuation-token format, multi-part body, C++ companion header, credential identity in cache, ConnectionString parser ownership, symbol stripping, pager continuation-token resume). - §8: updated Phase 0 / 1 / 2 / 3 / 5 / 6 acceptance criteria to match the new contracts (header check-in, error accessor coverage, cache-hit advisory test, error-mapped 404 surfaces as is_not_found). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions Bot added Azure.Core The azure_core crate Cosmos The azure_cosmos crate labels Nov 14, 2025

Ashley Stanton-Nurse (analogrelay) commented Nov 14, 2025

View reviewed changes

Comment thread sdk/core/typespec_client_core/src/http/clients/reqwest.rs Outdated

Ashley Stanton-Nurse (analogrelay) force-pushed the ashleyst/port-c-bindings branch from 4393c1b to aeaba92 Compare November 18, 2025 00:46

Ashley Stanton-Nurse (analogrelay) changed the title ~~[WIP] Initial C Bindings for Cosmos DB SDK for Rust~~ Initial C Bindings for Cosmos DB SDK for Rust Nov 18, 2025

Ashley Stanton-Nurse (analogrelay) marked this pull request as ready for review November 20, 2025 00:03

Ashley Stanton-Nurse (analogrelay) requested a review from a team as a code owner November 20, 2025 00:03

Copilot AI review requested due to automatic review settings November 20, 2025 00:03

Copilot started reviewing on behalf of Ashley Stanton-Nurse (analogrelay) November 20, 2025 00:03 View session

Copilot finished reviewing on behalf of Ashley Stanton-Nurse (analogrelay) November 20, 2025 00:04

Copilot AI reviewed Nov 20, 2025

View reviewed changes

Kevin Pilch (Pilchie) approved these changes Dec 2, 2025

View reviewed changes

Ashley Stanton-Nurse (analogrelay) force-pushed the ashleyst/port-c-bindings branch from 0e06cc1 to d5fa04b Compare December 15, 2025 22:49

Ashley Stanton-Nurse (analogrelay) added 14 commits December 16, 2025 09:51

initial port of c bindings

c15fc31

initial crud c test

118704e

IT WORKS

0343eae

remove unnecessary changes to error

d6a85ed

cbindgen fixes

b015d13

introduce runtime/call context

fa3b8a9

more c tests

423817b

remove debugging code

615ebc0

options types and tracing

3a9b61d

license headers

af32c7a

fix clippy lints

e248c21

remove old blocking implementation

eaf62b2

fix doc comment

538632a

stop modifying the build identifier comment every build

9dddcad

Ashley Stanton-Nurse (analogrelay) and others added 4 commits December 16, 2025 09:52

fix doc comment errors

18373dc

me spell pretty one day

1817a4d

fix copilot suggestions

8d4e324

test improvements and pkg-config

0c28da3

Ashley Stanton-Nurse (analogrelay) force-pushed the ashleyst/port-c-bindings branch from d5fa04b to 0c28da3 Compare December 16, 2025 21:16

Ashley Stanton-Nurse (analogrelay) requested review from Larry Osterman (LarryOsterman), Rick Winter (RickWinter), Heath Stewart (heaths) and Ronnie Geraghty (ronniegeraghty) as code owners December 16, 2025 21:16

Ashley Stanton-Nurse (analogrelay) added 3 commits December 16, 2025 13:17

undo changes to vscode workspace settings

d069490

windows fixes

96f7477

wasm and msrv fixes

52e4fed

Tomas Varon (tvaron3) reviewed Dec 17, 2025

View reviewed changes

Comment thread sdk/cosmos/azure_data_cosmos_native/include/azurecosmos.h

Tomas Varon (tvaron3) approved these changes Dec 17, 2025

View reviewed changes

Ashley Stanton-Nurse (analogrelay) added 3 commits December 17, 2025 15:00

fix wasm warnings

d4c82f5

fix tyop

b94a7a7

me spell good

bf5c695

Kevin Pilch (Pilchie) approved these changes Dec 18, 2025

View reviewed changes

fix broken link in README.md

c68b6e4

Heath Stewart (heaths) approved these changes Jan 7, 2026

View reviewed changes

Ashley Stanton-Nurse (analogrelay) merged commit 583455e into Azure:main Jan 8, 2026
17 checks passed

Ashley Stanton-Nurse (analogrelay) mentioned this pull request Jan 8, 2026

cosmos: remove extraneous C bindings header #3499

Merged

Debdatta Kunda (kundadebdatta) mentioned this pull request May 26, 2026

[Cosmos][Native Wrapper] Phase 1 — Error + context primitives #4468

Closed

6 tasks

Navigation Menu

Uh oh!

Initial C Bindings for Cosmos DB SDK for Rust - #3347

Initial C Bindings for Cosmos DB SDK for Rust#3347
Ashley Stanton-Nurse (analogrelay) merged 30 commits into
Azure:mainfrom
analogrelay:ashleyst/port-c-bindings

Ashley Stanton-Nurse (analogrelay) commented Nov 14, 2025 •

edited

Loading

Uh oh!

github-actions Bot commented Nov 14, 2025 •

edited

Loading

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Ashley Stanton-Nurse (analogrelay) commented Dec 9, 2025

Uh oh!

azure-pipelines Bot commented Dec 9, 2025

Uh oh!

Uh oh!

Tomas Varon (tvaron3) left a comment

Uh oh!

Ashley Stanton-Nurse (analogrelay) commented Dec 19, 2025

Uh oh!

azure-pipelines Bot commented Dec 19, 2025

Uh oh!

Ashley Stanton-Nurse (analogrelay) commented Dec 19, 2025

Uh oh!

Heath Stewart (heaths) left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Conversation

Ashley Stanton-Nurse (analogrelay) commented Nov 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Key Changes

Uh oh!

github-actions Bot commented Nov 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

API Change Check

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Ashley Stanton-Nurse (analogrelay) commented Dec 9, 2025

Uh oh!

azure-pipelines Bot commented Dec 9, 2025

Uh oh!

Uh oh!

Tomas Varon (tvaron3) left a comment

Choose a reason for hiding this comment

Uh oh!

Ashley Stanton-Nurse (analogrelay) commented Dec 19, 2025

Uh oh!

azure-pipelines Bot commented Dec 19, 2025

Uh oh!

Ashley Stanton-Nurse (analogrelay) commented Dec 19, 2025

Uh oh!

Heath Stewart (heaths) left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Ashley Stanton-Nurse (analogrelay) commented Nov 14, 2025 •

edited

Loading

github-actions Bot commented Nov 14, 2025 •

edited

Loading