prosody 0.5.1 → 0.6.0

data/ext/prosody/src/published.rs

@@ -1,76 +1,97 @@
 //! Read-only published-state handles for Ruby.
+//!
+//! Every reader method runs through [`Reads`], which refuses a forked child
+//! and joins the caller's OpenTelemetry context. A failed read raises the
+//! same typed state errors as an owned handle.
 
 use crate::bridge::Bridge;
 use crate::handler::{
-    NativeJsonDequeScan, NativeJsonMapScan, NativeMapKeyScan, parse_direction,
-    published_deque_scan, published_map_key_scan, published_map_scan,
+    NativeJsonDequeScan, NativeJsonMapScan, NativeMapKeyScan, key_query, position_query, run_state,
 };
+use crate::util::ForkGuard;
 use crate::{ROOT_MOD, id};
-use magnus::value::ReprValue;
-use magnus::{Error, Module, Ruby, StaticSymbol, Value, method};
+use magnus::{Error, Module, RHash, Ruby, StaticSymbol, Value, method};
 use opentelemetry::propagation::TextMapCompositePropagator;
-use prosody::JsonCodec;
+use prosody::consumer::event_context::ErasedStateError;
 use prosody::high_level::erased::{
-    ErasedDirection, SharedDequeReader, SharedMapReader, SharedValueReader,
+    SharedDequeReader, SharedMapReader, SharedSetReader, SharedValueReader,
 };
-use prosody::state::Direction;
+use serde_json::Value as JsonValue;
 use serde_magnus::serialize;
 use std::sync::Arc;
-use tracing::Span;
 
-fn read_error(ruby: &Ruby, error: &impl ToString) -> Error {
-    Error::new(ruby.exception_runtime_error(), error.to_string())
+/// The bridge, trace propagator, and fork guard that every reader shares.
+#[derive(Clone)]
+pub(crate) struct Reads {
+    pub(crate) bridge: Bridge,
+    pub(crate) propagator: Arc<TextMapCompositePropagator>,
+    pub(crate) fork: ForkGuard,
 }
 
-fn erased_direction(direction: Direction) -> ErasedDirection {
-    match direction {
-        Direction::Forward => ErasedDirection::Forward,
-        Direction::Backward => ErasedDirection::Backward,
+impl Reads {
+    /// Waits for one read in the caller's trace.
+    ///
+    /// # Errors
+    ///
+    /// Raises `RuntimeError` after fork, and a typed state error when the
+    /// read fails.
+    fn read<F, T>(&self, ruby: &Ruby, read: F) -> Result<T, Error>
+    where
+        F: Future<Output = Result<T, ErasedStateError>> + Send + 'static,
+        T: Send + 'static,
+    {
+        self.fork.check(ruby)?;
+        run_state(ruby, &self.bridge, &self.propagator, read)
+    }
+
+    /// Waits for one optional JSON read and returns the value or `nil`.
+    ///
+    /// # Errors
+    ///
+    /// See [`Reads::read`].
+    fn read_json<F>(&self, ruby: &Ruby, read: F) -> Result<Value, Error>
+    where
+        F: Future<Output = Result<Option<JsonValue>, ErasedStateError>> + Send + 'static,
+    {
+        serialize(ruby, &self.read(ruby, read)?)
+    }
+
+    /// Returns the bridge and propagator for a new scan.
+    ///
+    /// # Errors
+    ///
+    /// Raises `RuntimeError` after fork.
+    fn scan_parts(&self, ruby: &Ruby) -> Result<(Bridge, Arc<TextMapCompositePropagator>), Error> {
+        self.fork.check(ruby)?;
+        Ok((self.bridge.clone(), Arc::clone(&self.propagator)))
     }
 }
 
 #[magnus::wrap(class = "Prosody::NativePublishedValue")]
 pub(crate) struct NativePublishedValue {
-    pub(crate) inner: SharedValueReader<JsonCodec>,
-    pub(crate) bridge: Bridge,
+    pub(crate) inner: SharedValueReader<JsonValue>,
+    pub(crate) reads: Reads,
 }
 
 impl NativePublishedValue {
     fn get(ruby: &Ruby, this: &Self, key: String) -> Result<Value, Error> {
         let inner = Arc::clone(&this.inner);
-        let value = this
-            .bridge
-            .wait_for(ruby, async move { inner.get(key).await }, Span::current())?
-            .map_err(|error| read_error(ruby, &error))?;
-        match value {
-            Some(value) => serialize(ruby, &value),
-            None => Ok(ruby.qnil().as_value()),
-        }
+        this.reads
+            .read_json(ruby, async move { inner.get(key).await })
     }
 }
 
 #[magnus::wrap(class = "Prosody::NativePublishedMap")]
 pub(crate) struct NativePublishedMap {
-    pub(crate) inner: SharedMapReader<JsonCodec>,
-    pub(crate) bridge: Bridge,
-    pub(crate) propagator: Arc<TextMapCompositePropagator>,
+    pub(crate) inner: SharedMapReader<JsonValue>,
+    pub(crate) reads: Reads,
 }
 
 impl NativePublishedMap {
     fn get(ruby: &Ruby, this: &Self, key: String, map_key: String) -> Result<Value, Error> {
         let inner = Arc::clone(&this.inner);
-        let value = this
-            .bridge
-            .wait_for(
-                ruby,
-                async move { inner.get(key, map_key).await },
-                Span::current(),
-            )?
-            .map_err(|error| read_error(ruby, &error))?;
-        match value {
-            Some(value) => serialize(ruby, &value),
-            None => Ok(ruby.qnil().as_value()),
-        }
+        this.reads
+            .read_json(ruby, async move { inner.get(key, map_key).await })
     }
 
     fn get_many(
@@ -81,25 +102,34 @@ impl NativePublishedMap {
     ) -> Result<Value, Error> {
         let inner = Arc::clone(&this.inner);
         let values = this
-            .bridge
-            .wait_for(
-                ruby,
-                async move { inner.get_many(key, map_keys).await },
-                Span::current(),
-            )?
-            .map_err(|error| read_error(ruby, &error))?;
+            .reads
+            .read(ruby, async move { inner.get_many(key, map_keys).await })?;
         serialize(ruby, &values)
     }
 
+    fn contains_many(
+        ruby: &Ruby,
+        this: &Self,
+        key: String,
+        map_keys: Vec<String>,
+    ) -> Result<Vec<bool>, Error> {
+        let inner = Arc::clone(&this.inner);
+        this.reads.read(
+            ruby,
+            async move { inner.contains_many(key, map_keys).await },
+        )
+    }
+
+    fn is_empty(ruby: &Ruby, this: &Self, key: String) -> Result<bool, Error> {
+        let inner = Arc::clone(&this.inner);
+        this.reads
+            .read(ruby, async move { inner.is_empty(key).await })
+    }
+
     fn contains_key(ruby: &Ruby, this: &Self, key: String, map_key: String) -> Result<bool, Error> {
         let inner = Arc::clone(&this.inner);
-        this.bridge
-            .wait_for(
-                ruby,
-                async move { inner.contains_key(key, map_key).await },
-                Span::current(),
-            )?
-            .map_err(|error| read_error(ruby, &error))
+        this.reads
+            .read(ruby, async move { inner.contains_key(key, map_key).await })
     }
 
     fn scan(
@@ -107,23 +137,12 @@ impl NativePublishedMap {
         this: &Self,
         key: String,
         direction: StaticSymbol,
+        options: RHash,
     ) -> Result<NativeJsonMapScan, Error> {
-        let direction = erased_direction(parse_direction(ruby, direction)?);
-        let inner = Arc::clone(&this.inner);
-        let cursor = this
-            .bridge
-            .wait_for(
-                ruby,
-                async move { inner.stream(key, direction).await },
-                Span::current(),
-            )?
-            .map_err(|error| read_error(ruby, &error))?;
-        published_map_scan(
-            ruby,
-            cursor,
-            this.bridge.clone(),
-            Arc::clone(&this.propagator),
-        )
+        let query = key_query(ruby, direction, options)?;
+        let (bridge, propagator) = this.reads.scan_parts(ruby)?;
+        let entries = this.inner.entries(key).with_query(query).stream();
+        Ok(NativeJsonMapScan::new(entries, bridge, propagator))
     }
 
     fn keys(
@@ -131,98 +150,95 @@ impl NativePublishedMap {
         this: &Self,
         key: String,
         direction: StaticSymbol,
+        options: RHash,
     ) -> Result<NativeMapKeyScan, Error> {
-        let direction = erased_direction(parse_direction(ruby, direction)?);
+        let query = key_query(ruby, direction, options)?;
+        let (bridge, propagator) = this.reads.scan_parts(ruby)?;
+        let keys = this.inner.keys(key).with_query(query).stream();
+        Ok(NativeMapKeyScan::new(keys, bridge, propagator))
+    }
+}
+
+#[magnus::wrap(class = "Prosody::NativePublishedSet")]
+pub(crate) struct NativePublishedSet {
+    pub(crate) inner: SharedSetReader,
+    pub(crate) reads: Reads,
+}
+
+impl NativePublishedSet {
+    fn contains(ruby: &Ruby, this: &Self, key: String, member: String) -> Result<bool, Error> {
         let inner = Arc::clone(&this.inner);
-        let cursor = this
-            .bridge
-            .wait_for(
-                ruby,
-                async move { inner.keys(key, direction).await },
-                Span::current(),
-            )?
-            .map_err(|error| read_error(ruby, &error))?;
-        published_map_key_scan(
-            ruby,
-            cursor,
-            this.bridge.clone(),
-            Arc::clone(&this.propagator),
-        )
+        this.reads
+            .read(ruby, async move { inner.contains(key, member).await })
+    }
+
+    fn contains_many(
+        ruby: &Ruby,
+        this: &Self,
+        key: String,
+        members: Vec<String>,
+    ) -> Result<Vec<bool>, Error> {
+        let inner = Arc::clone(&this.inner);
+        this.reads
+            .read(ruby, async move { inner.contains_many(key, members).await })
+    }
+
+    fn is_empty(ruby: &Ruby, this: &Self, key: String) -> Result<bool, Error> {
+        let inner = Arc::clone(&this.inner);
+        this.reads
+            .read(ruby, async move { inner.is_empty(key).await })
+    }
+
+    /// Opens a member cursor. Members are bare `String` keys, so the map key
+    /// cursor carries them.
+    fn keys(
+        ruby: &Ruby,
+        this: &Self,
+        key: String,
+        direction: StaticSymbol,
+        options: RHash,
+    ) -> Result<NativeMapKeyScan, Error> {
+        let query = key_query(ruby, direction, options)?;
+        let (bridge, propagator) = this.reads.scan_parts(ruby)?;
+        let members = this.inner.keys(key).with_query(query).stream();
+        Ok(NativeMapKeyScan::new(members, bridge, propagator))
     }
 }
 
 #[magnus::wrap(class = "Prosody::NativePublishedDeque")]
 pub(crate) struct NativePublishedDeque {
-    pub(crate) inner: SharedDequeReader<JsonCodec>,
-    pub(crate) bridge: Bridge,
-    pub(crate) propagator: Arc<TextMapCompositePropagator>,
+    pub(crate) inner: SharedDequeReader<JsonValue>,
+    pub(crate) reads: Reads,
 }
 
 impl NativePublishedDeque {
     fn get(ruby: &Ruby, this: &Self, key: String, index: usize) -> Result<Value, Error> {
         let inner = Arc::clone(&this.inner);
-        let value = this
-            .bridge
-            .wait_for(
-                ruby,
-                async move { inner.get(key, index).await },
-                Span::current(),
-            )?
-            .map_err(|error| read_error(ruby, &error))?;
-        match value {
-            Some(value) => serialize(ruby, &value),
-            None => Ok(ruby.qnil().as_value()),
-        }
+        this.reads
+            .read_json(ruby, async move { inner.get(key, index).await })
     }
 
     fn length(ruby: &Ruby, this: &Self, key: String) -> Result<usize, Error> {
         let inner = Arc::clone(&this.inner);
-        this.bridge
-            .wait_for(ruby, async move { inner.len(key).await }, Span::current())?
-            .map_err(|error| read_error(ruby, &error))
+        this.reads.read(ruby, async move { inner.len(key).await })
     }
 
     fn is_empty(ruby: &Ruby, this: &Self, key: String) -> Result<bool, Error> {
         let inner = Arc::clone(&this.inner);
-        this.bridge
-            .wait_for(
-                ruby,
-                async move { inner.is_empty(key).await },
-                Span::current(),
-            )?
-            .map_err(|error| read_error(ruby, &error))
+        this.reads
+            .read(ruby, async move { inner.is_empty(key).await })
     }
 
     fn peek_front(ruby: &Ruby, this: &Self, key: String) -> Result<Value, Error> {
         let inner = Arc::clone(&this.inner);
-        let value = this
-            .bridge
-            .wait_for(
-                ruby,
-                async move { inner.peek_front(key).await },
-                Span::current(),
-            )?
-            .map_err(|error| read_error(ruby, &error))?;
-        match value {
-            Some(value) => serialize(ruby, &value),
-            None => Ok(ruby.qnil().as_value()),
-        }
+        this.reads
+            .read_json(ruby, async move { inner.peek_front(key).await })
     }
 
     fn peek_back(ruby: &Ruby, this: &Self, key: String) -> Result<Value, Error> {
         let inner = Arc::clone(&this.inner);
-        let value = this
-            .bridge
-            .wait_for(
-                ruby,
-                async move { inner.peek_back(key).await },
-                Span::current(),
-            )?
-            .map_err(|error| read_error(ruby, &error))?;
-        match value {
-            Some(value) => serialize(ruby, &value),
-            None => Ok(ruby.qnil().as_value()),
-        }
+        this.reads
+            .read_json(ruby, async move { inner.peek_back(key).await })
     }
 
     fn scan(
@@ -230,23 +246,12 @@ impl NativePublishedDeque {
         this: &Self,
         key: String,
         direction: StaticSymbol,
+        options: RHash,
     ) -> Result<NativeJsonDequeScan, Error> {
-        let direction = erased_direction(parse_direction(ruby, direction)?);
-        let inner = Arc::clone(&this.inner);
-        let cursor = this
-            .bridge
-            .wait_for(
-                ruby,
-                async move { inner.stream(key, direction).await },
-                Span::current(),
-            )?
-            .map_err(|error| read_error(ruby, &error))?;
-        published_deque_scan(
-            ruby,
-            cursor,
-            this.bridge.clone(),
-            Arc::clone(&this.propagator),
-        )
+        let query = position_query(ruby, direction, options)?;
+        let (bridge, propagator) = this.reads.scan_parts(ruby)?;
+        let values = this.inner.values(key).with_query(query).stream();
+        Ok(NativeJsonDequeScan::new(values, bridge, propagator))
     }
 }
 
@@ -259,8 +264,22 @@ pub(crate) fn init(ruby: &Ruby) -> Result<(), Error> {
     map.define_method("get", method!(NativePublishedMap::get, 2))?;
     map.define_method("get_many", method!(NativePublishedMap::get_many, 2))?;
     map.define_method("contains_key", method!(NativePublishedMap::contains_key, 2))?;
-    map.define_method("scan", method!(NativePublishedMap::scan, 2))?;
-    map.define_method("keys", method!(NativePublishedMap::keys, 2))?;
+    map.define_method(
+        "contains_many",
+        method!(NativePublishedMap::contains_many, 2),
+    )?;
+    map.define_method("is_empty", method!(NativePublishedMap::is_empty, 1))?;
+    map.define_method("scan", method!(NativePublishedMap::scan, 3))?;
+    map.define_method("keys", method!(NativePublishedMap::keys, 3))?;
+
+    let set = module.define_class(id!(ruby, "NativePublishedSet"), ruby.class_object())?;
+    set.define_method("contains", method!(NativePublishedSet::contains, 2))?;
+    set.define_method(
+        "contains_many",
+        method!(NativePublishedSet::contains_many, 2),
+    )?;
+    set.define_method("is_empty", method!(NativePublishedSet::is_empty, 1))?;
+    set.define_method("keys", method!(NativePublishedSet::keys, 3))?;
 
     let deque = module.define_class(id!(ruby, "NativePublishedDeque"), ruby.class_object())?;
     deque.define_method("get", method!(NativePublishedDeque::get, 2))?;
@@ -268,6 +287,6 @@ pub(crate) fn init(ruby: &Ruby) -> Result<(), Error> {
     deque.define_method("is_empty", method!(NativePublishedDeque::is_empty, 1))?;
     deque.define_method("peek_front", method!(NativePublishedDeque::peek_front, 1))?;
     deque.define_method("peek_back", method!(NativePublishedDeque::peek_back, 1))?;
-    deque.define_method("scan", method!(NativePublishedDeque::scan, 2))?;
+    deque.define_method("scan", method!(NativePublishedDeque::scan, 3))?;
     Ok(())
 }

data/ext/prosody/src/scheduler/result.rs

@@ -80,9 +80,10 @@ impl ResultSender {
             return false;
         };
 
+        // A result with no JSON form is a handler mistake, so it retries.
         if is_success {
             let result = deserialize(ruby, result)
-                .map_err(|error| ProcessingError::Permanent(error.to_string()));
+                .map_err(|error| ProcessingError::Transient(error.to_string()));
             if result_tx.send(result).is_err() {
                 debug!("discarding result; receiver went away");
             }

data/ext/prosody/src/util.rs

@@ -13,7 +13,11 @@ use prosody::tracing::{
     TracingError, flush_telemetry as core_flush_telemetry, initialize_tracing,
     shutdown_telemetry as core_shutdown_telemetry,
 };
+use std::fmt;
+use std::io::{self, Write};
 use std::mem::{ManuallyDrop, forget};
+use std::process;
+use std::time::Duration;
 use tokio::runtime::{EnterGuard, Handle};
 use tracing::{error, warn};
 
@@ -179,6 +183,65 @@ impl Drop for RubyDrop {
     }
 }
 
+/// Writes one line to standard error.
+///
+/// Use it only where no logger exists: before tracing starts, or when the
+/// Ruby logger itself fails.
+pub(crate) fn report(message: fmt::Arguments<'_>) {
+    drop(writeln!(io::stderr().lock(), "{message}"));
+}
+
+/// Converts a Ruby number of seconds into a [`Duration`].
+///
+/// # Errors
+///
+/// Returns an error that names `option` if the value is negative, not
+/// finite, or too large for a [`Duration`].
+pub(crate) fn seconds(option: &str, value: f64) -> Result<Duration, String> {
+    Duration::try_from_secs_f64(value)
+        .map_err(|_| format!("{option}: must be a finite, non-negative number of seconds"))
+}
+
+/// Detects the use of a native object in a forked child process.
+///
+/// The Tokio runtime and the bridge thread do not survive `fork`. A native
+/// object that waits on them in a child waits forever, so it raises instead.
+#[derive(Clone, Copy, Debug)]
+pub struct ForkGuard {
+    /// The process that created the object.
+    pid: u32,
+    /// The Ruby class name that the error message shows.
+    class: &'static str,
+}
+
+impl ForkGuard {
+    /// Records the current process for an object of the Ruby `class`.
+    pub fn new(class: &'static str) -> Self {
+        Self {
+            pid: process::id(),
+            class,
+        }
+    }
+
+    /// Checks that the current process created the object.
+    ///
+    /// # Errors
+    ///
+    /// Returns a `RuntimeError` in a forked child process.
+    pub fn check(self, ruby: &Ruby) -> Result<(), Error> {
+        if process::id() == self.pid {
+            return Ok(());
+        }
+        Err(Error::new(
+            ruby.exception_runtime_error(),
+            format!(
+                "{} cannot be used after fork. Create a new client in the child process.",
+                self.class
+            ),
+        ))
+    }
+}
+
 /// Ensures a Tokio runtime context exists, entering one if necessary.
 ///
 /// Only creates a runtime guard when not already in a runtime context, avoiding
@@ -207,14 +270,13 @@ pub fn ensure_runtime_context(ruby: &Ruby) -> Option<EnterGuard<'static>> {
     let bridge = BRIDGE.get_or_init(|| Bridge::new(ruby));
 
     // Initialize tracing for observability
-    #[allow(clippy::print_stderr, reason = "logger has not been initialized yet")]
     TRACING_INIT.get_or_init(|| {
         let maybe_logger = Logger::new(ruby, bridge.clone())
-            .inspect_err(|error| eprintln!("failed to create logger: {error:#}"))
+            .inspect_err(|error| report(format_args!("failed to create logger: {error:#}")))
             .ok();
 
         if let Err(error) = initialize_tracing(maybe_logger) {
-            eprintln!("failed to initialize tracing: {error:#}");
+            report(format_args!("failed to initialize tracing: {error:#}"));
         }
     });
 

data/lib/prosody/client.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Prosody
+  # Ruby-side lifecycle helpers for the native {Prosody::Client}.
+  class Client
+    # Creates a client, yields it, and shuts it down when the block exits.
+    # The client shuts down also when the block raises. Repeated shutdown
+    # calls wait for the same operation, so the block can also call
+    # {#shutdown}.
+    #
+    # @param config [Hash, Configuration] Client configuration
+    # @yieldparam client [Client] the new client
+    # @return [Object] the value of the block
+    # @raise [ArgumentError] if no block is given or the configuration is invalid
+    # @raise [RuntimeError] if client initialization or shutdown fails
+    #
+    # @example
+    #   Prosody::Client.open(bootstrap_servers: "localhost:9092") do |client|
+    #     client.send_message("my-topic", "key", {"hello" => "world"})
+    #   end
+    def self.open(config)
+      raise ArgumentError, "Prosody::Client.open requires a block" unless block_given?
+
+      client = new(config)
+      begin
+        yield client
+      ensure
+        client.shutdown
+      end
+    end
+  end
+end

data/lib/prosody/configuration.rb

@@ -124,14 +124,18 @@ module Prosody
     # Interval between offset commit operations (in seconds).
     config_param :commit_interval, converter: ->(v) { duration_converter(v) }
 
+    # Interval between librdkafka statistics reports (in seconds).
+    # Env: PROSODY_STATISTICS_INTERVAL. Default: 5 seconds.
+    config_param :statistics_interval, converter: ->(v) { duration_converter(v) }
+
     # Base delay for retry operations (in seconds).
     config_param :retry_base, converter: ->(v) { duration_converter(v) }
 
     # Maximum delay between retries (in seconds).
     config_param :max_retry_delay, converter: ->(v) { duration_converter(v) }
 
-    # Global shared cache capacity across all partitions for message deduplication.
-    # Must be at least 1. Default: 8192.
+    # Capacity of the producer idempotence cache and of the consumer
+    # deduplication cache. Must be at least 1. Default: 8192.
     config_param :idempotence_cache_size, converter: ->(v) { Integer(v) }
 
     # Version string for cache-busting deduplication hashes. Changing this
@@ -303,7 +307,7 @@ module Prosody
 
     # Keyed-state collections to register before subscribe.
     #
-    # Accepts an array of StateDefinition objects (from Prosody.value/map/deque
+    # Accepts an array of StateDefinition objects (from Prosody.value/map/set/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,
@@ -312,13 +316,15 @@ module Prosody
         list.map { |d| d.respond_to?(:to_state_config) ? d.to_state_config : d }
       }
 
-    # 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.
     config_param :subsystem, converter: lambda(&:to_s)
 
-    # 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.
+    # Directory for the local keyed-state caches. Each consumer opens its
+    # cache in a new subdirectory and removes it when the consumer stops, so
+    # clients can share the directory. Falls back to the
+    # PROSODY_STATE_CACHE_DIR environment variable, then to
+    # <temp>/prosody/keyed-state. Must not be an empty string.
     config_param :state_cache_dir, converter: lambda(&:to_s)
 
     # Capacity of the owning keyed-state cache, such as "64 MiB". Uses
@@ -326,6 +332,13 @@ module Prosody
     # selects its default.
     config_param :state_owned_cache_size, converter: lambda(&:to_s)
 
+    # Bytes of in-memory writes the local keyed-state cache holds for each
+    # assigned partition before it flushes them to disk, such as "16 MiB".
+    # 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.
+    config_param :state_memtable_size, converter: lambda(&:to_s)
+
     # Capacity of the published-state read-through cache, such as "1 MiB".
     # 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.
@@ -336,11 +349,6 @@ module Prosody
     config_param :state_read_cache,
       converter: ->(v) { (v == true || v == false) ? v : Float(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/demand.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Prosody
+  # The demand a handler call serves, from +context.demand+.
+  #
+  # +kind+ is +:normal+ for a normal delivery and +:failure+ for a retry after
+  # a failure. +retries+ is the number of retries: 0 for a normal delivery and
+  # 1 on the first retry. After Prosody defers an event, the count starts
+  # again at 1. The count is an estimate. Keep an exact attempt count in
+  # keyed state if the handler needs one.
+  #
+  # @example Alert only on a retry
+  #   def on_message(context, message)
+  #     alert(message.key) if context.demand.failure?
+  #   end
+  Demand = Data.define(:kind, :retries) do
+    # Whether this is a normal delivery.
+    #
+    # @return [Boolean]
+    def normal? = kind == :normal
+
+    # Whether this is a retry after a failure.
+    #
+    # @return [Boolean]
+    def failure? = kind == :failure
+  end
+end