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)
