use super::BindingValue;
use serde::{Deserialize, Serialize};
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
#[cfg_attr(feature = "jsonschema", derive(schemars::JsonSchema))]
#[serde(tag = "service", rename_all = "lowercase")]
pub enum AiBinding {
Bedrock(BedrockAiBinding),
Vertex(VertexAiBinding),
Foundry(FoundryAiBinding),
#[serde(rename = "external-ai")]
External(ExternalAiBinding),
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
#[cfg_attr(feature = "jsonschema", derive(schemars::JsonSchema))]
#[serde(rename_all = "camelCase")]
pub struct BedrockAiBinding {
#[serde(deserialize_with = "deserialize_aws_region")]
pub region: String,
}
impl BedrockAiBinding {
pub fn new(region: impl Into<String>) -> Result<Self, String> {
let region = region.into();
validate_aws_region(®ion)?;
Ok(Self { region })
}
}
pub fn validate_aws_region(region: &str) -> Result<(), String> {
let invalid = || {
format!(
"invalid AWS region {region:?}: expected a region name such as \"us-east-1\" \
(lowercase letters, digits and single dashes only)"
)
};
if region.len() > 30 {
return Err(invalid());
}
let parts: Vec<&str> = region.split('-').collect();
let [geography, middle @ .., number] = parts.as_slice() else {
return Err(invalid());
};
let lowercase = |s: &str| !s.is_empty() && s.bytes().all(|b| b.is_ascii_lowercase());
let valid = geography.len() == 2
&& lowercase(geography)
&& !middle.is_empty()
&& middle.iter().all(|m| lowercase(m))
&& !number.is_empty()
&& number.len() <= 2
&& number.bytes().all(|b| b.is_ascii_digit());
if valid {
Ok(())
} else {
Err(invalid())
}
}
fn deserialize_aws_region<'de, D: serde::Deserializer<'de>>(
deserializer: D,
) -> Result<String, D::Error> {
let region = String::deserialize(deserializer)?;
validate_aws_region(®ion).map_err(serde::de::Error::custom)?;
Ok(region)
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
#[cfg_attr(feature = "jsonschema", derive(schemars::JsonSchema))]
#[serde(rename_all = "camelCase")]
pub struct VertexAiBinding {
pub project: String,
pub location: String,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
#[cfg_attr(feature = "jsonschema", derive(schemars::JsonSchema))]
#[serde(rename_all = "camelCase")]
pub struct FoundryAiBinding {
pub endpoint: String,
pub account: String,
}
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
#[cfg_attr(feature = "jsonschema", derive(schemars::JsonSchema))]
#[serde(rename_all = "camelCase")]
pub struct ExternalAiBinding {
pub provider: String,
pub api_key: BindingValue<String>,
}
impl std::fmt::Debug for ExternalAiBinding {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("ExternalAiBinding")
.field("provider", &self.provider)
.field("api_key", &"<redacted>")
.finish()
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
#[cfg_attr(feature = "jsonschema", derive(schemars::JsonSchema))]
#[serde(untagged)]
pub enum ExternalAi {
Ambient(AmbientAiBinding),
ApiKey(ExternalAiBinding),
}
impl<'de> Deserialize<'de> for ExternalAi {
fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
use serde::de::Error;
const FORMS: &str = "expected either {\"service\": \"bedrock\", \"region\": \"<region>\"} \
(the pod's cloud identity, no key) or {\"provider\": \"<name>\", \"apiKey\": \"<key>\"} (your own key)";
let value = serde_json::Value::deserialize(deserializer)?;
let Some(object) = value.as_object() else {
return Err(D::Error::custom(format!(
"invalid external AI binding: {FORMS}"
)));
};
let service = object.get("service").and_then(|v| v.as_str());
if object.contains_key("service") && service != Some("external-ai") {
if let Some(extra) = object.keys().find(|k| *k != "service" && *k != "region") {
return Err(D::Error::custom(format!(
"invalid external AI binding: field `{extra}` is not allowed with `service` \
(it uses the workload's cloud identity and takes only `region`); {FORMS}"
)));
}
serde_json::from_value(value)
.map(Self::Ambient)
.map_err(|e| D::Error::custom(format!("invalid external AI binding: {e}; {FORMS}")))
} else {
serde_json::from_value(value)
.map(Self::ApiKey)
.map_err(|e| D::Error::custom(format!("invalid external AI binding: {e}; {FORMS}")))
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
#[cfg_attr(feature = "jsonschema", derive(schemars::JsonSchema))]
#[serde(tag = "service", rename_all = "lowercase")]
pub enum AmbientAiBinding {
Bedrock(BedrockAiBinding),
}
impl From<ExternalAiBinding> for ExternalAi {
fn from(binding: ExternalAiBinding) -> Self {
Self::ApiKey(binding)
}
}
impl ExternalAi {
pub fn to_ai_binding(&self) -> AiBinding {
match self {
Self::Ambient(AmbientAiBinding::Bedrock(b)) => AiBinding::Bedrock(b.clone()),
Self::ApiKey(b) => AiBinding::External(b.clone()),
}
}
}
impl AiBinding {
pub const LOCAL_API_KEY_ENV: &'static str = "OPENAI_API_KEY";
pub const LOCAL_DEFAULT_PROVIDER: &'static str = "openai";
pub fn bedrock(region: impl Into<String>) -> Self {
Self::Bedrock(BedrockAiBinding {
region: region.into(),
})
}
pub fn vertex(project: impl Into<String>, location: impl Into<String>) -> Self {
Self::Vertex(VertexAiBinding {
project: project.into(),
location: location.into(),
})
}
pub fn foundry(endpoint: impl Into<String>, account: impl Into<String>) -> Self {
Self::Foundry(FoundryAiBinding {
endpoint: endpoint.into(),
account: account.into(),
})
}
pub fn external(provider: impl Into<String>, api_key: impl Into<BindingValue<String>>) -> Self {
Self::External(ExternalAiBinding {
provider: provider.into(),
api_key: api_key.into(),
})
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_bedrock_binding_roundtrip() {
let binding = AiBinding::bedrock("us-east-1");
let json = serde_json::to_string(&binding).unwrap();
assert!(json.contains(r#""service":"bedrock""#));
let deserialized: AiBinding = serde_json::from_str(&json).unwrap();
assert_eq!(binding, deserialized);
}
#[test]
fn test_vertex_binding_roundtrip() {
let binding = AiBinding::vertex("my-project", "us-central1");
let json = serde_json::to_string(&binding).unwrap();
assert!(json.contains(r#""service":"vertex""#));
let deserialized: AiBinding = serde_json::from_str(&json).unwrap();
assert_eq!(binding, deserialized);
}
#[test]
fn test_foundry_binding_roundtrip() {
let binding = AiBinding::foundry("https://my-foundry.openai.azure.com", "my-subscription");
let json = serde_json::to_value(&binding).unwrap();
let json_str = json.to_string();
assert!(json_str.contains(r#""service":"foundry""#));
assert!(
!json_str.contains("instantAccess"),
"foundry binding must not serialize instant_access"
);
let deserialized: AiBinding = serde_json::from_value(json).unwrap();
assert_eq!(binding, deserialized);
}
#[test]
fn test_external_binding_roundtrip() {
let binding = AiBinding::external("openai", "sk-test-key");
let json = serde_json::to_value(&binding).unwrap();
let json_str = json.to_string();
assert!(
json_str.contains(r#""apiKey""#),
"external binding must serialize apiKey in camelCase"
);
assert_eq!(
json,
serde_json::json!({
"service": "external-ai",
"provider": "openai",
"apiKey": "sk-test-key",
})
);
let deserialized: AiBinding =
serde_json::from_value(json).expect("external binding should round-trip");
assert_eq!(binding, deserialized);
}
#[test]
fn external_ai_with_the_external_ai_service_tag_still_parses_as_a_key() {
let parsed: ExternalAi = serde_json::from_value(serde_json::json!({
"service": "external-ai", "provider": "openai", "apiKey": "sk-x"
}))
.expect("the tagged BYO-key input parsed before and must keep parsing");
assert!(matches!(&parsed, ExternalAi::ApiKey(b) if b.provider == "openai"));
let binding: crate::ExternalBinding = serde_json::from_value(serde_json::json!({
"type": "ai", "service": "external-ai", "provider": "openai", "apiKey": "sk-x"
}))
.unwrap();
assert_eq!(
binding.to_env_binding_value().unwrap(),
serde_json::json!({"service": "external-ai", "provider": "openai", "apiKey": "sk-x"})
);
let err = serde_json::from_value::<ExternalAi>(
serde_json::json!({"service": "external-ai", "provider": "openai"}),
)
.unwrap_err()
.to_string();
assert!(err.contains("invalid external AI binding"), "{err}");
}
#[test]
fn bedrock_region_must_be_a_plain_aws_region() {
for ok in [
"us-east-1",
"eu-central-2",
"ap-southeast-4",
"us-gov-west-1",
"us-iso-east-1",
"cn-north-1",
] {
let binding: BedrockAiBinding =
serde_json::from_value(serde_json::json!({ "region": ok }))
.unwrap_or_else(|e| panic!("{ok} must parse: {e}"));
assert_eq!(binding.region, ok);
assert!(BedrockAiBinding::new(ok).is_ok());
}
for bad in [
"x.evil.com/",
"us-east-1.evil.com",
"",
"US-EAST-1",
"us east 1",
"us-east-1/",
"us-east-1@evil.com",
"us-east",
"useast1",
"us--east-1",
"-us-east-1",
"us-east-1-",
"us-east-1\n",
"us-east-123",
] {
let err =
serde_json::from_value::<BedrockAiBinding>(serde_json::json!({ "region": bad }))
.expect_err(&format!("{bad:?} must be refused"))
.to_string();
assert!(
err.contains("invalid AWS region"),
"unclear error for {bad:?}: {err}"
);
assert!(BedrockAiBinding::new(bad).is_err());
assert!(serde_json::from_value::<AiBinding>(
serde_json::json!({ "service": "bedrock", "region": bad })
)
.is_err());
assert!(serde_json::from_value::<ExternalAi>(
serde_json::json!({ "service": "bedrock", "region": bad })
)
.is_err());
}
}
#[test]
fn test_external_ai_rejects_typos_and_unused_keys_with_clear_errors() {
for bad in [
serde_json::json!({"service": "bedrok", "region": "us-east-1"}),
serde_json::json!({"service": "bedrock"}),
serde_json::json!({"service": "bedrock", "region": "us-east-1", "apiKey": "sk-x"}),
serde_json::json!({"provider": "openai"}),
serde_json::json!("bedrock"),
] {
let err = serde_json::from_value::<ExternalAi>(bad.clone())
.expect_err(&format!("{bad} must be refused"))
.to_string();
assert!(
err.contains("invalid external AI binding") && err.contains("\"apiKey\""),
"unclear error for {bad}: {err}"
);
assert!(!err.contains("sk-x"), "error must not echo the key: {err}");
}
let err = serde_json::from_value::<ExternalAi>(
serde_json::json!({"service": "bedrock", "region": "us-east-1", "apiKey": "sk-x"}),
)
.unwrap_err()
.to_string();
assert!(err.contains("`apiKey` is not allowed"), "{err}");
}
}