prosody 0.4.0 → 0.5.0

data/lib/prosody/state.rb

@@ -40,7 +40,25 @@ module Prosody
   # both serializes into `Configuration#state_collections` (via
   # {#to_state_config}) so the collection is registered before subscribe, and
   # drives {Prosody::Context#state} to vend the matching typed handle.
-  StateDefinition = Data.define(:name, :kind, :payload, :ttl_seconds, :read_uncommitted, :keyset_limit, :capacity) do
+  StateAccess = Data.define(:vend_method, :wrapper, :published_vend_method, :published_wrapper)
+  private_constant :StateAccess
+  VALUE_ACCESS = StateAccess.new(vend_method: :value_state, wrapper: :ValueState,
+    published_vend_method: :published_value, published_wrapper: :PublishedValue)
+  MAP_ACCESS = StateAccess.new(vend_method: :map_state, wrapper: :MapState,
+    published_vend_method: :published_map, published_wrapper: :PublishedMap)
+  DEQUE_ACCESS = StateAccess.new(vend_method: :deque_state, wrapper: :DequeState,
+    published_vend_method: :published_deque, published_wrapper: :PublishedDeque)
+  MESSAGE_VALUE_ACCESS = StateAccess.new(vend_method: :message_value_state, wrapper: :ValueState,
+    published_vend_method: nil, published_wrapper: nil)
+  MESSAGE_MAP_ACCESS = StateAccess.new(vend_method: :message_map_state, wrapper: :MapState,
+    published_vend_method: nil, published_wrapper: nil)
+  MESSAGE_DEQUE_ACCESS = StateAccess.new(vend_method: :message_deque_state, wrapper: :DequeState,
+    published_vend_method: nil, published_wrapper: nil)
+  private_constant :VALUE_ACCESS, :MAP_ACCESS, :DEQUE_ACCESS,
+    :MESSAGE_VALUE_ACCESS, :MESSAGE_MAP_ACCESS, :MESSAGE_DEQUE_ACCESS
+
+  StateDefinition = Data.define(:name, :kind, :payload, :ttl_seconds, :read_uncommitted,
+    :published, :read_cache, :keyset_limit, :capacity, :access) do
     # Serializes this definition into the native-registration hash, omitting
     # unset optionals so they fall back to the core defaults.
     #
@@ -49,6 +67,7 @@ module Prosody
       config = {name: name, kind: kind, payload: payload}
       config[:ttl_seconds] = ttl_seconds unless ttl_seconds.nil?
       config[:read_uncommitted] = read_uncommitted unless read_uncommitted.nil?
+      config[:published] = published unless published.nil?
       config[:keyset_limit] = keyset_limit unless keyset_limit.nil?
       config[:capacity] = capacity unless capacity.nil?
       config
@@ -61,9 +80,11 @@ module Prosody
   # @param ttl [Integer, nil] optional per-write TTL in whole seconds
   # @param read_uncommitted [Boolean, nil] optional opt-out of transactional staging
   # @return [StateDefinition] a frozen definition
-  def self.value(name, ttl: nil, read_uncommitted: nil)
+  def self.value(name, ttl: nil, read_uncommitted: nil, published: nil, read_cache: nil)
     StateDefinition.new(name: name.to_s, kind: "value", payload: "json",
-      ttl_seconds: ttl, read_uncommitted: read_uncommitted, keyset_limit: nil, capacity: nil)
+      ttl_seconds: ttl, read_uncommitted: read_uncommitted, published: published,
+      read_cache: read_cache, keyset_limit: nil, capacity: nil,
+      access: VALUE_ACCESS)
   end
 
   # Defines a `String`-keyed ordered map JSON collection.
@@ -73,9 +94,11 @@ module Prosody
   # @param keyset_limit [Integer, nil] optional map-only keyset bound (`0..=4096`)
   # @param read_uncommitted [Boolean, nil] optional opt-out of transactional staging
   # @return [StateDefinition] a frozen definition
-  def self.map(name, ttl: nil, keyset_limit: nil, read_uncommitted: nil)
+  def self.map(name, ttl: nil, keyset_limit: nil, read_uncommitted: nil, published: nil, read_cache: nil)
     StateDefinition.new(name: name.to_s, kind: "map", payload: "json",
-      ttl_seconds: ttl, read_uncommitted: read_uncommitted, keyset_limit: keyset_limit, capacity: nil)
+      ttl_seconds: ttl, read_uncommitted: read_uncommitted, published: published,
+      read_cache: read_cache, keyset_limit: keyset_limit, capacity: nil,
+      access: MAP_ACCESS)
   end
 
   # Defines a deque JSON collection.
@@ -87,9 +110,11 @@ module Prosody
   #   and mutable across deploys, never persisted (see {DequeState#push}).
   # @param read_uncommitted [Boolean, nil] optional opt-out of transactional staging
   # @return [StateDefinition] a frozen definition
-  def self.deque(name, ttl: nil, capacity: nil, read_uncommitted: nil)
+  def self.deque(name, ttl: nil, capacity: nil, read_uncommitted: nil, published: nil, read_cache: nil)
     StateDefinition.new(name: name.to_s, kind: "deque", payload: "json",
-      ttl_seconds: ttl, read_uncommitted: read_uncommitted, keyset_limit: nil, capacity: capacity)
+      ttl_seconds: ttl, read_uncommitted: read_uncommitted, published: published,
+      read_cache: read_cache, keyset_limit: nil, capacity: capacity,
+      access: DEQUE_ACCESS)
   end
 
   # Defines a single-value Kafka-message collection (items are full messages).
@@ -100,7 +125,9 @@ module Prosody
   # @return [StateDefinition] a frozen definition
   def self.message_value(name, ttl: nil, read_uncommitted: nil)
     StateDefinition.new(name: name.to_s, kind: "value", payload: "message",
-      ttl_seconds: ttl, read_uncommitted: read_uncommitted, keyset_limit: nil, capacity: nil)
+      ttl_seconds: ttl, read_uncommitted: read_uncommitted, published: nil,
+      read_cache: nil, keyset_limit: nil, capacity: nil,
+      access: MESSAGE_VALUE_ACCESS)
   end
 
   # Defines a `String`-keyed ordered map Kafka-message collection.
@@ -112,7 +139,9 @@ module Prosody
   # @return [StateDefinition] a frozen definition
   def self.message_map(name, ttl: nil, keyset_limit: nil, read_uncommitted: nil)
     StateDefinition.new(name: name.to_s, kind: "map", payload: "message",
-      ttl_seconds: ttl, read_uncommitted: read_uncommitted, keyset_limit: keyset_limit, capacity: nil)
+      ttl_seconds: ttl, read_uncommitted: read_uncommitted, published: nil,
+      read_cache: nil, keyset_limit: keyset_limit, capacity: nil,
+      access: MESSAGE_MAP_ACCESS)
   end
 
   # Defines a deque Kafka-message collection.
@@ -126,21 +155,26 @@ module Prosody
   # @return [StateDefinition] a frozen definition
   def self.message_deque(name, ttl: nil, capacity: nil, read_uncommitted: nil)
     StateDefinition.new(name: name.to_s, kind: "deque", payload: "message",
-      ttl_seconds: ttl, read_uncommitted: read_uncommitted, keyset_limit: nil, capacity: capacity)
+      ttl_seconds: ttl, read_uncommitted: read_uncommitted, published: nil,
+      read_cache: nil, keyset_limit: nil, capacity: capacity,
+      access: MESSAGE_DEQUE_ACCESS)
   end
 
-  # Internal routing tables shared by the state wrappers.
+  # Shared state wrapper behavior.
   module State
-    # Maps a definition's `[kind, payload]` to the native vend method and the
-    # public wrapper class that wraps the vended native handle.
-    VEND = {
-      %w[value json] => [:value_state, :ValueState],
-      %w[map json] => [:map_state, :MapState],
-      %w[deque json] => [:deque_state, :DequeState],
-      %w[value message] => [:message_value_state, :ValueState],
-      %w[map message] => [:message_map_state, :MapState],
-      %w[deque message] => [:message_deque_state, :DequeState]
-    }.freeze
+    module Reading
+      # Opens a read-only view of a published JSON collection.
+      def state(subsystem, definition)
+        access = definition.access
+        if access.published_vend_method.nil? || access.published_wrapper.nil?
+          raise ArgumentError, "published state readers support JSON collections only"
+        end
+        cache_seconds = definition.read_cache unless definition.read_cache == false
+        native = public_send(access.published_vend_method, subsystem.to_s, definition.name, cache_seconds,
+          definition.read_cache == false)
+        Prosody.const_get(access.published_wrapper).new(native)
+      end
+    end
 
     # Adds keyed-state vending to the native context. Included into
     # {Prosody::Context}; kept as a module so the routing can be exercised
@@ -161,12 +195,8 @@ module Prosody
         cache_key = "#{definition.kind}:#{definition.payload}:#{definition.name}"
         return cache[cache_key] if cache.key?(cache_key)
 
-        vend_method, wrapper = VEND.fetch([definition.kind, definition.payload]) do
-          raise TransientStateError,
-            "state: unknown collection kind/payload #{[definition.kind, definition.payload].inspect}"
-        end
-        native = public_send(vend_method, definition.name)
-        cache[cache_key] = Prosody.const_get(wrapper).new(native)
+        native = public_send(definition.access.vend_method, definition.name)
+        cache[cache_key] = Prosody.const_get(definition.access.wrapper).new(native)
       end
     end
 
@@ -184,19 +214,104 @@ module Prosody
       # selects the native cursor seam — the default `:scan` yields values (or
       # `[key, value]` pairs), `:keys` yields bare map keys.
       def scan_each(direction, opener = :scan)
-        scan = @native.public_send(opener, direction.to_s)
-        begin
-          # `nil` is the exhaustion sentinel (unambiguous under the null ban);
-          # terminate on it explicitly rather than on falsiness, so a legal
-          # stored `false` (or a `[key, false]` pair, always a truthy Array)
-          # does not stop iteration and drop the tail after it.
-          until (item = scan.next).nil?
-            yield item
-          end
-        ensure
-          scan.close
+        scan_items(@native.public_send(opener, direction)) { |item| yield item }
+      end
+
+      def scan_items(scan)
+        # `nil` is the exhaustion sentinel (unambiguous under the null ban);
+        # terminate on it explicitly rather than on falsiness, so a legal
+        # stored `false` (or a `[key, false]` pair, always a truthy Array)
+        # does not stop iteration and drop the tail after it.
+        until (item = scan.next).nil?
+          yield item
         end
+      ensure
+        scan.close
+      end
+    end
+  end
+
+  class Client
+    include State::Reading
+  end
+
+  class PublishedValue
+    def initialize(native) = @native = native
+    def get(key) = @native.get(key.to_s)
+  end
+
+  class PublishedMap
+    include State::Scanning
+
+    def initialize(native) = @native = native
+    def get(key, map_key) = @native.get(key.to_s, map_key.to_s)
+    def get_many(key, map_keys) = @native.get_many(key.to_s, map_keys.map(&:to_s))
+    def key?(key, map_key) = @native.contains_key(key.to_s, map_key.to_s)
+    alias_method :has_key?, :key?
+    alias_method :include?, :key?
+    alias_method :member?, :key?
+
+    def each_pair(key, &block) = traverse(key, :forward, &block)
+    def reverse_each_pair(key, &block) = traverse(key, :backward, &block)
+    def each_key(key, &block) = traverse_keys(key, :forward, &block)
+    def reverse_each_key(key, &block) = traverse_keys(key, :backward, &block)
+    def each_value(key, &block) = traverse_values(key, :forward, &block)
+    def reverse_each_value(key, &block) = traverse_values(key, :backward, &block)
+    alias_method :each, :each_pair
+
+    private
+
+    def traverse(key, direction)
+      return enum_for(__method__, key, direction) unless block_given?
+
+      scan_items(@native.scan(key.to_s, direction)) { |entry| yield(*entry) }
+    end
+
+    def traverse_keys(key, direction)
+      return enum_for(__method__, key, direction) unless block_given?
+
+      scan_items(@native.keys(key.to_s, direction)) { |map_key| yield map_key }
+    end
+
+    def traverse_values(key, direction)
+      return enum_for(__method__, key, direction) unless block_given?
+
+      scan_items(@native.scan(key.to_s, direction)) { |entry| yield entry[1] }
+    end
+  end
+
+  class PublishedDeque
+    include State::Scanning
+
+    def initialize(native) = @native = native
+
+    def get(key, index)
+      unless index.is_a?(Integer)
+        raise TransientStateError, "get: index must be an Integer, got #{index.inspect}"
       end
+
+      return @native.get(key.to_s, index) unless index.negative?
+      return last(key) if index == -1
+
+      resolved = length(key) + index
+      resolved.negative? ? nil : @native.get(key.to_s, resolved)
+    end
+
+    def length(key) = @native.length(key.to_s)
+    alias_method :size, :length
+    def empty?(key) = @native.is_empty(key.to_s)
+    def first(key) = @native.peek_front(key.to_s)
+    def last(key) = @native.peek_back(key.to_s)
+
+    def each(key, &block) = traverse(key, :forward, &block)
+    def reverse_each(key, &block) = traverse(key, :backward, &block)
+
+    private
+
+    def traverse(key, direction)
+      return enum_for(__method__, key, direction) unless block_given?
+
+      scan_items(@native.scan(key.to_s, direction)) { |item| yield item }
     end
   end
 
@@ -207,7 +322,7 @@ module Prosody
   # made durable by {#commit}. All operations are fiber-yield async: they look
   # blocking but never block the thread.
   class ValueState
-    # @param native [Prosody::NativeValueState] the vended native handle
+    # @param native [Prosody::NativeJsonValueState, Prosody::NativeMessageValueState] the native handle
     def initialize(native)
       @native = native
     end
@@ -261,7 +376,7 @@ module Prosody
   class MapState
     include State::Scanning
 
-    # @param native [Prosody::NativeMapState] the vended native handle
+    # @param native [Prosody::NativeJsonMapState, Prosody::NativeMessageMapState] the native handle
     def initialize(native)
       @native = native
     end
@@ -348,6 +463,8 @@ module Prosody
     # @yieldparam key [String]
     # @return [Enumerator, void]
     def reverse_each_key(&block) = traverse_keys(:backward, &block)
+    def each_value(&block) = traverse_values(:forward, &block)
+    def reverse_each_value(&block) = traverse_values(:backward, &block)
 
     # --- idiomatic Hash-style aliases and conveniences ------------------
     # Each is composed from the canonical ops above and adds no capability
@@ -484,6 +601,12 @@ module Prosody
 
       scan_each(direction, :keys) { |key| yield key }
     end
+
+    def traverse_values(direction)
+      return enum_for(:traverse_values, direction) unless block_given?
+
+      scan_each(direction) { |entry| yield entry[1] }
+    end
   end
 
   # A deque keyed-state handle.
@@ -494,7 +617,7 @@ module Prosody
   class DequeState
     include State::Scanning
 
-    # @param native [Prosody::NativeDequeState] the vended native handle
+    # @param native [Prosody::NativeJsonDequeState, Prosody::NativeMessageDequeState] the native handle
     def initialize(native)
       @native = native
     end

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.4.0"
+  VERSION = "0.5.0"
 end

data/lib/prosody.rb

@@ -45,3 +45,4 @@ end
 # subclasses the error hierarchy, so every native class and base error must
 # already exist.
 require_relative "prosody/state"
+require_relative "prosody/request"

data/sig/configuration.rbs

@@ -103,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
@@ -199,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?
@@ -241,16 +261,32 @@ module Prosody
     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 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
+    # 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).

data/sig/handler.rbs

@@ -56,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[Payload = json_value]
+  # 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.
@@ -68,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[Payload] 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/prosody.rbs

@@ -12,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
@@ -95,6 +113,15 @@ module Prosody
     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.
   # Timer instances are passed to EventHandler's on_timer method when timers fire.
   class Timer
@@ -126,7 +153,7 @@ module Prosody
 
     # 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.
@@ -151,13 +178,16 @@ module Prosody
     # @raise [RuntimeError] If the message cannot be sent
     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.
     #
     # @param handler [EventHandler] A handler object that processes messages
     # @return [void]
     # @raise [RuntimeError] If subscription fails
-    def subscribe: [Payload] (EventHandler[Payload]) -> void
+    def subscribe: [Payload, Response] (EventHandler[Payload, Response]) -> void
 
     # Unsubscribes from all topics, stopping message processing.
     #
@@ -165,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
@@ -172,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