confluent_kafka/common/local_timeout_error.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//! Translated from `java.util.concurrent.TimeoutException`.
16//!
17//! Not to be confused with `org.apache.kafka.common.errors.TimeoutException`,
18//! which is [`TimeoutError`](crate::common::errors::TimeoutError) โ see the type
19//! docs below for why the two must stay apart.
20
21use crate::common::error::message_only_error;
22
23message_only_error! {
24 /// A wait on a future timed out.
25 ///
26 /// Java's `java.util.concurrent.TimeoutException`, thrown by
27 /// `Future.get(timeout, unit)` โ **not**
28 /// `org.apache.kafka.common.errors.TimeoutException`, which is a
29 /// `RetriableException` under `KafkaException` and is spelled
30 /// [`Error::timeout`](crate::common::Error::timeout). The two are unrelated
31 /// classes that share a simple name; conflating them makes a local await
32 /// timeout answer `true` to `is_retriable_error()` / `is_api_error()` /
33 /// `is_kafka_error()` and report a wire code, none of which Java does. A
34 /// plain checked `java.util` class outside the Kafka hierarchy, so no
35 /// predicate holds.
36 ///
37 /// The `Local` prefix marks this as a JDK class rather than a Kafka one โ
38 /// every `java.*` error carries it, independently of the subpackage. That is what separates this from
39 /// [`Error::Timeout`](crate::common::Error::Timeout): Java tells the two
40 /// `TimeoutException`s apart by package, and a flat enum cannot, so the
41 /// prefix carries what the package used to. It also says something the
42 /// package name would not: these errors are raised *here*, never reported by
43 /// a broker, which is why none of them has a wire code.
44 // translates java.util.concurrent.TimeoutException, a JDK exception (CLAUDE.md ยง2)
45 #[doc(alias = "rust-only")]
46 LocalTimeoutError
47}