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

["RivenSun (Jira)" <ji...@apache.org>]

RivenSun created KAFKA-13757:
--------------------------------

             Summary: Improve the annotations of all related methods of DelegationToken in the Admin class
                 Key: KAFKA-13757
                 URL: https://issues.apache.org/jira/browse/KAFKA-13757
             Project: Kafka
          Issue Type: Improvement
          Components: admin
            Reporter: RivenSun


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：
{code:java}
// 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 {code}

2. renewDelegationToken
{code:java}
// 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 {code}
3. expireDelegationToken
{code:java}
// 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. {code}
4. describeDelegationToken
{code:java}
// 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.
//    otherwise return all tokens that satisfies any of the following conditions:
//              1) if `owners` size > 0, at least one element in `owners` is token.ownerOrRenewer
//              2) the authenticated user is token.ownerOrRenewer
//              3) the authenticated user has `DESCRIBE` permission on `Token` Resource
//              for non-owned tokens {code}
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.

 



--
This message was sent by Atlassian Jira
(v8.20.1#820001)