confluent_kafka/producer/partitioner.rs
1// Copyright 2025 Confluent Inc.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! Pluggable partitioner interface.
16//!
17//! Translated from `org.apache.kafka.clients.producer.Partitioner`
18//! (`interface Partitioner extends Configurable, Closeable`).
19
20use std::collections::HashMap;
21
22use crate::common::Cluster;
23
24/// Partitioner Interface
25///
26/// # Translation notes
27///
28/// WARNING: `Monitorable` is not translated, so a partitioner cannot register
29/// metrics.
30///
31/// `partition` and `close` take `&self`: the producer shares one instance
32/// across tasks, as Java's shares it across threads.
33//
34// Java's interface `extends Configurable, Closeable` and takes `Object key` /
35// `Object value`. Rust has neither `Configurable` nor `Closeable`, and the
36// producer is generic rather than erased, so the shape differs deliberately
37// (justified deviations, Definition of Done ยง7):
38//
39// - `K, V` generics translate Java's `Object key` / `Object value`: the
40// partitioner receives typed borrows instead of `Object`, no downcasts.
41// - `Send + Sync` supertraits: the producer is shared across tasks, so the
42// boxed partitioner it owns must be shareable.
43// - `partition(&self)`, not `&mut self`: Java's `KafkaProducer` calls the one
44// shared partitioner concurrently, so Java implementations are already
45// internally synchronized (`RoundRobinPartitioner` uses a `ConcurrentMap` +
46// `AtomicInteger`). `&self` keeps the send path lock-free; per-record state
47// is the implementer's job via interior mutability, as in Java.
48// - `close(&self)`, not `&mut self`: `Producer::close` takes `&self`, and a
49// `Mutex` to obtain `&mut` would add a lock to every send.
50// - `configure(&mut self)` with a default no-op mirrors
51// `ConsumerInterceptor::configure` and is called exactly once, before the
52// instance is boxed and shared with the producer.
53// - Java's `Plugin<Partitioner>` / `Monitorable` metrics wrapper has no Rust
54// counterpart.
55#[doc(alias = "org.apache.kafka.clients.producer.Partitioner")]
56pub trait Partitioner<K, V>: Send + Sync {
57 /// Configure this class with the given key-value pairs
58 ///
59 /// # Arguments
60 ///
61 /// - `_configs` - the pairs
62 // Java's `Configurable.configure(Map<String, ?> configs)`. Called once,
63 // before the instance is shared with the producer, with the producer's
64 // original configuration plus the (possibly generated) `client.id`. The
65 // default implementation is a no-op.
66 #[doc(alias = "org.apache.kafka.common.Configurable#configure")]
67 fn configure(&mut self, _configs: &HashMap<String, String>) {}
68
69 /// Compute the partition for the given record.
70 ///
71 /// # Arguments
72 ///
73 /// - `topic` - The topic name
74 /// - `key` - The key to partition on (or None if no key)
75 /// - `key_bytes` - The serialized key to partition on( or None if no key)
76 /// - `value` - The value to partition on or None
77 /// - `value_bytes` - The serialized value to partition on or None
78 /// - `cluster` - The current cluster metadata
79 ///
80 /// # Returns
81 ///
82 /// The partition, non-negative: the send fails on a negative one.
83 ///
84 /// # Translation notes
85 ///
86 /// WARNING: `key` and `value` are `None` on the borrowed send path of
87 /// `KafkaProducer<Vec<u8>, Vec<u8>>`.
88 // On the borrowed zero-copy send path
89 // (`KafkaProducer<Vec<u8>, Vec<u8>>::send(ProducerRecord<&[u8], &[u8]>)`)
90 // Java's `record.key()` is the same `byte[]` as `keyBytes`; materializing a
91 // typed `&Vec<u8>` from the borrowed bytes would allocate, violating the
92 // zero-copy contract. Partitioners that need the key/value read the
93 // `*_bytes` parameters, which are always supplied when a key/value exists.
94 #[doc(alias = "org.apache.kafka.clients.producer.Partitioner#partition")]
95 fn partition(
96 &self,
97 topic: &str,
98 key: Option<&K>,
99 key_bytes: Option<&[u8]>,
100 value: Option<&V>,
101 value_bytes: Option<&[u8]>,
102 cluster: &Cluster,
103 ) -> i32;
104
105 /// This is called when partitioner is closed.
106 // Java's `Closeable.close()`. The default implementation is a no-op.
107 #[doc(alias = "org.apache.kafka.clients.producer.Partitioner#close")]
108 fn close(&self) {}
109}