Skip to main content

kafka_client_engine/consumer/group_control/
operation.rs

1//! Immediate batch control and clone-shared shutdown for one group handle.
2
3use std::{sync::Arc, time::Duration};
4
5use kafka_client_core::GroupId;
6
7use crate::consumer::{
8    group::{GroupConsumerCloseAuthority, GroupConsumerPort},
9    group_control::{
10        accepted::GroupConsumerControlAccepted, error::GroupConsumerControlError,
11        partition::GroupConsumerPartition,
12    },
13    group_registration::GroupConsumerHandle,
14};
15
16/// Cloneable exact-group shutdown capability.
17#[derive(Clone)]
18pub struct GroupConsumerControl {
19    group_id: GroupId,
20    close_authority: Arc<GroupConsumerCloseAuthority>,
21    shutdown_port: GroupConsumerPort,
22    close_timeout: Duration,
23}
24
25impl GroupConsumerControl {
26    /// Requests idempotent shutdown of this exact registered group.
27    ///
28    /// The first request retains its call-boundary deadline in the group's
29    /// preallocated close authority. Repeated requests and a later explicit
30    /// close converge on that same broker leave and terminal cell.
31    pub fn request_shutdown(&self) {
32        let Some(deadline) = self
33            .shutdown_port
34            .capture_control_close_deadline(self.close_timeout)
35        else {
36            return;
37        };
38        if self.close_authority.request(deadline) {
39            self.shutdown_port.request_control_shutdown_turn();
40        }
41    }
42}
43
44impl core::fmt::Debug for GroupConsumerControl {
45    fn fmt(&self, formatter: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
46        formatter
47            .debug_struct("GroupConsumerControl")
48            .field("group_id", &self.group_id)
49            .finish_non_exhaustive()
50    }
51}
52
53impl GroupConsumerHandle {
54    /// Returns a cloneable exact-group shutdown capability.
55    pub fn control(&self) -> GroupConsumerControl {
56        GroupConsumerControl {
57            group_id: self.group_id,
58            close_authority: Arc::clone(&self.close_authority),
59            shutdown_port: self.port.clone(),
60            close_timeout: self.close_timeout,
61        }
62    }
63
64    /// Requests idempotent shutdown of this exact registered group.
65    ///
66    /// The first request retains its call-boundary deadline in the group's
67    /// preallocated close authority. Repeated requests and a later explicit
68    /// close converge on that same broker leave and terminal cell.
69    pub fn request_shutdown(&self) {
70        self.control().request_shutdown();
71    }
72
73    /// Atomically pauses one caller-ordered unique partition batch.
74    pub fn pause(
75        &mut self,
76        partitions: Vec<GroupConsumerPartition>,
77    ) -> Result<GroupConsumerControlAccepted, GroupConsumerControlError> {
78        if partitions.is_empty() {
79            return Ok(GroupConsumerControlAccepted::inert());
80        }
81        match self.port.try_pause_partitions(self.group_id, &partitions) {
82            Ok(accepted) => Ok(GroupConsumerControlAccepted::from_port(accepted)),
83            Err(error) => Err(GroupConsumerControlError::from_port(error, partitions)),
84        }
85    }
86
87    /// Atomically resumes retained positions for one caller-ordered unique batch.
88    pub fn resume(
89        &mut self,
90        partitions: Vec<GroupConsumerPartition>,
91    ) -> Result<GroupConsumerControlAccepted, GroupConsumerControlError> {
92        if partitions.is_empty() {
93            return Ok(GroupConsumerControlAccepted::inert());
94        }
95        match self.capture_resume() {
96            Ok(capture) => capture.resume(partitions),
97            Err(error) => Err(GroupConsumerControlError::from_resume_capture(
98                error, partitions,
99            )),
100        }
101    }
102
103    pub(super) fn resume_captured(
104        &mut self,
105        partitions: Vec<GroupConsumerPartition>,
106        capture: crate::clock::DeadlineCapture,
107    ) -> Result<GroupConsumerControlAccepted, GroupConsumerControlError> {
108        if partitions.is_empty() {
109            return Ok(GroupConsumerControlAccepted::inert());
110        }
111        match self
112            .port
113            .try_resume_partitions_captured(self.group_id, &partitions, capture)
114        {
115            Ok(accepted) => Ok(GroupConsumerControlAccepted::from_port(accepted)),
116            Err(error) => Err(GroupConsumerControlError::from_port(error, partitions)),
117        }
118    }
119}