Skip to main content

alien_core/
extension.rs

1//! What a stack carries about each extension it uses.
2//!
3//! A stack lists its extensions in `Stack.extensions`, and each one describes the resource types
4//! it defines. Every holder of a stack reads a custom type's descriptor from there, so one
5//! deployment never sees the types of an extension another deployment uses.
6
7use crate::{BinaryTarget, PermissionSet, Platform, ResourceLifecycle, ResourceType};
8use indexmap::IndexMap;
9use serde::{Deserialize, Serialize};
10
11/// An extension a stack uses, and the resource types it defines.
12#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
13#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
14#[serde(rename_all = "camelCase")]
15pub struct ExtensionManifest {
16    /// The extension's name, the first part of each type it defines, such as "acme".
17    pub name: String,
18    /// The extension's version.
19    pub version: String,
20    /// The sha256 digest of the extension's bundle. Every loader checks the bundle against it.
21    pub digest: String,
22    /// The resource types the extension defines, keyed by type name, such as "acme/dns-zone".
23    #[cfg_attr(feature = "openapi", schema(value_type = HashMap<String, ResourceTypeDescriptor>))]
24    pub resource_types: IndexMap<ResourceType, ResourceTypeDescriptor>,
25    /// The origins (`https://host[:port]`) the extension's controllers may call besides its
26    /// cloud, as its bundle declares them. The setup template shows them to the customer.
27    #[serde(default, skip_serializing_if = "Vec::is_empty")]
28    pub egress: Vec<String>,
29}
30
31impl ExtensionManifest {
32    /// The extension that can define `resource_type`: the type's first part, as `acme` in
33    /// `acme/dns-zone`. The name prefixes every type an extension adds.
34    pub fn owner_of(resource_type: &ResourceType) -> Option<&str> {
35        resource_type
36            .as_ref()
37            .split_once('/')
38            .map(|(extension, _)| extension)
39    }
40
41    /// Whether this extension can define `resource_type`.
42    pub fn owns(&self, resource_type: &ResourceType) -> bool {
43        Self::owner_of(resource_type) == Some(self.name.as_str())
44    }
45
46    /// The id of the setup-owned identity the extension's controllers run as, such as
47    /// "acme-ext". Short, since cloud identity names carry the deployment's prefix and GCP caps
48    /// a service account's at 30 characters.
49    pub fn identity_id(&self) -> String {
50        format!("{}-ext", self.name)
51    }
52}
53
54/// The name the customer sees for an extension's identity, in the setup template and the cloud
55/// console, such as "Extension identity (acme)".
56pub fn extension_identity_display_name(extension: &str) -> String {
57    format!("Extension identity ({extension})")
58}
59
60/// The AWS role name setup gives an extension's identity: `<prefix>-<id>`, cut to IAM's 64
61/// characters with a hash of the full name, as the Terraform template derives it.
62pub fn extension_identity_aws_role_name(prefix: &str, id: &str) -> String {
63    let full = format!("{prefix}-{id}");
64    if full.chars().count() <= 64 {
65        return full;
66    }
67    let stem: String = full.chars().take(55).collect();
68    format!("{stem}-{}", &sha1_hex(&full)[..8])
69}
70
71/// The GCP service account id setup gives an extension's identity, as the Terraform template
72/// derives every service account's: a readable stem and a hash of the full name, within GCP's 30
73/// characters.
74pub fn extension_identity_gcp_account_id(prefix: &str, id: &str) -> String {
75    let full = format!("{prefix}-{}", terraform_label(id))
76        .to_lowercase()
77        .replace('_', "-");
78    let stem: String = format!("a-{full}").chars().take(21).collect();
79    format!("{}-{}", stem.trim_matches('-'), &sha1_hex(&full)[..8])
80}
81
82/// The Terraform label a resource id gets in a generated module.
83fn terraform_label(id: &str) -> String {
84    let label: String = id
85        .chars()
86        .map(|c| {
87            if c.is_ascii_alphanumeric() {
88                c.to_ascii_lowercase()
89            } else {
90                '_'
91            }
92        })
93        .collect();
94    if label.starts_with(|c: char| c.is_ascii_digit()) {
95        format!("_{label}")
96    } else {
97        label
98    }
99}
100
101fn sha1_hex(value: &str) -> String {
102    use sha1::{Digest, Sha1};
103    format!("{:x}", Sha1::digest(value.as_bytes()))
104}
105
106/// What Alien knows about a resource type an extension defines.
107#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
108#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
109#[serde(rename_all = "camelCase")]
110pub struct ResourceTypeDescriptor {
111    /// The lifecycles a resource of this type may have.
112    pub lifecycles: Vec<ResourceLifecycle>,
113    /// Whether deleting the resource can lose the customer's data. Removing a deployment keeps
114    /// such a resource unless the deletion erases data.
115    pub holds_data: bool,
116    /// The setup templates and importers the extension provides for this type.
117    pub setup: SetupSupport,
118    /// The platforms the extension ships a controller for this type on.
119    pub controller_platforms: Vec<Platform>,
120    /// The permission sets the extension defines for this type. Their ids are
121    /// `<extension>/<type>/<name>`.
122    pub permission_sets: Vec<PermissionSet>,
123    /// What a workload that links a resource of this type gets.
124    pub link: LinkDescriptor,
125    /// The JSON schemas of the type's config and outputs.
126    pub schemas: ResourceTypeSchemas,
127    /// The cloud services the type needs enabled, per platform: GCP APIs such as
128    /// "dns.googleapis.com", Azure resource providers such as "Microsoft.Network". Alien enables
129    /// them with the services its own resource types need.
130    #[serde(default, skip_serializing_if = "IndexMap::is_empty")]
131    #[cfg_attr(feature = "openapi", schema(value_type = HashMap<String, Vec<String>>))]
132    pub services: IndexMap<Platform, Vec<String>>,
133    /// Whether the type needs the stack's network. Alien then creates the network on AWS, GCP
134    /// and Azure.
135    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
136    pub requires_network: bool,
137    /// Where the type's private network endpoints are, when it has any. A sandbox's image may
138    /// then declare a direct connection to a resource of this type; see
139    /// [`crate::PrivateNetworkEndpoints`].
140    #[serde(default, skip_serializing_if = "Option::is_none")]
141    pub private_network_endpoints: Option<crate::PrivateEndpointPlacement>,
142}
143
144/// The stems of the files Alien's Terraform module writes besides one per resource: an
145/// extension's Terraform modifier writes `<extension>.tf` beside them. `override` is there too,
146/// since Terraform merges `override.tf` into the module, and `main`, the file a module's own
147/// configuration conventionally sits in. alien-terraform checks its generator against the list.
148pub const TERRAFORM_MODULE_FILE_STEMS: [&str; 15] = [
149    "versions",
150    "variables",
151    "providers",
152    "resource_prefix",
153    "locals",
154    "iam_propagation",
155    "registration",
156    "setup_record",
157    "helm",
158    "outputs",
159    "retention-inventory",
160    "existing-cluster-network-guard",
161    "signing",
162    "override",
163    "main",
164];
165
166/// The longest extension name every setup can name the extension's identity with. The
167/// CloudFormation role is `${AWS::StackName}-<name>-ext`, which isn't cut to fit, and a
168/// generated stack's prefix is at most 35 characters: 35 + 1 + 24 + 4 is IAM's 64, as for a
169/// permission profile's `-sa` role on EKS.
170pub const MAX_EXTENSION_NAME_LENGTH: usize = 24;
171
172/// Whether `name` is a lowercase letter followed by lowercase letters, digits and dashes: the
173/// form of an extension's name and of the last segment of its permission sets' ids. Such a name
174/// is a single path segment, a Terraform file stem with no `_override` suffix, and a valid part
175/// of every cloud's identity names.
176pub fn is_extension_name_segment(name: &str) -> bool {
177    name.starts_with(|c: char| c.is_ascii_lowercase())
178        && name
179            .chars()
180            .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-')
181}
182
183/// What makes `name` unusable as an extension's name, or `None` when it can be one. The name
184/// prefixes each type the extension defines, names its identity in every setup and its file in
185/// Alien's Terraform module. `alien extensions build`, the SDK's `export!` and `alien release`
186/// all apply this rule.
187pub fn extension_name_problem(name: &str) -> Option<String> {
188    if name.is_empty() {
189        Some("is empty".to_string())
190    } else if !is_extension_name_segment(name) {
191        Some(
192            "must start with a lowercase letter and hold only lowercase letters, digits and `-`"
193                .to_string(),
194        )
195    } else if name.chars().count() > MAX_EXTENSION_NAME_LENGTH {
196        Some(format!(
197            "is longer than {MAX_EXTENSION_NAME_LENGTH} characters, which the name of its identity's AWS role can't fit"
198        ))
199    } else if crate::RESERVED_TYPE_PREFIXES.contains(&name) {
200        Some("is reserved for Alien's own resource types".to_string())
201    } else if TERRAFORM_MODULE_FILE_STEMS.contains(&name) {
202        Some(format!(
203            "names the file `{name}.tf` in Alien's Terraform module, beside which a Terraform modifier writes `<extension>.tf`"
204        ))
205    } else {
206        None
207    }
208}
209
210/// Whether `service` names a cloud service Alien can enable on `platform`: a GCP API,
211/// `<name>.googleapis.com`, or an Azure resource provider, `Microsoft.<Namespace>`. Azure
212/// compares provider names without case, so the prefix may be in any case.
213pub fn is_cloud_service_name(platform: Platform, service: &str) -> bool {
214    match platform {
215        Platform::Gcp => service.strip_suffix(".googleapis.com").is_some_and(|name| {
216            name.starts_with(|c: char| c.is_ascii_lowercase())
217                && name
218                    .chars()
219                    .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-')
220        }),
221        Platform::Azure => service.split_once('.').is_some_and(|(prefix, namespace)| {
222            prefix.eq_ignore_ascii_case("Microsoft")
223                && namespace.starts_with(|c: char| c.is_ascii_alphabetic())
224                && namespace.chars().all(|c| c.is_ascii_alphanumeric())
225        }),
226        _ => false,
227    }
228}
229
230/// The platforms each setup path supports for one resource type.
231#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
232#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
233#[serde(rename_all = "camelCase")]
234pub struct SetupSupport {
235    /// Platforms with a CloudFormation emitter.
236    pub cloudformation: Vec<Platform>,
237    /// Platforms with a Terraform emitter.
238    pub terraform: Vec<Platform>,
239    /// Platforms with a Helm emitter.
240    pub helm: Vec<Platform>,
241    /// Platforms with an importer, which reads a resource a setup template created.
242    pub importers: Vec<Platform>,
243}
244
245/// A setup template format Alien generates.
246#[derive(Debug, Clone, Copy, PartialEq, Eq)]
247pub enum SetupFormat {
248    CloudFormation,
249    Terraform,
250    Helm,
251}
252
253impl std::fmt::Display for SetupFormat {
254    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
255        f.write_str(match self {
256            SetupFormat::CloudFormation => "CloudFormation",
257            SetupFormat::Terraform => "Terraform",
258            SetupFormat::Helm => "Helm",
259        })
260    }
261}
262
263impl SetupSupport {
264    /// The platforms the type has an emitter for in `format`.
265    pub fn platforms(&self, format: SetupFormat) -> &[Platform] {
266        match format {
267            SetupFormat::CloudFormation => &self.cloudformation,
268            SetupFormat::Terraform => &self.terraform,
269            SetupFormat::Helm => &self.helm,
270        }
271    }
272}
273
274/// What a workload that links a resource of this type gets.
275///
276/// The extension computes a link's environment variables from the resource's outputs, and
277/// declares their names here, so a release can see two links that set the same variable. The
278/// permission sets are fixed per type, because setup grants them before the resource has outputs.
279#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
280#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
281#[serde(rename_all = "camelCase")]
282pub struct LinkDescriptor {
283    /// Ids of the permission sets the workload gets on the linked resource.
284    pub permission_sets: Vec<String>,
285    /// Names of the environment variables the workload gets. A link that sets any other name
286    /// fails the deployment.
287    #[serde(default, skip_serializing_if = "Vec::is_empty")]
288    pub env: Vec<String>,
289}
290
291/// Prefixes a link's environment variable can't start with: Alien's own variables, and the
292/// names AWS Lambda reserves for its runtime.
293const LINK_ENV_RESERVED_PREFIXES: [&str; 4] = ["ALIEN_", "AWS_", "LAMBDA_", "_"];
294
295/// What makes `name` unusable as an environment variable a link sets, or `None` when it can be
296/// one: a letter or `_` followed by letters, digits and `_`, outside the reserved prefixes.
297pub fn link_env_name_problem(name: &str) -> Option<String> {
298    let valid = name.starts_with(|c: char| c.is_ascii_alphabetic() || c == '_')
299        && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_');
300    if !valid {
301        return Some(format!(
302            "`{name}` is not an environment variable name: use letters, digits and `_`, starting with a letter"
303        ));
304    }
305    let upper = name.to_ascii_uppercase();
306    LINK_ENV_RESERVED_PREFIXES
307        .iter()
308        .find(|prefix| upper.starts_with(*prefix))
309        .map(|prefix| {
310            format!(
311                "`{name}` starts with `{prefix}`, which Alien or the platform's runtime reserves"
312            )
313        })
314}
315
316/// The JSON schemas of a resource type's config and outputs.
317#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
318#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
319#[serde(rename_all = "camelCase")]
320pub struct ResourceTypeSchemas {
321    /// The schema of the resource's config.
322    pub config: serde_json::Map<String, serde_json::Value>,
323    /// The schema of the resource's outputs.
324    pub outputs: serde_json::Map<String, serde_json::Value>,
325}
326
327/// The file in an extension bundle's core zip that holds its [`ExtensionBundleManifest`].
328pub const EXTENSION_BUNDLE_MANIFEST: &str = "manifest.json";
329
330/// The file in an extension bundle's core zip that holds its hooks module.
331pub const EXTENSION_HOOKS_MODULE: &str = "hooks.wasm";
332
333/// The file in an extension bundle's core zip that holds its controller module, when its
334/// controllers run as WebAssembly.
335pub const EXTENSION_CONTROLLER_MODULE: &str = "controller.wasm";
336
337/// What an extension bundle's core zip says about the extension: what a loader checks before it
338/// runs anything. The zip's own digest is not in it, since a file can't hold its own digest; the
339/// stack pins the zip by [`ExtensionManifest::digest`].
340#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
341#[serde(rename_all = "camelCase")]
342pub struct ExtensionBundleManifest {
343    /// The extension's name, as `export!` declares it.
344    pub name: String,
345    /// The extension's version, from its hooks crate.
346    pub version: String,
347    /// The protocol versions the extension speaks.
348    pub protocol: ExtensionProtocols,
349    /// The sha256 of the hooks module, hex-encoded.
350    pub hooks_sha256: String,
351    /// The controller binary per target. Every target is listed when the extension has a
352    /// controller, and one the build did not produce is `null`. Empty without a controller.
353    pub controllers: IndexMap<BinaryTarget, Option<ControllerBinary>>,
354    /// The resource types the extension defines, keyed by type name.
355    pub resource_types: IndexMap<ResourceType, ResourceTypeDescriptor>,
356    /// The sha256 of the controller module, hex-encoded, when the extension's controllers run
357    /// as WebAssembly in the loader's process. Every loader runs it but `alien dev`, which runs
358    /// the binary in `controllers`.
359    #[serde(default, skip_serializing_if = "Option::is_none")]
360    pub controller_module_sha256: Option<String>,
361    /// The origins (`https://host[:port]`) the controller module may call besides its cloud,
362    /// with no credential of the deployment's.
363    #[serde(default, skip_serializing_if = "Vec::is_empty")]
364    pub egress: Vec<String>,
365}
366
367/// The protocol versions an extension speaks.
368#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
369#[serde(rename_all = "camelCase")]
370pub struct ExtensionProtocols {
371    /// The hooks module's ABI version.
372    pub hooks: u32,
373    /// The step protocol version its controller speaks, or `null` without a controller.
374    pub controller: Option<u32>,
375}
376
377/// One controller binary in an extension bundle, stored beside the core zip.
378#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
379#[serde(rename_all = "camelCase")]
380pub struct ControllerBinary {
381    /// The binary's sha256, hex-encoded.
382    pub sha256: String,
383    /// The binary's size in bytes.
384    pub size: u64,
385}
386
387#[cfg(test)]
388mod tests {
389    use super::*;
390
391    /// Names an extension can't take, each with the rule that refuses it, and names it can.
392    #[test]
393    fn an_extension_name_is_a_short_lowercase_segment_alien_does_not_use() {
394        for (name, problem) in [
395            ("alien", "reserved"),
396            ("experimental", "reserved"),
397            ("", "empty"),
398            ("a/b", "lowercase letters"),
399            ("my_ext", "lowercase letters"),
400            ("foo_override", "lowercase letters"),
401            ("override", "override.tf"),
402            ("..", "lowercase letters"),
403            ("a..b", "lowercase letters"),
404            ("a\\b", "lowercase letters"),
405            ("Acme", "lowercase letters"),
406            ("a b", "lowercase letters"),
407            ("outputs", "outputs.tf"),
408            ("main", "main.tf"),
409            ("-acme", "lowercase letters"),
410            ("aaaaaaaaaaaaaaaaaaaaaaaaa", "longer than 24 characters"),
411            ("ééééééééééééé", "lowercase letters"),
412            ("retention-inventory", "retention-inventory.tf"),
413        ] {
414            let found = extension_name_problem(name).unwrap_or_default();
415            assert!(found.contains(problem), "{name:?}: {found:?}");
416        }
417        for name in [
418            "acme",
419            "a",
420            "aaaaaaaaaaaaaaaaaaaaaaaa",
421            "dns-zone-2",
422            "backups",
423        ] {
424            assert_eq!(extension_name_problem(name), None, "{name:?}");
425        }
426    }
427
428    #[test]
429    fn cloud_service_names_are_gcp_apis_or_azure_providers() {
430        for (platform, service) in [
431            (Platform::Gcp, "dns.googleapis.com"),
432            (Platform::Gcp, "storage-component.googleapis.com"),
433            (Platform::Azure, "Microsoft.Network"),
434            (Platform::Azure, "microsoft.dbforpostgresql"),
435        ] {
436            assert!(is_cloud_service_name(platform, service), "{service}");
437        }
438        for (platform, service) in [
439            (Platform::Gcp, "cloud.quotas"),
440            (Platform::Gcp, "dns_api.googleapis.com"),
441            (Platform::Gcp, "a.b.googleapis.com"),
442            (Platform::Gcp, "Dns.googleapis.com"),
443            (Platform::Gcp, ".googleapis.com"),
444            (Platform::Azure, "App"),
445            (Platform::Azure, "Microsoft."),
446            (Platform::Azure, "Microsoft.Network.Dns"),
447            (Platform::Azure, "Contoso.Network"),
448            (Platform::Aws, "route53.amazonaws.com"),
449            (Platform::Gcp, "Microsoft.Network"),
450        ] {
451            assert!(!is_cloud_service_name(platform, service), "{service}");
452        }
453    }
454}