prosody 0.1.1

data/lib/prosody/configuration.rb

@@ -0,0 +1,333 @@
+# frozen_string_literal: true
+
+module Prosody
+  # Configuration class for the Prosody messaging client.
+  #
+  # This class provides a flexible configuration system for the Prosody client,
+  # with strong typing, validation, and convenient default values. It handles
+  # various parameter types including strings, arrays, durations, integers,
+  # and special case configurations like operation mode and health probe settings.
+  #
+  # @example Basic usage
+  #   config = Prosody::Configuration.new(
+  #     bootstrap_servers: "kafka:9092",
+  #     group_id: "my-consumer-group"
+  #   )
+  #
+  # @example With block syntax
+  #   config = Prosody::Configuration.new do |c|
+  #     c.bootstrap_servers = ["kafka1:9092", "kafka2:9092"]
+  #     c.group_id = "my-consumer-group"
+  #     c.max_concurrency = 10
+  #   end
+  class Configuration
+    # Defines a configuration parameter with type conversion and optional default value.
+    #
+    # This DSL helper creates getter and setter methods for a configuration parameter,
+    # with the setter applying type conversion. The getter returns the default value
+    # when the parameter hasn't been set.
+    #
+    # @param name [Symbol, String] The parameter name
+    # @param converter [Proc] A lambda that converts and validates the input value
+    # @param default [Object, nil] The default value returned when parameter is unset
+    # @return [void]
+    def self.config_param(name, converter: ->(v) { v }, default: nil)
+      name_sym = name.to_sym
+      define_method(name) { @config.key?(name_sym) ? @config[name_sym] : default }
+      define_method(:"#{name}=") { |value| @config[name_sym] = value.nil? ? nil : converter.call(value) }
+    end
+
+    # Converts a duration value to float seconds.
+    #
+    # Handles ActiveSupport::Duration objects (if available) and numeric values,
+    # converting them to floating-point seconds.
+    #
+    # @param v [Numeric, ActiveSupport::Duration] The duration value to convert
+    # @return [Float] The duration in seconds as a float
+    # @raise [ArgumentError] If the input is not a valid duration type
+    def self.duration_converter(v)
+      if defined?(ActiveSupport::Duration) && v.is_a?(ActiveSupport::Duration)
+        v.to_f
+      elsif v.is_a?(Numeric)
+        v.to_f
+      else
+        raise ArgumentError, "Invalid type for duration: #{v.inspect}"
+      end
+    end
+
+    # Initializes a new Configuration instance.
+    #
+    # @param kwargs [Hash] Initial configuration parameters as keyword arguments
+    # @yield [self] Yields self for block-based configuration
+    # @return [Configuration] The new configuration instance
+    def initialize(kwargs = {})
+      @config = {}
+      kwargs.each { |k, v| public_send(:"#{k}=", v) }
+      yield self if block_given?
+    end
+
+    # List of Kafka bootstrap server addresses.
+    # Accepts a string (single server) or array of strings (multiple servers).
+    config_param :bootstrap_servers,
+      converter: lambda { |v|
+        if v.is_a?(String)
+          [v.to_s]
+        elsif v.respond_to?(:to_a)
+          v.to_a.map(&:to_s)
+        else
+          raise ArgumentError, "Invalid type for bootstrap_servers"
+        end
+      }
+
+    # List of Kafka topics to subscribe to.
+    # Accepts a string (single topic) or array of strings (multiple topics).
+    config_param :subscribed_topics,
+      converter: lambda { |v|
+        if v.is_a?(String)
+          [v.to_s]
+        elsif v.respond_to?(:to_a)
+          v.to_a.map(&:to_s)
+        else
+          raise ArgumentError, "Invalid type for subscribed_topics"
+        end
+      }
+
+    # List of event types the consumer is allowed to process.
+    # Accepts a string (single event type) or array of strings (multiple event types).
+    config_param :allowed_events,
+      converter: lambda { |v|
+        if v.is_a?(String)
+          [v.to_s]
+        elsif v.respond_to?(:to_a)
+          v.to_a.map(&:to_s)
+        else
+          raise ArgumentError, "Invalid type for allowed_events"
+        end
+      }
+
+    # Whether to use mock mode (for testing).
+    # When enabled, creates a mock Kafka implementation instead of connecting to real servers.
+    config_param :mock, converter: ->(v) { v.nil? ? nil : !!v }
+
+    # Maximum time to wait for a send operation to complete (in seconds).
+    config_param :send_timeout, converter: ->(v) { duration_converter(v) }
+
+    # Threshold in seconds after which a stalled consumer is detected.
+    config_param :stall_threshold, converter: ->(v) { duration_converter(v) }
+
+    # Shutdown budget; handlers run freely until cancellation fires near the end of the timeout.
+    config_param :shutdown_timeout, converter: ->(v) { duration_converter(v) }
+
+    # Interval between Kafka poll operations (in seconds).
+    config_param :poll_interval, converter: ->(v) { duration_converter(v) }
+
+    # Interval between offset commit operations (in seconds).
+    config_param :commit_interval, converter: ->(v) { duration_converter(v) }
+
+    # Base delay for retry operations (in seconds).
+    config_param :retry_base, converter: ->(v) { duration_converter(v) }
+
+    # Maximum delay between retries (in seconds).
+    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.
+    config_param :idempotence_cache_size, converter: ->(v) { Integer(v) }
+
+    # Version string for cache-busting deduplication hashes. Changing this
+    # invalidates all previously recorded dedup entries.
+    config_param :idempotence_version, converter: lambda(&:to_s)
+
+    # TTL for deduplication records in Cassandra.
+    config_param :idempotence_ttl, converter: ->(v) { duration_converter(v) }
+
+    # Maximum number of concurrent message processing tasks.
+    config_param :max_concurrency, converter: ->(v) { Integer(v) }
+
+    # Maximum number of messages to process before committing offsets.
+    config_param :max_uncommitted, converter: ->(v) { Integer(v) }
+
+    # Maximum number of retry attempts.
+    config_param :max_retries, converter: ->(v) { Integer(v) }
+
+    # Kafka consumer group ID.
+    config_param :group_id, converter: lambda(&:to_s)
+
+    # Identifier for the system producing messages.
+    config_param :source_system, converter: lambda(&:to_s)
+
+    # Topic to send failed messages to.
+    config_param :failure_topic, converter: lambda(&:to_s)
+
+    # List of Cassandra contact nodes (hostnames or IPs).
+    # Accepts a string (single node) or array of strings (multiple nodes).
+    config_param :cassandra_nodes,
+      converter: lambda { |v|
+        if v.is_a?(String)
+          [v.to_s]
+        elsif v.respond_to?(:to_a)
+          v.to_a.map(&:to_s)
+        else
+          raise ArgumentError, "Invalid type for cassandra_nodes"
+        end
+      }
+
+    # Keyspace to use for storing timer data in Cassandra.
+    config_param :cassandra_keyspace, converter: lambda(&:to_s)
+
+    # Preferred datacenter for Cassandra query routing.
+    config_param :cassandra_datacenter, converter: lambda(&:to_s)
+
+    # Preferred rack identifier for Cassandra topology-aware routing.
+    config_param :cassandra_rack, converter: lambda(&:to_s)
+
+    # Username for authenticating with Cassandra.
+    config_param :cassandra_user, converter: lambda(&:to_s)
+
+    # Password for authenticating with Cassandra.
+    config_param :cassandra_password, converter: lambda(&:to_s)
+
+    # Retention period for failed/unprocessed timer data in Cassandra.
+    # Accepts duration objects or numeric values (in seconds).
+    config_param :cassandra_retention, converter: ->(v) { duration_converter(v) }
+
+    # Timer slab partitioning duration in seconds.
+    # Controls how timers are grouped for storage and retrieval.
+    config_param :slab_size, converter: ->(v) { duration_converter(v) }
+
+    # Scheduler configuration
+    #
+    # Target proportion of execution time for failure/retry task processing (0.0 to 1.0).
+    # Controls bandwidth allocation between Normal and Failure task classes.
+    config_param :scheduler_failure_weight, converter: ->(v) { Float(v) }
+
+    # Wait duration at which urgency boost reaches maximum intensity (in seconds).
+    config_param :scheduler_max_wait, converter: ->(v) { duration_converter(v) }
+
+    # Maximum urgency boost (in seconds of virtual time) for waiting tasks.
+    config_param :scheduler_wait_weight, converter: ->(v) { Float(v) }
+
+    # Cache capacity for tracking per-key virtual time in the scheduler.
+    config_param :scheduler_cache_size, converter: ->(v) { Integer(v) }
+
+    # Monopolization configuration
+    #
+    # Whether monopolization detection is enabled.
+    config_param :monopolization_enabled, converter: ->(v) { v.nil? ? nil : !!v }
+
+    # Threshold for monopolization detection (0.0 to 1.0).
+    config_param :monopolization_threshold, converter: ->(v) { Float(v) }
+
+    # Rolling window duration (in seconds) for monopolization detection.
+    config_param :monopolization_window, converter: ->(v) { duration_converter(v) }
+
+    # Cache size for tracking key execution intervals.
+    config_param :monopolization_cache_size, converter: ->(v) { Integer(v) }
+
+    # Defer configuration
+    #
+    # Whether deferral is enabled for new messages.
+    config_param :defer_enabled, converter: ->(v) { v.nil? ? nil : !!v }
+
+    # Base exponential backoff delay for deferred retries (in seconds).
+    config_param :defer_base, converter: ->(v) { duration_converter(v) }
+
+    # 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).
+    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) }
+
+    # Timeout for Kafka seek operations (in seconds).
+    config_param :defer_seek_timeout, converter: ->(v) { duration_converter(v) }
+
+    # Messages to read sequentially before seeking.
+    config_param :defer_discard_threshold, converter: ->(v) { Integer(v) }
+
+    # Timeout configuration
+    #
+    # Fixed timeout duration for handler execution (in seconds).
+    # If unset, defaults to 80% of stall_threshold.
+    config_param :timeout, converter: ->(v) { duration_converter(v) }
+
+    # Telemetry emitter configuration
+    #
+    # Kafka topic to produce internal telemetry events to.
+    # Overrides the PROSODY_TELEMETRY_TOPIC environment variable.
+    config_param :telemetry_topic, converter: lambda(&:to_s)
+
+    # Whether the telemetry emitter is enabled.
+    # Overrides the PROSODY_TELEMETRY_ENABLED environment variable.
+    config_param :telemetry_enabled, converter: ->(v) { v.nil? ? nil : !!v }
+
+    # Span linking for message execution spans.
+    # Controls how the receive span connects to the OTel context from the Kafka producer.
+    # Accepted values: "child" (child-of relationship) or "follows_from".
+    # Overrides the PROSODY_MESSAGE_SPANS environment variable. Default: "child".
+    config_param :message_spans, converter: ->(v) { v.to_s }
+
+    # Span linking for timer execution spans.
+    # Controls how timer spans connect to the OTel context stored at schedule time.
+    # Accepted values: "child" (child-of relationship) or "follows_from".
+    # Overrides the PROSODY_TIMER_SPANS environment variable. Default: "follows_from".
+    config_param :timer_spans, converter: ->(v) { v.to_s }
+
+    # Operation mode of the client.
+    #
+    # Valid values:
+    # - "pipeline" or :pipeline - Prioritizes throughput and ordering
+    # - "low_latency" or :low_latency - Prioritizes latency over throughput
+    # - "best_effort" or :best_effort - Makes best effort tradeoffs
+    config_param :mode,
+      converter: lambda { |v|
+        return nil if v.nil?
+
+        s = v.to_s.downcase
+        case s
+        when "pipeline"
+          :pipeline
+        when "low_latency"
+          :low_latency
+        when "best_effort"
+          :best_effort
+        else
+          raise ArgumentError, "Invalid mode: #{v}"
+        end
+      }
+
+    # Configuration for the health probe port.
+    #
+    # Accepts:
+    # - nil (uses default configuration)
+    # - false or :disabled (explicitly disables the probe port)
+    # - Port number (0-65535) to use for the health probe
+    config_param :probe_port,
+      converter: lambda { |v|
+        if v.nil?
+          nil
+        elsif v == false
+          false
+        elsif (v.is_a?(Symbol) || v.is_a?(String)) && v.to_sym == :disabled
+          false
+        else
+          port = Integer(v)
+          raise ArgumentError, "Invalid port number" unless port.between?(0, 65_535)
+
+          port
+        end
+      }
+
+    # Returns a Ruby hash with only non-nil values, suitable for Rust deserialization.
+    #
+    # @return [Hash] Configuration hash with all nil values removed
+    def to_hash
+      @config.dup.compact
+    end
+  end
+end

data/lib/prosody/handler.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Prosody
+  # Base error class for all Prosody-specific exceptions.
+  #
+  # Specific error types may extend this class to provide more detailed
+  # error information and classification.
+  class Error < StandardError; end
+
+  # --------------------------------------------------------------------------
+  # 1) Base error classes with a `#permanent?` contract
+  # --------------------------------------------------------------------------
+
+  # Abstract base for all errors raised by EventHandler methods.
+  # Subclasses **must** implement `#permanent?` to indicate retry behavior.
+  #
+  # @abstract
+  class EventHandlerError < Error
+    # Indicates whether this error is permanent (no retry) or
+    # transient (retryable).
+    #
+    # @return [Boolean] true if permanent (no retry), false if transient (retryable)
+    # @raise [NotImplementedError] if not overridden by subclass
+    def permanent?
+      raise NotImplementedError, "#{self.class} must implement #permanent?"
+    end
+  end
+
+  # Error indicating that the failure is temporary and can be retried.
+  #
+  # @see EventHandlerError#permanent?
+  class TransientError < EventHandlerError
+    # @return [false] indicates this error is retryable
+    def permanent? = false
+  end
+
+  # Error indicating that the failure is permanent and should not be retried.
+  #
+  # @see EventHandlerError#permanent?
+  class PermanentError < EventHandlerError
+    # @return [true] indicates this error is not retryable
+    def permanent? = true
+  end
+
+  # --------------------------------------------------------------------------
+  # 2) Mixin that provides "decorators" for wrapping methods
+  # --------------------------------------------------------------------------
+
+  # Mixin providing class-level methods to wrap instance methods so that
+  # specified exceptions are re-wrapped as PermanentError or TransientError.
+  #
+  # @example
+  #   class MyHandler < Prosody::EventHandler
+  #     extend Prosody::ErrorClassification
+  #
+  #     # Treat TypeError as permanent (no retry)
+  #     permanent :on_message, TypeError
+  #
+  #     # Treat JSON::ParserError as transient (retryable)
+  #     transient :on_message, JSON::ParserError
+  #
+  #     def on_message(context, message)
+  #       # Process the message...
+  #     end
+  #   end
+  module ErrorClassification
+    # Wraps the given instance method so that specified exception types
+    # are caught and re-raised as Prosody::PermanentError.
+    #
+    # @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]
+    # @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)
+      wrap_errors(method_name, exception_classes, PermanentError)
+    end
+
+    # Wraps the given instance method so that specified exception types
+    # are caught and re-raised as Prosody::TransientError.
+    #
+    # @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]
+    # @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)
+      wrap_errors(method_name, exception_classes, TransientError)
+    end
+
+    private
+
+    # Core implementation: prepends a module that defines the same method name,
+    # rescuing the specified exceptions and re-raising them as the given error_class.
+    #
+    # @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]
+    def wrap_errors(method_name, exception_classes, error_class)
+      # Must specify at least one exception class
+      if exception_classes.empty?
+        raise ArgumentError, "At least one exception class must be provided"
+      end
+
+      # Ensure the method exists (in this class or its ancestors)
+      unless method_defined?(method_name)
+        raise NameError, "Method `#{method_name}` is not defined"
+      end
+
+      # Build a prepended wrapper module
+      wrapper = Module.new do
+        define_method(method_name) do |*args, &block|
+          super(*args, &block)
+        rescue *exception_classes => e
+          # The new exception's #cause will be set automatically
+          raise error_class.new(e.message)
+        end
+      end
+
+      prepend wrapper
+    end
+  end
+
+  # --------------------------------------------------------------------------
+  # 3) Base EventHandler that users will subclass
+  # --------------------------------------------------------------------------
+
+  # 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.
+  # They may also use `permanent` or `transient` decorators to control retry logic.
+  #
+  # @example
+  #   class MyHandler < Prosody::EventHandler
+  #     extend Prosody::ErrorClassification
+  #
+  #     permanent :on_message, ArgumentError
+  #     transient :on_message, RuntimeError
+  #     permanent :on_timer, ArgumentError
+  #     transient :on_timer, RuntimeError
+  #
+  #     def on_message(context, message)
+  #       # Process message...
+  #     end
+  #
+  #     def on_timer(context, trigger)
+  #       # Process timer event...
+  #     end
+  #   end
+  class EventHandler
+    extend ErrorClassification
+
+    # 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
+    # @raise [NotImplementedError] if not overridden by subclass
+    # @return [void]
+    def on_message(context, message)
+      raise NotImplementedError, "Subclasses must implement #on_message"
+    end
+
+    # Process a timer event when it fires.
+    # This method must be implemented by subclasses to handle
+    # scheduled timer events if they can fire.
+    #
+    # @param [Context] context the event context
+    # @param [Timer] timer the timer containing key, time, and span
+    # @return [void]
+    def on_timer(context, timer)
+      raise NotImplementedError, "Subclasses must implement #on_timer"
+    end
+  end
+end