prosody 0.4.0 → 0.5.0

data/ext/prosody/src/util.rs

@@ -6,13 +6,16 @@
 
 use crate::bridge::Bridge;
 use crate::logging::Logger;
-use crate::{BRIDGE, RUNTIME, TRACING_INIT};
-use magnus::value::BoxValue;
-use magnus::{Ruby, Value};
-use prosody::tracing::initialize_tracing;
+use crate::{BRIDGE, ROOT_MOD, RUNTIME, TRACING_INIT};
+use magnus::value::{BoxValue, ReprValue};
+use magnus::{Error, Ruby, Value, function};
+use prosody::tracing::{
+    TracingError, flush_telemetry as core_flush_telemetry, initialize_tracing,
+    shutdown_telemetry as core_shutdown_telemetry,
+};
 use std::mem::{ManuallyDrop, forget};
 use tokio::runtime::{EnterGuard, Handle};
-use tracing::warn;
+use tracing::{error, warn};
 
 /// Creates a static Ruby identifier (symbol) for efficient reuse.
 ///
@@ -217,3 +220,81 @@ pub fn ensure_runtime_context(ruby: &Ruby) -> Option<EnterGuard<'static>> {
 
     guard
 }
+
+/// Exports buffered telemetry (spans and metrics) without shutting the
+/// export pipeline down. Safe to call even if tracing was never initialized.
+///
+/// Use for a mid-run flush — e.g. one of several clients in a process
+/// shutting down while others keep running. [`shutdown_telemetry`] is
+/// registered automatically to run once at process exit, so most
+/// applications only need this for manual, mid-run flushes.
+///
+/// Blocks the calling thread until the export completes.
+///
+/// # Errors
+///
+/// Returns a `RuntimeError` if the span or metric exporter fails to flush.
+pub fn flush_telemetry(ruby: &Ruby) -> Result<(), Error> {
+    core_flush_telemetry().map_err(|error| tracing_error(ruby, &error))
+}
+
+/// Flushes buffered telemetry and shuts the export pipeline down. Safe to
+/// call even if tracing was never initialized.
+///
+/// Registered to run once via `Kernel#at_exit` (see
+/// [`register_shutdown_at_exit`]), so applications get it for free; call it
+/// directly only for tests or other cases that need shutdown before the
+/// process actually exits.
+///
+/// Blocks the calling thread until the final export completes.
+///
+/// # Errors
+///
+/// Returns a `RuntimeError` if the span or metric pipeline fails to shut
+/// down.
+pub fn shutdown_telemetry(ruby: &Ruby) -> Result<(), Error> {
+    core_shutdown_telemetry().map_err(|error| tracing_error(ruby, &error))
+}
+
+/// Registers [`shutdown_telemetry`] to run once via `Kernel#at_exit`, so
+/// short-lived processes don't lose the tail of telemetry buffered since the
+/// last periodic export.
+///
+/// Failures are logged rather than raised: exceptions from an `at_exit`
+/// block are easy to miss and shouldn't prevent the process from exiting.
+///
+/// # Errors
+///
+/// Returns a `Magnus::Error` if registering the `at_exit` hook fails.
+fn register_shutdown_at_exit(ruby: &Ruby) -> Result<(), Error> {
+    let _: Value = ruby
+        .module_kernel()
+        .block_call("at_exit", (), |_ruby, _args, _block| {
+            if let Err(error) = core_shutdown_telemetry() {
+                error!("failed to shut down telemetry at exit: {error:#}");
+            }
+        })?;
+
+    Ok(())
+}
+
+/// Converts a [`TracingError`] into the `Magnus::Error` shape used across the
+/// extension's Ruby-facing functions.
+fn tracing_error(ruby: &Ruby, error: &TracingError) -> Error {
+    Error::new(ruby.exception_runtime_error(), error.to_string())
+}
+
+/// Initializes this module's Ruby-visible surface: the `flush_telemetry` and
+/// `shutdown_telemetry` module functions, plus the `at_exit` hook that runs
+/// shutdown automatically.
+///
+/// # Errors
+///
+/// Returns a `Magnus::Error` if function or hook registration fails.
+pub fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.get_inner(&ROOT_MOD);
+    module.define_module_function("flush_telemetry", function!(flush_telemetry, 0))?;
+    module.define_module_function("shutdown_telemetry", function!(shutdown_telemetry, 0))?;
+
+    register_shutdown_at_exit(ruby)
+}

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.