prosody 0.3.0 → 0.5.0

data/ext/prosody/src/client/config.rs

@@ -7,9 +7,13 @@
 //! builders.
 
 use magnus::{Error, Ruby, Value};
+use prosody::PeerConfiguration;
+use prosody::PeerEndpoint;
 use prosody::cassandra::config::CassandraConfigurationBuilder;
 use prosody::consumer::ConsumerConfigurationBuilder;
+use prosody::consumer::KeyedStateConfiguration;
 use prosody::consumer::SpanRelation;
+use prosody::consumer::kafka_state::{message_deque_state, message_map_state, message_state};
 use prosody::consumer::middleware::deduplication::DeduplicationConfigurationBuilder;
 use prosody::consumer::middleware::defer::DeferConfigurationBuilder;
 use prosody::consumer::middleware::monopolization::MonopolizationConfigurationBuilder;
@@ -19,11 +23,23 @@ use prosody::consumer::middleware::timeout::TimeoutConfigurationBuilder;
 use prosody::consumer::middleware::topic::FailureTopicConfigurationBuilder;
 use prosody::high_level::ConsumerBuilders;
 use prosody::high_level::mode::Mode;
+use prosody::loader::KafkaLoader;
+use prosody::loader::KafkaLoaderConfiguration;
 use prosody::producer::ProducerConfigurationBuilder;
+use prosody::state::descriptor::{
+    DequeDescriptor, MapDescriptor, StateDescriptor, deque_state, map_state, value_state,
+};
+use prosody::state::order_codec::Utf8KeyCodec;
+use prosody::subsystem::SubsystemName;
 use prosody::telemetry::emitter::TelemetryEmitterConfiguration;
+use prosody::timers::duration::CompactDuration;
+use prosody::{ByteSize, JsonCodec};
 use serde::{Deserialize, Deserializer};
 use serde_magnus::deserialize;
 use serde_untagged::UntaggedEnumVisitor;
+use std::net::SocketAddr;
+use std::num::NonZeroUsize;
+use std::path::PathBuf;
 use std::time::Duration;
 
 /// Configuration structure for the Prosody client that maps Ruby configuration
@@ -104,7 +120,7 @@ pub struct NativeConfiguration {
     /// List of Cassandra contact nodes (hostnames or IPs)
     cassandra_nodes: Option<Vec<String>>,
 
-    /// Keyspace to use for storing timer data in Cassandra
+    /// Keyspace used for persistent Prosody data in Cassandra.
     cassandra_keyspace: Option<String>,
 
     /// Preferred datacenter for Cassandra query routing
@@ -119,8 +135,8 @@ pub struct NativeConfiguration {
     /// Password for authenticating with Cassandra
     cassandra_password: Option<String>,
 
-    /// Retention period for failed/unprocessed timer data in Cassandra (in
-    /// seconds)
+    /// Retention period for persistent timer and deferral data in Cassandra,
+    /// in seconds.
     cassandra_retention: Option<f32>,
 
     /// Timer slab partitioning duration in seconds.
@@ -166,24 +182,24 @@ pub struct NativeConfiguration {
     /// Maximum delay between deferred retries (in seconds).
     defer_max_delay: Option<f32>,
 
-    /// Failure rate threshold for enabling deferral (0.0 to 1.0).
+    /// Failure rate threshold for disabling deferral (0.0 to 1.0).
     defer_failure_threshold: Option<f64>,
 
     /// Sliding window duration (in seconds) for failure rate tracking.
     defer_failure_window: Option<f32>,
 
-    /// Cache size for defer middleware.
-    defer_cache_size: Option<u32>,
+    /// Maximum messages retained by the shared Kafka loader.
+    loader_cache_size: Option<u32>,
 
     /// Maximum number of deferred store entries kept in the write-through cache
     /// per Cassandra defer store.
     defer_store_cache_size: Option<u32>,
 
-    /// Timeout for Kafka seek operations (in seconds).
-    defer_seek_timeout: Option<f32>,
+    /// Timeout for Kafka loader seek operations (in seconds).
+    loader_seek_timeout: Option<f32>,
 
     /// Messages to read sequentially before seeking.
-    defer_discard_threshold: Option<i64>,
+    loader_discard_threshold: Option<i64>,
 
     // Timeout configuration
     /// Fixed timeout duration for handler execution (in seconds).
@@ -202,6 +218,85 @@ pub struct NativeConfiguration {
 
     /// Span linking for timer execution spans (`child` or `follows_from`).
     timer_spans: Option<String>,
+
+    /// Address for the peer listener.
+    peer_bind_address: Option<String>,
+
+    /// gRPC connect URI that peers use for this client.
+    peer_advertised_connect: Option<String>,
+
+    /// Network name used to identify direct routes.
+    peer_network_name: Option<String>,
+
+    /// Maximum number of peer channels and registrations held in each cache.
+    peer_cache_capacity: Option<usize>,
+
+    /// Duration of each peer registration lease, in seconds.
+    peer_registration_ttl: Option<f64>,
+
+    // Keyed-state configuration
+    /// Keyed-state collections to register before subscribe.
+    state_collections: Option<Vec<StateCollectionConfig>>,
+
+    /// Subsystem under which published collections are advertised.
+    subsystem: Option<String>,
+
+    /// Root directory for the local keyed-state cache. Must not be empty.
+    state_cache_dir: Option<String>,
+
+    /// Capacity of the owning keyed-state cache.
+    state_owned_cache_size: Option<String>,
+
+    /// Capacity of the published-state read-through cache.
+    state_read_cache_size: Option<String>,
+
+    /// Default cache policy for published-state reads.
+    state_read_cache: Option<ReadCacheConfig>,
+
+    /// Delay in whole seconds before the keyed-state recovery sweep.
+    ///
+    /// Crosses as an `f64` so fractional/negative/non-finite values reach the
+    /// whole-number guard rather than being silently truncated.
+    state_recovery_delay: Option<f64>,
+}
+
+/// Declares one keyed-state collection to register before subscribe.
+#[derive(Clone, Debug, Deserialize)]
+struct StateCollectionConfig {
+    /// The collection name. Prosody requires it to be non-empty and unique.
+    name: String,
+
+    /// The collection kind: `"value"`, `"map"`, or `"deque"`.
+    kind: String,
+
+    /// The item payload: `"json"` or `"message"`.
+    payload: String,
+
+    /// Optional per-write TTL in whole seconds. Crosses as `f64` so
+    /// fractional/negative/non-finite values reach the whole-number guard.
+    ttl_seconds: Option<f64>,
+
+    /// Optional opt-out of transactional staging.
+    read_uncommitted: Option<bool>,
+
+    /// Whether other consumer groups may read this JSON collection.
+    published: Option<bool>,
+
+    /// Optional map-only keyset bound (`0..=4096`). The binding rejects values
+    /// that cannot map to an unsigned integer. Prosody enforces the ceiling.
+    keyset_limit: Option<f64>,
+
+    /// Optional deque-only window capacity (`>= 1`). Runtime-only and not
+    /// persisted. Crosses as `f64` so fractional/negative/non-finite values
+    /// reach the whole-number guard.
+    capacity: Option<f64>,
+}
+
+#[derive(Clone, Debug, Deserialize)]
+#[serde(untagged)]
+enum ReadCacheConfig {
+    Disabled(bool),
+    Ttl(f64),
 }
 
 /// Configuration for the health probe port.
@@ -651,22 +746,10 @@ impl<'a> From<&'a NativeConfiguration> for DeferConfigurationBuilder {
             builder.failure_window(Duration::from_secs_f32(*failure_window));
         }
 
-        if let Some(cache_size) = &config.defer_cache_size {
-            builder.cache_size(*cache_size as usize);
-        }
-
         if let Some(store_cache_size) = &config.defer_store_cache_size {
             builder.store_cache_size(*store_cache_size as usize);
         }
 
-        if let Some(seek_timeout) = &config.defer_seek_timeout {
-            builder.seek_timeout(Duration::from_secs_f32(*seek_timeout));
-        }
-
-        if let Some(discard_threshold) = &config.defer_discard_threshold {
-            builder.discard_threshold(*discard_threshold);
-        }
-
         builder
     }
 }
@@ -696,25 +779,41 @@ impl<'a> From<&'a NativeConfiguration> for TimeoutConfigurationBuilder {
     }
 }
 
-impl<'a> From<&'a NativeConfiguration> for DeduplicationConfigurationBuilder {
-    /// Converts a `NativeConfiguration` reference into a
+impl<'a> TryFrom<&'a NativeConfiguration> for DeduplicationConfigurationBuilder {
+    type Error = String;
+
+    /// Attempts to convert a `NativeConfiguration` reference into a
     /// `DeduplicationConfigurationBuilder`.
     ///
     /// This takes the relevant deduplication settings from the configuration
     /// and sets them on a new `DeduplicationConfigurationBuilder` instance.
     ///
+    /// Consumer deduplication is mandatory in the core (it is the keyed-state
+    /// commit oracle), so `cache_capacity` is `NonZeroUsize` and a zero
+    /// capacity is unrepresentable rather than a silent "disable". An explicit
+    /// `idempotence_cache_size` of `0` is therefore rejected here rather than
+    /// silently defaulting; this mirrors the sibling `prosody-js` binding and
+    /// the core's own rejection of `PROSODY_IDEMPOTENCE_CACHE_SIZE=0`.
+    ///
     /// # Arguments
     ///
     /// * `config` - The configuration to convert
     ///
     /// # Returns
     ///
-    /// A configured `DeduplicationConfigurationBuilder`
-    fn from(config: &'a NativeConfiguration) -> Self {
+    /// A configured `DeduplicationConfigurationBuilder` if successful
+    ///
+    /// # Errors
+    ///
+    /// Returns a `String` error if `idempotence_cache_size` is explicitly set
+    /// to `0`.
+    fn try_from(config: &'a NativeConfiguration) -> Result<Self, Self::Error> {
         let mut builder = Self::default();
 
         if let Some(cache_capacity) = &config.idempotence_cache_size {
-            builder.cache_capacity(*cache_capacity as usize);
+            let cache_capacity = NonZeroUsize::new(*cache_capacity as usize)
+                .ok_or_else(|| "idempotence_cache_size must be greater than 0".to_owned())?;
+            builder.cache_capacity(cache_capacity);
         }
 
         if let Some(version) = &config.idempotence_version {
@@ -728,7 +827,7 @@ impl<'a> From<&'a NativeConfiguration> for DeduplicationConfigurationBuilder {
             builder.ttl(Duration::from_secs_f64(*ttl));
         }
 
-        builder
+        Ok(builder)
     }
 }
 
@@ -770,6 +869,354 @@ impl<'a> TryFrom<&'a NativeConfiguration> for TelemetryEmitterConfiguration {
     }
 }
 
+/// The kind of a keyed-state collection.
+enum CollectionKind {
+    /// A single-value collection.
+    Value,
+    /// A `String`-keyed ordered map.
+    Map,
+    /// A deque.
+    Deque,
+}
+
+/// The item payload of a keyed-state collection.
+enum CollectionPayload {
+    /// JSON values.
+    Json,
+    /// The full Kafka message the handler received.
+    Message,
+}
+
+/// Parses a collection-kind token.
+///
+/// # Errors
+///
+/// Returns a permanent-category error naming the field if the token is not
+/// `"value"`, `"map"`, or `"deque"`.
+fn parse_kind(index: usize, kind: &str) -> Result<CollectionKind, String> {
+    match kind {
+        "value" => Ok(CollectionKind::Value),
+        "map" => Ok(CollectionKind::Map),
+        "deque" => Ok(CollectionKind::Deque),
+        other => Err(format!(
+            "state_collections[{index}].kind: expected \"value\", \"map\", or \"deque\", got \
+             {other:?}"
+        )),
+    }
+}
+
+/// Parses a collection-payload token.
+///
+/// # Errors
+///
+/// Returns a permanent-category error naming the field if the token is not
+/// `"json"` or `"message"`.
+fn parse_payload(index: usize, payload: &str) -> Result<CollectionPayload, String> {
+    match payload {
+        "json" => Ok(CollectionPayload::Json),
+        "message" => Ok(CollectionPayload::Message),
+        other => Err(format!(
+            "state_collections[{index}].payload: expected \"json\" or \"message\", got {other:?}"
+        )),
+    }
+}
+
+/// Validates a numeric field as a whole number within `min..=max`.
+///
+/// The field arrives as an `f64` (the raw Ruby number, un-coerced) so that
+/// fractional, negative, and non-finite values reach this guard instead of
+/// being silently truncated or wrapped by an earlier integer conversion.
+///
+/// # Errors
+///
+/// Returns a permanent-category error naming the field if the value is not a
+/// whole number in the inclusive range.
+fn whole_number_field(value: f64, field: &str, min: u32, max: u32) -> Result<u32, String> {
+    if value.is_finite()
+        && value.fract() == 0.0
+        && value >= f64::from(min)
+        && value <= f64::from(max)
+    {
+        Ok(value as u32)
+    } else {
+        Err(format!("{field}: must be a whole number in {min}..={max}"))
+    }
+}
+
+fn build_peer_config(config: &NativeConfiguration) -> Result<PeerConfiguration, String> {
+    let mut builder = PeerConfiguration::builder();
+    if let Some(value) = &config.peer_bind_address {
+        builder.bind_address(
+            value
+                .parse::<SocketAddr>()
+                .map_err(|error| format!("peer_bind_address: {error}"))?,
+        );
+    }
+    if let Some(value) = &config.peer_advertised_connect {
+        builder.advertised_connect(
+            PeerEndpoint::try_from(value.clone())
+                .map_err(|error| format!("peer_advertised_connect: {error}"))?,
+        );
+    }
+    if let Some(value) = &config.peer_network_name {
+        builder.network_name(value.clone());
+    }
+    if let Some(value) = config.peer_cache_capacity {
+        builder.peer_cache_capacity(value);
+    }
+    if let Some(value) = config.peer_registration_ttl {
+        builder.registration_ttl(
+            Duration::try_from_secs_f64(value)
+                .map_err(|_| "peer_registration_ttl: must be a valid duration".to_owned())?,
+        );
+    }
+    builder.build().map_err(|error| error.to_string())
+}
+
+/// Applies the shared descriptor options (TTL, commit mode) fluently.
+fn with_def<D: StateDescriptor>(
+    descriptor: D,
+    ttl_seconds: Option<u32>,
+    read_uncommitted: Option<bool>,
+    published: Option<bool>,
+) -> D {
+    let mut descriptor = descriptor;
+    if let Some(ttl) = ttl_seconds {
+        descriptor = descriptor.ttl(CompactDuration::new(ttl));
+    }
+    if read_uncommitted == Some(true) {
+        descriptor = descriptor.read_uncommitted();
+    }
+    if let Some(published) = published {
+        descriptor = descriptor.published(published);
+    }
+    descriptor
+}
+
+/// Applies the map-only keyset bound when configured.
+fn with_keyset<KC, V>(
+    descriptor: MapDescriptor<KC, V>,
+    keyset_limit: Option<u32>,
+) -> MapDescriptor<KC, V> {
+    match keyset_limit {
+        Some(limit) => descriptor.keyset_limit(limit as usize),
+        None => descriptor,
+    }
+}
+
+/// Applies the deque-only window capacity when configured.
+fn with_capacity<T>(
+    descriptor: DequeDescriptor<T>,
+    capacity: Option<NonZeroUsize>,
+) -> DequeDescriptor<T> {
+    match capacity {
+        Some(cap) => descriptor.capacity(cap),
+        None => descriptor,
+    }
+}
+
+/// Maps one collection into its descriptor over the closed 3×2 (kind ×
+/// payload) matrix.
+///
+/// # Errors
+///
+/// Returns a permanent-category error when a host value cannot be mapped into
+/// a Prosody type.
+fn register_state_collection(
+    keyed: &mut KeyedStateConfiguration,
+    index: usize,
+    collection: &StateCollectionConfig,
+) -> Result<(), String> {
+    let kind = parse_kind(index, &collection.kind)?;
+    let payload = parse_payload(index, &collection.payload)?;
+
+    let ttl_seconds = match collection.ttl_seconds {
+        Some(value) => Some(whole_number_field(
+            value,
+            &format!("state_collections[{index}].ttl_seconds"),
+            0,
+            u32::MAX,
+        )?),
+        None => None,
+    };
+
+    let keyset_limit = keyset_limit(collection.keyset_limit, &kind, index)?;
+    let capacity = capacity(collection.capacity, &kind, index)?;
+
+    let read_uncommitted = collection.read_uncommitted;
+    let name = collection.name.as_str();
+    match (kind, payload) {
+        (CollectionKind::Value, CollectionPayload::Json) => {
+            let _ = keyed.register(with_def(
+                value_state::<JsonCodec>(name),
+                ttl_seconds,
+                read_uncommitted,
+                collection.published,
+            ));
+        }
+        (CollectionKind::Map, CollectionPayload::Json) => {
+            let descriptor = with_def(
+                map_state::<Utf8KeyCodec, JsonCodec>(name),
+                ttl_seconds,
+                read_uncommitted,
+                collection.published,
+            );
+            let _ = keyed.register(with_keyset(descriptor, keyset_limit));
+        }
+        (CollectionKind::Deque, CollectionPayload::Json) => {
+            let descriptor = with_def(
+                deque_state::<JsonCodec>(name),
+                ttl_seconds,
+                read_uncommitted,
+                collection.published,
+            );
+            let _ = keyed.register(with_capacity(descriptor, capacity));
+        }
+        (CollectionKind::Value, CollectionPayload::Message) => {
+            let _ = keyed.register(with_def(
+                message_state::<KafkaLoader<JsonCodec>>(name),
+                ttl_seconds,
+                read_uncommitted,
+                collection.published,
+            ));
+        }
+        (CollectionKind::Map, CollectionPayload::Message) => {
+            let descriptor = with_def(
+                message_map_state::<Utf8KeyCodec, KafkaLoader<JsonCodec>>(name),
+                ttl_seconds,
+                read_uncommitted,
+                collection.published,
+            );
+            let _ = keyed.register(with_keyset(descriptor, keyset_limit));
+        }
+        (CollectionKind::Deque, CollectionPayload::Message) => {
+            let descriptor = with_def(
+                message_deque_state::<KafkaLoader<JsonCodec>>(name),
+                ttl_seconds,
+                read_uncommitted,
+                collection.published,
+            );
+            let _ = keyed.register(with_capacity(descriptor, capacity));
+        }
+    }
+
+    Ok(())
+}
+
+fn keyset_limit(
+    value: Option<f64>,
+    kind: &CollectionKind,
+    index: usize,
+) -> Result<Option<u32>, String> {
+    let Some(value) = value else {
+        return Ok(None);
+    };
+    if !matches!(kind, CollectionKind::Map) {
+        return Err(format!(
+            "state_collections[{index}].keyset_limit: only valid for map collections"
+        ));
+    }
+    whole_number_field(
+        value,
+        &format!("state_collections[{index}].keyset_limit"),
+        0,
+        u32::MAX,
+    )
+    .map(Some)
+}
+
+fn capacity(
+    value: Option<f64>,
+    kind: &CollectionKind,
+    index: usize,
+) -> Result<Option<NonZeroUsize>, String> {
+    let Some(value) = value else {
+        return Ok(None);
+    };
+    if !matches!(kind, CollectionKind::Deque) {
+        return Err(format!(
+            "state_collections[{index}].capacity: only valid for deque collections"
+        ));
+    }
+    let value = whole_number_field(
+        value,
+        &format!("state_collections[{index}].capacity"),
+        1,
+        u32::MAX,
+    )?;
+    Ok(NonZeroUsize::new(value as usize))
+}
+
+/// Builds the `KeyedStateConfiguration` by mapping each declared collection.
+/// The normal Prosody construction path validates the result.
+///
+/// # Errors
+///
+/// Returns an error if a host value cannot be mapped.
+fn build_keyed_state_config(
+    config: &NativeConfiguration,
+) -> Result<KeyedStateConfiguration, String> {
+    let mut builder = KeyedStateConfiguration::builder();
+
+    if let Some(dir) = &config.state_cache_dir {
+        builder.cache_dir(PathBuf::from(dir));
+    }
+
+    if let Some(seconds) = config.state_recovery_delay {
+        let seconds = whole_number_field(seconds, "state_recovery_delay", 0, u32::MAX)?;
+        builder.recovery_delay(CompactDuration::new(seconds));
+    }
+
+    if let Some(size) = &config.state_owned_cache_size {
+        let size = size
+            .parse::<ByteSize>()
+            .map_err(|error| format!("state_owned_cache_size: {error}"))?;
+        builder.owned_cache_size(Some(size));
+    }
+
+    if let Some(size) = &config.state_read_cache_size {
+        let size = size
+            .parse::<ByteSize>()
+            .map_err(|error| format!("state_read_cache_size: {error}"))?;
+        builder.read_cache_size(Some(size));
+    }
+
+    if let Some(cache) = &config.state_read_cache {
+        match cache {
+            ReadCacheConfig::Disabled(false) => {
+                builder.read_cache_ttl(None);
+            }
+            ReadCacheConfig::Disabled(true) => {
+                return Err(
+                    "state_read_cache: true is ambiguous; use a duration or false".to_owned(),
+                );
+            }
+            ReadCacheConfig::Ttl(seconds) => {
+                let ttl = Duration::try_from_secs_f64(*seconds).map_err(|_| {
+                    "state_read_cache: duration must be finite and non-negative".to_owned()
+                })?;
+                builder.read_cache_ttl(Some(ttl));
+            }
+        }
+    }
+
+    if let Some(subsystem) = &config.subsystem {
+        builder.subsystem(Some(
+            SubsystemName::try_new(subsystem).map_err(|error| error.to_string())?,
+        ));
+    }
+
+    let mut keyed = builder.build().map_err(|error| error.to_string())?;
+
+    if let Some(collections) = &config.state_collections {
+        for (index, collection) in collections.iter().enumerate() {
+            register_state_collection(&mut keyed, index, collection)?;
+        }
+    }
+
+    Ok(keyed)
+}
+
 impl<'a> TryFrom<&'a NativeConfiguration> for ConsumerBuilders {
     type Error = String;
 
@@ -795,6 +1242,8 @@ impl<'a> TryFrom<&'a NativeConfiguration> for ConsumerBuilders {
     ///   environment variable contains an unparseable value).
     /// - `message_spans` or `timer_spans` contains an unrecognized value
     ///   (expected `"child"` or `"follows_from"`).
+    /// - The Kafka loader configuration cannot be built (e.g. a tuning value
+    ///   fails validation).
     fn try_from(config: &'a NativeConfiguration) -> Result<Self, Self::Error> {
         let mut consumer: ConsumerConfigurationBuilder = config.into();
 
@@ -812,6 +1261,28 @@ impl<'a> TryFrom<&'a NativeConfiguration> for ConsumerBuilders {
             consumer.timer_spans(relation);
         }
 
+        // Route the shared Kafka message loader settings onto the consumer.
+        if config.loader_cache_size.is_some()
+            || config.loader_seek_timeout.is_some()
+            || config.loader_discard_threshold.is_some()
+        {
+            let mut loader = KafkaLoaderConfiguration::builder();
+
+            if let Some(cache_size) = &config.loader_cache_size {
+                loader.cache_size(*cache_size as usize);
+            }
+
+            if let Some(seek_timeout) = &config.loader_seek_timeout {
+                loader.seek_timeout(Duration::from_secs_f32(*seek_timeout));
+            }
+
+            if let Some(discard_threshold) = &config.loader_discard_threshold {
+                loader.discard_threshold(*discard_threshold);
+            }
+
+            consumer.loader(loader.build().map_err(|e| e.to_string())?);
+        }
+
         Ok(Self {
             consumer,
             retry: config.into(),
@@ -820,8 +1291,10 @@ impl<'a> TryFrom<&'a NativeConfiguration> for ConsumerBuilders {
             monopolization: config.into(),
             defer: config.into(),
             timeout: config.into(),
-            dedup: config.into(),
+            dedup: config.try_into()?,
             emitter: config.try_into()?,
+            keyed_state: build_keyed_state_config(config)?,
+            peer: build_peer_config(config)?,
         })
     }
 }