Skip to main content

kafka_client_engine/
engine.rs

1//! Shared public owner of one reactor-native execution host.
2
3mod admin;
4
5use std::sync::Arc;
6
7use crate::{
8    AssignedConsumerClaimError, AssignedConsumerHandle, EngineConfig, ProducerHandle,
9    engine_host::{
10        EngineHostControl, EngineLifecycle, EngineShutdownError, EngineStartError,
11        StartedEngineHost, start as start_host,
12    },
13};
14
15/// Cheaply cloneable owner of one embedded driver and shared execution host.
16#[derive(Clone)]
17pub struct Engine {
18    pub(crate) inner: Arc<EngineInner>,
19}
20
21pub(crate) struct EngineInner {
22    pub(crate) config: EngineConfig,
23    pub(crate) metrics: crate::driver::owner::observation::DriverObservationHandle,
24    pub(crate) admission: crate::producer::ingress::ProducerAdmissionPort,
25    abort_partition_transaction_admission:
26        crate::admin::AbortPartitionTransactionAdmissionPort,
27    create_topics_admission: crate::admin::CreateTopicsAdmissionPort,
28    create_acls_admission: crate::admin::CreateAclsAdmissionPort,
29    create_delegation_token_admission: crate::admin::CreateDelegationTokenAdmissionPort,
30    describe_delegation_tokens_admission: crate::admin::DescribeDelegationTokensAdmissionPort,
31    renew_delegation_token_admission: crate::admin::RenewDelegationTokenAdmissionPort,
32    expire_delegation_token_admission: crate::admin::ExpireDelegationTokenAdmissionPort,
33    delete_acls_admission: crate::admin::DeleteAclsAdmissionPort,
34    delete_topics_admission: crate::admin::DeleteTopicsAdmissionPort,
35    delete_consumer_groups_admission: crate::admin::DeleteConsumerGroupsAdmissionPort,
36    delete_records_admission: crate::admin::DeleteRecordsAdmissionPort,
37    describe_acls_admission: crate::admin::DescribeAclsAdmissionPort,
38    describe_client_quotas_admission: crate::admin::DescribeClientQuotasAdmissionPort,
39    alter_client_quotas_admission: crate::admin::AlterClientQuotasAdmissionPort,
40    alter_user_scram_credentials_admission: crate::admin::AlterUserScramCredentialsAdmissionPort,
41    update_features_admission: crate::admin::update_features::UpdateFeaturesAdmissionPort,
42    unregister_broker_admission: crate::admin::unregister_broker::UnregisterBrokerAdmissionPort,
43    add_raft_voter_admission: crate::admin::AddRaftVoterAdmissionPort,
44    remove_raft_voter_admission: crate::admin::RemoveRaftVoterAdmissionPort,
45    describe_user_scram_credentials_admission:
46        crate::admin::DescribeUserScramCredentialsAdmissionPort,
47    describe_metadata_quorum_admission: crate::admin::DescribeMetadataQuorumAdmissionPort,
48    describe_producers_admission: crate::admin::AdminDescribeProducersAdmissionPort,
49    describe_topic_partitions_admission: crate::admin::AdminDescribeTopicPartitionsAdmissionPort,
50    describe_transactions_admission: crate::admin::AdminDescribeTransactionsAdmissionPort,
51    fence_producers_admission: crate::admin::AdminFenceProducersAdmissionPort,
52    list_transactions_admission: crate::admin::AdminListTransactionsAdmissionPort,
53    list_client_metrics_resources_admission:
54        crate::admin::list_client_metrics_resources::internal_api::
55            ListClientMetricsResourcesAdmissionPort,
56    list_config_resources_admission:
57        crate::admin::list_config_resources::ListConfigResourcesAdmissionPort,
58    describe_cluster_admission: crate::admin::DescribeClusterAdmissionPort,
59    describe_consumer_groups_admission: crate::admin::DescribeConsumerGroupsAdmissionPort,
60    describe_features_admission: crate::admin::DescribeFeaturesAdmissionPort,
61    describe_log_dirs_admission: crate::admin::DescribeLogDirsAdmissionPort,
62    describe_replica_log_dirs_admission: crate::admin::DescribeReplicaLogDirsAdmissionPort,
63    create_partitions_admission: crate::admin::CreatePartitionsAdmissionPort,
64    describe_topics_admission: crate::admin::DescribeTopicsAdmissionPort,
65    describe_configs_admission: crate::admin::DescribeConfigsAdmissionPort,
66    incremental_alter_configs_admission: crate::admin::IncrementalAlterConfigsAdmissionPort,
67    legacy_alter_configs_admission: crate::admin::LegacyAlterConfigsAdmissionPort,
68    list_consumer_group_offsets_admission: crate::admin::ListConsumerGroupOffsetsAdmissionPort,
69    list_consumer_groups_admission: crate::admin::ListConsumerGroupsAdmissionPort,
70    delete_consumer_group_offsets_admission: crate::admin::DeleteConsumerGroupOffsetsAdmissionPort,
71    delete_share_group_offsets_admission:
72        crate::admin::delete_share_group_offsets::DeleteShareGroupOffsetsAdmissionPort,
73    list_share_group_offsets_admission:
74        crate::admin::list_share_group_offsets::ListShareGroupOffsetsAdmissionPort,
75    alter_share_group_offsets_admission:
76        crate::admin::alter_share_group_offsets::AlterShareGroupOffsetsAdmissionPort,
77    describe_share_group_admission:
78        crate::admin::describe_share_group::DescribeShareGroupAdmissionPort,
79    describe_streams_group_admission:
80        crate::admin::describe_streams_group::DescribeStreamsGroupAdmissionPort,
81    alter_consumer_group_offsets_admission: crate::admin::AlterConsumerGroupOffsetsAdmissionPort,
82    list_offsets_admission: crate::admin::AdminListOffsetsAdmissionPort,
83    list_partition_reassignments_admission: crate::admin::ListPartitionReassignmentsAdmissionPort,
84    alter_partition_reassignments_admission: crate::admin::AlterPartitionReassignmentsAdmissionPort,
85    alter_replica_log_dirs_admission: crate::admin::AlterReplicaLogDirsAdmissionPort,
86    elect_leaders_admission: crate::admin::ElectLeadersAdmissionPort,
87    remove_consumer_group_members_admission: crate::admin::RemoveConsumerGroupMembersAdmissionPort,
88    assigned_consumer: crate::consumer::AssignedConsumerClaimSlot,
89    assigned_consumer_admission: crate::consumer::AssignedConsumerAdmissionCloser,
90    pub(crate) group_consumer: crate::consumer::GroupConsumerPort,
91    pub(crate) transaction_initialization:
92        crate::transaction::TransactionInitializationAdmissionPort,
93    clock: Arc<crate::clock::MonotonicClock>,
94    control: Arc<EngineHostControl>,
95    lifecycle: Arc<EngineLifecycle>,
96}
97
98impl Engine {
99    /// Validates every local bound and starts one native host thread.
100    #[allow(
101        clippy::too_many_lines,
102        reason = "the one-to-one transfer of every admission capability into the shared owner stays explicit and auditable"
103    )]
104    pub fn start(config: EngineConfig) -> Result<Self, EngineStartError> {
105        let validated = config.validate().map_err(EngineStartError::configuration)?;
106        let StartedEngineHost {
107            metrics,
108            admission,
109            abort_partition_transaction_admission,
110            create_topics_admission,
111            create_acls_admission,
112            create_delegation_token_admission,
113            describe_delegation_tokens_admission,
114            renew_delegation_token_admission,
115            expire_delegation_token_admission,
116            delete_acls_admission,
117            delete_topics_admission,
118            delete_consumer_groups_admission,
119            delete_records_admission,
120            describe_acls_admission,
121            describe_client_quotas_admission,
122            alter_client_quotas_admission,
123            alter_user_scram_credentials_admission,
124            update_features_admission,
125            unregister_broker_admission,
126            add_raft_voter_admission,
127            remove_raft_voter_admission,
128            describe_user_scram_credentials_admission,
129            describe_metadata_quorum_admission,
130            describe_producers_admission,
131            describe_topic_partitions_admission,
132            describe_transactions_admission,
133            fence_producers_admission,
134            list_transactions_admission,
135            list_client_metrics_resources_admission,
136            list_config_resources_admission,
137            describe_cluster_admission,
138            describe_consumer_groups_admission,
139            describe_features_admission,
140            describe_log_dirs_admission,
141            describe_replica_log_dirs_admission,
142            create_partitions_admission,
143            describe_topics_admission,
144            describe_configs_admission,
145            incremental_alter_configs_admission,
146            legacy_alter_configs_admission,
147            list_consumer_group_offsets_admission,
148            list_consumer_groups_admission,
149            delete_consumer_group_offsets_admission,
150            delete_share_group_offsets_admission,
151            list_share_group_offsets_admission,
152            alter_share_group_offsets_admission,
153            describe_share_group_admission,
154            describe_streams_group_admission,
155            alter_consumer_group_offsets_admission,
156            list_offsets_admission,
157            list_partition_reassignments_admission,
158            alter_partition_reassignments_admission,
159            alter_replica_log_dirs_admission,
160            elect_leaders_admission,
161            remove_consumer_group_members_admission,
162            assigned_consumer,
163            group_consumer,
164            transaction_initialization,
165            clock,
166            control,
167            lifecycle,
168        } = start_host(&config, validated)?;
169        let (assigned_consumer, assigned_consumer_admission) =
170            crate::consumer::AssignedConsumerClaimSlot::create_for_engine(assigned_consumer);
171        Ok(Self {
172            inner: Arc::new(EngineInner {
173                config,
174                metrics,
175                admission,
176                abort_partition_transaction_admission,
177                create_topics_admission,
178                create_acls_admission,
179                create_delegation_token_admission,
180                describe_delegation_tokens_admission,
181                renew_delegation_token_admission,
182                expire_delegation_token_admission,
183                delete_acls_admission,
184                delete_topics_admission,
185                delete_consumer_groups_admission,
186                delete_records_admission,
187                describe_acls_admission,
188                describe_client_quotas_admission,
189                alter_client_quotas_admission,
190                alter_user_scram_credentials_admission,
191                update_features_admission,
192                unregister_broker_admission,
193                add_raft_voter_admission,
194                remove_raft_voter_admission,
195                describe_user_scram_credentials_admission,
196                describe_metadata_quorum_admission,
197                describe_producers_admission,
198                describe_topic_partitions_admission,
199                describe_transactions_admission,
200                fence_producers_admission,
201                list_transactions_admission,
202                list_client_metrics_resources_admission,
203                list_config_resources_admission,
204                describe_cluster_admission,
205                describe_consumer_groups_admission,
206                describe_features_admission,
207                describe_log_dirs_admission,
208                describe_replica_log_dirs_admission,
209                create_partitions_admission,
210                describe_topics_admission,
211                describe_configs_admission,
212                incremental_alter_configs_admission,
213                legacy_alter_configs_admission,
214                list_consumer_group_offsets_admission,
215                list_consumer_groups_admission,
216                delete_consumer_group_offsets_admission,
217                delete_share_group_offsets_admission,
218                list_share_group_offsets_admission,
219                alter_share_group_offsets_admission,
220                describe_share_group_admission,
221                describe_streams_group_admission,
222                alter_consumer_group_offsets_admission,
223                list_offsets_admission,
224                list_partition_reassignments_admission,
225                alter_partition_reassignments_admission,
226                alter_replica_log_dirs_admission,
227                elect_leaders_admission,
228                remove_consumer_group_members_admission,
229                assigned_consumer,
230                assigned_consumer_admission,
231                group_consumer,
232                transaction_initialization,
233                clock,
234                control,
235                lifecycle,
236            }),
237        })
238    }
239    /// Returns a runtime-neutral producer handle retaining this host.
240    pub fn producer(&self) -> ProducerHandle {
241        let lifetime: Arc<dyn Send + Sync> = self.inner.clone();
242        ProducerHandle::from_port(
243            self.inner.admission.clone(),
244            Arc::clone(&self.inner.clock),
245            self.inner.config.producer_limits().in_flight_records(),
246            lifetime,
247        )
248    }
249    /// Claims the host's sole directly assigned consumer.
250    pub fn claim_assigned_consumer(
251        &self,
252    ) -> Result<AssignedConsumerHandle, AssignedConsumerClaimError> {
253        let lifetime: Arc<dyn Send + Sync> = self.inner.clone();
254        self.inner.assigned_consumer.claim(lifetime)
255    }
256    /// Returns immutable engine configuration.
257    pub fn config(&self) -> &EngineConfig {
258        &self.inner.config
259    }
260
261    /// Waits for the host's retained report after native resource cleanup.
262    pub fn shutdown(&self) -> Result<(), EngineShutdownError> {
263        self.inner.shutdown()
264    }
265
266    /// Permanently closes admission and requests host shutdown without waiting.
267    pub fn request_shutdown(&self) {
268        self.inner.close_admission();
269        self.inner.lifecycle.request(&self.inner.control);
270    }
271
272    #[cfg(test)]
273    pub(crate) fn host_snapshot(&self) -> crate::engine_host::EngineHostSnapshot {
274        self.inner.control.snapshot()
275    }
276
277    #[cfg(test)]
278    pub(crate) fn force_host_failure(&self) {
279        self.inner.control.request_failure();
280    }
281
282    #[cfg(test)]
283    pub(crate) fn pause_after_produce_admission(&self) {
284        self.inner.control.request_pause_after_produce_admission();
285    }
286
287    #[cfg(test)]
288    pub(crate) fn host_is_closed(&self) -> bool {
289        self.inner.lifecycle.is_closed()
290    }
291
292    #[cfg(test)]
293    pub(crate) fn host_is_closing(&self) -> bool {
294        self.inner.lifecycle.is_closing()
295    }
296
297    #[cfg(test)]
298    pub(crate) fn completion_notifier_thread_count(&self) -> usize {
299        self.inner.lifecycle.notifier_thread_count()
300    }
301
302    #[cfg(test)]
303    pub(crate) fn host_probe(&self) -> EngineHostProbe {
304        EngineHostProbe {
305            lifecycle: Arc::clone(&self.inner.lifecycle),
306        }
307    }
308}
309
310impl EngineInner {
311    fn shutdown(&self) -> Result<(), EngineShutdownError> {
312        self.close_admission();
313        self.lifecycle.request_and_wait(&self.control)
314    }
315
316    fn close_admission(&self) {
317        let _close_result = self.admission.close_admission();
318        self.close_admin_admission();
319        let _close_result = self.assigned_consumer_admission.close();
320        self.group_consumer.close_admission();
321        self.transaction_initialization.close_admission();
322    }
323}
324
325impl Drop for EngineInner {
326    fn drop(&mut self) {
327        self.close_admission();
328        self.lifecycle.request(&self.control);
329    }
330}
331
332#[cfg(test)]
333pub(crate) struct EngineHostProbe {
334    lifecycle: Arc<EngineLifecycle>,
335}
336
337#[cfg(test)]
338impl EngineHostProbe {
339    pub(crate) fn wait_closed(&self, timeout: std::time::Duration) -> bool {
340        self.lifecycle.wait_closed(timeout)
341    }
342}