prosody 0.5.1 → 0.6.0

data/ext/prosody/src/handler/state/mod.rs

@@ -14,52 +14,36 @@ use crate::ROOT_MOD;
 use crate::bridge::Bridge;
 use crate::handler::message::Message;
 use crate::tracing_util::extract_opentelemetry_context;
-use magnus::value::{Lazy, ReprValue};
-use magnus::{Error, ExceptionClass, IntoValue, Module, Ruby, StaticSymbol, TryConvert, Value};
+use magnus::value::ReprValue;
+use magnus::{
+    Error, ExceptionClass, IntoValue, Module, RClass, RHash, RModule, Ruby, StaticSymbol,
+    TryConvert, Value, method,
+};
 use opentelemetry::propagation::TextMapCompositePropagator;
 use opentelemetry::trace::FutureExt;
 use prosody::consumer::event_context::{
-    DynDequeState, DynMapState, DynValueState, ErasedCategory, ErasedStateError,
+    DynMapState, DynValueState, ErasedCategory, ErasedStateError,
 };
 use prosody::consumer::message::ConsumerMessage;
-use prosody::state::Direction;
+use prosody::state::StoreOutcome;
 use serde_json::Value as JsonValue;
 use serde_magnus::{deserialize, serialize};
 use std::sync::Arc;
 use tracing::Span;
 
-/// Lazily resolved `Prosody::PermanentStateError` class (defined in Ruby).
-#[allow(
-    clippy::expect_used,
-    reason = "mirrors bridge.rs QUEUE_CLASS Lazy pattern"
-)]
-static PERMANENT_STATE_ERROR: Lazy<ExceptionClass> = Lazy::new(|ruby| {
-    ruby.get_inner(&ROOT_MOD)
-        .const_get("PermanentStateError")
-        .expect("Prosody::PermanentStateError")
-});
-
-/// Lazily resolved `Prosody::TransientStateError` class (defined in Ruby).
-#[allow(
-    clippy::expect_used,
-    reason = "mirrors bridge.rs QUEUE_CLASS Lazy pattern"
-)]
-static TRANSIENT_STATE_ERROR: Lazy<ExceptionClass> = Lazy::new(|ruby| {
-    ruby.get_inner(&ROOT_MOD)
-        .const_get("TransientStateError")
-        .expect("Prosody::TransientStateError")
-});
-
-/// Lazily resolved `Prosody::NullValueError` class (defined in Ruby).
-#[allow(
-    clippy::expect_used,
-    reason = "mirrors bridge.rs QUEUE_CLASS Lazy pattern"
-)]
-static NULL_VALUE_ERROR: Lazy<ExceptionClass> = Lazy::new(|ruby| {
-    ruby.get_inner(&ROOT_MOD)
-        .const_get("NullValueError")
-        .expect("Prosody::NullValueError")
-});
+/// Builds an error of the Ruby-defined `Prosody::<class>` exception class.
+///
+/// A failed class lookup returns the lookup error in place of the state
+/// error.
+fn ruby_error(ruby: &Ruby, class: &str, message: String) -> Error {
+    match ruby
+        .get_inner(&ROOT_MOD)
+        .const_get::<_, ExceptionClass>(class)
+    {
+        Ok(class) => Error::new(class, message),
+        Err(error) => error,
+    }
+}
 
 /// Maps an erased state error to the matching Ruby state-error class.
 ///
@@ -68,60 +52,32 @@ static NULL_VALUE_ERROR: Lazy<ExceptionClass> = Lazy::new(|ruby| {
 /// `#permanent?` path reclassifies a rethrown error with no change.
 pub(crate) fn state_error(ruby: &Ruby, error: &ErasedStateError) -> Error {
     let class = match error.category() {
-        ErasedCategory::Permanent => ruby.get_inner(&PERMANENT_STATE_ERROR),
-        ErasedCategory::Transient => ruby.get_inner(&TRANSIENT_STATE_ERROR),
+        ErasedCategory::Permanent => "PermanentStateError",
+        ErasedCategory::Transient => "TransientStateError",
     };
-    Error::new(class, error.message().to_owned())
+    ruby_error(ruby, class, error.message().to_owned())
 }
 
 /// Builds a transient state error for a caller-caused condition the glue
 /// detects (a wrong item shape, an invalid direction token, an unrepresentable
 /// value).
 fn transient_state_error(ruby: &Ruby, message: String) -> Error {
-    Error::new(ruby.get_inner(&TRANSIENT_STATE_ERROR), message)
-}
-
-/// Builds a null-value error for a rejected JSON-null write.
-fn null_value_error(ruby: &Ruby, message: String) -> Error {
-    Error::new(ruby.get_inner(&NULL_VALUE_ERROR), message)
-}
-
-/// Converts an optional JSON item into a Ruby value or `nil`.
-fn json_or_nil(ruby: &Ruby, item: Option<JsonValue>) -> Result<Value, Error> {
-    match item {
-        Some(value) => serialize(ruby, &value),
-        None => Ok(ruby.qnil().as_value()),
-    }
+    ruby_error(ruby, "TransientStateError", message)
 }
 
 /// Converts an optional message item into a `Prosody::Message` or `nil`.
-#[allow(
-    clippy::unnecessary_wraps,
-    reason = "parity with json_or_nil for uniform call sites"
-)]
-fn message_or_nil(ruby: &Ruby, item: Option<ConsumerMessage<JsonValue>>) -> Result<Value, Error> {
-    match item {
-        Some(message) => Ok(Message::from(message).into_value_with(ruby)),
-        None => Ok(ruby.qnil().as_value()),
-    }
+fn message_or_nil(ruby: &Ruby, item: Option<ConsumerMessage<JsonValue>>) -> Value {
+    item.map(Message::from).into_value_with(ruby)
 }
 
-/// Converts a Ruby argument into a storable JSON item.
+/// Converts a Ruby argument into a JSON item.
 ///
 /// A value with no JSON representation is a caller mistake and rejects
-/// transient. JSON `null` is rejected with a [`crate::NullValueError`] naming
-/// the deletion verb via `null_advice`.
-fn json_write_item(ruby: &Ruby, value: Value, null_advice: &str) -> Result<JsonValue, Error> {
-    let value: JsonValue = deserialize(ruby, value).map_err(|error| {
+/// transient. Core rejects a JSON `null` write as permanent.
+fn json_write_item(ruby: &Ruby, value: Value) -> Result<JsonValue, Error> {
+    deserialize(ruby, value).map_err(|error| {
         transient_state_error(ruby, format!("value is not representable as JSON: {error}"))
-    })?;
-    if value.is_null() {
-        return Err(null_value_error(
-            ruby,
-            format!("JSON null is not a storable value{null_advice}"),
-        ));
-    }
-    Ok(value)
+    })
 }
 
 /// Converts a Ruby argument into a storable message item.
@@ -140,49 +96,48 @@ fn message_write_item(
     Ok(message.consumer_message())
 }
 
-/// Parses a scan-direction token into the core [`Direction`].
+/// Maps a core [`StoreOutcome`] to `:applied` or `:no_op`.
 ///
-/// An invalid token is a caller mistake and rejects transient.
-pub(crate) fn parse_direction(ruby: &Ruby, direction: StaticSymbol) -> Result<Direction, Error> {
-    match direction.name()? {
-        "forward" => Ok(Direction::Forward),
-        "backward" => Ok(Direction::Backward),
-        other => Err(transient_state_error(
-            ruby,
-            format!("direction: expected :forward or :backward, got :{other}"),
-        )),
+/// `:applied` means the call drained buffered operations. `:no_op` means
+/// nothing was buffered.
+fn outcome_symbol(ruby: &Ruby, outcome: StoreOutcome) -> StaticSymbol {
+    match outcome {
+        StoreOutcome::Applied => ruby.sym_new("applied"),
+        StoreOutcome::NoOp => ruby.sym_new("no_op"),
     }
 }
 
-/// Drives an erased async op that returns `Result<_, ErasedStateError>` through
-/// [`Bridge::wait_for`] with the extracted carrier active, yielding the op's
-/// `Ok` value (state error mapped to the matching Ruby class).
-macro_rules! run_op {
-    ($ruby:expr, $this:expr, $handle:expr, $call:ident ( $($arg:expr),* )) => {{
-        let handle = Arc::clone($handle);
-        let context = extract_opentelemetry_context($ruby, &$this.propagator)?;
-        $this
-            .bridge
-            .wait_for(
-                $ruby,
-                async move { handle.$call($($arg),*).with_context(context).await },
-                Span::current(),
-            )?
-            .map_err(|error| state_error($ruby, &error))
-    }};
+/// Defines the class that a `magnus::wrap` path such as
+/// `"Prosody::NativeSetState"` names.
+fn wrapped_class(ruby: &Ruby, module: RModule, path: &str) -> Result<RClass, Error> {
+    module.define_class(path.trim_start_matches("Prosody::"), ruby.class_object())
 }
 
-/// Drives an infallible erased async op (returning `()`) through
-/// [`Bridge::wait_for`] with the extracted carrier active.
-macro_rules! run_infallible {
-    ($ruby:expr, $this:expr, $handle:expr, $call:ident ()) => {{
+/// Waits for one state operation in the caller's trace. An
+/// [`ErasedStateError`] raises its matching Ruby class.
+pub(crate) fn run_state<F, T>(
+    ruby: &Ruby,
+    bridge: &Bridge,
+    propagator: &Arc<TextMapCompositePropagator>,
+    operation: F,
+) -> Result<T, Error>
+where
+    F: Future<Output = Result<T, ErasedStateError>> + Send + 'static,
+    T: Send + 'static,
+{
+    let context = extract_opentelemetry_context(ruby, propagator)?;
+    bridge
+        .wait_for(ruby, operation.with_context(context), Span::current())?
+        .map_err(|error| state_error(ruby, &error))
+}
+
+/// Calls one method of an erased handle through [`run_state`].
+macro_rules! run_op {
+    ($ruby:expr, $this:expr, $handle:expr, $call:ident ( $($arg:expr),* )) => {{
         let handle = Arc::clone($handle);
-        let context = extract_opentelemetry_context($ruby, &$this.propagator)?;
-        $this.bridge.wait_for(
-            $ruby,
-            async move { handle.$call().with_context(context).await },
-            Span::current(),
-        )?
+        run_state($ruby, &$this.bridge, &$this.propagator, async move {
+            handle.$call($($arg),*).await
+        })
     }};
 }
 
@@ -213,25 +168,36 @@ macro_rules! value_state {
                 ($restore)(ruby, run_op!(ruby, this, &this.state, get())?)
             }
 
-            fn set(ruby: &Ruby, this: &Self, value: Value) -> Result<Value, Error> {
+            fn set(ruby: &Ruby, this: &Self, value: Value) -> Result<(), Error> {
                 let item = ($prepare)(ruby, value)?;
-                run_op!(ruby, this, &this.state, set(item))?;
-                Ok(ruby.qnil().as_value())
+                run_op!(ruby, this, &this.state, set(item))
+            }
+
+            fn clear(ruby: &Ruby, this: &Self) -> Result<(), Error> {
+                run_op!(ruby, this, &this.state, clear())
             }
 
-            fn clear(ruby: &Ruby, this: &Self) -> Result<Value, Error> {
-                run_op!(ruby, this, &this.state, clear())?;
-                Ok(ruby.qnil().as_value())
+            fn commit(ruby: &Ruby, this: &Self) -> Result<StaticSymbol, Error> {
+                let outcome = run_op!(ruby, this, &this.state, commit())?;
+                Ok(outcome_symbol(ruby, outcome))
             }
 
-            fn commit(ruby: &Ruby, this: &Self) -> Result<Value, Error> {
-                run_op!(ruby, this, &this.state, commit())?;
-                Ok(ruby.qnil().as_value())
+            fn rollback(ruby: &Ruby, this: &Self) -> Result<StaticSymbol, Error> {
+                let state = Arc::clone(&this.state);
+                let outcome = run_state(ruby, &this.bridge, &this.propagator, async move {
+                    Ok(state.rollback().await)
+                })?;
+                Ok(outcome_symbol(ruby, outcome))
             }
 
-            fn rollback(ruby: &Ruby, this: &Self) -> Result<Value, Error> {
-                run_infallible!(ruby, this, &this.state, rollback());
-                Ok(ruby.qnil().as_value())
+            pub(super) fn register(ruby: &Ruby, module: RModule) -> Result<(), Error> {
+                let class = wrapped_class(ruby, module, $class)?;
+                class.define_method("get", method!($name::get, 0))?;
+                class.define_method("set", method!($name::set, 1))?;
+                class.define_method("clear", method!($name::clear, 0))?;
+                class.define_method("commit", method!($name::commit, 0))?;
+                class.define_method("rollback", method!($name::rollback, 0))?;
+                Ok(())
             }
         }
     };
@@ -241,8 +207,8 @@ value_state!(
     NativeJsonValueState,
     "Prosody::NativeJsonValueState",
     JsonValue,
-    |ruby, value| json_write_item(ruby, value, "; use clear to remove the value"),
-    json_or_nil
+    json_write_item,
+    |ruby, item| serialize::<_, Value>(ruby, &item)
 );
 value_state!(
     NativeMessageValueState,
@@ -253,7 +219,7 @@ value_state!(
         value,
         "; use clear to delete a message value collection"
     ),
-    message_or_nil
+    |ruby, item| Ok::<_, Error>(message_or_nil(ruby, item))
 );
 
 macro_rules! map_state {
@@ -283,8 +249,12 @@ macro_rules! map_state {
                 ($restore)(ruby, run_op!(ruby, this, &this.state, get(key))?)
             }
 
-            fn contains_key(ruby: &Ruby, this: &Self, key: String) -> Result<Value, Error> {
-                Ok(run_op!(ruby, this, &this.state, contains_key(key))?.into_value_with(ruby))
+            fn contains_key(ruby: &Ruby, this: &Self, key: String) -> Result<bool, Error> {
+                run_op!(ruby, this, &this.state, contains_key(key))
+            }
+
+            fn is_empty(ruby: &Ruby, this: &Self) -> Result<bool, Error> {
+                run_op!(ruby, this, &this.state, is_empty())
             }
 
             fn get_many(ruby: &Ruby, this: &Self, keys: Vec<String>) -> Result<Value, Error> {
@@ -294,56 +264,83 @@ macro_rules! map_state {
                 Ok(array.as_value())
             }
 
-            fn set(ruby: &Ruby, this: &Self, key: String, value: Value) -> Result<Value, Error> {
+            fn contains_many(
+                ruby: &Ruby,
+                this: &Self,
+                keys: Vec<String>,
+            ) -> Result<Vec<bool>, Error> {
+                run_op!(ruby, this, &this.state, contains_many(keys))
+            }
+
+            fn set(ruby: &Ruby, this: &Self, key: String, value: Value) -> Result<(), Error> {
                 let item = ($prepare)(ruby, value)?;
-                run_op!(ruby, this, &this.state, set(key, item))?;
-                Ok(ruby.qnil().as_value())
+                run_op!(ruby, this, &this.state, set(key, item))
             }
 
-            fn remove(ruby: &Ruby, this: &Self, key: String) -> Result<Value, Error> {
-                run_op!(ruby, this, &this.state, remove(key))?;
-                Ok(ruby.qnil().as_value())
+            fn remove(ruby: &Ruby, this: &Self, key: String) -> Result<(), Error> {
+                run_op!(ruby, this, &this.state, remove(key))
             }
 
-            fn clear(ruby: &Ruby, this: &Self) -> Result<Value, Error> {
-                run_op!(ruby, this, &this.state, clear())?;
-                Ok(ruby.qnil().as_value())
+            fn clear(ruby: &Ruby, this: &Self) -> Result<(), Error> {
+                run_op!(ruby, this, &this.state, clear())
             }
 
-            fn scan(ruby: &Ruby, this: &Self, direction: StaticSymbol) -> Result<$scan, Error> {
-                let direction = parse_direction(ruby, direction)?;
-                let _guard = extract_opentelemetry_context(ruby, &this.propagator)?.attach();
-                $scan::new(
-                    ruby,
-                    this.state.scan(direction),
+            fn scan(
+                ruby: &Ruby,
+                this: &Self,
+                direction: StaticSymbol,
+                options: RHash,
+            ) -> Result<$scan, Error> {
+                let query = key_query(ruby, direction, options)?;
+                Ok($scan::new(
+                    this.state.entries().with_query(query).stream(),
                     this.bridge.clone(),
                     Arc::clone(&this.propagator),
-                )
+                ))
             }
 
             fn keys(
                 ruby: &Ruby,
                 this: &Self,
                 direction: StaticSymbol,
+                options: RHash,
             ) -> Result<NativeMapKeyScan, Error> {
-                let direction = parse_direction(ruby, direction)?;
-                let _guard = extract_opentelemetry_context(ruby, &this.propagator)?.attach();
-                NativeMapKeyScan::new(
-                    ruby,
-                    this.state.keys(direction),
+                let query = key_query(ruby, direction, options)?;
+                Ok(NativeMapKeyScan::new(
+                    this.state.keys().with_query(query).stream(),
                     this.bridge.clone(),
                     Arc::clone(&this.propagator),
-                )
+                ))
             }
 
-            fn commit(ruby: &Ruby, this: &Self) -> Result<Value, Error> {
-                run_op!(ruby, this, &this.state, commit())?;
-                Ok(ruby.qnil().as_value())
+            fn commit(ruby: &Ruby, this: &Self) -> Result<StaticSymbol, Error> {
+                let outcome = run_op!(ruby, this, &this.state, commit())?;
+                Ok(outcome_symbol(ruby, outcome))
             }
 
-            fn rollback(ruby: &Ruby, this: &Self) -> Result<Value, Error> {
-                run_infallible!(ruby, this, &this.state, rollback());
-                Ok(ruby.qnil().as_value())
+            fn rollback(ruby: &Ruby, this: &Self) -> Result<StaticSymbol, Error> {
+                let state = Arc::clone(&this.state);
+                let outcome = run_state(ruby, &this.bridge, &this.propagator, async move {
+                    Ok(state.rollback().await)
+                })?;
+                Ok(outcome_symbol(ruby, outcome))
+            }
+
+            pub(super) fn register(ruby: &Ruby, module: RModule) -> Result<(), Error> {
+                let class = wrapped_class(ruby, module, $class)?;
+                class.define_method("get", method!($name::get, 1))?;
+                class.define_method("contains_key", method!($name::contains_key, 1))?;
+                class.define_method("is_empty", method!($name::is_empty, 0))?;
+                class.define_method("get_many", method!($name::get_many, 1))?;
+                class.define_method("contains_many", method!($name::contains_many, 1))?;
+                class.define_method("set", method!($name::set, 2))?;
+                class.define_method("remove", method!($name::remove, 1))?;
+                class.define_method("clear", method!($name::clear, 0))?;
+                class.define_method("scan", method!($name::scan, 2))?;
+                class.define_method("keys", method!($name::keys, 2))?;
+                class.define_method("commit", method!($name::commit, 0))?;
+                class.define_method("rollback", method!($name::rollback, 0))?;
+                Ok(())
             }
         }
     };
@@ -354,8 +351,8 @@ map_state!(
     "Prosody::NativeJsonMapState",
     JsonValue,
     NativeJsonMapScan,
-    |ruby, value| json_write_item(ruby, value, "; use delete(key) to remove the entry"),
-    json_or_nil
+    json_write_item,
+    |ruby, item| serialize::<_, Value>(ruby, &item)
 );
 map_state!(
     NativeMessageMapState,
@@ -367,122 +364,20 @@ map_state!(
         value,
         "; use delete(key) to remove a message map entry"
     ),
-    message_or_nil
-);
-macro_rules! deque_state {
-    ($name:ident, $class:literal, $item:ty, $scan:ident, $prepare:expr, $restore:expr) => {
-        /// Native deque handle with one payload type.
-        #[magnus::wrap(class = $class)]
-        pub struct $name {
-            state: Arc<dyn DynDequeState<$item>>,
-            bridge: Bridge,
-            propagator: Arc<TextMapCompositePropagator>,
-        }
-
-        impl $name {
-            pub(crate) fn new(
-                state: Arc<dyn DynDequeState<$item>>,
-                bridge: Bridge,
-                propagator: Arc<TextMapCompositePropagator>,
-            ) -> Self {
-                Self {
-                    state,
-                    bridge,
-                    propagator,
-                }
-            }
-
-            fn len(ruby: &Ruby, this: &Self) -> Result<Value, Error> {
-                Ok(run_op!(ruby, this, &this.state, len())?.into_value_with(ruby))
-            }
-
-            fn is_empty(ruby: &Ruby, this: &Self) -> Result<Value, Error> {
-                Ok(run_op!(ruby, this, &this.state, is_empty())?.into_value_with(ruby))
-            }
-
-            fn get(ruby: &Ruby, this: &Self, index: usize) -> Result<Value, Error> {
-                ($restore)(ruby, run_op!(ruby, this, &this.state, get(index))?)
-            }
-
-            fn peek_front(ruby: &Ruby, this: &Self) -> Result<Value, Error> {
-                ($restore)(ruby, run_op!(ruby, this, &this.state, peek_front())?)
-            }
-
-            fn peek_back(ruby: &Ruby, this: &Self) -> Result<Value, Error> {
-                ($restore)(ruby, run_op!(ruby, this, &this.state, peek_back())?)
-            }
-
-            fn push_back(ruby: &Ruby, this: &Self, value: Value) -> Result<Value, Error> {
-                let item = ($prepare)(ruby, value)?;
-                run_op!(ruby, this, &this.state, push_back(item))?;
-                Ok(ruby.qnil().as_value())
-            }
-
-            fn push_front(ruby: &Ruby, this: &Self, value: Value) -> Result<Value, Error> {
-                let item = ($prepare)(ruby, value)?;
-                run_op!(ruby, this, &this.state, push_front(item))?;
-                Ok(ruby.qnil().as_value())
-            }
-
-            fn pop_front(ruby: &Ruby, this: &Self) -> Result<Value, Error> {
-                ($restore)(ruby, run_op!(ruby, this, &this.state, pop_front())?)
-            }
-
-            fn pop_back(ruby: &Ruby, this: &Self) -> Result<Value, Error> {
-                ($restore)(ruby, run_op!(ruby, this, &this.state, pop_back())?)
-            }
-
-            fn clear(ruby: &Ruby, this: &Self) -> Result<Value, Error> {
-                run_op!(ruby, this, &this.state, clear())?;
-                Ok(ruby.qnil().as_value())
-            }
-
-            fn scan(ruby: &Ruby, this: &Self, direction: StaticSymbol) -> Result<$scan, Error> {
-                let direction = parse_direction(ruby, direction)?;
-                let _guard = extract_opentelemetry_context(ruby, &this.propagator)?.attach();
-                $scan::new(
-                    ruby,
-                    this.state.scan(direction),
-                    this.bridge.clone(),
-                    Arc::clone(&this.propagator),
-                )
-            }
-
-            fn commit(ruby: &Ruby, this: &Self) -> Result<Value, Error> {
-                run_op!(ruby, this, &this.state, commit())?;
-                Ok(ruby.qnil().as_value())
-            }
-
-            fn rollback(ruby: &Ruby, this: &Self) -> Result<Value, Error> {
-                run_infallible!(ruby, this, &this.state, rollback());
-                Ok(ruby.qnil().as_value())
-            }
-        }
-    };
-}
-
-deque_state!(
-    NativeJsonDequeState,
-    "Prosody::NativeJsonDequeState",
-    JsonValue,
-    NativeJsonDequeScan,
-    |ruby, value| json_write_item(ruby, value, " in a deque"),
-    json_or_nil
-);
-deque_state!(
-    NativeMessageDequeState,
-    "Prosody::NativeMessageDequeState",
-    ConsumerMessage<JsonValue>,
-    NativeMessageDequeScan,
-    |ruby, value| message_write_item(ruby, value, " to push into a message deque"),
-    message_or_nil
+    |ruby, item| Ok::<_, Error>(message_or_nil(ruby, item))
 );
+mod deque;
+mod query;
 mod scan;
+mod set;
 
+pub(crate) use deque::{NativeJsonDequeState, NativeMessageDequeState};
+pub(crate) use query::{key_query, position_query};
 pub(crate) use scan::{
     NativeJsonDequeScan, NativeJsonMapScan, NativeMapKeyScan, NativeMessageDequeScan,
-    NativeMessageMapScan, published_deque_scan, published_map_key_scan, published_map_scan,
+    NativeMessageMapScan,
 };
+pub(crate) use set::NativeSetState;
 mod registration;
 
 pub(crate) use registration::register;