prosody 0.2.1 → 0.4.0

data/ext/prosody/src/lib.rs

@@ -11,6 +11,7 @@
 // Temporarily removing allows to see what lints we have
 
 #![allow(clippy::multiple_crate_versions, missing_docs)]
+#![recursion_limit = "256"]
 
 use crate::bridge::Bridge;
 use magnus::value::Lazy;

data/lib/prosody/configuration.rb

@@ -281,6 +281,32 @@ module Prosody
     # Overrides the PROSODY_TIMER_SPANS environment variable. Default: "follows_from".
     config_param :timer_spans, converter: ->(v) { v.to_s }
 
+    # Keyed-state collections to register before subscribe.
+    #
+    # Accepts an array of StateDefinition objects (from Prosody.value/map/deque
+    # and their message_* siblings) or already-serialized registration hashes.
+    # Duplicate names within the set are rejected by the native layer.
+    config_param :state_collections,
+      converter: lambda { |v|
+        list = v.is_a?(Hash) ? [v] : Array(v)
+        list.map { |d| d.respond_to?(:to_state_config) ? d.to_state_config : d }
+      }
+
+    # Disk workspace for the local keyed-state cache. Each live client
+    # needs its own directory. Falls back to the
+    # PROSODY_STATE_CACHE_DIR environment variable. Must not be an empty string.
+    config_param :state_cache_dir, converter: lambda(&:to_s)
+
+    # Capacity of the in-memory keyed-state cache, in bytes. Falls back to
+    # PROSODY_STATE_CACHE_SIZE_BYTES, then
+    # the storage-engine default.
+    config_param :state_cache_size_bytes, converter: ->(v) { Integer(v) }
+
+    # Delay in whole seconds between staging a provisional cell and the
+    # keyed-state recovery sweep. Every registered TTL must strictly exceed this.
+    # Must be a whole number of seconds >= 1 (validated natively).
+    config_param :state_recovery_delay, converter: ->(v) { duration_converter(v) }
+
     # Operation mode of the client.
     #
     # Valid values:

data/lib/prosody/handler.rb

@@ -114,7 +114,7 @@ module Prosody
           super(*args, &block)
         rescue *exception_classes => e
           # The new exception's #cause will be set automatically
-          raise error_class.new(e.message)
+          Kernel.raise error_class.new(e.message)
         end
       end
 
@@ -127,6 +127,10 @@ module Prosody
   # --------------------------------------------------------------------------
 
   # Abstract base class for handling incoming messages and timers from Prosody.
+  # The RBS type parameter describes the JSON payload delivered in each
+  # {Message}; it defaults to +Prosody::json_value+. Declare a narrower payload
+  # shape in your application's RBS (for example,
+  # +EventHandler[order_event]+) to type-check payload access.
   # Subclasses **must** implement `#on_message` to process received messages.
   # Subclasses **may** implement `#on_timer` to process timer events.
   # They may also use `permanent` or `transient` decorators to control retry logic.
@@ -156,7 +160,7 @@ module Prosody
     # custom message handling logic.
     #
     # @param [Context] context the message context
-    # @param [Message] message the message payload
+    # @param [Message<Payload>] message the message and its typed JSON payload
     # @raise [NotImplementedError] if not overridden by subclass
     # @return [void]
     def on_message(context, message)

data/lib/prosody/native_stubs.rb

@@ -179,12 +179,94 @@ module Prosody
     def scheduled
       raise NotImplementedError, "This method is implemented natively in Rust"
     end
+
+    # Vends the native single-value JSON state handle for the named collection.
+    #
+    # Internal routing target for {Prosody::State::Vending#state}; prefer
+    # +context.state(definition)+.
+    #
+    # @param name [String] the registered collection name
+    # @return [NativeValueState] the native handle
+    # @raise [PermanentStateError] if the name is unregistered or mismatched
+    # @private
+    def value_state(name)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    # Vends the native ordered-map JSON state handle for the named collection.
+    #
+    # Internal routing target for {Prosody::State::Vending#state}; prefer
+    # +context.state(definition)+.
+    #
+    # @param name [String] the registered collection name
+    # @return [NativeMapState] the native handle
+    # @raise [PermanentStateError] if the name is unregistered or mismatched
+    # @private
+    def map_state(name)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    # Vends the native deque JSON state handle for the named collection.
+    #
+    # Internal routing target for {Prosody::State::Vending#state}; prefer
+    # +context.state(definition)+.
+    #
+    # @param name [String] the registered collection name
+    # @return [NativeDequeState] the native handle
+    # @raise [PermanentStateError] if the name is unregistered or mismatched
+    # @private
+    def deque_state(name)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    # Vends the native single-value message state handle for the named
+    # collection.
+    #
+    # Internal routing target for {Prosody::State::Vending#state}; prefer
+    # +context.state(definition)+.
+    #
+    # @param name [String] the registered collection name
+    # @return [NativeValueState] the native handle
+    # @raise [PermanentStateError] if the name is unregistered or mismatched
+    # @private
+    def message_value_state(name)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    # Vends the native ordered-map message state handle for the named
+    # collection.
+    #
+    # Internal routing target for {Prosody::State::Vending#state}; prefer
+    # +context.state(definition)+.
+    #
+    # @param name [String] the registered collection name
+    # @return [NativeMapState] the native handle
+    # @raise [PermanentStateError] if the name is unregistered or mismatched
+    # @private
+    def message_map_state(name)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    # Vends the native deque message state handle for the named collection.
+    #
+    # Internal routing target for {Prosody::State::Vending#state}; prefer
+    # +context.state(definition)+.
+    #
+    # @param name [String] the registered collection name
+    # @return [NativeDequeState] the native handle
+    # @raise [PermanentStateError] if the name is unregistered or mismatched
+    # @private
+    def message_deque_state(name)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
   end
 
   # Represents a Kafka message with its metadata and payload.
   #
   # Instances of this class are created by the native code and passed to your
-  # EventHandler's #on_message method.
+  # EventHandler's #on_message method. In RBS, +Message[Payload]+ carries the
+  # statically declared payload shape; bare +Message+ defaults to
+  # +Prosody::json_value+. This annotation does not add runtime validation.
   #
   # @see ext/prosody/src/handler/message.rs for implementation
   class Message
@@ -227,7 +309,7 @@ module Prosody
     #
     # The payload is automatically deserialized from JSON to Ruby objects.
     #
-    # @return [Object] The message content
+    # @return [Payload] The message content
     def payload
       raise NotImplementedError, "This method is implemented natively in Rust"
     end
@@ -332,12 +414,14 @@ module Prosody
     #
     # @param topic [String] The destination topic name
     # @param key [String] The message key for partitioning
-    # @param payload [Object] The message payload (will be serialized to JSON)
+    # @param payload [Prosody::json_value] The JSON-compatible message payload
     # @return [void]
     # @raise [RuntimeError] If the message cannot be sent
     #
     # @example Sending a simple message
-    #   client.send_message("my-topic", "user-123", { event: "login", timestamp: Time.now })
+    #   client.send_message("my-topic", "user-123", {
+    #     "event" => "login", "timestamp" => Time.now.to_i
+    #   })
     def send_message(topic, key, payload)
       raise NotImplementedError, "This method is implemented natively in Rust"
     end
@@ -345,7 +429,7 @@ module Prosody
     # 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
+    # @param handler [EventHandler<untyped>] A handler object that processes messages
     # @return [void]
     # @raise [RuntimeError] If subscription fails
     #
@@ -389,6 +473,297 @@ module Prosody
     end
   end
 
+  # Native single-value keyed-state handle, vended by the context and wrapped by
+  # {Prosody::ValueState}. Every operation is fiber-yield async: it crosses the
+  # bridge and yields the fiber while the Rust core drives the operation.
+  #
+  # @see ext/prosody/src/handler/state.rs for implementation
+  class NativeValueState
+    # @private
+    def initialize
+      raise NotImplementedError, "This class is implemented natively in Rust"
+    end
+
+    # Reads the current value.
+    #
+    # @return [Object, nil] the stored value, or nil when absent
+    def get
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    # Buffers a write of the value.
+    #
+    # @param value [Object] the value to store
+    # @return [void]
+    # @raise [NullValueError] if value is nil
+    # @raise [TransientStateError] if value cannot be represented
+    def set(value)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    # Buffers a clear of the value.
+    #
+    # @return [void]
+    def clear
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    # Durably commits the buffered operations mid-handler.
+    #
+    # @return [nil]
+    def commit
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    # Discards the buffered uncommitted operations.
+    #
+    # @return [nil]
+    def rollback
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+  end
+
+  # Native String-keyed ordered-map keyed-state handle, vended by the context and
+  # wrapped by {Prosody::MapState}. Every operation is fiber-yield async, except
+  # +#scan+, which opens the cursor synchronously; each {StateScan#next} pull
+  # yields the fiber.
+  #
+  # @see ext/prosody/src/handler/state.rs for implementation
+  class NativeMapState
+    # @private
+    def initialize
+      raise NotImplementedError, "This class is implemented natively in Rust"
+    end
+
+    # Reads the value for a key.
+    #
+    # @param key [String] the map key
+    # @return [Object, nil] the value, or nil when the key is absent
+    def get(key)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    # Answers whether a stored cell exists for a key. No value decode and no
+    # resolver run (a message-backed map answers with zero Kafka fetches), but
+    # not no-I/O: a cache miss still reads the store.
+    #
+    # @param key [String] the map key
+    # @return [Boolean] whether a live cell exists for the key
+    def contains_key(key)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    # Reads several keys in a single isolated batch.
+    #
+    # @param keys [Array<String>] the keys to read, in order
+    # @return [Array<Object, nil>] one result per input key
+    def get_many(keys)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    # Inserts or overwrites a key.
+    #
+    # @param key [String] the map key
+    # @param value [Object] the value to store
+    # @return [void]
+    # @raise [NullValueError] if value is nil
+    # @raise [TransientStateError] if value cannot be represented
+    def set(key, value)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    # Removes a key.
+    #
+    # @param key [String] the map key
+    # @return [void]
+    def remove(key)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    # Removes every entry.
+    #
+    # @return [void]
+    def clear
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    # Opens a native ordered scan over the live entries.
+    #
+    # @param direction [String] "forward" or "backward"
+    # @return [StateScan] the native cursor
+    # @raise [TransientStateError] if direction is not "forward"/"backward"
+    def scan(direction)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    # Opens a native ordered scan over the live keys only, yielding bare keys.
+    # Skips value decode and the resolver (a message-backed map enumerates keys
+    # with zero Kafka fetches), though not no-I/O.
+    #
+    # @param direction [String] "forward" or "backward"
+    # @return [StateScan] the native key cursor
+    # @raise [TransientStateError] if direction is not "forward"/"backward"
+    def keys(direction)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    # Durably commits the buffered operations mid-handler.
+    #
+    # @return [nil]
+    def commit
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    # Discards the buffered uncommitted operations.
+    #
+    # @return [nil]
+    def rollback
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+  end
+
+  # Native deque keyed-state handle, vended by the context and wrapped by
+  # {Prosody::DequeState}. Every operation is fiber-yield async, except +#scan+,
+  # which opens the cursor synchronously; each {StateScan#next} pull yields the
+  # fiber.
+  #
+  # @see ext/prosody/src/handler/state.rs for implementation
+  class NativeDequeState
+    # @private
+    def initialize
+      raise NotImplementedError, "This class is implemented natively in Rust"
+    end
+
+    # The number of live elements.
+    #
+    # @return [Integer]
+    def len
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    # Whether the deque holds no live elements.
+    #
+    # @return [Boolean]
+    def is_empty
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    # Reads the element at front-relative position.
+    #
+    # @param index [Integer] the zero-based position from the front
+    # @return [Object, nil] the element, or nil past the end
+    def get(index)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    # Reads the front endpoint slot, or nil when empty. One round trip, no
+    # length read; an expired endpoint slot under a TTL yields nil even when
+    # live interior elements remain (a peek never searches inward).
+    #
+    # @return [Object, nil] the front element, or nil when empty
+    def peek_front
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    # Reads the back endpoint slot, or nil when empty. Same endpoint-slot
+    # semantics as #peek_front.
+    #
+    # @return [Object, nil] the back element, or nil when empty
+    def peek_back
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    # Appends an element at the back.
+    #
+    # @param value [Object] the element
+    # @return [void]
+    # @raise [NullValueError] if value is nil
+    # @raise [TransientStateError] if value cannot be represented
+    def push_back(value)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    # Prepends an element at the front.
+    #
+    # @param value [Object] the element
+    # @return [void]
+    # @raise [NullValueError] if value is nil
+    # @raise [TransientStateError] if value cannot be represented
+    def push_front(value)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    # Removes and returns the front element.
+    #
+    # @return [Object, nil] the removed element, or nil when empty
+    def pop_front
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    # Removes and returns the back element.
+    #
+    # @return [Object, nil] the removed element, or nil when empty
+    def pop_back
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    # Removes every element.
+    #
+    # @return [void]
+    def clear
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    # Opens a native scan over the live elements.
+    #
+    # @param direction [String] "forward" or "backward"
+    # @return [StateScan] the native cursor
+    # @raise [TransientStateError] if direction is not "forward"/"backward"
+    def scan(direction)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    # Durably commits the buffered operations mid-handler.
+    #
+    # @return [nil]
+    def commit
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    # Discards the buffered uncommitted operations.
+    #
+    # @return [nil]
+    def rollback
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+  end
+
+  # Native scan cursor over a keyed-state collection, driven one chunk at a time
+  # by the {Prosody::MapState} / {Prosody::DequeState} traversal methods. Each
+  # pull crosses the bridge and yields the fiber; +close+ is idempotent.
+  #
+  # @see ext/prosody/src/handler/state.rs for implementation
+  class StateScan
+    # @private
+    def initialize
+      raise NotImplementedError, "This class is implemented natively in Rust"
+    end
+
+    # Pulls the next item from the cursor.
+    #
+    # @return [Object, nil] the next item, or nil when the cursor is exhausted
+    def next
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    # Closes the native cursor. Idempotent.
+    #
+    # @return [void]
+    def close
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+  end
+
   # Internal processor for executing tasks asynchronously.
   # This class is used internally by the native code.
   #
@@ -410,7 +785,7 @@ module Prosody
     end
 
     # @private
-    def submit(task_id, carrier, callback, &block)
+    def submit(task_id, carrier, event_context, callback, &block)
       # Actual implementation is in lib/prosody/processor.rb
     end
   end