[ https://issues.apache.org/jira/browse/KAFKA-13757?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17510492#comment-17510492 ]
RivenSun commented on KAFKA-13757: ---------------------------------- Hi [~omkreddy] [~guozhang] and [~showuon] Could you give some advice? Thanks. > 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 > Priority: Major > > 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)