prosody 0.5.1 → 0.6.1

data/Cargo.toml

@@ -10,23 +10,22 @@ resolver = "2"
 atomic-take = "1.1"
 bumpalo = "3.20"
 crossbeam-channel = "0.5"
-educe = "0.7"
+educe = "0.8"
 futures = "0.3"
-magnus = { version = "0.8", default-features = false }
-# TODO: Use a crates.io release after it includes the fix for https://github.com/microsoft/mimalloc/issues/1287.
-mimalloc = { git = "https://github.com/xonatius/mimalloc_rust.git", rev = "6d4c41bb10c6d9da1d1b6f07b38c4cc051667f11" }
-opentelemetry = "0.32"
-prosody = { version = "0.6.0", features = ["libz-static"] }
+magnus = { version = "0.9", default-features = false }
+opentelemetry = "0.33"
+prosody = { version = "0.7.0", features = ["libz-static"] }
 rb-sys = "0.9"
+rustfs-mimalloc = "0.5.6"
 serde = "1.0"
 serde-untagged = "0.1"
 serde_json = "1.0"
 serde_magnus = "0.11"
 thiserror = "2.0"
-tokio = "1.52"
+tokio = "1.53"
 tokio-stream = "0.1"
 tracing = "0.1"
-tracing-opentelemetry = "0.33"
+tracing-opentelemetry = "0.34"
 tracing-subscriber = "0.3"
 
 [profile.release]
@@ -78,3 +77,7 @@ unneeded_field_pattern = "warn"
 unreachable = "warn"
 unwrap_used = "deny"
 verbose_file_reads = "warn"
+
+[patch.crates-io]
+# TODO: Use a crates.io release after serde_magnus supports magnus 0.9.
+serde_magnus = { git = "https://github.com/hadronzoo/serde-magnus", rev = "27aee737829a6bca399289b6e64ce4bcc08bfd94" }

data/README.md

@@ -277,10 +277,10 @@ You can monitor the stall state programmatically using the client's methods:
 
 ```ruby
 # Get the number of partitions currently assigned to this consumer
-partition_count = client.assigned_partitions
+partition_count = client.assigned_partition_count
 
 # Check if the consumer has stalled partitions
-if client.is_stalled?
+if client.stalled?
   warn 'Consumer has stalled partitions'
 end
 ```
@@ -299,7 +299,7 @@ Send a request from a handler or other application code. The Prosody client does
 
 Do not rely on hash order. The hash contains one entry for each selected subsystem. A missing response becomes a timeout `Failure`; Prosody does not omit the subsystem. The request raises an error for request-level failures, such as invalid input, a Kafka send failure, or shutdown. Do not wait for a request if the current consumer group must process it for the same key. That group cannot process it until the handler returns.
 
-Message and excise handler return values become successful outcomes. Each return value must have a JSON representation.
+Message and excise handler return values become successful outcomes. Each return value must have a JSON representation. A return value without one is a transient handler error, so Prosody retries the message.
 
 Set `subsystem` to `inventory` on the client that subscribes this handler.
 
@@ -457,8 +457,10 @@ This prevents endless loops where a service consumes its own produced messages.
 
 ## Message Deduplication
 
-Prosody automatically deduplicates messages using the `id` field in their JSON payload. Consecutive messages with the
-same ID and key are processed only once.
+Prosody uses the JSON payload's `id` field to detect duplicate messages. For a consumer group and idempotence version,
+messages with the same ID, key, topic, and partition share a deduplication record. Other messages can arrive between duplicates.
+Prosody skips a duplicate while its record remains in the cache or persistent store. Deduplication is best-effort;
+handlers must remain idempotent.
 
 The deduplication system uses:
 - A **global in-memory cache** shared across all partitions, surviving partition reassignments within a process
@@ -626,12 +628,53 @@ State operations look synchronous. They yield the current fiber while Prosody pe
 | Collection | JSON payload | Kafka message | Main operations |
 | --- | --- | --- | --- |
 | Value | `Prosody.value` | `Prosody.message_value` | `get`, `set`, `clear` |
-| Ordered string map | `Prosody.map` | `Prosody.message_map` | `get`, `get_many`, `key?`, `set`, `delete`, `each_pair`, `each_key`, `clear` |
+| Ordered string map | `Prosody.map` | `Prosody.message_map` | `get`, `get_many`, `key?`, `contains_many`, `empty?`, `set`, `delete`, `each_pair`, `each_key`, `clear` |
+| Ordered string set | `Prosody.set` | - | `add` / `<<`, `delete`, `include?`, `contains_many`, `empty?`, `each`, `clear` |
 | Deque | `Prosody.deque` | `Prosody.message_deque` | `push`, `unshift`, `pop`, `shift`, `get`, `length`, `each`, `clear` |
 
-Map and deque scans return enumerators when called without a block. Map keys are strings.
+Map, set, and deque scans return enumerators when called without a block. Map keys and set members are strings. A set stores membership only, so it has no payload type.
 
-`nil` means absence. Do not store this value. Use `clear` or `delete`.
+A value, map, or deque read returns `nil` when no value is present. Do not store `nil` as a value. A `nil` write fails with a `PermanentStateError`. Use `clear` (value, deque) or `delete` (map) to remove a value.
+
+A set handle mirrors Ruby's `Set`:
+
+```ruby
+SEEN_ORDERS = Prosody.set("seen-orders", ttl: 7 * 24 * 60 * 60)
+
+def on_message(context, message)
+  seen = context.state(SEEN_ORDERS)
+  return if seen.include?(message.payload["order_id"])
+
+  seen << message.payload["order_id"]
+  fulfill(message)
+end
+```
+
+### Query keywords
+
+Every traversal method accepts optional query keywords. Prosody applies them in storage, so a query reads only the selected entries. The `each` and `each_*` methods iterate forward. The `reverse_each` and `reverse_each_*` methods iterate backward.
+
+| Keyword | Selects |
+| --- | --- |
+| `from:` / `after:` | Starts at the key or position, or just after it, in iteration order |
+| `to:` / `before:` | Stops at the key or position, or just before it, in iteration order |
+| `range:` | Keeps keys or positions in a Ruby `Range`: `"a".."m"`, `"a"..."m"`, `.."m"`, or `"a"..`. Write the range in ascending order; it applies in both directions. A descending range is empty |
+| `prefix:` | Keeps map keys or set members that start with the string |
+| `limit:` | Stops after this many items; a positive `Integer` |
+
+A reverse traversal starts at the high end. Keywords narrow the selection and never widen it. Pass at most one of `from:` and `after:`, and at most one of `to:` and `before:`. Set traversals select members. Deque positions count from the front and must be non-negative. To read the last N items, use `reverse_each(limit: N)`. Deques have no `prefix:`. A bad keyword raises `ArgumentError` or `TypeError`.
+
+To read a map in pages, pass the last key of the previous page as `after:`:
+
+```ruby
+page = map.each_pair(prefix: "order:", limit: 100).to_a
+until page.empty?
+  page.each { |key, order| archive(key, order) }
+  page = map.each_pair(prefix: "order:", after: page.last.first, limit: 100).to_a
+end
+```
+
+The same pattern works backward with `reverse_each_pair`.
 
 ### When keyed-state changes become visible
 
@@ -643,6 +686,8 @@ This transaction applies only to keyed state. Some workflows need state changes
 - `commit` commits the collection's pending changes before the handler ends. A later handler failure does not remove them.
 - `rollback` discards pending changes since the last `commit`. It cannot undo committed changes.
 
+`commit` and `rollback` return `:applied` when they wrote or discarded pending changes. They return `:no_op` when the collection had no pending changes.
+
 ### Published state
 
 Some callers need only the current value for a key. They can accept a stale value or a race with a concurrent update.
@@ -665,7 +710,7 @@ current_order = context.state(CURRENT_ORDER)
 current_order.set({"sku" => "book"})
 ```
 
-Read published state from a handler or other application code. The Prosody client does not need an active subscription.
+Read published state from a handler or other application code. The Prosody client does not need an active subscription. A client that only reads published state needs no `subscribed_topics`.
 
 Use the subsystem and the same definition to open a reader:
 
@@ -674,9 +719,9 @@ order_reader = client.state("checkout", CURRENT_ORDER)
 current_order = order_reader.get("customer-123")
 ```
 
-The reader cannot see pending changes that exist only in a handler. It cannot change the collection. Each read takes an explicit key because no handler supplies one.
+The reader cannot see pending changes that exist only in a handler. It cannot change the collection. Each read takes an explicit String key because no handler supplies one.
 
-Map and deque readers fetch data in chunks. They do not load the complete collection before iteration starts. Readers return an `Enumerator` without a block.
+Map, set, and deque readers fetch data in chunks. They do not load the complete collection before iteration starts. Readers return an `Enumerator` without a block. Reader traversals accept the same [query keywords](#query-keywords) after the key. A failed read raises `Prosody::TransientStateError` or `Prosody::PermanentStateError`, as an owned handle does, for point reads and traversals alike. A reader that Prosody cannot open, such as one with a zero `read_cache`, raises the same classes.
 
 Use `reverse_each_pair`, `reverse_each_key`, `reverse_each_value`, or `reverse_each` for reverse traversal.
 
@@ -783,9 +828,9 @@ all traces to Ruby.
 To use OpenTelemetry tracing with Prosody, you need to install the following gems:
 
 ```ruby
-gem 'opentelemetry-sdk', '~> 1.10'
-gem 'opentelemetry-api', '~> 1.7'
-gem 'opentelemetry-exporter-otlp', '~> 0.31'
+gem 'opentelemetry-sdk', '~> 1.13'
+gem 'opentelemetry-api', '~> 1.10'
+gem 'opentelemetry-exporter-otlp', '~> 0.36'
 ```
 
 ### Initializing Tracing
@@ -907,6 +952,16 @@ Call `shutdown` when the application terminates. It stops all client services an
 client.shutdown
 ```
 
+To scope a client to a block, use `Prosody::Client.open`. It yields the client and calls `shutdown` when the block exits, also when the block raises. It returns the value of the block.
+
+```ruby
+Prosody::Client.open(bootstrap_servers: "localhost:9092") do |client|
+  client.send_message("my-topic", "key", {"hello" => "world"})
+end
+```
+
+Repeated `shutdown` calls wait for the same operation, so the block can also call `shutdown`.
+
 Handle application shutdown with signal handlers:
 
 ```ruby
@@ -972,6 +1027,18 @@ Best practices:
 - Be cautious with permanent errors as they prevent retries and can result in data loss.
 - Consider system reliability and data consistency when classifying errors.
 
+A handler can tell a retry from a normal delivery through `context.demand`:
+
+```ruby
+def on_message(context, message)
+  demand = context.demand
+  logger.warn("retry #{demand.retries} for #{message.key}") if demand.failure?
+  process(message)
+end
+```
+
+`demand.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 you need one.
+
 ### Handling Task Cancellation
 
 Prosody cancels tasks during partition rebalancing, timeout, or shutdown. During shutdown, handlers run freely for most of the `shutdown_timeout` before the cancellation signal fires—giving in-flight work time to complete. When cancelled, your handler receives `Async::Stop` at the next yield point (I/O operation, sleep, etc.).
@@ -1064,23 +1131,24 @@ Ensure you have thoroughly tested your changes before merging to `main`.
 ### Prosody::Client
 
 - `new(config)` or `new(**options)`: Create a client from a `Configuration`, hash, or keyword options.
+- `open(config) { |client| ... }`: Create a client, yield it, and shut it down when the block exits. It returns the value of the block.
 - `send_message(String topic, String key, Prosody::json_value payload)`: Send a JSON-serializable message.
 - `excise(String topic, String key)`: Send an excise record for a key.
 - `request(topic:, key:, payload:, subsystems:, timeout:)`: Return one outcome for each subsystem.
 - `request_excise(topic:, key:, subsystems:, timeout:)`: Return one excise outcome for each subsystem.
 - `consumer_state`: Get the client state (`:shut_down`, `:unconfigured`, `:configured`, or `:running`).
 - `source_system`: Get the source system identifier configured for the client.
-- `state(subsystem, definition)`: Open a typed, read-only published value, map, or deque.
+- `state(subsystem, definition)`: Open a typed, read-only published value, map, set, or deque.
 - `subscribe(handler)`: Start event processing with the specified handler.
 - `unsubscribe`: Stop the consumer. You can subscribe again later.
 - `shutdown`: Stop all client services. Concurrent and repeated calls wait for the same operation.
-- `assigned_partitions`: Get the number of partitions currently assigned to this consumer.
-- `is_stalled?`: Check if the consumer has stalled partitions.
+- `assigned_partition_count`: Get the number of partitions currently assigned to this consumer.
+- `stalled?`: Check if the consumer has stalled partitions.
 
 ### Prosody::AdminClient
 
 - `new(bootstrap_servers)`: Create an admin client for the specified Kafka servers.
-- `create_topic(name, partitions, replication_factor)`: Create a Kafka topic.
+- `create_topic(name, partitions, replication_factor, cleanup_policy: nil, retention: nil)`: Create a Kafka topic. `cleanup_policy` is a Kafka cleanup policy such as `"delete"`, `"compact"`, or `"delete,compact"`. `retention` is the message retention in seconds. A `nil` keyword uses the cluster default.
 - `delete_topic(name)`: Delete a Kafka topic.
 
 ### Prosody::EventHandler
@@ -1144,10 +1212,12 @@ Messages have the following attributes:
 - `timestamp` (Time): The timestamp when the message was created or sent.
 - `key` (String): The message key.
 - `payload` (`Payload`): The JSON-deserialized message payload.
+- `source_system` (String or nil): The source system of the producer that sent the message, or `nil` when the message has none.
+- `response_requested?` (Boolean): Whether the producer requested a response. When it is false, Prosody discards the handler result, so a handler can skip work that only builds the response.
 
 ### Prosody::ExciseMessage
 
-An `ExciseMessage` has `topic`, `partition`, `offset`, `timestamp`, and `key` attributes. It has no `payload` attribute.
+An `ExciseMessage` has `topic`, `partition`, `offset`, `timestamp`, `key`, `source_system`, and `response_requested?` attributes. It has no `payload` attribute.
 
 ### Prosody::Context
 
@@ -1155,7 +1225,8 @@ Represents the current event context:
 
 - `should_cancel?`: Check if cancellation has been requested (includes timeout and shutdown).
 - `on_cancel`: Wait until cancellation occurs.
-- `state(definition)`: Bind a registered collection for the current attempt. An unregistered or mismatched definition raises `PermanentStateError`. See [Keyed State](#keyed-state-2).
+- `demand`: A `Prosody::Demand` that tells whether this call is a normal delivery or a retry. `kind` is `:normal` or `:failure`, and `normal?` and `failure?` test it. `retries` is the number of retries: 0 for a normal delivery and 1 on the first retry. The count is an estimate. Keep an exact attempt count in keyed state if you need one.
+- `state(definition)`: Bind a registered collection for the current attempt. An unregistered or mismatched definition raises `PermanentStateError`. See [Keyed State](#keyed-state).
 
 Timer scheduling methods:
 
@@ -1186,6 +1257,7 @@ Definition constructors (each returns a frozen definition object used both in `C
 
 - `Prosody.value(name, ttl: nil, read_uncommitted: nil, published: nil, read_cache: nil)`
 - `Prosody.map(name, ttl: nil, keyset_limit: nil, read_uncommitted: nil, published: nil, read_cache: nil)`
+- `Prosody.set(name, ttl: nil, keyset_limit: nil, read_uncommitted: nil, published: nil, read_cache: nil)`
 - `Prosody.deque(name, ttl: nil, capacity: nil, read_uncommitted: nil, published: nil, read_cache: nil)`
 - `Prosody.message_value(name, ttl: nil, read_uncommitted: nil)`
 - `Prosody.message_map(name, ttl: nil, keyset_limit: nil, read_uncommitted: nil)`
@@ -1195,13 +1267,15 @@ Each constructor returns a `StateDefinition`. It exposes `name`, `kind`, `payloa
 
 Published readers take the user key as their first argument. `Prosody::PublishedValue` provides `get`.
 
-`Prosody::PublishedMap` provides `get`, `get_many`, `key?`, `has_key?`, `include?`, and `member?`.
+`Prosody::PublishedMap` provides `get`, `get_many`, `key?`, `has_key?`, `include?`, `member?`, `contains_many`, and `empty?`.
 
 It provides `each` or `each_pair`, `each_key`, and `each_value`. The reverse methods are `reverse_each_pair`, `reverse_each_key`, and `reverse_each_value`.
 
+`Prosody::PublishedSet` provides `include?` or `member?`, `contains_many`, `empty?`, `each`, and `reverse_each`.
+
 `Prosody::PublishedDeque` provides `get`, `length` or `size`, `empty?`, `first`, `last`, `each`, and `reverse_each`.
 
-Traversal methods return an `Enumerator` without a block.
+Traversal methods return an `Enumerator` without a block. Every traversal accepts the optional [query keywords](#query-keywords) `from:`, `after:`, `to:`, `before:`, `range:`, and `limit:`. Map and set traversals also accept `prefix:`.
 
 `Prosody::ValueState`:
 
@@ -1210,10 +1284,16 @@ Traversal methods return an `Enumerator` without a block.
 `Prosody::MapState` (keys are `String`):
 
 - `get` / `[]`, `get_many`, `set` / `[]=`, `store`, `delete`, and `clear`
-- `key?`, `has_key?`, `include?`, `member?`, `dig`, `slice`, `values_at`, `fetch`, and `fetch_values`
+- `key?`, `has_key?`, `include?`, `member?`, `contains_many`, `empty?`, `dig`, `slice`, `values_at`, `fetch`, and `fetch_values`
 - `each` / `each_pair`, `each_key`, and `each_value`, including each reverse form
 - `commit` and `rollback`
 
+`Prosody::SetState` (members are `String`):
+
+- `add` / `<<`, `delete`, and `clear`, which return the set
+- `include?` / `member?`, `contains_many`, and `empty?`
+- `each` / `reverse_each`, `commit`, and `rollback`
+
 `Prosody::DequeState`:
 
 - `push`, `append`, `<<`, `unshift`, `prepend`, `pop`, and `shift`
@@ -1223,8 +1303,7 @@ Traversal methods return an `Enumerator` without a block.
 Errors:
 
 - `Prosody::TransientStateError < Prosody::TransientError`: Reports a keyed-state error that Prosody can retry.
-- `Prosody::PermanentStateError < Prosody::PermanentError`: Reports a keyed-state error that another attempt cannot resolve.
-- `Prosody::NullValueError < Prosody::TransientStateError`: raised when a `nil` is written; use `clear`/`delete` instead.
+- `Prosody::PermanentStateError < Prosody::PermanentError`: Reports a keyed-state error that another attempt cannot resolve, such as a `nil` write.
 
 Handler error types:
 

data/examples/keyed_state.rb

@@ -3,7 +3,7 @@
 require "prosody"
 require "logger"
 
-# Keyed-state example: per-key value/map/deque collections that survive across
+# Keyed-state example: per-key value/map/set/deque collections that survive across
 # events. Definitions are declared once and reused for both registration (on the
 # client) and binding (inside the handler). Every state op yields the fiber,
 # never the thread.
@@ -12,6 +12,7 @@ require "logger"
 # keyed_state.rbs for payload and state types checked by Steep.
 CART = Prosody.value("cart", ttl: 30 * 24 * 3600)      # ValueState
 TOTALS = Prosody.map("totals")                          # keys are always String
+SEEN = Prosody.set("seen", ttl: 7 * 24 * 3600)          # String members, no payload
 BACKLOG = Prosody.message_deque("backlog", capacity: 100) # bounded window of messages
 
 class KeyedStateHandler < Prosody::EventHandler
@@ -19,6 +20,7 @@ class KeyedStateHandler < Prosody::EventHandler
     puts "Excise #{message.key}"
     context.state(CART).clear
     context.state(TOTALS).clear
+    context.state(SEEN).clear
     context.state(BACKLOG).clear
     nil
   end
@@ -29,6 +31,10 @@ class KeyedStateHandler < Prosody::EventHandler
 
   def on_message(context, message)
     payload = message.payload
+    seen = context.state(SEEN)
+    return if seen.include?(payload["order_id"]) # skip an order seen before
+    seen << payload["order_id"]
+
     cart = context.state(CART)             # bound for this attempt only
     current = cart.get || {"items" => []}  # Hash, or nil when absent
     cart.set(current.merge("items" => current["items"] + [payload["order_id"]]))
@@ -37,6 +43,8 @@ class KeyedStateHandler < Prosody::EventHandler
     totals.set(message.key, payload["total"])
     # Steep infers key as String and total as Integer from TOTALS's RBS type.
     totals.each_pair { |key, total| @logger.info(format_total(key, total)) }
+    # Query keywords narrow a traversal: here, the first ten keys after this one.
+    totals.each_key(after: message.key, limit: 10) { |key| @logger.info("next key: #{key}") }
 
     backlog = context.state(BACKLOG)
     backlog.push(message)                  # stores the full Prosody::Message
@@ -63,7 +71,7 @@ if __FILE__ == $PROGRAM_NAME
     mock: true,
     group_id: "keyed-state-example",
     subscribed_topics: "orders",
-    state_collections: [CART, TOTALS, BACKLOG]
+    state_collections: [CART, TOTALS, SEEN, BACKLOG]
   )
   client.subscribe(KeyedStateHandler.new(logger: Logger.new($stdout)))
   client.shutdown

data/examples/keyed_state.rbs

@@ -3,6 +3,7 @@ type keyed_state_order_event = { "order_id" => String, "total" => Integer }
 
 CART: Prosody::_ValueDefinition[keyed_state_cart]
 TOTALS: Prosody::_MapDefinition[Integer]
+SEEN: Prosody::_SetDefinition
 BACKLOG: Prosody::_MessageDequeDefinition[keyed_state_order_event]
 
 class KeyedStateHandler < Prosody::EventHandler[keyed_state_order_event]

data/ext/prosody/Cargo.toml

@@ -6,6 +6,7 @@ publish = false
 version = "0.1.0"
 
 [lib]
+# cdylib only: the extension has no Rust doctests; the RSpec suite covers it.
 crate-type = ["cdylib"]
 
 [dependencies]
@@ -15,10 +16,10 @@ crossbeam-channel.workspace = true
 educe.workspace = true
 futures.workspace = true
 magnus = { workspace = true, default-features = false }
-mimalloc = { workspace = true, features = ["local_dynamic_tls"] }
 opentelemetry.workspace = true
 prosody = { workspace = true }
 rb-sys.workspace = true
+rustfs-mimalloc = { workspace = true, features = ["local_dynamic_tls"] }
 serde = { workspace = true, features = ["derive"] }
 serde-untagged.workspace = true
 serde_json.workspace = true

data/ext/prosody/src/admin.rs

@@ -4,9 +4,10 @@
 //! This module implements Ruby bindings for creating and deleting Kafka topics.
 
 use crate::bridge::Bridge;
-use crate::util::ensure_runtime_context;
+use crate::util::{ForkGuard, ensure_runtime_context, seconds};
 use crate::{ROOT_MOD, id};
-use magnus::{Error, Module, Object, Ruby, function, method};
+use magnus::scan_args::{get_kwargs, scan_args};
+use magnus::{Error, Module, Object, RHash, Ruby, Value, function, method};
 use prosody::admin::{AdminConfiguration, ProsodyAdminClient, TopicConfiguration};
 use std::sync::Arc;
 use tracing::Span;
@@ -22,8 +23,8 @@ pub struct AdminClient {
     client: Arc<ProsodyAdminClient>,
     /// Bridge for executing asynchronous operations from Ruby
     bridge: Bridge,
-    /// PID at construction time, used to detect post-fork usage
-    pid: u32,
+    /// Refuses use in a forked child process
+    fork: ForkGuard,
 }
 
 impl AdminClient {
@@ -39,7 +40,6 @@ impl AdminClient {
     /// Returns a `Magnus::Error` if:
     /// - The client cannot be created with the provided bootstrap servers
     /// - The bridge is not initialized
-    #[allow(clippy::needless_pass_by_value)]
     pub fn new(ruby: &Ruby, bootstrap_servers: Vec<String>) -> Result<Self, Error> {
         let _guard = ensure_runtime_context(ruby);
         let admin_config = AdminConfiguration::new(bootstrap_servers)
@@ -61,48 +61,48 @@ impl AdminClient {
         Ok(Self {
             client,
             bridge,
-            pid: std::process::id(),
+            fork: ForkGuard::new("Prosody::AdminClient"),
         })
     }
 
-    fn check_fork(ruby: &Ruby, this: &Self) -> Result<(), Error> {
-        if std::process::id() != this.pid {
-            return Err(Error::new(
-                ruby.exception_runtime_error(),
-                "Prosody::AdminClient cannot be used after fork. Create a new client in the child \
-                 process.",
-            ));
-        }
-        Ok(())
-    }
-
     /// Creates a new Kafka topic.
     ///
-    /// # Arguments
-    ///
-    /// * `ruby` - Reference to the Ruby VM
-    /// * `this` - The admin client instance
-    /// * `name` - Name of the topic to create
-    /// * `partition_count` - Number of partitions for the topic
-    /// * `replication_factor` - Replication factor for the topic
+    /// Ruby calls it as `create_topic(name, partition_count,
+    /// replication_factor, cleanup_policy: nil, retention: nil)`. A `nil`
+    /// keyword uses the cluster default. `retention` is in seconds.
     ///
     /// # Errors
     ///
     /// Returns a `Magnus::Error` if:
+    /// - An argument has the wrong type, or `retention` has no `Duration` form
     /// - The topic creation fails
     /// - There's an issue with the asynchronous execution
-    pub fn create_topic(
-        ruby: &Ruby,
-        this: &Self,
-        name: String,
-        partition_count: u16,
-        replication_factor: u16,
-    ) -> Result<(), Error> {
-        Self::check_fork(ruby, this)?;
-        let topic_config = TopicConfiguration::builder()
+    pub fn create_topic(ruby: &Ruby, this: &Self, args: &[Value]) -> Result<(), Error> {
+        this.fork.check(ruby)?;
+        let args = scan_args::<(String, u16, u16), (), (), (), RHash, ()>(args)?;
+        let (name, partition_count, replication_factor) = args.required;
+        let keywords = get_kwargs::<_, (), (Option<Option<String>>, Option<Option<f64>>), ()>(
+            args.keywords,
+            &[],
+            &["cleanup_policy", "retention"],
+        )?;
+        let (cleanup_policy, retention) = keywords.optional;
+
+        let mut builder = TopicConfiguration::builder();
+        builder
             .name(name)
             .partition_count(partition_count)
-            .replication_factor(replication_factor)
+            .replication_factor(replication_factor);
+        if let Some(cleanup_policy) = cleanup_policy.flatten() {
+            builder.cleanup_policy(cleanup_policy);
+        }
+        if let Some(retention) = retention.flatten() {
+            builder.retention(
+                seconds("retention", retention)
+                    .map_err(|error| Error::new(ruby.exception_arg_error(), error))?,
+            );
+        }
+        let topic_config = builder
             .build()
             .map_err(|error| Error::new(ruby.exception_runtime_error(), error.to_string()))?;
 
@@ -128,7 +128,7 @@ impl AdminClient {
     /// - The topic deletion fails
     /// - There's an issue with the asynchronous execution
     pub fn delete_topic(ruby: &Ruby, this: &Self, name: String) -> Result<(), Error> {
-        Self::check_fork(ruby, this)?;
+        this.fork.check(ruby)?;
         let client = this.client.clone();
         let future = async move { client.delete_topic(&name).await };
 
@@ -156,7 +156,7 @@ pub fn init(ruby: &Ruby) -> Result<(), Error> {
     class.define_singleton_method("new", function!(AdminClient::new, 1))?;
     class.define_method(
         id!(ruby, "create_topic"),
-        method!(AdminClient::create_topic, 3),
+        method!(AdminClient::create_topic, -1),
     )?;
     class.define_method(
         id!(ruby, "delete_topic"),

data/ext/prosody/src/bridge/mod.rs

@@ -24,18 +24,13 @@ mod callback;
 /// Maximum number of commands to process in a single poll operation.
 const POLL_BATCH_SIZE: usize = 16;
 
-/// Lazily initialized reference to Ruby's Thread class.
-#[allow(clippy::expect_used)]
-pub static THREAD_CLASS: Lazy<RClass> = Lazy::new(|ruby| {
-    ruby.class_object()
-        .const_get(id!(ruby, "Thread"))
-        .expect("Failed to load Thread class")
-});
-
 /// Lazily initialized reference to Ruby's `Thread::Queue` class.
-#[allow(clippy::expect_used)]
+#[expect(
+    clippy::expect_used,
+    reason = "magnus Lazy takes an infallible initializer"
+)]
 pub static QUEUE_CLASS: Lazy<RClass> = Lazy::new(|ruby| {
-    ruby.get_inner(&THREAD_CLASS)
+    ruby.class_thread()
         .const_get(id!(ruby, "Queue"))
         .expect("Failed to load Queue class")
 });