prosody 0.3.0 → 0.5.0

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 [NativeJsonValueState] 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 [NativeJsonMapState] 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 [NativeJsonDequeState] 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 [NativeMessageValueState] 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 [NativeMessageMapState] 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 [NativeMessageDequeState] 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,12 +309,30 @@ 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
   end
 
+  # An excise record with Kafka metadata and no payload.
+  class ExciseMessage
+    # @return [String] The topic name
+    def topic = raise NotImplementedError, "This method is implemented natively in Rust"
+
+    # @return [Integer] The partition number
+    def partition = raise NotImplementedError, "This method is implemented natively in Rust"
+
+    # @return [Integer] The message offset
+    def offset = raise NotImplementedError, "This method is implemented natively in Rust"
+
+    # @return [String] The message key
+    def key = raise NotImplementedError, "This method is implemented natively in Rust"
+
+    # @return [Time] The record timestamp
+    def timestamp = raise NotImplementedError, "This method is implemented natively in Rust"
+  end
+
   # Represents a timer that was scheduled to fire at a specific time.
   #
   # Timer instances are created by the native code and passed to your
@@ -297,7 +397,8 @@ module Prosody
 
     # Returns the current state of the consumer.
     #
-    # The consumer can be in one of three states:
+    # The consumer can be in one of four states:
+    # - `:shut_down` - The client is shut down
     # - `:unconfigured` - The consumer has not been configured yet
     # - `:configured` - The consumer is configured but not running
     # - `:running` - The consumer is actively consuming messages
@@ -307,6 +408,10 @@ module Prosody
       raise NotImplementedError, "This method is implemented natively in Rust"
     end
 
+    def native_request(_request)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
     # Returns the number of Kafka partitions currently assigned to this consumer.
     #
     # This method can be used to monitor the consumer's workload and ensure
@@ -332,21 +437,34 @@ 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
 
+    # Sends an excise record to the specified Kafka topic.
+    #
+    # @param topic [String] The destination topic name
+    # @param key [String] The message key for partitioning
+    # @return [void]
+    # @raise [RuntimeError] If the excise record cannot be sent
+    def excise(topic, key)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
     # Subscribes to Kafka topics using the provided handler.
-    # The handler must implement an `on_message(context, message)` method.
+    # The handler must implement `on_message`, `on_excise`, and `on_timer`.
     #
     # @param handler [EventHandler] A handler object that processes messages
     # @return [void]
+    # @raise [ArgumentError] If a required handler method is missing
     # @raise [RuntimeError] If subscription fails
     #
     # @example Subscribing with a handler
@@ -354,6 +472,13 @@ module Prosody
     #     def on_message(context, message)
     #       puts "Received message: #{message.payload}"
     #     end
+    #
+    #     def on_excise(_context, message)
+    #       puts "Excised key: #{message.key}"
+    #     end
+    #
+    #     def on_timer(_context, _timer)
+    #     end
     #   end
     #
     #   client.subscribe(MyHandler.new)
@@ -369,12 +494,21 @@ module Prosody
     # @return [void]
     # @raise [RuntimeError] If unsubscription fails
     #
-    # @example Shutting down a consumer
-    #   client.unsubscribe
     def unsubscribe
       raise NotImplementedError, "This method is implemented natively in Rust"
     end
 
+    # Shuts down the consumer and all client services.
+    #
+    # @return [void]
+    # @raise [RuntimeError] If shutdown fails
+    #
+    # @example Shutting down a client
+    #   client.shutdown
+    def shutdown
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
     # Returns the configured source system identifier.
     #
     # The source system is used to identify the originating service or
@@ -387,6 +521,413 @@ module Prosody
     def source_system
       raise NotImplementedError, "This method is implemented natively in Rust"
     end
+
+    # @private
+    def published_value(subsystem, name, read_cache, read_cache_disabled)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    # @private
+    def published_map(subsystem, name, read_cache, read_cache_disabled)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    # @private
+    def published_deque(subsystem, name, read_cache, read_cache_disabled)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    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/mod.rs for implementation
+  module NativeValueOperations
+    # @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
+
+  class NativeJsonValueState
+    include NativeValueOperations
+  end
+
+  class NativeMessageValueState
+    include NativeValueOperations
+  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 native cursor pull
+  # yields the fiber.
+  #
+  # @see ext/prosody/src/handler/state/mod.rs for implementation
+  module NativeMapOperations
+    # @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 [Symbol] +:forward+ or +:backward+
+    # @return [Object] the native cursor
+    # @raise [TransientStateError] if direction is not +:forward+ or +: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 [Symbol] +:forward+ or +:backward+
+    # @return [NativeMapKeyScan] the native key cursor
+    # @raise [TransientStateError] if direction is not +:forward+ or +: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
+
+  class NativeJsonMapState
+    include NativeMapOperations
+  end
+
+  class NativeMessageMapState
+    include NativeMapOperations
+  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 native cursor pull yields the
+  # fiber.
+  #
+  # @see ext/prosody/src/handler/state/mod.rs for implementation
+  module NativeDequeOperations
+    # @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 [Symbol] +:forward+ or +:backward+
+    # @return [Object] the native cursor
+    # @raise [TransientStateError] if direction is not +:forward+ or +: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
+
+  class NativeJsonDequeState
+    include NativeDequeOperations
+  end
+
+  class NativeMessageDequeState
+    include NativeDequeOperations
+  end
+
+  # Native 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/scan.rs for implementation
+  module NativeScanOperations
+    # @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
+
+  class NativeJsonDequeScan
+    include NativeScanOperations
+  end
+
+  class NativeJsonMapScan
+    include NativeScanOperations
+  end
+
+  class NativeMessageDequeScan
+    include NativeScanOperations
+  end
+
+  class NativeMessageMapScan
+    include NativeScanOperations
+  end
+
+  class NativeMapKeyScan
+    include NativeScanOperations
+  end
+
+  # @private
+  class NativePublishedValue
+    def get(key)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+  end
+
+  # @private
+  class NativePublishedMap
+    def get(key, map_key)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    def get_many(key, map_keys)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    def contains_key(key, map_key)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    def scan(key, direction)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    def keys(key, direction)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+  end
+
+  # @private
+  class NativePublishedDeque
+    def get(key, index)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    def length(key)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    def is_empty(key)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    def peek_front(key)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    def peek_back(key)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
+
+    def scan(key, direction)
+      raise NotImplementedError, "This method is implemented natively in Rust"
+    end
   end
 
   # Internal processor for executing tasks asynchronously.
@@ -410,7 +951,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

data/lib/prosody/request.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Prosody
+  Success = Data.define(:value)
+  Failure = Data.define(:error)
+  HandlerError = Data.define(:message)
+
+  Timeout = Data.define do
+    def message = "no response arrived before the deadline"
+  end
+
+  FormatMismatch = Data.define do
+    def message = "the responder answered in another format"
+  end
+
+  MalformedResponse = Data.define do
+    def message = "the response did not decode"
+  end
+
+  class Client
+    # Returns one outcome for each subsystem.
+    # @param timeout [Numeric] The response deadline in seconds.
+    # @raise [ArgumentError] if a subsystem name or timeout is invalid
+    # @raise [RuntimeError] if the request cannot start or the Kafka send fails
+    def request(topic:, key:, payload:, subsystems:, timeout:)
+      native_request(
+        topic: topic,
+        key: key,
+        payload: payload,
+        subsystems: subsystems,
+        timeout: timeout
+      )
+    end
+
+    # Returns one excise outcome for each subsystem.
+    def request_excise(topic:, key:, subsystems:, timeout:)
+      native_request_excise(
+        topic: topic,
+        key: key,
+        subsystems: subsystems,
+        timeout: timeout
+      )
+    end
+  end
+end