Skip to main content

alien_core/bindings/
ai.rs

1//! AI Gateway binding definitions for managed AI inference across cloud providers.
2
3use super::BindingValue;
4use serde::{Deserialize, Serialize};
5
6/// Represents an AI Gateway binding for managed inference across cloud providers.
7///
8/// The managed variants (Bedrock/Vertex/Foundry) carry only identifiers and
9/// endpoints; authentication uses the workload's ambient cloud identity. The
10/// `External` (BYO-key) variant deliberately carries a vault-resolved API key.
11#[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    /// AWS Bedrock AI binding
17    Bedrock(BedrockAiBinding),
18    /// GCP Vertex AI binding
19    Vertex(VertexAiBinding),
20    /// Azure AI Foundry binding
21    Foundry(FoundryAiBinding),
22    /// External provider binding (generic endpoint-based). The tag must stay
23    /// unique across every resource type's binding enum — a bare "external"
24    /// collides with the external Postgres binding in the shared
25    /// `ALIEN_*_BINDING` namespace.
26    #[serde(rename = "external-ai")]
27    External(ExternalAiBinding),
28}
29
30/// AWS Bedrock AI binding configuration
31#[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    /// The AWS region where Bedrock is accessed (for example `us-east-1`). The gateway builds
37    /// `https://bedrock-runtime.<region>.amazonaws.com` from it, so parsing refuses anything
38    /// that is not a plain AWS region name.
39    #[serde(deserialize_with = "deserialize_aws_region")]
40    pub region: String,
41}
42
43impl BedrockAiBinding {
44    /// Builds a binding after checking the region with [`validate_aws_region`].
45    pub fn new(region: impl Into<String>) -> Result<Self, String> {
46        let region = region.into();
47        validate_aws_region(&region)?;
48        Ok(Self { region })
49    }
50}
51
52/// Accepts an AWS region name such as `us-east-1`, `eu-central-2`, `us-gov-west-1` or
53/// `ap-southeast-4`: lowercase letter groups and one trailing number, joined by single
54/// dashes, starting with a two-letter geography. No dots, slashes, spaces or uppercase, so a
55/// region can never change the host of a URL built from it.
56pub 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(&region).map_err(serde::de::Error::custom)?;
90    Ok(region)
91}
92
93/// GCP Vertex AI binding configuration
94#[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    /// The GCP project ID
100    pub project: String,
101    /// The Vertex AI region (e.g., "us-central1")
102    pub location: String,
103}
104
105/// Azure AI Foundry binding configuration
106#[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    /// The Foundry deployment endpoint URL
112    pub endpoint: String,
113    /// The Azure account or subscription identifier
114    pub account: String,
115}
116
117/// External AI provider binding configuration (BYO-key).
118///
119/// The operator-supplied secret rides inside the binding via
120/// `BindingValue<String>`, so it is a literal on cloud platforms and gains
121/// Kubernetes SecretRef resolution for free (`extract_binding_secrets` walks
122/// the binding JSON for `secretRef`).
123// No derived `Debug` — an inline `api_key` would print cleartext; see the redacting impl below.
124#[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    /// The external AI provider name (e.g., "openai", "anthropic")
130    pub provider: String,
131    /// The provider API key. Resolved to plaintext in the worker environment
132    /// (literal on cloud, Kubernetes Secret on K8s) so the SDK reads it directly.
133    pub api_key: BindingValue<String>,
134}
135
136// Redacts the inline key and keeps every other field, mirroring the external
137// Postgres binding's redacting impl.
138impl 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/// What an installer supplies for an AI resource with an external binding.
148///
149/// Two inputs, told apart by whether the JSON carries a `service` tag (other than `external-ai`):
150/// - `{ "provider", "apiKey" }` — BYO key (the original input; stored deployments and Helm values
151///   carry it, so it parses exactly as before). `{ "service": "external-ai", "provider",
152///   "apiKey" }` also parses, as it did before the cloud-identity form existed.
153/// - `{ "service": "bedrock", "region" }` — the cloud's own AI service, called with the workload's
154///   ambient identity (for example an EKS pod's IRSA role). No key, no Secret.
155///
156/// The cloud-identity form needs the pod to have its own AWS identity: on Kubernetes, an IRSA role
157/// on the service account (or an EKS Pod Identity association) with `bedrock:InvokeModel` and
158/// `bedrock:InvokeModelWithResponseStream`. Without one the gateway refuses to sign and never uses
159/// the node's role. The `region` must be a plain AWS region name such as `us-east-1`.
160///
161/// Access is not checked at install time (the setup credentials cannot speak for the pod's role):
162/// it is checked on the first call, and a model the role cannot use fails with
163/// `provider_access_unavailable`.
164///
165/// Untagged, because the BYO-key input has no tag and must keep parsing unchanged. The two shapes
166/// cannot overlap: the ambient one requires `service`, the key one requires `provider` and `apiKey`.
167/// `Deserialize` is hand-written (see below) so a typo gets an error naming both accepted forms, and
168/// so an ambient input carrying an unused key such as `apiKey` is refused instead of dropped.
169#[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    /// A managed cloud AI service reached with the workload's own identity.
175    Ambient(AmbientAiBinding),
176    /// A provider reached with a key the installer supplies.
177    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        // `external-ai` is the tag the BYO-key binding carries once it reaches a workload, and
192        // earlier releases accepted that form here (the tag was ignored), so keep it on the key
193        // path. Any other `service` is the cloud-identity form.
194        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/// A managed cloud AI service the workload reaches with its ambient identity. The installer owns
214/// the identity and its permissions; Alien grants nothing for it.
215#[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    /// AWS Bedrock, signed with the workload's AWS credential chain.
221    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    /// The binding the workload SDK parses from `ALIEN_<NAME>_BINDING`.
232    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    /// The env var a developer sets to bring their own provider key on the Local platform.
242    /// Shared by the Local controller (provision-time check) and the local bindings
243    /// resolver (runtime-only re-resolution), so the two never drift.
244    pub const LOCAL_API_KEY_ENV: &'static str = "OPENAI_API_KEY";
245    /// The BYO-key provider assumed on the Local platform.
246    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        // The injected env-var JSON must match exactly what the SDK's
323        // `ai(name)` parser expects: service-tagged, camelCase, key inline.
324        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        // Same through the external binding wrapper, and a tagged input missing its key is
352        // still refused with the clear error.
353        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            // Also refused through the tagged forms that carry a Bedrock binding.
411            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}