prosody 0.4.0 → 0.5.0

data/lib/prosody/native_stubs.rb

@@ -186,7 +186,7 @@ module Prosody
     # +context.state(definition)+.
     #
     # @param name [String] the registered collection name
-    # @return [NativeValueState] the native handle
+    # @return [NativeJsonValueState] the native handle
     # @raise [PermanentStateError] if the name is unregistered or mismatched
     # @private
     def value_state(name)
@@ -199,7 +199,7 @@ module Prosody
     # +context.state(definition)+.
     #
     # @param name [String] the registered collection name
-    # @return [NativeMapState] the native handle
+    # @return [NativeJsonMapState] the native handle
     # @raise [PermanentStateError] if the name is unregistered or mismatched
     # @private
     def map_state(name)
@@ -212,7 +212,7 @@ module Prosody
     # +context.state(definition)+.
     #
     # @param name [String] the registered collection name
-    # @return [NativeDequeState] the native handle
+    # @return [NativeJsonDequeState] the native handle
     # @raise [PermanentStateError] if the name is unregistered or mismatched
     # @private
     def deque_state(name)
@@ -226,7 +226,7 @@ module Prosody
     # +context.state(definition)+.
     #
     # @param name [String] the registered collection name
-    # @return [NativeValueState] the native handle
+    # @return [NativeMessageValueState] the native handle
     # @raise [PermanentStateError] if the name is unregistered or mismatched
     # @private
     def message_value_state(name)
@@ -240,7 +240,7 @@ module Prosody
     # +context.state(definition)+.
     #
     # @param name [String] the registered collection name
-    # @return [NativeMapState] the native handle
+    # @return [NativeMessageMapState] the native handle
     # @raise [PermanentStateError] if the name is unregistered or mismatched
     # @private
     def message_map_state(name)
@@ -253,7 +253,7 @@ module Prosody
     # +context.state(definition)+.
     #
     # @param name [String] the registered collection name
-    # @return [NativeDequeState] the native handle
+    # @return [NativeMessageDequeState] the native handle
     # @raise [PermanentStateError] if the name is unregistered or mismatched
     # @private
     def message_deque_state(name)
@@ -315,6 +315,24 @@ module Prosody
     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
@@ -379,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
@@ -389,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
@@ -426,11 +449,22 @@ module Prosody
       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<untyped>] A handler object that processes messages
+    # @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
@@ -438,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)
@@ -453,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
@@ -471,14 +521,29 @@ 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.rs for implementation
-  class NativeValueState
+  # @see ext/prosody/src/handler/state/mod.rs for implementation
+  module NativeValueOperations
     # @private
     def initialize
       raise NotImplementedError, "This class is implemented natively in Rust"
@@ -523,13 +588,21 @@ module Prosody
     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 {StateScan#next} pull
+  # +#scan+, which opens the cursor synchronously; each native cursor pull
   # yields the fiber.
   #
-  # @see ext/prosody/src/handler/state.rs for implementation
-  class NativeMapState
+  # @see ext/prosody/src/handler/state/mod.rs for implementation
+  module NativeMapOperations
     # @private
     def initialize
       raise NotImplementedError, "This class is implemented natively in Rust"
@@ -589,9 +662,9 @@ module Prosody
 
     # 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"
+    # @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
@@ -600,9 +673,9 @@ module Prosody
     # 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"
+    # @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
@@ -622,13 +695,21 @@ module Prosody
     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 {StateScan#next} pull yields the
+  # which opens the cursor synchronously; each native cursor pull yields the
   # fiber.
   #
-  # @see ext/prosody/src/handler/state.rs for implementation
-  class NativeDequeState
+  # @see ext/prosody/src/handler/state/mod.rs for implementation
+  module NativeDequeOperations
     # @private
     def initialize
       raise NotImplementedError, "This class is implemented natively in Rust"
@@ -716,9 +797,9 @@ module Prosody
 
     # 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"
+    # @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
@@ -738,12 +819,20 @@ module Prosody
     end
   end
 
-  # Native scan cursor over a keyed-state collection, driven one chunk at a time
+  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.rs for implementation
-  class StateScan
+  # @see ext/prosody/src/handler/state/scan.rs for implementation
+  module NativeScanOperations
     # @private
     def initialize
       raise NotImplementedError, "This class is implemented natively in Rust"
@@ -764,6 +853,83 @@ module Prosody
     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.
   # This class is used internally by the native code.
   #

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