Skip to main content

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}