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.lockindex 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.tomlindex 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.tomlnew file mode 100644index 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 = truediff --git a/crates/switchyard-ffi/README.md b/crates/switchyard-ffi/README.mdnew file mode 100644index 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.hnew file mode 100644index 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);++#endifdiff --git a/crates/switchyard-ffi/src/lib.rs b/crates/switchyard-ffi/src/lib.rsnew file mode 100644index 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.rsnew file mode 100644index 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");+}