feat: added core sdk

Author: raphael-goetz

README.md

@@ -3,6 +3,7 @@ The action sdk to connect with aquila
 
 This action sdk is currently implemented in:
 - [Typescript](./ts/README.md)
+- [Rust](./rust/README.md)
 
 # GRPC Communcation Flow
 

rust/.gitignore

@@ -0,0 +1 @@
+/target

rust/README.md

@@ -0,0 +1,119 @@
+# hercules
+
+Rust SDK for building Hercules actions that connect to Aquila. An action
+registers the functions it exposes, the events it can fire, and any custom
+data types it needs, then talks to Aquila over a persistent gRPC stream.
+
+Depends on the [`tucana`](https://crates.io/crates/tucana) crate for the
+underlying protobuf types.
+
+**Not yet included:** the `definitions/` standard library (the ~150
+`std::*` function/data-type declarations) and an equivalent of the `hercules
+export` CLI. Both are independent of the core framework and can be added
+later.
+
+## Installation
+
+Not yet published to crates.io — until then, link it locally by path:
+
+```toml
+[dependencies]
+hercules = { path = "../hercules" }
+```
+
+## Quick start
+
+Attach `#[hercules::runtime_function]` to a struct and implement
+`RuntimeFunctionHandler` — that's enough to register it, no separate call
+required:
+
+```rust
+use hercules::{Arguments, FunctionContext, PlainValue, Result, RuntimeFunctionHandler, async_trait};
+
+#[hercules::runtime_function(identifier = "add", signature = "(a: NUMBER, b: NUMBER): NUMBER")]
+struct Add;
+
+#[async_trait]
+impl RuntimeFunctionHandler for Add {
+    async fn run(&self, _ctx: &FunctionContext, args: &Arguments) -> Result<PlainValue> {
+        let a: f64 = args.get("a")?;
+        let b: f64 = args.get("b")?;
+        Ok((a + b).into())
+    }
+}
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    let action = hercules::Action::new("my-action", "0.1.0").aquila_url("127.0.0.1:8081");
+
+    let action = action.connect("token", None).await?;
+    std::future::pending::<()>().await; // keep dispatching execution requests
+    # let _ = action;
+    Ok(())
+}
+```
+
+Only `identifier` and `version` are required on `Action::new` — `author`,
+`icon`, `documentation`, `name`, and `configuration` are optional chained
+setters.
+
+See [`examples/simple-example-rs`](./examples/simple-example-rs) for a
+runnable action exercising every registration kind: a runtime function, its
+public variant, a data type, and a runtime event.
+
+```bash
+cd examples/simple-example-rs
+cp .env.example .env && set -a && source .env && set +a
+cargo run
+```
+
+## Public vs. runtime functions
+
+A `RuntimeFunction` holds the actual implementation. A `Function` is an
+optional, separately-identified public variant of it — same execution
+behavior, its own metadata (identifier, parameter defaults, ...). Use
+`#[hercules::function(base = ...)]` when you want to expose a runtime
+function under different public-facing metadata without duplicating logic:
+
+```rust
+#[hercules::function(base = Add, identifier = "sum")]
+#[parameter(runtime_name = "a", default_value = 0)]
+struct Sum;
+```
+
+Events follow the same pattern: `#[hercules::runtime_event]` for the
+internal definition, `#[hercules::event(base = ...)]` for a public,
+user-facing variant.
+
+## Data types
+
+Data types are derived from a Rust type's `schemars::JsonSchema` impl
+instead of a hand-written schema DSL — `schemars`' own validation attributes
+double as the wire validation rules:
+
+```rust
+use hercules::JsonSchema;
+use serde::{Deserialize, Serialize};
+
+#[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);
+```
+
+## Firing events
+
+```rust
+action.fire("user_created", project_id, serde_json::json!({ "userId": 42 }))?;
+```
+
+The second argument is the project ID the event belongs to; the third is
+the payload matching the event's signature.
+
+## Testing without a live Aquila
+
+`Action::build_module()` returns the wire `Module` without connecting, so
+registration logic (macro-generated metadata, `Function`/`Event` merging,
+data type schema resolution) can be unit tested directly — see
+[`examples/simple-example-rs/src/main.rs`](./examples/simple-example-rs/src/main.rs)'s
+`tests` module for a working example.

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

@@ -2,8 +2,9 @@ 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(...))]`
+/// schema DSL: `#[derive(JsonSchema)]` gives us the structural type
+/// (`"string"`), and `#[schemars(regex(...))]` gives us the validation rule
+/// Aquila enforces on top of it.
 #[hercules::data_type(identifier = "email_address", name(en_US = "Email Address"))]
 #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
 #[serde(transparent)]

rust/hercules-macros/src/lib.rs

@@ -1,11 +1,9 @@
-//! Attribute macros that replace the TS SDK's `reflect-metadata` decorators
-//! (`@Identifier`, `@Signature`, `@Parameter`, ...) with compile-time code
-//! generation: each macro parses its arguments and any repeated
-//! `#[parameter(...)]`/`#[setting(...)]` helper attributes on the annotated
-//! struct, then emits a `meta()` associated function implementing the
-//! corresponding `hercules` trait. No runtime reflection, no metadata
-//! registry — the definition is just a value the macro builds once, at
-//! compile time.
+//! Attribute macros that turn `identifier = "...", name(en_US = "...")`
+//! arguments — plus any repeated `#[parameter(...)]`/`#[setting(...)]` helper
+//! attributes on the annotated struct — into a `meta()` associated function
+//! implementing the corresponding `hercules` trait. Each macro parses its
+//! arguments and generates that function once, at compile time; there's no
+//! runtime reflection or metadata registry involved.
 
 mod data_type;
 mod event;

rust/hercules-macros/src/parse.rs

@@ -128,12 +128,12 @@ impl AttrArgs {
     }
 }
 
-/// Extracts and removes every `#[name(...)]` attribute on `item`, in
-/// source order, parsing each occurrence's arguments as [`AttrArgs`]. This
-/// is how `#[parameter(...)]`/`#[setting(...)]` behave like the TS SDK's
-/// repeatable `@Parameter`/`@EventSetting` decorators: rustc never resolves
-/// them as real attributes because the outer `#[hercules::...]` macro (which
-/// runs first) strips them before re-emitting the struct.
+/// Extracts and removes every `#[name(...)]` attribute on `item`, in source
+/// order, parsing each occurrence's arguments as [`AttrArgs`]. This is how
+/// `#[parameter(...)]`/`#[setting(...)]` can appear multiple times on one
+/// struct: rustc never resolves them as real attributes because the outer
+/// `#[hercules::...]` macro (which runs first) strips them before
+/// re-emitting the struct.
 pub fn take_repeated(item: &mut ItemStruct, name: &str) -> syn::Result<Vec<AttrArgs>> {
     let mut found = Vec::new();
     let mut error = None;

rust/hercules/Cargo.toml

@@ -0,0 +1,24 @@
+[package]
+name = "hercules"
+description = "Rust SDK for the hercules action runner"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[dependencies]
+hercules-macros = { path = "../hercules-macros", version = "0.0.0" }
+tucana.workspace = true
+tokio.workspace = true
+tonic.workspace = true
+async-trait.workspace = true
+thiserror.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+schemars.workspace = true
+tokio-stream.workspace = true
+log.workspace = true
+inventory.workspace = true
+
+[dev-dependencies]
+tokio = { workspace = true, features = ["rt-multi-thread", "macros", "test-util"] }