prosody 0.1.1

data/sig/handler.rbs

@@ -0,0 +1,79 @@
+module Prosody
+  # Abstract base for all errors raised by EventHandler methods.
+  # Subclasses must implement `#permanent?` to indicate retry behavior.
+  class EventHandlerError < Prosody::Error
+    # Indicates whether this error is permanent (no retry) or transient (retryable).
+    #
+    # @raise [NotImplementedError] if not overridden by subclass
+    def permanent?: () -> bool
+  end
+
+  # Error indicating that the failure is temporary and can be retried.
+  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.
+  class PermanentError < EventHandlerError
+    # @return [true] indicates this error is not retryable
+    def permanent?: () -> true
+  end
+
+  # Mixin providing class-level methods to wrap instance methods so that
+  # specified exceptions are re-wrapped as PermanentError or TransientError.
+  module ErrorClassification
+    # Wraps the given instance method so that specified exception types
+    # are caught and re-raised as Prosody::PermanentError.
+    #
+    # @param method_name the name of the method to wrap
+    # @param exception_classes one or more Exception subclasses to catch
+    # @raise [ArgumentError] if no exception classes given or invalid
+    # @raise [NameError] if method_name is not defined
+    def permanent: (Symbol method_name, *Class exception_classes) -> void
+
+    # Wraps the given instance method so that specified exception types
+    # are caught and re-raised as Prosody::TransientError.
+    #
+    # @param method_name the name of the method to wrap
+    # @param exception_classes one or more Exception subclasses to catch
+    # @raise [ArgumentError] if no exception classes given or invalid
+    # @raise [NameError] if method_name is not defined
+    def transient: (Symbol method_name, *Class exception_classes) -> void
+
+    private
+
+    # Core implementation: redefines `method_name` to catch listed exceptions
+    # and re-raise them as the specified error class.
+    #
+    # @param method_name the method to wrap
+    # @param exception_classes exceptions to catch
+    # @param error_class the error class to wrap caught exceptions in
+    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
+    extend ErrorClassification
+
+    # Process a single message received from Prosody.
+    # This method must be implemented by subclasses to define
+    # custom message handling logic.
+    #
+    # @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
+
+    # Process a timer that has fired.
+    # This method is called when a previously scheduled timer fires.
+    # This method must be implemented by subclasses to define
+    # custom timer handling logic.
+    #
+    # @param context the timer context containing metadata and control capabilities
+    # @param timer the timer object with key and time information
+    # @raise [NotImplementedError] if not overridden by subclass
+    def on_timer: (Context context, Timer timer) -> void
+  end
+end

data/sig/processor.rbs

@@ -0,0 +1,100 @@
+# Type definitions for Prosody::Processor
+
+module Prosody
+  # Provides a mechanism for canceling asynchronous tasks
+  class CancellationToken
+    @queue: Queue
+
+    # Creates a new token with an internal queue for signaling
+    def initialize: () -> void
+
+    # Signals that the associated task should be canceled
+    # Wakes up any threads waiting on #wait
+    def cancel: () -> void
+
+    # Blocks until cancellation is requested
+    # @return always returns true after cancellation is received
+    def wait: () -> bool
+  end
+
+  module Commands
+    # Base class for all processor commands
+    class Command
+
+    end
+
+    # Command to execute a task with the given parameters
+    class Execute < Command
+      # Task identifier for logging and debugging
+      attr_reader task_id: String
+
+      # The block of code to execute
+      attr_reader block: ^() -> void
+
+      # Callback to invoke when execution completes or fails
+      attr_reader callback: ^(bool, untyped) -> bool
+
+      # Cancellation token for this task
+      attr_reader token: CancellationToken
+
+      # OpenTelemetry context carrier for trace propagation
+      attr_reader carrier: Hash[String, String]
+
+      # 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
+        ) -> void
+    end
+
+    # Command that signals the processor to shut down
+    class Shutdown < Command
+
+    end
+  end
+
+  class AsyncTaskProcessor
+    @logger: Logger
+    @command_queue: Queue
+    @processing_thread: Thread?
+    @tracer: untyped?
+
+    # Creates a new processor with the given logger
+    # @param logger logger for diagnostic messages (defaults to Prosody.logger)
+    def initialize: (?Logger) -> void
+
+    # Starts the processor by launching a dedicated thread
+    # Does nothing if the processor is already running
+    # @return the Thread if started, or nil if already running
+    def start: () -> Thread?
+
+    # Gracefully stops the processor
+    # Does nothing if the processor is already stopped
+    def stop: () -> void
+
+    # Submits a task for asynchronous execution
+    # @param task_id unique identifier for the task
+    # @param carrier OpenTelemetry context carrier for tracing
+    # @param callback called with (success, result) when task completes
+    # @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
+      ) { () -> untyped } -> CancellationToken
+
+    private
+
+    # 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
+  end
+end

data/sig/prosody.rbs

@@ -0,0 +1,171 @@
+module Prosody
+  @logger: Logger?
+
+  # Returns the module-level logger, creating a default if not yet set.
+  # The default writes to $stdout at INFO level.
+  def self.logger: () -> Logger
+
+  # Sets the module-level logger. Pass nil to reset to the default.
+  def self.logger=: (Logger?) -> Logger?
+
+  # Wrapper for dynamically-typed results from async operations.
+  # This is an internal class used for bridging Rust and Ruby.
+  class DynamicResult
+    # This class should not be instantiated directly.
+
+    private
+
+    def initialize: (untyped) -> void
+  end
+
+  # Represents the context of a Kafka message.
+  # Provides metadata and control capabilities for message processing.
+  class Context
+    # This class is instantiated internally by the client.
+
+    # Checks if cancellation has been requested.
+    # Cancellation includes both message-level cancellation (e.g., timeout)
+    # and partition shutdown.
+    # @return [bool] true if cancellation has been requested, false otherwise
+    def should_cancel?: () -> bool
+
+    # Blocks until cancellation is signaled.
+    # Cancellation includes both message-level cancellation (e.g., timeout)
+    # and partition shutdown.
+    # @return [void]
+    def on_cancel: () -> void
+
+    # Schedules a timer to fire at the specified time.
+    # @param time [Time] When the timer should fire
+    # @return [void]
+    def schedule: (Time time) -> void
+
+    # Clears all scheduled timers and schedules a new one at the specified time.
+    # @param time [Time] When the new timer should fire
+    # @return [void]
+    def clear_and_schedule: (Time time) -> void
+
+    # Unschedules a timer that was scheduled for the specified time.
+    # @param time [Time] The time for which to unschedule the timer
+    # @return [void]
+    def unschedule: (Time time) -> void
+
+    # Clears all scheduled timers.
+    # @return [void]
+    def clear_scheduled: () -> void
+
+    # Returns all currently scheduled timer times.
+    # @return [Array<Time>] Array of scheduled timer times
+    def scheduled: () -> Array[Time]
+
+    private
+
+    def initialize: (untyped) -> void
+  end
+
+  # Represents a Kafka message with its metadata and payload.
+  # Provides access to message properties like topic, partition, offset, and content.
+  class Message
+    # Returns the Kafka topic this message was published to.
+    # @return [String] The topic name
+    def topic: () -> String
+
+    # Returns the Kafka partition number for this message.
+    # @return [Integer] The partition number
+    def partition: () -> Integer
+
+    # Returns the Kafka offset of this message within its partition.
+    # @return [Integer] The message offset
+    def offset: () -> Integer
+
+    # Returns the message key used for partitioning.
+    # @return [String] The message key
+    def key: () -> String
+
+    # Returns the timestamp when the message was created.
+    # @return [Time] The message timestamp
+    def timestamp: () -> Time
+
+    # Returns the deserialized message payload.
+    # @return [untyped] The message content
+    def payload: () -> untyped
+  end
+
+  # Represents a timer that was scheduled to fire at a specific time.
+  # Timer instances are passed to EventHandler's on_timer method when timers fire.
+  class Timer
+    # Returns the entity key identifying what this timer belongs to.
+    # @return [String] The entity key
+    def key: () -> String
+
+    # Returns the time when this timer was scheduled to fire.
+    # @return [Time] The scheduled execution time
+    def time: () -> Time
+
+
+    private
+
+    def initialize: (untyped) -> void
+  end
+
+  # Main client for interacting with the Prosody messaging system.
+  # Provides methods for sending messages and subscribing to Kafka topics.
+  class Client
+    # Creates a new Prosody client with the given configuration.
+    #
+    # @param config [Hash, Configuration] Client configuration
+    # @return [Client] A new client instance
+    # @raise [ArgumentError] If the configuration is invalid
+    # @raise [RuntimeError] If client initialization fails
+    def self.new: (Hash[Symbol, untyped] | Configuration config) -> Client
+
+    # Returns the current state of the consumer.
+    #
+    # @return [Symbol] The consumer state: :unconfigured, :configured, or :running
+    def consumer_state: () -> Symbol
+
+    # Returns the number of Kafka partitions currently assigned to this consumer.
+    #
+    # @return [Integer] The number of assigned partitions
+    def assigned_partitions: () -> Integer
+
+    # Checks if the consumer is stalled.
+    #
+    # A stalled consumer is one that has stopped processing messages due to
+    # errors or reaching processing limits.
+    #
+    # @return [Boolean] true if the consumer is stalled, false otherwise
+    def is_stalled?: () -> bool
+
+    # Sends a message to the specified Kafka topic.
+    #
+    # @param topic [String] The destination topic name
+    # @param key [String] The message key for partitioning
+    # @param payload [untyped] 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
+
+    # Subscribes to Kafka topics using the provided handler.
+    # The handler must implement an `on_message(context, message)` method.
+    #
+    # @param handler [EventHandler] A handler object that processes messages
+    # @return [void]
+    # @raise [RuntimeError] If subscription fails
+    def subscribe: (EventHandler) -> void
+
+    # Unsubscribes from all topics, stopping message processing.
+    #
+    # @return [void]
+    # @raise [RuntimeError] If unsubscription fails
+    def unsubscribe: () -> void
+
+    # Returns the configured source system identifier.
+    #
+    # The source system is used to identify the originating service or
+    # component in produced messages, enabling loop detection.
+    #
+    # @return [String] The source system identifier
+    def source_system: () -> String
+  end
+end

data/sig/version.rbs

@@ -0,0 +1,9 @@
+# Type definitions for Prosody version module
+
+module Prosody
+  # Current version of the Prosody library.
+  #
+  # This version number follows semantic versioning and is used by the
+  # gem system to identify the library version.
+  VERSION: String
+end

metadata

@@ -0,0 +1,193 @@
+--- !ruby/object:Gem::Specification
+name: prosody
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Joshua Griffith
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: async
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.39'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.39'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-api
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.126
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.126
+- !ruby/object:Gem::Dependency
+  name: async-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-exporter-otlp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.33'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.33'
+- !ruby/object:Gem::Dependency
+  name: sentry-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.5'
+description: |
+  Prosody offers Ruby bindings to the Prosody Kafka client, providing features
+  for message production and consumption, including configurable retry
+  mechanisms, failure handling strategies, and integrated OpenTelemetry
+  support for distributed tracing.
+executables: []
+extensions:
+- ext/prosody/extconf.rb
+extra_rdoc_files: []
+files:
+- ".cargo/config.toml"
+- ".release-please-manifest.json"
+- ".rspec"
+- ".ruby-version"
+- ".standard.yml"
+- ".taplo.toml"
+- ARCHITECTURE.md
+- CHANGELOG.md
+- Cargo.lock
+- Cargo.toml
+- LICENSE
+- Makefile
+- README.md
+- Rakefile
+- ext/prosody/Cargo.toml
+- ext/prosody/extconf.rb
+- ext/prosody/src/admin.rs
+- ext/prosody/src/bridge/callback.rs
+- ext/prosody/src/bridge/mod.rs
+- ext/prosody/src/client/config.rs
+- ext/prosody/src/client/mod.rs
+- ext/prosody/src/gvl.rs
+- ext/prosody/src/handler/context.rs
+- ext/prosody/src/handler/message.rs
+- ext/prosody/src/handler/mod.rs
+- ext/prosody/src/handler/trigger.rs
+- ext/prosody/src/lib.rs
+- ext/prosody/src/logging.rs
+- ext/prosody/src/scheduler/cancellation.rs
+- ext/prosody/src/scheduler/handle.rs
+- ext/prosody/src/scheduler/mod.rs
+- ext/prosody/src/scheduler/processor.rs
+- ext/prosody/src/scheduler/result.rs
+- ext/prosody/src/tracing_util.rs
+- ext/prosody/src/util.rs
+- lib/prosody.rb
+- lib/prosody/configuration.rb
+- lib/prosody/handler.rb
+- lib/prosody/native_stubs.rb
+- lib/prosody/processor.rb
+- lib/prosody/sentry.rb
+- lib/prosody/version.rb
+- release-please-config.json
+- sig/configuration.rbs
+- sig/handler.rbs
+- sig/processor.rbs
+- sig/prosody.rbs
+- sig/version.rbs
+homepage: https://github.com/prosody-events/prosody-rb
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/prosody-events/prosody-rb
+  source_code_uri: https://github.com/prosody-events/prosody-rb
+  changelog_uri: https://github.com/prosody-events/prosody-rb/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.11
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby bindings for the Prosody Kafka client library
+test_files: []