THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
...
| Command | Wire Protocol Message | Note |
|---|---|---|
| create-topic | CreateTopicRequest | |
| alter-topic | AlterTopicRequest | |
| delete-topic | DeleteTopicRequest | |
| describe-topic | TopicMetadataRequest_V1 | Using new version on TopicMetadataRequest which will include topic-level config |
| list-topics | TopicMetadataRequest | Using an empty list as input for request, which results in returning metadata for all existing topcis |
| reassign-partitions | AlterTopicReqeust | Using batch AlterTopicRequest with replica assignment specified |
| preferred-replica-leader-election | PreferredReplicaLeaderElectionRequest |
It is also important that all Admin requests are intended to be asynchronous. This means requests will only initiate particular command, and will not wait until the command is actually completed. There are different reasons to that, but we wan't to make sure that we give users all needed tools to verify whether issued command has been completed. E.g. one can consider topic is created once it is possible to consumer from / produce to this topic. In this case user can leverage TopicMetadataRequest to check all brokers received metadata about the newly created topic.
Finally, Topic Admin schema requests are likely to be used not only in CLI tool, where the common use case in create/change/delete/get a single entity. Since Kafka is able to maintain a huge number of topics it is important that user can efficiently issue many requests at one time. That's why all Topic Admin messages essentially are batch requests, i.e. it is possible to group commands of one type for many topics in one batch reducing network calls.
New Protocol Errors
It is proposed to add these error codes to the protocol.
Error | Description | Requests |
|---|---|---|
TopicAlreadyExists | Topic with this name already exists. | CreateTopicRequest |
InvalidArgumentTopicName | Topic name contains invalid characters | CreateTopicRequest |
InvalidArgumentPartitions | Either partition field is invalid (e.g. negative), or not defined when needed. | CreateTopicRequest, AlterTopicRequest |
InvalidArgumentReplicationFactor | Either replication-factor field is invalid (e.g. negative), or not defined when needed. | CreateTopicRequest, |
InvalidArgumentReplicaAssignment | Either replication-factor field is invalid (e.g. contains duplicates), or not defined when needed. |
|
InvalidArgumentTopicConfig | Either topic-level config setting or value is incorrect. | CreateTopicRequest, AlterTopicRequest |
DecreasePartitionsNotAllowed | Invalid partitions argument: decreasing partitions is prohibited when altering topic. | AlterTopicRequest |
PreferredReplicaLeaderElectionInProgress | Preferred replica leader election procedure has been already started. | PreferredReplicaLeaderElectionRequest |
ReassignPartitionsInProgress | Reassign partitions procedure has been already started. | AlterTopicRequest |
| MultipleInstructionsForOneTopic | Only one mutation is allowed at once: e.g. change topic replication factor or change topic config | CreateTopic, AlterTopicRequest |
MultipleTopicInstructionsInOnebatch | Multiple topic instructions for the same topic in one batch request | CreateTopicRequest, AlterTopicRequest, DeleteTopicRequest |
Generally, the Admin Client (see section 3) or another request dispatcher should have enough context to provide descriptive error message.
The same notation as in A Guide To The Kafka Protocol is used here.
...