blokctl 1.3.0 → 1.4.1

package/dist/scaffold-repo/sdks/rust/src/logging.rs

@@ -0,0 +1,195 @@
+use serde::{Deserialize, Serialize};
+use std::sync::{Arc, Mutex};
+
+/// Log level for structured logging.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
+pub enum LogLevel {
+    #[serde(rename = "DEBUG")]
+    Debug = 0,
+    #[serde(rename = "INFO")]
+    Info = 1,
+    #[serde(rename = "WARN")]
+    Warn = 2,
+    #[serde(rename = "ERROR")]
+    Error = 3,
+}
+
+/// A single log entry.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct LogEntry {
+    pub level: LogLevel,
+    pub message: String,
+    pub timestamp: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub fields: Option<serde_json::Value>,
+}
+
+impl std::fmt::Display for LogEntry {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        let level = match self.level {
+            LogLevel::Debug => "DEBUG",
+            LogLevel::Info => "INFO",
+            LogLevel::Warn => "WARN",
+            LogLevel::Error => "ERROR",
+        };
+        match &self.fields {
+            Some(fields) => write!(f, "[{}] {} {} {}", level, self.timestamp, self.message, fields),
+            None => write!(f, "[{}] {} {}", level, self.timestamp, self.message),
+        }
+    }
+}
+
+/// Logger captures log entries for inclusion in ExecutionResult.logs.
+///
+/// Thread-safe and cheaply cloneable (uses Arc<Mutex>).
+#[derive(Debug, Clone)]
+pub struct Logger {
+    entries: Arc<Mutex<Vec<LogEntry>>>,
+    min_level: LogLevel,
+}
+
+impl Logger {
+    /// Create a new logger with the specified minimum level.
+    pub fn new(min_level: LogLevel) -> Self {
+        Self {
+            entries: Arc::new(Mutex::new(Vec::new())),
+            min_level,
+        }
+    }
+
+    fn log(&self, level: LogLevel, message: impl Into<String>, fields: Option<serde_json::Value>) {
+        if level < self.min_level {
+            return;
+        }
+        let entry = LogEntry {
+            level,
+            message: message.into(),
+            timestamp: chrono::Utc::now().to_rfc3339(),
+            fields,
+        };
+        self.entries.lock().unwrap().push(entry);
+    }
+
+    /// Log a debug message.
+    pub fn debug(&self, message: impl Into<String>) {
+        self.log(LogLevel::Debug, message, None);
+    }
+
+    /// Log a debug message with fields.
+    pub fn debug_with(&self, message: impl Into<String>, fields: serde_json::Value) {
+        self.log(LogLevel::Debug, message, Some(fields));
+    }
+
+    /// Log an info message.
+    pub fn info(&self, message: impl Into<String>) {
+        self.log(LogLevel::Info, message, None);
+    }
+
+    /// Log an info message with fields.
+    pub fn info_with(&self, message: impl Into<String>, fields: serde_json::Value) {
+        self.log(LogLevel::Info, message, Some(fields));
+    }
+
+    /// Log a warning message.
+    pub fn warn(&self, message: impl Into<String>) {
+        self.log(LogLevel::Warn, message, None);
+    }
+
+    /// Log a warning message with fields.
+    pub fn warn_with(&self, message: impl Into<String>, fields: serde_json::Value) {
+        self.log(LogLevel::Warn, message, Some(fields));
+    }
+
+    /// Log an error message.
+    pub fn error(&self, message: impl Into<String>) {
+        self.log(LogLevel::Error, message, None);
+    }
+
+    /// Log an error message with fields.
+    pub fn error_with(&self, message: impl Into<String>, fields: serde_json::Value) {
+        self.log(LogLevel::Error, message, Some(fields));
+    }
+
+    /// Get all captured log entries.
+    pub fn entries(&self) -> Vec<LogEntry> {
+        self.entries.lock().unwrap().clone()
+    }
+
+    /// Get log entries as formatted strings for ExecutionResult.logs.
+    pub fn lines(&self) -> Vec<String> {
+        self.entries
+            .lock()
+            .unwrap()
+            .iter()
+            .map(|e| e.to_string())
+            .collect()
+    }
+
+    /// Clear all captured entries.
+    pub fn clear(&self) {
+        self.entries.lock().unwrap().clear();
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_logger_level_filtering() {
+        let logger = Logger::new(LogLevel::Info);
+        logger.debug("hidden");
+        logger.info("visible");
+        logger.warn("visible");
+        logger.error("visible");
+
+        assert_eq!(logger.entries().len(), 3);
+    }
+
+    #[test]
+    fn test_logger_debug_level() {
+        let logger = Logger::new(LogLevel::Debug);
+        logger.debug("visible");
+        assert_eq!(logger.entries().len(), 1);
+    }
+
+    #[test]
+    fn test_logger_with_fields() {
+        let logger = Logger::new(LogLevel::Debug);
+        logger.info_with("test", serde_json::json!({"key": "value"}));
+
+        let entries = logger.entries();
+        assert_eq!(entries.len(), 1);
+        assert!(entries[0].fields.is_some());
+    }
+
+    #[test]
+    fn test_logger_lines() {
+        let logger = Logger::new(LogLevel::Debug);
+        logger.info("hello");
+        logger.error("oops");
+
+        let lines = logger.lines();
+        assert_eq!(lines.len(), 2);
+        assert!(lines[0].contains("[INFO]"));
+        assert!(lines[1].contains("[ERROR]"));
+    }
+
+    #[test]
+    fn test_logger_clear() {
+        let logger = Logger::new(LogLevel::Debug);
+        logger.info("test");
+        assert_eq!(logger.entries().len(), 1);
+        logger.clear();
+        assert_eq!(logger.entries().len(), 0);
+    }
+
+    #[test]
+    fn test_logger_is_clone_safe() {
+        let logger = Logger::new(LogLevel::Debug);
+        let cloned = logger.clone();
+        logger.info("from original");
+        cloned.info("from clone");
+        assert_eq!(logger.entries().len(), 2);
+    }
+}

package/dist/scaffold-repo/sdks/rust/src/main.rs

@@ -0,0 +1,79 @@
+use tracing::info;
+use tracing_subscriber::EnvFilter;
+
+use blok::config::ServerConfig;
+use blok::logging::{LogLevel, Logger};
+use blok::middleware::LoggingMiddleware;
+use blok::nodes;
+use blok::registry::NodeRegistry;
+
+// User nodes scaffolded under runtimes/rust/nodes. The committed default is a
+// no-op; `blokctl dev` regenerates src/user_nodes/ in the project's
+// .blok/runtimes/rust copy with one module per user node.
+mod user_nodes;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Initialize tracing
+    tracing_subscriber::fmt()
+        .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new("info")))
+        .init();
+
+    let config = ServerConfig::from_env();
+
+    // Create registry and register nodes
+    let mut registry = NodeRegistry::new(&config.version);
+    nodes::register_all(&mut registry);
+    user_nodes::register_user_nodes(&mut registry);
+
+    // Add middleware
+    let logger = Logger::new(LogLevel::Info);
+    registry.use_middleware(LoggingMiddleware::new(logger));
+
+    info!(
+        "Blok Rust Runtime v{} — {} node(s) registered",
+        config.version,
+        registry.len()
+    );
+
+    #[cfg(feature = "grpc")]
+    if config.enable_grpc {
+        use std::sync::Arc;
+        use tokio::sync::Mutex;
+
+        // Build a separate registry per transport. `serve()` takes ownership;
+        // `serve_grpc()` takes a shared `Arc<Mutex<…>>`. Both are populated
+        // via `nodes::register_all` so they expose the same node set.
+        let mut grpc_registry = NodeRegistry::new(&config.version);
+        nodes::register_all(&mut grpc_registry);
+        user_nodes::register_user_nodes(&mut grpc_registry);
+        let grpc_shared = Arc::new(Mutex::new(grpc_registry));
+
+        let mut http_registry = NodeRegistry::new(&config.version);
+        nodes::register_all(&mut http_registry);
+        user_nodes::register_user_nodes(&mut http_registry);
+
+        let version = config.version.clone();
+
+        tokio::select! {
+            result = blok::server::serve(http_registry, config.port) => {
+                result?;
+            }
+            result = blok::grpc_server::serve_grpc(grpc_shared, config.grpc_port, version, config.grpc_max_message_bytes) => {
+                result.map_err(|e| -> Box<dyn std::error::Error> { e })?;
+            }
+        }
+
+        // Suppress dead-code warning when `grpc` is built but `enable_grpc=false`.
+        let _ = registry;
+    } else {
+        blok::server::serve(registry, config.port).await?;
+    }
+
+    #[cfg(not(feature = "grpc"))]
+    {
+        blok::server::serve(registry, config.port).await?;
+    }
+
+    Ok(())
+}

package/dist/scaffold-repo/sdks/rust/src/middleware.rs

@@ -0,0 +1,181 @@
+use async_trait::async_trait;
+use std::collections::HashMap;
+use std::sync::Arc;
+use std::time::{Duration, Instant};
+
+use crate::logging::Logger;
+use crate::node::NodeHandler;
+use crate::types::Context;
+
+/// Middleware wraps a NodeHandler to add cross-cutting behavior.
+#[async_trait]
+pub trait Middleware: Send + Sync {
+    /// Wrap a handler and return a new handler with additional behavior.
+    fn wrap(&self, handler: Arc<dyn NodeHandler>) -> Arc<dyn NodeHandler>;
+}
+
+/// LoggingMiddleware logs node execution with timing.
+pub struct LoggingMiddleware {
+    logger: Logger,
+}
+
+impl LoggingMiddleware {
+    pub fn new(logger: Logger) -> Self {
+        Self { logger }
+    }
+}
+
+#[async_trait]
+impl Middleware for LoggingMiddleware {
+    fn wrap(&self, handler: Arc<dyn NodeHandler>) -> Arc<dyn NodeHandler> {
+        Arc::new(LoggingHandler {
+            inner: handler,
+            logger: self.logger.clone(),
+        })
+    }
+}
+
+struct LoggingHandler {
+    inner: Arc<dyn NodeHandler>,
+    logger: Logger,
+}
+
+#[async_trait]
+impl NodeHandler for LoggingHandler {
+    async fn execute(
+        &self,
+        ctx: &mut Context,
+        config: &HashMap<String, serde_json::Value>,
+    ) -> Result<serde_json::Value, Box<dyn std::error::Error + Send + Sync>> {
+        let start = Instant::now();
+        self.logger.info_with(
+            "node execution started",
+            serde_json::json!({"workflow": &ctx.workflow_name}),
+        );
+
+        let result = self.inner.execute(ctx, config).await;
+        let duration = start.elapsed();
+
+        match &result {
+            Ok(_) => self.logger.info_with(
+                "node execution completed",
+                serde_json::json!({
+                    "workflow": &ctx.workflow_name,
+                    "duration_ms": duration.as_secs_f64() * 1000.0,
+                }),
+            ),
+            Err(e) => self.logger.error_with(
+                "node execution failed",
+                serde_json::json!({
+                    "workflow": &ctx.workflow_name,
+                    "duration_ms": duration.as_secs_f64() * 1000.0,
+                    "error": e.to_string(),
+                }),
+            ),
+        }
+
+        result
+    }
+}
+
+/// TimeoutMiddleware enforces a maximum execution duration.
+pub struct TimeoutMiddleware {
+    timeout: Duration,
+}
+
+impl TimeoutMiddleware {
+    pub fn new(timeout: Duration) -> Self {
+        Self { timeout }
+    }
+}
+
+#[async_trait]
+impl Middleware for TimeoutMiddleware {
+    fn wrap(&self, handler: Arc<dyn NodeHandler>) -> Arc<dyn NodeHandler> {
+        Arc::new(TimeoutHandler {
+            inner: handler,
+            timeout: self.timeout,
+        })
+    }
+}
+
+struct TimeoutHandler {
+    inner: Arc<dyn NodeHandler>,
+    timeout: Duration,
+}
+
+#[async_trait]
+impl NodeHandler for TimeoutHandler {
+    async fn execute(
+        &self,
+        ctx: &mut Context,
+        config: &HashMap<String, serde_json::Value>,
+    ) -> Result<serde_json::Value, Box<dyn std::error::Error + Send + Sync>> {
+        match tokio::time::timeout(self.timeout, self.inner.execute(ctx, config)).await {
+            Ok(result) => result,
+            Err(_) => Err(format!(
+                "execution timed out after {:?}",
+                self.timeout
+            )
+            .into()),
+        }
+    }
+}
+
+/// Apply a chain of middleware to a handler.
+pub fn apply_middleware(
+    handler: Arc<dyn NodeHandler>,
+    middlewares: &[Arc<dyn Middleware>],
+) -> Arc<dyn NodeHandler> {
+    let mut current = handler;
+    for mw in middlewares {
+        current = mw.wrap(current);
+    }
+    current
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::logging::LogLevel;
+    use crate::testing::MockContext;
+
+    struct EchoNode;
+
+    #[async_trait]
+    impl NodeHandler for EchoNode {
+        async fn execute(
+            &self,
+            _ctx: &mut Context,
+            _config: &HashMap<String, serde_json::Value>,
+        ) -> Result<serde_json::Value, Box<dyn std::error::Error + Send + Sync>> {
+            Ok(serde_json::json!("echo"))
+        }
+    }
+
+    #[tokio::test]
+    async fn test_logging_middleware() {
+        let logger = Logger::new(LogLevel::Debug);
+        let mw = LoggingMiddleware::new(logger.clone());
+
+        let handler: Arc<dyn NodeHandler> = Arc::new(EchoNode);
+        let wrapped = mw.wrap(handler);
+
+        let mut ctx = MockContext::new().build();
+        let result = wrapped.execute(&mut ctx, &HashMap::new()).await;
+
+        assert!(result.is_ok());
+        assert!(logger.entries().len() >= 2);
+    }
+
+    #[tokio::test]
+    async fn test_timeout_middleware_fast() {
+        let mw = TimeoutMiddleware::new(Duration::from_secs(5));
+        let handler: Arc<dyn NodeHandler> = Arc::new(EchoNode);
+        let wrapped = mw.wrap(handler);
+
+        let mut ctx = MockContext::new().build();
+        let result = wrapped.execute(&mut ctx, &HashMap::new()).await;
+        assert!(result.is_ok());
+    }
+}

package/dist/scaffold-repo/sdks/rust/src/node.rs

@@ -0,0 +1,172 @@
+use async_trait::async_trait;
+use std::collections::HashMap;
+
+use crate::blok_error::BlokError;
+use crate::types::Context;
+
+/// NodeHandler is the core trait that all Blok nodes must implement.
+///
+/// # Example
+///
+/// ```rust
+/// use async_trait::async_trait;
+/// use blok::{NodeHandler, Context};
+/// use std::collections::HashMap;
+///
+/// struct MyNode;
+///
+/// #[async_trait]
+/// impl NodeHandler for MyNode {
+///     async fn execute(
+///         &self,
+///         ctx: &mut Context,
+///         config: &HashMap<String, serde_json::Value>,
+///     ) -> Result<serde_json::Value, Box<dyn std::error::Error + Send + Sync>> {
+///         let name = ctx.request.body_str("name").unwrap_or("World");
+///         Ok(serde_json::json!({ "message": format!("Hello, {}!", name) }))
+///     }
+/// }
+/// ```
+#[async_trait]
+pub trait NodeHandler: Send + Sync {
+    /// Execute the node logic with the given workflow context and node configuration.
+    async fn execute(
+        &self,
+        ctx: &mut Context,
+        config: &HashMap<String, serde_json::Value>,
+    ) -> Result<serde_json::Value, Box<dyn std::error::Error + Send + Sync>>;
+
+    /// v0.7 — human-readable description, surfaced in the node catalog
+    /// (`GET /__blok/nodes`). Default empty; `TypedNode` overrides it.
+    fn description(&self) -> &str {
+        ""
+    }
+
+    /// v0.7 — JSON Schema for this node's input, for the catalog / gRPC
+    /// `ListNodes` reflection (SPEC-B P3). Default `None`; the typed contract
+    /// (`TypedNode`) returns the derived schema.
+    fn input_schema(&self) -> Option<serde_json::Value> {
+        None
+    }
+
+    /// v0.7 — JSON Schema for this node's output. See [`Self::input_schema`].
+    fn output_schema(&self) -> Option<serde_json::Value> {
+        None
+    }
+}
+
+/// ValidatedNodeHandler extends NodeHandler with input/output schema support.
+#[async_trait]
+pub trait ValidatedNodeHandler: NodeHandler {
+    /// Return the JSON Schema for validating input (request body).
+    /// Return None to skip input validation.
+    fn input_schema(&self) -> Option<serde_json::Value> {
+        None
+    }
+
+    /// Return the JSON Schema for validating output (result data).
+    /// Return None to skip output validation.
+    fn output_schema(&self) -> Option<serde_json::Value> {
+        None
+    }
+}
+
+/// `TypedNode` — the typed authoring contract (SPEC-B P3), the Rust equivalent of
+/// the TypeScript `defineNode` / Python `@node`. Declare typed `Input`/`Output`
+/// (deriving `serde` + `schemars::JsonSchema`); the SDK validates `config ->
+/// Input` BEFORE `run`, serializes the `Output`, and reflects both JSON Schemas
+/// via gRPC `ListNodes` — instead of a raw `HashMap<String, serde_json::Value>`.
+///
+/// Register with `NodeRegistry::register_typed`, or wrap with
+/// [`TypedNodeHandler`] and register as a normal `NodeHandler`.
+///
+/// ```ignore
+/// #[derive(serde::Deserialize, schemars::JsonSchema)]
+/// struct Input { query: String, #[serde(default)] limit: u32 }
+/// #[derive(serde::Serialize, schemars::JsonSchema)]
+/// struct Output { results: Vec<String>, count: usize }
+///
+/// struct Search;
+/// #[async_trait::async_trait]
+/// impl blok::TypedNode for Search {
+///     type Input = Input;
+///     type Output = Output;
+///     fn name(&self) -> &str { "@acme/search" }
+///     fn description(&self) -> &str { "Full-text search" }
+///     async fn run(&self, _ctx: &mut blok::Context, input: Input) -> Result<Output, blok::BlokError> {
+///         let results = vec![input.query];
+///         Ok(Output { count: results.len(), results })
+///     }
+/// }
+/// ```
+#[async_trait]
+pub trait TypedNode: Send + Sync {
+    /// Validated, typed input — `serde::Deserialize` + `schemars::JsonSchema`.
+    type Input: serde::de::DeserializeOwned + schemars::JsonSchema + Send;
+    /// Typed output — `serde::Serialize` + `schemars::JsonSchema`.
+    type Output: serde::Serialize + schemars::JsonSchema + Send;
+
+    /// The node's registered name (e.g. `"@acme/search"`).
+    fn name(&self) -> &str;
+
+    /// Human-readable description (surfaced in the node catalog).
+    fn description(&self) -> &str {
+        ""
+    }
+
+    /// Run the node with a VALIDATED, typed input.
+    async fn run(&self, ctx: &mut Context, input: Self::Input) -> Result<Self::Output, BlokError>;
+}
+
+/// Adapts a [`TypedNode`] into a [`NodeHandler`]: deserializes `config -> Input`
+/// (a failure becomes a structured `BlokError`, HTTP 400), runs it, serializes
+/// the `Output`, and exposes both JSON Schemas. A distinct concrete type, so it
+/// never conflicts with hand-written `impl NodeHandler for …` blocks.
+pub struct TypedNodeHandler<T: TypedNode>(pub T);
+
+#[async_trait]
+impl<T: TypedNode> NodeHandler for TypedNodeHandler<T> {
+    async fn execute(
+        &self,
+        ctx: &mut Context,
+        config: &HashMap<String, serde_json::Value>,
+    ) -> Result<serde_json::Value, Box<dyn std::error::Error + Send + Sync>> {
+        let value = serde_json::to_value(config)
+            .map_err(|e| Box::new(e) as Box<dyn std::error::Error + Send + Sync>)?;
+
+        let input: T::Input = serde_json::from_value(value).map_err(|e| {
+            Box::new(
+                BlokError::validation()
+                    .code("NODE_INPUT_VALIDATION")
+                    .message(format!(
+                        "Input validation failed for node '{}': {}",
+                        self.0.name(),
+                        e
+                    ))
+                    .http_status(400)
+                    .node(self.0.name())
+                    .build(),
+            ) as Box<dyn std::error::Error + Send + Sync>
+        })?;
+
+        let output = self
+            .0
+            .run(ctx, input)
+            .await
+            .map_err(|e| Box::new(e) as Box<dyn std::error::Error + Send + Sync>)?;
+
+        serde_json::to_value(output).map_err(|e| Box::new(e) as Box<dyn std::error::Error + Send + Sync>)
+    }
+
+    fn description(&self) -> &str {
+        self.0.description()
+    }
+
+    fn input_schema(&self) -> Option<serde_json::Value> {
+        serde_json::to_value(schemars::schema_for!(T::Input)).ok()
+    }
+
+    fn output_schema(&self) -> Option<serde_json::Value> {
+        serde_json::to_value(schemars::schema_for!(T::Output)).ok()
+    }
+}