Skip to content

Switchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.

Rust

feat(ffi): expose request and response translation (#1076)

Alex Fournier56c538e2427c
diff --git a/Cargo.lock b/Cargo.lock
index 7f3c9fd98..e7f816931 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -5411,6 +5411,16 @@ dependencies = [
"windows-sys 0.61.2",
]
+[[package]]
+name = "switchyard-ffi"
+version = "0.3.0"
+dependencies = [
+ "serde",
+ "serde_json",
+ "switchyard-protocol",
+ "switchyard-translation",
+]
+
[[package]]
name = "switchyard-libsy"
version = "0.3.0"
diff --git a/Cargo.toml b/Cargo.toml
index bd81b1cd9..f2ca080b8 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -11,6 +11,7 @@ members = [
"crates/prefill-router",
"crates/switchyard-py",
"crates/switchyard-node",
+ "crates/switchyard-ffi",
"crates/protocol",
"crates/switchyard-nemo-relay-plugin",
"crates/switchyard-runner",
diff --git a/crates/switchyard-ffi/Cargo.toml b/crates/switchyard-ffi/Cargo.toml
new file mode 100644
index 000000000..c113438ed
--- /dev/null
+++ b/crates/switchyard-ffi/Cargo.toml
@@ -0,0 +1,19 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+[package]
+name = "switchyard-ffi"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+rust-version.workspace = true
+publish = false
+
+[lib]
+crate-type = ["cdylib", "staticlib"]
+
+[dependencies]
+serde.workspace = true
+serde_json.workspace = true
+switchyard-protocol.workspace = true
+switchyard-translation.workspace = true
diff --git a/crates/switchyard-ffi/README.md b/crates/switchyard-ffi/README.md
new file mode 100644
index 000000000..4b1ec9866
--- /dev/null
+++ b/crates/switchyard-ffi/README.md
@@ -0,0 +1,21 @@
+# C translation interface
+
+An experimental C interface to Switchyard's request and response codecs. The
+interface uses NUL-terminated JSON strings. Ownership rules are in
+[`include/switchyard.h`](include/switchyard.h).
+
+## JSON payloads
+
+| Function | Input |
+| --- | --- |
+| `sy_decode_request`, `sy_decode_response` | `{format, body}` |
+| `sy_encode_request` | `{format, request, model}` |
+
+`request` and model responses use Switchyard's normalized protocol JSON.
+`sy_encode_request` applies the selected model before encoding the request.
+
+Wire formats are `openai_chat`, `openai_responses`, and `anthropic_messages`.
+The translation functions use the existing Switchyard codecs.
+
+Fallible calls return NULL on success or an owned error string. Free every
+returned error or JSON string with `sy_string_free`.
diff --git a/crates/switchyard-ffi/include/switchyard.h b/crates/switchyard-ffi/include/switchyard.h
new file mode 100644
index 000000000..ded662702
--- /dev/null
+++ b/crates/switchyard-ffi/include/switchyard.h
@@ -0,0 +1,22 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+#ifndef SWITCHYARD_H
+#define SWITCHYARD_H
+
+#include <stdint.h>
+
+// Compatibility generation for C signatures and JSON payloads.
+#define SY_ABI_VERSION 1
+uint32_t sy_abi_version(void);
+
+// Fallible calls return NULL on success or an owned error string.
+// JSON inputs are borrowed for the call and must be NUL-terminated.
+// Free all output strings with sy_string_free.
+char *sy_decode_request(const char *input_json, char **out_json);
+char *sy_encode_request(const char *input_json, char **out_json);
+char *sy_decode_response(const char *input_json, char **out_json);
+
+void sy_string_free(char *string);
+
+#endif
diff --git a/crates/switchyard-ffi/src/lib.rs b/crates/switchyard-ffi/src/lib.rs
new file mode 100644
index 000000000..2a0c73a09
--- /dev/null
+++ b/crates/switchyard-ffi/src/lib.rs
@@ -0,0 +1,139 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+//! C bridge to Switchyard's request and response codecs.
+
+use std::ffi::{CStr, CString, c_char};
+use std::panic::{AssertUnwindSafe, catch_unwind};
+
+use serde::{Deserialize, Serialize};
+use switchyard_protocol::{LlmRequest, ModelId, WireFormat};
+
+type Result<T> = std::result::Result<T, Box<dyn std::error::Error>>;
+
+/// Returns the compatibility generation for C signatures and JSON payloads.
+#[unsafe(no_mangle)]
+pub extern "C" fn sy_abi_version() -> u32 {
+ 1
+}
+
+#[derive(Deserialize)]
+struct DecodeInput {
+ format: WireFormat,
+ body: serde_json::Value,
+}
+
+#[derive(Deserialize)]
+struct EncodeInput {
+ format: WireFormat,
+ request: LlmRequest,
+ model: ModelId,
+}
+
+fn error_string(message: String) -> *mut c_char {
+ match CString::new(message) {
+ Ok(message) => message.into_raw(),
+ Err(_) => c"Switchyard error contained a NUL byte"
+ .to_owned()
+ .into_raw(),
+ }
+}
+
+// Keep Rust panics and errors inside the C boundary.
+fn ffi_call(work: impl FnOnce() -> Result<()>) -> *mut c_char {
+ match catch_unwind(AssertUnwindSafe(work)) {
+ Ok(Ok(())) => std::ptr::null_mut(),
+ Ok(Err(error)) => error_string(error.to_string()),
+ Err(_) => error_string("Switchyard binding panicked".to_string()),
+ }
+}
+
+// The input must be NUL-terminated; parsed values do not borrow it.
+unsafe fn parse_json_input<T: serde::de::DeserializeOwned>(input: *const c_char) -> Result<T> {
+ if input.is_null() {
+ return Err("missing JSON input".into());
+ }
+ let input = unsafe { CStr::from_ptr(input) };
+ Ok(serde_json::from_slice(input.to_bytes())?)
+}
+
+fn encode_json(output: &impl Serialize) -> Result<CString> {
+ Ok(CString::new(serde_json::to_vec(output)?)?)
+}
+
+/// Decodes provider JSON into a normalized request.
+/// # Safety
+/// JSON must be NUL-terminated and `out_json` writable. Free the output with `sy_string_free`.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn sy_decode_request(
+ input_json: *const c_char,
+ out_json: *mut *mut c_char,
+) -> *mut c_char {
+ ffi_call(|| {
+ let out = unsafe { out_json.as_mut() }.ok_or("missing request output")?;
+ *out = std::ptr::null_mut();
+ let input: DecodeInput = unsafe { parse_json_input(input_json) }?;
+ *out = encode_json(&switchyard_translation::decode_request(
+ input.format,
+ &input.body,
+ )?)?
+ .into_raw();
+ Ok(())
+ })
+}
+
+/// Applies the selected model and encodes the request.
+/// # Safety
+/// JSON must be NUL-terminated and `out_json` writable. Free the output with `sy_string_free`.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn sy_encode_request(
+ input_json: *const c_char,
+ out_json: *mut *mut c_char,
+) -> *mut c_char {
+ ffi_call(|| {
+ let out = unsafe { out_json.as_mut() }.ok_or("missing request output")?;
+ *out = std::ptr::null_mut();
+ let mut input: EncodeInput = unsafe { parse_json_input(input_json) }?;
+ switchyard_translation::prepare_request_for_target(&mut input.request, &input.model, None);
+ *out = encode_json(&switchyard_translation::encode_request(
+ &input.request,
+ input.format,
+ )?)?
+ .into_raw();
+ Ok(())
+ })
+}
+
+/// Decodes a buffered provider response.
+/// # Safety
+/// JSON must be NUL-terminated and `out_json` writable. Free the output with `sy_string_free`.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn sy_decode_response(
+ input_json: *const c_char,
+ out_json: *mut *mut c_char,
+) -> *mut c_char {
+ ffi_call(|| {
+ let out = unsafe { out_json.as_mut() }.ok_or("missing response output")?;
+ *out = std::ptr::null_mut();
+ let input: DecodeInput = unsafe { parse_json_input(input_json) }?;
+ *out = encode_json(&switchyard_translation::decode_aggregated_response(
+ &input.body,
+ input.format,
+ )?)?
+ .into_raw();
+ Ok(())
+ })
+}
+
+/// Frees a library-owned error or JSON string.
+/// # Safety
+/// Pass a returned string once, with no remaining readers, or NULL.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn sy_string_free(string: *mut c_char) {
+ if !string.is_null() {
+ drop(unsafe { CString::from_raw(string) });
+ }
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/switchyard-ffi/src/tests.rs b/crates/switchyard-ffi/src/tests.rs
new file mode 100644
index 000000000..29ec3f397
--- /dev/null
+++ b/crates/switchyard-ffi/src/tests.rs
@@ -0,0 +1,78 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+//! Unit tests for the C bridge.
+
+use super::*;
+use serde_json::{Value, json};
+
+// ABI generations are independent of package releases.
+#[test]
+fn abi_version_identifies_v1_contract() {
+ assert_eq!(sy_abi_version(), 1);
+}
+
+// Success is NULL; errors and panics produce strings owned by the caller.
+#[test]
+fn ffi_call_contains_errors_and_panics() {
+ assert!(ffi_call(|| Ok(())).is_null());
+ for (error, expected) in [
+ (ffi_call(|| Err("test error".into())), "test error"),
+ (
+ ffi_call(|| panic!("test panic")),
+ "Switchyard binding panicked",
+ ),
+ ] {
+ assert!(!error.is_null());
+ let message = unsafe { CStr::from_ptr(error) }.to_str().unwrap();
+ assert_eq!(message, expected);
+ unsafe { sy_string_free(error) };
+ }
+}
+
+fn check(error: *mut c_char) {
+ if !error.is_null() {
+ panic!("{}", unsafe { CString::from_raw(error) }.to_string_lossy());
+ }
+}
+
+fn translated(
+ call: unsafe extern "C" fn(*const c_char, *mut *mut c_char) -> *mut c_char,
+ input: Value,
+) -> Value {
+ let input = CString::new(input.to_string()).unwrap();
+ let mut output = std::ptr::null_mut();
+ check(unsafe { call(input.as_ptr(), &mut output) });
+ assert!(!output.is_null());
+ let result = serde_json::from_slice(unsafe { CStr::from_ptr(output) }.to_bytes());
+ unsafe { sy_string_free(output) };
+ result.unwrap()
+}
+
+// Translation exports return owned JSON strings that the caller releases through the ABI.
+#[test]
+fn translation_exports_return_owned_json() {
+ let request = translated(
+ sy_decode_request,
+ json!({
+ "format": "openai_chat",
+ "body": {"model": "route", "messages": [{"role": "user", "content": "hello"}]},
+ }),
+ );
+ assert_eq!(request["messages"][0]["content"][0]["text"], "hello");
+ let encoded = translated(
+ sy_encode_request,
+ json!({
+ "format": "openai_chat", "request": request, "model": "selected",
+ }),
+ );
+ assert_eq!(encoded["model"], "selected");
+ let response = translated(
+ sy_decode_response,
+ json!({
+ "format": "openai_chat",
+ "body": {"choices": [{"index": 0, "message": {"role": "assistant", "content": "hello"}, "finish_reason": "stop"}]},
+ }),
+ );
+ assert_eq!(response["outputs"][0]["content"][0]["text"], "hello");
+}