You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@rocketmq.apache.org by li...@apache.org on 2021/10/11 07:52:22 UTC
[rocketmq-apis] branch main updated: Add comment for
QueryRouteRequest and Digest
This is an automated email from the ASF dual-hosted git repository.
lizhanhui pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/rocketmq-apis.git
The following commit(s) were added to refs/heads/main by this push:
new 9def17d Add comment for QueryRouteRequest and Digest
9def17d is described below
commit 9def17d0785ef244911282e70179608f4b17195c
Author: Li Zhanhui <li...@gmail.com>
AuthorDate: Mon Oct 11 15:52:10 2021 +0800
Add comment for QueryRouteRequest and Digest
---
apache/rocketmq/v1/definition.proto | 25 ++++++-
apache/rocketmq/v1/service.proto | 133 +++++++++++++++++++++++-------------
2 files changed, 107 insertions(+), 51 deletions(-)
diff --git a/apache/rocketmq/v1/definition.proto b/apache/rocketmq/v1/definition.proto
index c92aad3..b6cb24b 100644
--- a/apache/rocketmq/v1/definition.proto
+++ b/apache/rocketmq/v1/definition.proto
@@ -207,6 +207,21 @@ enum DigestType {
reserved 3 to 64;
}
+// When publishing messages to or subscribing messages from brokers, clients
+// shall include or validate digests of message body to ensure data integrity.
+//
+// For message publishment, when an invalid digest were detected, brokers need
+// respond client with BAD_REQUEST.
+//
+// For messags subscription, when an invalid digest were detected, consumers
+// need to handle this case according to message type:
+// 1) Standard messages should be negatively acknowledged instantly, causing
+// immediate re-delivery; 2) FIFO messages require special RPC, to re-fetch
+// previously acquired messages batch;
+//
+// Message consumption model also affects how invalid digest are handled. When
+// messages are consumed in broadcasting way,
+// TODO: define semantics of invalid-digest-when-broadcasting.
message Digest {
DigestType type = 1;
string checksum = 2;
@@ -229,7 +244,8 @@ message SystemAttribute {
repeated string keys = 2;
// Message identifier, client-side generated, remains unique.
- // if message_id is empty, the send message request will be aborted with status `INVALID_ARGUMENT`
+ // if message_id is empty, the send message request will be aborted with
+ // status `INVALID_ARGUMENT`
string message_id = 3;
// Message body digest
@@ -296,13 +312,18 @@ message SystemAttribute {
}
message Message {
+
Resource topic = 1;
+
// User defined key-value pairs.
// If user_attribute contains the reserved keys by RocketMQ,
- // the send message request will be aborted with status `INVALID_ARGUMENT`. See below links for the reserved keys
+ // the send message request will be aborted with status `INVALID_ARGUMENT`.
+ // See below links for the reserved keys
// https://github.com/apache/rocketmq/blob/master/common/src/main/java/org/apache/rocketmq/common/message/MessageConst.java#L58
map<string, string> user_attribute = 2;
+
SystemAttribute system_attribute = 3;
+
bytes body = 4;
reserved 5 to 64;
diff --git a/apache/rocketmq/v1/service.proto b/apache/rocketmq/v1/service.proto
index ce09da5..9334e9d 100644
--- a/apache/rocketmq/v1/service.proto
+++ b/apache/rocketmq/v1/service.proto
@@ -41,13 +41,26 @@ message ResponseCommon {
reserved 7 to 64;
}
-// A QueryRouteRequest requests a set of Partitions of the specific topic with
-// necessary route infos.
+// Topics are destination of messages to publish to or subscribe from. Similar
+// to domain names, they will be addressable after resolution through the
+// provided access point.
+//
+// Access points are usually the addresses of name servers, which fulfill
+// service discovery, load-balancing and other auxillary services. Name servers
+// receive periodic heartbeats from affiliate brokers and erase those which
+// failed to maintain alive status.
+//
+// Name servers answer queries of QueryRouteRequest, responding clients with
+// addressable partitions, which they may directly publish messages to or
+// subscribe messages from.
+//
+// QueryRouteRequest shall include source endpoints, aka, configured
+// access-point , which annotates tenant-id, instance-id or other
+// vendor-specific settings. Purpose-built name servers may respond customized
+// results based on these particular requirements.
message QueryRouteRequest {
Resource topic = 1;
- // The service access points used to issue QueryRouteRequest
- // The QueryRouteResponse will indicate the adress of subsequent RPCs.
Endpoints endpoints = 2;
reserved 3 to 64;
@@ -55,6 +68,7 @@ message QueryRouteRequest {
message QueryRouteResponse {
ResponseCommon common = 1;
+
repeated Partition partitions = 2;
reserved 3 to 64;
@@ -352,97 +366,118 @@ message NotifyClientTerminationResponse {
reserved 2 to 64;
}
-// For all the RPCs in MessagingService, the following error handling policies apply:
+// For all the RPCs in MessagingService, the following error handling policies
+// apply:
//
-// If the request doesn't bear a valid authentication credential, return a response with common.status.code == `UNAUTHENTICATED`.
-// If the authenticated user is not granted with sufficient permission to execute the requested operation, return a response with common.status.code == `PERMISSION_DENIED`.
-// If the per-user-resource-based quota is exhausted, return a response with common.status.code == `RESOURCE_EXHAUSTED`.
-// If any unexpected server-side errors raise, return a response with common.status.code == `INTERNAL`.
+// If the request doesn't bear a valid authentication credential, return a
+// response with common.status.code == `UNAUTHENTICATED`. If the authenticated
+// user is not granted with sufficient permission to execute the requested
+// operation, return a response with common.status.code == `PERMISSION_DENIED`.
+// If the per-user-resource-based quota is exhausted, return a response with
+// common.status.code == `RESOURCE_EXHAUSTED`. If any unexpected server-side
+// errors raise, return a response with common.status.code == `INTERNAL`.
service MessagingService {
- // Querys the route entries of the requested topic in the perspective of the given endpoints.
- // On success, servers should return a collection of addressable partitions.
- // Note servers may return customized route entries based on endpoints provided.
+ // Querys the route entries of the requested topic in the perspective of the
+ // given endpoints. On success, servers should return a collection of
+ // addressable partitions. Note servers may return customized route entries
+ // based on endpoints provided.
//
// If the requested topic doesn't exist, returns `NOT_FOUND`.
// If the specific endpoints is emtpy, returns `INVALID_ARGUMENT`.
rpc QueryRoute(QueryRouteRequest) returns (QueryRouteResponse) {}
- // Producer or consumer sends HeartbeatRequest to servers periodically to keep-alive.
- // Additionally, it also reports client-side configuration, including topic subscription, load-balancing group name, etc.
+ // Producer or consumer sends HeartbeatRequest to servers periodically to
+ // keep-alive. Additionally, it also reports client-side configuration,
+ // including topic subscription, load-balancing group name, etc.
//
// Returns `OK` if success.
//
- // If a client specifies a language that is not yet supported by servers, returns `INVALID_ARGUMENT`
+ // If a client specifies a language that is not yet supported by servers,
+ // returns `INVALID_ARGUMENT`
rpc Heartbeat(HeartbeatRequest) returns (HeartbeatResponse) {}
- // Checks the health status of message server, returns `OK` if services are online and serving.
- // Clients may use this RPC to detect availability of messaging service, and take isolation actions when necessary.
+ // Checks the health status of message server, returns `OK` if services are
+ // online and serving. Clients may use this RPC to detect availability of
+ // messaging service, and take isolation actions when necessary.
rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse) {}
// Delivers messages to brokers.
// Clients may further:
- // 1. Refine a message destination to topic partition which fulfills parts of FIFO semantic;
- // 2. Flag a message as transactional, which keeps it invisible to consumers until it commits;
- // 3. Time a message, making it invisible to consumers till specified time-point;
+ // 1. Refine a message destination to topic partition which fulfills parts of
+ // FIFO semantic;
+ // 2. Flag a message as transactional, which keeps it invisible to consumers
+ // until it commits;
+ // 3. Time a message, making it invisible to consumers till specified
+ // time-point;
// 4. And more...
- //
+ //
// Returns message-id or transaction-id with status `OK` on success.
//
// If the destination topic doesn't exist, returns `NOT_FOUND`.
rpc SendMessage(SendMessageRequest) returns (SendMessageResponse) {}
- // Querys the assigned partition route info of a topic for current consumer,
+ // Querys the assigned partition route info of a topic for current consumer,
// the returned assignment result is descided by server-side load balacner.
//
// If the corresponding topic doesn't exist, returns `NOT_FOUND`.
// If the specific endpoints is emtpy, returns `INVALID_ARGUMENT`.
- rpc QueryAssignment(QueryAssignmentRequest) returns (QueryAssignmentResponse) {}
+ rpc QueryAssignment(QueryAssignmentRequest)
+ returns (QueryAssignmentResponse) {}
- // Receives messages from the server in batch manner, returns a set of messages if success.
- // The received messages should be acked or uacked after processed.
+ // Receives messages from the server in batch manner, returns a set of
+ // messages if success. The received messages should be acked or uacked after
+ // processed.
//
- // If the pending concurrent receive requests exceed the quota of the given consumer group, returns `UNAVAILABLE`.
- // If the upstream store server hangs, return `DEADLINE_EXCEEDED` in a timely manner.
- // If the corresponding topic or consumer group doesn't exist, returns `NOT_FOUND`.
- // If there is no new message in the specific topic, returns `OK` with an empty message set. Please note that client
- // may suffer from false empty responses.
+ // If the pending concurrent receive requests exceed the quota of the given
+ // consumer group, returns `UNAVAILABLE`. If the upstream store server hangs,
+ // return `DEADLINE_EXCEEDED` in a timely manner. If the corresponding topic
+ // or consumer group doesn't exist, returns `NOT_FOUND`. If there is no new
+ // message in the specific topic, returns `OK` with an empty message set.
+ // Please note that client may suffer from false empty responses.
rpc ReceiveMessage(ReceiveMessageRequest) returns (ReceiveMessageResponse) {}
- // Acknowledges the message associated with the `receipt_handle` or `offset` in the
- // `AckMessageRequest`, it means the message has been successfully processed.
- // Returns `OK` if the message server remove the relevant message successfully.
+ // Acknowledges the message associated with the `receipt_handle` or `offset`
+ // in the `AckMessageRequest`, it means the message has been successfully
+ // processed. Returns `OK` if the message server remove the relevant message
+ // successfully.
//
- // If the given receipt_handle is illegal or out of date, returns `INVALID_ARGUMENT`.
+ // If the given receipt_handle is illegal or out of date, returns
+ // `INVALID_ARGUMENT`.
rpc AckMessage(AckMessageRequest) returns (AckMessageResponse) {}
- // Signals that the message has not been successfully processed. The message server should resend the message
- // follow the retry policy defined at server-side.
+ // Signals that the message has not been successfully processed. The message
+ // server should resend the message follow the retry policy defined at
+ // server-side.
//
- // If the corresponding topic or consumer group doesn't exist, returns `NOT_FOUND`.
+ // If the corresponding topic or consumer group doesn't exist, returns
+ // `NOT_FOUND`.
rpc NackMessage(NackMessageRequest) returns (NackMessageResponse) {}
- // Forwards one message to dead letter queue if the DeadLetterPolicy is triggered by this message at client-side,
- // return `OK` if success.
+ // Forwards one message to dead letter queue if the DeadLetterPolicy is
+ // triggered by this message at client-side, return `OK` if success.
rpc ForwardMessageToDeadLetterQueue(ForwardMessageToDeadLetterQueueRequest)
returns (ForwardMessageToDeadLetterQueueResponse) {}
// Commits or rollback one transactional message.
rpc EndTransaction(EndTransactionRequest) returns (EndTransactionResponse) {}
- // Querys the offset of the specific partition, returns the offset with `OK` if success.
- // The message server should maintain a numerical offset for each message in a parition.
+ // Querys the offset of the specific partition, returns the offset with `OK`
+ // if success. The message server should maintain a numerical offset for each
+ // message in a parition.
rpc QueryOffset(QueryOffsetRequest) returns (QueryOffsetResponse) {}
- // Pulls messages from the specific partition, returns a set of messages with next pull offset.
- // The pulled messages can't be acked or nacked, while the client is responsible for manage offesets for consumer,
- // typically update consume offset to local memory or a third-party storage service.
+ // Pulls messages from the specific partition, returns a set of messages with
+ // next pull offset. The pulled messages can't be acked or nacked, while the
+ // client is responsible for manage offesets for consumer, typically update
+ // consume offset to local memory or a third-party storage service.
//
- // If the pending concurrent receive requests exceed the quota of the given consumer group, returns `UNAVAILABLE`.
- // If the upstream store server hangs, return `DEADLINE_EXCEEDED` in a timely manner.
- // If the corresponding topic or consumer group doesn't exist, returns `NOT_FOUND`.
- // If there is no new message in the specific topic, returns `OK` with an empty message set. Please note that client
- // may suffer from false empty responses.
+ // If the pending concurrent receive requests exceed the quota of the given
+ // consumer group, returns `UNAVAILABLE`. If the upstream store server hangs,
+ // return `DEADLINE_EXCEEDED` in a timely manner. If the corresponding topic
+ // or consumer group doesn't exist, returns `NOT_FOUND`. If there is no new
+ // message in the specific topic, returns `OK` with an empty message set.
+ // Please note that client may suffer from false empty responses.
rpc PullMessage(PullMessageRequest) returns (PullMessageResponse) {}
// Multiplexing RPC(s) for various polling requests, which issue different