Skip to main content

krabka_client_core/
connection.rs

1//! Single-broker `Connection`.
2//!
3//! A `Connection` holds a TCP socket, reader and writer tasks, and
4//! correlation-ID multiplexing.
5
6use std::{
7    future::Future,
8    net::SocketAddr,
9    sync::{
10        Arc,
11        atomic::{AtomicI32, AtomicU64, Ordering},
12    },
13};
14
15use bytes::{BufMut, Bytes, BytesMut};
16use dashmap::DashMap;
17use krabka_ids::{ApiKey, ApiVersion};
18use krabka_protocol::owned::{api_versions_request, api_versions_response};
19use krabka_units::{
20    ByteSize, Time,
21    convert::{ByteSizeExt as _, TimeExt as _},
22    kibibytes, mebibytes, millis, minutes, secs,
23};
24use refined_type::rule::{GreaterI64, GreaterUsize};
25use tokio::{
26    io::{AsyncRead, AsyncWrite},
27    net::TcpStream,
28    sync::{mpsc, oneshot},
29    task::JoinHandle,
30};
31use tokio_util::sync::CancellationToken;
32
33#[cfg(test)]
34use crate::mock;
35use crate::{
36    error::ClientError,
37    framing, reauth,
38    request::ProtocolRequest,
39    sasl, security, telemetry,
40    transport::{SocketOptions, dial_address},
41    version::ApiVersionTable,
42};
43
44/// Trait alias for the duplex stream types `Connection::from_stream` accepts,
45/// such as `TcpStream` and `tokio_rustls::client::TlsStream`.
46///
47/// The trait is boxed so callers can hand in different stream types through
48/// one path.
49pub trait ClientDuplex: AsyncRead + AsyncWrite + Send + Unpin {}
50impl<T: AsyncRead + AsyncWrite + Send + Unpin + ?Sized> ClientDuplex for T {}
51
52type Pending = Arc<DashMap<i32, oneshot::Sender<Result<Bytes, ClientError>>>>;
53
54/// Kafka API key for `ApiVersionsRequest` / `ApiVersionsResponse`.
55///
56/// `Connection` uses this key to apply the response-header quirk:
57/// `ApiVersionsResponse` always uses `ResponseHeader v0` (no tagged-fields
58/// byte) even when the request version is flexible (v3+).
59const API_VERSIONS_KEY: i16 = 18;
60
61/// Default deadline for one client DNS lookup.
62pub const DEFAULT_CLIENT_DNS_TIMEOUT: Time = secs(10);
63/// Kafka's `socket.connection.setup.timeout.ms` default: the TCP connect
64/// deadline of the first attempt to a broker.
65pub const DEFAULT_SOCKET_CONNECTION_SETUP_TIMEOUT: Time = secs(10);
66/// Kafka's `socket.connection.setup.timeout.max.ms` default: the connect
67/// deadline grows exponentially per failed attempt up to this value.
68pub const DEFAULT_SOCKET_CONNECTION_SETUP_TIMEOUT_MAX: Time = secs(30);
69/// Kafka's `reconnect.backoff.ms` default.
70pub const DEFAULT_RECONNECT_BACKOFF: Time = millis(50);
71/// Kafka's `reconnect.backoff.max.ms` default.
72pub const DEFAULT_RECONNECT_BACKOFF_MAX: Time = secs(1);
73/// Kafka's producer and consumer `connections.max.idle.ms` default (9
74/// minutes, below the broker's 10 minutes).
75pub const DEFAULT_CONNECTIONS_MAX_IDLE: Time = minutes(9);
76/// Kafka's producer, consumer and admin `send.buffer.bytes` default.
77pub const DEFAULT_SEND_BUFFER: ByteSize = kibibytes(128);
78/// Kafka's consumer and admin `receive.buffer.bytes` default. The producer
79/// default is 32 KiB.
80pub const DEFAULT_RECEIVE_BUFFER: ByteSize = kibibytes(64);
81/// Default deadline for one client request.
82pub const DEFAULT_CLIENT_REQUEST_TIMEOUT: Time = secs(30);
83/// Default capacity of one connection's pending request dispatch queue.
84pub const DEFAULT_CONNECTION_DISPATCH_QUEUE_CAPACITY: usize = 64;
85/// Fixed security ceiling for accepted client frames.
86pub const MAX_CLIENT_FRAME_BYTES: ByteSize = mebibytes(100);
87/// Default maximum accepted client frame size.
88pub const DEFAULT_CLIENT_FRAME_MAX: ByteSize = MAX_CLIENT_FRAME_BYTES;
89
90/// Positive, whole-millisecond DNS lookup deadline.
91///
92/// Stores the validated millisecond count so policy structs can retain `Eq`
93/// while public configuration boundaries use dimensioned [`Time`] values.
94#[derive(Clone, Copy, Debug, Eq, PartialEq, derive_more::Into)]
95pub struct ClientDnsTimeout(i64);
96
97impl ClientDnsTimeout {
98    /// Validate a DNS lookup deadline.
99    ///
100    /// # Errors
101    ///
102    /// Returns an error when the duration is non-finite, zero, negative,
103    /// fractional in milliseconds, or cannot be represented as `i64`
104    /// milliseconds.
105    pub fn new(value: Time) -> Result<Self, String> {
106        let milliseconds = GreaterI64::<0>::new(value.millis_i64())
107            .map_err(|error| format!("client DNS timeout: {error}"))?
108            .into_value();
109        if !value.secs_f64().is_finite() || Time::from_millis(milliseconds) != value {
110            return Err("client DNS timeout must be a whole number of milliseconds".to_owned());
111        }
112        Ok(Self(milliseconds))
113    }
114
115    /// Return the validated timeout.
116    #[must_use]
117    pub fn time(self) -> Time {
118        Time::from_millis(self.0)
119    }
120
121    /// Return the validated timeout in milliseconds.
122    #[must_use]
123    pub const fn milliseconds(self) -> i64 {
124        self.0
125    }
126}
127
128impl Default for ClientDnsTimeout {
129    fn default() -> Self {
130        Self::new(DEFAULT_CLIENT_DNS_TIMEOUT).expect("default client DNS timeout is valid")
131    }
132}
133
134/// Positive capacity of one connection's pending request dispatch queue.
135#[derive(Clone, Copy, Debug, Eq, PartialEq, derive_more::Into)]
136pub struct ConnectionDispatchQueueCapacity(usize);
137
138impl ConnectionDispatchQueueCapacity {
139    /// Validate a dispatch queue capacity.
140    ///
141    /// # Errors
142    ///
143    /// Returns an error when `value` is zero.
144    pub fn new(value: usize) -> Result<Self, String> {
145        GreaterUsize::<0>::new(value)
146            .map(|value| Self(value.into_value()))
147            .map_err(|error| format!("client dispatch queue capacity: {error}"))
148    }
149
150    /// Return the validated capacity.
151    #[must_use]
152    pub const fn get(self) -> usize {
153        self.0
154    }
155}
156
157impl Default for ConnectionDispatchQueueCapacity {
158    fn default() -> Self {
159        Self::new(DEFAULT_CONNECTION_DISPATCH_QUEUE_CAPACITY)
160            .expect("default client dispatch queue capacity is valid")
161    }
162}
163
164/// Positive whole-byte accepted-frame limit bounded by the fixed security ceiling.
165#[derive(Clone, Copy, Debug, Eq, PartialEq, derive_more::Into)]
166pub struct ClientFrameMax(usize);
167
168impl ClientFrameMax {
169    /// Return the validated byte count.
170    #[must_use]
171    pub const fn bytes(self) -> usize {
172        self.0
173    }
174
175    /// Return the validated limit as a dimensioned quantity.
176    #[must_use]
177    pub fn size(self) -> ByteSize {
178        ByteSize::from_bytes(u64::try_from(self.0).unwrap_or(u64::MAX))
179    }
180}
181
182impl TryFrom<ByteSize> for ClientFrameMax {
183    type Error = String;
184
185    fn try_from(value: ByteSize) -> Result<Self, Self::Error> {
186        let bytes = value.bytes_f64();
187        if !bytes.is_finite()
188            || bytes.fract() != 0.0
189            || !(1.0..=MAX_CLIENT_FRAME_BYTES.bytes_f64()).contains(&bytes)
190        {
191            return Err(
192                "client frame max must be a positive whole-byte value no greater than 100MiB"
193                    .to_owned(),
194            );
195        }
196        usize::try_from(value.bytes_u64())
197            .map(Self)
198            .map_err(|_| "client frame max does not fit usize".to_owned())
199    }
200}
201
202impl Default for ClientFrameMax {
203    fn default() -> Self {
204        Self::try_from(DEFAULT_CLIENT_FRAME_MAX).expect("default client frame max is valid")
205    }
206}
207
208/// How the client resolves broker host names (Kafka `client.dns.lookup`).
209#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
210pub enum ClientDnsLookup {
211    /// `use_all_dns_ips`: resolve each host to all its addresses of the family
212    /// of the first address, and try them in turn.
213    #[default]
214    UseAllDnsIps,
215    /// `resolve_canonical_bootstrap_servers_only`: replace each bootstrap
216    /// address with the canonical host name of its reverse lookup, then use
217    /// all addresses as `UseAllDnsIps` does.
218    ResolveCanonicalBootstrapServersOnly,
219}
220
221/// Connect-time + per-request configuration knobs.
222#[derive(Debug, Clone)]
223pub struct ConnectionOptions {
224    pub client_id: String,
225    pub dns_timeout: ClientDnsTimeout,
226    /// The TCP connect deadline of one attempt
227    /// (`socket.connection.setup.timeout.ms`). The broker pool doubles it,
228    /// with jitter, for each failed attempt to the same broker, up to
229    /// [`Self::socket_connection_setup_timeout_max`].
230    pub socket_connection_setup_timeout: Time,
231    /// `socket.connection.setup.timeout.max.ms`.
232    pub socket_connection_setup_timeout_max: Time,
233    /// The wait before the broker pool connects again to a broker after a
234    /// failure or a disconnect (`reconnect.backoff.ms`). It doubles, with
235    /// jitter, for each failure in a row.
236    pub reconnect_backoff: Time,
237    /// `reconnect.backoff.max.ms`.
238    pub reconnect_backoff_max: Time,
239    /// The connection closes after this time with no request and no response
240    /// (`connections.max.idle.ms`).
241    pub connections_max_idle: Time,
242    /// `client.dns.lookup`.
243    pub client_dns_lookup: ClientDnsLookup,
244    /// The socket send buffer (`send.buffer.bytes`). `None` keeps the
245    /// operating system default, as Kafka's `-1` does.
246    pub send_buffer: Option<ByteSize>,
247    /// The socket receive buffer (`receive.buffer.bytes`). `None` keeps the
248    /// operating system default.
249    pub receive_buffer: Option<ByteSize>,
250    pub request_timeout: Time,
251    pub dispatch_queue_capacity: ConnectionDispatchQueueCapacity,
252    pub frame_max: ClientFrameMax,
253    /// Client-side TLS/SASL policy. `None` = plaintext (default).
254    ///
255    /// This field is boxed so `ConnectionOptions` stays small. Many call
256    /// sites clone `ConnectionOptions` and embed it in connection-building
257    /// futures, and `ClientSecurity` carries several `String`/`PathBuf`
258    /// fields that would otherwise make every such future large.
259    pub security: Option<Box<security::ClientSecurity>>,
260    /// The network metrics of a client that pushes its metrics (KIP-714).
261    /// [`Connection::connect_with_options`] counts the new connection in
262    /// them. `None` counts nowhere.
263    pub network_metrics: Option<telemetry::NetworkMetrics>,
264}
265
266impl ConnectionOptions {
267    /// Validate transport budgets before converting durations or opening sockets.
268    ///
269    /// # Errors
270    /// Rejects nonfinite, unrepresentable or invalid durations, inverted retry
271    /// bounds, and nonpositive or fractional socket buffer sizes.
272    pub fn validate(&self) -> Result<(), String> {
273        for (name, value, allow_zero) in [
274            ("request_timeout", self.request_timeout, false),
275            (
276                "socket_connection_setup_timeout",
277                self.socket_connection_setup_timeout,
278                false,
279            ),
280            (
281                "socket_connection_setup_timeout_max",
282                self.socket_connection_setup_timeout_max,
283                false,
284            ),
285            ("reconnect_backoff", self.reconnect_backoff, true),
286            ("reconnect_backoff_max", self.reconnect_backoff_max, true),
287            ("connections_max_idle", self.connections_max_idle, true),
288        ] {
289            let seconds = value.secs_f64();
290            let duration = std::time::Duration::try_from_secs_f64(seconds);
291            if !seconds.is_finite()
292                || seconds < 0.0
293                || duration.as_ref().is_err()
294                || (!allow_zero && duration.as_ref().is_ok_and(std::time::Duration::is_zero))
295                || duration.as_ref().is_ok_and(|duration| {
296                    std::time::Instant::now().checked_add(*duration).is_none()
297                })
298            {
299                return Err(format!(
300                    "{name} must be {} and representable as a transport deadline",
301                    if allow_zero {
302                        "nonnegative"
303                    } else {
304                        "positive"
305                    }
306                ));
307            }
308        }
309        if self.socket_connection_setup_timeout_max < self.socket_connection_setup_timeout {
310            return Err("socket_connection_setup_timeout_max must not be below socket_connection_setup_timeout".into());
311        }
312        if self.reconnect_backoff_max < self.reconnect_backoff {
313            return Err("reconnect_backoff_max must not be below reconnect_backoff".into());
314        }
315        for (name, value) in [
316            ("send_buffer", self.send_buffer),
317            ("receive_buffer", self.receive_buffer),
318        ] {
319            if let Some(value) = value {
320                let bytes = value.bytes_f64();
321                if !bytes.is_finite()
322                    || bytes < 1.0
323                    || bytes > f64::from(i32::MAX)
324                    || bytes.fract().abs() > f64::EPSILON
325                {
326                    return Err(format!(
327                        "{name} must contain positive whole bytes fitting i32"
328                    ));
329                }
330            }
331        }
332        Ok(())
333    }
334}
335
336impl Default for ConnectionOptions {
337    fn default() -> Self {
338        Self {
339            client_id: "krabka".into(),
340            dns_timeout: ClientDnsTimeout::default(),
341            socket_connection_setup_timeout: DEFAULT_SOCKET_CONNECTION_SETUP_TIMEOUT,
342            socket_connection_setup_timeout_max: DEFAULT_SOCKET_CONNECTION_SETUP_TIMEOUT_MAX,
343            reconnect_backoff: DEFAULT_RECONNECT_BACKOFF,
344            reconnect_backoff_max: DEFAULT_RECONNECT_BACKOFF_MAX,
345            connections_max_idle: DEFAULT_CONNECTIONS_MAX_IDLE,
346            client_dns_lookup: ClientDnsLookup::default(),
347            send_buffer: Some(DEFAULT_SEND_BUFFER),
348            receive_buffer: Some(DEFAULT_RECEIVE_BUFFER),
349            request_timeout: DEFAULT_CLIENT_REQUEST_TIMEOUT,
350            dispatch_queue_capacity: ConnectionDispatchQueueCapacity::default(),
351            frame_max: ClientFrameMax::default(),
352            security: None,
353            network_metrics: None,
354        }
355    }
356}
357
358/// A connection to a single Kafka broker.
359#[derive(Clone)]
360pub struct Connection {
361    inner: Arc<ConnectionInner>,
362}
363
364struct ConnectionInner {
365    versions: ApiVersionTable,
366    options: ConnectionOptions,
367    next_corr_id: AtomicI32,
368    pending: Pending,
369    writer_tx: mpsc::Sender<DispatchItem>,
370    shutdown: CancellationToken,
371    /// SASL re-authentication state (KIP-368), for a connection whose broker
372    /// sent a session lifetime.
373    reauth: Option<reauth::Reauth>,
374    /// The network metrics of the client, once attached. They count the
375    /// requests after the `ApiVersions` exchange.
376    metrics: std::sync::OnceLock<telemetry::ConnectionMetrics>,
377    _reader: JoinHandle<()>,
378    _writer: JoinHandle<()>,
379}
380
381struct DispatchItem {
382    bytes: Bytes,
383}
384
385/// Classify a failed TLS handshake.
386///
387/// Kafka's `SslTransportLayer.maybeProcessHandshakeFailure` raises an
388/// `SslAuthenticationException` for an error from the TLS engine, and keeps a
389/// `close_notify` during the handshake and a plain I/O error retriable.
390/// `tokio-rustls` wraps an error from the TLS engine as the inner error of the
391/// `io::Error`.
392fn tls_handshake_error(addr: SocketAddr, source: std::io::Error) -> ClientError {
393    let rejected = source
394        .get_ref()
395        .and_then(|inner| inner.downcast_ref::<rustls::Error>())
396        .is_some_and(|error| {
397            !matches!(
398                error,
399                rustls::Error::AlertReceived(rustls::AlertDescription::CloseNotify)
400            )
401        });
402    if rejected {
403        ClientError::Authentication {
404            addr,
405            source: crate::error::AuthenticationError::Tls(source),
406        }
407    } else {
408        ClientError::Tls { addr, source }
409    }
410}
411
412/// Classify a failed SASL exchange. Only a rejection is an authentication
413/// failure.
414pub(crate) fn sasl_error(addr: SocketAddr, source: sasl::OutboundSaslError) -> ClientError {
415    match source {
416        sasl::OutboundSaslError::Authentication(error) => ClientError::Authentication {
417            addr,
418            source: error.into(),
419        },
420        source => ClientError::Sasl { addr, source },
421    }
422}
423
424/// The last time that a connection sent or received a frame, as milliseconds
425/// since the connection started.
426struct Activity {
427    started: tokio::time::Instant,
428    last_ms: AtomicU64,
429}
430
431impl Activity {
432    fn new() -> Self {
433        Self {
434            started: tokio::time::Instant::now(),
435            last_ms: AtomicU64::new(0),
436        }
437    }
438
439    fn touch(&self) {
440        let elapsed = u64::try_from(self.started.elapsed().as_millis()).unwrap_or(u64::MAX);
441        self.last_ms.fetch_max(elapsed, Ordering::Relaxed);
442    }
443
444    fn last(&self) -> tokio::time::Instant {
445        self.started + std::time::Duration::from_millis(self.last_ms.load(Ordering::Relaxed))
446    }
447}
448
449/// Open a TCP connection to `addr` through [`crate::transport::dial`], with
450/// the `send.buffer.bytes` and `receive.buffer.bytes` of `options`.
451async fn tcp_connect(
452    addr: SocketAddr,
453    options: &ConnectionOptions,
454) -> Result<TcpStream, ClientError> {
455    let socket = SocketOptions {
456        send_buffer: options.send_buffer,
457        receive_buffer: options.receive_buffer,
458        nodelay: true,
459    };
460    dial_address(addr, socket)
461        .await
462        .map_err(|source| ClientError::Connect { addr, source })
463}
464
465/// Run `setup` within `options.socket_connection_setup_timeout`.
466///
467/// Kafka's connection setup timeout covers a node in the `CONNECTING` state:
468/// the TCP connection and the TLS and SASL handshakes, until the client sends
469/// `ApiVersions` (`ClusterConnectionStates.checkingApiVersions`).
470async fn within_setup_timeout<T>(
471    options: &ConnectionOptions,
472    setup: impl Future<Output = Result<T, ClientError>>,
473) -> Result<T, ClientError> {
474    options.validate().map_err(ClientError::InvalidConfig)?;
475    tokio::time::timeout(options.socket_connection_setup_timeout.to_std(), setup)
476        .await
477        .map_err(|_| ClientError::Timeout(options.socket_connection_setup_timeout))?
478}
479
480impl Connection {
481    /// Connect to `addr`, negotiate API versions, return a usable `Connection`.
482    #[tracing::instrument(level = "debug", skip_all, fields(addr = %addr), err(level = "debug"))]
483    /// # Errors
484    /// Returns an error when configuration is invalid, protocol encoding fails, the broker rejects the request, or transport I/O fails.
485    pub async fn connect(
486        addr: SocketAddr,
487        options: ConnectionOptions,
488    ) -> Result<Self, ClientError> {
489        let stream = within_setup_timeout(&options, tcp_connect(addr, &options)).await?;
490        Self::from_stream(Box::new(stream), options).await
491    }
492
493    /// Connect to `addr` and honour `options.security`.
494    ///
495    /// This method makes a secured (TLS/SASL) dial when a policy is set, and
496    /// a plaintext dial otherwise. It is the single connect entry point for
497    /// every metadata-client site (pool, admin, RLMM fetch loop), so the
498    /// plaintext-versus-secured branch cannot drift between them. The
499    /// plaintext (`None`) path is byte-identical to [`Self::connect`].
500    ///
501    /// # Errors
502    /// Propagates [`Self::connect`] / [`Self::connect_secured`] failures.
503    #[tracing::instrument(
504        level = "debug",
505        skip_all,
506        fields(addr = %addr, secured = options.security.is_some()),
507        err(level = "debug"),
508    )]
509    pub async fn connect_with_options(
510        addr: SocketAddr,
511        options: ConnectionOptions,
512    ) -> Result<Self, ClientError> {
513        let metrics = options.network_metrics.clone();
514        // The TLS and SASL handshakes make a large future. Boxing it keeps the
515        // futures of the callers small, and it keeps the type depth of a
516        // caller that nests several connections below the compiler limit.
517        let connection = match options.security.clone() {
518            Some(sec) => Box::pin(Self::connect_secured(addr, options, sec.as_ref())).await,
519            None => Box::pin(Self::connect(addr, options)).await,
520        }?;
521        if let Some(metrics) = &metrics {
522            connection.attach_metrics(metrics);
523        }
524        Ok(connection)
525    }
526
527    /// Connect to `addr` and apply `security` (TLS then SASL) before the
528    /// API-versions bootstrap.
529    ///
530    /// `Plaintext` is identical to [`Self::connect`].
531    ///
532    /// # Errors
533    ///
534    /// Returns [`ClientError::Connect`] / [`ClientError::Timeout`] on the
535    /// TCP dial, [`ClientError::Tls`] or [`ClientError::Sasl`] if the TLS
536    /// handshake or the SASL exchange fails with no verdict from the peer,
537    /// [`ClientError::Authentication`] if the peer rejects authentication,
538    /// [`ClientError::InvalidConfig`] if the TLS settings do not build, or
539    /// [`ClientError::Io`] if the security policy is internally inconsistent
540    /// (e.g. a TLS protocol with no TLS config).
541    #[tracing::instrument(
542        level = "debug",
543        skip_all,
544        fields(addr = %addr, protocol = ?security.protocol),
545        err(level = "debug"),
546    )]
547    pub async fn connect_secured(
548        addr: SocketAddr,
549        options: ConnectionOptions,
550        security: &security::ClientSecurity,
551    ) -> Result<Self, ClientError> {
552        let (stream, reauth) = within_setup_timeout(&options, async {
553            let tcp = tcp_connect(addr, &options).await?;
554            Self::secure_stream(addr, tcp, &options, security).await
555        })
556        .await?;
557        Self::from_stream_with_reauth(stream, options, reauth).await
558    }
559
560    /// Run the TLS and SASL handshakes of `security` over `tcp`.
561    async fn secure_stream(
562        addr: SocketAddr,
563        tcp: TcpStream,
564        options: &ConnectionOptions,
565        security: &security::ClientSecurity,
566    ) -> Result<(Box<dyn ClientDuplex>, Option<reauth::Reauth>), ClientError> {
567        // 1. TLS (if the protocol demands it).
568        let mut stream: Box<dyn ClientDuplex> = if security.protocol.requires_tls() {
569            let tls = security.tls.as_ref().ok_or_else(|| {
570                ClientError::Io(std::io::Error::other("TLS protocol without tls config"))
571            })?;
572            let connector = tls
573                .connector()
574                .map_err(|error| ClientError::InvalidConfig(error.to_string()))?;
575            let server_name = if tls.server_name.is_empty() {
576                addr.ip().to_string()
577            } else {
578                tls.server_name.clone()
579            };
580            let sni = tokio_rustls::rustls::pki_types::ServerName::try_from(server_name)
581                .map_err(|e| ClientError::Io(std::io::Error::other(format!("invalid SNI: {e}"))))?;
582            let s = connector
583                .connect(sni, tcp)
584                .await
585                .map_err(|source| tls_handshake_error(addr, source))?;
586            Box::new(s)
587        } else {
588            Box::new(tcp)
589        };
590
591        // 2. SASL (if the protocol demands it).
592        let mut reauth = None;
593        if security.protocol.requires_sasl() {
594            let creds = security.sasl.as_ref().ok_or_else(|| {
595                ClientError::Io(std::io::Error::other("SASL protocol without credentials"))
596            })?;
597            // GSSAPI SPN host: explicit `sasl_host`, else TLS SNI, else the
598            // connection's target IP, else "localhost". The target IP is a
599            // last resort — for GSSAPI the caller should set `sasl_host` so
600            // the principal matches the broker's advertised hostname.
601            let target = addr.ip().to_string();
602            let server_name = security.sasl_handshake_host(Some(target.as_str()));
603            let session = sasl::outbound_sasl(
604                &mut *stream,
605                creds,
606                server_name,
607                &options.client_id,
608                options.frame_max,
609            )
610            .await
611            .map_err(|source| sasl_error(addr, source))?;
612            reauth = session
613                .needs_reauthentication()
614                .then(|| reauth::Reauth::new(addr, creds.clone(), server_name.to_owned(), session));
615        }
616        Ok((stream, reauth))
617    }
618
619    /// Build a `Connection` over a pre-established, optionally
620    /// pre-authenticated stream.
621    ///
622    /// This method negotiates API versions over the stream and returns a
623    /// usable `Connection`. The broker's `InterBrokerClient` integration
624    /// calls it: the TLS + SASL handshake runs before this call, so the
625    /// stream is already authenticated. From here on the connection's normal
626    /// request / response framing applies.
627    #[tracing::instrument(level = "debug", skip_all, err(level = "debug"))]
628    /// # Errors
629    /// Returns an error when configuration is invalid, protocol encoding fails, the broker rejects the request, or transport I/O fails.
630    /// # Panics
631    /// Panics if synchronized client state is poisoned or a response violates an invariant established by protocol validation.
632    pub async fn from_stream(
633        stream: Box<dyn ClientDuplex>,
634        options: ConnectionOptions,
635    ) -> Result<Self, ClientError> {
636        Self::from_stream_with_reauth(stream, options, None).await
637    }
638
639    /// [`Self::from_stream`] for a stream that a SASL exchange authenticated,
640    /// with the state to authenticate again before the session ends.
641    pub(crate) async fn from_stream_with_reauth(
642        stream: Box<dyn ClientDuplex>,
643        options: ConnectionOptions,
644        reauth: Option<reauth::Reauth>,
645    ) -> Result<Self, ClientError> {
646        options.validate().map_err(ClientError::InvalidConfig)?;
647        let (writer_tx, writer_rx) =
648            mpsc::channel::<DispatchItem>(options.dispatch_queue_capacity.get());
649        let shutdown = CancellationToken::new();
650        let pending: Pending = Arc::new(DashMap::new());
651        let activity = Arc::new(Activity::new());
652
653        let (reader_handle, writer_handle) = spawn_io_tasks(
654            stream,
655            writer_rx,
656            IoContext {
657                shutdown: shutdown.clone(),
658                pending: Arc::clone(&pending),
659                activity,
660                frame_max: options.frame_max,
661                max_idle: options.connections_max_idle.to_std(),
662            },
663        );
664
665        let mut conn = Self {
666            inner: Arc::new(ConnectionInner {
667                versions: ApiVersionTable::default(),
668                options: options.clone(),
669                next_corr_id: AtomicI32::new(0),
670                pending,
671                writer_tx,
672                shutdown,
673                reauth,
674                metrics: std::sync::OnceLock::new(),
675                _reader: reader_handle,
676                _writer: writer_handle,
677            }),
678        };
679
680        let versions = fetch_api_versions(&conn).await?;
681        let inner = Arc::get_mut(&mut conn.inner).expect("unique handle at connect-time");
682        inner.versions = versions;
683
684        Ok(conn)
685    }
686
687    /// Return the peer-advertised version range for `api_key`.
688    ///
689    /// Higher-level clients use this to distinguish an API that is absent
690    /// from a listener's surface from one whose advertised versions merely do
691    /// not overlap their codec range.
692    #[must_use]
693    pub fn advertised_api_range(&self, api_key: i16) -> Option<(i16, i16)> {
694        self.inner.versions.broker_range(api_key)
695    }
696
697    /// Send a typed request and await the typed response.
698    ///
699    /// This method negotiates the version from the broker-advertised table
700    /// that `connect` populated. It encodes and decodes the request and
701    /// response headers automatically.
702    ///
703    /// # Errors
704    ///
705    /// Returns `ClientError::IncompatibleVersion` if there is no mutually
706    /// supported version, `ClientError::Disconnected` if the I/O loop has
707    /// exited, or `ClientError::Timeout` if no response arrives in time.
708    // cargo-mutants: live-broker send path; not unit-testable
709    #[cfg_attr(test, mutants::skip)]
710    #[tracing::instrument(
711        level = "debug",
712        skip_all,
713        fields(api_key = R::API_KEY, version = tracing::field::Empty),
714        err(level = "debug"),
715    )]
716    pub async fn send<R: ProtocolRequest>(&self, req: R) -> Result<R::Response, ClientError> {
717        // 1. Negotiate version.
718        let version = self.inner.versions.negotiate::<R>()?;
719        tracing::Span::current().record("version", version);
720
721        // 2. Allocate correlation ID.
722        let corr_id = self.next_correlation_id();
723
724        // 3. Build request header + encoded body into one frame.
725        //
726        // The header has a trailing tagged-fields byte (header v2) iff the
727        // body is flexible. The `client_id` field is always i16 NULLABLE_STRING
728        // per the upstream `RequestHeader.json` schema.
729        let body_flexible = version >= R::FLEXIBLE_MIN;
730        let mut frame = build_request_header(
731            ApiKey(R::API_KEY),
732            ApiVersion(version),
733            corr_id,
734            &self.inner.options.client_id,
735            body_flexible,
736        );
737        req.encode(&mut frame, version)?;
738
739        // 4. Dispatch request and await response.
740        let body_bytes = self.dispatch_request(corr_id, frame).await?;
741
742        // 5. Decode the response.
743        //
744        // The reader has already stripped the 4-byte correlation_id prefix.
745        // What remains is: [ResponseHeader fields after corr_id] + [response body].
746        //
747        // ResponseHeader version rules:
748        //   - ApiVersionsResponse (api_key=18): always ResponseHeader v0, which
749        //     has NO fields after the correlation_id. This is a long-standing
750        //     Kafka asymmetry — even flexible ApiVersions responses use v0 header.
751        //   - All other flexible messages (version >= FLEXIBLE_MIN): ResponseHeader
752        //     v1 adds 1 byte for the tagged-fields count (0x00 when empty).
753        //   - Non-flexible messages: ResponseHeader v0 (no bytes after corr_id).
754        let mut cursor: &[u8] = &body_bytes;
755        let uses_flexible_resp_header = body_flexible && R::API_KEY != API_VERSIONS_KEY;
756        if uses_flexible_resp_header {
757            cursor = skip_tagged_fields(cursor)?;
758        }
759
760        let resp = <R::Response as krabka_protocol::Decode>::decode(&mut cursor, version)?;
761        Ok(resp)
762    }
763
764    /// Encode and enqueue a typed request that intentionally has no response.
765    /// Kafka Produce with `acks=0` is the standard use case.
766    ///
767    /// # Errors
768    ///
769    /// Returns an error if version negotiation or encoding fails, or if the
770    /// connection writer has stopped before accepting the frame.
771    pub async fn send_no_response<R: ProtocolRequest>(&self, req: R) -> Result<(), ClientError> {
772        let version = self.inner.versions.negotiate::<R>()?;
773        let corr_id = self.next_correlation_id();
774        let body_flexible = version >= R::FLEXIBLE_MIN;
775        let mut frame = build_request_header(
776            ApiKey(R::API_KEY),
777            ApiVersion(version),
778            corr_id,
779            &self.inner.options.client_id,
780            body_flexible,
781        );
782        req.encode(&mut frame, version)?;
783        let guard = self.reauthenticate_if_due().await?;
784        if let Some(metrics) = self.inner.metrics.get() {
785            metrics.request(frame.len());
786        }
787        let sent = self
788            .inner
789            .writer_tx
790            .send(DispatchItem {
791                bytes: frame.freeze(),
792            })
793            .await
794            .map_err(|_| ClientError::Disconnected);
795        drop(guard);
796        sent
797    }
798
799    /// Send a hand-framed request and await the raw response body.
800    ///
801    /// This method bypasses the typed [`ProtocolRequest`] codegen path so
802    /// callers can speak Krabka-private APIs whose wire types live outside
803    /// `krabka-protocol`, for example the controller's Raft RPCs at api keys
804    /// 1000+.
805    ///
806    /// This method always writes the header as `RequestHeader v2` (flexible)
807    /// with an empty trailing tagged-fields byte. It assumes the response
808    /// uses `ResponseHeader v1` (flexible): the I/O loop strips the 4-byte
809    /// correlation id, and this method strips the leading tagged-fields byte
810    /// before it returns. Callers receive the raw body bytes only.
811    ///
812    /// `body` is the encoded request body, which is everything after the
813    /// request header, exactly as it should appear on the wire.
814    ///
815    /// # Errors
816    ///
817    /// Returns [`ClientError::Disconnected`] if the I/O loop has exited
818    /// or [`ClientError::Timeout`] if no response arrives within the
819    /// configured request timeout.
820    // cargo-mutants: live-broker I/O path; not unit-testable
821    #[cfg_attr(test, mutants::skip)]
822    #[tracing::instrument(
823        level = "debug",
824        skip_all,
825        fields(api_key, api_version),
826        err(level = "debug")
827    )]
828    pub async fn raw_request(
829        &self,
830        api_key: i16,
831        api_version: i16,
832        body: Bytes,
833    ) -> Result<Bytes, ClientError> {
834        let corr_id = self.next_correlation_id();
835
836        // RequestHeader v2 (flexible). Krabka-private api keys are always
837        // declared flexible so the header shape is predictable.
838        let mut frame = build_request_header(
839            ApiKey(api_key),
840            ApiVersion(api_version),
841            corr_id,
842            &self.inner.options.client_id,
843            true,
844        );
845        frame.put_slice(&body);
846
847        let body_bytes = self.dispatch_request(corr_id, frame).await?;
848
849        // ResponseHeader v1: the tagged fields after the already-stripped
850        // correlation id.
851        let body = skip_tagged_fields(&body_bytes)?;
852        Ok(body_bytes.slice(body_bytes.len() - body.len()..))
853    }
854
855    /// Negotiated API versions known to this connection.
856    // cargo-mutants: one-line accessor returning a borrowed field
857    #[must_use]
858    #[cfg_attr(test, mutants::skip)]
859    pub fn versions(&self) -> &ApiVersionTable {
860        &self.inner.versions
861    }
862
863    /// The number of requests that wait for a response on this connection.
864    #[must_use]
865    pub fn in_flight(&self) -> usize {
866        self.inner.pending.len()
867    }
868
869    /// The next correlation id of a normal request. As Kafka's
870    /// `NetworkClient.nextCorrelationId` does, the ids wrap to 0 before the
871    /// range that SASL re-authentication reserves.
872    fn next_correlation_id(&self) -> i32 {
873        let last_normal = sasl::MIN_RESERVED_CORRELATION_ID - 1;
874        self.inner
875            .next_corr_id
876            .fetch_update(Ordering::Relaxed, Ordering::Relaxed, |current| {
877                Some(if current >= last_normal {
878                    0
879                } else {
880                    current + 1
881                })
882            })
883            .unwrap_or(0)
884    }
885
886    /// Whether the connection has closed: the peer closed it, an I/O error
887    /// ended it, it was idle for `connections_max_idle`, or [`Self::close`]
888    /// ran. A closed connection fails every request with `Disconnected`.
889    #[must_use]
890    pub fn is_closed(&self) -> bool {
891        self.inner.shutdown.is_cancelled()
892    }
893
894    /// Close the connection, cancelling all background tasks.
895    // cargo-mutants: teardown; no observable return to assert against
896    #[cfg_attr(test, mutants::skip)]
897    pub fn close(self) {
898        self.inner.shutdown.cancel();
899        // The Arc gets dropped when `self` does; `JoinHandle`s abort naturally.
900    }
901
902    async fn dispatch_request(&self, corr_id: i32, frame: BytesMut) -> Result<Bytes, ClientError> {
903        let guard = self.reauthenticate_if_due().await?;
904        // A caller that drops this future must not leave its id in `pending`,
905        // where it would keep the connection from its idle close.
906        let _registration = PendingRegistration {
907            pending: &self.inner.pending,
908            corr_id,
909        };
910        let metrics = self.inner.metrics.get();
911        if let Some(metrics) = metrics {
912            metrics.request(frame.len());
913        }
914        let rx = self.enqueue(corr_id, frame).await?;
915        drop(guard);
916        let response = self.await_response(corr_id, rx).await?;
917        if let Some(metrics) = metrics {
918            metrics.response(response.len());
919        }
920        Ok(response)
921    }
922
923    /// Count this connection in the client's network metrics from now on.
924    /// A connection counts in one set of metrics; a second call does
925    /// nothing.
926    pub fn attach_metrics(&self, metrics: &telemetry::NetworkMetrics) {
927        self.inner.metrics.get_or_init(|| metrics.opened());
928    }
929
930    /// Send a frame and wait for its response, with no re-authentication
931    /// check. A re-authentication sends its own frames this way.
932    pub(crate) async fn dispatch_unguarded(
933        &self,
934        corr_id: i32,
935        frame: BytesMut,
936    ) -> Result<Bytes, ClientError> {
937        let _registration = PendingRegistration {
938            pending: &self.inner.pending,
939            corr_id,
940        };
941        let rx = self.enqueue(corr_id, frame).await?;
942        self.await_response(corr_id, rx).await
943    }
944
945    /// The request header of a frame that this connection sends.
946    pub(crate) fn request_header(
947        &self,
948        api_key: ApiKey,
949        version: ApiVersion,
950        corr_id: i32,
951        flexible: bool,
952    ) -> BytesMut {
953        build_request_header(
954            api_key,
955            version,
956            corr_id,
957            &self.inner.options.client_id,
958            flexible,
959        )
960    }
961
962    /// Wait for a due SASL re-authentication to finish, and return a guard
963    /// that keeps a new one from starting until the caller enqueues its frame.
964    ///
965    /// Kafka's `KafkaChannel.maybeBeginClientReauthentication` starts the
966    /// exchange before the first request after the due time. A failed
967    /// exchange closes the connection and fails the request.
968    async fn reauthenticate_if_due(
969        &self,
970    ) -> Result<Option<tokio::sync::RwLockReadGuard<'_, Option<tokio::time::Instant>>>, ClientError>
971    {
972        let Some(reauth) = self.inner.reauth.as_ref() else {
973            return Ok(None);
974        };
975        loop {
976            let next = reauth.next.read().await;
977            if next.is_none_or(|due| tokio::time::Instant::now() < due) {
978                return Ok(Some(next));
979            }
980            drop(next);
981            let mut next = reauth.next.write().await;
982            if next.is_some_and(|due| tokio::time::Instant::now() >= due) {
983                let mut channel = reauth::ConnectionChannel { connection: self };
984                // The exchange nests the whole SASL state machine. Boxing it
985                // keeps every send future small.
986                match Box::pin(reauth.authenticate(
987                    &mut channel,
988                    &self.inner.options.client_id,
989                    self.inner.options.frame_max,
990                ))
991                .await
992                {
993                    Ok(due) => *next = due,
994                    Err(error) => {
995                        tracing::warn!(error = %error, "SASL re-authentication failed");
996                        self.inner.shutdown.cancel();
997                        return Err(error);
998                    }
999                }
1000            }
1001        }
1002    }
1003
1004    /// Register `corr_id` and queue `frame` for the writer.
1005    async fn enqueue(
1006        &self,
1007        corr_id: i32,
1008        frame: BytesMut,
1009    ) -> Result<oneshot::Receiver<Result<Bytes, ClientError>>, ClientError> {
1010        let (tx, rx) = oneshot::channel::<Result<Bytes, ClientError>>();
1011        self.inner.pending.insert(corr_id, tx);
1012        self.inner
1013            .writer_tx
1014            .send(DispatchItem {
1015                bytes: frame.freeze(),
1016            })
1017            .await
1018            .map_err(|_| ClientError::Disconnected)?;
1019        Ok(rx)
1020    }
1021
1022    /// Wait for the response of `corr_id` within the request timeout.
1023    async fn await_response(
1024        &self,
1025        corr_id: i32,
1026        rx: oneshot::Receiver<Result<Bytes, ClientError>>,
1027    ) -> Result<Bytes, ClientError> {
1028        match tokio::time::timeout(self.inner.options.request_timeout.to_std(), rx).await {
1029            Ok(Ok(Ok(bytes))) => Ok(bytes),
1030            Ok(Ok(Err(err))) => Err(err),
1031            Ok(Err(_recv_closed)) => Err(ClientError::Disconnected),
1032            Err(_timeout) => {
1033                self.inner.pending.remove(&corr_id);
1034                // Kafka's `NetworkClient.handleTimedOutRequests` closes the
1035                // connection of a timed-out request: a late response must
1036                // not match a later request, and the next use connects again.
1037                self.inner.shutdown.cancel();
1038                Err(ClientError::Timeout(self.inner.options.request_timeout))
1039            }
1040        }
1041    }
1042}
1043
1044/// Removes a request from `pending` when its caller stops waiting.
1045struct PendingRegistration<'a> {
1046    pending: &'a Pending,
1047    corr_id: i32,
1048}
1049
1050impl Drop for PendingRegistration<'_> {
1051    fn drop(&mut self) {
1052        self.pending.remove(&self.corr_id);
1053    }
1054}
1055
1056/// Skip the tagged fields of a flexible response header: an unsigned varint
1057/// count, then for each field a varint tag, a varint size and the data.
1058///
1059/// # Errors
1060/// Returns a codec error for a header that ends early.
1061pub(crate) fn skip_tagged_fields(mut bytes: &[u8]) -> Result<&[u8], ClientError> {
1062    fn uvarint(bytes: &mut &[u8]) -> Result<u32, ClientError> {
1063        let mut value = 0_u32;
1064        for shift in (0..35).step_by(7) {
1065            let (&byte, rest) = bytes.split_first().ok_or_else(truncated)?;
1066            *bytes = rest;
1067            value |= u32::from(byte & 0x7F) << shift;
1068            if byte & 0x80 == 0 {
1069                return Ok(value);
1070            }
1071        }
1072        Err(truncated())
1073    }
1074    fn truncated() -> ClientError {
1075        ClientError::Io(std::io::Error::new(
1076            std::io::ErrorKind::InvalidData,
1077            "invalid tagged fields in a response header",
1078        ))
1079    }
1080    if bytes.is_empty() {
1081        return Ok(bytes);
1082    }
1083    for _ in 0..uvarint(&mut bytes)? {
1084        uvarint(&mut bytes)?;
1085        let size = usize::try_from(uvarint(&mut bytes)?).map_err(|_| truncated())?;
1086        bytes = bytes.get(size..).ok_or_else(truncated)?;
1087    }
1088    Ok(bytes)
1089}
1090
1091/// Spawn independent reader and writer tasks over the split socket.
1092///
1093/// This function splits the socket into a read half and a write half, and one
1094/// task drives each half. It does not multiplex both directions through one
1095/// `select!` over a single shared `Framed`. A combined task must `await` the
1096/// `framed.send(...)` flush *inside* a `select!` arm, and it does not poll the
1097/// read arm during that time. On a request/response connection the broker
1098/// stays silent until it receives the next request. A write that does not
1099/// complete in one poll therefore wedges the whole connection: the frame sits
1100/// buffered, no inbound traffic ever re-drives the loop, and the caller's
1101/// request never reaches the wire.
1102///
1103/// This is what made `krabka-client-consumer`'s group rejoin hang under the
1104/// jemalloc heap-profiling allocator. Its per-alloc sampling latency widened
1105/// that window enough to trip the hang deterministically. Independent halves
1106/// keep an inbound frame pollable while an outbound write is in flight, and
1107/// the reverse.
1108///
1109/// Liveness on teardown: when either task exits on EOF, an I/O error, a
1110/// dropped `Connection`, or `close()`, it cancels the shared `shutdown` token
1111/// so the other task also stops. The reader then fails every outstanding
1112/// request with `Disconnected`. A write-half failure therefore reaches
1113/// callers promptly instead of stalling them until the request timeout.
1114///
1115/// Idle close: the writer also closes the connection when no frame went out
1116/// or came in for `max_idle` and no request waits for a response, as Kafka's
1117/// `Selector` closes a connection idle for `connections.max.idle.ms`.
1118fn spawn_io_tasks(
1119    stream: Box<dyn ClientDuplex>,
1120    mut writer_rx: mpsc::Receiver<DispatchItem>,
1121    context: IoContext,
1122) -> (JoinHandle<()>, JoinHandle<()>) {
1123    use futures_util::StreamExt;
1124    use tokio_util::codec::{FramedRead, FramedWrite};
1125
1126    let IoContext {
1127        shutdown,
1128        pending,
1129        activity,
1130        frame_max,
1131        max_idle,
1132    } = context;
1133
1134    let (read_half, write_half) = tokio::io::split(stream);
1135    let mut framed_read = FramedRead::new(read_half, framing::codec_with_max(frame_max));
1136    let mut framed_write = FramedWrite::new(write_half, framing::codec_with_max(frame_max));
1137
1138    // WRITER: drains the dispatch channel, flushing each frame in receive
1139    // order. Owns only the write half, so a not-yet-writable socket can never
1140    // block the reader.
1141    let writer_shutdown = shutdown.clone();
1142    let writer_activity = Arc::clone(&activity);
1143    let writer_pending = Arc::clone(&pending);
1144    let writer = tokio::spawn(async move {
1145        write_loop(
1146            &writer_shutdown,
1147            &writer_activity,
1148            &writer_pending,
1149            max_idle,
1150            &mut writer_rx,
1151            &mut framed_write,
1152        )
1153        .await;
1154        // A write-side failure (or all senders dropped) must wake the reader
1155        // so it drains pending callers to `Disconnected` rather than letting
1156        // them wait out the request timeout.
1157        writer_shutdown.cancel();
1158    });
1159
1160    // READER: pulls frames and fulfils the matching pending oneshot. Owns only
1161    // the read half.
1162    let reader = tokio::spawn(async move {
1163        loop {
1164            tokio::select! {
1165                () = shutdown.cancelled() => break,
1166                maybe_frame = framed_read.next() => {
1167                    let Some(frame) = maybe_frame else { break; };
1168                    let Ok(frame) = frame else { break; };
1169                    activity.touch();
1170                    if frame.len() < 4 { continue; }
1171                    let corr_id = i32::from_be_bytes([frame[0], frame[1], frame[2], frame[3]]);
1172                    if let Some((_, tx)) = pending.remove(&corr_id) {
1173                        let body = Bytes::copy_from_slice(&frame[4..]);
1174                        let _ = tx.send(Ok(body));
1175                    }
1176                }
1177            }
1178        }
1179        // Stop the writer too, then fail every outstanding request.
1180        shutdown.cancel();
1181        let keys: Vec<i32> = pending.iter().map(|e| *e.key()).collect();
1182        for k in keys {
1183            if let Some((_, tx)) = pending.remove(&k) {
1184                let _ = tx.send(Err(ClientError::Disconnected));
1185            }
1186        }
1187    });
1188
1189    (reader, writer)
1190}
1191
1192/// The shared state of a connection's I/O tasks.
1193struct IoContext {
1194    shutdown: CancellationToken,
1195    pending: Pending,
1196    activity: Arc<Activity>,
1197    frame_max: ClientFrameMax,
1198    max_idle: std::time::Duration,
1199}
1200
1201/// The writer loop: send each dispatched frame in order, and stop when the
1202/// connection shuts down, a write fails, or the connection is idle for
1203/// `max_idle` with no pending request.
1204async fn write_loop<W>(
1205    shutdown: &CancellationToken,
1206    activity: &Activity,
1207    pending: &Pending,
1208    max_idle: std::time::Duration,
1209    writer_rx: &mut mpsc::Receiver<DispatchItem>,
1210    framed_write: &mut W,
1211) where
1212    W: futures_util::Sink<Bytes> + Unpin,
1213{
1214    use futures_util::SinkExt;
1215
1216    loop {
1217        let idle_deadline = activity.last() + max_idle;
1218        tokio::select! {
1219            () = shutdown.cancelled() => break,
1220            item = writer_rx.recv() => {
1221                let Some(item) = item else { break; };
1222                activity.touch();
1223                // A peer that stops reading can hold a write for ever. The
1224                // write must still end when the connection shuts down, for
1225                // example after a request timeout.
1226                let written = tokio::select! {
1227                    () = shutdown.cancelled() => break,
1228                    written = framed_write.send(item.bytes) => written,
1229                };
1230                if written.is_err() {
1231                    break;
1232                }
1233                activity.touch();
1234            }
1235            () = tokio::time::sleep_until(idle_deadline), if !max_idle.is_zero() => {
1236                let idle = activity.last() + max_idle <= tokio::time::Instant::now();
1237                if idle && pending.is_empty() && writer_rx.is_empty() {
1238                    tracing::debug!(
1239                        max_idle_ms = max_idle.as_millis(),
1240                        "closing a connection idle for connections.max.idle.ms"
1241                    );
1242                    break;
1243                }
1244                if idle {
1245                    // A request waits for its response. Look again after the
1246                    // idle interval.
1247                    activity.touch();
1248                }
1249            }
1250        }
1251    }
1252}
1253
1254/// Build an encoded `RequestHeader` into a `BytesMut`.
1255///
1256/// Kafka has only two `RequestHeader` formats:
1257///
1258/// - **v1** (non-flexible): `api_key` + `version` + `corr_id` + i16
1259///   `client_id` length + `client_id` bytes.
1260/// - **v2** (flexible): same fields *plus* a trailing `tagged_fields` byte
1261///   (`0x00` when empty).
1262///
1263/// Note that `client_id` is `NULLABLE_STRING` (i16 length) in **both**
1264/// versions. The upstream `RequestHeader.json` schema marks the field as
1265/// `"flexibleVersions": "none"`, so even a v2 header keeps the i16-length
1266/// encoding. A UVARINT here makes the broker misread the length and throw
1267/// `InvalidRequestException` during header parsing.
1268///
1269/// Pass `with_tagged_fields = true` iff the request body is flexible
1270/// (`version >= R::FLEXIBLE_MIN`).
1271fn build_request_header(
1272    api_key: ApiKey,
1273    version: ApiVersion,
1274    corr_id: i32,
1275    client_id: &str,
1276    with_tagged_fields: bool,
1277) -> BytesMut {
1278    let mut buf = BytesMut::with_capacity(32);
1279    buf.put_i16(api_key.0);
1280    buf.put_i16(version.0);
1281    buf.put_i32(corr_id);
1282    let n = i16::try_from(client_id.len()).expect("client_id fits in i16");
1283    buf.put_i16(n);
1284    buf.put_slice(client_id.as_bytes());
1285    if with_tagged_fields {
1286        buf.put_u8(0); // empty tagged fields
1287    }
1288    buf
1289}
1290
1291/// The client software name that `ApiVersions` v3 and later sends (KIP-511).
1292pub const CLIENT_SOFTWARE_NAME: &str = "krabka-client-rs";
1293
1294/// The client software version that `ApiVersions` v3 and later sends.
1295pub const CLIENT_SOFTWARE_VERSION: &str = env!("CARGO_PKG_VERSION");
1296
1297/// Kafka's `UNSUPPORTED_VERSION` error code.
1298const UNSUPPORTED_VERSION: i16 = 35;
1299
1300/// The `ApiVersions` request of a new connection at `version`, as Kafka's
1301/// `ApiVersionsRequest.Builder` fills it.
1302pub(crate) fn api_versions_request() -> api_versions_request::ApiVersionsRequest {
1303    api_versions_request::ApiVersionsRequest {
1304        client_software_name: CLIENT_SOFTWARE_NAME.to_owned(),
1305        client_software_version: CLIENT_SOFTWARE_VERSION.to_owned(),
1306        ..Default::default()
1307    }
1308}
1309
1310/// Decode an `ApiVersions` response body sent for a request at `version`.
1311///
1312/// Kafka's `ApiVersionsResponse.parse` falls back to version 0: a broker that
1313/// does not support `version` answers with a version 0 `UNSUPPORTED_VERSION`
1314/// response. A body that does not decode to its end at `version` is read as
1315/// version 0.
1316pub(crate) fn decode_api_versions_response(
1317    body: &[u8],
1318    version: i16,
1319) -> Result<api_versions_response::ApiVersionsResponse, ClientError> {
1320    use krabka_protocol::{Decode as _, owned::api_versions_response::ApiVersionsResponse};
1321
1322    let decode = |version| {
1323        let mut cursor = body;
1324        let response = ApiVersionsResponse::decode(&mut cursor, version)?;
1325        if cursor.is_empty() {
1326            Ok(response)
1327        } else {
1328            Err(ClientError::Io(std::io::Error::new(
1329                std::io::ErrorKind::InvalidData,
1330                format!(
1331                    "ApiVersions response v{version} has {} bytes after its end",
1332                    cursor.len()
1333                ),
1334            )))
1335        }
1336    };
1337    match decode(version) {
1338        Err(_) if version != 0 => decode(0),
1339        result => result,
1340    }
1341}
1342
1343/// The next `ApiVersions` version after a response at `version`, or `None`
1344/// when the response ends the negotiation.
1345///
1346/// Kafka's `NetworkClient.handleApiVersionsResponse` retries an
1347/// `UNSUPPORTED_VERSION` answer to a version above 0 at the highest
1348/// `ApiVersions` version that the broker lists, or at version 0.
1349pub(crate) fn api_versions_retry_version(
1350    response: &api_versions_response::ApiVersionsResponse,
1351    version: i16,
1352) -> Option<i16> {
1353    use api_versions_request::API_KEY;
1354
1355    (response.error_code == UNSUPPORTED_VERSION && version > 0).then(|| {
1356        response
1357            .api_keys
1358            .iter()
1359            .find(|key| key.api_key == API_KEY)
1360            .map_or(0, |key| key.max_version)
1361            .min(version - 1)
1362            .max(0)
1363    })
1364}
1365
1366/// Send `ApiVersions` and return the broker's table.
1367///
1368/// This is the bootstrap step inside `connect`. No version table exists yet,
1369/// so this function cannot use `Connection::send`. The first request uses the
1370/// highest version of the client, as Kafka's `NetworkClient` does, and an
1371/// `UNSUPPORTED_VERSION` answer makes it retry at the version that the broker
1372/// lists.
1373#[tracing::instrument(level = "debug", skip_all, err(level = "debug"))]
1374async fn fetch_api_versions(conn: &Connection) -> Result<ApiVersionTable, ClientError> {
1375    use krabka_protocol::{Encode, owned::api_versions_request::ApiVersionsRequest};
1376
1377    let mut version = ApiVersionsRequest::MAX_VERSION;
1378    loop {
1379        let corr_id = conn.next_correlation_id();
1380        let mut frame = build_request_header(
1381            ApiKey(ApiVersionsRequest::API_KEY),
1382            ApiVersion(version),
1383            corr_id,
1384            &conn.inner.options.client_id,
1385            version >= ApiVersionsRequest::FLEXIBLE_MIN,
1386        );
1387        api_versions_request().encode(&mut frame, version)?;
1388
1389        let (tx, rx) = oneshot::channel::<Result<Bytes, ClientError>>();
1390        conn.inner.pending.insert(corr_id, tx);
1391        conn.inner
1392            .writer_tx
1393            .send(DispatchItem {
1394                bytes: frame.freeze(),
1395            })
1396            .await
1397            .map_err(|_| ClientError::Disconnected)?;
1398
1399        let body_bytes = tokio::time::timeout(conn.inner.options.request_timeout.to_std(), rx)
1400            .await
1401            .map_err(|_| ClientError::Timeout(conn.inner.options.request_timeout))?
1402            .map_err(|_| ClientError::Disconnected)??;
1403
1404        // ResponseHeader v0: only correlation_id (already stripped by the
1405        // reader), for every ApiVersions version (the Kafka asymmetry
1406        // documented in `send`).
1407        let response = decode_api_versions_response(&body_bytes, version)?;
1408        if let Some(retry) = api_versions_retry_version(&response, version) {
1409            version = retry;
1410            continue;
1411        }
1412        if response.error_code != 0 {
1413            return Err(ClientError::Server {
1414                error_code: response.error_code,
1415            });
1416        }
1417        return Ok(ApiVersionTable::from_response(&response));
1418    }
1419}
1420
1421#[cfg(test)]
1422mod tests {
1423    use assert2::assert;
1424    use krabka_units::{ByteSize, bytes, kibibytes, mebibytes, micros, millis};
1425
1426    use super::*;
1427    use crate::Client;
1428
1429    #[test]
1430    fn client_dns_timeout_validates_and_preserves_milliseconds() {
1431        let timeout = ClientDnsTimeout::new(millis(37)).expect("positive timeout");
1432        assert!(timeout.time() == millis(37));
1433        assert!(timeout.milliseconds() == 37);
1434        assert!(ClientDnsTimeout::new(Time::ZERO).is_err());
1435        assert!(ClientDnsTimeout::new(micros(1)).is_err());
1436        assert!(ClientDnsTimeout::new(millis(1) + micros(1)).is_err());
1437    }
1438
1439    #[test]
1440    fn connection_options_default_to_kafka_client_settings() {
1441        let options = ConnectionOptions::default();
1442        assert!(options.reconnect_backoff == millis(50));
1443        assert!(options.reconnect_backoff_max == secs(1));
1444        assert!(options.socket_connection_setup_timeout_max == secs(30));
1445        assert!(options.connections_max_idle == minutes(9));
1446        assert!(options.client_dns_lookup == ClientDnsLookup::UseAllDnsIps);
1447        assert!(options.send_buffer == Some(kibibytes(128)));
1448        assert!(options.receive_buffer == Some(kibibytes(64)));
1449    }
1450
1451    #[test]
1452    fn connection_options_own_named_defaults() {
1453        let options = ConnectionOptions::default();
1454        assert!(DEFAULT_CLIENT_DNS_TIMEOUT == secs(10));
1455        assert!(DEFAULT_SOCKET_CONNECTION_SETUP_TIMEOUT == secs(10));
1456        assert!(DEFAULT_SOCKET_CONNECTION_SETUP_TIMEOUT_MAX == secs(30));
1457        assert!(DEFAULT_CLIENT_REQUEST_TIMEOUT == secs(30));
1458        assert!(options.dns_timeout == ClientDnsTimeout::default());
1459        assert!(options.dns_timeout.time() == DEFAULT_CLIENT_DNS_TIMEOUT);
1460        assert!(options.socket_connection_setup_timeout == DEFAULT_SOCKET_CONNECTION_SETUP_TIMEOUT);
1461        assert!(options.request_timeout == DEFAULT_CLIENT_REQUEST_TIMEOUT);
1462    }
1463
1464    #[test]
1465    fn connection_resource_defaults_preserve_existing_values() {
1466        assert!(
1467            ConnectionDispatchQueueCapacity::default().get()
1468                == DEFAULT_CONNECTION_DISPATCH_QUEUE_CAPACITY
1469        );
1470        assert!(ConnectionDispatchQueueCapacity::default().get() == 64);
1471        assert!(ClientFrameMax::default().size() == mebibytes(100));
1472        assert!(MAX_CLIENT_FRAME_BYTES == mebibytes(100));
1473    }
1474
1475    #[test]
1476    fn transport_options_validate_duration_and_socket_boundaries() {
1477        let setters: [fn(&mut ConnectionOptions, Time); 6] = [
1478            |options, value| options.request_timeout = value,
1479            |options, value| options.socket_connection_setup_timeout = value,
1480            |options, value| options.socket_connection_setup_timeout_max = value,
1481            |options, value| options.reconnect_backoff = value,
1482            |options, value| options.reconnect_backoff_max = value,
1483            |options, value| options.connections_max_idle = value,
1484        ];
1485        for set in setters {
1486            for value in [
1487                Time::from_secs_f64(-1.0),
1488                Time::from_secs_f64(f64::NAN),
1489                Time::from_secs_f64(f64::INFINITY),
1490                Time::from_secs_f64(f64::MAX),
1491            ] {
1492                let mut options = ConnectionOptions::default();
1493                set(&mut options, value);
1494                assert!(options.validate().is_err());
1495            }
1496        }
1497        for value in [
1498            ByteSize::ZERO,
1499            ByteSize::from_bytes_f64(-1.0),
1500            ByteSize::from_bytes_f64(0.5),
1501            ByteSize::from_bytes_f64(f64::NAN),
1502            ByteSize::from_bytes_f64(f64::INFINITY),
1503            ByteSize::from_bytes_f64(f64::from(i32::MAX) + 1.0),
1504        ] {
1505            assert!(
1506                (ConnectionOptions {
1507                    send_buffer: Some(value),
1508                    ..Default::default()
1509                })
1510                .validate()
1511                .is_err()
1512            );
1513            assert!(
1514                (ConnectionOptions {
1515                    receive_buffer: Some(value),
1516                    ..Default::default()
1517                })
1518                .validate()
1519                .is_err()
1520            );
1521        }
1522        assert!(
1523            (ConnectionOptions {
1524                request_timeout: Time::ZERO,
1525                ..Default::default()
1526            })
1527            .validate()
1528            .is_err()
1529        );
1530        assert!(
1531            (ConnectionOptions {
1532                socket_connection_setup_timeout: Time::ZERO,
1533                ..Default::default()
1534            })
1535            .validate()
1536            .is_err()
1537        );
1538        assert!(
1539            (ConnectionOptions {
1540                socket_connection_setup_timeout: secs(31),
1541                ..Default::default()
1542            })
1543            .validate()
1544            .is_err()
1545        );
1546        assert!(
1547            (ConnectionOptions {
1548                reconnect_backoff: secs(2),
1549                ..Default::default()
1550            })
1551            .validate()
1552            .is_err()
1553        );
1554        assert!(
1555            (ConnectionOptions {
1556                reconnect_backoff: Time::ZERO,
1557                reconnect_backoff_max: Time::ZERO,
1558                connections_max_idle: Time::ZERO,
1559                send_buffer: None,
1560                receive_buffer: Some(bytes(1)),
1561                request_timeout: millis(1),
1562                socket_connection_setup_timeout: millis(1),
1563                socket_connection_setup_timeout_max: millis(1),
1564                ..Default::default()
1565            })
1566            .validate()
1567            .is_ok()
1568        );
1569    }
1570
1571    #[tokio::test]
1572    async fn invalid_options_fail_before_connect_or_stream_negotiation() {
1573        let options = ConnectionOptions {
1574            request_timeout: Time::from_secs_f64(f64::NAN),
1575            ..Default::default()
1576        };
1577        let result = Connection::connect("127.0.0.1:1".parse().unwrap(), options.clone()).await;
1578        assert!(matches!(result, Err(ClientError::InvalidConfig(_))));
1579        let result = Client::builder()
1580            .bootstrap("invalid-bootstrap")
1581            .request_timeout(Time::from_secs_f64(f64::NAN))
1582            .build()
1583            .await;
1584        assert!(matches!(result, Err(ClientError::InvalidConfig(_))));
1585        let (stream, _peer) = tokio::io::duplex(1024);
1586        let result = Connection::from_stream(Box::new(stream), options).await;
1587        assert!(matches!(result, Err(ClientError::InvalidConfig(_))));
1588    }
1589
1590    #[test]
1591    fn connection_resource_policy_validates_boundaries() {
1592        assert!(ConnectionDispatchQueueCapacity::new(0).is_err());
1593        assert!(ConnectionDispatchQueueCapacity::new(7).unwrap().get() == 7);
1594
1595        assert!(ClientFrameMax::try_from(bytes(0)).is_err());
1596        assert!(ClientFrameMax::try_from(ByteSize::from_bytes_f64(1.5)).is_err());
1597        assert!(ClientFrameMax::try_from(mebibytes(100) + bytes(1)).is_err());
1598        assert!(ClientFrameMax::try_from(kibibytes(32)).unwrap().size() == kibibytes(32));
1599    }
1600}
1601
1602#[cfg(test)]
1603mod secured_tests {
1604    use krabka_security::ListenerProtocol;
1605    use security::{ClientSecurity, SaslCredentials};
1606
1607    use super::*;
1608
1609    // A SASL_PLAINTEXT connect drives the handshake then ApiVersions.
1610    // The fake broker answers SaslHandshake(0), SaslAuthenticate(0),
1611    // then a minimal ApiVersionsResponse v0 so from_stream succeeds.
1612    #[tokio::test]
1613    async fn connect_secured_runs_sasl_then_api_versions() {
1614        use krabka_protocol::{
1615            Encode,
1616            owned::{
1617                api_versions_response::ApiVersionsResponse,
1618                sasl_authenticate_response::SaslAuthenticateResponse,
1619                sasl_handshake_response::SaslHandshakeResponse,
1620            },
1621        };
1622        use tokio::io::{AsyncReadExt, AsyncWriteExt};
1623
1624        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
1625        let addr = listener.local_addr().unwrap();
1626        let server = tokio::spawn(async move {
1627            let (mut s, _) = listener.accept().await.unwrap();
1628            // (body, flexible_response_header)
1629            let replies: [(BytesMut, bool); 4] = [
1630                {
1631                    // The ApiVersions v0 that starts the SASL exchange lists
1632                    // the SASL APIs.
1633                    let mock::MockReply::Respond(body) = mock::MockSaslAnswer::Accept
1634                        .reply(api_versions_request::API_KEY, 0)
1635                        .unwrap()
1636                    else {
1637                        unreachable!("ApiVersions v0 has a reply")
1638                    };
1639                    (BytesMut::from(&body[..]), false)
1640                },
1641                {
1642                    let mut b = BytesMut::new();
1643                    SaslHandshakeResponse {
1644                        error_code: 0,
1645                        ..Default::default()
1646                    }
1647                    .encode(&mut b, 1)
1648                    .unwrap();
1649                    (b, false)
1650                },
1651                {
1652                    let mut b = BytesMut::new();
1653                    SaslAuthenticateResponse {
1654                        error_code: 0,
1655                        ..Default::default()
1656                    }
1657                    .encode(&mut b, 2)
1658                    .unwrap();
1659                    (b, true)
1660                },
1661                {
1662                    let mut b = BytesMut::new();
1663                    ApiVersionsResponse::default().encode(&mut b, 0).unwrap();
1664                    // ApiVersions always uses a v0 response header.
1665                    (b, false)
1666                },
1667            ];
1668            for (body, flex_header) in replies {
1669                let req_len = s.read_u32().await.unwrap();
1670                let mut req = vec![0u8; req_len as usize];
1671                s.read_exact(&mut req).await.unwrap();
1672                let corr = i32::from_be_bytes([req[4], req[5], req[6], req[7]]);
1673                let mut frame = BytesMut::new();
1674                frame.put_i32(corr);
1675                if flex_header {
1676                    frame.put_u8(0);
1677                }
1678                frame.put_slice(&body);
1679                s.write_u32(u32::try_from(frame.len()).unwrap())
1680                    .await
1681                    .unwrap();
1682                s.write_all(&frame).await.unwrap();
1683                s.flush().await.unwrap();
1684            }
1685        });
1686        let security = ClientSecurity {
1687            protocol: ListenerProtocol::SaslPlaintext,
1688            tls: None,
1689            sasl: Some(SaslCredentials::Plain {
1690                username: "u".into(),
1691                password: "p".into(),
1692            }),
1693            sasl_host: None,
1694        };
1695        let conn = Connection::connect_secured(addr, ConnectionOptions::default(), &security)
1696            .await
1697            .expect("secured connect completes");
1698        conn.close();
1699        server.await.unwrap();
1700    }
1701}
1702
1703#[cfg(test)]
1704mod tls_handshake_failure_tests {
1705    use krabka_security::ListenerProtocol;
1706    use tokio::{
1707        io::{AsyncReadExt, AsyncWriteExt},
1708        net::TcpListener,
1709    };
1710
1711    use super::*;
1712    use crate::{
1713        error::AuthenticationError,
1714        security::{ClientSecurity, TlsConnectorConfig},
1715    };
1716
1717    /// What the TLS listener does after it accepts the connection.
1718    #[derive(Clone, Copy, Debug)]
1719    enum Peer {
1720        /// Answer the `ClientHello` with plaintext, as a plaintext listener
1721        /// does.
1722        Plaintext,
1723        /// Close the connection before the handshake completes.
1724        Close,
1725    }
1726
1727    /// How the handshake failed, as a caller classifies it.
1728    #[derive(Debug, PartialEq, Eq)]
1729    enum Failure {
1730        Rejected(std::io::ErrorKind),
1731        Transport(std::io::ErrorKind),
1732        Other(String),
1733    }
1734
1735    async fn listener(peer: Peer) -> SocketAddr {
1736        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
1737        let addr = listener.local_addr().unwrap();
1738        tokio::spawn(async move {
1739            let (mut stream, _) = listener.accept().await.unwrap();
1740            let mut buf = [0_u8; 1024];
1741            let _ = stream.read(&mut buf).await;
1742            if matches!(peer, Peer::Plaintext) {
1743                let _ = stream.write_all(b"HTTP/1.0 400 Bad Request\r\n\r\n").await;
1744                while matches!(stream.read(&mut buf).await, Ok(n) if n > 0) {}
1745            }
1746        });
1747        addr
1748    }
1749
1750    /// Kafka's `SslTransportLayer.maybeProcessHandshakeFailure` raises an
1751    /// `SslAuthenticationException` for "Unrecognized SSL message", and keeps
1752    /// a disconnect during the handshake retriable.
1753    #[tokio::test]
1754    async fn tls_rejection_is_an_authentication_failure_and_eof_is_not() {
1755        let security = ClientSecurity {
1756            protocol: ListenerProtocol::Ssl,
1757            tls: Some(TlsConnectorConfig::default()),
1758            sasl: None,
1759            sasl_host: None,
1760        };
1761        for (peer, expected) in [
1762            (
1763                Peer::Plaintext,
1764                Failure::Rejected(std::io::ErrorKind::InvalidData),
1765            ),
1766            (
1767                Peer::Close,
1768                Failure::Transport(std::io::ErrorKind::UnexpectedEof),
1769            ),
1770        ] {
1771            let addr = listener(peer).await;
1772            let result =
1773                Connection::connect_secured(addr, ConnectionOptions::default(), &security).await;
1774            let failure = match result {
1775                Err(ClientError::Authentication {
1776                    source: AuthenticationError::Tls(source),
1777                    ..
1778                }) => Failure::Rejected(source.kind()),
1779                Err(ClientError::Tls { source, .. }) => Failure::Transport(source.kind()),
1780                Err(error) => Failure::Other(error.to_string()),
1781                Ok(_) => Failure::Other("connected".into()),
1782            };
1783            assert2::check!(failure == expected, "{peer:?}");
1784        }
1785    }
1786}
1787
1788#[cfg(test)]
1789mod io_task_tests {
1790    use std::time::{Duration, Instant};
1791
1792    use krabka_protocol::{
1793        Encode,
1794        owned::{
1795            api_versions_response::{ApiVersion, ApiVersionsResponse},
1796            metadata_request::MetadataRequest,
1797            metadata_response::MetadataResponse,
1798        },
1799    };
1800    use tokio::{
1801        io::{AsyncReadExt, AsyncWriteExt},
1802        net::TcpListener,
1803    };
1804
1805    use super::*;
1806
1807    // The split reader/writer tasks must keep their teardown contract: a
1808    // server that closes the connection mid-request has to surface to the
1809    // caller promptly as `Disconnected`, NOT stall until the request timeout.
1810    // The reader's EOF cancels the shared shutdown (stopping the writer) and
1811    // drains every outstanding request — so a write-half failure can't strand
1812    // a caller for the full timeout. (Regression guard for the io-task split.)
1813    #[tokio::test]
1814    async fn server_close_mid_request_yields_prompt_disconnected() {
1815        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
1816        let addr = listener.local_addr().unwrap();
1817        let server = tokio::spawn(async move {
1818            let (mut s, _) = listener.accept().await.unwrap();
1819            // Answer the `from_stream` ApiVersions handshake.
1820            let len = s.read_u32().await.unwrap();
1821            let mut req = vec![0u8; len as usize];
1822            s.read_exact(&mut req).await.unwrap();
1823            let corr = i32::from_be_bytes([req[4], req[5], req[6], req[7]]);
1824            let mut body = BytesMut::new();
1825            ApiVersionsResponse::default().encode(&mut body, 0).unwrap();
1826            let mut frame = BytesMut::new();
1827            frame.put_i32(corr);
1828            frame.put_slice(&body);
1829            s.write_u32(u32::try_from(frame.len()).unwrap())
1830                .await
1831                .unwrap();
1832            s.write_all(&frame).await.unwrap();
1833            s.flush().await.unwrap();
1834            // Read the next request fully (so its pending entry is registered),
1835            // then drop the socket without replying.
1836            let len2 = s.read_u32().await.unwrap();
1837            let mut req2 = vec![0u8; len2 as usize];
1838            s.read_exact(&mut req2).await.unwrap();
1839            // `s` drops here -> the connection closes with no response.
1840        });
1841
1842        let stream = TcpStream::connect(addr).await.unwrap();
1843        let opts = ConnectionOptions {
1844            request_timeout: secs(5),
1845            socket_connection_setup_timeout: secs(5),
1846            ..Default::default()
1847        };
1848        let conn = Connection::from_stream(Box::new(stream), opts)
1849            .await
1850            .expect("plaintext from_stream completes");
1851
1852        let started = Instant::now();
1853        // Hand-framed Metadata request; the server reads it then closes.
1854        let result = conn.raw_request(3, 0, Bytes::new()).await;
1855        assert!(
1856            matches!(result, Err(ClientError::Disconnected)),
1857            "server close mid-request must yield Disconnected, got {result:?}"
1858        );
1859        assert!(
1860            started.elapsed() < Duration::from_secs(4),
1861            "drain must be prompt (reader EOF), not a request-timeout stall"
1862        );
1863        server.await.unwrap();
1864    }
1865
1866    #[tokio::test]
1867    async fn no_response_request_does_not_capture_the_next_response() {
1868        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
1869        let addr = listener.local_addr().unwrap();
1870        let server = tokio::spawn(async move {
1871            let (mut socket, _) = listener.accept().await.unwrap();
1872
1873            let handshake_len = socket.read_u32().await.unwrap();
1874            let mut handshake = vec![0u8; handshake_len as usize];
1875            socket.read_exact(&mut handshake).await.unwrap();
1876            let handshake_corr =
1877                i32::from_be_bytes([handshake[4], handshake[5], handshake[6], handshake[7]]);
1878            let mut handshake_body = BytesMut::new();
1879            ApiVersionsResponse {
1880                api_keys: vec![ApiVersion {
1881                    api_key: MetadataRequest::API_KEY,
1882                    min_version: 0,
1883                    max_version: 0,
1884                    ..Default::default()
1885                }],
1886                ..Default::default()
1887            }
1888            .encode(&mut handshake_body, 0)
1889            .unwrap();
1890            let mut handshake_response = BytesMut::new();
1891            handshake_response.put_i32(handshake_corr);
1892            handshake_response.put_slice(&handshake_body);
1893            socket
1894                .write_u32(u32::try_from(handshake_response.len()).unwrap())
1895                .await
1896                .unwrap();
1897            socket.write_all(&handshake_response).await.unwrap();
1898            socket.flush().await.unwrap();
1899
1900            let one_way_len = socket.read_u32().await.unwrap();
1901            let mut one_way = vec![0u8; one_way_len as usize];
1902            socket.read_exact(&mut one_way).await.unwrap();
1903            let one_way_corr = i32::from_be_bytes([one_way[4], one_way[5], one_way[6], one_way[7]]);
1904
1905            let request_len = socket.read_u32().await.unwrap();
1906            let mut request = vec![0u8; request_len as usize];
1907            socket.read_exact(&mut request).await.unwrap();
1908            let request_corr = i32::from_be_bytes([request[4], request[5], request[6], request[7]]);
1909            assert2::assert!(request_corr == one_way_corr.wrapping_add(1));
1910
1911            let mut body = BytesMut::new();
1912            MetadataResponse::default().encode(&mut body, 0).unwrap();
1913            let mut response = BytesMut::new();
1914            response.put_i32(request_corr);
1915            response.put_slice(&body);
1916            socket
1917                .write_u32(u32::try_from(response.len()).unwrap())
1918                .await
1919                .unwrap();
1920            socket.write_all(&response).await.unwrap();
1921            socket.flush().await.unwrap();
1922        });
1923
1924        let stream = TcpStream::connect(addr).await.unwrap();
1925        let conn = Connection::from_stream(Box::new(stream), ConnectionOptions::default())
1926            .await
1927            .expect("plaintext from_stream completes");
1928        conn.send_no_response(MetadataRequest::default())
1929            .await
1930            .expect("one-way request enqueues");
1931        let response = conn
1932            .send(MetadataRequest::default())
1933            .await
1934            .expect("subsequent response remains correlated");
1935        assert2::assert!(response == MetadataResponse::default());
1936
1937        conn.close();
1938        server.await.unwrap();
1939    }
1940}
1941
1942#[cfg(test)]
1943mod connection_policy_tests {
1944    use std::time::Duration;
1945
1946    use assert2::check;
1947    use krabka_protocol::{
1948        Encode,
1949        owned::{
1950            api_versions_response::{ApiVersion, ApiVersionsResponse},
1951            metadata_request::MetadataRequest,
1952        },
1953    };
1954    use krabka_security::ListenerProtocol;
1955    use security::{ClientSecurity, SaslCredentials};
1956    use tokio::io::{AsyncReadExt, AsyncWriteExt, DuplexStream};
1957
1958    use super::*;
1959
1960    /// Answer the `ApiVersions` request of `from_stream` on `server`, with
1961    /// `Metadata` v0 supported, and return the stream.
1962    async fn answer_api_versions(mut server: DuplexStream) -> DuplexStream {
1963        let len = server.read_u32().await.unwrap();
1964        let mut request = vec![0_u8; len as usize];
1965        server.read_exact(&mut request).await.unwrap();
1966        let mut body = BytesMut::new();
1967        body.put_slice(&request[4..8]);
1968        ApiVersionsResponse {
1969            api_keys: vec![ApiVersion {
1970                api_key: MetadataRequest::API_KEY,
1971                min_version: 0,
1972                max_version: 0,
1973                ..Default::default()
1974            }],
1975            ..Default::default()
1976        }
1977        .encode(&mut body, 0)
1978        .unwrap();
1979        server
1980            .write_u32(u32::try_from(body.len()).unwrap())
1981            .await
1982            .unwrap();
1983        server.write_all(&body).await.unwrap();
1984        server
1985    }
1986
1987    async fn connection(options: ConnectionOptions) -> (Connection, DuplexStream) {
1988        let (client, server) = tokio::io::duplex(64 * 1024);
1989        let (connection, server) = tokio::join!(
1990            Connection::from_stream(Box::new(client), options),
1991            answer_api_versions(server)
1992        );
1993        (connection.unwrap(), server)
1994    }
1995
1996    /// Kafka's `Selector.maybeCloseOldestConnection` closes a connection
1997    /// with no traffic for `connections.max.idle.ms`. Each row is the idle
1998    /// time after the last response and whether a request waits.
1999    #[tokio::test(start_paused = true)]
2000    async fn an_idle_connection_closes_after_connections_max_idle() {
2001        let max_idle = Duration::from_mins(9);
2002        let ms = Duration::from_millis;
2003        for (name, idle, waiting, closed) in [
2004            (
2005                "just below the limit",
2006                max_idle.saturating_sub(ms(1)),
2007                false,
2008                false,
2009            ),
2010            ("just past the limit", max_idle + ms(1), false, true),
2011            (
2012                "a request waits for its response",
2013                max_idle * 2,
2014                true,
2015                false,
2016            ),
2017        ] {
2018            let (connection, _server) = connection(ConnectionOptions {
2019                request_timeout: secs(3600),
2020                ..ConnectionOptions::default()
2021            })
2022            .await;
2023            let waiter = waiting.then(|| {
2024                let connection = connection.clone();
2025                tokio::spawn(async move { connection.send(MetadataRequest::default()).await })
2026            });
2027            tokio::time::sleep(idle).await;
2028            check!(connection.is_closed() == closed, "{name}");
2029            if let Some(waiter) = waiter {
2030                waiter.abort();
2031            }
2032        }
2033    }
2034
2035    #[tokio::test(start_paused = true)]
2036    async fn zero_idle_budget_disables_eviction_instead_of_closing_immediately() {
2037        let (connection, _server) = connection(ConnectionOptions {
2038            connections_max_idle: Time::ZERO,
2039            ..ConnectionOptions::default()
2040        })
2041        .await;
2042        tokio::time::sleep(Duration::from_hours(24)).await;
2043        check!(!connection.is_closed());
2044        connection.close();
2045    }
2046
2047    /// Kafka's `NetworkClient.handleTimedOutRequests` closes the connection
2048    /// of a request that timed out.
2049    #[tokio::test(start_paused = true)]
2050    async fn a_request_timeout_closes_the_connection() {
2051        let (connection, _server) = connection(ConnectionOptions {
2052            request_timeout: secs(30),
2053            ..ConnectionOptions::default()
2054        })
2055        .await;
2056        let result = connection.send(MetadataRequest::default()).await;
2057        check!(matches!(result, Err(ClientError::Timeout(_))));
2058        check!(connection.is_closed());
2059        check!(connection.in_flight() == 0);
2060    }
2061
2062    /// The connection setup timeout covers the TLS and SASL handshakes, as a
2063    /// Kafka node stays `CONNECTING` until it sends `ApiVersions`.
2064    #[tokio::test]
2065    async fn the_setup_timeout_covers_a_sasl_handshake_that_never_answers() {
2066        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
2067        let addr = listener.local_addr().unwrap();
2068        let server = tokio::spawn(async move {
2069            let (mut stream, _) = listener.accept().await.unwrap();
2070            let mut buffer = [0_u8; 1024];
2071            while matches!(stream.read(&mut buffer).await, Ok(read) if read > 0) {}
2072        });
2073        let security = ClientSecurity {
2074            protocol: ListenerProtocol::SaslPlaintext,
2075            tls: None,
2076            sasl: Some(SaslCredentials::Plain {
2077                username: "u".into(),
2078                password: "p".into(),
2079            }),
2080            sasl_host: None,
2081        };
2082        let options = ConnectionOptions {
2083            socket_connection_setup_timeout: millis(100),
2084            request_timeout: secs(30),
2085            ..ConnectionOptions::default()
2086        };
2087        let started = std::time::Instant::now();
2088        let result = Connection::connect_secured(addr, options, &security).await;
2089        check!(matches!(result, Err(ClientError::Timeout(timeout)) if timeout == millis(100)));
2090        check!(started.elapsed() < Duration::from_secs(5));
2091        server.abort();
2092    }
2093
2094    /// A request timeout closes the connection, and the writer ends even
2095    /// while a peer that does not read holds its write.
2096    #[tokio::test(start_paused = true)]
2097    async fn a_write_blocked_by_a_peer_that_does_not_read_ends_at_shutdown() {
2098        let (client, server) = tokio::io::duplex(64 * 1024);
2099        let (connection, _server) = tokio::join!(
2100            Connection::from_stream(
2101                Box::new(client),
2102                ConnectionOptions {
2103                    request_timeout: secs(30),
2104                    ..ConnectionOptions::default()
2105                },
2106            ),
2107            answer_api_versions(server)
2108        );
2109        let connection = connection.unwrap();
2110        // The raw request is larger than the duplex buffer, so its write
2111        // blocks.
2112        let result = connection
2113            .raw_request(3, 0, Bytes::from(vec![0_u8; 256 * 1024]))
2114            .await;
2115        check!(matches!(result, Err(ClientError::Timeout(_))));
2116        tokio::time::sleep(Duration::from_millis(1)).await;
2117        // The writer task drops the receiver when it ends.
2118        check!(connection.inner.writer_tx.is_closed());
2119    }
2120
2121    /// How a scripted broker answers each `ApiVersions` version.
2122    #[derive(Clone, Copy, Debug)]
2123    enum Broker {
2124        /// It supports `ApiVersions` up to this version, and lists it in an
2125        /// `UNSUPPORTED_VERSION` answer, as Kafka 2.4 and later do.
2126        ListsUpTo(i16),
2127        /// It supports only version 0 and lists nothing in its
2128        /// `UNSUPPORTED_VERSION` answer.
2129        OnlyVersionZero,
2130    }
2131
2132    /// Kafka's `NetworkClient` sends `ApiVersions` at its highest version and
2133    /// retries an `UNSUPPORTED_VERSION` answer at the version that the broker
2134    /// lists, or at version 0. A version 3 or later answer holds the finalized
2135    /// features.
2136    #[tokio::test]
2137    async fn api_versions_negotiation_follows_the_broker_and_keeps_the_features() {
2138        use krabka_protocol::{
2139            Decode as _,
2140            owned::{
2141                api_versions_request::ApiVersionsRequest,
2142                api_versions_response::{FinalizedFeatureKey, SupportedFeatureKey},
2143            },
2144        };
2145
2146        let features = |version: i16| {
2147            if version >= 3 {
2148                crate::FinalizedFeatures {
2149                    epoch: 7,
2150                    levels: maplit::btreemap! {"transaction.version".to_owned() => 2},
2151                }
2152            } else {
2153                crate::FinalizedFeatures::default()
2154            }
2155        };
2156        let software = |version: i16| {
2157            if version >= 3 {
2158                (
2159                    CLIENT_SOFTWARE_NAME.to_owned(),
2160                    CLIENT_SOFTWARE_VERSION.to_owned(),
2161                )
2162            } else {
2163                (String::new(), String::new())
2164            }
2165        };
2166        for (name, broker, expected_versions, expected_features) in [
2167            (
2168                "a broker at version 5",
2169                Broker::ListsUpTo(5),
2170                vec![5],
2171                features(5),
2172            ),
2173            (
2174                "a broker at version 3",
2175                Broker::ListsUpTo(3),
2176                vec![5, 3],
2177                features(3),
2178            ),
2179            (
2180                "a broker at version 2",
2181                Broker::ListsUpTo(2),
2182                vec![5, 2],
2183                features(2),
2184            ),
2185            (
2186                "an old broker",
2187                Broker::OnlyVersionZero,
2188                vec![5, 0],
2189                features(0),
2190            ),
2191        ] {
2192            let (client, mut server) = tokio::io::duplex(64 * 1024);
2193            let script = tokio::spawn(async move {
2194                let mut seen = Vec::new();
2195                loop {
2196                    let Ok(len) = server.read_u32().await else {
2197                        return seen;
2198                    };
2199                    let mut request = vec![0_u8; len as usize];
2200                    server.read_exact(&mut request).await.unwrap();
2201                    let version = i16::from_be_bytes([request[2], request[3]]);
2202                    let client_id_len = usize::from(u16::from_be_bytes([request[8], request[9]]));
2203                    let mut body = &request[10 + client_id_len + usize::from(version >= 3)..];
2204                    let decoded = ApiVersionsRequest::decode(&mut body, version).unwrap();
2205                    seen.push((
2206                        version,
2207                        (
2208                            decoded.client_software_name,
2209                            decoded.client_software_version,
2210                        ),
2211                    ));
2212                    let max = match broker {
2213                        Broker::ListsUpTo(max) => max,
2214                        Broker::OnlyVersionZero => 0,
2215                    };
2216                    let (response, encoded_at) = if version > max {
2217                        let api_keys = match broker {
2218                            Broker::ListsUpTo(max) => vec![ApiVersion {
2219                                api_key: ApiVersionsRequest::API_KEY,
2220                                min_version: 0,
2221                                max_version: max,
2222                                ..Default::default()
2223                            }],
2224                            Broker::OnlyVersionZero => Vec::new(),
2225                        };
2226                        (
2227                            ApiVersionsResponse {
2228                                error_code: UNSUPPORTED_VERSION,
2229                                api_keys,
2230                                ..Default::default()
2231                            },
2232                            0,
2233                        )
2234                    } else {
2235                        (
2236                            ApiVersionsResponse {
2237                                api_keys: vec![ApiVersion {
2238                                    api_key: MetadataRequest::API_KEY,
2239                                    min_version: 0,
2240                                    max_version: 12,
2241                                    ..Default::default()
2242                                }],
2243                                supported_features: vec![SupportedFeatureKey {
2244                                    name: "transaction.version".into(),
2245                                    min_version: 0,
2246                                    max_version: 2,
2247                                    ..Default::default()
2248                                }],
2249                                finalized_features_epoch: 7,
2250                                finalized_features: vec![FinalizedFeatureKey {
2251                                    name: "transaction.version".into(),
2252                                    max_version_level: 2,
2253                                    min_version_level: 2,
2254                                    ..Default::default()
2255                                }],
2256                                ..Default::default()
2257                            },
2258                            version,
2259                        )
2260                    };
2261                    let mut frame = BytesMut::new();
2262                    frame.put_slice(&request[4..8]);
2263                    response.encode(&mut frame, encoded_at).unwrap();
2264                    server
2265                        .write_u32(u32::try_from(frame.len()).unwrap())
2266                        .await
2267                        .unwrap();
2268                    server.write_all(&frame).await.unwrap();
2269                }
2270            });
2271            let connection =
2272                Connection::from_stream(Box::new(client), ConnectionOptions::default())
2273                    .await
2274                    .unwrap();
2275            let observed_features = connection.versions().finalized_features().clone();
2276            let metadata = connection.advertised_api_range(MetadataRequest::API_KEY);
2277            connection.close();
2278            let seen = script.await.unwrap();
2279            check!(
2280                seen == expected_versions
2281                    .iter()
2282                    .map(|version| (*version, software(*version)))
2283                    .collect::<Vec<_>>(),
2284                "{name}"
2285            );
2286            check!(observed_features == expected_features, "{name}");
2287            check!(metadata == Some((0, 12)), "{name}");
2288        }
2289    }
2290
2291    /// Kafka's `NetworkClient.nextCorrelationId` wraps before the SASL
2292    /// reserved range.
2293    #[tokio::test]
2294    async fn normal_correlation_ids_wrap_before_the_sasl_range() {
2295        let (connection, _server) = connection(ConnectionOptions::default()).await;
2296        let reserved = sasl::MIN_RESERVED_CORRELATION_ID;
2297        connection
2298            .inner
2299            .next_corr_id
2300            .store(reserved - 2, Ordering::Relaxed);
2301        let ids = (0..3)
2302            .map(|_| connection.next_correlation_id())
2303            .collect::<Vec<_>>();
2304        check!(ids == vec![reserved - 2, reserved - 1, 0]);
2305    }
2306
2307    #[test]
2308    fn flexible_response_headers_skip_every_tagged_field() {
2309        for (name, header_and_body, expected) in [
2310            ("empty body", vec![], Ok(vec![])),
2311            ("no tagged field", vec![0, 7, 8], Ok(vec![7, 8])),
2312            (
2313                "two tagged fields",
2314                vec![2, 1, 2, 0xAA, 0xBB, 5, 0, 7],
2315                Ok(vec![7]),
2316            ),
2317            ("truncated field", vec![1, 1, 4, 0xAA], Err(())),
2318        ] {
2319            check!(
2320                skip_tagged_fields(&header_and_body)
2321                    .map(<[u8]>::to_vec)
2322                    .map_err(drop)
2323                    == expected,
2324                "{name}"
2325            );
2326        }
2327    }
2328
2329    /// A caller that stops waiting leaves nothing in `pending`, so the idle
2330    /// close still applies.
2331    #[tokio::test(start_paused = true)]
2332    async fn a_dropped_request_leaves_no_pending_entry() {
2333        let (connection, _server) = connection(ConnectionOptions::default()).await;
2334        let sending = connection.clone();
2335        let task = tokio::spawn(async move { sending.send(MetadataRequest::default()).await });
2336        tokio::time::sleep(Duration::from_millis(1)).await;
2337        check!(connection.in_flight() == 1);
2338        task.abort();
2339        let _ = task.await;
2340        check!(connection.in_flight() == 0);
2341    }
2342}