prosody 0.5.1 → 0.6.0

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.5.1"
+  VERSION = "0.6.0"
 end

data/lib/prosody.rb

@@ -16,10 +16,10 @@ require "async"
 require "logger"
 require_relative "prosody/version"
 require_relative "prosody/configuration"
+require_relative "prosody/demand"
 require_relative "prosody/handler"
 require_relative "prosody/processor"
 require_relative "prosody/sentry"
-require_relative "prosody/native_stubs" if defined?(Prosody::Client)
 
 module Prosody
   def self.logger
@@ -46,3 +46,4 @@ end
 # already exist.
 require_relative "prosody/state"
 require_relative "prosody/request"
+require_relative "prosody/client"

data/sig/configuration.rbs

@@ -63,6 +63,10 @@ module Prosody
     def commit_interval: () -> Float?
     def commit_interval=: (Numeric) -> Float
 
+    # Interval between librdkafka statistics reports (seconds)
+    def statistics_interval: () -> Float?
+    def statistics_interval=: (Numeric) -> Float
+
     # Base delay for retry operations (seconds)
     def retry_base: () -> Float?
     def retry_base=: (Numeric) -> Float
@@ -71,7 +75,7 @@ module Prosody
     def max_retry_delay: () -> Float?
     def max_retry_delay=: (Numeric) -> Float
 
-    # Size of the cache used for message idempotence
+    # Capacity of the producer idempotence cache and the consumer deduplication cache
     def idempotence_cache_size: () -> Integer?
     def idempotence_cache_size=: (Integer | _ToInt) -> Integer
 
@@ -256,18 +260,20 @@ module Prosody
     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_*
+    # definition objects (from Prosody.value/map/set/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.
+    # Subsystem under which published JSON and set 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.
+    # Directory for the local keyed-state caches. Each consumer uses a new
+    # subdirectory, so clients can share it. Falls back to
+    # PROSODY_STATE_CACHE_DIR, then to <temp>/prosody/keyed-state. Must not be
+    # an empty string.
     def state_cache_dir: () -> String?
     def state_cache_dir=: (_ToS) -> String
 
@@ -277,6 +283,14 @@ module Prosody
     def state_owned_cache_size: () -> String?
     def state_owned_cache_size=: (String | _ToS) -> String
 
+    # Bytes of in-memory writes the local keyed-state cache holds for each
+    # assigned partition before it flushes them to disk. Accepts a
+    # human-readable size. Memory use scales with the number of assigned
+    # partitions. Uses PROSODY_STATE_MEMTABLE_SIZE when omitted. Otherwise,
+    # the engine uses its default of 64 MiB.
+    def state_memtable_size: () -> String?
+    def state_memtable_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.
@@ -288,11 +302,6 @@ module Prosody
     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/prosody.rbs

@@ -23,8 +23,9 @@ module Prosody
     # 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
+    # Creates a topic. A nil cleanup_policy or retention uses the cluster
+    # default. retention is in seconds.
+    def create_topic: (String name, Integer partition_count, Integer replication_factor, ?cleanup_policy: String?, ?retention: Numeric?) -> void
 
     # Deletes a topic.
     def delete_topic: (String) -> void
@@ -40,11 +41,31 @@ module Prosody
     def initialize: (untyped) -> void
   end
 
+  type demand_kind = :normal | :failure
+
+  # The demand a handler call serves. kind is :normal for a normal delivery
+  # and :failure for a retry. retries is the number of retries: 0 for a
+  # normal delivery and 1 on the first retry. The count is an estimate.
+  class Demand < Data
+    attr_reader kind: demand_kind
+    attr_reader retries: Integer
+
+    def self.new: (demand_kind kind, Integer retries) -> instance
+                | (kind: demand_kind, retries: Integer) -> instance
+
+    def normal?: () -> bool
+    def failure?: () -> bool
+  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.
 
+    # Returns whether this call is a normal delivery or a retry.
+    # @return [Demand] the demand this call serves
+    def demand: () -> Demand
+
     # Checks if cancellation has been requested.
     # Cancellation includes both message-level cancellation (e.g., timeout)
     # and partition shutdown.
@@ -111,6 +132,12 @@ module Prosody
     # Returns the deserialized message payload.
     # @return [Payload] The message content
     def payload: () -> Payload
+
+    # Returns the producer's source system, or nil when the message has none.
+    def source_system: () -> String?
+
+    # Reports whether the producer requested a response to this message.
+    def response_requested?: () -> bool
   end
 
   # Represents an excise record with no payload.
@@ -120,6 +147,8 @@ module Prosody
     def offset: () -> Integer
     def key: () -> String
     def timestamp: () -> Time
+    def source_system: () -> String?
+    def response_requested?: () -> bool
   end
 
   # Represents a timer that was scheduled to fire at a specific time.
@@ -151,6 +180,9 @@ module Prosody
     def self.new: (Hash[Symbol, untyped] | Configuration config) -> Client
                 | (**untyped options) -> Client
 
+    # Creates a client, yields it, and shuts it down when the block exits.
+    def self.open: [T] (Hash[Symbol, untyped] | Configuration config) { (Client client) -> T } -> T
+
     # Returns the current state of the consumer.
     #
     # @return [Symbol] The consumer state: :shut_down, :unconfigured, :configured, or :running
@@ -159,7 +191,7 @@ module Prosody
     # Returns the number of Kafka partitions currently assigned to this consumer.
     #
     # @return [Integer] The number of assigned partitions
-    def assigned_partitions: () -> Integer
+    def assigned_partition_count: () -> Integer
 
     # Checks if the consumer is stalled.
     #
@@ -167,7 +199,7 @@ module Prosody
     # errors or reaching processing limits.
     #
     # @return [Boolean] true if the consumer is stalled, false otherwise
-    def is_stalled?: () -> bool
+    def stalled?: () -> bool
 
     # Sends a message to the specified Kafka topic.
     #
@@ -212,6 +244,7 @@ module Prosody
 
     def state: [T] (_ToS subsystem, _ValueDefinition[T] definition) -> PublishedValue[T]
              | [V] (_ToS subsystem, _MapDefinition[V] definition) -> PublishedMap[V]
+             | (_ToS subsystem, _SetDefinition definition) -> PublishedSet
              | [T] (_ToS subsystem, _DequeDefinition[T] definition) -> PublishedDeque[T]
   end
 end

data/sig/published.rbs

@@ -0,0 +1,102 @@
+module Prosody
+  # --- published-state readers, opened by Client#state -------------------
+  class NativePublishedValue
+    def get: (String key) -> json_value?
+  end
+
+  class NativePublishedMap
+    def get: (String key, String map_key) -> json_value?
+    def get_many: (String key, Array[String] map_keys) -> Array[json_value?]
+    def contains_key: (String key, String map_key) -> bool
+    def contains_many: (String key, Array[String] map_keys) -> Array[bool]
+    def is_empty: (String key) -> bool
+    def scan: (String key, Symbol direction, query_options query) -> NativeJsonMapScan
+    def keys: (String key, Symbol direction, query_options query) -> NativeMapKeyScan
+  end
+
+  class NativePublishedSet
+    def contains: (String key, String member) -> bool
+    def contains_many: (String key, Array[String] members) -> Array[bool]
+    def is_empty: (String key) -> bool
+    def keys: (String key, Symbol direction, query_options query) -> NativeMapKeyScan
+  end
+
+  class NativePublishedDeque
+    def get: (String key, Integer index) -> json_value?
+    def length: (String key) -> Integer
+    def is_empty: (String key) -> bool
+    def peek_front: (String key) -> json_value?
+    def peek_back: (String key) -> json_value?
+    def scan: (String key, Symbol direction, query_options query) -> NativeJsonDequeScan
+  end
+
+  class PublishedValue[T = json_value]
+    def get: (String key) -> T?
+
+    private
+    def initialize: (NativePublishedValue native) -> void
+  end
+
+  class PublishedMap[V = json_value]
+    include State::Scanning
+
+    def get: (String key, String map_key) -> V?
+    def get_many: (String key, Array[String] map_keys) -> Array[V?]
+    def key?: (String key, String map_key) -> bool
+    alias has_key? key?
+    alias include? key?
+    alias member? key?
+    def contains_many: (String key, Array[String] map_keys) -> Array[bool]
+    def empty?: (String key) -> bool
+    def each_pair: (String key, ?from: String?, ?after: String?, ?to: String?, ?before: String?, ?range: Range[String?]?, ?prefix: String?, ?limit: Integer?) { ([String, V]) -> void } -> void
+                 | (String key, ?from: String?, ?after: String?, ?to: String?, ?before: String?, ?range: Range[String?]?, ?prefix: String?, ?limit: Integer?) -> Enumerator[[String, V], void]
+    def reverse_each_pair: (String key, ?from: String?, ?after: String?, ?to: String?, ?before: String?, ?range: Range[String?]?, ?prefix: String?, ?limit: Integer?) { ([String, V]) -> void } -> void
+                         | (String key, ?from: String?, ?after: String?, ?to: String?, ?before: String?, ?range: Range[String?]?, ?prefix: String?, ?limit: Integer?) -> Enumerator[[String, V], void]
+    def each_key: (String key, ?from: String?, ?after: String?, ?to: String?, ?before: String?, ?range: Range[String?]?, ?prefix: String?, ?limit: Integer?) { (String) -> void } -> void
+                | (String key, ?from: String?, ?after: String?, ?to: String?, ?before: String?, ?range: Range[String?]?, ?prefix: String?, ?limit: Integer?) -> Enumerator[String, void]
+    def reverse_each_key: (String key, ?from: String?, ?after: String?, ?to: String?, ?before: String?, ?range: Range[String?]?, ?prefix: String?, ?limit: Integer?) { (String) -> void } -> void
+                        | (String key, ?from: String?, ?after: String?, ?to: String?, ?before: String?, ?range: Range[String?]?, ?prefix: String?, ?limit: Integer?) -> Enumerator[String, void]
+    def each_value: (String key, ?from: String?, ?after: String?, ?to: String?, ?before: String?, ?range: Range[String?]?, ?prefix: String?, ?limit: Integer?) { (V) -> void } -> void
+                  | (String key, ?from: String?, ?after: String?, ?to: String?, ?before: String?, ?range: Range[String?]?, ?prefix: String?, ?limit: Integer?) -> Enumerator[V, void]
+    def reverse_each_value: (String key, ?from: String?, ?after: String?, ?to: String?, ?before: String?, ?range: Range[String?]?, ?prefix: String?, ?limit: Integer?) { (V) -> void } -> void
+                          | (String key, ?from: String?, ?after: String?, ?to: String?, ?before: String?, ?range: Range[String?]?, ?prefix: String?, ?limit: Integer?) -> Enumerator[V, void]
+    alias each each_pair
+
+    private
+    def initialize: (NativePublishedMap native) -> void
+  end
+
+  class PublishedSet
+    include State::Scanning
+
+    def include?: (String key, String member) -> bool
+    alias member? include?
+    def contains_many: (String key, Array[String] members) -> Array[bool]
+    def empty?: (String key) -> bool
+    def each: (String key, ?from: String?, ?after: String?, ?to: String?, ?before: String?, ?range: Range[String?]?, ?prefix: String?, ?limit: Integer?) { (String) -> void } -> void
+            | (String key, ?from: String?, ?after: String?, ?to: String?, ?before: String?, ?range: Range[String?]?, ?prefix: String?, ?limit: Integer?) -> Enumerator[String, void]
+    def reverse_each: (String key, ?from: String?, ?after: String?, ?to: String?, ?before: String?, ?range: Range[String?]?, ?prefix: String?, ?limit: Integer?) { (String) -> void } -> void
+                    | (String key, ?from: String?, ?after: String?, ?to: String?, ?before: String?, ?range: Range[String?]?, ?prefix: String?, ?limit: Integer?) -> Enumerator[String, void]
+
+    private
+    def initialize: (NativePublishedSet native) -> void
+  end
+
+  class PublishedDeque[T = json_value]
+    include State::Scanning
+
+    def get: (String key, Integer index) -> T?
+    def length: (String key) -> Integer
+    alias size length
+    def empty?: (String key) -> bool
+    def first: (String key) -> T?
+    def last: (String key) -> T?
+    def each: (String key, ?from: Integer?, ?after: Integer?, ?to: Integer?, ?before: Integer?, ?range: Range[Integer?]?, ?limit: Integer?) { (T) -> void } -> void
+            | (String key, ?from: Integer?, ?after: Integer?, ?to: Integer?, ?before: Integer?, ?range: Range[Integer?]?, ?limit: Integer?) -> Enumerator[T, void]
+    def reverse_each: (String key, ?from: Integer?, ?after: Integer?, ?to: Integer?, ?before: Integer?, ?range: Range[Integer?]?, ?limit: Integer?) { (T) -> void } -> void
+                    | (String key, ?from: Integer?, ?after: Integer?, ?to: Integer?, ?before: Integer?, ?range: Range[Integer?]?, ?limit: Integer?) -> Enumerator[T, void]
+
+    private
+    def initialize: (NativePublishedDeque native) -> void
+  end
+end