feat: added example action

Author: raphael-goetz

rust/examples/simple-example-rs/.env.example

@@ -0,0 +1,4 @@
+ACTION_ID=example-action
+VERSION=0.0.0
+AQUILA_URL=127.0.0.1:8081
+AUTH_TOKEN=token

rust/examples/simple-example-rs/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "simple-example-rs"
+version = "0.0.0"
+edition = "2021"
+publish = false
+
+[dependencies]
+hercules = { path = "../../hercules" }
+tokio = { workspace = true, features = ["rt-multi-thread", "macros"] }
+tokio-stream.workspace = true
+serde = { workspace = true }
+serde_json.workspace = true
+schemars.workspace = true
+log.workspace = true
+env_logger = "0.11"
+
+[dev-dependencies]
+tucana.workspace = true

rust/examples/simple-example-rs/src/data_types/email_data_type.rs

@@ -0,0 +1,10 @@
+use hercules::JsonSchema;
+use serde::{Deserialize, Serialize};
+
+/// A data type derived from a real Rust type instead of a hand-written
+/// schema DSL: `#[derive(JsonSchema)]` gives us both the structural type
+/// (`"string"`) and, via `#[schemars(regex(...))]`
+#[hercules::data_type(identifier = "email_address", name(en_US = "Email Address"))]
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[serde(transparent)]
+pub struct EmailAddress(#[schemars(regex(pattern = r"^[^@]+@[^@]+\.[^@]+$"))] pub String);

rust/examples/simple-example-rs/src/data_types/mod.rs

@@ -0,0 +1 @@
+pub mod email_data_type;

rust/examples/simple-example-rs/src/events/mod.rs

@@ -0,0 +1 @@
+pub mod user_created_runtime_event;

rust/examples/simple-example-rs/src/events/user_created_runtime_event.rs

@@ -0,0 +1,10 @@
+#[hercules::runtime_event(
+    identifier = "user_created",
+    signature = "(): { userId: NUMBER }",
+    name(en_US = "User created event"),
+    display_message(en_US = "Triggers on user creation"),
+    description(
+        en_US = "Triggers on user creation and has a payload including the user database id"
+    )
+)]
+pub struct UserCreatedRuntimeEvent;

rust/examples/simple-example-rs/src/functions/fibonacci_function.rs

@@ -0,0 +1,14 @@
+use super::fibonacci_runtime_function::FibonacciRuntimeFunction;
+
+/// The public, user-facing variant of [`FibonacciRuntimeFunction`]: same
+/// execution behavior, its own identifier and a default input value.
+/// Execution always dispatches through the runtime function — this struct
+/// carries no `run()` of its own, only metadata overrides.
+#[hercules::function(base = FibonacciRuntimeFunction, identifier = "fibonacci")]
+#[parameter(
+    runtime_name = "test",
+    name(en_US = "Input Number"),
+    description(en_US = "The position in the Fibonacci sequence"),
+    default_value = 10
+)]
+pub struct FibonacciFunction;

rust/examples/simple-example-rs/src/functions/fibonacci_runtime_function.rs

@@ -0,0 +1,37 @@
+use hercules::{
+    async_trait, Arguments, FunctionContext, PlainValue, Result, RuntimeFunctionHandler,
+};
+
+#[hercules::runtime_function(
+    identifier = "fibonacci_runtime",
+    signature = "(test: NUMBER): NUMBER",
+    name(en_US = "Fibonacci (Runtime)"),
+    display_message(en_US = "Computes the n-th Fibonacci number"),
+    omit_definition
+)]
+#[parameter(runtime_name = "test", name(en_US = "N"))]
+pub struct FibonacciRuntimeFunction;
+
+#[async_trait]
+impl RuntimeFunctionHandler for FibonacciRuntimeFunction {
+    async fn run(&self, context: &FunctionContext, args: &Arguments) -> Result<PlainValue> {
+        // Missing or malformed, `args.get` reports it back to Aquila as a
+        // runtime error on its own — nothing to check by hand here.
+        let n: u64 = args.get("test")?;
+
+        log::debug!(
+            "computing fibonacci({n}) for project={} execution={}",
+            context.project_id,
+            context.execution_id
+        );
+        Ok(fib(n).into())
+    }
+}
+
+fn fib(n: u64) -> u64 {
+    if n <= 1 {
+        n
+    } else {
+        fib(n - 1) + fib(n - 2)
+    }
+}

rust/examples/simple-example-rs/src/functions/mod.rs

@@ -0,0 +1,2 @@
+pub mod fibonacci_function;
+pub mod fibonacci_runtime_function;

rust/examples/simple-example-rs/src/main.rs

@@ -0,0 +1,119 @@
+mod data_types;
+mod events;
+mod functions;
+
+use hercules::{Action, ConfigurationDefinition, HerculesEvent, Translation};
+use tokio_stream::StreamExt;
+
+fn env(key: &str, default: &str) -> String {
+    std::env::var(key).unwrap_or_else(|_| default.to_string())
+}
+
+/// `FibonacciRuntimeFunction`, `FibonacciFunction`, `EmailAddress` and
+/// `UserCreatedRuntimeEvent` never appear below — attaching
+/// `#[hercules::runtime_function]` / `function` / `data_type` /
+/// `runtime_event` registered each of them automatically as part of
+/// `Action::new` (see `hercules::registration`). There's simply nothing left
+/// to wire up by hand for this example.
+fn build_action() -> Action {
+    Action::new(env("ACTION_ID", "example-action"), env("VERSION", "0.0.0"))
+        .aquila_url(env("AQUILA_URL", "127.0.0.1:8081"))
+        .author("code0-tech")
+        .icon("tabler:bolt")
+        .documentation("A simple example action")
+        .name([Translation::new("en-US", "Example Action")])
+        .configuration(
+            ConfigurationDefinition::new("EXAMPLE_CONFIG", "string")
+                .name([Translation::new("en-US", "Example Config")]),
+        )
+}
+
+#[tokio::main]
+async fn main() -> hercules::Result<()> {
+    // RUST_LOG=hercules=debug,simple_example_rs=debug cargo run
+    env_logger::init();
+
+    let action = build_action();
+    let mut events = action.subscribe();
+
+    // The returned `Connected` handle can be discarded immediately: the
+    // background dispatch task (started inside `connect`) holds its own
+    // `Arc` to the shared connection state, so nothing here needs to keep
+    // it alive.
+    action
+        .connect(env("AUTH_TOKEN", "token"), None)
+        .await
+        .unwrap_or_else(|err| panic!("failed to connect to Aquila: {err}"));
+
+    // React to connection lifecycle events on the main task for as long as
+    // the process runs. Panicking here (unlike inside a spawned task) takes
+    // the whole process down on an unrecoverable stream error.
+    while let Some(event) = events.next().await {
+        match event {
+            HerculesEvent::Connected => log::info!("connected to Aquila"),
+            HerculesEvent::Error(error) => panic!("Aquila stream error: {error}"),
+            _ => {}
+        }
+    }
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use hercules::wire::Module;
+
+    use super::build_action;
+
+    /// Exercises the real registration path end to end — link-time
+    /// `inventory` auto-registration, `Function`/`RuntimeFunction` merging,
+    /// and `schemars`-driven data type resolution — by building the wire
+    /// `Module` without connecting.
+    #[test]
+    fn builds_a_well_formed_module() {
+        let module: Module = build_action().build_module();
+
+        assert_eq!(module.identifier, "example-action");
+
+        let email = module
+            .definition_data_types
+            .iter()
+            .find(|dt| dt.identifier == "email_address")
+            .expect("email_address data type");
+        assert_eq!(email.r#type, "string");
+        assert!(matches!(
+            email.rules.first().and_then(|r| r.config.clone()),
+            Some(tucana::shared::definition_data_type_rule::Config::Regex(_))
+        ));
+
+        let fibonacci = module
+            .function_definitions
+            .iter()
+            .find(|f| f.runtime_name == "fibonacci")
+            .expect("fibonacci function");
+        assert_eq!(fibonacci.runtime_definition_name, "fibonacci_runtime");
+        let param = &fibonacci.parameter_definitions[0];
+        assert_eq!(param.runtime_name, "test");
+        assert_eq!(
+            param.default_value.as_ref().and_then(|v| v.kind.clone()),
+            Some(tucana::shared::value::Kind::NumberValue(
+                tucana::shared::NumberValue {
+                    number: Some(tucana::shared::number_value::Number::Integer(10))
+                }
+            ))
+        );
+
+        // omit_definition on the runtime function means it isn't separately
+        // published under its own identifier.
+        assert!(module
+            .function_definitions
+            .iter()
+            .all(|f| f.runtime_name != "fibonacci_runtime"));
+        assert_eq!(
+            module.runtime_function_definitions[0].runtime_name,
+            "fibonacci_runtime"
+        );
+
+        assert_eq!(module.runtime_flow_types[0].identifier, "user_created");
+    }
+}