prosody 0.4.0 → 0.5.0

data/sig/state.rbs

@@ -1,4 +1,6 @@
 module Prosody
+  type state_config_value = String | Integer | bool
+
   # --- error taxonomy -----------------------------------------------------
   # Raised for keyed-state failures a retry cannot resolve (unregistered
   # collection, identity mismatch, duplicate registration, bad TTL). Never
@@ -17,6 +19,13 @@ module Prosody
   class NullValueError < TransientStateError
   end
 
+  class StateAccess < Data
+    attr_reader vend_method: Symbol
+    attr_reader wrapper: Symbol
+    attr_reader published_vend_method: Symbol?
+    attr_reader published_wrapper: Symbol?
+  end
+
   # Concrete immutable definition object returned by the constructor helpers.
   class StateDefinition < Data
     attr_reader name: String
@@ -24,10 +33,13 @@ module Prosody
     attr_reader payload: String
     attr_reader ttl_seconds: Integer?
     attr_reader read_uncommitted: bool?
+    attr_reader published: bool?
+    attr_reader read_cache: (Numeric | false)?
     attr_reader keyset_limit: Integer?
     attr_reader capacity: Integer?
+    attr_reader access: StateAccess
 
-    def to_state_config: () -> Hash[Symbol, untyped]
+    def to_state_config: () -> Hash[Symbol, state_config_value]
   end
 
   # --- definition interfaces (phantom-typed over the payload) --------------
@@ -37,51 +49,54 @@ module Prosody
     def name: () -> String
     def kind: () -> "value"
     def payload: () -> "json"
-    def to_state_config: () -> Hash[Symbol, untyped]
+    def read_cache: () -> (Numeric | false)?
+    def to_state_config: () -> Hash[Symbol, state_config_value]
   end
 
   interface _MapDefinition[V = json_value]
     def name: () -> String
     def kind: () -> "map"
     def payload: () -> "json"
-    def to_state_config: () -> Hash[Symbol, untyped]
+    def read_cache: () -> (Numeric | false)?
+    def to_state_config: () -> Hash[Symbol, state_config_value]
   end
 
   interface _DequeDefinition[T = json_value]
     def name: () -> String
     def kind: () -> "deque"
     def payload: () -> "json"
-    def to_state_config: () -> Hash[Symbol, untyped]
+    def read_cache: () -> (Numeric | false)?
+    def to_state_config: () -> Hash[Symbol, state_config_value]
   end
 
   interface _MessageValueDefinition[P = json_value]
     def name: () -> String
     def kind: () -> "value"
     def payload: () -> "message"
-    def to_state_config: () -> Hash[Symbol, untyped]
+    def to_state_config: () -> Hash[Symbol, state_config_value]
   end
 
   interface _MessageMapDefinition[P = json_value]
     def name: () -> String
     def kind: () -> "map"
     def payload: () -> "message"
-    def to_state_config: () -> Hash[Symbol, untyped]
+    def to_state_config: () -> Hash[Symbol, state_config_value]
   end
 
   interface _MessageDequeDefinition[P = json_value]
     def name: () -> String
     def kind: () -> "deque"
     def payload: () -> "message"
-    def to_state_config: () -> Hash[Symbol, untyped]
+    def to_state_config: () -> Hash[Symbol, state_config_value]
   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.value: [T] (_ToS name, ?ttl: Integer?, ?read_uncommitted: bool?, ?published: bool?, ?read_cache: (Numeric | false)?) -> _ValueDefinition[T]
+  def self.map: [V] (_ToS name, ?ttl: Integer?, ?keyset_limit: Integer?, ?read_uncommitted: bool?, ?published: bool?, ?read_cache: (Numeric | false)?) -> _MapDefinition[V]
+  def self.deque: [T] (_ToS name, ?ttl: Integer?, ?capacity: Integer?, ?read_uncommitted: bool?, ?published: bool?, ?read_cache: (Numeric | false)?) -> _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]
@@ -101,7 +116,7 @@ module Prosody
     def value=: (T value) -> T      # alias of #set (assignment yields value)
 
     private
-    def initialize: (NativeValueState native) -> void
+    def initialize: ((NativeJsonValueState | NativeMessageValueState) native) -> void
   end
 
   # A String-keyed ordered-map keyed-state handle.
@@ -123,6 +138,10 @@ module Prosody
                 | () -> Enumerator[String, void]
     def reverse_each_key: () { (String) -> void } -> void
                         | () -> Enumerator[String, void]
+    def each_value: () { (V) -> void } -> void
+                  | () -> Enumerator[V, void]
+    def reverse_each_value: () { (V) -> void } -> void
+                          | () -> Enumerator[V, void]
 
     # idiomatic Hash-style conveniences (bounded reads only)
     def []: (String key) -> V?                       # alias of #get
@@ -144,7 +163,7 @@ module Prosody
                     | [R] (*String keys) { (String) -> R } -> Array[V | R]
 
     private
-    def initialize: (NativeMapState native) -> void
+    def initialize: ((NativeJsonMapState | NativeMessageMapState) native) -> void
     def traverse: (Symbol direction) { (String, V) -> void } -> void
                 | (Symbol direction) -> Enumerator[[ String, V ], void]
     def traverse_keys: (Symbol direction) { (String) -> void } -> void
@@ -185,62 +204,160 @@ module Prosody
              | [R] (Integer index) { (Integer) -> R } -> (T | R)
 
     private
-    def initialize: (NativeDequeState native) -> void
+    def initialize: ((NativeJsonDequeState | NativeMessageDequeState) 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
+  interface _NativeValueHandle[T]
+    def get: () -> T?
+    def set: (T 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
+  class NativeJsonValueState
+    include _NativeValueHandle[json_value]
+  end
+
+  class NativeMessageValueState
+    include _NativeValueHandle[Message[json_value]]
+  end
+
+  interface _NativeMapHandle[V, S]
+    def get: (String key) -> V?
     def contains_key: (String key) -> bool
-    def get_many: (Array[String] keys) -> Array[untyped]
-    def set: (String key, untyped value) -> void
+    def get_many: (Array[String] keys) -> Array[V?]
+    def set: (String key, V value) -> void
     def remove: (String key) -> void
     def clear: () -> void
-    def scan: (String direction) -> StateScan
-    def keys: (String direction) -> StateScan
+    def scan: (Symbol direction) -> S
+    def keys: (Symbol direction) -> NativeMapKeyScan
     def commit: () -> nil
     def rollback: () -> nil
   end
 
-  # Native deque handle (Prosody::NativeDequeState), wrapped by DequeState.
-  class NativeDequeState
+  class NativeJsonMapState
+    include _NativeMapHandle[json_value, NativeJsonMapScan]
+  end
+
+  class NativeMessageMapState
+    include _NativeMapHandle[Message[json_value], NativeMessageMapScan]
+  end
+
+  interface _NativeDequeHandle[T, S]
     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 get: (Integer index) -> T?
+    def peek_front: () -> T?
+    def peek_back: () -> T?
+    def push_back: (T value) -> void
+    def push_front: (T value) -> void
+    def pop_front: () -> T?
+    def pop_back: () -> T?
     def clear: () -> void
-    def scan: (String direction) -> StateScan
+    def scan: (Symbol direction) -> S
     def commit: () -> nil
     def rollback: () -> nil
   end
 
-  # Native scan cursor (Prosody::StateScan), driven by the wrapper traversal.
-  class StateScan
-    def next: () -> untyped
+  class NativeJsonDequeState
+    include _NativeDequeHandle[json_value, NativeJsonDequeScan]
+  end
+
+  class NativeMessageDequeState
+    include _NativeDequeHandle[Message[json_value], NativeMessageDequeScan]
+  end
+
+  interface _NativeScan[T]
+    def next: () -> T?
     def close: () -> void
   end
 
-  # --- internal routing module --------------------------------------------
-  module State
-    VEND: Hash[Array[String], [ Symbol, Symbol ]]
+  class NativeJsonDequeScan
+    include _NativeScan[json_value]
+  end
+
+  class NativeJsonMapScan
+    include _NativeScan[[String, json_value]]
+  end
+
+  class NativeMessageDequeScan
+    include _NativeScan[Message[json_value]]
+  end
+
+  class NativeMessageMapScan
+    include _NativeScan[[String, Message[json_value]]]
+  end
+
+  class NativeMapKeyScan
+    include _NativeScan[String]
+  end
+
+  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 scan: (String key, Symbol direction) -> NativeJsonMapScan
+    def keys: (String key, Symbol direction) -> 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) -> NativeJsonDequeScan
+  end
+
+  class PublishedValue[T = json_value]
+    def get: (_ToS key) -> T?
+  end
+
+  class PublishedMap[V = json_value]
+    def get: (_ToS key, _ToS map_key) -> V?
+    def get_many: (_ToS key, Array[_ToS] map_keys) -> Array[V?]
+    def key?: (_ToS key, _ToS map_key) -> bool
+    alias has_key? key?
+    alias include? key?
+    alias member? key?
+    def each_pair: (_ToS key) { (String, V) -> void } -> void
+                 | (_ToS key) -> Enumerator[[String, V], void]
+    def reverse_each_pair: (_ToS key) { (String, V) -> void } -> void
+                         | (_ToS key) -> Enumerator[[String, V], void]
+    def each_key: (_ToS key) { (String) -> void } -> void
+                | (_ToS key) -> Enumerator[String, void]
+    def reverse_each_key: (_ToS key) { (String) -> void } -> void
+                        | (_ToS key) -> Enumerator[String, void]
+    def each_value: (_ToS key) { (V) -> void } -> void
+                  | (_ToS key) -> Enumerator[V, void]
+    def reverse_each_value: (_ToS key) { (V) -> void } -> void
+                          | (_ToS key) -> Enumerator[V, void]
+    alias each each_pair
+  end
+
+  class PublishedDeque[T = json_value]
+    def get: (_ToS key, Integer index) -> T?
+    def length: (_ToS key) -> Integer
+    alias size length
+    def empty?: (_ToS key) -> bool
+    def first: (_ToS key) -> T?
+    def last: (_ToS key) -> T?
+    def each: (_ToS key) { (T) -> void } -> void
+            | (_ToS key) -> Enumerator[T, void]
+    def reverse_each: (_ToS key) { (T) -> void } -> void
+                    | (_ToS key) -> Enumerator[T, void]
+  end
+
+  # --- shared state modules ------------------------------------------------
+  module State
     # Adds keyed-state vending to the native context.
     module Vending
       def state: [T] (_ValueDefinition[T]) -> ValueState[T]
@@ -254,7 +371,8 @@ module Prosody
     # Shared native-scan driving mixed into the traversal handles.
     module Scanning
       private
-      def scan_each: (Symbol direction, ?Symbol opener) { (untyped) -> void } -> void
+      def scan_each: [T] (Symbol direction, ?Symbol opener) { (T) -> void } -> void
+      def scan_items: [T] (_NativeScan[T] scan) { (T) -> void } -> void
     end
   end
 
@@ -262,11 +380,11 @@ module Prosody
   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
+    def value_state: (String name) -> NativeJsonValueState
+    def map_state: (String name) -> NativeJsonMapState
+    def deque_state: (String name) -> NativeJsonDequeState
+    def message_value_state: (String name) -> NativeMessageValueState
+    def message_map_state: (String name) -> NativeMessageMapState
+    def message_deque_state: (String name) -> NativeMessageDequeState
   end
 end

data/steep_expectations.yml

@@ -45,3 +45,13 @@
               ::Object <: ::Prosody::Message[untyped]
                 ::BasicObject <: ::Prosody::Message[untyped]
     code: Ruby::ArgumentTypeMismatch
+  - range:
+      start:
+        line: 18
+        character: 12
+      end:
+        line: 18
+        character: 19
+    severity: ERROR
+    message: Type `::Prosody::ExciseMessage` does not have method `payload`
+    code: Ruby::NoMethod

data/typecheck/payload_types.rb

@@ -7,9 +7,15 @@ ORDER_BACKLOG = Prosody.message_deque("order-backlog")
 ORDER_TOTALS = Prosody.map("order-totals")
 
 class TypedOrderHandler < Prosody::EventHandler
+  def on_excise(_context, message)
+    message.key
+    {"accepted" => true}
+  end
+
   def on_message(context, message)
-    order_id = message.payload["order_id"]
-    total = message.payload["total"]
+    payload = message.payload
+    order_id = payload["order_id"]
+    total = payload["total"]
 
     # Message-backed state preserves the handler's payload type.
     backlog = context.state(ORDER_BACKLOG)
@@ -21,7 +27,12 @@ class TypedOrderHandler < Prosody::EventHandler
     consume_totals(context.state(ORDER_TOTALS))
 
     consume_order(order_id, total)
-    consume_order(oldest.payload["order_id"], oldest.payload["total"]) if oldest
+    oldest_payload = oldest&.payload
+    consume_order(oldest_payload["order_id"], oldest_payload["total"]) if oldest_payload
+    {"accepted" => true}
+  end
+
+  def on_timer(_context, _timer)
   end
 
   private

data/typecheck/payload_types.rbs

@@ -2,12 +2,14 @@ type order_event = {
   "order_id" => String,
   "total" => Integer
 }
+type handler_response = { "accepted" => bool }
 
 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
+class TypedOrderHandler < Prosody::EventHandler[order_event, handler_response]
+  def on_message: (Prosody::Context context, Prosody::Message[order_event] message) -> handler_response
+  def on_excise: (Prosody::Context context, Prosody::ExciseMessage message) -> handler_response
 
   private
 

data/typecheck_negative/payload_types.rb

@@ -13,4 +13,8 @@ class NegativeTypeChecks
     totals.set("key", "not-an-integer")
     context.state(NEGATIVE_MESSAGES).push(message.payload)
   end
+
+  def check_excise(message)
+    message.payload
+  end
 end

data/typecheck_negative/payload_types.rbs

@@ -5,4 +5,5 @@ NEGATIVE_MESSAGES: Prosody::_MessageDequeDefinition[negative_event]
 
 class NegativeTypeChecks
   def check: (Prosody::Client client, Prosody::Context context, Prosody::Message[negative_event] message) -> void
+  def check_excise: (Prosody::ExciseMessage message) -> void
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: prosody
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Joshua Griffith
@@ -123,8 +123,11 @@ files:
 - ".ruby-version"
 - ".standard.yml"
 - ".taplo.toml"
+- AGENTS.md
 - ARCHITECTURE.md
 - CHANGELOG.md
+- CLAUDE.md
+- CONFIGURATION.md
 - Cargo.lock
 - Cargo.toml
 - LICENSE
@@ -143,14 +146,19 @@ files:
 - ext/prosody/src/bridge/mod.rs
 - ext/prosody/src/client/config.rs
 - ext/prosody/src/client/mod.rs
+- ext/prosody/src/client/request.rs
+- ext/prosody/src/client/support.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/state.rs
+- ext/prosody/src/handler/state/mod.rs
+- ext/prosody/src/handler/state/registration.rs
+- ext/prosody/src/handler/state/scan.rs
 - ext/prosody/src/handler/trigger.rs
 - ext/prosody/src/lib.rs
 - ext/prosody/src/logging.rs
+- ext/prosody/src/published.rs
 - ext/prosody/src/scheduler/cancellation.rs
 - ext/prosody/src/scheduler/handle.rs
 - ext/prosody/src/scheduler/mod.rs
@@ -163,6 +171,7 @@ files:
 - lib/prosody/handler.rb
 - lib/prosody/native_stubs.rb
 - lib/prosody/processor.rb
+- lib/prosody/request.rb
 - lib/prosody/sentry.rb
 - lib/prosody/state.rb
 - lib/prosody/version.rb
@@ -171,6 +180,7 @@ files:
 - sig/handler.rbs
 - sig/processor.rbs
 - sig/prosody.rbs
+- sig/request.rbs
 - sig/sentry.rbs
 - sig/state.rbs
 - sig/version.rbs