Skip to main content

alien_core/bindings/
mod.rs

1//! Type-safe binding parameter definitions
2//!
3//! This module defines structs that represent the runtime parameters needed by bindings
4//! to interact with cloud resources. These structs are used by:
5//! - Controllers when returning binding parameters directly
6//! - Template generators when creating CloudFormation/Terraform templates (using Fn::ToJsonString)
7//! - Bindings when consuming runtime parameters (parsing JSON)
8//!
9//! This provides type safety and ensures consistency across all parts of the system.
10
11use crate::error::ErrorData;
12use alien_error::{AlienError, Context, IntoAlienError};
13use serde::{Deserialize, Serialize};
14use serde_json::Value as JsonValue;
15use std::collections::HashMap;
16
17mod ai;
18mod artifact_registry;
19mod build;
20mod container;
21mod container_apps_environment;
22mod key;
23mod kv;
24mod postgres;
25mod queue;
26mod redis;
27mod sandbox;
28mod service_account;
29mod storage;
30mod vault;
31mod worker;
32
33pub use ai::{
34    validate_aws_region, AiBinding, AmbientAiBinding, BedrockAiBinding, ExternalAi,
35    ExternalAiBinding, FoundryAiBinding, VertexAiBinding,
36};
37pub use artifact_registry::{
38    AcrArtifactRegistryBinding, ArtifactRegistryBinding, EcrArtifactRegistryBinding,
39    GarArtifactRegistryBinding, LocalArtifactRegistryBinding, LEGACY_REPOSITORY_PUSH_REFUSAL,
40};
41pub use build::{
42    AcaBuildBinding, BuildBinding, CloudbuildBuildBinding, CodebuildBuildBinding, LocalBuildBinding,
43};
44pub use container::{
45    ContainerBinding, HorizonContainerBinding, KubernetesContainerBinding, LocalContainerBinding,
46};
47pub use container_apps_environment::ContainerAppsEnvironmentBinding;
48pub use key::{AwsKmsKeyBinding, AzureKeyVaultKeyBinding, GcpCloudKmsKeyBinding, KeyBinding};
49pub use kv::{
50    DynamodbKvBinding, FirestoreKvBinding, KvBinding, LocalKvBinding, RedisKvBinding,
51    TableStorageKvBinding,
52};
53pub use postgres::{
54    AuroraPostgresBinding, CloudSqlPostgresBinding, ExternalPostgresBinding,
55    ExternalPostgresSslMode, FlexibleServerPostgresBinding, LocalPostgresBinding, PostgresBinding,
56};
57pub use queue::{
58    LocalHttpQueueBinding, LocalQueueBinding, PubSubQueueBinding, QueueBinding,
59    ServiceBusQueueBinding, SqsQueueBinding,
60};
61pub use redis::{
62    AzureManagedRedisBinding, ElastiCacheRedisBinding, ExternalRedisBinding, LocalRedisBinding,
63    MemorystoreRedisBinding, RedisBinding,
64};
65pub use sandbox::{
66    AwsSandboxBinding, AzureSandboxBinding, GcpAgentPlatformSandboxBinding,
67    KubernetesSandboxBinding, LocalSandboxBinding, SandboxBinding, SandboxEgressBinding,
68    SandboxEgressGateway, SandboxEgressReplicas, SandboxEgressSigningKey,
69    EGRESS_GATEWAY_ADMIN_PROTOCOL,
70};
71pub use service_account::{
72    AwsServiceAccountBinding, AzureServiceAccountBinding, GcpServiceAccountBinding,
73    ServiceAccountBinding,
74};
75pub use storage::{
76    BlobStorageBinding, GcsStorageBinding, LocalStorageBinding, S3StorageBinding, StorageBinding,
77};
78pub use vault::{
79    KeyVaultBinding, KubernetesSecretVaultBinding, LocalVaultBinding, ParameterStoreVaultBinding,
80    SecretManagerVaultBinding, VaultBinding,
81};
82pub use worker::{
83    CloudRunWorkerBinding, ContainerAppWorkerBinding, KubernetesWorkerBinding, LambdaWorkerBinding,
84    LocalWorkerBinding, WorkerBinding,
85};
86
87/// Represents a value that can be either a concrete value, a template expression,
88/// or a reference to a Kubernetes Secret
89#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
90#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
91#[cfg_attr(feature = "jsonschema", derive(schemars::JsonSchema))]
92#[serde(untagged)]
93pub enum BindingValue<T> {
94    /// A concrete value (used by controllers)
95    Value(T),
96    /// A Kubernetes Secret reference (must come before Expression)
97    #[serde(rename_all = "camelCase")]
98    SecretRef { secret_ref: SecretReference },
99    /// A template expression (used by IaC template generators)
100    #[cfg_attr(feature = "jsonschema", schemars(skip))]
101    Expression(JsonValue),
102}
103
104/// Reference to a Kubernetes Secret
105#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
106#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
107#[cfg_attr(feature = "jsonschema", derive(schemars::JsonSchema))]
108#[serde(rename_all = "camelCase")]
109pub struct SecretReference {
110    pub name: String,
111    pub key: String,
112}
113
114impl<T> BindingValue<T> {
115    /// Creates a concrete value
116    pub fn value(val: T) -> Self {
117        Self::Value(val)
118    }
119
120    /// Creates a template expression
121    pub fn expression(expr: JsonValue) -> Self {
122        Self::Expression(expr)
123    }
124
125    /// Extracts the concrete value, returning an error if this is a template expression or SecretRef
126    pub fn into_value(self, binding_name: &str, field_name: &str) -> crate::error::Result<T> {
127        match self {
128            BindingValue::Value(val) => Ok(val),
129            BindingValue::Expression(_) => Err(AlienError::new(ErrorData::BindingConfigInvalid {
130                binding_name: binding_name.to_string(),
131                reason: format!("Template expressions not supported in runtime bindings for field '{}'", field_name),
132            })),
133            BindingValue::SecretRef { .. } => Err(AlienError::new(ErrorData::BindingConfigInvalid {
134                binding_name: binding_name.to_string(),
135                reason: format!("SecretRef not resolved for field '{}' - this should have been resolved by the controller", field_name),
136            }))
137        }
138    }
139}
140
141impl<T> From<T> for BindingValue<T> {
142    fn from(val: T) -> Self {
143        Self::Value(val)
144    }
145}
146
147impl From<&str> for BindingValue<String> {
148    fn from(val: &str) -> Self {
149        Self::Value(val.to_string())
150    }
151}
152
153impl From<JsonValue> for BindingValue<String> {
154    fn from(val: JsonValue) -> Self {
155        Self::Expression(val)
156    }
157}
158
159/// Helper worker to serialize binding struct as JSON for environment variables
160pub fn serialize_binding_as_env_var<T: Serialize>(
161    binding_name: &str,
162    binding: &T,
163) -> crate::error::Result<HashMap<String, String>> {
164    let mut env_vars = HashMap::new();
165    let key = binding_env_var_name(binding_name);
166    let mut value = serde_json::to_value(binding).into_alien_error().context(
167        ErrorData::BindingConfigInvalid {
168            binding_name: binding_name.to_string(),
169            reason: "Failed to serialize binding to JSON".to_string(),
170        },
171    )?;
172    // Environment strings become part of pod templates. Map insertion order
173    // must not restart a workload whose binding values have not changed.
174    value.sort_all_objects();
175    let binding_json = serde_json::to_string(&value).into_alien_error().context(
176        ErrorData::BindingConfigInvalid {
177            binding_name: binding_name.to_string(),
178            reason: "Failed to serialize binding to JSON".to_string(),
179        },
180    )?;
181    env_vars.insert(key, binding_json);
182    Ok(env_vars)
183}
184
185/// Helper worker to serialize binding struct for CloudFormation templates
186pub fn serialize_binding_for_template<T: Serialize>(
187    binding_name: &str,
188    binding: &T,
189) -> crate::error::Result<HashMap<String, JsonValue>> {
190    let mut env_vars = HashMap::new();
191    let key = binding_env_var_name(binding_name);
192    let binding_json = serde_json::to_value(binding).into_alien_error().context(
193        ErrorData::BindingConfigInvalid {
194            binding_name: binding_name.to_string(),
195            reason: "Failed to serialize binding to JSON for template".to_string(),
196        },
197    )?;
198
199    // Wrap in Fn::ToJsonString for CloudFormation
200    env_vars.insert(
201        key,
202        JsonValue::Object({
203            let mut map = serde_json::Map::new();
204            map.insert("Fn::ToJsonString".to_string(), binding_json);
205            map
206        }),
207    );
208
209    Ok(env_vars)
210}
211
212/// Helper worker to generate the environment variable name for a binding
213pub fn binding_env_var_name(binding_name: &str) -> String {
214    format!(
215        "ALIEN_{}_BINDING",
216        binding_name.replace('-', "_").to_uppercase()
217    )
218}
219
220/// Helper worker to parse binding from environment variable
221pub fn parse_binding_from_env<T: for<'de> Deserialize<'de>>(
222    env: &HashMap<String, String>,
223    binding_name: &str,
224) -> crate::error::Result<T> {
225    let key = binding_env_var_name(binding_name);
226    let json_str = env.get(&key).ok_or_else(|| {
227        AlienError::new(ErrorData::BindingEnvVarMissing {
228            binding_name: binding_name.to_string(),
229            env_var: key.clone(),
230        })
231    })?;
232
233    let mut value: JsonValue = serde_json::from_str(json_str).into_alien_error().context(
234        ErrorData::BindingJsonParseFailed {
235            binding_name: binding_name.to_string(),
236            reason: "Invalid JSON format".to_string(),
237        },
238    )?;
239    resolve_binding_env_refs(&mut value, env, binding_name)?;
240    serde_json::from_value(value)
241        .into_alien_error()
242        .context(ErrorData::BindingJsonParseFailed {
243            binding_name: binding_name.to_string(),
244            reason: "Invalid JSON format".to_string(),
245        })
246}
247
248/// Resolve projected Secret values after parsing JSON, preserving their exact bytes.
249/// Values read from the environment are literals, never recursively interpreted.
250pub fn resolve_binding_env_refs(
251    value: &mut JsonValue,
252    env: &HashMap<String, String>,
253    binding_name: &str,
254) -> crate::error::Result<()> {
255    match value {
256        JsonValue::Object(fields) => {
257            if fields.len() == 1 && fields.contains_key("envRef") {
258                let name = fields["envRef"].as_str().ok_or_else(|| {
259                    AlienError::new(ErrorData::BindingConfigInvalid {
260                        binding_name: binding_name.to_string(),
261                        reason: "envRef must name an environment variable".to_string(),
262                    })
263                })?;
264                let secret = env.get(name).ok_or_else(|| {
265                    AlienError::new(ErrorData::BindingEnvVarMissing {
266                        binding_name: binding_name.to_string(),
267                        env_var: name.to_string(),
268                    })
269                })?;
270                *value = JsonValue::String(secret.clone());
271            } else {
272                for field in fields.values_mut() {
273                    resolve_binding_env_refs(field, env, binding_name)?;
274                }
275            }
276        }
277        JsonValue::Array(items) => {
278            for item in items {
279                resolve_binding_env_refs(item, env, binding_name)?;
280            }
281        }
282        _ => {}
283    }
284    Ok(())
285}
286
287#[cfg(test)]
288mod tests {
289    use super::*;
290    use crate::bindings::{ArtifactRegistryBinding, BuildBinding, StorageBinding};
291    use serde_json::json;
292    use std::collections::HashMap;
293
294    #[test]
295    fn environment_references_are_resolved_as_literals() {
296        let original = json!({"nested": [{"envRef": "SECRET"}], "literal": "$(SECRET)"});
297        let secret = "{\"envRef\":\"OTHER\"}\n\\";
298        let env = HashMap::from([("SECRET".into(), secret.into())]);
299        let mut value = original.clone();
300        resolve_binding_env_refs(&mut value, &env, "database").unwrap();
301        assert_eq!(value, json!({"nested": [secret], "literal": "$(SECRET)"}));
302        let mut missing = original;
303        assert!(resolve_binding_env_refs(&mut missing, &HashMap::new(), "database").is_err());
304        let mut invalid = json!({"envRef": 7});
305        assert!(resolve_binding_env_refs(&mut invalid, &env, "database").is_err());
306    }
307
308    #[test]
309    fn build_binding_environment_is_stable_across_map_constructions() {
310        let expected = r#"{"buildEnvVars":{"CACHE":"shared","MODE":"release","TARGET":"linux"},"namespace":"site","service":"kubernetes","serviceAccountName":"builder"}"#;
311        for _ in 0..16 {
312            let binding = BuildBinding::kubernetes(
313                "site",
314                "builder",
315                HashMap::from([
316                    ("MODE".to_string(), "release".to_string()),
317                    ("CACHE".to_string(), "shared".to_string()),
318                    ("TARGET".to_string(), "linux".to_string()),
319                ]),
320            );
321            let vars = serialize_binding_as_env_var("build", &binding).unwrap();
322            assert_eq!(vars["ALIEN_BUILD_BINDING"], expected);
323            let parsed: BuildBinding = parse_binding_from_env(&vars, "build").unwrap();
324            assert_eq!(parsed, binding);
325        }
326    }
327
328    #[test]
329    fn binding_environment_ignores_nested_object_order_but_preserves_arrays() {
330        let first =
331            json!({"service": "kubernetes", "nested": [{"z": 1, "a": 2}], "args": ["run", "app"]});
332        let second =
333            json!({"args": ["run", "app"], "nested": [{"a": 2, "z": 1}], "service": "kubernetes"});
334        let original = serialize_binding_as_env_var("build", &first).unwrap();
335        assert_eq!(
336            original,
337            serialize_binding_as_env_var("build", &second).unwrap()
338        );
339        let mut changed = second;
340        changed["args"] = json!(["app", "run"]);
341        assert_ne!(
342            original,
343            serialize_binding_as_env_var("build", &changed).unwrap()
344        );
345        assert_eq!(
346            serde_json::from_str::<JsonValue>(&original["ALIEN_BUILD_BINDING"]).unwrap(),
347            first
348        );
349    }
350
351    #[test]
352    fn test_serialize_storage_binding_as_env_var() {
353        let binding = StorageBinding::s3("my-bucket");
354
355        let env_vars = serialize_binding_as_env_var("TEST", &binding).unwrap();
356
357        assert_eq!(env_vars.len(), 1);
358        let json_str = env_vars.get("ALIEN_TEST_BINDING").unwrap();
359        let parsed: StorageBinding = serde_json::from_str(json_str).unwrap();
360        assert_eq!(binding, parsed);
361    }
362
363    #[test]
364    fn test_serialize_binding_for_template() {
365        let binding = StorageBinding::S3(S3StorageBinding::bucket(BindingValue::expression(
366            json!({"Ref": "MyBucket"}),
367        )));
368
369        let env_vars = serialize_binding_for_template("TEST", &binding).unwrap();
370
371        assert_eq!(env_vars.len(), 1);
372        let fn_to_json_string = env_vars.get("ALIEN_TEST_BINDING").unwrap();
373
374        // Should be wrapped in Fn::ToJsonString
375        assert!(fn_to_json_string.get("Fn::ToJsonString").is_some());
376    }
377
378    #[test]
379    fn test_artifact_registry_binding_roundtrip() {
380        let binding = ArtifactRegistryBinding::ecr(
381            "my-project",
382            Some("arn:aws:iam::123456789012:role/PullRole".to_string()),
383            None::<String>,
384        );
385
386        let env_vars = serialize_binding_as_env_var("TEST", &binding).unwrap();
387
388        let reconstructed: ArtifactRegistryBinding =
389            parse_binding_from_env(&env_vars, "TEST").unwrap();
390        assert_eq!(binding, reconstructed);
391    }
392
393    #[test]
394    fn test_service_type_serialization() {
395        // Test S3 storage
396        let s3_binding = StorageBinding::s3("my-bucket");
397        let s3_json = serde_json::to_string(&s3_binding).unwrap();
398        assert!(s3_json.contains(r#""service":"s3""#));
399
400        // Test ECR registry
401        let ecr_binding = ArtifactRegistryBinding::ecr("my-repo", None::<String>, None::<String>);
402        let ecr_json = serde_json::to_string(&ecr_binding).unwrap();
403        assert!(ecr_json.contains(r#""service":"ecr""#));
404
405        // Test CodeBuild
406        let build_binding = BuildBinding::codebuild("my-project", HashMap::new(), None);
407        let build_json = serde_json::to_string(&build_binding).unwrap();
408        assert!(build_json.contains(r#""service":"codebuild""#));
409    }
410
411    #[test]
412    fn test_cross_provider_bindings() {
413        // Test that we can mix different service types in one environment
414        let storage_binding = StorageBinding::s3("prod-bucket");
415        let registry_binding = ArtifactRegistryBinding::acr("myregistry", "mygroup");
416        let build_binding = BuildBinding::cloudbuild(
417            HashMap::new(),
418            "build@project.iam.gserviceaccount.com",
419            None,
420        );
421
422        // Serialize all bindings
423        let storage_env = serialize_binding_as_env_var("STORAGE", &storage_binding).unwrap();
424        let registry_env = serialize_binding_as_env_var("REGISTRY", &registry_binding).unwrap();
425        let build_env = serialize_binding_as_env_var("BUILD", &build_binding).unwrap();
426
427        // All should work together
428        assert!(storage_env.contains_key("ALIEN_STORAGE_BINDING"));
429        assert!(registry_env.contains_key("ALIEN_REGISTRY_BINDING"));
430        assert!(build_env.contains_key("ALIEN_BUILD_BINDING"));
431    }
432
433    #[test]
434    fn test_binding_value_secret_ref() {
435        // Test SecretRef serialization
436        let secret_ref: BindingValue<String> = BindingValue::SecretRef {
437            secret_ref: SecretReference {
438                name: "my-secret".to_string(),
439                key: "password".to_string(),
440            },
441        };
442
443        let json = serde_json::to_string(&secret_ref).unwrap();
444        assert!(json.contains(r#""secretRef""#));
445        assert!(json.contains(r#""name":"my-secret""#));
446        assert!(json.contains(r#""key":"password""#));
447
448        // Test deserialization
449        let parsed: BindingValue<String> = serde_json::from_str(&json).unwrap();
450        assert_eq!(secret_ref, parsed);
451    }
452
453    #[test]
454    fn test_binding_value_into_value_secret_ref() {
455        let secret_ref: BindingValue<String> = BindingValue::SecretRef {
456            secret_ref: SecretReference {
457                name: "my-secret".to_string(),
458                key: "password".to_string(),
459            },
460        };
461
462        let result = secret_ref.into_value("test", "password");
463        assert!(result.is_err());
464        assert!(result
465            .unwrap_err()
466            .to_string()
467            .contains("SecretRef not resolved"));
468    }
469
470    #[test]
471    fn test_binding_value_variants() {
472        // Test Value variant
473        let value: BindingValue<String> = BindingValue::value("test".to_string());
474        assert_eq!(value.into_value("test", "field").unwrap(), "test");
475
476        // Test Expression variant
477        let expr: BindingValue<String> = BindingValue::expression(json!({"Ref": "Test"}));
478        assert!(expr.into_value("test", "field").is_err());
479    }
480}