[KAFKA-13757] Improve the annotations of all related methods of DelegationToken in the Admin class

• Type: Improvement
• Status: Open
• Priority: Major
• Resolution: Unresolved
• Component/s: admin
• Assignee: Unassigned
• Reporter: RivenSun
• Created: 22/Mar/22 13:26
• Updated: 31/Mar/22 02:45

Description

DelegationToken is a great and lightweight feature, but when users actually use it, they get confused.
From the existing official documents/comments on methods/comments on method parameters, the user cannot know what is the specific processing logic of the server and what is the meaning of the returned fields after he calls the XXXDelegationToken(...) method.

After reading the source code, I briefly sorted out the processing logic of the XXXDelegationToken(...) method on the server side.

1. createDelegationToken：

// 1. if the request sent on PLAINTEXT/1-way SSL channels or delegation token authenticated channels,
// throw UnsupportedByAuthenticationException
// 2. if the delegation token feature is disabled, throw DelegationTokenDisabledException
// 3. if the renewers principal type is not KafkaPrincipal.USER_TYPE, throw InvalidPrincipalTypeException
// 4. if the request was not completed in within the given timeoutMs(), throw TimeoutException

//processing logic:
//   maxLifeTime = `maxLifeTimeMs` <= 0 ? brokerConfig.delegationTokenMaxLifeMs : Math.min(`maxLifeTimeMs`, brokerConfig.delegationTokenMaxLifeMs)
//   maxLifeTimestamp = currentTimeMillis + maxLifeTime
//   expiryTimestamp = Math.min(maxLifeTimestamp, currentTimeMillis + brokerConfig.delegationTokenExpiryTimeMs)
//   update tokenInfo and return createTokenResult 

2. renewDelegationToken

// 1. if the request sent on PLAINTEXT/1-way SSL channels or delegation token authenticated channels,
// throw UnsupportedByAuthenticationException
// 2. if the delegation token feature is disabled, throw DelegationTokenDisabledException
// 3. if the authenticated user is not owner/renewer of the token, throw DelegationTokenOwnerMismatchException
// 4. if the delegation token is expired, throw DelegationTokenExpiredException
// 5. if the delegation token is not found on server, throw DelegationTokenNotFoundException
// 6. if the request was not completed in within the given timeoutMs(), throw TimeoutException

//processing logic:
//    renewLifeTime = `renewTimePeriodMs` < 0 ? brokerConfig.delegationTokenExpiryTimeMs : `renewTimePeriodMs`
//    renewTimestamp = currentTimeMillis + renewLifeTime
//    expiryTimestamp = Math.min(tokenInfo.maxTimestamp, renewTimestamp)
//    update tokenInfo.expiryTimestamp
//    return expiryTimestamp 

3. expireDelegationToken

// 1. if the request sent on PLAINTEXT/1-way SSL channels or delegation token authenticated channels,
// throw UnsupportedByAuthenticationException
// 2. if the delegation token feature is disabled, throw DelegationTokenDisabledException
// 3. if the authenticated user is not owner/renewer of the token, throw DelegationTokenOwnerMismatchException
// 4. if the delegation token is expired, throw DelegationTokenExpiredException
// 5. if the delegation token is not found on server, throw DelegationTokenNotFoundException
// 6. if the request was not completed in within the given timeoutMs(), throw TimeoutException

//processing logic:
//    if `expiryTimePeriodMs` < 0, delete tokenInfo immediately, return currentTimeMillis.
//    otherwise update tokenInfo expiryTimestamp:
//              expiryTimestamp = Math.min(tokenInfo.maxTimestamp, currentTimeMillis + `expiryTimePeriodMs`)
//              update tokenInfo.expiryTimestamp
//              return expiryTimestamp
//
//    Note: Tokens can be cancelled explicitly. If a token is not renewed by the token’s expiration time or if token is
//    beyond the max life time, it will also be deleted from all broker caches as well as from zookeeper. 

4. describeDelegationToken

// 1. if the request sent on PLAINTEXT/1-way SSL channels or delegation token authenticated channels,
// throw UnsupportedByAuthenticationException
// 2. if the delegation token feature is disabled, throw DelegationTokenDisabledException
// 3. if the request was not completed in within the given timeoutMs(), throw TimeoutException

//processing logic:
//    if `owners` is EmptyList(note: exclude `null`), return List() immediately.
//    if `owners` size > 0, First discard all tokens whose token.ownerOrRenewer does not contain any element in `owners`
//    then return all tokens that satisfies any of the following conditions:
//              1) the authenticated user is token.ownerOrRenewer
//              2) the authenticated user has `DESCRIBE` permission on `Token` Resource
//              for non-owned tokens

I think we can add some comments on the XXXDelegationToken method: how the server handles the parameters passed by the user, which can better help the user to use these methods reasonably.