cosmos: add experimental c wrapper around cosmos sdk (#2906)

analogrelay · web-flow · commit de5bf3ba8951 · 2025-10-20T17:29:44.000Z
We want to explore the option of publishing a C library of the Azure
Cosmos DB SDK for Rust. This PR adds the basic framework to start that
effort:

* A new package `cosmosclient` that depends on `azure_data_cosmos`. This
package builds a `cdylib` and `staticlib` target
(`libcosmosclient.a`/`libcosmosclient.so`/`cosmosclient.dll`/etc.) that
exports a C-compatible API. For now, that API is extremely simple
(`cosmosclient_version`).
* A simple test infrastructure (NOT currently integrated into anything).
There are C programs in `sdk/cosmos/cosmosclient/c_tests` that will be
built and linked against the cosmosclient library. The tests are simple
pass/fail programs. If the test returns a `0` exit code, it passed,
otherwise, it failed.
* `build.rs` script in `cosmosclient` to produce
`sdk/cosmos/cosmosclient/include/cosmosclient.h`, which is a C header
file defining the API surface of `cosmosclient`. We should publish this
as an artifact at some point, but for now it's there to be used by
tests.
diff --git a/.vscode/cspell.json b/.vscode/cspell.json
@@ -234,4 +234,4 @@
       ]
     }
   ]
-}
+}
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -13,6 +13,7 @@ members = [
   "sdk/core/azure_core_test_macros",
   "sdk/core/azure_core_opentelemetry",
   "sdk/cosmos/azure_data_cosmos",
+  "sdk/cosmos/azure_data_cosmos_native",
   "sdk/identity/azure_identity",
   "sdk/eventhubs/azure_messaging_eventhubs",
   "sdk/eventhubs/azure_messaging_eventhubs_checkpointstore_blob",
diff --git a/deny.toml b/deny.toml
@@ -13,6 +13,7 @@ allow = [
   "BSL-1.0",
   "ISC",
   "MIT",
+  "MPL-2.0",
   # "OpenSSL",
   "Unicode-3.0",
   "Zlib",
diff --git a/eng/dict/crates.txt b/eng/dict/crates.txt
@@ -16,8 +16,9 @@ azure_messaging_eventhubs
 azure_security_keyvault_keys
 azure_security_keyvault_secrets
 azure_storage_blob
-azure_canary
-azure_canary_core
+azure_storage_common
+azure_template
+azure_template_core
 base64
 bytes
 cargo_metadata
diff --git a/eng/dict/rust-custom.txt b/eng/dict/rust-custom.txt
@@ -12,3 +12,7 @@ rustflags
 rustls
 rustsec
 turbofish
+dylib
+cdylib
+staticlib
+cbindgen
diff --git a/sdk/cosmos/.dict.txt b/sdk/cosmos/.dict.txt
@@ -8,3 +8,7 @@ udfs
 
 # Cosmos' docs all use "Autoscale" as a single word, rather than a compound "AutoScale" or "Auto Scale"
 autoscale
+
+# Words used within the Cosmos Native Client (azure_data_cosmos_native)
+azurecosmos
+cosmosclient
diff --git a/sdk/cosmos/azure_data_cosmos/Cargo.toml b/sdk/cosmos/azure_data_cosmos/Cargo.toml
@@ -43,4 +43,9 @@ hmac_rust = ["azure_core/hmac_rust"]
 hmac_openssl = ["azure_core/hmac_openssl"]
 
 [package.metadata.docs.rs]
-features = ["key_auth"]
+features = [
+  "key_auth",
+  "preview_query_engine",
+  "hmac_rust",
+  "hmac_openssl",
+]
diff --git a/sdk/cosmos/azure_data_cosmos_native/.gitignore b/sdk/cosmos/azure_data_cosmos_native/.gitignore
@@ -0,0 +1 @@
+build/
diff --git a/sdk/cosmos/azure_data_cosmos_native/CMakeLists.txt b/sdk/cosmos/azure_data_cosmos_native/CMakeLists.txt
@@ -0,0 +1,33 @@
+# cSpell:ignore cosmosctest CRATETYPES endforeach
+
+project(cosmosctest C)
+cmake_minimum_required(VERSION 4.1)
+
+# CMake automatically uses this option, but we should define it.
+option(BUILD_SHARED_LIBS "Build using shared libraries" ON)
+
+include(FetchContent)
+include(CTest)
+
+FetchContent_Declare(
+    Corrosion
+    GIT_REPOSITORY https://github.com/corrosion-rs/corrosion.git
+    GIT_TAG v0.5.2
+)
+FetchContent_MakeAvailable(Corrosion)
+
+corrosion_import_crate(
+    MANIFEST_PATH ./Cargo.toml
+    CRATETYPES staticlib cdylib
+)
+
+set(TEST_FILES
+    ./c_tests/version.c)
+
+foreach(test_file ${TEST_FILES})
+    get_filename_component(test_name ${test_file} NAME_WE)
+    add_executable(${test_name} ${test_file})
+    target_link_libraries(${test_name} PRIVATE azurecosmos)
+    add_test(${test_name} ${test_name})
+endforeach()
+
diff --git a/sdk/cosmos/azure_data_cosmos_native/Cargo.toml b/sdk/cosmos/azure_data_cosmos_native/Cargo.toml
@@ -0,0 +1,23 @@
+[package]
+name = "azure_data_cosmos_native"
+publish = false
+description = "The Cosmos Native Client is a C library, written in Rust but exporting a C-compatible API, that provides a full SDK for Azure Cosmos DB."
+version = "0.27.0"
+authors.workspace = true
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+
+[lib]
+name = "azurecosmos"
+crate-type = ["cdylib", "staticlib"]
+
+[dependencies]
+azure_data_cosmos = { path = "../azure_data_cosmos" }
+
+[build-dependencies]
+cbindgen = "0.29.0"
+
+[lints]
+workspace = true
diff --git a/sdk/cosmos/azure_data_cosmos_native/build.rs b/sdk/cosmos/azure_data_cosmos_native/build.rs
@@ -0,0 +1,44 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+// cSpell:ignore SOURCEVERSION, SOURCEBRANCH, BUILDID, BUILDNUMBER, COSMOSCLIENT, cosmosclient, libcosmosclient, cbindgen
+
+fn main() {
+    let build_id = format!(
+        "$Id: {}, Version: {}, Commit: {}, Branch: {}, Build ID: {}, Build Number: {}, Timestamp: {}$",
+        env!("CARGO_PKG_NAME"),
+        env!("CARGO_PKG_VERSION"),
+        option_env!("BUILD_SOURCEVERSION").unwrap_or("unknown"),
+        option_env!("BUILD_SOURCEBRANCH").unwrap_or("unknown"),
+        option_env!("BUILD_BUILDID").unwrap_or("unknown"),
+        option_env!("BUILD_BUILDNUMBER").unwrap_or("unknown"),
+        std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap_or_default()
+            .as_secs(),
+    );
+    println!("cargo:rustc-env=BUILD_IDENTIFIER={}", build_id);
+
+    let mut header: String = r"// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+// This file is auto-generated by cbindgen. Do not edit manually.
+// cSpell: disable
+"
+    .to_string();
+    header.push_str(&format!("// Build identifier: {}\n", build_id));
+
+    let crate_dir = std::env::var("CARGO_MANIFEST_DIR").unwrap();
+    cbindgen::Builder::new()
+        .with_crate(crate_dir)
+        .with_language(cbindgen::Language::C)
+        .with_after_include(format!(
+            "\n// Specifies the version of cosmosclient this header file was generated from.\n// This should match the version of libcosmosclient you are referencing.\n#define COSMOSCLIENT_H_VERSION \"{}\"",
+            env!("CARGO_PKG_VERSION")
+        ))
+        .with_cpp_compat(true)
+        .with_header(header)
+        .generate()
+        .expect("unable to generate bindings")
+        .write_to_file("include/cosmosclient.h");
+}
diff --git a/sdk/cosmos/azure_data_cosmos_native/c_tests/README.md b/sdk/cosmos/azure_data_cosmos_native/c_tests/README.md
@@ -0,0 +1,44 @@
+# Cosmos Client C Tests
+
+This directory contains tests written in C that utilize the Cosmos Client library. The tests are designed to validate the functionality of the Cosmos Client C API, ensuring that it correctly interacts with the Azure CosmosDB service.
+
+Building this directory requires CMake, Rust, and a C compiler.
+
+## Running the tests
+
+To run the tests, follow these steps:
+
+1. Create a `build` directory:
+
+```bash
+mkdir build
+cd build
+```
+
+1. Configure the project with CMake:
+
+```bash
+cmake ..
+```
+
+1. Run the build AND tests:
+
+```bash
+make && make test
+```
+
+## Test Structure
+
+Each test is a separate C program located in the `c_tests` directory.
+The tests are compiled into executables that can be run independently.
+Tests must be manually listed in `CMakeLists.txt` to be included in the build process:
+
+```cmake
+set(TEST_FILES
+    ./c_tests/version.c
+    ./c_tests/your_test_here.c)
+```
+
+Once a test is present in the `TEST_FILES` list, it will be automatically compiled and linked against the Cosmos Client library (either static, or dynamic, depending on the value of `BUILD_SHARED_LIBS` when `cmake` is run, which defaults to `ON`).
+
+Helper code should be added to an include file in the `c_tests` directory, such as `c_tests/test_helpers.h`, and included in the test files as needed.
diff --git a/sdk/cosmos/azure_data_cosmos_native/c_tests/version.c b/sdk/cosmos/azure_data_cosmos_native/c_tests/version.c
@@ -0,0 +1,20 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+#include <stdio.h>
+#include <string.h>
+#include "../include/cosmosclient.h"
+
+int main() {
+    const char *version = cosmosclient_version();
+    const char *header_version = COSMOSCLIENT_H_VERSION;
+    printf("Cosmos Client Version: %s\n", version);
+    printf("Header Version: %s\n", header_version);
+    if (!strcmp(version, header_version)) {
+        printf("Version match successful.\n");
+        return 0;
+    } else {
+        printf("Version mismatch: %s != %s\n", version, header_version);
+        return 1;
+    }
+}
diff --git a/sdk/cosmos/azure_data_cosmos_native/include/.gitignore b/sdk/cosmos/azure_data_cosmos_native/include/.gitignore
@@ -0,0 +1,3 @@
+# Ignore everything except this ignore file, this directory contains build artifacts
+*
+!.gitignore
diff --git a/sdk/cosmos/azure_data_cosmos_native/src/lib.rs b/sdk/cosmos/azure_data_cosmos_native/src/lib.rs
@@ -0,0 +1,19 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+use std::ffi::{c_char, CStr};
+
+#[macro_use]
+mod macros;
+
+/// cbindgen:ignore
+#[no_mangle] // Necessary to prevent the compiler from stripping it when optimizing
+pub static BUILD_IDENTIFIER: &CStr = c_str!(env!("BUILD_IDENTIFIER"));
+
+const VERSION: &CStr = c_str!(env!("CARGO_PKG_VERSION"));
+
+/// Returns a constant C string containing the version of the Cosmos Client library.
+#[no_mangle]
+pub extern "C" fn cosmosclient_version() -> *const c_char {
+    VERSION.as_ptr()
+}
diff --git a/sdk/cosmos/azure_data_cosmos_native/src/macros.rs b/sdk/cosmos/azure_data_cosmos_native/src/macros.rs
@@ -0,0 +1,26 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+macro_rules! c_str {
+    ($s:expr) => {
+        const {
+            // This does a few funky things to make sure we can stay in a const context
+            // Which ensures the string is generated as a c-str at compile time
+            const STR: &str = $s;
+            const BYTES: [u8; STR.len() + 1] = const {
+                let mut cstr_buf: [u8; STR.len() + 1] = [0; STR.len() + 1];
+                let mut i = 0;
+                // For loops over ranges don't work in const contexts yet.
+                while i < STR.len() {
+                    cstr_buf[i] = STR.as_bytes()[i];
+                    i += 1;
+                }
+                cstr_buf
+            };
+            match CStr::from_bytes_with_nul(&BYTES) {
+                Ok(cstr) => cstr,
+                Err(_) => panic!("failed to convert value to C string"),
+            }
+        }
+    };
+}

Original file line number	Diff line number	Diff line change
`@@ -234,4 +234,4 @@`
`234`	`234`	`]`
`235`	`235`	`}`
`236`	`236`	`]`
`237`		`-}`
	`237`	`+}`