prosody 0.3.0 → 0.5.0

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

@@ -13,25 +13,45 @@
 use crate::bridge::Bridge;
 use crate::client::config::NativeConfiguration;
 use crate::handler::RubyHandler;
+use crate::published::{NativePublishedDeque, NativePublishedMap, NativePublishedValue};
 use crate::tracing_util::extract_opentelemetry_context;
 use crate::util::ensure_runtime_context;
 use crate::{BRIDGE, ROOT_MOD, id};
 use educe::Educe;
+use futures::FutureExt;
+use futures::future::{BoxFuture, Shared};
 use magnus::value::ReprValue;
-use magnus::{Error, Module, Object, RClass, Ruby, StaticSymbol, Value, function, method};
+use magnus::{
+    Class, Error, Module, Object, RClass, RModule, Ruby, StaticSymbol, Value, function, kwargs,
+    method,
+};
 use opentelemetry::propagation::TextMapCompositePropagator;
+use prosody::cassandra::config::CassandraConfigurationBuilder;
 use prosody::high_level::ConsumerBuilders;
-use prosody::high_level::HighLevelClient;
+use prosody::high_level::erased::{
+    ErasedConsumerState, ErasedReadCache, SharedHighLevelClient, new_erased,
+};
 use prosody::high_level::mode::Mode;
-use prosody::high_level::state::ConsumerState;
 use prosody::propagator::new_propagator;
+use prosody::requester::ResponseError;
+use prosody::subsystem::SubsystemName;
+use serde::Deserialize;
 use serde_magnus::deserialize;
+use serde_magnus::serialize;
 use std::sync::Arc;
+use std::time::Duration;
 use tracing::{Span, debug, info_span};
 use tracing_opentelemetry::OpenTelemetrySpanExt;
 
 /// Configuration types and conversion between Ruby and Rust representations
 mod config;
+mod request;
+mod support;
+
+pub use support::init;
+use support::{read_cache, response_error, shutdown, validate_handler};
+
+type Shutdown = Shared<BoxFuture<'static, Result<(), Arc<str>>>>;
 
 /// A Ruby-compatible wrapper around the Prosody high-level client.
 ///
@@ -44,11 +64,14 @@ mod config;
 pub struct Client {
     /// The underlying Prosody client
     #[educe(Debug(ignore))]
-    inner: Arc<HighLevelClient<RubyHandler>>,
+    inner: SharedHighLevelClient<RubyHandler>,
+    /// One shutdown operation shared by all callers
+    #[educe(Debug(ignore))]
+    shutdown: Shutdown,
     /// Bridge for communicating between Rust and Ruby
     bridge: Bridge,
     /// OpenTelemetry propagator for distributed tracing
-    propagator: TextMapCompositePropagator,
+    propagator: Arc<TextMapCompositePropagator>,
     /// PID at construction time, used to detect post-fork usage
     pid: u32,
 }
@@ -96,14 +119,6 @@ impl Client {
             .try_into()
             .map_err(|error: String| Error::new(ruby.exception_arg_error(), error))?;
 
-        let client = HighLevelClient::new(
-            mode,
-            &mut config_ref.into(),
-            &consumer_builders,
-            &config_ref.into(),
-        )
-        .map_err(|error| Error::new(ruby.exception_runtime_error(), error.to_string()))?;
-
         let bridge = BRIDGE
             .get()
             .ok_or(Error::new(
@@ -111,11 +126,23 @@ impl Client {
                 "Bridge not initialized",
             ))?
             .clone();
+        let cassandra = Into::<CassandraConfigurationBuilder>::into(config_ref);
+        let mut producer = config_ref.into();
+        let client = bridge
+            .wait_for(
+                ruby,
+                async move {
+                    new_erased(mode, &mut producer, &consumer_builders, &cassandra).await
+                },
+                Span::current(),
+            )?
+            .map_err(|error| Error::new(ruby.exception_runtime_error(), error.to_string()))?;
 
         Ok(Self {
-            inner: Arc::new(client),
-            bridge: bridge.clone(),
-            propagator: new_propagator(),
+            shutdown: shutdown(&client),
+            inner: client,
+            bridge,
+            propagator: Arc::new(new_propagator()),
             pid: std::process::id(),
         })
     }
@@ -133,7 +160,8 @@ impl Client {
 
     /// Returns the current state of the consumer.
     ///
-    /// The consumer can be in one of three states:
+    /// The consumer can be in one of four states:
+    /// - `:shut_down` - The client is shut down
     /// - `:unconfigured` - The consumer has not been configured yet
     /// - `:configured` - The consumer is configured but not running
     /// - `:running` - The consumer is actively consuming messages
@@ -158,14 +186,14 @@ impl Client {
         let state: Result<&'static str, String> = this.bridge.wait_for(
             ruby,
             async move {
-                let view = inner.consumer_state().await;
-                match &*view {
-                    ConsumerState::Unconfigured => Ok("unconfigured"),
-                    ConsumerState::ConfigurationFailed(err) => {
-                        Err(format!("consumer configuration failed: {err:#}"))
+                match inner.consumer_state().await {
+                    ErasedConsumerState::Shutdown => Ok("shut_down"),
+                    ErasedConsumerState::Unconfigured => Ok("unconfigured"),
+                    ErasedConsumerState::ConfigurationFailed(error) => {
+                        Err(format!("consumer configuration failed: {error}"))
                     }
-                    ConsumerState::Configured(_) => Ok("configured"),
-                    ConsumerState::Running { .. } => Ok("running"),
+                    ErasedConsumerState::Configured(_) => Ok("configured"),
+                    ErasedConsumerState::Running { .. } => Ok("running"),
                 }
             },
             Span::current(),
@@ -215,30 +243,39 @@ impl Client {
         this.bridge
             .wait_for(
                 ruby,
-                async move { client.send(topic.as_str().into(), &key, value).await },
+                async move { client.send(topic.as_str().into(), key, value).await },
                 span,
             )?
             .map_err(|error| Error::new(ruby.exception_runtime_error(), format!("{error:#}")))
     }
 
-    /// Subscribes to events using the provided Ruby handler.
-    ///
-    /// The handler must implement an `on_message(context, message)` method
-    /// that will be called for each received message.
-    ///
-    /// # Arguments
-    ///
-    /// * `ruby` - The Ruby VM context
-    /// * `this` - The client instance
-    /// * `handler` - A Ruby object that will handle incoming messages
+    /// Sends an excise record for a key.
+    fn excise(ruby: &Ruby, this: &Self, topic: String, key: String) -> Result<(), Error> {
+        Self::check_fork(ruby, this)?;
+        let _guard = ensure_runtime_context(ruby);
+        let client = this.inner.clone();
+        let context = extract_opentelemetry_context(ruby, &this.propagator)?;
+        let span = info_span!("ruby-excise", %topic, %key);
+        if let Err(err) = span.set_parent(context) {
+            debug!("failed to set parent span: {err:#}");
+        }
+        this.bridge
+            .wait_for(
+                ruby,
+                async move { client.excise(topic.as_str().into(), key).await },
+                span,
+            )?
+            .map_err(|error| Error::new(ruby.exception_runtime_error(), format!("{error:#}")))
+    }
+
+    /// Subscribes with a complete Ruby event handler.
     ///
     /// # Errors
     ///
-    /// Returns an error if:
-    /// - The handler cannot be wrapped
-    /// - The client cannot subscribe with the handler
+    /// Returns an error if the handler is incomplete or subscription fails.
     fn subscribe(ruby: &Ruby, this: &Self, handler: Value) -> Result<(), Error> {
         Self::check_fork(ruby, this)?;
+        validate_handler(ruby, handler)?;
         let _guard = ensure_runtime_context(ruby);
         let wrapper = RubyHandler::new(this.bridge.clone(), ruby, handler)?;
         let inner = this.inner.clone();
@@ -327,6 +364,22 @@ impl Client {
             .map_err(|error| Error::new(ruby.exception_runtime_error(), format!("{error:#}")))
     }
 
+    /// Shuts down the client and all its services.
+    /// Concurrent and repeated calls wait for the same operation.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if shutdown fails.
+    fn shutdown(ruby: &Ruby, this: &Self) -> Result<(), Error> {
+        Self::check_fork(ruby, this)?;
+        let _guard = ensure_runtime_context(ruby);
+        let shutdown = this.shutdown.clone();
+
+        this.bridge
+            .wait_for(ruby, shutdown, Span::current())?
+            .map_err(|error| Error::new(ruby.exception_runtime_error(), format!("{error:#}")))
+    }
+
     /// Returns the configured source system identifier.
     ///
     /// The source system is used to identify the originating service or
@@ -342,41 +395,81 @@ impl Client {
     fn source_system(this: &Self) -> &str {
         this.inner.source_system()
     }
-}
 
-/// Initializes the client module in Ruby.
-///
-/// Defines the `Prosody::Client` class and its methods, making the client
-/// functionality available to Ruby code.
-///
-/// # Arguments
-///
-/// * `ruby` - The Ruby VM context
-///
-/// # Errors
-///
-/// Returns an error if Ruby class or method definition fails.
-pub fn init(ruby: &Ruby) -> Result<(), Error> {
-    let module = ruby.get_inner(&ROOT_MOD);
-    let class = module.define_class(id!(ruby, "Client"), ruby.class_object())?;
-
-    class.define_singleton_method("new", function!(Client::new, 1))?;
-    class.define_method(
-        id!(ruby, "consumer_state"),
-        method!(Client::consumer_state, 0),
-    )?;
-    class.define_method(id!(ruby, "send_message"), method!(Client::send, 3))?;
-    class.define_method(id!(ruby, "subscribe"), method!(Client::subscribe, 1))?;
-    class.define_method(
-        id!(ruby, "assigned_partitions"),
-        method!(Client::assigned_partitions, 0),
-    )?;
-    class.define_method(id!(ruby, "is_stalled?"), method!(Client::is_stalled, 0))?;
-    class.define_method(id!(ruby, "unsubscribe"), method!(Client::unsubscribe, 0))?;
-    class.define_method(
-        id!(ruby, "source_system"),
-        method!(Client::source_system, 0),
-    )?;
-
-    Ok(())
+    fn published_value(
+        ruby: &Ruby,
+        this: &Self,
+        subsystem: String,
+        name: String,
+        cache_seconds: Option<f64>,
+        cache_disabled: bool,
+    ) -> Result<NativePublishedValue, Error> {
+        Self::check_fork(ruby, this)?;
+        let cache = read_cache(ruby, cache_seconds, cache_disabled)?;
+        let inner = this.inner.clone();
+        let reader = this
+            .bridge
+            .wait_for(
+                ruby,
+                async move { inner.value_state(subsystem, name, cache).await },
+                Span::current(),
+            )?
+            .map_err(|error| Error::new(ruby.exception_runtime_error(), error.to_string()))?;
+        Ok(NativePublishedValue {
+            inner: reader,
+            bridge: this.bridge.clone(),
+        })
+    }
+
+    fn published_map(
+        ruby: &Ruby,
+        this: &Self,
+        subsystem: String,
+        name: String,
+        cache_seconds: Option<f64>,
+        cache_disabled: bool,
+    ) -> Result<NativePublishedMap, Error> {
+        Self::check_fork(ruby, this)?;
+        let cache = read_cache(ruby, cache_seconds, cache_disabled)?;
+        let inner = this.inner.clone();
+        let reader = this
+            .bridge
+            .wait_for(
+                ruby,
+                async move { inner.map_state(subsystem, name, cache).await },
+                Span::current(),
+            )?
+            .map_err(|error| Error::new(ruby.exception_runtime_error(), error.to_string()))?;
+        Ok(NativePublishedMap {
+            inner: reader,
+            bridge: this.bridge.clone(),
+            propagator: Arc::clone(&this.propagator),
+        })
+    }
+
+    fn published_deque(
+        ruby: &Ruby,
+        this: &Self,
+        subsystem: String,
+        name: String,
+        cache_seconds: Option<f64>,
+        cache_disabled: bool,
+    ) -> Result<NativePublishedDeque, Error> {
+        Self::check_fork(ruby, this)?;
+        let cache = read_cache(ruby, cache_seconds, cache_disabled)?;
+        let inner = this.inner.clone();
+        let reader = this
+            .bridge
+            .wait_for(
+                ruby,
+                async move { inner.deque_state(subsystem, name, cache).await },
+                Span::current(),
+            )?
+            .map_err(|error| Error::new(ruby.exception_runtime_error(), error.to_string()))?;
+        Ok(NativePublishedDeque {
+            inner: reader,
+            bridge: this.bridge.clone(),
+            propagator: Arc::clone(&this.propagator),
+        })
+    }
 }

data/ext/prosody/src/client/request.rs

@@ -0,0 +1,132 @@
+use super::{
+    Class, Client, Deserialize, Duration, Error, Module, OpenTelemetrySpanExt, RClass, ROOT_MOD,
+    ReprValue, Ruby, SubsystemName, Value, debug, deserialize, ensure_runtime_context,
+    extract_opentelemetry_context, id, info_span, kwargs, response_error, serialize,
+};
+
+#[derive(Deserialize)]
+struct NativeRequest {
+    topic: String,
+    key: String,
+    payload: serde_json::Value,
+    subsystems: Vec<String>,
+    timeout: f64,
+}
+
+#[derive(Deserialize)]
+struct NativeExciseRequest {
+    topic: String,
+    key: String,
+    subsystems: Vec<String>,
+    timeout: f64,
+}
+
+pub(super) fn request(ruby: &Ruby, this: &Client, request: Value) -> Result<Value, Error> {
+    Client::check_fork(ruby, this)?;
+    let _guard = ensure_runtime_context(ruby);
+    let request: NativeRequest = deserialize(ruby, request)?;
+    let (subsystems, timeout) = request_parameters(ruby, request.subsystems, request.timeout)?;
+    let topic = prosody::Topic::from(request.topic.as_str());
+    let context = extract_opentelemetry_context(ruby, &this.propagator)?;
+    let span = info_span!("ruby-request", topic = %request.topic, key = %request.key);
+    if let Err(error) = span.set_parent(context) {
+        debug!("failed to set parent span: {error:#}");
+    }
+    let inner = this.inner.clone();
+    let results = this
+        .bridge
+        .wait_for(
+            ruby,
+            async move {
+                inner
+                    .request(
+                        Vec::new(),
+                        topic,
+                        request.key,
+                        request.payload,
+                        subsystems,
+                        timeout,
+                    )
+                    .await
+            },
+            span,
+        )?
+        .map_err(|error| Error::new(ruby.exception_runtime_error(), error.to_string()))?;
+
+    request_outcomes(ruby, results)
+}
+
+pub(super) fn request_excise(ruby: &Ruby, this: &Client, request: Value) -> Result<Value, Error> {
+    Client::check_fork(ruby, this)?;
+    let _guard = ensure_runtime_context(ruby);
+    let request: NativeExciseRequest = deserialize(ruby, request)?;
+    let (subsystems, timeout) = request_parameters(ruby, request.subsystems, request.timeout)?;
+    let topic = prosody::Topic::from(request.topic.as_str());
+    let context = extract_opentelemetry_context(ruby, &this.propagator)?;
+    let span = info_span!("ruby-request-excise", topic = %request.topic, key = %request.key);
+    if let Err(error) = span.set_parent(context) {
+        debug!("failed to set parent span: {error:#}");
+    }
+    let inner = this.inner.clone();
+    let results = this
+        .bridge
+        .wait_for(
+            ruby,
+            async move {
+                inner
+                    .request_excise(Vec::new(), topic, request.key, subsystems, timeout)
+                    .await
+            },
+            span,
+        )?
+        .map_err(|error| Error::new(ruby.exception_runtime_error(), error.to_string()))?;
+
+    request_outcomes(ruby, results)
+}
+
+fn request_parameters(
+    ruby: &Ruby,
+    subsystems: Vec<String>,
+    timeout: f64,
+) -> Result<(Vec<SubsystemName>, Duration), Error> {
+    let subsystems = subsystems
+        .into_iter()
+        .map(SubsystemName::try_new)
+        .collect::<Result<Vec<_>, _>>()
+        .map_err(|error| Error::new(ruby.exception_arg_error(), error.to_string()))?;
+    let timeout = Duration::try_from_secs_f64(timeout).map_err(|_| {
+        Error::new(
+            ruby.exception_arg_error(),
+            "timeout must be a finite, non-negative duration",
+        )
+    })?;
+    Ok((subsystems, timeout))
+}
+
+fn request_outcomes<I>(ruby: &Ruby, results: I) -> Result<Value, Error>
+where
+    I: IntoIterator<
+        Item = (
+            SubsystemName,
+            Result<serde_json::Value, prosody::requester::ResponseError>,
+        ),
+    >,
+{
+    let module = ruby.get_inner(&ROOT_MOD);
+    let outcomes = ruby.hash_new();
+    let success: RClass = module.const_get(id!(ruby, "Success"))?;
+    let failure: RClass = module.const_get(id!(ruby, "Failure"))?;
+    for (subsystem, result) in results {
+        let outcome = match result {
+            Ok(value) => {
+                let value: Value = serialize(ruby, &value)?;
+                success.new_instance((kwargs!(ruby, "value" => value),))?
+            }
+            Err(error) => failure.new_instance((kwargs!(
+                ruby, "error" => response_error(ruby, module, error)?
+            ),))?,
+        };
+        outcomes.aset(subsystem.as_str(), outcome)?;
+    }
+    Ok(outcomes.as_value())
+}

data/ext/prosody/src/client/support.rs

@@ -0,0 +1,122 @@
+use super::{
+    Arc, Class, Client, Duration, ErasedReadCache, Error, FutureExt, Module, Object, RClass,
+    RModule, ROOT_MOD, ReprValue, ResponseError, Ruby, RubyHandler, SharedHighLevelClient,
+    Shutdown, Value, function, id, kwargs, method, request,
+};
+
+pub(super) fn validate_handler(ruby: &Ruby, handler: Value) -> Result<(), Error> {
+    let event_handler: RClass = ruby
+        .get_inner(&ROOT_MOD)
+        .const_get(id!(ruby, "EventHandler"))?;
+    let _: Value = event_handler.funcall(id!(ruby, "validate_handler!"), (handler,))?;
+    Ok(())
+}
+
+pub(super) fn shutdown(client: &SharedHighLevelClient<RubyHandler>) -> Shutdown {
+    let client = client.clone();
+    async move {
+        client
+            .shutdown()
+            .await
+            .map_err(|error| Arc::from(error.to_string()))
+    }
+    .boxed()
+    .shared()
+}
+
+pub(super) fn read_cache(
+    ruby: &Ruby,
+    seconds: Option<f64>,
+    disabled: bool,
+) -> Result<ErasedReadCache, Error> {
+    match (seconds, disabled) {
+        (None, false) => Ok(ErasedReadCache::Inherit),
+        (None, true) => Ok(ErasedReadCache::Disabled),
+        (Some(seconds), false) => Duration::try_from_secs_f64(seconds)
+            .map(ErasedReadCache::Ttl)
+            .map_err(|_| {
+                Error::new(
+                    ruby.exception_arg_error(),
+                    "read_cache must be finite and non-negative",
+                )
+            }),
+        (Some(_), true) => Err(Error::new(
+            ruby.exception_arg_error(),
+            "read_cache cannot specify a TTL and be disabled",
+        )),
+    }
+}
+
+/// Initializes the client module in Ruby.
+///
+/// Defines the `Prosody::Client` class and its methods, making the client
+/// functionality available to Ruby code.
+///
+/// # Arguments
+///
+/// * `ruby` - The Ruby VM context
+///
+/// # Errors
+///
+/// Returns an error if Ruby class or method definition fails.
+pub fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.get_inner(&ROOT_MOD);
+    let class = module.define_class(id!(ruby, "Client"), ruby.class_object())?;
+
+    class.define_singleton_method("new", function!(Client::new, 1))?;
+    class.define_method(
+        id!(ruby, "consumer_state"),
+        method!(Client::consumer_state, 0),
+    )?;
+    class.define_method(id!(ruby, "send_message"), method!(Client::send, 3))?;
+    class.define_method(id!(ruby, "excise"), method!(Client::excise, 2))?;
+    class.define_method(id!(ruby, "native_request"), method!(request::request, 1))?;
+    class.define_method(
+        id!(ruby, "native_request_excise"),
+        method!(request::request_excise, 1),
+    )?;
+    class.define_method(id!(ruby, "subscribe"), method!(Client::subscribe, 1))?;
+    class.define_method(
+        id!(ruby, "assigned_partitions"),
+        method!(Client::assigned_partitions, 0),
+    )?;
+    class.define_method(id!(ruby, "is_stalled?"), method!(Client::is_stalled, 0))?;
+    class.define_method(id!(ruby, "unsubscribe"), method!(Client::unsubscribe, 0))?;
+    class.define_method(id!(ruby, "shutdown"), method!(Client::shutdown, 0))?;
+    class.define_method(
+        id!(ruby, "source_system"),
+        method!(Client::source_system, 0),
+    )?;
+    class.define_method(
+        id!(ruby, "published_value"),
+        method!(Client::published_value, 4),
+    )?;
+    class.define_method(
+        id!(ruby, "published_map"),
+        method!(Client::published_map, 4),
+    )?;
+    class.define_method(
+        id!(ruby, "published_deque"),
+        method!(Client::published_deque, 4),
+    )?;
+
+    Ok(())
+}
+
+pub(super) fn response_error(
+    ruby: &Ruby,
+    module: RModule,
+    error: ResponseError,
+) -> Result<Value, Error> {
+    let (name, message) = match error {
+        ResponseError::Handler { message } => ("HandlerError", Some(message)),
+        ResponseError::Timeout => ("Timeout", None),
+        ResponseError::FormatMismatch => ("FormatMismatch", None),
+        ResponseError::Malformed => ("MalformedResponse", None),
+    };
+    let class: RClass = module.const_get(name)?;
+    match message {
+        Some(message) => class.new_instance((kwargs!(ruby, "message" => message),)),
+        None => class.new_instance(()),
+    }
+}