prosody 0.3.0-aarch64-linux → 0.4.0-aarch64-linux

data/lib/prosody.rb

@@ -40,3 +40,8 @@ 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"

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]?
@@ -234,6 +235,28 @@ 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]
+
+    # 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 in-memory keyed-state cache, in bytes. Must be positive.
+    # Falls back to
+    # PROSODY_STATE_CACHE_SIZE_BYTES, then the engine default.
+    def state_cache_size_bytes: () -> Integer?
+    def state_cache_size_bytes=: (Integer | _ToInt) -> Integer
+
+    # 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.
     #
@@ -54,7 +58,7 @@ module Prosody
 
   # Abstract base class for handling incoming messages from Prosody.
   # Subclasses must implement `#on_message` to process received messages.
-  class EventHandler
+  class EventHandler[Payload = json_value]
     extend ErrorClassification
 
     # Process a single message received from Prosody.
@@ -64,7 +68,7 @@ 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) -> void
 
     # 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.
@@ -65,7 +69,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 +91,8 @@ 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 a timer that was scheduled to fire at a specific time.
@@ -118,6 +122,7 @@ 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.
     #
@@ -141,10 +146,10 @@ 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
 
     # Subscribes to Kafka topics using the provided handler.
     # The handler must implement an `on_message(context, message)` method.
@@ -152,7 +157,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] (EventHandler[Payload]) -> void
 
     # Unsubscribes from all topics, stopping message processing.
     #

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

data/sig/state.rbs

@@ -0,0 +1,272 @@
+module Prosody
+  # --- error taxonomy -----------------------------------------------------
+  # Raised for keyed-state failures a retry cannot resolve (unregistered
+  # collection, identity mismatch, duplicate registration, bad TTL). Never
+  # Terminal: core folds Terminal into Transient.
+  class PermanentStateError < PermanentError
+  end
+
+  # Raised for keyed-state failures that may succeed on retry, plus every
+  # caller mistake (null write, wrong item shape, invalid index, invalid
+  # direction). Never Terminal.
+  class TransientStateError < TransientError
+  end
+
+  # Raised when a JSON null is written to a collection. Null is not storable
+  # (indistinguishable from absence); use clear/delete instead.
+  class NullValueError < TransientStateError
+  end
+
+  # Concrete immutable definition object returned by the constructor helpers.
+  class StateDefinition < Data
+    attr_reader name: String
+    attr_reader kind: String
+    attr_reader payload: String
+    attr_reader ttl_seconds: Integer?
+    attr_reader read_uncommitted: bool?
+    attr_reader keyset_limit: Integer?
+    attr_reader capacity: Integer?
+
+    def to_state_config: () -> Hash[Symbol, untyped]
+  end
+
+  # --- definition interfaces (phantom-typed over the payload) --------------
+  # The runtime returns a single frozen StateDefinition (Data) that structurally
+  # satisfies every interface below; the type parameter is annotation-only.
+  interface _ValueDefinition[T = json_value]
+    def name: () -> String
+    def kind: () -> "value"
+    def payload: () -> "json"
+    def to_state_config: () -> Hash[Symbol, untyped]
+  end
+
+  interface _MapDefinition[V = json_value]
+    def name: () -> String
+    def kind: () -> "map"
+    def payload: () -> "json"
+    def to_state_config: () -> Hash[Symbol, untyped]
+  end
+
+  interface _DequeDefinition[T = json_value]
+    def name: () -> String
+    def kind: () -> "deque"
+    def payload: () -> "json"
+    def to_state_config: () -> Hash[Symbol, untyped]
+  end
+
+  interface _MessageValueDefinition[P = json_value]
+    def name: () -> String
+    def kind: () -> "value"
+    def payload: () -> "message"
+    def to_state_config: () -> Hash[Symbol, untyped]
+  end
+
+  interface _MessageMapDefinition[P = json_value]
+    def name: () -> String
+    def kind: () -> "map"
+    def payload: () -> "message"
+    def to_state_config: () -> Hash[Symbol, untyped]
+  end
+
+  interface _MessageDequeDefinition[P = json_value]
+    def name: () -> String
+    def kind: () -> "deque"
+    def payload: () -> "message"
+    def to_state_config: () -> Hash[Symbol, untyped]
+  end
+
+  # --- definition constructors --------------------------------------------
+  # The `message_*` siblings return the same structural definition interfaces as
+  # their JSON counterparts (the runtime object is one StateDefinition); the
+  # `[P]` type parameter is annotation-only, naming the message payload type.
+  def self.value: [T] (_ToS name, ?ttl: Integer?, ?read_uncommitted: bool?) -> _ValueDefinition[T]
+  def self.map: [V] (_ToS name, ?ttl: Integer?, ?keyset_limit: Integer?, ?read_uncommitted: bool?) -> _MapDefinition[V]
+  def self.deque: [T] (_ToS name, ?ttl: Integer?, ?capacity: Integer?, ?read_uncommitted: bool?) -> _DequeDefinition[T]
+  def self.message_value: [P] (_ToS name, ?ttl: Integer?, ?read_uncommitted: bool?) -> _MessageValueDefinition[P]
+  def self.message_map: [P] (_ToS name, ?ttl: Integer?, ?keyset_limit: Integer?, ?read_uncommitted: bool?) -> _MessageMapDefinition[P]
+  def self.message_deque: [P] (_ToS name, ?ttl: Integer?, ?capacity: Integer?, ?read_uncommitted: bool?) -> _MessageDequeDefinition[P]
+
+  # --- handles ------------------------------------------------------------
+  # A single-value keyed-state handle. Reads return the stored value or nil.
+  # Every op is fiber-yield async: it looks blocking but never blocks the thread.
+  class ValueState[T = json_value]
+    def get: () -> T?
+    def set: (T value) -> void
+    def clear: () -> void
+    def commit: () -> nil
+    def rollback: () -> nil
+
+    # idiomatic conveniences
+    def value: () -> T?              # alias of #get
+    def value=: (T value) -> T      # alias of #set (assignment yields value)
+
+    private
+    def initialize: (NativeValueState native) -> void
+  end
+
+  # A String-keyed ordered-map keyed-state handle.
+  class MapState[V = json_value]
+    include State::Scanning
+
+    def get: (String key) -> V?
+    def get_many: (Array[String] keys) -> Array[V?]
+    def set: (String key, V value) -> void
+    def delete: (String key) -> nil
+    def clear: () -> void
+    def commit: () -> nil
+    def rollback: () -> nil
+    def each_pair: () { (String, V) -> void } -> void
+                 | () -> Enumerator[[ String, V ], void]
+    def reverse_each_pair: () { (String, V) -> void } -> void
+                         | () -> Enumerator[[ String, V ], void]
+    def each_key: () { (String) -> void } -> void
+                | () -> Enumerator[String, void]
+    def reverse_each_key: () { (String) -> void } -> void
+                        | () -> Enumerator[String, void]
+
+    # idiomatic Hash-style conveniences (bounded reads only)
+    def []: (String key) -> V?                       # alias of #get
+    def []=: (String key, V value) -> V              # alias of #set (assignment yields value)
+    def store: (String key, V value) -> V            # wrapper over #set, returns value
+    def each: () { (String, V) -> void } -> void     # alias of #each_pair
+            | () -> Enumerator[[ String, V ], void]
+    def values_at: (*String keys) -> Array[V?]
+    def fetch: (String key) -> V
+             | [D] (String key, D default) -> (V | D)
+             | [R] (String key) { (String) -> R } -> (V | R)
+    def key?: (String key) -> bool
+    def has_key?: (String key) -> bool
+    def include?: (String key) -> bool
+    def member?: (String key) -> bool
+    def dig: (String key, *untyped) -> untyped
+    def slice: (*String keys) -> Hash[String, V]
+    def fetch_values: (*String keys) -> Array[V]
+                    | [R] (*String keys) { (String) -> R } -> Array[V | R]
+
+    private
+    def initialize: (NativeMapState native) -> void
+    def traverse: (Symbol direction) { (String, V) -> void } -> void
+                | (Symbol direction) -> Enumerator[[ String, V ], void]
+    def traverse_keys: (Symbol direction) { (String) -> void } -> void
+                     | (Symbol direction) -> Enumerator[String, void]
+  end
+
+  # A deque keyed-state handle.
+  class DequeState[T = json_value]
+    include State::Scanning
+
+    def push: (T value) -> void
+    def unshift: (T value) -> void
+    def pop: () -> T?
+    def shift: () -> T?
+    def length: () -> Integer
+    def size: () -> Integer
+    def empty?: () -> bool
+    def clear: () -> void
+    def commit: () -> nil
+    def rollback: () -> nil
+    def get: (Integer index) -> T?
+    def each: () { (T) -> void } -> void
+            | () -> Enumerator[T, void]
+    def reverse_each: () { (T) -> void } -> void
+                    | () -> Enumerator[T, void]
+
+    # idiomatic Array-style conveniences (bounded reads only). #get and #fetch
+    # take a single Integer index (negatives resolve from the back, Array-style);
+    # #[] and #at are deliberately absent because they would invite a range read
+    # the remote deque cannot honor.
+    def prepend: (T value) -> self   # wrapper over #unshift
+    def append: (T value) -> self    # wrapper over #push
+    def <<: (T value) -> self
+    def first: () -> T?
+    def last: () -> T?
+    def fetch: (Integer index) -> T
+             | [D] (Integer index, D default) -> (T | D)
+             | [R] (Integer index) { (Integer) -> R } -> (T | R)
+
+    private
+    def initialize: (NativeDequeState native) -> void
+    def at_negative: (Integer index) -> T?
+    def traverse: (Symbol direction) { (T) -> void } -> void
+                | (Symbol direction) -> Enumerator[T, void]
+  end
+
+  # Native single-value handle (Prosody::NativeValueState), wrapped by ValueState.
+  class NativeValueState
+    def get: () -> untyped
+    def set: (untyped value) -> void
+    def clear: () -> void
+    def commit: () -> nil
+    def rollback: () -> nil
+  end
+
+  # Native ordered-map handle (Prosody::NativeMapState), wrapped by MapState.
+  class NativeMapState
+    def get: (String key) -> untyped
+    def contains_key: (String key) -> bool
+    def get_many: (Array[String] keys) -> Array[untyped]
+    def set: (String key, untyped value) -> void
+    def remove: (String key) -> void
+    def clear: () -> void
+    def scan: (String direction) -> StateScan
+    def keys: (String direction) -> StateScan
+    def commit: () -> nil
+    def rollback: () -> nil
+  end
+
+  # Native deque handle (Prosody::NativeDequeState), wrapped by DequeState.
+  class NativeDequeState
+    def len: () -> Integer
+    def is_empty: () -> bool
+    def get: (Integer index) -> untyped
+    def peek_front: () -> untyped
+    def peek_back: () -> untyped
+    def push_back: (untyped value) -> void
+    def push_front: (untyped value) -> void
+    def pop_front: () -> untyped
+    def pop_back: () -> untyped
+    def clear: () -> void
+    def scan: (String direction) -> StateScan
+    def commit: () -> nil
+    def rollback: () -> nil
+  end
+
+  # Native scan cursor (Prosody::StateScan), driven by the wrapper traversal.
+  class StateScan
+    def next: () -> untyped
+    def close: () -> void
+  end
+
+  # --- internal routing module --------------------------------------------
+  module State
+    VEND: Hash[Array[String], [ Symbol, Symbol ]]
+
+    # Adds keyed-state vending to the native context.
+    module Vending
+      def state: [T] (_ValueDefinition[T]) -> ValueState[T]
+               | [V] (_MapDefinition[V]) -> MapState[V]
+               | [T] (_DequeDefinition[T]) -> DequeState[T]
+               | [P] (_MessageValueDefinition[P]) -> ValueState[Message[P]]
+               | [P] (_MessageMapDefinition[P]) -> MapState[Message[P]]
+               | [P] (_MessageDequeDefinition[P]) -> DequeState[Message[P]]
+    end
+
+    # Shared native-scan driving mixed into the traversal handles.
+    module Scanning
+      private
+      def scan_each: (Symbol direction, ?Symbol opener) { (untyped) -> void } -> void
+    end
+  end
+
+  # Reopened to add keyed-state vending (see lib/prosody/state.rb).
+  class Context
+    include State::Vending
+
+    def value_state: (String name) -> NativeValueState
+    def map_state: (String name) -> NativeMapState
+    def deque_state: (String name) -> NativeDequeState
+    def message_value_state: (String name) -> NativeValueState
+    def message_map_state: (String name) -> NativeMapState
+    def message_deque_state: (String name) -> NativeDequeState
+  end
+end

data/steep_expectations.yml

@@ -0,0 +1,47 @@
+---
+- file: typecheck_negative/payload_types.rb
+  diagnostics:
+  - range:
+      start:
+        line: 10
+        character: 41
+      end:
+        line: 10
+        character: 51
+    severity: ERROR
+    message: |-
+      Cannot pass a value of type `::Object` as an argument of type `::Prosody::json_value`
+        ::Object <: ::Prosody::json_value
+          ::Object <: (nil | bool | ::Integer | ::Float | ::String | ::Array[::Prosody::json_value] | ::Hash[::String, ::Prosody::json_value])
+            ::Object <: nil
+    code: Ruby::ArgumentTypeMismatch
+  - range:
+      start:
+        line: 13
+        character: 22
+      end:
+        line: 13
+        character: 38
+    severity: ERROR
+    message: |-
+      Cannot pass a value of type `::String` as an argument of type `::Integer`
+        ::String <: ::Integer
+          ::Object <: ::Integer
+            ::BasicObject <: ::Integer
+    code: Ruby::ArgumentTypeMismatch
+  - range:
+      start:
+        line: 14
+        character: 42
+      end:
+        line: 14
+        character: 57
+    severity: ERROR
+    message: |-
+      Cannot pass a value of type `::negative_event` as an argument of type `::Prosody::Message[untyped]`
+        ::negative_event <: ::Prosody::Message[untyped]
+          { "amount" => ::Integer } <: ::Prosody::Message[untyped]
+            ::Hash["amount", ::Integer] <: ::Prosody::Message[untyped]
+              ::Object <: ::Prosody::Message[untyped]
+                ::BasicObject <: ::Prosody::Message[untyped]
+    code: Ruby::ArgumentTypeMismatch

data/typecheck/payload_types.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# This file is checked by Steep as a consumer of Prosody's public signatures.
+# It is not loaded at runtime.
+
+ORDER_BACKLOG = Prosody.message_deque("order-backlog")
+ORDER_TOTALS = Prosody.map("order-totals")
+
+class TypedOrderHandler < Prosody::EventHandler
+  def on_message(context, message)
+    order_id = message.payload["order_id"]
+    total = message.payload["total"]
+
+    # Message-backed state preserves the handler's payload type.
+    backlog = context.state(ORDER_BACKLOG)
+    backlog.push(message)
+    oldest = backlog.first
+
+    # This call is a regression constraint: state(ORDER_TOTALS) must infer as
+    # MapState[Integer], not untyped or a generic JSON-valued state handle.
+    consume_totals(context.state(ORDER_TOTALS))
+
+    consume_order(order_id, total)
+    consume_order(oldest.payload["order_id"], oldest.payload["total"]) if oldest
+  end
+
+  private
+
+  def consume_order(order_id, total)
+    "#{order_id.upcase}:#{total + 1}"
+  end
+
+  def consume_totals(totals)
+    totals.set("latest", 1)
+    nil
+  end
+end
+
+class DefaultPayloadConsumer
+  def payload(message)
+    message.payload
+  end
+end

data/typecheck/payload_types.rbs

@@ -0,0 +1,20 @@
+type order_event = {
+  "order_id" => String,
+  "total" => Integer
+}
+
+ORDER_BACKLOG: Prosody::_MessageDequeDefinition[order_event]
+ORDER_TOTALS: Prosody::_MapDefinition[Integer]
+
+class TypedOrderHandler < Prosody::EventHandler[order_event]
+  def on_message: (Prosody::Context context, Prosody::Message[order_event] message) -> void
+
+  private
+
+  def consume_order: (String order_id, Integer total) -> String
+  def consume_totals: (Prosody::MapState[Integer] totals) -> nil
+end
+
+class DefaultPayloadConsumer
+  def payload: (Prosody::Message message) -> Prosody::json_value
+end

data/typecheck_negative/payload_types.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Deliberately invalid calls. Diagnostics are committed in
+# steep_expectations.yml, so Steep fails if these errors disappear.
+NEGATIVE_TOTALS = Prosody.map("negative-totals")
+NEGATIVE_MESSAGES = Prosody.message_deque("negative-messages")
+
+class NegativeTypeChecks
+  def check(client, context, message)
+    client.send_message("events", "key", Object.new)
+    # @type var totals: Prosody::MapState[Integer]
+    totals = context.state(NEGATIVE_TOTALS)
+    totals.set("key", "not-an-integer")
+    context.state(NEGATIVE_MESSAGES).push(message.payload)
+  end
+end

data/typecheck_negative/payload_types.rbs

@@ -0,0 +1,8 @@
+type negative_event = { "amount" => Integer }
+
+NEGATIVE_TOTALS: Prosody::_MapDefinition[Integer]
+NEGATIVE_MESSAGES: Prosody::_MessageDequeDefinition[negative_event]
+
+class NegativeTypeChecks
+  def check: (Prosody::Client client, Prosody::Context context, Prosody::Message[negative_event] message) -> void
+end