Skip to main content

krabka_client_admin/
delegation_tokens.rs

1//! KIP-48 delegation tokens, as Kafka's `Admin.createDelegationToken`,
2//! `renewDelegationToken`, `expireDelegationToken`, and
3//! `describeDelegationToken`.
4//!
5//! Each call takes an options struct that mirrors Kafka's
6//! `CreateDelegationTokenOptions`, `RenewDelegationTokenOptions`,
7//! `ExpireDelegationTokenOptions`, or `DescribeDelegationTokenOptions`, and
8//! sends one request on the admin connection, as `KafkaAdminClient` sends it
9//! to the least-loaded node. A non-zero top-level error code becomes
10//! [`AdminError::Broker`], as Kafka completes the call with
11//! `response.error().exception()`.
12
13use bytes::Bytes;
14use krabka_protocol::owned::{
15    create_delegation_token_request::{CreatableRenewers, CreateDelegationTokenRequest},
16    create_delegation_token_response::CreateDelegationTokenResponse,
17    describe_delegation_token_request::{
18        DescribeDelegationTokenOwner, DescribeDelegationTokenRequest,
19    },
20    describe_delegation_token_response::{
21        DescribeDelegationTokenResponse, DescribedDelegationToken,
22    },
23    expire_delegation_token_request::ExpireDelegationTokenRequest,
24    renew_delegation_token_request::RenewDelegationTokenRequest,
25};
26use krabka_security::KafkaPrincipal;
27use krabka_units::{
28    Time,
29    convert::{TimeExt as _, wire::opt_time_to_millis_i64},
30};
31
32use crate::{AdminClient, AdminError, kafka_error_name};
33
34/// The first `CreateDelegationToken` version with the owner fields
35/// (KIP-373).
36const CREATE_WITH_OWNER_MIN_VERSION: i16 = 3;
37
38/// What [`AdminClient::create_delegation_token`] asks for, as Kafka's
39/// `CreateDelegationTokenOptions`. The default mints a token that the caller
40/// owns, with no renewers and the broker's maximum lifetime.
41#[derive(Debug, Clone, Default, PartialEq, bon::Builder)]
42pub struct CreateDelegationTokenOptions {
43    /// The owner of the token, of any principal type. `None` makes the
44    /// caller the owner. Another owner needs the `CreateTokens` operation on
45    /// the owner's `User` resource, and `CreateDelegationToken` v3 (KIP-373).
46    pub owner: Option<KafkaPrincipal>,
47    /// The principals that may renew the token.
48    #[builder(default)]
49    pub renewers: Vec<KafkaPrincipal>,
50    /// The maximum lifetime of the token. `None` sends Kafka's `-1`, and the
51    /// broker then uses `delegation.token.max.lifetime.ms`. The broker also
52    /// uses that ceiling for a lifetime of zero or less, and caps a longer
53    /// one at it.
54    #[builder(with = |millis: i64| Time::from_millis(millis))]
55    pub max_lifetime: Option<Time>,
56}
57
58/// What [`AdminClient::renew_delegation_token`] asks for, as Kafka's
59/// `RenewDelegationTokenOptions`.
60#[derive(Debug, Clone, Copy, Default, PartialEq, bon::Builder)]
61pub struct RenewDelegationTokenOptions {
62    /// How far past now to move the expiry. `None` sends Kafka's `-1`, and
63    /// the broker then uses `delegation.token.expiry.time.ms`. The broker
64    /// also uses that default for a period of zero or less, caps a longer
65    /// one at it, and never moves the expiry past the token's maximum
66    /// timestamp.
67    #[builder(with = |millis: i64| Time::from_millis(millis))]
68    pub renew_time_period: Option<Time>,
69}
70
71/// What [`AdminClient::expire_delegation_token`] asks for, as Kafka's
72/// `ExpireDelegationTokenOptions`.
73#[derive(Debug, Clone, Copy, Default, PartialEq, bon::Builder)]
74pub struct ExpireDelegationTokenOptions {
75    /// How far past now the token expires. `None` sends Kafka's `-1`, which
76    /// expires the token now, as does any negative period. A period of zero
77    /// or more sets the expiry to that time, capped at the token's maximum
78    /// timestamp.
79    #[builder(with = |millis: i64| Time::from_millis(millis))]
80    pub expiry_time_period: Option<Time>,
81}
82
83/// What [`AdminClient::describe_delegation_token`] asks for, as Kafka's
84/// `DescribeDelegationTokenOptions`. The default describes every token that
85/// the caller may describe.
86#[derive(Debug, Clone, Default, PartialEq, Eq, bon::Builder)]
87pub struct DescribeDelegationTokenOptions {
88    /// The owners whose tokens to describe. `None` sends a null owner list,
89    /// and the broker returns every token that the caller owns or may
90    /// describe. An empty list sends an empty owner list, and the broker
91    /// returns no tokens.
92    pub owners: Option<Vec<KafkaPrincipal>>,
93}
94
95/// One delegation token, as Kafka's `DelegationToken` with its
96/// `TokenInformation`.
97#[derive(Debug, Clone, PartialEq, Eq)]
98pub struct DelegationToken {
99    /// The token ID, which a client presents as its SCRAM user name.
100    pub token_id: String,
101    /// The HMAC of the token, which a client presents as its SCRAM password.
102    pub hmac: Vec<u8>,
103    /// The principal that owns the token.
104    pub owner: KafkaPrincipal,
105    /// The principal that asked for the token. It differs from
106    /// [`owner`](Self::owner) when a caller created a token for another
107    /// owner.
108    pub token_requester: KafkaPrincipal,
109    /// The principals that may renew the token.
110    pub renewers: Vec<KafkaPrincipal>,
111    /// When the broker issued the token, in epoch milliseconds.
112    pub issue_timestamp_ms: i64,
113    /// When the token expires unless someone renews it, in epoch
114    /// milliseconds.
115    pub expiry_timestamp_ms: i64,
116    /// The latest expiry that a renewal can set, in epoch milliseconds.
117    pub max_timestamp_ms: i64,
118}
119
120impl AdminClient {
121    /// Creates a delegation token, as Kafka's `createDelegationToken`
122    /// operation does.
123    ///
124    /// The broker does not return the renewers, so the result has the
125    /// renewers of `options`, as Kafka's result does. With an
126    /// [`owner`](CreateDelegationTokenOptions::owner) the client negotiates
127    /// `CreateDelegationToken` v3 or higher, as Kafka's request refuses to
128    /// write the owner fields below v3.
129    ///
130    /// # Errors
131    ///
132    /// Returns [`AdminError::Broker`] for a non-zero error code, such as
133    /// `DELEGATION_TOKEN_AUTH_DISABLED` (61),
134    /// `DELEGATION_TOKEN_REQUEST_NOT_ALLOWED` (64),
135    /// `DELEGATION_TOKEN_AUTHORIZATION_FAILED` (65), or
136    /// `INVALID_PRINCIPAL_TYPE` (67). Returns [`AdminError::Transport`] when
137    /// the connection fails, or when an owner is set and the broker does not
138    /// support v3.
139    pub async fn create_delegation_token(
140        &self,
141        options: &CreateDelegationTokenOptions,
142    ) -> Result<DelegationToken, AdminError> {
143        let request = create_request(options);
144        let response = if options.owner.is_some() {
145            self.conn
146                .send_at_least(request, CREATE_WITH_OWNER_MIN_VERSION)
147                .await?
148        } else {
149            self.conn.send(request).await?
150        };
151        created_token(response, &options.renewers)
152    }
153
154    /// Renews the delegation token with `hmac`, as Kafka's
155    /// `renewDelegationToken` operation does, and returns its new expiry in
156    /// epoch milliseconds.
157    ///
158    /// # Errors
159    ///
160    /// Returns [`AdminError::Broker`] for a non-zero error code, such as
161    /// `DELEGATION_TOKEN_NOT_FOUND` (62), `DELEGATION_TOKEN_OWNER_MISMATCH`
162    /// (63), or `DELEGATION_TOKEN_EXPIRED` (66). Returns
163    /// [`AdminError::Transport`] when the connection fails.
164    pub async fn renew_delegation_token(
165        &self,
166        hmac: &[u8],
167        options: RenewDelegationTokenOptions,
168    ) -> Result<i64, AdminError> {
169        let response = self.conn.send(renew_request(hmac, options)).await?;
170        check("RenewDelegationToken", response.error_code)?;
171        Ok(response.expiry_timestamp_ms)
172    }
173
174    /// Expires the delegation token with `hmac`, as Kafka's
175    /// `expireDelegationToken` operation does, and returns the expiry that
176    /// the broker set, in epoch milliseconds. A token that expires now gets
177    /// the broker's clock at the time of the request.
178    ///
179    /// # Errors
180    ///
181    /// Returns [`AdminError::Broker`] for a non-zero error code, such as
182    /// `DELEGATION_TOKEN_NOT_FOUND` (62), `DELEGATION_TOKEN_OWNER_MISMATCH`
183    /// (63), or `DELEGATION_TOKEN_EXPIRED` (66). Returns
184    /// [`AdminError::Transport`] when the connection fails.
185    pub async fn expire_delegation_token(
186        &self,
187        hmac: &[u8],
188        options: ExpireDelegationTokenOptions,
189    ) -> Result<i64, AdminError> {
190        let response = self.conn.send(expire_request(hmac, options)).await?;
191        check("ExpireDelegationToken", response.error_code)?;
192        Ok(response.expiry_timestamp_ms)
193    }
194
195    /// Describes the delegation tokens that `options` selects, as Kafka's
196    /// `describeDelegationToken` operation does.
197    ///
198    /// # Errors
199    ///
200    /// Returns [`AdminError::Broker`] for a non-zero error code, such as
201    /// `DELEGATION_TOKEN_AUTH_DISABLED` (61) or
202    /// `DELEGATION_TOKEN_REQUEST_NOT_ALLOWED` (64). Returns
203    /// [`AdminError::Transport`] when the connection fails.
204    pub async fn describe_delegation_token(
205        &self,
206        options: &DescribeDelegationTokenOptions,
207    ) -> Result<Vec<DelegationToken>, AdminError> {
208        let response = self.conn.send(describe_request(options)).await?;
209        described_tokens(response)
210    }
211}
212
213/// The `CreateDelegationToken` request of `options`, as
214/// `KafkaAdminClient.createDelegationToken` builds it. With no owner the
215/// owner fields keep their empty-string defaults, as Kafka's
216/// `CreateDelegationTokenRequestData` does, and the broker makes the caller
217/// the owner.
218fn create_request(options: &CreateDelegationTokenOptions) -> CreateDelegationTokenRequest {
219    let mut request = CreateDelegationTokenRequest {
220        renewers: options
221            .renewers
222            .iter()
223            .map(|renewer| CreatableRenewers {
224                principal_type: renewer.principal_type.clone(),
225                principal_name: renewer.name.clone(),
226                ..Default::default()
227            })
228            .collect(),
229        max_lifetime_ms: opt_time_to_millis_i64(options.max_lifetime),
230        ..Default::default()
231    };
232    if let Some(owner) = &options.owner {
233        request.owner_principal_type = Some(owner.principal_type.clone());
234        request.owner_principal_name = Some(owner.name.clone());
235    }
236    request
237}
238
239fn renew_request(hmac: &[u8], options: RenewDelegationTokenOptions) -> RenewDelegationTokenRequest {
240    RenewDelegationTokenRequest {
241        hmac: Bytes::copy_from_slice(hmac),
242        renew_period_ms: opt_time_to_millis_i64(options.renew_time_period),
243        ..Default::default()
244    }
245}
246
247fn expire_request(
248    hmac: &[u8],
249    options: ExpireDelegationTokenOptions,
250) -> ExpireDelegationTokenRequest {
251    ExpireDelegationTokenRequest {
252        hmac: Bytes::copy_from_slice(hmac),
253        expiry_time_period_ms: opt_time_to_millis_i64(options.expiry_time_period),
254        ..Default::default()
255    }
256}
257
258/// The `DescribeDelegationToken` request of `options`, as Kafka's
259/// `DescribeDelegationTokenRequest.Builder` builds it: a null owner list for
260/// no owners, and the listed owners otherwise.
261fn describe_request(options: &DescribeDelegationTokenOptions) -> DescribeDelegationTokenRequest {
262    DescribeDelegationTokenRequest {
263        owners: options.owners.as_ref().map(|owners| {
264            owners
265                .iter()
266                .map(|owner| DescribeDelegationTokenOwner {
267                    principal_type: owner.principal_type.clone(),
268                    principal_name: owner.name.clone(),
269                    ..Default::default()
270                })
271                .collect()
272        }),
273        ..Default::default()
274    }
275}
276
277/// The token of a `CreateDelegationToken` answer, with the renewers that the
278/// request named.
279fn created_token(
280    response: CreateDelegationTokenResponse,
281    renewers: &[KafkaPrincipal],
282) -> Result<DelegationToken, AdminError> {
283    check("CreateDelegationToken", response.error_code)?;
284    let owner = principal(response.principal_type, response.principal_name);
285    Ok(DelegationToken {
286        token_id: response.token_id,
287        hmac: response.hmac.to_vec(),
288        token_requester: requester(
289            &owner,
290            response.token_requester_principal_type,
291            response.token_requester_principal_name,
292        ),
293        owner,
294        renewers: renewers.to_vec(),
295        issue_timestamp_ms: response.issue_timestamp_ms,
296        expiry_timestamp_ms: response.expiry_timestamp_ms,
297        max_timestamp_ms: response.max_timestamp_ms,
298    })
299}
300
301fn described_tokens(
302    response: DescribeDelegationTokenResponse,
303) -> Result<Vec<DelegationToken>, AdminError> {
304    check("DescribeDelegationToken", response.error_code)?;
305    Ok(response.tokens.into_iter().map(described_token).collect())
306}
307
308fn described_token(token: DescribedDelegationToken) -> DelegationToken {
309    let owner = principal(token.principal_type, token.principal_name);
310    DelegationToken {
311        token_id: token.token_id,
312        hmac: token.hmac.to_vec(),
313        token_requester: requester(
314            &owner,
315            token.token_requester_principal_type,
316            token.token_requester_principal_name,
317        ),
318        owner,
319        renewers: token
320            .renewers
321            .into_iter()
322            .map(|renewer| principal(renewer.principal_type, renewer.principal_name))
323            .collect(),
324        issue_timestamp_ms: token.issue_timestamp,
325        expiry_timestamp_ms: token.expiry_timestamp,
326        max_timestamp_ms: token.max_timestamp,
327    }
328}
329
330/// The requester of a token. The requester fields start at v3; below it they
331/// decode empty, and a token could then only be made by its own owner, so the
332/// owner is the requester.
333fn requester(owner: &KafkaPrincipal, principal_type: String, name: String) -> KafkaPrincipal {
334    if principal_type.is_empty() && name.is_empty() {
335        owner.clone()
336    } else {
337        principal(principal_type, name)
338    }
339}
340
341fn principal(principal_type: String, name: String) -> KafkaPrincipal {
342    KafkaPrincipal {
343        principal_type,
344        name,
345    }
346}
347
348/// `Ok` for a zero error code, and [`AdminError::Broker`] for any other.
349fn check(api: &'static str, code: i16) -> Result<(), AdminError> {
350    if code == 0 {
351        return Ok(());
352    }
353    Err(AdminError::Broker {
354        api,
355        code,
356        name: kafka_error_name(code),
357        message: None,
358    })
359}
360
361#[cfg(test)]
362mod tests {
363    use std::sync::{Arc, Mutex};
364
365    use krabka_client_core::{ClientError, MockBroker};
366    use krabka_protocol::{
367        Decode, Encode,
368        owned::{
369            api_versions_request, create_delegation_token_request,
370            describe_delegation_token_request,
371            describe_delegation_token_response::DescribedDelegationTokenRenewer,
372            expire_delegation_token_request,
373            expire_delegation_token_response::ExpireDelegationTokenResponse,
374            renew_delegation_token_request,
375            renew_delegation_token_response::RenewDelegationTokenResponse,
376        },
377    };
378
379    use super::*;
380    use crate::partition_leaders::test_support::{
381        ApiVersionRange, api_versions, decode_request, encode_response, fast_admin,
382    };
383
384    fn user(name: &str) -> KafkaPrincipal {
385        principal("User".to_owned(), name.to_owned())
386    }
387
388    fn group(name: &str) -> KafkaPrincipal {
389        principal("Group".to_owned(), name.to_owned())
390    }
391
392    /// Every delegation-token API up to its latest version.
393    const TOKEN_APIS: [ApiVersionRange; 4] = [
394        ApiVersionRange {
395            api_key: create_delegation_token_request::API_KEY,
396            min_version: 1,
397            max_version: 3,
398        },
399        ApiVersionRange {
400            api_key: renew_delegation_token_request::API_KEY,
401            min_version: 1,
402            max_version: 2,
403        },
404        ApiVersionRange {
405            api_key: expire_delegation_token_request::API_KEY,
406            min_version: 1,
407            max_version: 2,
408        },
409        ApiVersionRange {
410            api_key: describe_delegation_token_request::API_KEY,
411            min_version: 1,
412            max_version: 3,
413        },
414    ];
415
416    /// A mock broker that advertises `apis`, answers each `api_key` request
417    /// with `answer` encoded at the negotiated version, and records the
418    /// requests it decodes. Every token API is flexible from v2.
419    async fn token_broker<Req, Resp>(
420        apis: Vec<ApiVersionRange>,
421        api_key: i16,
422        answer: Resp,
423    ) -> (MockBroker, Arc<Mutex<Vec<Req>>>)
424    where
425        Req: for<'a> Decode<'a> + Send + 'static,
426        Resp: Encode + Send + 'static,
427    {
428        let requests = Arc::new(Mutex::new(Vec::new()));
429        let seen = Arc::clone(&requests);
430        let broker = MockBroker::start(move |key, version, _, body| match key {
431            api_versions_request::API_KEY => Some(api_versions().apis(apis.clone()).call()),
432            key if key == api_key => {
433                let flexible = version >= 2;
434                seen.lock()
435                    .expect("requests lock")
436                    .push(decode_request::<Req>(body, version, flexible));
437                Some(encode_response(&answer, version, flexible))
438            }
439            _ => None,
440        })
441        .await;
442        (broker, requests)
443    }
444
445    type Outcome<T> = Result<T, (&'static str, i16, &'static str)>;
446
447    fn outcome<T>(result: Result<T, AdminError>) -> Outcome<T> {
448        result.map_err(|error| match error {
449            AdminError::Broker {
450                api,
451                code,
452                name,
453                message: None,
454            } => (api, code, name),
455            other => panic!("unexpected error {other:?}"),
456        })
457    }
458
459    fn created_response(error_code: i16) -> CreateDelegationTokenResponse {
460        CreateDelegationTokenResponse {
461            error_code,
462            principal_type: "Group".to_owned(),
463            principal_name: "ops".to_owned(),
464            token_requester_principal_type: "User".to_owned(),
465            token_requester_principal_name: "admin".to_owned(),
466            issue_timestamp_ms: 1_000,
467            expiry_timestamp_ms: 2_000,
468            max_timestamp_ms: 9_000,
469            token_id: "tok-1".to_owned(),
470            hmac: Bytes::from_static(b"\xde\xad"),
471            ..Default::default()
472        }
473    }
474
475    /// Kafka's `createDelegationToken` sends the renewers and the maximum
476    /// lifetime, sets the owner fields only for an owner, and builds the
477    /// token from the answer and the requested renewers.
478    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
479    async fn create_delegation_token_sends_each_option_as_kafka_does() {
480        let token = |renewers| DelegationToken {
481            token_id: "tok-1".to_owned(),
482            hmac: vec![0xde, 0xad],
483            owner: group("ops"),
484            token_requester: user("admin"),
485            renewers,
486            issue_timestamp_ms: 1_000,
487            expiry_timestamp_ms: 2_000,
488            max_timestamp_ms: 9_000,
489        };
490        let renewers = vec![user("bob"), group("ops")];
491        let wire_renewers = vec![
492            CreatableRenewers {
493                principal_type: "User".to_owned(),
494                principal_name: "bob".to_owned(),
495                ..Default::default()
496            },
497            CreatableRenewers {
498                principal_type: "Group".to_owned(),
499                principal_name: "ops".to_owned(),
500                ..Default::default()
501            },
502        ];
503        for (name, options, request, error_code, expected) in [
504            (
505                "defaults",
506                CreateDelegationTokenOptions::builder().build(),
507                CreateDelegationTokenRequest {
508                    owner_principal_type: Some(String::new()),
509                    owner_principal_name: Some(String::new()),
510                    renewers: Vec::new(),
511                    max_lifetime_ms: -1,
512                    ..Default::default()
513                },
514                0,
515                Ok(token(Vec::new())),
516            ),
517            (
518                "owner of another principal type, renewers, lifetime",
519                CreateDelegationTokenOptions::builder()
520                    .owner(group("ops"))
521                    .renewers(renewers.clone())
522                    .max_lifetime(60_000)
523                    .build(),
524                CreateDelegationTokenRequest {
525                    owner_principal_type: Some("Group".to_owned()),
526                    owner_principal_name: Some("ops".to_owned()),
527                    renewers: wire_renewers.clone(),
528                    max_lifetime_ms: 60_000,
529                    ..Default::default()
530                },
531                0,
532                Ok(token(renewers.clone())),
533            ),
534            (
535                "zero lifetime reaches the broker as zero",
536                CreateDelegationTokenOptions::builder()
537                    .max_lifetime(0)
538                    .build(),
539                CreateDelegationTokenRequest {
540                    max_lifetime_ms: 0,
541                    ..Default::default()
542                },
543                0,
544                Ok(token(Vec::new())),
545            ),
546            (
547                "not authorized to create for the owner",
548                CreateDelegationTokenOptions::builder()
549                    .owner(user("alice"))
550                    .build(),
551                CreateDelegationTokenRequest {
552                    owner_principal_type: Some("User".to_owned()),
553                    owner_principal_name: Some("alice".to_owned()),
554                    max_lifetime_ms: -1,
555                    ..Default::default()
556                },
557                65,
558                Err((
559                    "CreateDelegationToken",
560                    65,
561                    "DELEGATION_TOKEN_AUTHORIZATION_FAILED",
562                )),
563            ),
564            (
565                "renewer of an invalid principal type",
566                CreateDelegationTokenOptions::builder()
567                    .renewers(renewers.clone())
568                    .build(),
569                CreateDelegationTokenRequest {
570                    renewers: wire_renewers.clone(),
571                    max_lifetime_ms: -1,
572                    ..Default::default()
573                },
574                67,
575                Err(("CreateDelegationToken", 67, "INVALID_PRINCIPAL_TYPE")),
576            ),
577        ] {
578            let (broker, requests) = token_broker::<CreateDelegationTokenRequest, _>(
579                TOKEN_APIS.to_vec(),
580                create_delegation_token_request::API_KEY,
581                created_response(error_code),
582            )
583            .await;
584            let admin = fast_admin(broker.addr, krabka_units::secs(5)).await;
585
586            let result = outcome(admin.create_delegation_token(&options).await);
587
588            broker.stop();
589            let requests = requests.lock().expect("requests lock").clone();
590            assert2::assert!(
591                (result, requests) == (expected, vec![request]),
592                "case {name}"
593            );
594        }
595    }
596
597    /// The `AdminClientLike` methods forward to the inherent calls: each one
598    /// reaches the broker and returns the inherent call's result.
599    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
600    async fn admin_client_like_forwards_each_token_call() {
601        use crate::AdminClientLike;
602
603        let (create, _) = token_broker::<CreateDelegationTokenRequest, _>(
604            TOKEN_APIS.to_vec(),
605            create_delegation_token_request::API_KEY,
606            created_response(0),
607        )
608        .await;
609        let mut admin = fast_admin(create.addr, krabka_units::secs(5)).await;
610        let created = AdminClientLike::create_delegation_token(
611            &mut admin,
612            &CreateDelegationTokenOptions::builder().build(),
613        )
614        .await
615        .map(|token| token.token_id);
616        create.stop();
617
618        let (renew, _) = token_broker::<RenewDelegationTokenRequest, _>(
619            TOKEN_APIS.to_vec(),
620            renew_delegation_token_request::API_KEY,
621            RenewDelegationTokenResponse {
622                expiry_timestamp_ms: 7_000,
623                ..Default::default()
624            },
625        )
626        .await;
627        let mut admin = fast_admin(renew.addr, krabka_units::secs(5)).await;
628        let renewed = AdminClientLike::renew_delegation_token(
629            &mut admin,
630            b"hmac",
631            RenewDelegationTokenOptions::builder().build(),
632        )
633        .await;
634        renew.stop();
635
636        let (expire, _) = token_broker::<ExpireDelegationTokenRequest, _>(
637            TOKEN_APIS.to_vec(),
638            expire_delegation_token_request::API_KEY,
639            ExpireDelegationTokenResponse {
640                expiry_timestamp_ms: 8_000,
641                ..Default::default()
642            },
643        )
644        .await;
645        let mut admin = fast_admin(expire.addr, krabka_units::secs(5)).await;
646        let expired = AdminClientLike::expire_delegation_token(
647            &mut admin,
648            b"hmac",
649            ExpireDelegationTokenOptions::builder().build(),
650        )
651        .await;
652        expire.stop();
653
654        let (describe, _) = token_broker::<DescribeDelegationTokenRequest, _>(
655            TOKEN_APIS.to_vec(),
656            describe_delegation_token_request::API_KEY,
657            DescribeDelegationTokenResponse::default(),
658        )
659        .await;
660        let mut admin = fast_admin(describe.addr, krabka_units::secs(5)).await;
661        let described = AdminClientLike::describe_delegation_token(
662            &mut admin,
663            &DescribeDelegationTokenOptions::builder().build(),
664        )
665        .await
666        .map(|tokens| tokens.len());
667        describe.stop();
668
669        assert2::assert!(
670            (
671                outcome(created),
672                outcome(renewed),
673                outcome(expired),
674                outcome(described),
675            ) == (Ok("tok-1".to_owned()), Ok(7_000), Ok(8_000), Ok(0))
676        );
677    }
678
679    /// Below v3 the requester fields are absent and decode empty, and a
680    /// token could then only be made by its owner, so the requester of a
681    /// created or described token falls back to the owner. From v3 the answer
682    /// names the requester.
683    #[test]
684    fn a_token_without_requester_fields_names_its_owner_as_requester() {
685        for (name, requester_type, requester_name, expected) in [
686            ("v1 or v2 answer", "", "", user("alice")),
687            ("v3 answer", "User", "admin", user("admin")),
688        ] {
689            let created = created_token(
690                CreateDelegationTokenResponse {
691                    principal_type: "User".to_owned(),
692                    principal_name: "alice".to_owned(),
693                    token_requester_principal_type: requester_type.to_owned(),
694                    token_requester_principal_name: requester_name.to_owned(),
695                    ..Default::default()
696                },
697                &[],
698            )
699            .expect("no error code");
700            let described = described_token(DescribedDelegationToken {
701                principal_type: "User".to_owned(),
702                principal_name: "alice".to_owned(),
703                token_requester_principal_type: requester_type.to_owned(),
704                token_requester_principal_name: requester_name.to_owned(),
705                ..Default::default()
706            });
707            assert2::assert!(
708                (created.token_requester, described.token_requester)
709                    == (expected.clone(), expected),
710                "case {name}"
711            );
712        }
713    }
714
715    /// Kafka's request refuses to write the owner fields below v3, so an
716    /// owner needs v3. Without an owner an older version serves.
717    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
718    async fn create_delegation_token_needs_v3_only_for_an_owner() {
719        for (name, owner, expected) in [
720            ("no owner", None, Ok(1)),
721            (
722                "owner",
723                Some(user("alice")),
724                Err((create_delegation_token_request::API_KEY, 1, 2, 3, 3)),
725            ),
726        ] {
727            let (broker, requests) = token_broker::<CreateDelegationTokenRequest, _>(
728                vec![
729                    ApiVersionRange::builder()
730                        .api_key(create_delegation_token_request::API_KEY)
731                        .min_version(1)
732                        .max_version(2)
733                        .build(),
734                ],
735                create_delegation_token_request::API_KEY,
736                created_response(0),
737            )
738            .await;
739            let admin = fast_admin(broker.addr, krabka_units::secs(5)).await;
740
741            let result = admin
742                .create_delegation_token(
743                    &CreateDelegationTokenOptions::builder()
744                        .maybe_owner(owner)
745                        .build(),
746                )
747                .await
748                .map(|_| requests.lock().expect("requests lock").len())
749                .map_err(|error| match error {
750                    AdminError::Transport(ClientError::IncompatibleVersion {
751                        api_key,
752                        broker_min,
753                        broker_max,
754                        client_min,
755                        client_max,
756                    }) => (api_key, broker_min, broker_max, client_min, client_max),
757                    other => panic!("case {name}: unexpected error {other:?}"),
758                });
759
760            broker.stop();
761            assert2::assert!(result == expected, "case {name}");
762        }
763    }
764
765    /// Kafka's `renewDelegationToken` sends the renew period, `-1` by
766    /// default, and returns the expiry of the answer.
767    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
768    async fn renew_delegation_token_sends_the_period_and_returns_the_expiry() {
769        for (name, renew_time_period, renew_period_ms, error_code, expected) in [
770            ("broker default", None, -1, 0, Ok(5_000)),
771            (
772                "one hour",
773                Some(krabka_units::secs(3_600)),
774                3_600_000,
775                0,
776                Ok(5_000),
777            ),
778            (
779                "unknown token",
780                None,
781                -1,
782                62,
783                Err(("RenewDelegationToken", 62, "DELEGATION_TOKEN_NOT_FOUND")),
784            ),
785            (
786                "expired token",
787                None,
788                -1,
789                66,
790                Err(("RenewDelegationToken", 66, "DELEGATION_TOKEN_EXPIRED")),
791            ),
792        ] {
793            let (broker, requests) = token_broker::<RenewDelegationTokenRequest, _>(
794                TOKEN_APIS.to_vec(),
795                renew_delegation_token_request::API_KEY,
796                RenewDelegationTokenResponse {
797                    error_code,
798                    expiry_timestamp_ms: 5_000,
799                    ..Default::default()
800                },
801            )
802            .await;
803            let admin = fast_admin(broker.addr, krabka_units::secs(5)).await;
804
805            let result = outcome(
806                admin
807                    .renew_delegation_token(
808                        b"\x01\x02",
809                        RenewDelegationTokenOptions::builder()
810                            .maybe_renew_time_period(
811                                renew_time_period.map(krabka_units::convert::TimeExt::millis_i64),
812                            )
813                            .build(),
814                    )
815                    .await,
816            );
817
818            broker.stop();
819            let requests = requests.lock().expect("requests lock").clone();
820            assert2::assert!(
821                (result, requests)
822                    == (
823                        expected,
824                        vec![RenewDelegationTokenRequest {
825                            hmac: Bytes::from_static(b"\x01\x02"),
826                            renew_period_ms,
827                            ..Default::default()
828                        }]
829                    ),
830                "case {name}"
831            );
832        }
833    }
834
835    /// Kafka's `expireDelegationToken` sends the expiry period, `-1` (now)
836    /// by default, and returns the expiry of the answer, which
837    /// `kafka-delegation-tokens` prints as the new expiry date.
838    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
839    async fn expire_delegation_token_sends_the_period_and_returns_the_expiry() {
840        for (name, expiry_time_period, expiry_time_period_ms, error_code, expected) in [
841            ("now", None, -1, 0, Ok(7_000)),
842            ("in zero ms", Some(krabka_units::millis(0)), 0, 0, Ok(7_000)),
843            (
844                "in one minute",
845                Some(krabka_units::secs(60)),
846                60_000,
847                0,
848                Ok(7_000),
849            ),
850            (
851                "not a renewer",
852                None,
853                -1,
854                63,
855                Err((
856                    "ExpireDelegationToken",
857                    63,
858                    "DELEGATION_TOKEN_OWNER_MISMATCH",
859                )),
860            ),
861        ] {
862            let (broker, requests) = token_broker::<ExpireDelegationTokenRequest, _>(
863                TOKEN_APIS.to_vec(),
864                expire_delegation_token_request::API_KEY,
865                ExpireDelegationTokenResponse {
866                    error_code,
867                    expiry_timestamp_ms: 7_000,
868                    ..Default::default()
869                },
870            )
871            .await;
872            let admin = fast_admin(broker.addr, krabka_units::secs(5)).await;
873
874            let result = outcome(
875                admin
876                    .expire_delegation_token(
877                        b"\xaa",
878                        ExpireDelegationTokenOptions::builder()
879                            .maybe_expiry_time_period(
880                                expiry_time_period.map(krabka_units::convert::TimeExt::millis_i64),
881                            )
882                            .build(),
883                    )
884                    .await,
885            );
886
887            broker.stop();
888            let requests = requests.lock().expect("requests lock").clone();
889            assert2::assert!(
890                (result, requests)
891                    == (
892                        expected,
893                        vec![ExpireDelegationTokenRequest {
894                            hmac: Bytes::from_static(b"\xaa"),
895                            expiry_time_period_ms,
896                            ..Default::default()
897                        }]
898                    ),
899                "case {name}"
900            );
901        }
902    }
903
904    /// Kafka's `describeDelegationToken` sends a null owner list for no
905    /// owners, which asks for every token that the caller may describe, and
906    /// an empty list for an empty list, which asks for none. It maps each
907    /// described token with its requester and renewers.
908    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
909    async fn describe_delegation_token_sends_the_owner_filter_as_kafka_does() {
910        let described = DescribedDelegationToken {
911            principal_type: "User".to_owned(),
912            principal_name: "alice".to_owned(),
913            token_requester_principal_type: "User".to_owned(),
914            token_requester_principal_name: "operator".to_owned(),
915            issue_timestamp: 1_000,
916            expiry_timestamp: 2_000,
917            max_timestamp: 9_000,
918            token_id: "tok-1".to_owned(),
919            hmac: Bytes::from_static(b"\xbe\xef"),
920            renewers: vec![DescribedDelegationTokenRenewer {
921                principal_type: "Group".to_owned(),
922                principal_name: "ops".to_owned(),
923                ..Default::default()
924            }],
925            ..Default::default()
926        };
927        let token = DelegationToken {
928            token_id: "tok-1".to_owned(),
929            hmac: vec![0xbe, 0xef],
930            owner: user("alice"),
931            token_requester: user("operator"),
932            renewers: vec![group("ops")],
933            issue_timestamp_ms: 1_000,
934            expiry_timestamp_ms: 2_000,
935            max_timestamp_ms: 9_000,
936        };
937        let owner = |principal_type: &str, principal_name: &str| DescribeDelegationTokenOwner {
938            principal_type: principal_type.to_owned(),
939            principal_name: principal_name.to_owned(),
940            ..Default::default()
941        };
942        for (name, owners, wire_owners, (error_code, tokens), expected) in [
943            (
944                "every token",
945                None,
946                None,
947                (0, vec![described.clone()]),
948                Ok(vec![token.clone()]),
949            ),
950            (
951                "no owner",
952                Some(Vec::new()),
953                Some(Vec::new()),
954                (0, Vec::new()),
955                Ok(Vec::new()),
956            ),
957            (
958                "owners of two principal types",
959                Some(vec![user("alice"), group("ops")]),
960                Some(vec![owner("User", "alice"), owner("Group", "ops")]),
961                (0, vec![described.clone()]),
962                Ok(vec![token.clone()]),
963            ),
964            (
965                "tokens disabled",
966                None,
967                None,
968                (61, Vec::new()),
969                Err((
970                    "DescribeDelegationToken",
971                    61,
972                    "DELEGATION_TOKEN_AUTH_DISABLED",
973                )),
974            ),
975        ] {
976            let (broker, requests) = token_broker::<DescribeDelegationTokenRequest, _>(
977                TOKEN_APIS.to_vec(),
978                describe_delegation_token_request::API_KEY,
979                DescribeDelegationTokenResponse {
980                    error_code,
981                    tokens,
982                    ..Default::default()
983                },
984            )
985            .await;
986            let admin = fast_admin(broker.addr, krabka_units::secs(5)).await;
987
988            let result = outcome(
989                admin
990                    .describe_delegation_token(
991                        &DescribeDelegationTokenOptions::builder()
992                            .maybe_owners(owners)
993                            .build(),
994                    )
995                    .await,
996            );
997
998            broker.stop();
999            let requests = requests.lock().expect("requests lock").clone();
1000            assert2::assert!(
1001                (result, requests)
1002                    == (
1003                        expected,
1004                        vec![DescribeDelegationTokenRequest {
1005                            owners: wire_owners,
1006                            ..Default::default()
1007                        }]
1008                    ),
1009                "case {name}"
1010            );
1011        }
1012    }
1013}