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

data/lib/prosody/version.rb

@@ -6,5 +6,5 @@ module Prosody
   # This version number follows semantic versioning and is used by the
   # gem system to identify the library version. It should be updated
   # according to semver guidelines when making releases.
-  VERSION = "0.3.0"
+  VERSION = "0.5.0"
 end

data/lib/prosody.rb

@@ -40,3 +40,9 @@ begin
 rescue LoadError
   require_relative "prosody/prosody"
 end
+
+# Loaded last: the keyed-state surface reopens the native Prosody::Context and
+# subclasses the error hierarchy, so every native class and base error must
+# already exist.
+require_relative "prosody/state"
+require_relative "prosody/request"

data/release-please-config.json

@@ -1,5 +1,9 @@
 {
   "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "bootstrap-sha": "a5c4faa0b7a5bf14d74c7c77de72883b20fc41fa",
+  "include-component-in-tag": true,
+  "include-v-in-tag": true,
+  "tag-separator": "/",
   "packages": {
     ".": {
       "release-type": "ruby",

data/sig/configuration.rbs

@@ -24,7 +24,8 @@ module Prosody
     # Create a new configuration with initial values
     #
     # @param kwargs Initial configuration values
-    def initialize: (?Hash[Symbol, untyped] kwargs) ?{ (Configuration) -> void } -> void
+    def initialize: (?Hash[Symbol, untyped] options) ?{ (Configuration) -> void } -> void
+                  | (**untyped options) ?{ (Configuration) -> void } -> void
 
     # Kafka bootstrap server addresses
     def bootstrap_servers: () -> Array[String]?
@@ -102,6 +103,26 @@ module Prosody
     def source_system: () -> String?
     def source_system=: (_ToS) -> String
 
+    # Address for the peer listener. Prosody reads PROSODY_PEER_BIND_ADDRESS when absent.
+    def peer_bind_address: () -> String?
+    def peer_bind_address=: (_ToS) -> String
+
+    # Connect URI for remote peers. Prosody reads PROSODY_PEER_ADVERTISED_CONNECT when absent.
+    def peer_advertised_connect: () -> String?
+    def peer_advertised_connect=: (_ToS) -> String
+
+    # Network name for direct routes. Prosody reads PROSODY_PEER_NETWORK_NAME when absent.
+    def peer_network_name: () -> String?
+    def peer_network_name=: (_ToS) -> String
+
+    # Peer cache capacity. Prosody reads PROSODY_PEER_CACHE_CAPACITY when absent.
+    def peer_cache_capacity: () -> Integer?
+    def peer_cache_capacity=: (Integer | _ToInt) -> Integer
+
+    # Peer registration lease. Prosody reads PROSODY_PEER_REGISTRATION_TTL when absent.
+    def peer_registration_ttl: () -> Float?
+    def peer_registration_ttl=: (Numeric) -> Float
+
     # Topic to send failed messages to
     def failure_topic: () -> String?
     def failure_topic=: (_ToS) -> String
@@ -198,21 +219,21 @@ module Prosody
     def defer_failure_window: () -> Float?
     def defer_failure_window=: (Numeric) -> Float
 
-    # Defer cache size
-    def defer_cache_size: () -> Integer?
-    def defer_cache_size=: (Integer | _ToInt) -> Integer
-
     # Maximum deferred store cache entries. Env: PROSODY_DEFER_STORE_CACHE_SIZE
     def defer_store_cache_size: () -> Integer?
     def defer_store_cache_size=: (Integer | _ToInt) -> Integer
 
-    # Defer seek timeout (seconds)
-    def defer_seek_timeout: () -> Float?
-    def defer_seek_timeout=: (Numeric) -> Float
+    # Maximum messages retained by the shared Kafka loader. Env: PROSODY_LOADER_CACHE_SIZE. Default: 1024
+    def loader_cache_size: () -> Integer?
+    def loader_cache_size=: (Integer | _ToInt) -> Integer
 
-    # Defer discard threshold (messages)
-    def defer_discard_threshold: () -> Integer?
-    def defer_discard_threshold=: (Integer | _ToInt) -> Integer
+    # Kafka loader seek timeout (seconds). Env: PROSODY_LOADER_SEEK_TIMEOUT. Default: 30
+    def loader_seek_timeout: () -> Float?
+    def loader_seek_timeout=: (Numeric) -> Float
+
+    # Sequential-read distance before the loader seeks. Env: PROSODY_LOADER_DISCARD_THRESHOLD. Default: 100
+    def loader_discard_threshold: () -> Integer?
+    def loader_discard_threshold=: (Integer | _ToInt) -> Integer
 
     # Handler execution timeout (seconds)
     def timeout: () -> Float?
@@ -234,6 +255,44 @@ module Prosody
     def timer_spans: () -> String?
     def timer_spans=: (_ToS) -> String
 
+    # Keyed-state collections to register before subscribe. Accepts an array of
+    # definition objects (from Prosody.value/map/deque and their message_*
+    # siblings) or already-serialized registration hashes.
+    def state_collections: () -> Array[untyped]?
+    def state_collections=: (untyped) -> Array[untyped]
+
+    # Subsystem under which published JSON collections are advertised.
+    # Uses PROSODY_SUBSYSTEM when omitted. Published collections require it.
+    def subsystem: () -> String?
+    def subsystem=: (_ToS) -> String
+
+    # Root directory for the local keyed-state cache. Falls back to
+    # PROSODY_STATE_CACHE_DIR. Must not be an empty string.
+    def state_cache_dir: () -> String?
+    def state_cache_dir=: (_ToS) -> String
+
+    # Capacity of the owning keyed-state cache. Accepts a human-readable size.
+    # Uses PROSODY_STATE_OWNED_CACHE_SIZE when omitted. Otherwise, the engine
+    # selects its default.
+    def state_owned_cache_size: () -> String?
+    def state_owned_cache_size=: (String | _ToS) -> String
+
+    # Capacity of the published-state read cache. 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.
+    def state_read_cache_size: () -> String?
+    def state_read_cache_size=: (String | _ToS) -> String
+
+    # Default published-read cache TTL in seconds, or false to bypass it. Uses
+    # PROSODY_STATE_READ_CACHE_TTL when omitted, then 5 seconds.
+    def state_read_cache: () -> (Float | false)?
+    def state_read_cache=: (Numeric | false) -> (Float | false)
+
+    # Delay in whole seconds between staging a provisional cell and the recovery
+    # sweep. Falls back to PROSODY_STATE_RECOVERY_DELAY (read by core).
+    def state_recovery_delay: () -> Float?
+    def state_recovery_delay=: (Numeric) -> Float
+
     # Convert configuration to a hash with non-nil values only
     def to_hash: () -> Hash[Symbol, untyped]
   end

data/sig/handler.rbs

@@ -1,4 +1,8 @@
 module Prosody
+  # Base error class for all Prosody errors (defined in lib/prosody/handler.rb).
+  class Error < ::StandardError
+  end
+
   # Abstract base for all errors raised by EventHandler methods.
   # Subclasses must implement `#permanent?` to indicate retry behavior.
   class EventHandlerError < Prosody::Error
@@ -22,7 +26,7 @@ module Prosody
 
   # Mixin providing class-level methods to wrap instance methods so that
   # specified exceptions are re-wrapped as PermanentError or TransientError.
-  module ErrorClassification
+  module ErrorClassification : Module
     # Wraps the given instance method so that specified exception types
     # are caught and re-raised as Prosody::PermanentError.
     #
@@ -52,11 +56,16 @@ module Prosody
     def wrap_errors: (Symbol method_name, Array[Class] exception_classes, singleton(EventHandlerError) error_class) -> void
   end
 
-  # Abstract base class for handling incoming messages from Prosody.
-  # Subclasses must implement `#on_message` to process received messages.
-  class EventHandler
+  # Abstract base class for handling events from Prosody.
+  # Subclasses must implement all three handler methods.
+  class EventHandler[Payload = json_value, Response = json_value]
     extend ErrorClassification
 
+    def self.validate_handler!: [Payload, Response] (EventHandler[Payload, Response] handler) -> void
+
+    private def self.validate_method!: [Payload, Response] (EventHandler[Payload, Response] handler, Array[Module] owners, Symbol name) -> void
+    private def self.accepts_two_parameters?: (Method method) -> bool
+
     # Process a single message received from Prosody.
     # This method must be implemented by subclasses to define
     # custom message handling logic.
@@ -64,7 +73,10 @@ module Prosody
     # @param context the message context containing metadata and control capabilities
     # @param message the message content with payload and metadata
     # @raise [NotImplementedError] if not overridden by subclass
-    def on_message: (Context context, Message message) -> void
+    def on_message: (Context context, Message[Payload] message) -> Response
+
+    # Process an excise record.
+    def on_excise: (Context context, ExciseMessage message) -> Response
 
     # Process a timer that has fired.
     # This method is called when a previously scheduled timer fires.

data/sig/processor.rbs

@@ -40,13 +40,17 @@ module Prosody
       # OpenTelemetry context carrier for trace propagation
       attr_reader carrier: Hash[String, String]
 
+      # Structured event fields for error reporting
+      attr_reader event_context: Hash[Symbol, untyped]
+
       # Creates a new execute command with all required parameters
       def initialize: (
-          task_id: String,
-          carrier: Hash[String, String],
-          block: ^() -> void,
-          callback: ^(bool, untyped) -> bool,
-          token: CancellationToken
+          String task_id,
+          Hash[String, String] carrier,
+          Hash[Symbol, untyped] event_context,
+          ^() -> untyped block,
+          ^(bool, untyped) -> untyped callback,
+          CancellationToken token
         ) -> void
     end
 
@@ -82,19 +86,31 @@ module Prosody
     # @yield the block to execute asynchronously
     # @return token that can be used to cancel the task
     def submit: (
-        task_id: String,
-        carrier: Hash[String, String],
-        callback: ^(bool, untyped) -> bool
+        String task_id,
+        Hash[String, String] carrier,
+        Hash[String | Symbol, untyped] event_context,
+        ^(bool, untyped) -> untyped callback
       ) { () -> untyped } -> CancellationToken
 
     private
 
+    def running?: () -> bool?
+
     # Main processing loop for the async thread
     def process_commands: () -> void
 
-    # Handles execution of a task with proper context propagation and error handling
-    # @param command the command containing task details
-    # @param barrier barrier for tracking active tasks
-    def handle_execute: (Commands::Execute, Async::Barrier) -> void
+    # Handles execution of a task with proper context propagation and error handling.
+    # The barrier belongs to the external async gem and is intentionally kept
+    # untyped rather than publishing a partial signature for that dependency.
+    def handle_execute: (Commands::Execute, untyped) -> void
+
+    def run_with_cancellation: (
+      String,
+      CancellationToken,
+      ^() -> untyped,
+      ^(bool, untyped) -> untyped,
+      untyped,
+      Hash[Symbol, untyped]
+    ) -> void
   end
 end

data/sig/prosody.rbs

@@ -1,4 +1,8 @@
 module Prosody
+  # Any value representable by JSON. This is the default payload type for
+  # messages and handlers; applications can substitute a narrower record type.
+  type json_value = nil | bool | Integer | Float | String | Array[json_value] | Hash[String, json_value]
+
   @logger: Logger?
 
   # Returns the module-level logger, creating a default if not yet set.
@@ -8,6 +12,24 @@ module Prosody
   # Sets the module-level logger. Pass nil to reset to the default.
   def self.logger=: (Logger?) -> Logger?
 
+  # Exports buffered telemetry without shutting down the process-global pipeline.
+  def self.flush_telemetry: () -> void
+
+  # Exports buffered telemetry and shuts down the process-global pipeline.
+  def self.shutdown_telemetry: () -> void
+
+  # Manages Kafka topics.
+  class AdminClient
+    # Creates an admin client for the specified Kafka bootstrap servers.
+    def self.new: (Array[String]) -> AdminClient
+
+    # Creates a topic.
+    def create_topic: (String, Integer, Integer) -> void
+
+    # Deletes a topic.
+    def delete_topic: (String) -> void
+  end
+
   # Wrapper for dynamically-typed results from async operations.
   # This is an internal class used for bridging Rust and Ruby.
   class DynamicResult
@@ -65,7 +87,7 @@ module Prosody
 
   # Represents a Kafka message with its metadata and payload.
   # Provides access to message properties like topic, partition, offset, and content.
-  class Message
+  class Message[Payload = json_value]
     # Returns the Kafka topic this message was published to.
     # @return [String] The topic name
     def topic: () -> String
@@ -87,8 +109,17 @@ module Prosody
     def timestamp: () -> Time
 
     # Returns the deserialized message payload.
-    # @return [untyped] The message content
-    def payload: () -> untyped
+    # @return [Payload] The message content
+    def payload: () -> Payload
+  end
+
+  # Represents an excise record with no payload.
+  class ExciseMessage
+    def topic: () -> String
+    def partition: () -> Integer
+    def offset: () -> Integer
+    def key: () -> String
+    def timestamp: () -> Time
   end
 
   # Represents a timer that was scheduled to fire at a specific time.
@@ -118,10 +149,11 @@ module Prosody
     # @raise [ArgumentError] If the configuration is invalid
     # @raise [RuntimeError] If client initialization fails
     def self.new: (Hash[Symbol, untyped] | Configuration config) -> Client
+                | (**untyped options) -> Client
 
     # Returns the current state of the consumer.
     #
-    # @return [Symbol] The consumer state: :unconfigured, :configured, or :running
+    # @return [Symbol] The consumer state: :shut_down, :unconfigured, :configured, or :running
     def consumer_state: () -> Symbol
 
     # Returns the number of Kafka partitions currently assigned to this consumer.
@@ -141,10 +173,13 @@ module Prosody
     #
     # @param topic [String] The destination topic name
     # @param key [String] The message key for partitioning
-    # @param payload [untyped] The message payload (will be serialized)
+    # @param payload [json_value] The message payload (will be serialized)
     # @return [void]
     # @raise [RuntimeError] If the message cannot be sent
-    def send_message: (String topic, String key, untyped payload) -> void
+    def send_message: (String topic, String key, json_value payload) -> void
+
+    # Sends an excise record for a key.
+    def excise: (String topic, String key) -> void
 
     # Subscribes to Kafka topics using the provided handler.
     # The handler must implement an `on_message(context, message)` method.
@@ -152,7 +187,7 @@ module Prosody
     # @param handler [EventHandler] A handler object that processes messages
     # @return [void]
     # @raise [RuntimeError] If subscription fails
-    def subscribe: (EventHandler) -> void
+    def subscribe: [Payload, Response] (EventHandler[Payload, Response]) -> void
 
     # Unsubscribes from all topics, stopping message processing.
     #
@@ -160,6 +195,13 @@ module Prosody
     # @raise [RuntimeError] If unsubscription fails
     def unsubscribe: () -> void
 
+    # Shuts down all client services.
+    # Concurrent and repeated calls wait for the same shutdown operation.
+    #
+    # @return [void]
+    # @raise [RuntimeError] If shutdown fails
+    def shutdown: () -> void
+
     # Returns the configured source system identifier.
     #
     # The source system is used to identify the originating service or
@@ -167,5 +209,9 @@ module Prosody
     #
     # @return [String] The source system identifier
     def source_system: () -> String
+
+    def state: [T] (_ToS subsystem, _ValueDefinition[T] definition) -> PublishedValue[T]
+             | [V] (_ToS subsystem, _MapDefinition[V] definition) -> PublishedMap[V]
+             | [T] (_ToS subsystem, _DequeDefinition[T] definition) -> PublishedDeque[T]
   end
 end

data/sig/request.rbs

@@ -0,0 +1,66 @@
+module Prosody
+  class Success[Value] < Data
+    attr_reader value: Value
+  end
+
+  class Failure < Data
+    attr_reader error: response_error
+  end
+
+  class HandlerError < Data
+    attr_reader message: String
+  end
+
+  class Timeout < Data
+    def message: () -> String
+  end
+
+  class FormatMismatch < Data
+    def message: () -> String
+  end
+
+  class MalformedResponse < Data
+    def message: () -> String
+  end
+
+  type response_error = HandlerError | Timeout | FormatMismatch | MalformedResponse
+  type outcome[Value] = Success[Value] | Failure
+  type outcomes[Value] = Hash[String, outcome[Value]]
+  type native_request = {
+    topic: String,
+    key: String,
+    payload: json_value,
+    subsystems: Array[String],
+    timeout: Integer | Float
+  }
+  type native_excise_request = {
+    topic: String,
+    key: String,
+    subsystems: Array[String],
+    timeout: Integer | Float
+  }
+
+  class Client
+    # The timeout value uses seconds.
+    # The method raises if the request cannot start or the Kafka send fails.
+    def request: (
+      topic: String,
+      key: String,
+      payload: json_value,
+      subsystems: Array[String],
+      timeout: Integer | Float
+    ) -> outcomes[json_value]
+
+    def request_excise: (
+      topic: String,
+      key: String,
+      subsystems: Array[String],
+      timeout: Integer | Float
+    ) -> outcomes[json_value]
+
+    private
+
+    def native_request: (native_request request) -> outcomes[json_value]
+    def native_request_excise: (native_excise_request request) -> outcomes[json_value]
+  end
+end

data/sig/sentry.rbs

@@ -0,0 +1,6 @@
+module Prosody
+  module SentryIntegration
+    def self.enabled?: () -> bool
+    def self.capture_exception: (Exception exception, ?Hash[Symbol, untyped] context) -> untyped
+  end
+end