prosody 0.3.0-aarch64-linux → 0.5.0-aarch64-linux

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/lib/prosody/configuration.rb

@@ -131,7 +131,7 @@ module Prosody
     config_param :max_retry_delay, converter: ->(v) { duration_converter(v) }
 
     # Global shared cache capacity across all partitions for message deduplication.
-    # Default 8192. Set to 0 to disable deduplication entirely.
+    # Must be at least 1. Default: 8192.
     config_param :idempotence_cache_size, converter: ->(v) { Integer(v) }
 
     # Version string for cache-busting deduplication hashes. Changing this
@@ -156,6 +156,21 @@ module Prosody
     # Identifier for the system producing messages.
     config_param :source_system, converter: lambda(&:to_s)
 
+    # Address for the peer listener.
+    config_param :peer_bind_address, converter: lambda(&:to_s)
+
+    # gRPC connect URI that other clients use for this client.
+    config_param :peer_advertised_connect, converter: lambda(&:to_s)
+
+    # Network name used to identify direct routes.
+    config_param :peer_network_name, converter: lambda(&:to_s)
+
+    # Maximum number of peer channels and registrations in each cache.
+    config_param :peer_cache_capacity, converter: ->(v) { Integer(v) }
+
+    # Duration of each peer registration lease.
+    config_param :peer_registration_ttl, converter: ->(v) { duration_converter(v) }
+
     # Topic to send failed messages to.
     config_param :failure_topic, converter: lambda(&:to_s)
 
@@ -172,7 +187,7 @@ module Prosody
         end
       }
 
-    # Keyspace to use for storing timer data in Cassandra.
+    # Keyspace used for persistent Prosody data in Cassandra.
     config_param :cassandra_keyspace, converter: lambda(&:to_s)
 
     # Preferred datacenter for Cassandra query routing.
@@ -187,7 +202,7 @@ module Prosody
     # Password for authenticating with Cassandra.
     config_param :cassandra_password, converter: lambda(&:to_s)
 
-    # Retention period for failed/unprocessed timer data in Cassandra.
+    # Retention period for persistent timer and deferral data in Cassandra.
     # Accepts duration objects or numeric values (in seconds).
     config_param :cassandra_retention, converter: ->(v) { duration_converter(v) }
 
@@ -235,23 +250,28 @@ module Prosody
     # Maximum delay between deferred retries (in seconds).
     config_param :defer_max_delay, converter: ->(v) { duration_converter(v) }
 
-    # Failure rate threshold for enabling deferral (0.0 to 1.0).
+    # Failure rate threshold for disabling deferral (0.0 to 1.0).
     config_param :defer_failure_threshold, converter: ->(v) { Float(v) }
 
     # Sliding window duration (in seconds) for failure rate tracking.
     config_param :defer_failure_window, converter: ->(v) { duration_converter(v) }
 
-    # Cache size for defer middleware.
-    config_param :defer_cache_size, converter: ->(v) { Integer(v) }
-
     # Maximum deferred store cache entries per Cassandra defer store. Env: PROSODY_DEFER_STORE_CACHE_SIZE
     config_param :defer_store_cache_size, converter: ->(v) { Integer(v) }
 
-    # Timeout for Kafka seek operations (in seconds).
-    config_param :defer_seek_timeout, converter: ->(v) { duration_converter(v) }
+    # Kafka message loader configuration
+    #
+    # Maximum messages retained by the shared Kafka loader.
+    # Env: PROSODY_LOADER_CACHE_SIZE. Default: 1024.
+    config_param :loader_cache_size, converter: ->(v) { Integer(v) }
 
-    # Messages to read sequentially before seeking.
-    config_param :defer_discard_threshold, converter: ->(v) { Integer(v) }
+    # Timeout for Kafka loader seek operations (in seconds).
+    # Env: PROSODY_LOADER_SEEK_TIMEOUT. Default: 30 seconds.
+    config_param :loader_seek_timeout, converter: ->(v) { duration_converter(v) }
+
+    # Sequential-read distance before the loader seeks.
+    # Env: PROSODY_LOADER_DISCARD_THRESHOLD. Default: 100.
+    config_param :loader_discard_threshold, converter: ->(v) { Integer(v) }
 
     # Timeout configuration
     #
@@ -281,6 +301,46 @@ module Prosody
     # Overrides the PROSODY_TIMER_SPANS environment variable. Default: "follows_from".
     config_param :timer_spans, converter: ->(v) { v.to_s }
 
+    # Keyed-state collections to register before subscribe.
+    #
+    # Accepts an array of StateDefinition objects (from Prosody.value/map/deque
+    # and their message_* siblings) or already-serialized registration hashes.
+    # Duplicate names within the set are rejected by the native layer.
+    config_param :state_collections,
+      converter: lambda { |v|
+        list = v.is_a?(Hash) ? [v] : Array(v)
+        list.map { |d| d.respond_to?(:to_state_config) ? d.to_state_config : d }
+      }
+
+    # Subsystem under which published JSON collections are advertised.
+    # Uses PROSODY_SUBSYSTEM when omitted. Published collections require it.
+    config_param :subsystem, converter: lambda(&:to_s)
+
+    # Disk workspace for the local keyed-state cache. Each live client
+    # needs its own directory. Falls back to the
+    # PROSODY_STATE_CACHE_DIR environment variable. Must not be an empty string.
+    config_param :state_cache_dir, converter: lambda(&:to_s)
+
+    # Capacity of the owning keyed-state cache, such as "64 MiB". Uses
+    # PROSODY_STATE_OWNED_CACHE_SIZE when omitted. Otherwise, the engine
+    # selects its default.
+    config_param :state_owned_cache_size, converter: lambda(&:to_s)
+
+    # Capacity of the published-state read-through cache, such as "1 MiB".
+    # Uses PROSODY_STATE_READ_CACHE_SIZE when omitted. It then uses the owned
+    # cache size when set, or 1 MiB when both sizes are unset.
+    config_param :state_read_cache_size, converter: lambda(&:to_s)
+
+    # Default published-read cache policy in seconds, or false to bypass it.
+    # Uses PROSODY_STATE_READ_CACHE_TTL when omitted, then 5 seconds.
+    config_param :state_read_cache,
+      converter: ->(v) { (v == true || v == false) ? v : Float(v) }
+
+    # Delay in whole seconds between staging a provisional cell and the
+    # keyed-state recovery sweep. Every registered TTL must strictly exceed this.
+    # Must be a whole number of seconds >= 1 (validated natively).
+    config_param :state_recovery_delay, converter: ->(v) { duration_converter(v) }
+
     # Operation mode of the client.
     #
     # Valid values:

data/lib/prosody/handler.rb

@@ -69,7 +69,7 @@ module Prosody
     #
     # @param [Symbol] method_name the name of the method to wrap
     # @param [Class<Exception>] exception_classes one or more Exception subclasses to catch
-    # @return [void]
+    # @return [Prosody::json_value] The wrapped method result
     # @raise [ArgumentError] if no exception classes given
     # @raise [NameError] if method_name is not defined on this class or its ancestors
     def permanent(method_name, *exception_classes)
@@ -81,7 +81,7 @@ module Prosody
     #
     # @param [Symbol] method_name the name of the method to wrap
     # @param [Class<Exception>] exception_classes one or more Exception subclasses to catch
-    # @return [void]
+    # @return [Prosody::json_value] The wrapped method result
     # @raise [ArgumentError] if no exception classes given
     # @raise [NameError] if method_name is not defined on this class or its ancestors
     def transient(method_name, *exception_classes)
@@ -96,7 +96,7 @@ module Prosody
     # @param [Symbol] method_name the method to wrap
     # @param [Array<Class<Exception>>] exception_classes exceptions to catch
     # @param [Class<EventHandlerError>] error_class the error class to wrap caught exceptions in
-    # @return [void]
+    # @return [Prosody::json_value] the message response
     def wrap_errors(method_name, exception_classes, error_class)
       # Must specify at least one exception class
       if exception_classes.empty?
@@ -114,9 +114,10 @@ module Prosody
           super(*args, &block)
         rescue *exception_classes => e
           # The new exception's #cause will be set automatically
-          raise error_class.new(e.message)
+          Kernel.raise error_class.new(e.message)
         end
       end
+      wrapper.instance_variable_set(:@prosody_error_wrapper, true)
 
       prepend wrapper
     end
@@ -127,8 +128,10 @@ module Prosody
   # --------------------------------------------------------------------------
 
   # Abstract base class for handling incoming messages and timers from Prosody.
-  # Subclasses **must** implement `#on_message` to process received messages.
-  # Subclasses **may** implement `#on_timer` to process timer events.
+  # The RBS type parameters describe the message payload and handler response.
+  # Both parameters default to +Prosody::json_value+. Declare narrower types in
+  # your application's RBS to check payload access and handler responses.
+  # Subclasses must implement `#on_message`, `#on_excise`, and `#on_timer`.
   # They may also use `permanent` or `transient` decorators to control retry logic.
   #
   # @example
@@ -144,6 +147,10 @@ module Prosody
   #       # Process message...
   #     end
   #
+  #     def on_excise(context, message)
+  #       # Process excise record...
+  #     end
+  #
   #     def on_timer(context, trigger)
   #       # Process timer event...
   #     end
@@ -151,18 +158,68 @@ module Prosody
   class EventHandler
     extend ErrorClassification
 
+    HANDLER_METHODS = %i[on_message on_excise on_timer].freeze
+
+    def self.validate_handler!(handler)
+      owners = handler.class.ancestors.take_while { |owner| owner != self }
+
+      HANDLER_METHODS.each do |name|
+        validate_method!(handler, owners, name)
+      end
+    end
+
+    def self.validate_method!(handler, owners, name)
+      implemented = owners.any? do |owner|
+        !owner.instance_variable_get(:@prosody_error_wrapper) &&
+          (owner.instance_methods(false) + owner.private_instance_methods(false)).include?(name)
+      end
+      raise ArgumentError, "handler must implement ##{name}" unless implemented
+      method = handler.method(name)
+      while method.owner.instance_variable_get(:@prosody_error_wrapper)
+        method = method.super_method
+        raise ArgumentError, "handler must implement ##{name}" unless method
+      end
+      return if accepts_two_parameters?(method)
+
+      raise ArgumentError, "handler ##{name} must accept two parameters"
+    end
+    private_class_method :validate_method!
+
+    def self.accepts_two_parameters?(method)
+      parameters = method.parameters
+      required = parameters.count { |kind, _| kind == :req }
+      positional = parameters.count do |parameter|
+        parameter.first == :req || parameter.first == :opt
+      end
+      has_rest = parameters.any? { |kind, _| kind == :rest }
+      has_required_keyword = parameters.any? { |kind, _| kind == :keyreq }
+
+      !has_required_keyword && required <= 2 && (has_rest || positional >= 2)
+    end
+    private_class_method :accepts_two_parameters?
+
     # Process a single message received from Prosody.
     # This method must be implemented by subclasses to define
     # custom message handling logic.
     #
     # @param [Context] context the message context
-    # @param [Message] message the message payload
+    # @param [Message<Payload>] message the message and its typed JSON payload
     # @raise [NotImplementedError] if not overridden by subclass
-    # @return [void]
+    # @return [Prosody::json_value] the message response
     def on_message(context, message)
       raise NotImplementedError, "Subclasses must implement #on_message"
     end
 
+    # Process an excise record for a key.
+    #
+    # @param [Context] context the event context
+    # @param [ExciseMessage] message the excise record metadata
+    # @raise [NotImplementedError] if not overridden by a subclass
+    # @return [Prosody::json_value] the excise response
+    def on_excise(context, message)
+      raise NotImplementedError, "Subclasses must implement #on_excise"
+    end
+
     # Process a timer event when it fires.
     # This method must be implemented by subclasses to handle
     # scheduled timer events if they can fire.