prosody 0.3.0 → 0.5.0

data/Rakefile

@@ -23,4 +23,14 @@ RSpec::Core::RakeTask.new(:spec)
 
 require "standard/rake"
 
-task default: %i[compile spec standard]
+desc "Validate RBS signatures over the whole sig/ tree"
+task :rbs do
+  sh "rbs -r logger -I sig validate"
+end
+
+desc "Type-check the Ruby implementation against its RBS signatures"
+task :steep do
+  sh "steep check --with-expectations --severity-level=error"
+end
+
+task default: %i[compile spec standard rbs steep]

data/examples/keyed_state.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "prosody"
+require "logger"
+
+# Keyed-state example: per-key value/map/deque collections that survive across
+# events. Definitions are declared once and reused for both registration (on the
+# client) and binding (inside the handler). Every state op yields the fiber,
+# never the thread.
+
+# Definitions: declared once, reused for registration and binding. See
+# keyed_state.rbs for payload and state types checked by Steep.
+CART = Prosody.value("cart", ttl: 30 * 24 * 3600)      # ValueState
+TOTALS = Prosody.map("totals")                          # keys are always String
+BACKLOG = Prosody.message_deque("backlog", capacity: 100) # bounded window of messages
+
+class KeyedStateHandler < Prosody::EventHandler
+  def on_excise(context, message)
+    puts "Excise #{message.key}"
+    context.state(CART).clear
+    context.state(TOTALS).clear
+    context.state(BACKLOG).clear
+    nil
+  end
+
+  def initialize(logger:)
+    @logger = logger
+  end
+
+  def on_message(context, message)
+    payload = message.payload
+    cart = context.state(CART)             # bound for this attempt only
+    current = cart.get || {"items" => []}  # Hash, or nil when absent
+    cart.set(current.merge("items" => current["items"] + [payload["order_id"]]))
+
+    totals = context.state(TOTALS)
+    totals.set(message.key, payload["total"])
+    # Steep infers key as String and total as Integer from TOTALS's RBS type.
+    totals.each_pair { |key, total| @logger.info(format_total(key, total)) }
+
+    backlog = context.state(BACKLOG)
+    backlog.push(message)                  # stores the full Prosody::Message
+    oldest = backlog.get(0)                # Message[order_event]?, preserving payload shape
+    @logger.info("oldest order: #{format_order_id(oldest.payload["order_id"])}") if oldest
+  end
+
+  def on_timer(_context, _timer)
+  end
+
+  private
+
+  def format_total(key, total)
+    "#{key}=#{total}"
+  end
+
+  def format_order_id(order_id)
+    order_id
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  client = Prosody::Client.new(
+    mock: true,
+    group_id: "keyed-state-example",
+    subscribed_topics: "orders",
+    state_collections: [CART, TOTALS, BACKLOG]
+  )
+  client.subscribe(KeyedStateHandler.new(logger: Logger.new($stdout)))
+  client.shutdown
+end

data/examples/keyed_state.rbs

@@ -0,0 +1,18 @@
+type keyed_state_cart = { "items" => Array[String] }
+type keyed_state_order_event = { "order_id" => String, "total" => Integer }
+
+CART: Prosody::_ValueDefinition[keyed_state_cart]
+TOTALS: Prosody::_MapDefinition[Integer]
+BACKLOG: Prosody::_MessageDequeDefinition[keyed_state_order_event]
+
+class KeyedStateHandler < Prosody::EventHandler[keyed_state_order_event]
+  @logger: Logger
+
+  def initialize: (logger: Logger) -> void
+  def on_message: (Prosody::Context context, Prosody::Message[keyed_state_order_event] message) -> void
+
+  private
+
+  def format_total: (String key, Integer total) -> String
+  def format_order_id: (String order_id) -> String
+end

data/examples/keyed_state_windowing.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "prosody"
+
+# The complete typed counterpart of the README burst-windowing example.
+ACTIVITY_WINDOW = Prosody.value("activity-window")
+PENDING_ACTIVITIES = Prosody.message_deque("pending-activities", capacity: 100)
+
+class ActivityWindowHandler < Prosody::EventHandler
+  def on_excise(context, message)
+    puts "Excise #{message.key}"
+    context.state(PENDING_ACTIVITIES).clear
+    context.state(ACTIVITY_WINDOW).clear
+    context.clear_scheduled
+    nil
+  end
+
+  def on_message(context, message)
+    window = context.state(ACTIVITY_WINDOW)
+    pending = context.state(PENDING_ACTIVITIES)
+
+    if window.get
+      pending.push(message)
+    else
+      notify(message.key, [message])
+      window.set(true)
+      context.clear_and_schedule(Time.now + 5 * 60)
+    end
+  end
+
+  def on_timer(context, timer)
+    pending = context.state(PENDING_ACTIVITIES)
+    batch = pending.each.to_a
+    notify(timer.key, batch) unless batch.empty?
+    pending.clear
+    context.state(ACTIVITY_WINDOW).clear
+  end
+
+  private
+
+  def notify(user_id, activities)
+    puts "notify #{user_id}: #{activities.length} activities"
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  client = Prosody::Client.new(
+    mock: true,
+    group_id: "activity-window-example",
+    subscribed_topics: "activities",
+    state_collections: [ACTIVITY_WINDOW, PENDING_ACTIVITIES]
+  )
+  client.subscribe(ActivityWindowHandler.new)
+  client.shutdown
+end

data/examples/keyed_state_windowing.rbs

@@ -0,0 +1,16 @@
+type activity_event = {
+  "actor" => String,
+  "action" => String
+}
+
+ACTIVITY_WINDOW: Prosody::_ValueDefinition[bool]
+PENDING_ACTIVITIES: Prosody::_MessageDequeDefinition[activity_event]
+
+class ActivityWindowHandler < Prosody::EventHandler[activity_event]
+  def on_message: (Prosody::Context context, Prosody::Message[activity_event] message) -> void
+  def on_timer: (Prosody::Context context, Prosody::Timer timer) -> void
+
+  private
+
+  def notify: (String user_id, Array[Prosody::Message[activity_event]] activities) -> void
+end

data/ext/prosody/Cargo.toml

@@ -11,6 +11,7 @@ crate-type = ["cdylib"]
 [dependencies]
 atomic-take.workspace = true
 bumpalo = { workspace = true, features = ["collections"] }
+crossbeam-channel.workspace = true
 educe.workspace = true
 futures.workspace = true
 magnus = { workspace = true, default-features = false }

data/ext/prosody/src/admin.rs

@@ -6,8 +6,7 @@
 use crate::bridge::Bridge;
 use crate::util::ensure_runtime_context;
 use crate::{ROOT_MOD, id};
-use magnus::value::ReprValue;
-use magnus::{Error, Module, Object, Ruby, Value, function, method};
+use magnus::{Error, Module, Object, Ruby, function, method};
 use prosody::admin::{AdminConfiguration, ProsodyAdminClient, TopicConfiguration};
 use std::sync::Arc;
 use tracing::Span;
@@ -164,8 +163,5 @@ pub fn init(ruby: &Ruby) -> Result<(), Error> {
         method!(AdminClient::delete_topic, 1),
     )?;
 
-    // Make the admin client class private
-    let _: Value = module.funcall(id!(ruby, "private_constant"), (class_id,))?;
-
     Ok(())
 }

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

@@ -9,15 +9,12 @@ use crate::bridge::callback::AsyncCallback;
 use crate::gvl::{GvlError, without_gvl};
 use crate::{ROOT_MOD, RUNTIME, id};
 use atomic_take::AtomicTake;
+use crossbeam_channel::{Receiver, Sender, TryRecvError, TrySendError, bounded, select, unbounded};
 use educe::Educe;
-use futures::executor::block_on;
 use magnus::value::{Lazy, ReprValue};
 use magnus::{Error, Module, RClass, Ruby, Value};
 use std::any::Any;
 use thiserror::Error;
-use tokio::select;
-use tokio::sync::mpsc::error::SendError;
-use tokio::sync::mpsc::{UnboundedReceiver, UnboundedSender, unbounded_channel};
 use tokio::sync::oneshot;
 use tracing::{Instrument, Span, debug, error, warn};
 
@@ -63,7 +60,7 @@ pub struct Bridge {
     /// Channel sender for submitting functions to be executed in the Ruby
     /// context.
     #[educe(Debug(ignore))]
-    tx: UnboundedSender<RubyFunction>,
+    tx: Sender<RubyFunction>,
 }
 
 impl Bridge {
@@ -83,12 +80,12 @@ impl Bridge {
     ///
     /// A new `Bridge` instance.
     pub fn new(ruby: &Ruby) -> Self {
-        let (tx, mut rx) = unbounded_channel();
+        let (tx, rx) = unbounded();
 
         // Create a dedicated Ruby thread to process functions
         ruby.thread_create_from_fn(move |ruby| {
             loop {
-                let Err(error) = poll(&mut rx, ruby) else {
+                let Err(error) = poll(&rx, ruby) else {
                     continue;
                 };
 
@@ -208,8 +205,8 @@ impl Bridge {
     /// Unlike [`run`](Self::run), this method does not await a result and can
     /// be called from synchronous contexts such as `Drop` implementations.
     /// Returns `Err` only if the bridge receiver has been dropped (shutdown).
-    pub(crate) fn send(&self, function: RubyFunction) -> Result<(), SendError<RubyFunction>> {
-        self.tx.send(function)
+    pub(crate) fn send(&self, function: RubyFunction) -> Result<(), BridgeError> {
+        self.tx.send(function).map_err(|_| BridgeError::Shutdown)
     }
 }
 
@@ -233,32 +230,24 @@ impl Bridge {
 ///
 /// Returns a `BridgeError` if there was an issue with polling or executing
 /// commands.
-fn poll(rx: &mut UnboundedReceiver<RubyFunction>, ruby: &Ruby) -> Result<(), BridgeError> {
-    // Set up cancellation channel
-    let (cancel_tx, cancel_rx) = oneshot::channel();
-    let mut maybe_cancel_tx = Some(cancel_tx);
+fn poll(rx: &Receiver<RubyFunction>, ruby: &Ruby) -> Result<(), BridgeError> {
+    let (cancel_tx, cancel_rx) = bounded(1);
 
     // Function to be executed without the GVL (Global VM Lock)
     let poll_fn = || {
-        // Wait for either a command or cancellation
-        let maybe_command = block_on(async {
-            select! {
-                _ = cancel_rx => Err(BridgeError::Cancelled),
-                result = rx.recv() => Ok(result),
-            }
-        })?;
-
-        let first_command = maybe_command.ok_or(BridgeError::Shutdown)?;
+        let first_command = select! {
+            recv(cancel_rx) -> _ => return Err(BridgeError::Cancelled),
+            recv(rx) -> result => result.map_err(|_| BridgeError::Shutdown)?,
+        };
 
         // Batch up to POLL_BATCH_SIZE commands
         let mut commands = Vec::with_capacity(POLL_BATCH_SIZE);
         commands.push(first_command);
 
         while commands.len() < POLL_BATCH_SIZE {
-            if let Ok(command) = rx.try_recv() {
-                commands.push(command);
-            } else {
-                break;
+            match rx.try_recv() {
+                Ok(command) => commands.push(command),
+                Err(TryRecvError::Empty | TryRecvError::Disconnected) => break,
             }
         }
 
@@ -266,12 +255,8 @@ fn poll(rx: &mut UnboundedReceiver<RubyFunction>, ruby: &Ruby) -> Result<(), Bri
     };
 
     // Function to cancel polling if needed
-    let cancel_fn = || {
-        let Some(cancel_tx) = maybe_cancel_tx.take() else {
-            return;
-        };
-
-        if cancel_tx.send(()).is_err() {
+    let cancel_fn = move || {
+        if matches!(cancel_tx.try_send(()), Err(TrySendError::Disconnected(()))) {
             warn!("Failed to cancel poll operation");
         }
     };