Skip to main content

confluent_kafka/common/acl/
access_control_entry.rs

1// Copyright 2025 Confluent Inc.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! Access control entries.
16//!
17//! Corresponds to `org.apache.kafka.common.acl.AccessControlEntry`.
18
19use crate::common::Error;
20
21use super::access_control_entry_data::AccessControlEntryData;
22use super::{AccessControlEntryFilter, AclOperation, AclPermissionType};
23
24/// Represents an access control entry. ACEs are a tuple of principal, host,
25/// operation, and permissionType.
26#[derive(Clone, Debug, PartialEq, Eq, Hash)]
27#[doc(alias = "org.apache.kafka.common.acl.AccessControlEntry")]
28pub struct AccessControlEntry {
29    pub(crate) data: AccessControlEntryData,
30}
31
32impl AccessControlEntry {
33    /// Create an instance of an access control entry with the provided
34    /// parameters.
35    ///
36    /// # Arguments
37    /// * `principal` - principal
38    /// * `host` - host
39    /// * `operation` - operation, `ANY` is not an allowed operation
40    /// * `permission_type` - permission type, `ANY` is not an allowed type
41    ///
42    /// # Errors
43    ///
44    /// - [`Error::is_local_illegal_argument_error`] if `operation` is
45    ///   [`AclOperation::Any`] or `permission_type` is [`AclPermissionType::Any`]
46    #[doc(alias = "org.apache.kafka.common.acl.AccessControlEntry#AccessControlEntry")]
47    pub fn new(
48        principal: impl Into<String>,
49        host: impl Into<String>,
50        operation: AclOperation,
51        permission_type: AclPermissionType,
52    ) -> Result<AccessControlEntry, Error> {
53        if operation == AclOperation::Any {
54            return Err(Error::local_illegal_argument("operation must not be ANY"));
55        }
56        if permission_type == AclPermissionType::Any {
57            return Err(Error::local_illegal_argument("permissionType must not be ANY"));
58        }
59        Ok(AccessControlEntry {
60            data: AccessControlEntryData::new(Some(principal.into()), Some(host.into()), operation, permission_type),
61        })
62    }
63
64    /// Returns the principal for this entry.
65    #[doc(alias = "org.apache.kafka.common.acl.AccessControlEntry#principal")]
66    pub fn principal(&self) -> &str {
67        // Invariant: a public `AccessControlEntry` always has a non-null
68        // principal (set by `new`).
69        self.data.principal().expect("AccessControlEntry principal is always set")
70    }
71
72    /// Returns the host, or `*` for all hosts.
73    #[doc(alias = "org.apache.kafka.common.acl.AccessControlEntry#host")]
74    pub fn host(&self) -> &str {
75        self.data.host().expect("AccessControlEntry host is always set")
76    }
77
78    /// Returns the `AclOperation`. This method will never return
79    /// [`AclOperation::Any`].
80    #[doc(alias = "org.apache.kafka.common.acl.AccessControlEntry#operation")]
81    pub fn operation(&self) -> AclOperation {
82        self.data.operation()
83    }
84
85    /// Returns the `AclPermissionType`. This method will never return
86    /// [`AclPermissionType::Any`].
87    #[doc(alias = "org.apache.kafka.common.acl.AccessControlEntry#permissionType")]
88    pub fn permission_type(&self) -> AclPermissionType {
89        self.data.permission_type()
90    }
91
92    /// Returns a filter which matches only this `AccessControlEntry`.
93    #[doc(alias = "org.apache.kafka.common.acl.AccessControlEntry#toFilter")]
94    pub fn to_filter(&self) -> AccessControlEntryFilter {
95        AccessControlEntryFilter::with_data(self.data.clone())
96    }
97
98    /// Returns true if this ACE has any UNKNOWN components.
99    #[doc(alias = "org.apache.kafka.common.acl.AccessControlEntry#isUnknown")]
100    pub fn is_unknown(&self) -> bool {
101        self.data.is_unknown()
102    }
103}
104
105impl std::fmt::Display for AccessControlEntry {
106    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
107        write!(f, "{}", self.data)
108    }
109}
110
111#[cfg(test)]
112mod tests {
113    use super::*;
114
115    #[test]
116    fn rejects_any_operation() {
117        let err = AccessControlEntry::new("User:x", "*", AclOperation::Any, AclPermissionType::Allow);
118        assert!(matches!(err, Err(Error::LocalIllegalArgument(_))));
119    }
120
121    #[test]
122    fn rejects_any_permission_type() {
123        let err = AccessControlEntry::new("User:x", "*", AclOperation::Read, AclPermissionType::Any);
124        assert!(matches!(err, Err(Error::LocalIllegalArgument(_))));
125    }
126
127    #[test]
128    fn accessors() {
129        let entry = AccessControlEntry::new("User:x", "host", AclOperation::Read, AclPermissionType::Allow).unwrap();
130        assert_eq!(entry.principal(), "User:x");
131        assert_eq!(entry.host(), "host");
132        assert_eq!(entry.operation(), AclOperation::Read);
133        assert_eq!(entry.permission_type(), AclPermissionType::Allow);
134        assert!(!entry.is_unknown());
135    }
136
137    #[test]
138    fn is_unknown_for_unknown_operation() {
139        let entry = AccessControlEntry::new("User:x", "host", AclOperation::Unknown, AclPermissionType::Allow).unwrap();
140        assert!(entry.is_unknown());
141    }
142}