tasker-rb 0.1.1

data/ext/tasker_core/src/ffi_logging.rs

@@ -0,0 +1,245 @@
+//! FFI-specific logging module using unified logging patterns
+//!
+//! This module provides structured logging for FFI boundary debugging
+//! using the unified logging macros that match Ruby patterns.
+//!
+//! ## TAS-29 Phase 6: Ruby FFI Logging Bridge
+//!
+//! This module exposes Rust's tracing infrastructure to Ruby via FFI, enabling
+//! unified structured logging across both Ruby and Rust components.
+//!
+//! ### Architecture
+//!
+//! ```text
+//! Ruby Handler
+//!     ↓
+//! TaskerCore::Tracing.info("message", fields: {...})
+//!     ↓
+//! FFI Bridge (this module)
+//!     ↓
+//! tasker_shared::log_ffi! macro
+//!     ↓
+//! tracing crate → OpenTelemetry (if enabled)
+//! ```
+//!
+//! ### Log Levels
+//!
+//! - ERROR: Unrecoverable failures requiring intervention
+//! - WARN: Degraded operation, retryable failures
+//! - INFO: Lifecycle events, state transitions
+//! - DEBUG: Detailed diagnostic information
+//! - TRACE: Very verbose, hot-path entry/exit
+
+use magnus::{value::ReprValue, Error, RHash, Value};
+use std::collections::HashMap;
+use tracing::{debug, error, info, trace, warn};
+
+/// Initialize FFI logging using two-phase pattern for telemetry support
+///
+/// # Two-Phase Initialization Pattern (TAS-65)
+///
+/// This function implements phase 1 of the FFI telemetry initialization pattern:
+///
+/// **Phase 1 (This function)**: Called during Magnus initialization (no Tokio runtime)
+/// - If TELEMETRY_ENABLED=false: Initialize console-only logging (safe, no runtime needed)
+/// - If TELEMETRY_ENABLED=true: Skip initialization (will be done in phase 2)
+///
+/// **Phase 2**: Called in `bootstrap_worker()` after Tokio runtime creation
+/// - Always call `init_tracing()` in `runtime.block_on()` context
+/// - If console already initialized: Returns early (no-op)
+/// - If not initialized (telemetry case): Initializes with OpenTelemetry in Tokio context
+///
+/// # Why This Pattern?
+///
+/// OpenTelemetry batch exporter requires a Tokio runtime context for async I/O.
+/// During Magnus initialization, no Tokio runtime exists yet, so we defer full
+/// initialization until after the runtime is created in `bootstrap_worker()`.
+///
+/// This pattern works for all FFI targets:
+/// - Ruby (Magnus): Same pattern
+/// - Python (PyO3): Same pattern
+/// - WASM: Same pattern
+pub fn init_ffi_logger() -> Result<(), Box<dyn std::error::Error>> {
+    // Check if telemetry is enabled
+    let telemetry_enabled = std::env::var("TELEMETRY_ENABLED")
+        .map(|v| v.to_lowercase() == "true")
+        .unwrap_or(false);
+
+    if telemetry_enabled {
+        // Phase 1: Telemetry enabled - skip logging init
+        // Will be initialized in bootstrap_worker() after runtime creation
+        println!("📡 TAS-65: Telemetry enabled - deferring logging init to runtime context");
+    } else {
+        // Phase 1: Telemetry disabled - safe to initialize console-only logging
+        tasker_shared::logging::init_console_only();
+
+        // Use unified logging macro
+        tasker_shared::log_ffi!(
+            info,
+            "FFI console logging initialized (no telemetry)",
+            component: "ffi_boundary"
+        );
+    }
+
+    Ok(())
+}
+
+/// Convert Ruby hash to Rust `HashMap` for structured fields
+fn ruby_hash_to_map(hash: RHash) -> Result<HashMap<String, String>, Error> {
+    let mut map = HashMap::new();
+
+    hash.foreach(|key: Value, value: Value| {
+        let key_str = key.to_r_string()?.to_string()?;
+        let value_str = value.to_r_string()?.to_string()?;
+        map.insert(key_str, value_str);
+        Ok(magnus::r_hash::ForEach::Continue)
+    })?;
+
+    Ok(map)
+}
+
+/// Log ERROR level message with structured fields (Ruby FFI)
+///
+/// # Ruby Usage
+/// ```ruby
+/// TaskerCore.log_error("Task processing failed", {
+///   correlation_id: correlation_id,
+///   task_uuid: task_uuid,
+///   error_message: error.message
+/// })
+/// ```
+pub fn log_error(message: String, fields: RHash) -> Result<(), Error> {
+    let fields_map = ruby_hash_to_map(fields)?;
+
+    // Extract common fields for structured logging
+    let correlation_id = fields_map.get("correlation_id").cloned();
+    let task_uuid = fields_map.get("task_uuid").cloned();
+    let step_uuid = fields_map.get("step_uuid").cloned();
+    let namespace = fields_map.get("namespace").cloned();
+    let operation = fields_map
+        .get("operation")
+        .cloned()
+        .unwrap_or_else(|| "ruby_handler".to_string());
+
+    // Log with structured fields
+    error!(
+        correlation_id = correlation_id.as_deref(),
+        task_uuid = task_uuid.as_deref(),
+        step_uuid = step_uuid.as_deref(),
+        namespace = namespace.as_deref(),
+        operation = %operation,
+        component = "ruby_ffi",
+        "{}",
+        message
+    );
+
+    Ok(())
+}
+
+/// Log WARN level message with structured fields (Ruby FFI)
+pub fn log_warn(message: String, fields: RHash) -> Result<(), Error> {
+    let fields_map = ruby_hash_to_map(fields)?;
+
+    let correlation_id = fields_map.get("correlation_id").cloned();
+    let task_uuid = fields_map.get("task_uuid").cloned();
+    let step_uuid = fields_map.get("step_uuid").cloned();
+    let namespace = fields_map.get("namespace").cloned();
+    let operation = fields_map
+        .get("operation")
+        .cloned()
+        .unwrap_or_else(|| "ruby_handler".to_string());
+
+    warn!(
+        correlation_id = correlation_id.as_deref(),
+        task_uuid = task_uuid.as_deref(),
+        step_uuid = step_uuid.as_deref(),
+        namespace = namespace.as_deref(),
+        operation = %operation,
+        component = "ruby_ffi",
+        "{}",
+        message
+    );
+
+    Ok(())
+}
+
+/// Log INFO level message with structured fields (Ruby FFI)
+pub fn log_info(message: String, fields: RHash) -> Result<(), Error> {
+    let fields_map = ruby_hash_to_map(fields)?;
+
+    let correlation_id = fields_map.get("correlation_id").cloned();
+    let task_uuid = fields_map.get("task_uuid").cloned();
+    let step_uuid = fields_map.get("step_uuid").cloned();
+    let namespace = fields_map.get("namespace").cloned();
+    let operation = fields_map
+        .get("operation")
+        .cloned()
+        .unwrap_or_else(|| "ruby_handler".to_string());
+
+    info!(
+        correlation_id = correlation_id.as_deref(),
+        task_uuid = task_uuid.as_deref(),
+        step_uuid = step_uuid.as_deref(),
+        namespace = namespace.as_deref(),
+        operation = %operation,
+        component = "ruby_ffi",
+        "{}",
+        message
+    );
+
+    Ok(())
+}
+
+/// Log DEBUG level message with structured fields (Ruby FFI)
+pub fn log_debug(message: String, fields: RHash) -> Result<(), Error> {
+    let fields_map = ruby_hash_to_map(fields)?;
+
+    let correlation_id = fields_map.get("correlation_id").cloned();
+    let task_uuid = fields_map.get("task_uuid").cloned();
+    let step_uuid = fields_map.get("step_uuid").cloned();
+    let namespace = fields_map.get("namespace").cloned();
+    let operation = fields_map
+        .get("operation")
+        .cloned()
+        .unwrap_or_else(|| "ruby_handler".to_string());
+
+    debug!(
+        correlation_id = correlation_id.as_deref(),
+        task_uuid = task_uuid.as_deref(),
+        step_uuid = step_uuid.as_deref(),
+        namespace = namespace.as_deref(),
+        operation = %operation,
+        component = "ruby_ffi",
+        "{}",
+        message
+    );
+
+    Ok(())
+}
+
+/// Log TRACE level message with structured fields (Ruby FFI)
+pub fn log_trace(message: String, fields: RHash) -> Result<(), Error> {
+    let fields_map = ruby_hash_to_map(fields)?;
+
+    let correlation_id = fields_map.get("correlation_id").cloned();
+    let task_uuid = fields_map.get("task_uuid").cloned();
+    let step_uuid = fields_map.get("step_uuid").cloned();
+    let namespace = fields_map.get("namespace").cloned();
+    let operation = fields_map
+        .get("operation")
+        .cloned()
+        .unwrap_or_else(|| "ruby_handler".to_string());
+
+    trace!(
+        correlation_id = correlation_id.as_deref(),
+        task_uuid = task_uuid.as_deref(),
+        step_uuid = step_uuid.as_deref(),
+        namespace = namespace.as_deref(),
+        operation = %operation,
+        component = "ruby_ffi",
+        "{}",
+        message
+    );
+
+    Ok(())
+}

data/ext/tasker_core/src/global_event_system.rs

@@ -0,0 +1,16 @@
+//! # Global Event System
+//!
+//! Provides a global singleton `WorkerEventSystem` that can be shared between
+//! the `WorkerProcessor` and our Rust event handlers.
+
+use std::sync::Arc;
+use tasker_shared::events::WorkerEventSystem;
+
+/// Global worker event system singleton
+pub static GLOBAL_EVENT_SYSTEM: std::sync::LazyLock<Arc<WorkerEventSystem>> =
+    std::sync::LazyLock::new(|| Arc::new(WorkerEventSystem::new()));
+
+/// Get the global worker event system
+pub fn get_global_event_system() -> Arc<WorkerEventSystem> {
+    GLOBAL_EVENT_SYSTEM.clone()
+}

data/ext/tasker_core/src/in_process_event_ffi.rs

@@ -0,0 +1,319 @@
+//! # TAS-65 Phase 4.1: Ruby FFI Bindings for In-Process Domain Events
+//!
+//! Exposes the fast in-process event bus to Ruby for subscribing to domain events.
+//! Ruby handlers can receive domain events with `delivery_mode: fast` for internal
+//! processing like metrics, notifications, and logging integrations.
+//!
+//! ## Architecture
+//!
+//! ```text
+//! EventRouter
+//!     ↓ (delivery_mode: fast)
+//! InProcessEventBus
+//!     ↓
+//! Broadcast Channel
+//!     ↓
+//! Ruby FFI poll_in_process_events()
+//!     ↓
+//! Ruby handlers (Sentry, DataDog, Slack, etc.)
+//! ```
+//!
+//! ## Usage
+//!
+//! ```ruby
+//! # Poll for fast domain events
+//! loop do
+//!   events = TaskerCore::FFI.poll_in_process_events(10)
+//!   break if events.empty?
+//!
+//!   events.each do |event|
+//!     puts "Received: #{event[:event_name]}"
+//!     # Forward to integration (Sentry, DataDog, etc.)
+//!   end
+//! end
+//! ```
+
+use crate::bridge::WORKER_SYSTEM;
+use chrono::{DateTime, Utc};
+use magnus::{
+    function, prelude::*, Error as MagnusError, ExceptionClass, RHash, RModule, Ruby,
+    Value as RValue,
+};
+use tasker_shared::events::domain_events::DomainEvent;
+use tokio::sync::broadcast;
+use tracing::{debug, error, trace, warn};
+
+/// Helper to get RuntimeError exception class (magnus 0.8 API)
+fn runtime_error_class() -> ExceptionClass {
+    Ruby::get()
+        .expect("Ruby runtime should be available")
+        .exception_runtime_error()
+}
+
+/// Maximum events to return in a single poll (safety limit)
+const MAX_POLL_BATCH_SIZE: i64 = 100;
+
+/// Convert a DomainEvent to a Ruby hash
+///
+/// Transforms the Rust DomainEvent structure into a Ruby hash with all
+/// relevant fields for Ruby-side processing.
+fn domain_event_to_ruby_hash(ruby: &Ruby, event: &DomainEvent) -> Result<RHash, MagnusError> {
+    let hash = ruby.hash_new();
+
+    // Core event fields
+    hash.aset("event_id", event.event_id.to_string())?;
+    hash.aset("event_name", event.event_name.clone())?;
+    hash.aset("event_version", event.event_version.clone())?;
+
+    // Metadata
+    let metadata = ruby.hash_new();
+    metadata.aset("task_uuid", event.metadata.task_uuid.to_string())?;
+    metadata.aset("step_uuid", event.metadata.step_uuid.map(|u| u.to_string()))?;
+    metadata.aset("step_name", event.metadata.step_name.clone())?;
+    metadata.aset("namespace", event.metadata.namespace.clone())?;
+    metadata.aset("correlation_id", event.metadata.correlation_id.to_string())?;
+    metadata.aset("fired_at", format_datetime(&event.metadata.fired_at))?;
+    metadata.aset("fired_by", event.metadata.fired_by.clone())?;
+    hash.aset("metadata", metadata)?;
+
+    // Payload - business-specific data as JSON string for Ruby parsing
+    // Using JSON string because Ruby can easily parse it with JSON.parse
+    let payload_json = serde_json::to_string(&event.payload.payload).map_err(|e| {
+        MagnusError::new(
+            runtime_error_class(),
+            format!("Failed to serialize payload: {}", e),
+        )
+    })?;
+    hash.aset("business_payload", payload_json)?;
+
+    // Execution result summary (most commonly needed fields)
+    let execution = ruby.hash_new();
+    execution.aset("success", event.payload.execution_result.success)?;
+    execution.aset("status", event.payload.execution_result.status.clone())?;
+    execution.aset(
+        "step_uuid",
+        event.payload.execution_result.step_uuid.to_string(),
+    )?;
+    if let Some(ref error) = event.payload.execution_result.error {
+        // Convert error to JSON string for Ruby consumption
+        let error_json = serde_json::to_string(error).map_err(|e| {
+            MagnusError::new(
+                runtime_error_class(),
+                format!("Failed to serialize error: {}", e),
+            )
+        })?;
+        execution.aset("error", error_json)?;
+    }
+    hash.aset("execution_result", execution)?;
+
+    // Task/step context summary
+    let context = ruby.hash_new();
+    context.aset(
+        "task_uuid",
+        event
+            .payload
+            .task_sequence_step
+            .task
+            .task
+            .task_uuid
+            .to_string(),
+    )?;
+    context.aset(
+        "task_name",
+        event.payload.task_sequence_step.task.task_name.clone(),
+    )?;
+    context.aset(
+        "namespace",
+        event.payload.task_sequence_step.task.namespace_name.clone(),
+    )?;
+    context.aset(
+        "step_name",
+        event.payload.task_sequence_step.workflow_step.name.clone(),
+    )?;
+    hash.aset("context", context)?;
+
+    Ok(hash)
+}
+
+/// Format datetime for Ruby
+fn format_datetime(dt: &DateTime<Utc>) -> String {
+    dt.to_rfc3339()
+}
+
+/// FFI function to poll for in-process domain events
+///
+/// Non-blocking poll that returns up to `max_events` domain events from the
+/// fast in-process event bus. Returns empty array if no events are available.
+///
+/// # Arguments
+///
+/// * `max_events` - Maximum number of events to return (capped at 100)
+///
+/// # Returns
+///
+/// Array of Ruby hashes, each representing a domain event with:
+/// - `event_id`: String UUID
+/// - `event_name`: String (e.g., "payment.processed")
+/// - `event_version`: String
+/// - `metadata`: Hash with task_uuid, step_uuid, namespace, correlation_id, etc.
+/// - `business_payload`: JSON string of business-specific data
+/// - `execution_result`: Hash with success, status, step_uuid, error
+/// - `context`: Hash with task_uuid, task_name, namespace, step_name
+///
+/// # Ruby Example
+///
+/// ```ruby
+/// # Poll up to 10 events
+/// events = TaskerCore::FFI.poll_in_process_events(10)
+///
+/// events.each do |event|
+///   puts "Event: #{event[:event_name]}"
+///   payload = JSON.parse(event[:business_payload])
+///   # Process event...
+/// end
+/// ```
+pub fn poll_in_process_events(max_events: i64) -> Result<RValue, MagnusError> {
+    let ruby = Ruby::get().map_err(|e| {
+        MagnusError::new(runtime_error_class(), format!("Failed to get Ruby: {}", e))
+    })?;
+
+    // Cap max_events for safety (1 to MAX_POLL_BATCH_SIZE)
+    let max_events = max_events.clamp(1, MAX_POLL_BATCH_SIZE) as usize;
+
+    let handle_guard = WORKER_SYSTEM.lock().map_err(|e| {
+        error!("Failed to acquire worker system lock: {}", e);
+        MagnusError::new(runtime_error_class(), "Lock acquisition failed")
+    })?;
+
+    let handle = handle_guard.as_ref().ok_or_else(|| {
+        MagnusError::new(
+            runtime_error_class(),
+            "Worker system not running - call bootstrap_worker first",
+        )
+    })?;
+
+    // Get the FFI receiver
+    let ffi_receiver_guard = handle.in_process_event_receiver.as_ref().ok_or_else(|| {
+        MagnusError::new(
+            runtime_error_class(),
+            "In-process event bus not initialized",
+        )
+    })?;
+
+    let mut receiver = ffi_receiver_guard.lock().map_err(|e| {
+        error!("Failed to acquire event receiver lock: {}", e);
+        MagnusError::new(runtime_error_class(), "Event receiver lock failed")
+    })?;
+
+    // Collect events using try_recv (non-blocking)
+    let events = ruby.ary_new();
+    let mut received_count = 0;
+
+    while received_count < max_events {
+        match receiver.try_recv() {
+            Ok(event) => {
+                trace!(
+                    event_id = %event.event_id,
+                    event_name = %event.event_name,
+                    "Polled in-process domain event for Ruby"
+                );
+
+                match domain_event_to_ruby_hash(&ruby, &event) {
+                    Ok(hash) => {
+                        events.push(hash)?;
+                        received_count += 1;
+                    }
+                    Err(e) => {
+                        warn!(
+                            event_id = %event.event_id,
+                            error = %e,
+                            "Failed to convert domain event to Ruby hash - skipping"
+                        );
+                        // Continue processing other events
+                    }
+                }
+            }
+            Err(broadcast::error::TryRecvError::Empty) => {
+                // No more events available
+                break;
+            }
+            Err(broadcast::error::TryRecvError::Closed) => {
+                warn!("In-process event channel closed");
+                break;
+            }
+            Err(broadcast::error::TryRecvError::Lagged(count)) => {
+                warn!(
+                    lagged_count = count,
+                    "In-process event receiver lagged - some events were dropped"
+                );
+                // Continue receiving remaining events
+            }
+        }
+    }
+
+    if received_count > 0 {
+        debug!(
+            count = received_count,
+            "Polled in-process domain events for Ruby"
+        );
+    }
+
+    Ok(events.as_value())
+}
+
+/// FFI function to get in-process event bus statistics
+///
+/// Returns statistics about the in-process event bus including subscriber
+/// counts and dispatch metrics.
+///
+/// # Returns
+///
+/// Ruby hash with:
+/// - `enabled`: Boolean - whether in-process events are enabled
+/// - `ffi_subscriber_count`: Integer - number of FFI subscribers
+/// - Additional stats when available
+pub fn get_in_process_event_stats() -> Result<RValue, MagnusError> {
+    let ruby = Ruby::get().map_err(|e| {
+        MagnusError::new(runtime_error_class(), format!("Failed to get Ruby: {}", e))
+    })?;
+
+    let hash = ruby.hash_new();
+
+    let handle_guard = WORKER_SYSTEM.lock().map_err(|e| {
+        error!("Failed to acquire worker system lock: {}", e);
+        MagnusError::new(runtime_error_class(), "Lock acquisition failed")
+    })?;
+
+    match handle_guard.as_ref() {
+        Some(handle) => {
+            hash.aset("enabled", handle.in_process_event_receiver.is_some())?;
+
+            // If we have access to the event bus stats through the handle,
+            // add them here. For now, just report enabled status.
+            if handle.in_process_event_receiver.is_some() {
+                hash.aset("status", "active")?;
+            } else {
+                hash.aset("status", "not_initialized")?;
+            }
+        }
+        None => {
+            hash.aset("enabled", false)?;
+            hash.aset("status", "worker_not_running")?;
+        }
+    }
+
+    Ok(hash.as_value())
+}
+
+/// Initialize the in-process event FFI module
+pub fn init_in_process_event_ffi(module: &RModule) -> Result<(), MagnusError> {
+    module.define_singleton_method(
+        "poll_in_process_events",
+        function!(poll_in_process_events, 1),
+    )?;
+    module.define_singleton_method(
+        "in_process_event_stats",
+        function!(get_in_process_event_stats, 0),
+    )?;
+    Ok(())
+}

data/ext/tasker_core/src/lib.rs

@@ -0,0 +1,41 @@
+use magnus::{Error as MagnusError, Module, Ruby};
+
+mod bootstrap;
+mod bridge;
+mod client_ffi; // TAS-231: Client API FFI functions
+mod conversions;
+mod diagnostics; // System diagnostics for troubleshooting
+mod event_publisher_ffi; // TAS-65 Phase 2.4a: Domain event publishing FFI
+mod ffi_logging;
+mod global_event_system;
+mod in_process_event_ffi; // TAS-65 Phase 4.1: In-process event polling FFI
+mod observability_ffi; // TAS-77: Observability services FFI
+
+// TAS-67: DomainEventCallback is now provided by tasker-worker (shared implementation)
+
+// TAS-67: event_handler module removed - replaced by FfiDispatchChannel in bridge.rs
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), MagnusError> {
+    // Initialize logging
+    ffi_logging::init_ffi_logger().map_err(|err| {
+        MagnusError::new(
+            ruby.exception_runtime_error(),
+            format!("Failed to initialize logging, {err}"),
+        )
+    })?;
+
+    let module = ruby.define_module("TaskerCore")?;
+    let ffi_module = module.define_module("FFI")?;
+
+    // Initialize bridge with all lifecycle methods
+    bridge::init_bridge(&ffi_module)?;
+
+    // Add diagnostic function for troubleshooting
+    ffi_module.define_module_function(
+        "system_diagnostics",
+        magnus::function!(diagnostics::system_diagnostics, 0),
+    )?;
+
+    Ok(())
+}