prosody 0.5.1 → 0.6.1

data/ext/prosody/src/published.rs

@@ -1,76 +1,97 @@
 //! Read-only published-state handles for Ruby.
+//!
+//! Every reader method runs through [`Reads`], which refuses a forked child
+//! and joins the caller's OpenTelemetry context. A failed read raises the
+//! same typed state errors as an owned handle.
 
 use crate::bridge::Bridge;
 use crate::handler::{
-    NativeJsonDequeScan, NativeJsonMapScan, NativeMapKeyScan, parse_direction,
-    published_deque_scan, published_map_key_scan, published_map_scan,
+    NativeJsonDequeScan, NativeJsonMapScan, NativeMapKeyScan, key_query, position_query, run_state,
 };
+use crate::util::ForkGuard;
 use crate::{ROOT_MOD, id};
-use magnus::value::ReprValue;
-use magnus::{Error, Module, Ruby, StaticSymbol, Value, method};
+use magnus::{Error, Module, RHash, Ruby, StaticSymbol, Value, method};
 use opentelemetry::propagation::TextMapCompositePropagator;
-use prosody::JsonCodec;
+use prosody::consumer::event_context::ErasedStateError;
 use prosody::high_level::erased::{
-    ErasedDirection, SharedDequeReader, SharedMapReader, SharedValueReader,
+    SharedDequeReader, SharedMapReader, SharedSetReader, SharedValueReader,
 };
-use prosody::state::Direction;
+use serde_json::Value as JsonValue;
 use serde_magnus::serialize;
 use std::sync::Arc;
-use tracing::Span;
 
-fn read_error(ruby: &Ruby, error: &impl ToString) -> Error {
-    Error::new(ruby.exception_runtime_error(), error.to_string())
+/// The bridge, trace propagator, and fork guard that every reader shares.
+#[derive(Clone)]
+pub(crate) struct Reads {
+    pub(crate) bridge: Bridge,
+    pub(crate) propagator: Arc<TextMapCompositePropagator>,
+    pub(crate) fork: ForkGuard,
 }
 
-fn erased_direction(direction: Direction) -> ErasedDirection {
-    match direction {
-        Direction::Forward => ErasedDirection::Forward,
-        Direction::Backward => ErasedDirection::Backward,
+impl Reads {
+    /// Waits for one read in the caller's trace.
+    ///
+    /// # Errors
+    ///
+    /// Raises `RuntimeError` after fork, and a typed state error when the
+    /// read fails.
+    fn read<F, T>(&self, ruby: &Ruby, read: F) -> Result<T, Error>
+    where
+        F: Future<Output = Result<T, ErasedStateError>> + Send + 'static,
+        T: Send + 'static,
+    {
+        self.fork.check(ruby)?;
+        run_state(ruby, &self.bridge, &self.propagator, read)
+    }
+
+    /// Waits for one optional JSON read and returns the value or `nil`.
+    ///
+    /// # Errors
+    ///
+    /// See [`Reads::read`].
+    fn read_json<F>(&self, ruby: &Ruby, read: F) -> Result<Value, Error>
+    where
+        F: Future<Output = Result<Option<JsonValue>, ErasedStateError>> + Send + 'static,
+    {
+        serialize(ruby, &self.read(ruby, read)?)
+    }
+
+    /// Returns the bridge and propagator for a new scan.
+    ///
+    /// # Errors
+    ///
+    /// Raises `RuntimeError` after fork.
+    fn scan_parts(&self, ruby: &Ruby) -> Result<(Bridge, Arc<TextMapCompositePropagator>), Error> {
+        self.fork.check(ruby)?;
+        Ok((self.bridge.clone(), Arc::clone(&self.propagator)))
     }
 }
 
 #[magnus::wrap(class = "Prosody::NativePublishedValue")]
 pub(crate) struct NativePublishedValue {
-    pub(crate) inner: SharedValueReader<JsonCodec>,
-    pub(crate) bridge: Bridge,
+    pub(crate) inner: SharedValueReader<JsonValue>,
+    pub(crate) reads: Reads,
 }
 
 impl NativePublishedValue {
     fn get(ruby: &Ruby, this: &Self, key: String) -> Result<Value, Error> {
         let inner = Arc::clone(&this.inner);
-        let value = this
-            .bridge
-            .wait_for(ruby, async move { inner.get(key).await }, Span::current())?
-            .map_err(|error| read_error(ruby, &error))?;
-        match value {
-            Some(value) => serialize(ruby, &value),
-            None => Ok(ruby.qnil().as_value()),
-        }
+        this.reads
+            .read_json(ruby, async move { inner.get(key).await })
     }
 }
 
 #[magnus::wrap(class = "Prosody::NativePublishedMap")]
 pub(crate) struct NativePublishedMap {
-    pub(crate) inner: SharedMapReader<JsonCodec>,
-    pub(crate) bridge: Bridge,
-    pub(crate) propagator: Arc<TextMapCompositePropagator>,
+    pub(crate) inner: SharedMapReader<JsonValue>,
+    pub(crate) reads: Reads,
 }
 
 impl NativePublishedMap {
     fn get(ruby: &Ruby, this: &Self, key: String, map_key: String) -> Result<Value, Error> {
         let inner = Arc::clone(&this.inner);
-        let value = this
-            .bridge
-            .wait_for(
-                ruby,
-                async move { inner.get(key, map_key).await },
-                Span::current(),
-            )?
-            .map_err(|error| read_error(ruby, &error))?;
-        match value {
-            Some(value) => serialize(ruby, &value),
-            None => Ok(ruby.qnil().as_value()),
-        }
+        this.reads
+            .read_json(ruby, async move { inner.get(key, map_key).await })
     }
 
     fn get_many(
@@ -81,25 +102,34 @@ impl NativePublishedMap {
     ) -> Result<Value, Error> {
         let inner = Arc::clone(&this.inner);
         let values = this
-            .bridge
-            .wait_for(
-                ruby,
-                async move { inner.get_many(key, map_keys).await },
-                Span::current(),
-            )?
-            .map_err(|error| read_error(ruby, &error))?;
+            .reads
+            .read(ruby, async move { inner.get_many(key, map_keys).await })?;
         serialize(ruby, &values)
     }
 
+    fn contains_many(
+        ruby: &Ruby,
+        this: &Self,
+        key: String,
+        map_keys: Vec<String>,
+    ) -> Result<Vec<bool>, Error> {
+        let inner = Arc::clone(&this.inner);
+        this.reads.read(
+            ruby,
+            async move { inner.contains_many(key, map_keys).await },
+        )
+    }
+
+    fn is_empty(ruby: &Ruby, this: &Self, key: String) -> Result<bool, Error> {
+        let inner = Arc::clone(&this.inner);
+        this.reads
+            .read(ruby, async move { inner.is_empty(key).await })
+    }
+
     fn contains_key(ruby: &Ruby, this: &Self, key: String, map_key: String) -> Result<bool, Error> {
         let inner = Arc::clone(&this.inner);
-        this.bridge
-            .wait_for(
-                ruby,
-                async move { inner.contains_key(key, map_key).await },
-                Span::current(),
-            )?
-            .map_err(|error| read_error(ruby, &error))
+        this.reads
+            .read(ruby, async move { inner.contains_key(key, map_key).await })
     }
 
     fn scan(
@@ -107,23 +137,12 @@ impl NativePublishedMap {
         this: &Self,
         key: String,
         direction: StaticSymbol,
+        options: RHash,
     ) -> Result<NativeJsonMapScan, Error> {
-        let direction = erased_direction(parse_direction(ruby, direction)?);
-        let inner = Arc::clone(&this.inner);
-        let cursor = this
-            .bridge
-            .wait_for(
-                ruby,
-                async move { inner.stream(key, direction).await },
-                Span::current(),
-            )?
-            .map_err(|error| read_error(ruby, &error))?;
-        published_map_scan(
-            ruby,
-            cursor,
-            this.bridge.clone(),
-            Arc::clone(&this.propagator),
-        )
+        let query = key_query(ruby, direction, options)?;
+        let (bridge, propagator) = this.reads.scan_parts(ruby)?;
+        let entries = this.inner.entries(key).with_query(query).stream();
+        Ok(NativeJsonMapScan::new(entries, bridge, propagator))
     }
 
     fn keys(
@@ -131,98 +150,95 @@ impl NativePublishedMap {
         this: &Self,
         key: String,
         direction: StaticSymbol,
+        options: RHash,
     ) -> Result<NativeMapKeyScan, Error> {
-        let direction = erased_direction(parse_direction(ruby, direction)?);
+        let query = key_query(ruby, direction, options)?;
+        let (bridge, propagator) = this.reads.scan_parts(ruby)?;
+        let keys = this.inner.keys(key).with_query(query).stream();
+        Ok(NativeMapKeyScan::new(keys, bridge, propagator))
+    }
+}
+
+#[magnus::wrap(class = "Prosody::NativePublishedSet")]
+pub(crate) struct NativePublishedSet {
+    pub(crate) inner: SharedSetReader,
+    pub(crate) reads: Reads,
+}
+
+impl NativePublishedSet {
+    fn contains(ruby: &Ruby, this: &Self, key: String, member: String) -> Result<bool, Error> {
         let inner = Arc::clone(&this.inner);
-        let cursor = this
-            .bridge
-            .wait_for(
-                ruby,
-                async move { inner.keys(key, direction).await },
-                Span::current(),
-            )?
-            .map_err(|error| read_error(ruby, &error))?;
-        published_map_key_scan(
-            ruby,
-            cursor,
-            this.bridge.clone(),
-            Arc::clone(&this.propagator),
-        )
+        this.reads
+            .read(ruby, async move { inner.contains(key, member).await })
+    }
+
+    fn contains_many(
+        ruby: &Ruby,
+        this: &Self,
+        key: String,
+        members: Vec<String>,
+    ) -> Result<Vec<bool>, Error> {
+        let inner = Arc::clone(&this.inner);
+        this.reads
+            .read(ruby, async move { inner.contains_many(key, members).await })
+    }
+
+    fn is_empty(ruby: &Ruby, this: &Self, key: String) -> Result<bool, Error> {
+        let inner = Arc::clone(&this.inner);
+        this.reads
+            .read(ruby, async move { inner.is_empty(key).await })
+    }
+
+    /// Opens a member cursor. Members are bare `String` keys, so the map key
+    /// cursor carries them.
+    fn keys(
+        ruby: &Ruby,
+        this: &Self,
+        key: String,
+        direction: StaticSymbol,
+        options: RHash,
+    ) -> Result<NativeMapKeyScan, Error> {
+        let query = key_query(ruby, direction, options)?;
+        let (bridge, propagator) = this.reads.scan_parts(ruby)?;
+        let members = this.inner.keys(key).with_query(query).stream();
+        Ok(NativeMapKeyScan::new(members, bridge, propagator))
     }
 }
 
 #[magnus::wrap(class = "Prosody::NativePublishedDeque")]
 pub(crate) struct NativePublishedDeque {
-    pub(crate) inner: SharedDequeReader<JsonCodec>,
-    pub(crate) bridge: Bridge,
-    pub(crate) propagator: Arc<TextMapCompositePropagator>,
+    pub(crate) inner: SharedDequeReader<JsonValue>,
+    pub(crate) reads: Reads,
 }
 
 impl NativePublishedDeque {
     fn get(ruby: &Ruby, this: &Self, key: String, index: usize) -> Result<Value, Error> {
         let inner = Arc::clone(&this.inner);
-        let value = this
-            .bridge
-            .wait_for(
-                ruby,
-                async move { inner.get(key, index).await },
-                Span::current(),
-            )?
-            .map_err(|error| read_error(ruby, &error))?;
-        match value {
-            Some(value) => serialize(ruby, &value),
-            None => Ok(ruby.qnil().as_value()),
-        }
+        this.reads
+            .read_json(ruby, async move { inner.get(key, index).await })
     }
 
     fn length(ruby: &Ruby, this: &Self, key: String) -> Result<usize, Error> {
         let inner = Arc::clone(&this.inner);
-        this.bridge
-            .wait_for(ruby, async move { inner.len(key).await }, Span::current())?
-            .map_err(|error| read_error(ruby, &error))
+        this.reads.read(ruby, async move { inner.len(key).await })
     }
 
     fn is_empty(ruby: &Ruby, this: &Self, key: String) -> Result<bool, Error> {
         let inner = Arc::clone(&this.inner);
-        this.bridge
-            .wait_for(
-                ruby,
-                async move { inner.is_empty(key).await },
-                Span::current(),
-            )?
-            .map_err(|error| read_error(ruby, &error))
+        this.reads
+            .read(ruby, async move { inner.is_empty(key).await })
     }
 
     fn peek_front(ruby: &Ruby, this: &Self, key: String) -> Result<Value, Error> {
         let inner = Arc::clone(&this.inner);
-        let value = this
-            .bridge
-            .wait_for(
-                ruby,
-                async move { inner.peek_front(key).await },
-                Span::current(),
-            )?
-            .map_err(|error| read_error(ruby, &error))?;
-        match value {
-            Some(value) => serialize(ruby, &value),
-            None => Ok(ruby.qnil().as_value()),
-        }
+        this.reads
+            .read_json(ruby, async move { inner.peek_front(key).await })
     }
 
     fn peek_back(ruby: &Ruby, this: &Self, key: String) -> Result<Value, Error> {
         let inner = Arc::clone(&this.inner);
-        let value = this
-            .bridge
-            .wait_for(
-                ruby,
-                async move { inner.peek_back(key).await },
-                Span::current(),
-            )?
-            .map_err(|error| read_error(ruby, &error))?;
-        match value {
-            Some(value) => serialize(ruby, &value),
-            None => Ok(ruby.qnil().as_value()),
-        }
+        this.reads
+            .read_json(ruby, async move { inner.peek_back(key).await })
     }
 
     fn scan(
@@ -230,23 +246,12 @@ impl NativePublishedDeque {
         this: &Self,
         key: String,
         direction: StaticSymbol,
+        options: RHash,
     ) -> Result<NativeJsonDequeScan, Error> {
-        let direction = erased_direction(parse_direction(ruby, direction)?);
-        let inner = Arc::clone(&this.inner);
-        let cursor = this
-            .bridge
-            .wait_for(
-                ruby,
-                async move { inner.stream(key, direction).await },
-                Span::current(),
-            )?
-            .map_err(|error| read_error(ruby, &error))?;
-        published_deque_scan(
-            ruby,
-            cursor,
-            this.bridge.clone(),
-            Arc::clone(&this.propagator),
-        )
+        let query = position_query(ruby, direction, options)?;
+        let (bridge, propagator) = this.reads.scan_parts(ruby)?;
+        let values = this.inner.values(key).with_query(query).stream();
+        Ok(NativeJsonDequeScan::new(values, bridge, propagator))
     }
 }
 
@@ -259,8 +264,22 @@ pub(crate) fn init(ruby: &Ruby) -> Result<(), Error> {
     map.define_method("get", method!(NativePublishedMap::get, 2))?;
     map.define_method("get_many", method!(NativePublishedMap::get_many, 2))?;
     map.define_method("contains_key", method!(NativePublishedMap::contains_key, 2))?;
-    map.define_method("scan", method!(NativePublishedMap::scan, 2))?;
-    map.define_method("keys", method!(NativePublishedMap::keys, 2))?;
+    map.define_method(
+        "contains_many",
+        method!(NativePublishedMap::contains_many, 2),
+    )?;
+    map.define_method("is_empty", method!(NativePublishedMap::is_empty, 1))?;
+    map.define_method("scan", method!(NativePublishedMap::scan, 3))?;
+    map.define_method("keys", method!(NativePublishedMap::keys, 3))?;
+
+    let set = module.define_class(id!(ruby, "NativePublishedSet"), ruby.class_object())?;
+    set.define_method("contains", method!(NativePublishedSet::contains, 2))?;
+    set.define_method(
+        "contains_many",
+        method!(NativePublishedSet::contains_many, 2),
+    )?;
+    set.define_method("is_empty", method!(NativePublishedSet::is_empty, 1))?;
+    set.define_method("keys", method!(NativePublishedSet::keys, 3))?;
 
     let deque = module.define_class(id!(ruby, "NativePublishedDeque"), ruby.class_object())?;
     deque.define_method("get", method!(NativePublishedDeque::get, 2))?;
@@ -268,6 +287,6 @@ pub(crate) fn init(ruby: &Ruby) -> Result<(), Error> {
     deque.define_method("is_empty", method!(NativePublishedDeque::is_empty, 1))?;
     deque.define_method("peek_front", method!(NativePublishedDeque::peek_front, 1))?;
     deque.define_method("peek_back", method!(NativePublishedDeque::peek_back, 1))?;
-    deque.define_method("scan", method!(NativePublishedDeque::scan, 2))?;
+    deque.define_method("scan", method!(NativePublishedDeque::scan, 3))?;
     Ok(())
 }

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

@@ -80,9 +80,10 @@ impl ResultSender {
             return false;
         };
 
+        // A result with no JSON form is a handler mistake, so it retries.
         if is_success {
             let result = deserialize(ruby, result)
-                .map_err(|error| ProcessingError::Permanent(error.to_string()));
+                .map_err(|error| ProcessingError::Transient(error.to_string()));
             if result_tx.send(result).is_err() {
                 debug!("discarding result; receiver went away");
             }

data/ext/prosody/src/tracing_util.rs

@@ -32,14 +32,6 @@ use std::collections::HashMap;
 /// - OpenTelemetry module is not available in Ruby
 /// - Context extraction or propagation fails
 /// - Ruby-to-Rust type conversion fails
-///
-/// # Example
-///
-/// ```rust
-/// let context = extract_opentelemetry_context(ruby, &propagator)?;
-/// let span = info_span!("operation");
-/// span.set_parent(context);
-/// ```
 pub fn extract_opentelemetry_context(
     ruby: &Ruby,
     propagator: &TextMapCompositePropagator,

data/ext/prosody/src/util.rs

@@ -13,7 +13,11 @@ use prosody::tracing::{
     TracingError, flush_telemetry as core_flush_telemetry, initialize_tracing,
     shutdown_telemetry as core_shutdown_telemetry,
 };
+use std::fmt;
+use std::io::{self, Write};
 use std::mem::{ManuallyDrop, forget};
+use std::process;
+use std::time::Duration;
 use tokio::runtime::{EnterGuard, Handle};
 use tracing::{error, warn};
 
@@ -25,13 +29,6 @@ use tracing::{error, warn};
 ///
 /// This macro requires a `ruby: &Ruby` parameter to enforce that it can only
 /// be used within a Ruby thread context, ensuring thread safety.
-///
-/// # Examples
-///
-/// ```
-/// let method_name = id!(ruby, "to_s");
-/// // Use method_name with Ruby function calls
-/// ```
 #[macro_export]
 macro_rules! id {
     ($ruby:expr, $str:expr) => {{
@@ -179,6 +176,65 @@ impl Drop for RubyDrop {
     }
 }
 
+/// Writes one line to standard error.
+///
+/// Use it only where no logger exists: before tracing starts, or when the
+/// Ruby logger itself fails.
+pub(crate) fn report(message: fmt::Arguments<'_>) {
+    drop(writeln!(io::stderr().lock(), "{message}"));
+}
+
+/// Converts a Ruby number of seconds into a [`Duration`].
+///
+/// # Errors
+///
+/// Returns an error that names `option` if the value is negative, not
+/// finite, or too large for a [`Duration`].
+pub(crate) fn seconds(option: &str, value: f64) -> Result<Duration, String> {
+    Duration::try_from_secs_f64(value)
+        .map_err(|_| format!("{option}: must be a finite, non-negative number of seconds"))
+}
+
+/// Detects the use of a native object in a forked child process.
+///
+/// The Tokio runtime and the bridge thread do not survive `fork`. A native
+/// object that waits on them in a child waits forever, so it raises instead.
+#[derive(Clone, Copy, Debug)]
+pub struct ForkGuard {
+    /// The process that created the object.
+    pid: u32,
+    /// The Ruby class name that the error message shows.
+    class: &'static str,
+}
+
+impl ForkGuard {
+    /// Records the current process for an object of the Ruby `class`.
+    pub fn new(class: &'static str) -> Self {
+        Self {
+            pid: process::id(),
+            class,
+        }
+    }
+
+    /// Checks that the current process created the object.
+    ///
+    /// # Errors
+    ///
+    /// Returns a `RuntimeError` in a forked child process.
+    pub fn check(self, ruby: &Ruby) -> Result<(), Error> {
+        if process::id() == self.pid {
+            return Ok(());
+        }
+        Err(Error::new(
+            ruby.exception_runtime_error(),
+            format!(
+                "{} cannot be used after fork. Create a new client in the child process.",
+                self.class
+            ),
+        ))
+    }
+}
+
 /// Ensures a Tokio runtime context exists, entering one if necessary.
 ///
 /// Only creates a runtime guard when not already in a runtime context, avoiding
@@ -193,13 +249,6 @@ impl Drop for RubyDrop {
 ///
 /// `Some(EnterGuard)` if we entered a new runtime (hold the guard), or `None`
 /// if already in a runtime context.
-///
-/// # Examples
-///
-/// ```rust
-/// let _guard = ensure_runtime_context(ruby);
-/// // Safe to perform async operations
-/// ```
 pub fn ensure_runtime_context(ruby: &Ruby) -> Option<EnterGuard<'static>> {
     let guard = Handle::try_current().is_err().then(|| RUNTIME.enter());
 
@@ -207,14 +256,13 @@ pub fn ensure_runtime_context(ruby: &Ruby) -> Option<EnterGuard<'static>> {
     let bridge = BRIDGE.get_or_init(|| Bridge::new(ruby));
 
     // Initialize tracing for observability
-    #[allow(clippy::print_stderr, reason = "logger has not been initialized yet")]
     TRACING_INIT.get_or_init(|| {
         let maybe_logger = Logger::new(ruby, bridge.clone())
-            .inspect_err(|error| eprintln!("failed to create logger: {error:#}"))
+            .inspect_err(|error| report(format_args!("failed to create logger: {error:#}")))
             .ok();
 
         if let Err(error) = initialize_tracing(maybe_logger) {
-            eprintln!("failed to initialize tracing: {error:#}");
+            report(format_args!("failed to initialize tracing: {error:#}"));
         }
     });
 

data/lib/prosody/client.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Prosody
+  # Ruby-side lifecycle helpers for the native {Prosody::Client}.
+  class Client
+    # Creates a client, yields it, and shuts it down when the block exits.
+    # The client shuts down also when the block raises. Repeated shutdown
+    # calls wait for the same operation, so the block can also call
+    # {#shutdown}.
+    #
+    # @param config [Hash, Configuration] Client configuration
+    # @yieldparam client [Client] the new client
+    # @return [Object] the value of the block
+    # @raise [ArgumentError] if no block is given or the configuration is invalid
+    # @raise [RuntimeError] if client initialization or shutdown fails
+    #
+    # @example
+    #   Prosody::Client.open(bootstrap_servers: "localhost:9092") do |client|
+    #     client.send_message("my-topic", "key", {"hello" => "world"})
+    #   end
+    def self.open(config)
+      raise ArgumentError, "Prosody::Client.open requires a block" unless block_given?
+
+      client = new(config)
+      begin
+        yield client
+      ensure
+        client.shutdown
+      end
+    end
+  end
+end