prosody 0.1.1

data/ext/prosody/src/logging.rs

@@ -0,0 +1,353 @@
+//! # Logging Bridge
+//!
+//! This module provides a bridge between Rust's tracing infrastructure and
+//! Ruby's logging system. It captures tracing events from Rust code and
+//! forwards them to a Ruby logger, ensuring logs from the native extension are
+//! properly integrated into the Ruby application's logging.
+//!
+//! It uses bump allocation for efficient string formatting and concurrent
+//! processing for high-throughput logging scenarios.
+
+#![allow(clippy::print_stderr)]
+
+use crate::ROOT_MOD;
+use crate::bridge::Bridge;
+use crate::id;
+use crate::util::ThreadSafeValue;
+use bumpalo::Bump;
+use bumpalo::collections::string::String as BumpString;
+use educe::Educe;
+use futures::StreamExt;
+use magnus::value::ReprValue;
+use magnus::{Ruby, Value};
+use std::cell::RefCell;
+use std::error::Error;
+use std::fmt;
+use std::fmt::{Debug, Display, Write};
+use std::sync::Arc;
+use tokio::spawn;
+use tokio::sync::mpsc::{UnboundedSender, unbounded_channel};
+use tokio_stream::wrappers::UnboundedReceiverStream;
+use tracing::field::{Field, Visit};
+use tracing::{Event, Level, Metadata, Subscriber};
+use tracing_subscriber::Layer;
+use tracing_subscriber::layer::Context;
+
+/// Maximum number of log requests to process concurrently.
+///
+/// Setting this to `None` allows unlimited concurrency, while `Some(n)` limits
+/// to n concurrent log requests.
+const CONCURRENT_LOG_REQUESTS: Option<usize> = Some(16);
+
+/// A tracing layer that forwards log events to Ruby's logging system.
+///
+/// This struct captures tracing events from Rust and sends them to a Ruby
+/// Logger instance, ensuring consistent logging across language boundaries.
+#[derive(Clone, Educe)]
+#[educe(Debug)]
+pub struct Logger {
+    /// Channel sender for log events
+    #[educe(Debug(ignore))]
+    tx: UnboundedSender<(Level, String)>,
+}
+
+impl Logger {
+    /// Creates a new logger that forwards events to Ruby's logging system.
+    ///
+    /// This function:
+    /// 1. Creates a channel for passing log events
+    /// 2. Reads the user-configured logger from `Prosody.logger`
+    /// 3. Spawns a tokio task to handle log events asynchronously
+    ///
+    /// # Arguments
+    ///
+    /// * `ruby` - Reference to the Ruby VM
+    /// * `bridge` - Bridge for communication between Rust and Ruby
+    ///
+    /// # Returns
+    ///
+    /// A new `Logger` instance or an error if Ruby logger creation fails.
+    ///
+    /// # Errors
+    ///
+    /// Returns a `magnus::Error` if:
+    /// - The `Prosody` module cannot be accessed
+    /// - Calling `Prosody.logger` fails
+    pub fn new(ruby: &Ruby, bridge: Bridge) -> Result<Self, magnus::Error> {
+        let (tx, rx) = unbounded_channel::<(Level, String)>();
+
+        let module = ruby.get_inner(&ROOT_MOD);
+        let logger: Value = module.funcall(id!(ruby, "logger"), ())?;
+        let logger = Arc::new(ThreadSafeValue::new(logger, bridge.clone()));
+
+        spawn(async move {
+            UnboundedReceiverStream::new(rx)
+                .for_each_concurrent(CONCURRENT_LOG_REQUESTS, move |evt| {
+                    log_event(bridge.clone(), logger.clone(), evt)
+                })
+                .await;
+        });
+
+        Ok(Self { tx })
+    }
+}
+
+/// Sends a log event to Ruby.
+///
+/// This function maps Rust tracing levels to Ruby Logger methods and forwards
+/// the message to the Ruby logger.
+///
+/// # Arguments
+///
+/// * `bridge` - Bridge for communication between Rust and Ruby
+/// * `logger` - Thread-safe reference to a Ruby Logger instance
+/// * `(level, msg)` - The log level and formatted message to send
+async fn log_event(bridge: Bridge, logger: Arc<ThreadSafeValue>, (level, msg): (Level, String)) {
+    if let Err(error) = bridge
+        .run(move |ruby| {
+            let method = match level {
+                Level::ERROR => id!(ruby, "error"),
+                Level::WARN => id!(ruby, "warn"),
+                Level::INFO => id!(ruby, "info"),
+                Level::DEBUG | Level::TRACE => id!(ruby, "debug"),
+            };
+
+            if let Err(error) = logger.get(ruby).funcall::<_, _, Value>(method, (msg,)) {
+                eprintln!("failed to log to Ruby: {error:#}");
+            }
+        })
+        .await
+    {
+        eprintln!("failed to log to Ruby: {error:#}");
+    }
+}
+
+impl<S: Subscriber> Layer<S> for Logger {
+    /// Processes a tracing event and forwards it to Ruby.
+    ///
+    /// This method captures the event, formats it using a `Visitor`, and sends
+    /// it to the Ruby logger.
+    ///
+    /// # Arguments
+    ///
+    /// * `event` - The tracing event to process
+    /// * `_ctx` - The subscriber context (unused)
+    fn on_event(&self, event: &Event<'_>, _ctx: Context<'_, S>) {
+        let metadata = event.metadata();
+        if !metadata.is_event() {
+            return;
+        }
+
+        thread_local! {
+            static LOG_BUMP: RefCell<Bump> = RefCell::new(Bump::with_capacity(1024));
+        }
+
+        LOG_BUMP.with(|cell| {
+            let mut bump = cell.borrow_mut();
+            bump.reset();
+
+            let mut visitor = Visitor::new(&bump, metadata);
+            event.record(&mut visitor);
+
+            if let Err(error) = self.tx.send((*metadata.level(), visitor.to_string())) {
+                eprintln!("failed to send log message: {error:#}; message: {visitor}");
+            }
+        });
+    }
+}
+
+/// A visitor that accumulates recorded field values into a bump-allocated
+/// string.
+///
+/// This struct processes tracing event fields and formats them into a
+/// human-readable log message using bump allocation for efficient memory
+/// management.
+pub struct Visitor<'a> {
+    /// Reference to the bump allocator
+    bump: &'a Bump,
+
+    /// Accumulated metadata as a string
+    metadata: BumpString<'a>,
+
+    /// Optional message field, if present
+    maybe_message: Option<BumpString<'a>>,
+}
+
+impl<'a> Visitor<'a> {
+    /// Creates a new visitor for processing event fields.
+    ///
+    /// Initializes the visitor with metadata from the event, including module
+    /// path and source line number.
+    ///
+    /// # Arguments
+    ///
+    /// * `bump` - Reference to a bump allocator
+    /// * `md` - Metadata from the tracing event
+    pub fn new(bump: &'a Bump, md: &'static Metadata<'static>) -> Self {
+        let mut visitor = Self {
+            bump,
+            metadata: BumpString::with_capacity_in(128, bump),
+            maybe_message: None,
+        };
+
+        if let Some(module) = md.module_path() {
+            let v = bump.alloc_str(module);
+            visitor.push_kv("module", v);
+        }
+
+        if let Some(line) = md.line() {
+            let v = bumpalo::format!(in bump, "{}", line);
+            visitor.push_kv("line", &v);
+        }
+
+        visitor
+    }
+
+    /// Adds a key-value pair to the metadata string.
+    ///
+    /// # Arguments
+    ///
+    /// * `key` - The field name
+    /// * `value` - The field value as a string
+    fn push_kv(&mut self, key: &str, value: &str) {
+        if self.metadata.is_empty() {
+            self.metadata.push_str(key);
+            self.metadata.push('=');
+            self.metadata.push_str(value);
+        } else {
+            self.metadata.push(' ');
+            self.metadata.push_str(key);
+            self.metadata.push('=');
+            self.metadata.push_str(value);
+        }
+    }
+}
+
+impl Visit for Visitor<'_> {
+    /// Records a f64 value.
+    ///
+    /// # Arguments
+    ///
+    /// * `f` - Field descriptor
+    /// * `v` - Field value
+    fn record_f64(&mut self, f: &Field, v: f64) {
+        let s = bumpalo::format!(in self.bump, "{}", v);
+        self.push_kv(f.name(), &s);
+    }
+
+    /// Records an i64 value.
+    ///
+    /// # Arguments
+    ///
+    /// * `f` - Field descriptor
+    /// * `v` - Field value
+    fn record_i64(&mut self, f: &Field, v: i64) {
+        let s = bumpalo::format!(in self.bump, "{}", v);
+        self.push_kv(f.name(), &s);
+    }
+
+    /// Records a u64 value.
+    ///
+    /// # Arguments
+    ///
+    /// * `f` - Field descriptor
+    /// * `v` - Field value
+    fn record_u64(&mut self, f: &Field, v: u64) {
+        let s = bumpalo::format!(in self.bump, "{}", v);
+        self.push_kv(f.name(), &s);
+    }
+
+    /// Records an i128 value.
+    ///
+    /// # Arguments
+    ///
+    /// * `f` - Field descriptor
+    /// * `v` - Field value
+    fn record_i128(&mut self, f: &Field, v: i128) {
+        let s = bumpalo::format!(in self.bump, "{}", v);
+        self.push_kv(f.name(), &s);
+    }
+
+    /// Records a u128 value.
+    ///
+    /// # Arguments
+    ///
+    /// * `f` - Field descriptor
+    /// * `v` - Field value
+    fn record_u128(&mut self, f: &Field, v: u128) {
+        let s = bumpalo::format!(in self.bump, "{}", v);
+        self.push_kv(f.name(), &s);
+    }
+
+    /// Records a boolean value.
+    ///
+    /// # Arguments
+    ///
+    /// * `f` - Field descriptor
+    /// * `v` - Field value
+    fn record_bool(&mut self, f: &Field, v: bool) {
+        let s = bumpalo::format!(in self.bump, "{}", v);
+        self.push_kv(f.name(), &s);
+    }
+
+    /// Records a string value.
+    ///
+    /// # Arguments
+    ///
+    /// * `f` - Field descriptor
+    /// * `v` - Field value
+    fn record_str(&mut self, f: &Field, v: &str) {
+        self.push_kv(f.name(), v);
+    }
+
+    /// Records an error value.
+    ///
+    /// # Arguments
+    ///
+    /// * `f` - Field descriptor
+    /// * `err` - Error value
+    fn record_error(&mut self, f: &Field, err: &(dyn Error + 'static)) {
+        let s = bumpalo::format!(in self.bump, "{:#}", err);
+        self.push_kv(f.name(), &s);
+    }
+
+    /// Records a debug-formatted value.
+    ///
+    /// Special handling is applied to the "message" field, which is stored
+    /// separately from other metadata.
+    ///
+    /// # Arguments
+    ///
+    /// * `f` - Field descriptor
+    /// * `dbg` - Value to format with Debug
+    fn record_debug(&mut self, f: &Field, dbg: &dyn Debug) {
+        let m = bumpalo::format!(in self.bump, "{:?}", dbg);
+        if f.name() == "message" {
+            self.maybe_message = Some(m);
+        } else {
+            self.push_kv(f.name(), &m);
+        }
+    }
+}
+
+impl Display for Visitor<'_> {
+    /// Formats the log message.
+    ///
+    /// If a "message" field was recorded, it's placed at the beginning of the
+    /// formatted string, followed by the metadata. Otherwise, only metadata is
+    /// included.
+    ///
+    /// # Arguments
+    ///
+    /// * `f` - Formatter to write to
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match &self.maybe_message {
+            None => f.write_str(&self.metadata),
+            Some(message) => {
+                f.write_str(message)?;
+                f.write_char(' ')?;
+                f.write_str(&self.metadata)
+            }
+        }
+    }
+}

data/ext/prosody/src/scheduler/cancellation.rs

@@ -0,0 +1,67 @@
+//! Provides functionality for canceling scheduled Ruby tasks from Rust.
+//!
+//! This module defines a token-based cancellation mechanism that allows
+//! asynchronous Rust code to safely cancel operations running in the Ruby VM.
+
+use crate::bridge::Bridge;
+use crate::id;
+use crate::scheduler::SchedulerError;
+use crate::util::ThreadSafeValue;
+use magnus::value::ReprValue;
+use magnus::{Ruby, Value};
+
+/// Token that can be used to cancel a scheduled Ruby task.
+///
+/// This struct wraps a Ruby cancellation token object and provides a safe
+/// interface for canceling the associated task across the Rust/Ruby boundary.
+#[derive(Debug)]
+pub struct CancellationToken {
+    /// The Ruby cancellation token, wrapped in a thread-safe container
+    token: ThreadSafeValue,
+}
+
+impl CancellationToken {
+    /// Creates a new cancellation token from a Ruby value.
+    ///
+    /// # Arguments
+    ///
+    /// * `token` - A Ruby value that responds to the `cancel` method
+    /// * `bridge` - The bridge used to defer cleanup of the wrapped token
+    ///   value onto the Ruby thread when the token is dropped
+    pub fn new(token: Value, bridge: Bridge) -> Self {
+        Self {
+            token: ThreadSafeValue::new(token, bridge),
+        }
+    }
+
+    /// Cancels the associated Ruby task.
+    ///
+    /// This method consumes the token, preventing it from being used to cancel
+    /// the task more than once.
+    ///
+    /// # Arguments
+    ///
+    /// * `bridge` - The bridge used to execute Ruby code from Rust
+    ///
+    /// # Returns
+    ///
+    /// `Ok(())` if the task was successfully canceled.
+    ///
+    /// # Errors
+    ///
+    /// Returns a `SchedulerError::Cancel` if:
+    /// - The Ruby `cancel` method call fails
+    /// - The bridge fails to execute the Ruby code
+    pub async fn cancel(self, bridge: &Bridge) -> Result<(), SchedulerError> {
+        bridge
+            .run(move |ruby: &Ruby| {
+                self.token
+                    .get(ruby)
+                    .funcall::<_, _, Value>(id!(ruby, "cancel"), ())
+                    .map_err(|error| SchedulerError::Cancel(error.to_string()))?;
+
+                Ok(())
+            })
+            .await?
+    }
+}

data/ext/prosody/src/scheduler/handle.rs

@@ -0,0 +1,50 @@
+//! # Task Handle
+//!
+//! This module provides the `TaskHandle` type, which represents a handle to an
+//! asynchronous task scheduled for execution in the Ruby runtime.
+//!
+//! A `TaskHandle` encapsulates:
+//! 1. A `ResultReceiver` for awaiting the completion of the task
+//! 2. A `CancellationToken` for requesting cancellation of the task
+
+use crate::scheduler::cancellation::CancellationToken;
+use crate::scheduler::result::ResultReceiver;
+
+/// A handle to an asynchronous task scheduled for execution in the Ruby
+/// runtime.
+///
+/// This struct combines two key components for managing asynchronous tasks:
+/// - A `ResultReceiver` that allows waiting for the task's completion and
+///   retrieving its result
+/// - A `CancellationToken` that enables requesting cancellation of the
+///   in-progress task
+///
+/// The handle is typically returned from the `Scheduler::schedule` method and
+/// should be retained as long as the task is active to maintain the ability
+/// to await its result or request cancellation.
+#[derive(Debug)]
+pub struct TaskHandle {
+    /// Receiver for the task's result, used to await task completion
+    pub result: ResultReceiver,
+
+    /// Token used to request cancellation of the task
+    pub cancellation_token: CancellationToken,
+}
+
+impl TaskHandle {
+    /// Creates a new `TaskHandle` with the provided result receiver and
+    /// cancellation token.
+    ///
+    /// # Arguments
+    ///
+    /// * `result` - The receiver that will provide the task's result upon
+    ///   completion
+    /// * `cancellation_token` - The token that can be used to request
+    ///   cancellation of the task
+    pub fn new(result: ResultReceiver, cancellation_token: CancellationToken) -> TaskHandle {
+        Self {
+            result,
+            cancellation_token,
+        }
+    }
+}

data/ext/prosody/src/scheduler/mod.rs

@@ -0,0 +1,169 @@
+//! # Scheduler
+//!
+//! The scheduler module provides an asynchronous task scheduling mechanism for
+//! executing Ruby code from Rust. It handles the complexities of bridging
+//! between the Rust async world and the Ruby synchronous environment, ensuring
+//! proper propagation of tracing context.
+//!
+//! This module manages task submission, execution, cancellation, and result
+//! handling, while preserving proper OpenTelemetry context across language
+//! boundaries.
+
+use crate::RUNTIME;
+use crate::bridge::{Bridge, BridgeError};
+use crate::scheduler::handle::TaskHandle;
+use crate::scheduler::processor::RubyProcessor;
+use crate::scheduler::result::result_channel;
+use magnus::{Error, Ruby};
+use opentelemetry::propagation::{TextMapCompositePropagator, TextMapPropagator};
+use prosody::propagator::new_propagator;
+use std::collections::HashMap;
+use std::convert::identity;
+use thiserror::Error;
+use tracing::{Span, error, instrument};
+use tracing_opentelemetry::OpenTelemetrySpanExt;
+
+mod cancellation;
+pub mod handle;
+mod processor;
+pub mod result;
+
+/// Manages the scheduling of Rust functions for execution in Ruby, with proper
+/// context propagation.
+///
+/// The `Scheduler` is responsible for:
+/// - Submitting tasks to a Ruby processor for execution
+/// - Propagating OpenTelemetry context between Rust and Ruby
+/// - Managing task lifecycle and result handling
+/// - Ensuring proper shutdown when dropped
+#[derive(Debug)]
+pub struct Scheduler {
+    /// Communication bridge to the Ruby runtime
+    bridge: Bridge,
+
+    /// Ruby-side task processor
+    processor: RubyProcessor,
+
+    /// Propagator for OpenTelemetry context
+    propagator: TextMapCompositePropagator,
+}
+
+impl Scheduler {
+    /// Creates a new `Scheduler` instance.
+    ///
+    /// # Arguments
+    ///
+    /// * `ruby` - A reference to the Ruby VM
+    /// * `bridge` - A bridge for communication with the Ruby runtime
+    ///
+    /// # Errors
+    ///
+    /// Returns a `Magnus::Error` if the Ruby processor cannot be created.
+    pub fn new(ruby: &Ruby, bridge: Bridge) -> Result<Self, Error> {
+        Ok(Self {
+            bridge: bridge.clone(),
+            processor: RubyProcessor::new(ruby, bridge)?,
+            propagator: new_propagator(),
+        })
+    }
+
+    /// Schedules a function to be executed in the Ruby runtime.
+    ///
+    /// This method:
+    /// 1. Injects the current tracing context into a carrier
+    /// 2. Creates a channel for receiving the task result
+    /// 3. Submits the task to the Ruby processor
+    /// 4. Returns a handle for tracking the task
+    ///
+    /// # Arguments
+    ///
+    /// * `task_id` - A unique identifier for the task
+    /// * `span` - The tracing span to propagate to Ruby
+    /// * `function` - The function to execute in Ruby
+    ///
+    /// # Errors
+    ///
+    /// Returns a `SchedulerError` if:
+    /// - The bridge fails to run the submission function
+    /// - The processor fails to submit the task
+    ///
+    /// # Returns
+    ///
+    /// A `TaskHandle` for tracking the status and result of the scheduled task.
+    #[instrument(level = "debug", skip(self, span, event_context, function), err)]
+    pub async fn schedule<F>(
+        &self,
+        task_id: String,
+        span: &Span,
+        event_context: HashMap<String, String>,
+        function: F,
+    ) -> Result<TaskHandle, SchedulerError>
+    where
+        F: FnOnce(&Ruby) -> Result<(), Error> + Send + 'static,
+    {
+        let mut carrier: HashMap<String, String> = HashMap::with_capacity(2);
+        self.propagator
+            .inject_context(&span.context(), &mut carrier);
+
+        let (result_tx, result_rx) = result_channel();
+        let cloned_instance = self.processor.clone();
+
+        let token = self
+            .bridge
+            .run(move |ruby: &Ruby| {
+                cloned_instance
+                    .submit(ruby, &task_id, carrier, event_context, result_tx, function)
+                    .map_err(|error| SchedulerError::Submit(error.to_string()))
+            })
+            .await??;
+
+        Ok(TaskHandle::new(result_rx, token))
+    }
+}
+
+impl Drop for Scheduler {
+    /// Ensures the Ruby processor is properly stopped when the scheduler is
+    /// dropped.
+    ///
+    /// This spawns an async task to gracefully shut down the processor,
+    /// logging any errors that occur during shutdown.
+    fn drop(&mut self) {
+        let bridge = self.bridge.clone();
+        let processor = self.processor.clone();
+
+        RUNTIME.spawn(async move {
+            if let Err(error) = bridge
+                .run(move |ruby| {
+                    processor
+                        .stop(ruby)
+                        .map_err(|error| SchedulerError::Shutdown(error.to_string()))
+                })
+                .await
+                .map_err(SchedulerError::from)
+                .and_then(identity)
+            {
+                error!("failed to shutdown processor: {error:#}");
+            }
+        });
+    }
+}
+
+/// Errors that can occur during scheduler operations.
+#[derive(Debug, Error)]
+pub enum SchedulerError {
+    /// Failed to submit a task to the Ruby processor.
+    #[error("failed to submit task: {0}")]
+    Submit(String),
+
+    /// An error occurred in the bridge while communicating with Ruby.
+    #[error(transparent)]
+    Bridge(#[from] BridgeError),
+
+    /// Failed to cancel a running task.
+    #[error("failed to cancel task: {0}")]
+    Cancel(String),
+
+    /// Failed to properly shut down the Ruby processor.
+    #[error("failed to shutdown processor: {0}")]
+    Shutdown(String),
+}