Merge pull request #292 from code0-tech/#291-development-flow

development flow

Author: raphael-goetz

Cargo.lock

@@ -5,6 +5,7 @@ edition.workspace = true
 
 [dependencies]
 tucana = { workspace = true }
+code0-flow = { workspace = true, features = ["flow_config"] }
 base64 = { workspace = true }
 rand = { workspace = true }
 log = { workspace = true }

crates/taurus-core/Cargo.toml

@@ -32,6 +32,14 @@ fn write(module: &Module, dir: &Path) -> io::Result<()> {
         &module.definition_data_types,
         |dt| &dt.identifier,
     )?;
+    write_each(&dir.join("flow_types"), &module.flow_types, |ft| {
+        &ft.identifier
+    })?;
+    write_each(
+        &dir.join("runtime_flow_types"),
+        &module.runtime_flow_types,
+        |ft| &ft.identifier,
+    )?;
     write_each(&dir.join("functions"), &module.function_definitions, |f| {
         &f.runtime_name
     })?;

crates/taurus-core/src/export.rs

@@ -54,6 +54,26 @@ pub struct ModuleMeta {
     pub author: &'static str,
     pub icon: &'static str,
     pub version: &'static str,
+    /// Only built by [`crate::registry::build_modules`] while Taurus is
+    /// running with `ENVIRONMENT=development` (the default) -- lets a module
+    /// still under development self-register without shipping to staging or
+    /// production.
+    pub dev_only: bool,
+}
+
+pub struct FlowTypeMeta {
+    pub identifier: &'static str,
+    /// Identifier of the [`ModuleMeta`] this flow type belongs to.
+    pub module: &'static str,
+    pub name: Vec<Translation>,
+    pub description: Vec<Translation>,
+    pub documentation: Vec<Translation>,
+    pub display_message: Vec<Translation>,
+    pub alias: Vec<Translation>,
+    pub editable: bool,
+    pub display_icon: Option<&'static str>,
+    pub linked_data_type_identifiers: Vec<&'static str>,
+    pub signature: &'static str,
 }
 
 pub struct MetaRegistration(pub fn() -> RuntimeFunctionMeta);
@@ -62,5 +82,8 @@ inventory::collect!(MetaRegistration);
 pub struct DataTypeRegistration(pub fn() -> DataTypeMeta);
 inventory::collect!(DataTypeRegistration);
 
+pub struct FlowTypeRegistration(pub fn() -> FlowTypeMeta);
+inventory::collect!(FlowTypeRegistration);
+
 pub struct ModuleRegistration(pub fn() -> ModuleMeta);
 inventory::collect!(ModuleRegistration);

crates/taurus-core/src/meta.rs

@@ -4,27 +4,51 @@
 //! the result anywhere (Aquila, a file, ...) is a transport concern that
 //! belongs to the caller.
 
+use std::collections::HashSet;
+
+use code0_flow::flow_config::env_with_default;
+use code0_flow::flow_config::environment::Environment;
+
 use crate::meta::{
-    DataTypeMeta, DataTypeRegistration, MetaRegistration, ModuleMeta, ModuleRegistration,
-    RuntimeFunctionMeta,
+    DataTypeMeta, DataTypeRegistration, FlowTypeMeta, FlowTypeRegistration, MetaRegistration,
+    ModuleMeta, ModuleRegistration, RuntimeFunctionMeta,
 };
 use tucana::shared::{
-    DefinitionDataType, FunctionDefinition, Module, ParameterDefinition, RuntimeFunctionDefinition,
-    RuntimeParameterDefinition,
+    DefinitionDataType, FlowType, FunctionDefinition, Module, ParameterDefinition,
+    RuntimeFlowType, RuntimeFunctionDefinition, RuntimeParameterDefinition,
 };
 
-/// Builds every registered module, complete with its function and data-type
-/// definitions. Panics if a function or data type declares a `module` that
+/// Builds every registered module, complete with its function, data-type and
+/// flow-type definitions. Skips modules declared `dev_only` unless Taurus is
+/// running with `ENVIRONMENT=development` (the default), along with anything
+/// that declares one of those modules as its owner.
+///
+/// Panics if a function, data type, or flow type declares a `module` that
 /// has no matching `taurus_macros::module!` registration -- a broken link
 /// between a handler and its owning module is a programming error, not a
-/// runtime condition to recover from.
+/// runtime condition to recover from. This does not apply to modules that
+/// were themselves excluded for being `dev_only`.
 pub fn build_modules() -> Vec<Module> {
+    let is_dev = env_with_default("ENVIRONMENT", Environment::Development) == Environment::Development;
+
+    let mut excluded: HashSet<&'static str> = HashSet::new();
     let mut modules: Vec<Module> = inventory::iter::<ModuleRegistration>()
-        .map(|reg| module_from_meta((reg.0)()))
+        .map(|reg| (reg.0)())
+        .filter_map(|meta| {
+            if meta.dev_only && !is_dev {
+                excluded.insert(meta.identifier);
+                None
+            } else {
+                Some(module_from_meta(meta))
+            }
+        })
         .collect();
 
     for reg in inventory::iter::<MetaRegistration>() {
         let meta = (reg.0)();
+        if excluded.contains(meta.module) {
+            continue;
+        }
         let module = find_module(&mut modules, meta.module, meta.identifier);
         let version = module.version.clone();
         module
@@ -37,13 +61,29 @@ pub fn build_modules() -> Vec<Module> {
 
     for reg in inventory::iter::<DataTypeRegistration>() {
         let meta = (reg.0)();
+        if excluded.contains(meta.module) {
+            continue;
+        }
         let module = find_module(&mut modules, meta.module, meta.identifier);
         let version = module.version.clone();
         module
             .definition_data_types
             .push(data_type_definition(&meta, version));
     }
 
+    for reg in inventory::iter::<FlowTypeRegistration>() {
+        let meta = (reg.0)();
+        if excluded.contains(meta.module) {
+            continue;
+        }
+        let module = find_module(&mut modules, meta.module, meta.identifier);
+        let version = module.version.clone();
+        module
+            .runtime_flow_types
+            .push(runtime_flow_type_definition(&meta, version.clone()));
+        module.flow_types.push(flow_type_definition(&meta, version));
+    }
+
     modules
 }
 
@@ -148,6 +188,51 @@ fn function_definition(meta: &RuntimeFunctionMeta, version: String) -> FunctionD
     }
 }
 
+fn flow_type_definition(meta: &FlowTypeMeta, version: String) -> FlowType {
+    FlowType {
+        identifier: meta.identifier.to_string(),
+        settings: Vec::new(),
+        editable: meta.editable,
+        name: meta.name.clone(),
+        description: meta.description.clone(),
+        documentation: meta.documentation.clone(),
+        display_message: meta.display_message.clone(),
+        alias: meta.alias.clone(),
+        version,
+        display_icon: meta.display_icon.unwrap_or_default().to_string(),
+        definition_source: None,
+        linked_data_type_identifiers: meta
+            .linked_data_type_identifiers
+            .iter()
+            .map(|s| s.to_string())
+            .collect(),
+        signature: meta.signature.to_string(),
+        runtime_identifier: meta.identifier.to_string(),
+    }
+}
+
+fn runtime_flow_type_definition(meta: &FlowTypeMeta, version: String) -> RuntimeFlowType {
+    RuntimeFlowType {
+        identifier: meta.identifier.to_string(),
+        runtime_settings: Vec::new(),
+        editable: meta.editable,
+        name: meta.name.clone(),
+        description: meta.description.clone(),
+        documentation: meta.documentation.clone(),
+        display_message: meta.display_message.clone(),
+        alias: meta.alias.clone(),
+        version,
+        display_icon: meta.display_icon.unwrap_or_default().to_string(),
+        definition_source: None,
+        linked_data_type_identifiers: meta
+            .linked_data_type_identifiers
+            .iter()
+            .map(|s| s.to_string())
+            .collect(),
+        signature: meta.signature.to_string(),
+    }
+}
+
 fn data_type_definition(meta: &DataTypeMeta, version: String) -> DefinitionDataType {
     DefinitionDataType {
         identifier: meta.identifier.to_string(),

crates/taurus-core/src/registry.rs

@@ -0,0 +1,26 @@
+//! Development-only module for exercising flow-type features end-to-end
+//! without touching a real domain module. Only registered while Taurus runs
+//! with `ENVIRONMENT=development` (the default) -- see `dev_only` on
+//! `taurus_macros::module!`.
+
+taurus_macros::module! {
+    identifier = "taurus-dev",
+    name(en_US = "Development"),
+    description(en_US = "Development-only flow types and definitions, not shipped to staging or production."),
+    documentation = "",
+    author = "CodeZero",
+    icon = "tabler:test-pipe",
+    version = "0.0.1",
+    dev_only,
+}
+
+taurus_macros::flow_type! {
+    identifier = "MANUAL",
+    module = "taurus-dev",
+    signature = "(): void",
+    name(en_US = "Manual"),
+    description(en_US = "A flow started manually, with no configurable settings."),
+    display_message(en_US = "Manual"),
+    alias(en_US = "manual;trigger;dev;test"),
+    display_icon = "tabler:test-pipe",
+}

crates/taurus-core/src/runtime/functions/dev.rs

@@ -10,6 +10,7 @@ mod boolean;
 mod color;
 mod control;
 mod date;
+mod dev;
 mod file;
 mod http;
 mod number;

crates/taurus-core/src/runtime/functions/mod.rs

@@ -0,0 +1,53 @@
+//! Expands the function-like `taurus_macros::flow_type! { ... }` macro. Flow
+//! types carry no handler body, like data types -- just metadata.
+
+use proc_macro2::TokenStream;
+use quote::{format_ident, quote};
+
+use crate::parse::{AttrArgs, optional_string, translation_vec};
+
+pub fn expand(input: TokenStream) -> syn::Result<TokenStream> {
+    let args = AttrArgs::parse(input)?;
+
+    let identifier = args.required_string("identifier")?;
+    let module = args.required_string("module")?;
+    let name = translation_vec(&args.translations("name")?);
+    let description = translation_vec(&args.translations("description")?);
+    let documentation = translation_vec(&args.translations("documentation")?);
+    let display_message = translation_vec(&args.translations("display_message")?);
+    let alias = translation_vec(&args.translations("alias")?);
+    let editable = args.flag("editable");
+    let display_icon = optional_string(args.string("display_icon")?);
+    let linked: Vec<String> = args.string_array("linked_data_type_identifiers")?;
+    let signature = args.string("signature")?.unwrap_or_default();
+
+    let meta_fn_ident = format_ident!(
+        "__taurus_flow_type_meta_{}",
+        identifier
+            .to_lowercase()
+            .replace(|c: char| !c.is_ascii_alphanumeric(), "_"),
+    );
+
+    Ok(quote! {
+        #[doc(hidden)]
+        fn #meta_fn_ident() -> crate::meta::FlowTypeMeta {
+            crate::meta::FlowTypeMeta {
+                identifier: #identifier,
+                module: #module,
+                name: #name,
+                description: #description,
+                documentation: #documentation,
+                display_message: #display_message,
+                alias: #alias,
+                editable: #editable,
+                display_icon: #display_icon,
+                linked_data_type_identifiers: vec![#(#linked),*],
+                signature: #signature,
+            }
+        }
+
+        ::inventory::submit! {
+            crate::meta::FlowTypeRegistration(#meta_fn_ident)
+        }
+    })
+}

crates/taurus-macros/src/flow_type.rs

@@ -12,6 +12,7 @@
 //! entry it constructs.
 
 mod data_type;
+mod flow_type;
 mod module;
 mod parse;
 mod runtime_function;
@@ -53,6 +54,12 @@ pub fn data_type(input: TokenStream) -> TokenStream {
     run_fnlike(data_type::expand, input)
 }
 
+/// Declares a flow type (was `flow_types/*.json`).
+#[proc_macro]
+pub fn flow_type(input: TokenStream) -> TokenStream {
+    run_fnlike(flow_type::expand, input)
+}
+
 /// Declares a module (was `module.json`). Exactly one per feature file.
 #[proc_macro]
 pub fn module(input: TokenStream) -> TokenStream {

crates/taurus-macros/src/lib.rs

@@ -17,6 +17,7 @@ pub fn expand(input: TokenStream) -> syn::Result<TokenStream> {
     let author = args.required_string("author")?;
     let icon = args.required_string("icon")?;
     let version = args.required_string("version")?;
+    let dev_only = args.flag("dev_only");
 
     let meta_fn_ident = format_ident!(
         "__taurus_module_meta_{}",
@@ -36,6 +37,7 @@ pub fn expand(input: TokenStream) -> syn::Result<TokenStream> {
                 author: #author,
                 icon: #icon,
                 version: #version,
+                dev_only: #dev_only,
             }
         }