feat: added newest function handler impl

Author: raphael-goetz

crates/taurus-core/src/handler/argument.rs

@@ -0,0 +1,133 @@
+//! Handler argument representation and typed extraction contracts.
+
+use crate::types::errors::runtime_error::RuntimeError;
+use crate::types::signal::Signal;
+use std::convert::Infallible;
+use tucana::shared::value::Kind;
+use tucana::shared::{ListValue, NumberValue, Struct, Value};
+
+use crate::value::{number_to_f64, number_to_i64_lossy};
+#[derive(Clone, Debug)]
+pub enum Argument {
+    /// Eager value that can be consumed immediately by a handler.
+    Eval(Value),
+    /// Deferred node execution handle, evaluated by calling `run(node_id)`.
+    Thunk(i64),
+}
+
+#[derive(Clone, Copy, Debug)]
+pub enum ParameterNode {
+    /// Argument must be resolved before the handler is called.
+    Eager,
+    /// Argument is passed as a thunk and may be executed by the handler.
+    Lazy,
+}
+
+/// Conversion interface used by `args!` to parse typed handler inputs.
+pub trait TryFromArgument: Sized {
+    fn try_from_argument(a: &Argument) -> Result<Self, Signal>;
+}
+
+fn type_err(msg: &str, a: &Argument) -> Signal {
+    Signal::Failure(RuntimeError::new(
+        "T-RT-000000",
+        "InvalidArgumentRuntimeError",
+        format!("{} but it was the arugment: {:?}", msg, a),
+    ))
+}
+
+impl TryFromArgument for Value {
+    fn try_from_argument(a: &Argument) -> Result<Self, Signal> {
+        match a {
+            Argument::Eval(v) => Ok(v.clone()),
+            _ => Err(type_err("Expected evaluated value but got lazy thunk", a)),
+        }
+    }
+}
+
+impl TryFromArgument for NumberValue {
+    fn try_from_argument(a: &Argument) -> Result<Self, Signal> {
+        match a {
+            Argument::Eval(Value {
+                kind: Some(Kind::NumberValue(n)),
+            }) => Ok(*n),
+            _ => Err(type_err("Expected number", a)),
+        }
+    }
+}
+
+impl TryFromArgument for i64 {
+    fn try_from_argument(a: &Argument) -> Result<Self, Signal> {
+        match a {
+            Argument::Eval(Value {
+                kind: Some(Kind::NumberValue(n)),
+            }) => number_to_i64_lossy(n).ok_or_else(|| type_err("Expected number", a)),
+            _ => Err(type_err("Expected number", a)),
+        }
+    }
+}
+
+impl TryFromArgument for f64 {
+    fn try_from_argument(a: &Argument) -> Result<Self, Signal> {
+        match a {
+            Argument::Eval(Value {
+                kind: Some(Kind::NumberValue(n)),
+            }) => number_to_f64(n).ok_or_else(|| type_err("Expected number", a)),
+            _ => Err(type_err("Expected number", a)),
+        }
+    }
+}
+
+impl TryFromArgument for bool {
+    fn try_from_argument(a: &Argument) -> Result<Self, Signal> {
+        match a {
+            Argument::Eval(Value {
+                kind: Some(Kind::BoolValue(b)),
+            }) => Ok(*b),
+            _ => Err(type_err("Expected boolean", a)),
+        }
+    }
+}
+
+impl TryFromArgument for String {
+    fn try_from_argument(a: &Argument) -> Result<Self, Signal> {
+        match a {
+            Argument::Eval(Value {
+                kind: Some(Kind::StringValue(s)),
+            }) => Ok(s.clone()),
+            _ => Err(type_err("Expected string", a)),
+        }
+    }
+}
+
+impl TryFromArgument for Struct {
+    fn try_from_argument(a: &Argument) -> Result<Self, Signal> {
+        match a {
+            Argument::Eval(Value {
+                kind: Some(Kind::StructValue(s)),
+            }) => Ok(s.clone()),
+            _ => Err(type_err("Expected struct", a)),
+        }
+    }
+}
+
+impl TryFromArgument for ListValue {
+    fn try_from_argument(a: &Argument) -> Result<Self, Signal> {
+        match a {
+            Argument::Eval(Value {
+                kind: Some(Kind::ListValue(list)),
+            }) => Ok(list.clone()),
+            _ => Err(Signal::Failure(RuntimeError::new(
+                "T-RT-000000",
+                "InvalidArgumentRuntimeError",
+                format!("Expected array (ListValue) but it was: {:?}", a),
+            ))),
+        }
+    }
+}
+
+impl From<Infallible> for RuntimeError {
+    fn from(never: Infallible) -> Self {
+        match never {}
+    }
+}

crates/taurus-core/src/handler/macros.rs

@@ -0,0 +1,56 @@
+//! Handler argument parsing macros.
+
+/// Pulls typed parameters from a slice of `Argument` using your `TryFromArgument`
+/// impls. Fails early with your `Signal::Failure(RuntimeError::new("T-RT-000000", ...))`.
+macro_rules! args {
+    ($args_ident:ident => $( $name:ident : $ty:ty ),+ $(,)?) => {
+        // Arity check
+        let __expected: usize = 0usize $(+ { let _ = ::core::any::type_name::<$ty>(); 1usize })*;
+        if $args_ident.len() != __expected {
+            return $crate::types::signal::Signal::Failure(
+                $crate::types::errors::runtime_error::RuntimeError::new("T-RT-000000",
+                    "InvalidArgumentRuntimeError",
+                    format!("Expected {__expected} args but received {}", $args_ident.len()),
+                )
+            );
+        }
+
+        // Typed extraction
+        let mut __i: usize = 0;
+        $(
+            let $name: $ty = match <
+                $ty as $crate::handler::argument::TryFromArgument
+            >::try_from_argument(& $args_ident[__i]) {
+                Ok(v) => v,
+                Err(sig) => {
+                    log::debug!(
+                        "Failed to parse argument '{}' (index {}, type {})",
+                        stringify!($name),
+                        __i,
+                        ::core::any::type_name::<$ty>(),
+                    );
+                    return sig;
+                }
+            };
+            __i += 1;
+        )+
+    };
+}
+
+/// Asserts there are no arguments.
+macro_rules! no_args {
+    ($args_ident:ident) => {
+        if !$args_ident.is_empty() {
+            return $crate::types::signal::Signal::Failure(
+                $crate::types::errors::runtime_error::RuntimeError::new(
+                    "T-RT-000000",
+                    "InvalidArgumentRuntimeError",
+                    format!("Expected 0 args but received {}", $args_ident.len()),
+                ),
+            );
+        }
+    };
+}
+
+pub(crate) use args;
+pub(crate) use no_args;

crates/taurus-core/src/handler/mod.rs

@@ -0,0 +1,8 @@
+//! Runtime handler-facing infrastructure.
+//!
+//! This module contains the argument model, extraction macros, and function
+//! registry used to invoke runtime handlers.
+
+pub mod argument;
+pub mod macros;
+pub mod registry;

crates/taurus-core/src/handler/registry.rs

@@ -0,0 +1,124 @@
+//! Runtime handler registry and callable function signatures.
+
+use crate::handler::argument::{Argument, ParameterNode};
+use crate::runtime::execution::value_store::ValueStore;
+use crate::runtime::functions::ALL_FUNCTION_SETS;
+use crate::types::signal::Signal;
+use std::collections::HashMap;
+
+/// Handler function type.
+/// - For eager params, the executor will already convert them to Argument::Eval(Value).
+/// - For lazy params, the executor will pass Argument::Thunk(node_id).
+/// - If a handler wants to execute a lazy arg, it calls run(node_id).
+pub type HandlerFn = fn(
+    args: &[Argument],
+    ctx: &mut ValueStore,
+    run: &mut dyn FnMut(i64, &mut ValueStore) -> Signal,
+) -> Signal;
+
+#[derive(Clone, Copy)]
+pub enum ParamSpec {
+    /// All parameters are evaluated eagerly.
+    AllEager(u8),
+    /// Per-parameter evaluation mode.
+    Explicit(&'static [ParameterNode]),
+}
+
+impl ParamSpec {
+    pub fn mode_at(self, index: usize) -> ParameterNode {
+        match self {
+            ParamSpec::AllEager(_) => ParameterNode::Eager,
+            ParamSpec::Explicit(modes) => modes.get(index).copied().unwrap_or(ParameterNode::Eager),
+        }
+    }
+}
+
+#[derive(Clone, Copy)]
+pub struct HandlerFunctionEntry {
+    /// Callable implementation.
+    pub handler: HandlerFn,
+    /// Evaluation strategy for the handler parameters.
+    pub param_spec: ParamSpec,
+}
+
+impl HandlerFunctionEntry {
+    pub const fn eager(handler: HandlerFn, param_count: u8) -> Self {
+        Self {
+            handler,
+            param_spec: ParamSpec::AllEager(param_count),
+        }
+    }
+
+    pub const fn modes(handler: HandlerFn, param_modes: &'static [ParameterNode]) -> Self {
+        Self {
+            handler,
+            param_spec: ParamSpec::Explicit(param_modes),
+        }
+    }
+
+    pub fn param_mode(&self, index: usize) -> ParameterNode {
+        self.param_spec.mode_at(index)
+    }
+}
+
+#[derive(Clone, Copy)]
+pub struct FunctionRegistration {
+    pub id: &'static str,
+    pub entry: HandlerFunctionEntry,
+}
+
+impl FunctionRegistration {
+    pub const fn eager(id: &'static str, handler: HandlerFn, param_count: u8) -> Self {
+        Self {
+            id,
+            entry: HandlerFunctionEntry::eager(handler, param_count),
+        }
+    }
+
+    pub const fn modes(
+        id: &'static str,
+        handler: HandlerFn,
+        param_modes: &'static [ParameterNode],
+    ) -> Self {
+        Self {
+            id,
+            entry: HandlerFunctionEntry::modes(handler, param_modes),
+        }
+    }
+}
+
+/// Holds all registered handlers.
+pub struct FunctionStore {
+    functions: HashMap<&'static str, HandlerFunctionEntry>,
+}
+
+impl Default for FunctionStore {
+    fn default() -> Self {
+        let mut store = Self::new();
+        for set in ALL_FUNCTION_SETS {
+            store.populate(set);
+        }
+        store
+    }
+}
+
+impl FunctionStore {
+    /// Create a new, empty store.
+    pub fn new() -> Self {
+        FunctionStore {
+            functions: HashMap::new(),
+        }
+    }
+
+    /// Look up a handler by its ID.
+    pub fn get(&self, id: &str) -> Option<&HandlerFunctionEntry> {
+        self.functions.get(id)
+    }
+
+    /// Register a group of handlers.
+    pub fn populate(&mut self, regs: &[FunctionRegistration]) {
+        for reg in regs {
+            self.functions.insert(reg.id, reg.entry);
+        }
+    }
+}