tasker-rb 0.1.1

data/ext/tasker_core/src/conversions.rs

@@ -0,0 +1,131 @@
+use magnus::{RHash, Value as RValue};
+use serde_magnus::serialize;
+use tasker_shared::errors::{TaskerError, TaskerResult};
+use tasker_shared::messaging::StepExecutionResult;
+use tasker_shared::models::batch_worker::CheckpointYieldData;
+use tasker_shared::types::TaskSequenceStep;
+use tasker_worker::worker::FfiStepEvent;
+
+// Convert TaskSequenceStep to Ruby hash with full fidelity
+fn convert_task_sequence_step_to_ruby(tss: &TaskSequenceStep) -> TaskerResult<RHash> {
+    let ruby = magnus::Ruby::get().map_err(|err| {
+        TaskerError::FFIError(format!("Ruby Magnus FFI Ruby Acquire Error: {err}"))
+    })?;
+
+    let ruby_hash: RHash = serialize(&ruby, tss).map_err(|err| {
+        TaskerError::FFIError(format!(
+            "Could not serialize TaskSequenceStep to Ruby hash: {err}"
+        ))
+    })?;
+
+    Ok(ruby_hash)
+}
+
+pub fn tasker_error_from_magnus_error(err: &magnus::Error) -> TaskerError {
+    TaskerError::FFIError(format!("Ruby Magnus FFI Error: {err}"))
+}
+
+/// TAS-67: Convert FfiStepEvent to Ruby hash
+///
+/// This converts the new dispatch channel event format to Ruby.
+/// Includes the event_id for correlation when completing the step.
+pub fn convert_ffi_step_event_to_ruby(event: &FfiStepEvent) -> TaskerResult<RHash> {
+    let ruby = magnus::Ruby::get().map_err(|err| {
+        TaskerError::FFIError(format!("Ruby Magnus FFI Ruby Acquire Error: {err}"))
+    })?;
+
+    let event_hash = ruby.hash_new();
+
+    // TAS-67: Event ID is critical for completion correlation
+    event_hash
+        .aset("event_id", event.event_id.to_string())
+        .map_err(|err| tasker_error_from_magnus_error(&err))?;
+
+    event_hash
+        .aset("task_uuid", event.task_uuid.to_string())
+        .map_err(|err| tasker_error_from_magnus_error(&err))?;
+
+    event_hash
+        .aset("step_uuid", event.step_uuid.to_string())
+        .map_err(|err| tasker_error_from_magnus_error(&err))?;
+
+    event_hash
+        .aset("correlation_id", event.correlation_id.to_string())
+        .map_err(|err| tasker_error_from_magnus_error(&err))?;
+
+    // Optional trace context
+    if let Some(ref trace_id) = event.trace_id {
+        event_hash
+            .aset("trace_id", trace_id.clone())
+            .map_err(|err| tasker_error_from_magnus_error(&err))?;
+    }
+    if let Some(ref span_id) = event.span_id {
+        event_hash
+            .aset("span_id", span_id.clone())
+            .map_err(|err| tasker_error_from_magnus_error(&err))?;
+    }
+
+    // Convert the full execution event payload (contains TaskSequenceStep)
+    let payload = &event.execution_event.payload;
+
+    // TAS-29: Also expose correlation_id from task if different
+    let task_correlation_id = payload.task_sequence_step.task.task.correlation_id;
+    event_hash
+        .aset("task_correlation_id", task_correlation_id.to_string())
+        .map_err(|err| tasker_error_from_magnus_error(&err))?;
+
+    // Parent correlation ID if present
+    if let Some(parent_id) = payload.task_sequence_step.task.task.parent_correlation_id {
+        event_hash
+            .aset("parent_correlation_id", parent_id.to_string())
+            .map_err(|err| tasker_error_from_magnus_error(&err))?;
+    }
+
+    // Convert TaskSequenceStep to Ruby hash
+    let task_sequence_step_hash = convert_task_sequence_step_to_ruby(&payload.task_sequence_step)?;
+    event_hash
+        .aset("task_sequence_step", task_sequence_step_hash)
+        .map_err(|err| tasker_error_from_magnus_error(&err))?;
+
+    Ok(event_hash)
+}
+
+/// TAS-67: Convert Ruby completion hash to StepExecutionResult
+///
+/// This is the new conversion for the FfiDispatchChannel flow.
+/// The Ruby hash should contain the result data that can be deserialized
+/// into a StepExecutionResult.
+pub fn convert_ruby_completion_to_step_result(value: RValue) -> TaskerResult<StepExecutionResult> {
+    let ruby = magnus::Ruby::get().map_err(|err| {
+        TaskerError::FFIError(format!("Ruby Magnus FFI Ruby Acquire Error: {err}"))
+    })?;
+
+    let result: StepExecutionResult = serde_magnus::deserialize(&ruby, value).map_err(|err| {
+        TaskerError::FFIError(format!(
+            "Could not deserialize to StepExecutionResult: {err}"
+        ))
+    })?;
+
+    Ok(result)
+}
+
+/// TAS-125: Convert Ruby checkpoint data hash to CheckpointYieldData
+///
+/// The Ruby hash should contain:
+/// - step_uuid: String (UUID of the step)
+/// - cursor: Any JSON value (position to resume from)
+/// - items_processed: Integer (count of items processed so far)
+/// - accumulated_results: Optional JSON value (partial results to carry forward)
+pub fn convert_ruby_checkpoint_to_yield_data(value: RValue) -> TaskerResult<CheckpointYieldData> {
+    let ruby = magnus::Ruby::get().map_err(|err| {
+        TaskerError::FFIError(format!("Ruby Magnus FFI Ruby Acquire Error: {err}"))
+    })?;
+
+    let data: CheckpointYieldData = serde_magnus::deserialize(&ruby, value).map_err(|err| {
+        TaskerError::FFIError(format!(
+            "Could not deserialize to CheckpointYieldData: {err}"
+        ))
+    })?;
+
+    Ok(data)
+}

data/ext/tasker_core/src/diagnostics.rs

@@ -0,0 +1,57 @@
+//! System diagnostics for Ruby FFI
+//!
+//! Provides diagnostic information about the Ruby FFI environment to help
+//! troubleshoot architecture-specific issues (M2 vs M4 Pro, etc.)
+
+use magnus::value::ReprValue;
+use magnus::{Error, ExceptionClass, Ruby, Value};
+
+/// Helper to get RuntimeError exception class
+fn runtime_error_class() -> ExceptionClass {
+    Ruby::get()
+        .expect("Ruby runtime should be available")
+        .exception_runtime_error()
+}
+
+/// Get system diagnostics for troubleshooting
+///
+/// Returns a hash with:
+/// - rust_version: Cargo package version
+/// - ruby_version: Ruby version string
+/// - ruby_abi: Ruby ABI version
+/// - thread_count: Available parallelism (CPU cores)
+/// - arch: System architecture (aarch64, x86_64, etc.)
+/// - tokio_runtime: Information about Tokio runtime if available
+pub fn system_diagnostics() -> Result<Value, Error> {
+    let ruby = Ruby::get().map_err(|err| {
+        Error::new(
+            runtime_error_class(),
+            format!("Failed to get Ruby runtime: {}", err),
+        )
+    })?;
+
+    let hash = ruby.hash_new();
+
+    // Rust environment
+    hash.aset("rust_version", env!("CARGO_PKG_VERSION"))?;
+    hash.aset("magnus_version", "0.8")?;
+
+    // Ruby environment
+    let ruby_version = ruby
+        .eval::<String>("RUBY_VERSION")
+        .unwrap_or_else(|_| "unknown".to_string());
+    hash.aset("ruby_version", ruby_version)?;
+
+    // System information
+    let thread_count = std::thread::available_parallelism()
+        .map(|n| n.get())
+        .unwrap_or(0);
+    hash.aset("thread_count", thread_count)?;
+    hash.aset("arch", std::env::consts::ARCH)?;
+    hash.aset("os", std::env::consts::OS)?;
+
+    // Build information - embed feature was removed for M4 Pro compatibility
+    hash.aset("magnus_embed_feature", false)?;
+
+    Ok(hash.as_value())
+}

data/ext/tasker_core/src/event_handler.rs

@@ -0,0 +1,179 @@
+//! # Ruby Event Handler
+//!
+//! Bridges `WorkerEventSystem` to Ruby dry-events without circular dependencies.
+//! Events flow: Rust → Ruby for execution, Ruby → Rust for completion.
+//!
+//! Uses MPSC channel for thread-safe communication between tokio tasks and Ruby threads.
+
+use crate::bridge;
+use crate::conversions::convert_ruby_completion_to_rust;
+use magnus::{Error as MagnusError, Value as RValue};
+use std::sync::Arc;
+use tasker_shared::monitoring::ChannelMonitor;
+use tasker_shared::{
+    events::{WorkerEventSubscriber, WorkerEventSystem},
+    types::{StepExecutionCompletionEvent, StepExecutionEvent},
+};
+use tasker_shared::{TaskerError, TaskerResult};
+use tokio::sync::{broadcast, mpsc};
+use tracing::{debug, error, info, warn};
+
+/// Ruby Event Handler - forwards Rust events to Ruby via MPSC channel (TAS-51: bounded)
+pub struct RubyEventHandler {
+    event_subscriber: Arc<WorkerEventSubscriber>,
+    worker_id: String,
+    event_sender: mpsc::Sender<StepExecutionEvent>,
+    channel_monitor: ChannelMonitor,
+}
+
+impl RubyEventHandler {
+    /// Create new Ruby event handler with bounded channel
+    ///
+    /// # Arguments
+    /// * `event_system` - Worker event system to subscribe to
+    /// * `worker_id` - Worker identifier
+    /// * `buffer_size` - MPSC channel buffer size (TAS-51: bounded channels)
+    ///
+    /// # Note
+    /// TAS-51: Migrated from unbounded to bounded channel to provide backpressure.
+    /// Buffer size should come from: `config.mpsc_channels.shared.ffi.ruby_event_buffer_size`
+    pub fn new(
+        event_system: Arc<WorkerEventSystem>,
+        worker_id: String,
+        buffer_size: usize,
+    ) -> (Self, mpsc::Receiver<StepExecutionEvent>) {
+        let event_subscriber = Arc::new(WorkerEventSubscriber::new((*event_system).clone()));
+        let (event_sender, event_receiver) = mpsc::channel(buffer_size);
+
+        // TAS-51: Initialize channel monitor for observability
+        let channel_monitor = ChannelMonitor::new("ruby_ffi_event_handler", buffer_size);
+
+        let handler = Self {
+            event_subscriber,
+            worker_id,
+            event_sender,
+            channel_monitor,
+        };
+
+        (handler, event_receiver)
+    }
+
+    pub async fn start(&self) -> TaskerResult<()> {
+        info!(
+            worker_id = %self.worker_id,
+            channel_monitor = %self.channel_monitor.channel_name(),
+            buffer_size = self.channel_monitor.buffer_size(),
+            "Starting Ruby event handler with channel monitoring"
+        );
+
+        let mut receiver = self.event_subscriber.subscribe_to_step_executions();
+        let event_sender = self.event_sender.clone();
+        // TAS-51: Clone channel monitor for observability in spawned task
+        let monitor = self.channel_monitor.clone();
+
+        tokio::spawn(async move {
+            loop {
+                match receiver.recv().await {
+                    Ok(event) => {
+                        debug!(
+                            event_id = %event.event_id,
+                            step_name = %event.payload.task_sequence_step.workflow_step.name,
+                            "Received step execution event - sending to channel for Ruby processing"
+                        );
+
+                        // Send to channel instead of directly calling Ruby
+                        match event_sender.send(event).await {
+                            Ok(()) => {
+                                // TAS-51: Record send and periodically check saturation (optimized)
+                                if monitor.record_send_success() {
+                                    monitor.check_and_warn_saturation(event_sender.capacity());
+                                }
+                            }
+                            Err(e) => {
+                                error!(
+                                    error = %e,
+                                    "Failed to send event to Ruby channel"
+                                );
+                            }
+                        }
+                    }
+                    Err(broadcast::error::RecvError::Lagged(count)) => {
+                        warn!(lagged_count = count, "Ruby event handler lagged behind");
+                    }
+                    Err(broadcast::error::RecvError::Closed) => {
+                        info!("Event channel closed - stopping Ruby event handler");
+                        break;
+                    }
+                }
+            }
+        });
+
+        Ok(())
+    }
+
+    // This method is no longer used - events are sent through the channel instead
+    // Ruby will poll for events using the receiver returned from new()
+
+    /// Handle completion event from Ruby and forward to Rust event system
+    pub async fn handle_completion(
+        &self,
+        completion: StepExecutionCompletionEvent,
+    ) -> TaskerResult<()> {
+        // Get the global event system
+        let event_system = crate::global_event_system::get_global_event_system();
+
+        // Publish completion to the event system
+        event_system
+            .publish_step_completion(completion)
+            .await
+            .map_err(|err| TaskerError::WorkerError(err.to_string()))?;
+
+        Ok(())
+    }
+}
+
+/// Called by Ruby when step processing completes
+/// This properly sends the completion event to the global event system
+pub fn send_step_completion_event(completion_data: RValue) -> Result<(), MagnusError> {
+    // Convert Ruby completion to Rust event
+    let rust_completion = convert_ruby_completion_to_rust(completion_data).map_err(|err| {
+        error!("Could not convert magnus Value to StepExecutionCompletionEvent: {err}");
+        MagnusError::new(
+            magnus::exception::runtime_error(),
+            format!("Could not convert magnus Value to StepExecutionCompletionEvent: {err}"),
+        )
+    })?;
+
+    // Get the bridge handle to access the event handler
+    let handle_guard = bridge::WORKER_SYSTEM.lock().map_err(|err| {
+        error!("Could not acquire WORKER_SYSTEM handle lock: {err}");
+        MagnusError::new(
+            magnus::exception::runtime_error(),
+            format!("Could not acquire WORKER_SYSTEM handle lock: {err}"),
+        )
+    })?;
+
+    let handle = handle_guard.as_ref().ok_or_else(|| {
+        error!("Could not acquire WORKER_SYSTEM handle");
+        MagnusError::new(
+            magnus::exception::runtime_error(),
+            "Could not acquire WORKER_SYSTEM handle".to_string(),
+        )
+    })?;
+
+    // Use the event handler to publish the completion
+    handle.runtime_handle().block_on(async {
+        handle
+            .event_handler()
+            .handle_completion(rust_completion)
+            .await
+            .map_err(|err| {
+                error!("Unable to handle event completion: {err}");
+                MagnusError::new(
+                    magnus::exception::runtime_error(),
+                    format!("Unable to handle event completion: {err}"),
+                )
+            })
+    })?;
+    Ok(())
+}

data/ext/tasker_core/src/event_publisher_ffi.rs

@@ -0,0 +1,239 @@
+//! # TAS-65 Phase 2.4a: Ruby FFI Bindings for Domain Event Publishing
+//!
+//! Exposes `DomainEventPublisher` to Ruby for step handler event publishing.
+//! Allows Ruby handlers to publish domain events with full execution context.
+//!
+//! ## Architecture
+//!
+//! This FFI layer accepts Ruby hashes that match our domain types and deserializes
+//! them into proper Rust structs using `serde_magnus`. The key types are:
+//!
+//! - `EventPublishRequest`: Top-level FFI input containing all event data
+//! - `TaskSequenceStep`: Full task/step context (reuses tasker_shared types)
+//! - `StepExecutionResult`: Complete execution result (reuses tasker_shared types)
+//! - `EventMetadataInput`: FFI-friendly metadata that converts to `EventMetadata`
+
+use crate::bridge::WORKER_SYSTEM;
+use chrono::{DateTime, Utc};
+use magnus::{
+    function, prelude::*, Error as MagnusError, ExceptionClass, RModule, Ruby, Value as RValue,
+};
+use serde::Deserialize;
+use serde_magnus::deserialize;
+use tasker_shared::events::domain_events::{DomainEventPayload, EventMetadata};
+use tasker_shared::messaging::execution_types::StepExecutionResult;
+use tasker_shared::types::TaskSequenceStep;
+use tracing::{debug, error};
+use uuid::Uuid;
+
+/// 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()
+}
+
+/// Helper to get ArgumentError exception class (magnus 0.8 API)
+fn arg_error_class() -> ExceptionClass {
+    Ruby::get()
+        .expect("Ruby runtime should be available")
+        .exception_arg_error()
+}
+
+/// FFI input structure for publishing domain events from Ruby
+///
+/// This struct is deserialized directly from a Ruby hash using serde_magnus.
+/// All nested types use the same structures as tasker_shared for consistency.
+#[derive(Debug, Deserialize)]
+pub struct EventPublishRequest {
+    /// Event name in dot notation (e.g., "payment.processed")
+    pub event_name: String,
+
+    /// Full task sequence step context
+    pub task_sequence_step: TaskSequenceStep,
+
+    /// Complete step execution result
+    pub execution_result: StepExecutionResult,
+
+    /// Business-specific event payload
+    pub business_payload: serde_json::Value,
+
+    /// Event metadata for routing and correlation
+    pub metadata: EventMetadataInput,
+}
+
+/// FFI-friendly event metadata input
+///
+/// Similar to `EventMetadata` but with String UUIDs for easier Ruby interop.
+/// Converts to `EventMetadata` with proper UUID parsing.
+#[derive(Debug, Deserialize)]
+pub struct EventMetadataInput {
+    /// Task UUID as string
+    pub task_uuid: String,
+
+    /// Step UUID as string (optional)
+    pub step_uuid: Option<String>,
+
+    /// Step name (optional)
+    pub step_name: Option<String>,
+
+    /// Namespace for queue routing
+    pub namespace: String,
+
+    /// Correlation ID as string
+    pub correlation_id: String,
+
+    /// Handler name that fired the event
+    pub fired_by: String,
+
+    /// When the event was fired (optional, defaults to now)
+    #[serde(default = "Utc::now")]
+    pub fired_at: DateTime<Utc>,
+}
+
+impl TryFrom<EventMetadataInput> for EventMetadata {
+    type Error = MagnusError;
+
+    fn try_from(input: EventMetadataInput) -> Result<Self, Self::Error> {
+        let task_uuid = parse_uuid(&input.task_uuid, "task_uuid")?;
+        let correlation_id = parse_uuid(&input.correlation_id, "correlation_id")?;
+        let step_uuid = input
+            .step_uuid
+            .map(|s| parse_uuid(&s, "step_uuid"))
+            .transpose()?;
+
+        Ok(EventMetadata {
+            task_uuid,
+            step_uuid,
+            step_name: input.step_name,
+            namespace: input.namespace,
+            correlation_id,
+            fired_at: input.fired_at,
+            fired_by: input.fired_by,
+        })
+    }
+}
+
+/// Parse a UUID string with a descriptive error message
+fn parse_uuid(s: &str, field_name: &str) -> Result<Uuid, MagnusError> {
+    Uuid::parse_str(s).map_err(|e| {
+        MagnusError::new(
+            arg_error_class(),
+            format!("Invalid {} format: {}", field_name, e),
+        )
+    })
+}
+
+/// FFI function to publish a domain event from Ruby
+///
+/// # Arguments
+///
+/// A Ruby hash containing:
+/// - `event_name`: String - Event name in dot notation (e.g., "payment.processed")
+/// - `task_sequence_step`: Hash - Full TaskSequenceStep structure
+/// - `execution_result`: Hash - Full StepExecutionResult structure
+/// - `business_payload`: Hash - Business-specific event data
+/// - `metadata`: Hash - Event metadata for routing and correlation
+///
+/// # Returns
+///
+/// String - The generated event_id (UUID v7)
+///
+/// # Ruby Example
+///
+/// ```ruby
+/// TaskerCore::FFI.publish_domain_event({
+///   event_name: "payment.processed",
+///   task_sequence_step: task_sequence_step.to_h,
+///   execution_result: execution_result.to_h,
+///   business_payload: { transaction_id: "txn_123", amount: 100.00 },
+///   metadata: {
+///     task_uuid: task.task_uuid,
+///     step_uuid: workflow_step.workflow_step_uuid,
+///     step_name: workflow_step.name,
+///     namespace: task.namespace_name,
+///     correlation_id: task.task.correlation_id,
+///     fired_by: handler_name
+///   }
+/// })
+/// # => "0199c8f0-1234-7abc-9def-0123456789ab"
+/// ```
+pub fn publish_domain_event(event_params: RValue) -> Result<String, MagnusError> {
+    // Get Ruby handle for serde_magnus
+    let ruby = magnus::Ruby::get().map_err(|e| {
+        error!("Failed to acquire Ruby handle: {}", e);
+        MagnusError::new(
+            runtime_error_class(),
+            format!("Failed to acquire Ruby handle: {}", e),
+        )
+    })?;
+
+    // Deserialize the entire request using serde_magnus
+    let request: EventPublishRequest = deserialize(&ruby, event_params).map_err(|e| {
+        error!("Failed to deserialize event publish request: {}", e);
+        MagnusError::new(
+            arg_error_class(),
+            format!("Invalid event publish request: {}", e),
+        )
+    })?;
+
+    // Convert metadata input to EventMetadata
+    let metadata: EventMetadata = request.metadata.try_into()?;
+
+    debug!(
+        event_name = %request.event_name,
+        namespace = %metadata.namespace,
+        correlation_id = %metadata.correlation_id,
+        step_success = request.execution_result.success,
+        "Publishing domain event from Ruby FFI"
+    );
+
+    // Construct the domain event payload with full context
+    let domain_payload = DomainEventPayload {
+        task_sequence_step: request.task_sequence_step,
+        execution_result: request.execution_result,
+        payload: request.business_payload,
+    };
+
+    // Get worker system to access domain event publisher
+    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",
+        )
+    })?;
+
+    // Access the domain event publisher created during bootstrap
+    let event_publisher = &handle.domain_event_publisher;
+
+    // Publish event using the async runtime
+    let runtime_handle = handle.runtime_handle();
+    let event_id = runtime_handle
+        .block_on(event_publisher.publish_event(&request.event_name, domain_payload, metadata))
+        .map_err(|e| {
+            error!("Failed to publish domain event: {}", e);
+            MagnusError::new(
+                runtime_error_class(),
+                format!("Event publication failed: {}", e),
+            )
+        })?;
+
+    debug!(
+        event_id = %event_id,
+        event_name = %request.event_name,
+        "Domain event published successfully from Ruby"
+    );
+
+    Ok(event_id.to_string())
+}
+
+/// Initialize the event publisher FFI module
+pub fn init_event_publisher_ffi(module: &RModule) -> Result<(), MagnusError> {
+    module.define_singleton_method("publish_domain_event", function!(publish_domain_event, 1))?;
+    Ok(())
+}