1use super::BindingValue;
4use serde::{Deserialize, Serialize};
5
6#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
12#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
13#[cfg_attr(feature = "jsonschema", derive(schemars::JsonSchema))]
14#[serde(tag = "service", rename_all = "lowercase")]
15pub enum AiBinding {
16 Bedrock(BedrockAiBinding),
18 Vertex(VertexAiBinding),
20 Foundry(FoundryAiBinding),
22 #[serde(rename = "external-ai")]
27 External(ExternalAiBinding),
28}
29
30#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
32#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
33#[cfg_attr(feature = "jsonschema", derive(schemars::JsonSchema))]
34#[serde(rename_all = "camelCase")]
35pub struct BedrockAiBinding {
36 #[serde(deserialize_with = "deserialize_aws_region")]
40 pub region: String,
41}
42
43impl BedrockAiBinding {
44 pub fn new(region: impl Into<String>) -> Result<Self, String> {
46 let region = region.into();
47 validate_aws_region(®ion)?;
48 Ok(Self { region })
49 }
50}
51
52pub fn validate_aws_region(region: &str) -> Result<(), String> {
57 let invalid = || {
58 format!(
59 "invalid AWS region {region:?}: expected a region name such as \"us-east-1\" \
60 (lowercase letters, digits and single dashes only)"
61 )
62 };
63 if region.len() > 30 {
64 return Err(invalid());
65 }
66 let parts: Vec<&str> = region.split('-').collect();
67 let [geography, middle @ .., number] = parts.as_slice() else {
68 return Err(invalid());
69 };
70 let lowercase = |s: &str| !s.is_empty() && s.bytes().all(|b| b.is_ascii_lowercase());
71 let valid = geography.len() == 2
72 && lowercase(geography)
73 && !middle.is_empty()
74 && middle.iter().all(|m| lowercase(m))
75 && !number.is_empty()
76 && number.len() <= 2
77 && number.bytes().all(|b| b.is_ascii_digit());
78 if valid {
79 Ok(())
80 } else {
81 Err(invalid())
82 }
83}
84
85fn deserialize_aws_region<'de, D: serde::Deserializer<'de>>(
86 deserializer: D,
87) -> Result<String, D::Error> {
88 let region = String::deserialize(deserializer)?;
89 validate_aws_region(®ion).map_err(serde::de::Error::custom)?;
90 Ok(region)
91}
92
93#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
95#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
96#[cfg_attr(feature = "jsonschema", derive(schemars::JsonSchema))]
97#[serde(rename_all = "camelCase")]
98pub struct VertexAiBinding {
99 pub project: String,
101 pub location: String,
103}
104
105#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
107#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
108#[cfg_attr(feature = "jsonschema", derive(schemars::JsonSchema))]
109#[serde(rename_all = "camelCase")]
110pub struct FoundryAiBinding {
111 pub endpoint: String,
113 pub account: String,
115}
116
117#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
125#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
126#[cfg_attr(feature = "jsonschema", derive(schemars::JsonSchema))]
127#[serde(rename_all = "camelCase")]
128pub struct ExternalAiBinding {
129 pub provider: String,
131 pub api_key: BindingValue<String>,
134}
135
136impl std::fmt::Debug for ExternalAiBinding {
139 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
140 f.debug_struct("ExternalAiBinding")
141 .field("provider", &self.provider)
142 .field("api_key", &"<redacted>")
143 .finish()
144 }
145}
146
147#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
170#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
171#[cfg_attr(feature = "jsonschema", derive(schemars::JsonSchema))]
172#[serde(untagged)]
173pub enum ExternalAi {
174 Ambient(AmbientAiBinding),
176 ApiKey(ExternalAiBinding),
178}
179
180impl<'de> Deserialize<'de> for ExternalAi {
181 fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
182 use serde::de::Error;
183 const FORMS: &str = "expected either {\"service\": \"bedrock\", \"region\": \"<region>\"} \
184 (the pod's cloud identity, no key) or {\"provider\": \"<name>\", \"apiKey\": \"<key>\"} (your own key)";
185 let value = serde_json::Value::deserialize(deserializer)?;
186 let Some(object) = value.as_object() else {
187 return Err(D::Error::custom(format!(
188 "invalid external AI binding: {FORMS}"
189 )));
190 };
191 let service = object.get("service").and_then(|v| v.as_str());
195 if object.contains_key("service") && service != Some("external-ai") {
196 if let Some(extra) = object.keys().find(|k| *k != "service" && *k != "region") {
197 return Err(D::Error::custom(format!(
198 "invalid external AI binding: field `{extra}` is not allowed with `service` \
199 (it uses the workload's cloud identity and takes only `region`); {FORMS}"
200 )));
201 }
202 serde_json::from_value(value)
203 .map(Self::Ambient)
204 .map_err(|e| D::Error::custom(format!("invalid external AI binding: {e}; {FORMS}")))
205 } else {
206 serde_json::from_value(value)
207 .map(Self::ApiKey)
208 .map_err(|e| D::Error::custom(format!("invalid external AI binding: {e}; {FORMS}")))
209 }
210 }
211}
212
213#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
216#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
217#[cfg_attr(feature = "jsonschema", derive(schemars::JsonSchema))]
218#[serde(tag = "service", rename_all = "lowercase")]
219pub enum AmbientAiBinding {
220 Bedrock(BedrockAiBinding),
222}
223
224impl From<ExternalAiBinding> for ExternalAi {
225 fn from(binding: ExternalAiBinding) -> Self {
226 Self::ApiKey(binding)
227 }
228}
229
230impl ExternalAi {
231 pub fn to_ai_binding(&self) -> AiBinding {
233 match self {
234 Self::Ambient(AmbientAiBinding::Bedrock(b)) => AiBinding::Bedrock(b.clone()),
235 Self::ApiKey(b) => AiBinding::External(b.clone()),
236 }
237 }
238}
239
240impl AiBinding {
241 pub const LOCAL_API_KEY_ENV: &'static str = "OPENAI_API_KEY";
245 pub const LOCAL_DEFAULT_PROVIDER: &'static str = "openai";
247
248 pub fn bedrock(region: impl Into<String>) -> Self {
249 Self::Bedrock(BedrockAiBinding {
250 region: region.into(),
251 })
252 }
253
254 pub fn vertex(project: impl Into<String>, location: impl Into<String>) -> Self {
255 Self::Vertex(VertexAiBinding {
256 project: project.into(),
257 location: location.into(),
258 })
259 }
260
261 pub fn foundry(endpoint: impl Into<String>, account: impl Into<String>) -> Self {
262 Self::Foundry(FoundryAiBinding {
263 endpoint: endpoint.into(),
264 account: account.into(),
265 })
266 }
267
268 pub fn external(provider: impl Into<String>, api_key: impl Into<BindingValue<String>>) -> Self {
269 Self::External(ExternalAiBinding {
270 provider: provider.into(),
271 api_key: api_key.into(),
272 })
273 }
274}
275
276#[cfg(test)]
277mod tests {
278 use super::*;
279
280 #[test]
281 fn test_bedrock_binding_roundtrip() {
282 let binding = AiBinding::bedrock("us-east-1");
283
284 let json = serde_json::to_string(&binding).unwrap();
285 assert!(json.contains(r#""service":"bedrock""#));
286
287 let deserialized: AiBinding = serde_json::from_str(&json).unwrap();
288 assert_eq!(binding, deserialized);
289 }
290
291 #[test]
292 fn test_vertex_binding_roundtrip() {
293 let binding = AiBinding::vertex("my-project", "us-central1");
294
295 let json = serde_json::to_string(&binding).unwrap();
296 assert!(json.contains(r#""service":"vertex""#));
297
298 let deserialized: AiBinding = serde_json::from_str(&json).unwrap();
299 assert_eq!(binding, deserialized);
300 }
301
302 #[test]
303 fn test_foundry_binding_roundtrip() {
304 let binding = AiBinding::foundry("https://my-foundry.openai.azure.com", "my-subscription");
305
306 let json = serde_json::to_value(&binding).unwrap();
307 let json_str = json.to_string();
308 assert!(json_str.contains(r#""service":"foundry""#));
309 assert!(
310 !json_str.contains("instantAccess"),
311 "foundry binding must not serialize instant_access"
312 );
313
314 let deserialized: AiBinding = serde_json::from_value(json).unwrap();
315 assert_eq!(binding, deserialized);
316 }
317
318 #[test]
319 fn test_external_binding_roundtrip() {
320 let binding = AiBinding::external("openai", "sk-test-key");
321
322 let json = serde_json::to_value(&binding).unwrap();
325 let json_str = json.to_string();
326 assert!(
327 json_str.contains(r#""apiKey""#),
328 "external binding must serialize apiKey in camelCase"
329 );
330 assert_eq!(
331 json,
332 serde_json::json!({
333 "service": "external-ai",
334 "provider": "openai",
335 "apiKey": "sk-test-key",
336 })
337 );
338
339 let deserialized: AiBinding =
340 serde_json::from_value(json).expect("external binding should round-trip");
341 assert_eq!(binding, deserialized);
342 }
343
344 #[test]
345 fn external_ai_with_the_external_ai_service_tag_still_parses_as_a_key() {
346 let parsed: ExternalAi = serde_json::from_value(serde_json::json!({
347 "service": "external-ai", "provider": "openai", "apiKey": "sk-x"
348 }))
349 .expect("the tagged BYO-key input parsed before and must keep parsing");
350 assert!(matches!(&parsed, ExternalAi::ApiKey(b) if b.provider == "openai"));
351 let binding: crate::ExternalBinding = serde_json::from_value(serde_json::json!({
354 "type": "ai", "service": "external-ai", "provider": "openai", "apiKey": "sk-x"
355 }))
356 .unwrap();
357 assert_eq!(
358 binding.to_env_binding_value().unwrap(),
359 serde_json::json!({"service": "external-ai", "provider": "openai", "apiKey": "sk-x"})
360 );
361 let err = serde_json::from_value::<ExternalAi>(
362 serde_json::json!({"service": "external-ai", "provider": "openai"}),
363 )
364 .unwrap_err()
365 .to_string();
366 assert!(err.contains("invalid external AI binding"), "{err}");
367 }
368
369 #[test]
370 fn bedrock_region_must_be_a_plain_aws_region() {
371 for ok in [
372 "us-east-1",
373 "eu-central-2",
374 "ap-southeast-4",
375 "us-gov-west-1",
376 "us-iso-east-1",
377 "cn-north-1",
378 ] {
379 let binding: BedrockAiBinding =
380 serde_json::from_value(serde_json::json!({ "region": ok }))
381 .unwrap_or_else(|e| panic!("{ok} must parse: {e}"));
382 assert_eq!(binding.region, ok);
383 assert!(BedrockAiBinding::new(ok).is_ok());
384 }
385 for bad in [
386 "x.evil.com/",
387 "us-east-1.evil.com",
388 "",
389 "US-EAST-1",
390 "us east 1",
391 "us-east-1/",
392 "us-east-1@evil.com",
393 "us-east",
394 "useast1",
395 "us--east-1",
396 "-us-east-1",
397 "us-east-1-",
398 "us-east-1\n",
399 "us-east-123",
400 ] {
401 let err =
402 serde_json::from_value::<BedrockAiBinding>(serde_json::json!({ "region": bad }))
403 .expect_err(&format!("{bad:?} must be refused"))
404 .to_string();
405 assert!(
406 err.contains("invalid AWS region"),
407 "unclear error for {bad:?}: {err}"
408 );
409 assert!(BedrockAiBinding::new(bad).is_err());
410 assert!(serde_json::from_value::<AiBinding>(
412 serde_json::json!({ "service": "bedrock", "region": bad })
413 )
414 .is_err());
415 assert!(serde_json::from_value::<ExternalAi>(
416 serde_json::json!({ "service": "bedrock", "region": bad })
417 )
418 .is_err());
419 }
420 }
421
422 #[test]
423 fn test_external_ai_rejects_typos_and_unused_keys_with_clear_errors() {
424 for bad in [
425 serde_json::json!({"service": "bedrok", "region": "us-east-1"}),
426 serde_json::json!({"service": "bedrock"}),
427 serde_json::json!({"service": "bedrock", "region": "us-east-1", "apiKey": "sk-x"}),
428 serde_json::json!({"provider": "openai"}),
429 serde_json::json!("bedrock"),
430 ] {
431 let err = serde_json::from_value::<ExternalAi>(bad.clone())
432 .expect_err(&format!("{bad} must be refused"))
433 .to_string();
434 assert!(
435 err.contains("invalid external AI binding") && err.contains("\"apiKey\""),
436 "unclear error for {bad}: {err}"
437 );
438 assert!(!err.contains("sk-x"), "error must not echo the key: {err}");
439 }
440 let err = serde_json::from_value::<ExternalAi>(
441 serde_json::json!({"service": "bedrock", "region": "us-east-1", "apiKey": "sk-x"}),
442 )
443 .unwrap_err()
444 .to_string();
445 assert!(err.contains("`apiKey` is not allowed"), "{err}");
446 }
447}