Skip to main content

kafka_client_engine/admin/
handle.rs

1//! Runtime-neutral public handle retaining concrete admin admission ports.
2
3use std::{fmt, sync::Arc, time::Duration};
4
5use super::{
6    CreateTopicsAdmissionError, CreateTopicsAdmissionErrorKind, CreateTopicsObserver,
7    CreateTopicsRequest, DeleteTopicsAdmissionPort,
8    list_client_metrics_resources::internal_api::ListClientMetricsResourcesAdmissionPort,
9    list_config_resources::ListConfigResourcesAdmissionPort, shard::CreateTopicsAdmissionPort,
10};
11use crate::clock::MonotonicClock;
12
13/// Closed set of concrete admin admission capabilities retained by one handle.
14pub(crate) struct AdminAdmissionPorts {
15    pub(crate) abort_partition_transaction:
16        super::abort_partition_transaction::AbortPartitionTransactionAdmissionPort,
17    pub(crate) add_raft_voter: super::add_raft_voter::AddRaftVoterAdmissionPort,
18    pub(crate) remove_raft_voter: super::remove_raft_voter::RemoveRaftVoterAdmissionPort,
19    pub(crate) create_topics: CreateTopicsAdmissionPort,
20    pub(crate) create_acls: super::CreateAclsAdmissionPort,
21    pub(crate) create_delegation_token: super::CreateDelegationTokenAdmissionPort,
22    pub(crate) describe_delegation_tokens: super::DescribeDelegationTokensAdmissionPort,
23    pub(crate) renew_delegation_token: super::RenewDelegationTokenAdmissionPort,
24    pub(crate) expire_delegation_token: super::ExpireDelegationTokenAdmissionPort,
25    pub(crate) delete_acls: super::DeleteAclsAdmissionPort,
26    pub(crate) delete_topics: DeleteTopicsAdmissionPort,
27    pub(crate) delete_records: super::DeleteRecordsAdmissionPort,
28    pub(crate) delete_share_group_offsets:
29        super::delete_share_group_offsets::DeleteShareGroupOffsetsAdmissionPort,
30    pub(crate) list_share_group_offsets:
31        super::list_share_group_offsets::ListShareGroupOffsetsAdmissionPort,
32    pub(crate) alter_share_group_offsets:
33        super::alter_share_group_offsets::AlterShareGroupOffsetsAdmissionPort,
34    pub(crate) describe_share_group: super::describe_share_group::DescribeShareGroupAdmissionPort,
35    pub(crate) describe_streams_group:
36        super::describe_streams_group::DescribeStreamsGroupAdmissionPort,
37    pub(crate) describe_acls: super::DescribeAclsAdmissionPort,
38    pub(crate) describe_client_quotas: super::DescribeClientQuotasAdmissionPort,
39    pub(crate) alter_client_quotas: super::AlterClientQuotasAdmissionPort,
40    pub(crate) alter_user_scram_credentials: super::AlterUserScramCredentialsAdmissionPort,
41    pub(crate) update_features: super::update_features::UpdateFeaturesAdmissionPort,
42    pub(crate) unregister_broker: super::unregister_broker::UnregisterBrokerAdmissionPort,
43    pub(crate) describe_user_scram_credentials: super::DescribeUserScramCredentialsAdmissionPort,
44    pub(crate) describe_metadata_quorum: super::DescribeMetadataQuorumAdmissionPort,
45    pub(crate) describe_producers: super::AdminDescribeProducersAdmissionPort,
46    pub(crate) describe_topic_partitions: super::AdminDescribeTopicPartitionsAdmissionPort,
47    pub(crate) describe_transactions: super::AdminDescribeTransactionsAdmissionPort,
48    pub(crate) fence_producers: super::AdminFenceProducersAdmissionPort,
49    pub(crate) list_transactions: super::AdminListTransactionsAdmissionPort,
50    pub(crate) list_client_metrics_resources: ListClientMetricsResourcesAdmissionPort,
51    pub(crate) list_config_resources: ListConfigResourcesAdmissionPort,
52    pub(crate) describe_cluster: super::DescribeClusterAdmissionPort,
53    pub(crate) describe_consumer_groups: super::DescribeConsumerGroupsAdmissionPort,
54    pub(crate) describe_features: super::describe_features::DescribeFeaturesAdmissionPort,
55    pub(crate) describe_log_dirs: super::DescribeLogDirsAdmissionPort,
56    pub(crate) describe_replica_log_dirs: super::DescribeReplicaLogDirsAdmissionPort,
57    pub(crate) create_partitions: super::CreatePartitionsAdmissionPort,
58    pub(crate) describe_topics: super::DescribeTopicsAdmissionPort,
59    pub(crate) describe_configs: super::DescribeConfigsAdmissionPort,
60    pub(crate) incremental_alter_configs: super::IncrementalAlterConfigsAdmissionPort,
61    pub(crate) legacy_alter_configs: super::LegacyAlterConfigsAdmissionPort,
62    pub(crate) list_consumer_group_offsets: super::ListConsumerGroupOffsetsAdmissionPort,
63    pub(crate) list_consumer_groups: super::ListConsumerGroupsAdmissionPort,
64    pub(crate) delete_consumer_group_offsets: super::DeleteConsumerGroupOffsetsAdmissionPort,
65    pub(crate) delete_consumer_groups: super::DeleteConsumerGroupsAdmissionPort,
66    pub(crate) alter_consumer_group_offsets: super::AlterConsumerGroupOffsetsAdmissionPort,
67    pub(crate) list_offsets: super::AdminListOffsetsAdmissionPort,
68    pub(crate) list_partition_reassignments: super::ListPartitionReassignmentsAdmissionPort,
69    pub(crate) alter_partition_reassignments: super::AlterPartitionReassignmentsAdmissionPort,
70    pub(crate) alter_replica_log_dirs: super::AlterReplicaLogDirsAdmissionPort,
71    pub(crate) elect_leaders: super::ElectLeadersAdmissionPort,
72    pub(crate) remove_consumer_group_members: super::RemoveConsumerGroupMembersAdmissionPort,
73}
74
75/// Cheaply cloneable handle to the concrete admin shards.
76#[derive(Clone)]
77pub struct AdminHandle {
78    pub(super) abort_partition_transaction:
79        super::abort_partition_transaction::AbortPartitionTransactionAdmissionPort,
80    pub(super) add_raft_voter: super::add_raft_voter::AddRaftVoterAdmissionPort,
81    pub(super) remove_raft_voter: super::remove_raft_voter::RemoveRaftVoterAdmissionPort,
82    pub(super) create_topics: CreateTopicsAdmissionPort,
83    pub(super) create_acls: super::CreateAclsAdmissionPort,
84    pub(super) create_delegation_token: super::CreateDelegationTokenAdmissionPort,
85    pub(super) describe_delegation_tokens: super::DescribeDelegationTokensAdmissionPort,
86    pub(super) renew_delegation_token: super::RenewDelegationTokenAdmissionPort,
87    pub(super) expire_delegation_token: super::ExpireDelegationTokenAdmissionPort,
88    pub(super) delete_acls: super::DeleteAclsAdmissionPort,
89    pub(super) delete_topics: DeleteTopicsAdmissionPort,
90    pub(super) delete_records: super::DeleteRecordsAdmissionPort,
91    pub(super) delete_share_group_offsets:
92        super::delete_share_group_offsets::DeleteShareGroupOffsetsAdmissionPort,
93    pub(super) list_share_group_offsets:
94        super::list_share_group_offsets::ListShareGroupOffsetsAdmissionPort,
95    pub(super) alter_share_group_offsets:
96        super::alter_share_group_offsets::AlterShareGroupOffsetsAdmissionPort,
97    pub(super) describe_share_group: super::describe_share_group::DescribeShareGroupAdmissionPort,
98    pub(super) describe_streams_group:
99        super::describe_streams_group::DescribeStreamsGroupAdmissionPort,
100    pub(super) describe_acls: super::DescribeAclsAdmissionPort,
101    pub(super) describe_client_quotas: super::DescribeClientQuotasAdmissionPort,
102    pub(super) alter_client_quotas: super::AlterClientQuotasAdmissionPort,
103    pub(super) alter_user_scram_credentials: super::AlterUserScramCredentialsAdmissionPort,
104    pub(super) update_features: super::update_features::UpdateFeaturesAdmissionPort,
105    pub(super) unregister_broker: super::unregister_broker::UnregisterBrokerAdmissionPort,
106    pub(super) describe_user_scram_credentials: super::DescribeUserScramCredentialsAdmissionPort,
107    pub(super) describe_metadata_quorum: super::DescribeMetadataQuorumAdmissionPort,
108    pub(super) describe_producers: super::AdminDescribeProducersAdmissionPort,
109    pub(super) describe_topic_partitions: super::AdminDescribeTopicPartitionsAdmissionPort,
110    pub(super) describe_transactions: super::AdminDescribeTransactionsAdmissionPort,
111    pub(super) fence_producers: super::AdminFenceProducersAdmissionPort,
112    pub(super) list_transactions: super::AdminListTransactionsAdmissionPort,
113    pub(super) list_client_metrics_resources: ListClientMetricsResourcesAdmissionPort,
114    pub(super) list_config_resources: ListConfigResourcesAdmissionPort,
115    pub(super) describe_cluster: super::DescribeClusterAdmissionPort,
116    pub(super) describe_consumer_groups: super::DescribeConsumerGroupsAdmissionPort,
117    pub(super) describe_features: super::describe_features::DescribeFeaturesAdmissionPort,
118    pub(super) describe_log_dirs: super::DescribeLogDirsAdmissionPort,
119    pub(super) describe_replica_log_dirs: super::DescribeReplicaLogDirsAdmissionPort,
120    pub(super) create_partitions: super::CreatePartitionsAdmissionPort,
121    pub(super) describe_topics: super::DescribeTopicsAdmissionPort,
122    pub(super) describe_configs: super::DescribeConfigsAdmissionPort,
123    pub(super) incremental_alter_configs: super::IncrementalAlterConfigsAdmissionPort,
124    pub(super) legacy_alter_configs: super::LegacyAlterConfigsAdmissionPort,
125    pub(super) list_consumer_group_offsets: super::ListConsumerGroupOffsetsAdmissionPort,
126    pub(super) list_consumer_groups: super::ListConsumerGroupsAdmissionPort,
127    pub(super) delete_consumer_group_offsets: super::DeleteConsumerGroupOffsetsAdmissionPort,
128    pub(super) delete_consumer_groups: super::DeleteConsumerGroupsAdmissionPort,
129    pub(super) alter_consumer_group_offsets: super::AlterConsumerGroupOffsetsAdmissionPort,
130    pub(super) list_offsets: super::AdminListOffsetsAdmissionPort,
131    pub(super) list_partition_reassignments: super::ListPartitionReassignmentsAdmissionPort,
132    pub(super) alter_partition_reassignments: super::AlterPartitionReassignmentsAdmissionPort,
133    pub(super) alter_replica_log_dirs: super::AlterReplicaLogDirsAdmissionPort,
134    pub(super) elect_leaders: super::ElectLeadersAdmissionPort,
135    pub(super) remove_consumer_group_members: super::RemoveConsumerGroupMembersAdmissionPort,
136    pub(super) clock: Arc<MonotonicClock>,
137    _lifetime: Arc<dyn Send + Sync>,
138}
139
140impl AdminHandle {
141    pub(crate) fn new(
142        ports: AdminAdmissionPorts,
143        clock: Arc<MonotonicClock>,
144        lifetime: Arc<dyn Send + Sync>,
145    ) -> Self {
146        Self {
147            abort_partition_transaction: ports.abort_partition_transaction,
148            add_raft_voter: ports.add_raft_voter,
149            remove_raft_voter: ports.remove_raft_voter,
150            create_topics: ports.create_topics,
151            create_acls: ports.create_acls,
152            create_delegation_token: ports.create_delegation_token,
153            describe_delegation_tokens: ports.describe_delegation_tokens,
154            renew_delegation_token: ports.renew_delegation_token,
155            expire_delegation_token: ports.expire_delegation_token,
156            delete_acls: ports.delete_acls,
157            delete_topics: ports.delete_topics,
158            delete_records: ports.delete_records,
159            delete_share_group_offsets: ports.delete_share_group_offsets,
160            list_share_group_offsets: ports.list_share_group_offsets,
161            alter_share_group_offsets: ports.alter_share_group_offsets,
162            describe_share_group: ports.describe_share_group,
163            describe_streams_group: ports.describe_streams_group,
164            describe_acls: ports.describe_acls,
165            describe_client_quotas: ports.describe_client_quotas,
166            alter_client_quotas: ports.alter_client_quotas,
167            alter_user_scram_credentials: ports.alter_user_scram_credentials,
168            update_features: ports.update_features,
169            unregister_broker: ports.unregister_broker,
170            describe_user_scram_credentials: ports.describe_user_scram_credentials,
171            describe_metadata_quorum: ports.describe_metadata_quorum,
172            describe_producers: ports.describe_producers,
173            describe_topic_partitions: ports.describe_topic_partitions,
174            describe_transactions: ports.describe_transactions,
175            fence_producers: ports.fence_producers,
176            list_transactions: ports.list_transactions,
177            list_client_metrics_resources: ports.list_client_metrics_resources,
178            list_config_resources: ports.list_config_resources,
179            describe_cluster: ports.describe_cluster,
180            describe_consumer_groups: ports.describe_consumer_groups,
181            describe_features: ports.describe_features,
182            describe_log_dirs: ports.describe_log_dirs,
183            describe_replica_log_dirs: ports.describe_replica_log_dirs,
184            create_partitions: ports.create_partitions,
185            describe_topics: ports.describe_topics,
186            describe_configs: ports.describe_configs,
187            incremental_alter_configs: ports.incremental_alter_configs,
188            legacy_alter_configs: ports.legacy_alter_configs,
189            list_consumer_group_offsets: ports.list_consumer_group_offsets,
190            list_consumer_groups: ports.list_consumer_groups,
191            delete_consumer_group_offsets: ports.delete_consumer_group_offsets,
192            delete_consumer_groups: ports.delete_consumer_groups,
193            alter_consumer_group_offsets: ports.alter_consumer_group_offsets,
194            list_offsets: ports.list_offsets,
195            list_partition_reassignments: ports.list_partition_reassignments,
196            alter_partition_reassignments: ports.alter_partition_reassignments,
197            alter_replica_log_dirs: ports.alter_replica_log_dirs,
198            elect_leaders: ports.elect_leaders,
199            remove_consumer_group_members: ports.remove_consumer_group_members,
200            clock,
201            _lifetime: lifetime,
202        }
203    }
204
205    /// Attempts immediate bounded admission using one call-boundary deadline.
206    pub fn try_create_topics(
207        &self,
208        request: CreateTopicsRequest,
209        timeout: Duration,
210    ) -> Result<CreateTopicsAccepted, CreateTopicsAdmissionError> {
211        let capture = self
212            .clock
213            .capture_deadline_after(timeout)
214            .map_err(|_error| {
215                CreateTopicsAdmissionError::new(CreateTopicsAdmissionErrorKind::InvalidDeadline)
216            })?;
217        if timeout.is_zero() {
218            return Err(CreateTopicsAdmissionError::new(
219                CreateTopicsAdmissionErrorKind::InvalidDeadline,
220            ));
221        }
222        let request = request.canonicalize();
223        let retained_bytes = request.retained_charge().ok_or_else(|| {
224            CreateTopicsAdmissionError::new(CreateTopicsAdmissionErrorKind::RetainedBytes)
225        })?;
226        let plan = request.into_plan().map_err(|_error| {
227            CreateTopicsAdmissionError::new(CreateTopicsAdmissionErrorKind::InvalidRequest)
228        })?;
229        let admission = self
230            .create_topics
231            .try_admit(
232                capture.now(),
233                capture.operation_deadline(),
234                plan,
235                retained_bytes,
236            )
237            .map_err(CreateTopicsAdmissionError::new)?;
238        Ok(CreateTopicsAccepted {
239            observer: admission.observer,
240            fault: admission.fault.map(accepted_fault_kind),
241        })
242    }
243}
244
245impl fmt::Debug for AdminHandle {
246    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
247        formatter
248            .debug_struct("AdminHandle")
249            .finish_non_exhaustive()
250    }
251}
252
253pub(super) const fn accepted_fault_kind(
254    fault: super::CreateTopicsHostError,
255) -> CreateTopicsAcceptedFaultKind {
256    match fault {
257        super::CreateTopicsHostError::Wake => CreateTopicsAcceptedFaultKind::Wake,
258        _ => CreateTopicsAcceptedFaultKind::HostInvariant,
259    }
260}
261
262/// Accepted post-commit degradation that cannot revoke operation ownership.
263#[derive(Clone, Copy, Debug, Eq, PartialEq)]
264pub enum CreateTopicsAcceptedFaultKind {
265    /// The coalescing host wake failed after admission committed.
266    Wake,
267    /// An internal host invariant failed after terminal capacity was reserved.
268    HostInvariant,
269}
270
271/// Accepted operation plus any post-commit wake degradation.
272#[must_use = "accepted CreateTopics work must retain its observer"]
273pub struct CreateTopicsAccepted {
274    observer: CreateTopicsObserver,
275    fault: Option<CreateTopicsAcceptedFaultKind>,
276}
277
278impl CreateTopicsAccepted {
279    /// Returns any post-commit degradation without misclassifying ownership.
280    pub const fn fault(&self) -> Option<CreateTopicsAcceptedFaultKind> {
281        self.fault
282    }
283
284    /// Consumes the acceptance envelope into its named observer.
285    pub fn into_observer(self) -> CreateTopicsObserver {
286        self.observer
287    }
288}
289
290impl fmt::Debug for CreateTopicsAccepted {
291    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
292        formatter
293            .debug_struct("CreateTopicsAccepted")
294            .field("observer", &self.observer)
295            .field("fault", &self.fault)
296            .finish()
297    }
298}