prosody 0.4.0-aarch64-linux → 0.5.1-aarch64-linux

data/examples/keyed_state.rb

@@ -15,17 +15,26 @@ 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"] + [message.payload["order_id"]]))
+    cart.set(current.merge("items" => current["items"] + [payload["order_id"]]))
 
     totals = context.state(TOTALS)
-    totals.set(message.key, message.payload["total"])
+    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)) }
 
@@ -35,6 +44,9 @@ class KeyedStateHandler < Prosody::EventHandler
     @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)
@@ -54,5 +66,5 @@ if __FILE__ == $PROGRAM_NAME
     state_collections: [CART, TOTALS, BACKLOG]
   )
   client.subscribe(KeyedStateHandler.new(logger: Logger.new($stdout)))
-  client.unsubscribe
+  client.shutdown
 end

data/examples/keyed_state_windowing.rb

@@ -7,6 +7,14 @@ 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)
@@ -43,5 +51,5 @@ if __FILE__ == $PROGRAM_NAME
     state_collections: [ACTIVITY_WINDOW, PENDING_ACTIVITIES]
   )
   client.subscribe(ActivityWindowHandler.new)
-  client.unsubscribe
+  client.shutdown
 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) }
+
+    # 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) }
 
-    # Messages to read sequentially before seeking.
-    config_param :defer_discard_threshold, converter: ->(v) { Integer(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
     #
@@ -292,15 +312,29 @@ module Prosody
         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 in-memory keyed-state cache, in bytes. Falls back to
-    # PROSODY_STATE_CACHE_SIZE_BYTES, then
-    # the storage-engine default.
-    config_param :state_cache_size_bytes, converter: ->(v) { Integer(v) }
+    # 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.

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?
@@ -117,6 +117,7 @@ module Prosody
           Kernel.raise error_class.new(e.message)
         end
       end
+      wrapper.instance_variable_set(:@prosody_error_wrapper, true)
 
       prepend wrapper
     end
@@ -127,12 +128,10 @@ module Prosody
   # --------------------------------------------------------------------------
 
   # Abstract base class for handling incoming messages and timers from Prosody.
-  # The RBS type parameter describes the JSON payload delivered in each
-  # {Message}; it defaults to +Prosody::json_value+. Declare a narrower payload
-  # shape in your application's RBS (for example,
-  # +EventHandler[order_event]+) to type-check payload access.
-  # 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
@@ -148,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
@@ -155,6 +158,46 @@ 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.
@@ -162,11 +205,21 @@ module Prosody
     # @param [Context] context the message context
     # @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.