This is an automated email from the ASF dual-hosted git repository. aaronai pushed a commit to branch java in repository https://gitbox.apache.org/repos/asf/rocketmq-apis.git
commit 31b4c65bd7ad041f621c3c84508aa0faa1b6c218 Author: 凌楚 <[email protected]> AuthorDate: Mon Mar 28 15:08:06 2022 +0800 Add proto --- pom.xml | 86 +++- .../resources/proto/apache/rocketmq/v1/admin.proto | 46 ++ .../proto/apache/rocketmq/v1/definition.proto | 351 +++++++++++++ .../proto/apache/rocketmq/v1/service.proto | 551 +++++++++++++++++++++ 4 files changed, 1033 insertions(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index 8ffa424..6e36d7c 100644 --- a/pom.xml +++ b/pom.xml @@ -6,11 +6,95 @@ <groupId>org.apache.rocketmq</groupId> <artifactId>rocketmq-proto</artifactId> - <version>5.0.0-SNAPSHOT</version> + <version>2.0.0-SNAPSHOT</version> <properties> <maven.compiler.source>8</maven.compiler.source> <maven.compiler.target>8</maven.compiler.target> + + <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> + <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding> + + <grpc.version>1.45.0</grpc.version> + <protobuf.version>3.12.0</protobuf.version> + <annotation-api.version>1.3.2</annotation-api.version> + <protobuf-maven-plugin.version>0.6.1</protobuf-maven-plugin.version> + <os-maven-plugin.version>1.6.2</os-maven-plugin.version> </properties> + <dependencies> + <dependency> + <groupId>io.grpc</groupId> + <artifactId>grpc-protobuf</artifactId> + <version>${grpc.version}</version> + </dependency> + + <dependency> + <groupId>io.grpc</groupId> + <artifactId>grpc-stub</artifactId> + <version>${grpc.version}</version> + </dependency> + + <dependency> + <groupId>io.grpc</groupId> + <artifactId>grpc-netty-shaded</artifactId> + <version>${grpc.version}</version> + </dependency> + + <!-- For jdk11 --> + <dependency> + <groupId>javax.annotation</groupId> + <artifactId>javax.annotation-api</artifactId> + <version>${annotation-api.version}</version> + </dependency> + </dependencies> + + <profiles> + <profile> + <id>protoc-gen</id> + <activation> + <activeByDefault>true</activeByDefault> + </activation> + <build> + <plugins> + <plugin> + <groupId>org.xolstice.maven.plugins</groupId> + <artifactId>protobuf-maven-plugin</artifactId> + <version>${protobuf-maven-plugin.version}</version> + <configuration> + <protocArtifact> + com.google.protobuf:protoc:${protobuf.version}:exe:${os.detected.classifier} + </protocArtifact> + <pluginId>grpc-java</pluginId> + <pluginArtifact> + io.grpc:protoc-gen-grpc-java:${grpc.version}:exe:${os.detected.classifier} + </pluginArtifact> + <protoSourceRoot>${basedir}/src/main/resources/proto</protoSourceRoot> + <outputDirectory>${basedir}/src/main/java</outputDirectory> + <clearOutputDirectory>false</clearOutputDirectory> + </configuration> + <executions> + <execution> + <goals> + <goal>compile</goal> + <goal>compile-custom</goal> + </goals> + </execution> + </executions> + </plugin> + </plugins> + </build> + </profile> + </profiles> + + <build> + <extensions> + <extension> + <groupId>kr.motd.maven</groupId> + <artifactId>os-maven-plugin</artifactId> + <version>${os-maven-plugin.version}</version> + </extension> + </extensions> + </build> + </project> \ No newline at end of file diff --git a/src/main/resources/proto/apache/rocketmq/v1/admin.proto b/src/main/resources/proto/apache/rocketmq/v1/admin.proto new file mode 100644 index 0000000..283ca82 --- /dev/null +++ b/src/main/resources/proto/apache/rocketmq/v1/admin.proto @@ -0,0 +1,46 @@ +// Licensed to the Apache Software Foundation (ASF) under one or more +// contributor license agreements. See the NOTICE file distributed with +// this work for additional information regarding copyright ownership. +// The ASF licenses this file to You under the Apache License, Version 2.0 +// (the "License"); you may not use this file except in compliance with +// the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +syntax = "proto3"; + +package apache.rocketmq.v1; + +option cc_enable_arenas = true; +option csharp_namespace = "Apache.Rocketmq.V1"; +option java_multiple_files = true; +option java_package = "apache.rocketmq.v1"; +option java_generate_equals_and_hash = true; +option java_string_check_utf8 = true; +option java_outer_classname = "MQAdmin"; + +message ChangeLogLevelRequest { + enum Level { + TRACE = 0; + DEBUG = 1; + INFO = 2; + WARN = 3; + ERROR = 4; + } + Level level = 1; +} + +message ChangeLogLevelResponse { + string remark = 1; +} + +service Admin { + rpc ChangeLogLevel(ChangeLogLevelRequest) returns (ChangeLogLevelResponse) { + } +} \ No newline at end of file diff --git a/src/main/resources/proto/apache/rocketmq/v1/definition.proto b/src/main/resources/proto/apache/rocketmq/v1/definition.proto new file mode 100644 index 0000000..723c1e3 --- /dev/null +++ b/src/main/resources/proto/apache/rocketmq/v1/definition.proto @@ -0,0 +1,351 @@ +// Licensed to the Apache Software Foundation (ASF) under one or more +// contributor license agreements. See the NOTICE file distributed with +// this work for additional information regarding copyright ownership. +// The ASF licenses this file to You under the Apache License, Version 2.0 +// (the "License"); you may not use this file except in compliance with +// the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +syntax = "proto3"; + +import "google/protobuf/timestamp.proto"; +import "google/protobuf/duration.proto"; + +package apache.rocketmq.v1; + +option csharp_namespace = "Apache.Rocketmq.V1"; +option java_multiple_files = true; +option java_package = "apache.rocketmq.v1"; +option java_generate_equals_and_hash = true; +option java_string_check_utf8 = true; +option java_outer_classname = "MQDomain"; + +enum Permission { + NONE = 0; + READ = 1; + WRITE = 2; + READ_WRITE = 3; + + reserved 4 to 64; +} + +enum FilterType { + TAG = 0; + SQL = 1; + + reserved 2 to 64; +} + +message FilterExpression { + FilterType type = 1; + string expression = 2; + + reserved 3 to 64; +} + +// Dead lettering is done on a best effort basis. The same message might be +// dead lettered multiple times. +// +// If validation on any of the fields fails at subscription creation/update, +// the create/update subscription request will fail. +message DeadLetterPolicy { + // The maximum number of delivery attempts for any message. + // + // This field will be honored on a best effort basis. + // + // If this parameter is 0, a default value of 16 is used. + int32 max_delivery_attempts = 1; + + reserved 2 to 64; +} + +message Resource { + string resource_namespace = 1; + + // Resource name identifier, which remains unique within the abstract resource + // namespace. + string name = 2; + + reserved 3 to 64; +} + +enum ConsumeModel { + CLUSTERING = 0; + BROADCASTING = 1; + + reserved 2 to 64; +} + +message ProducerData { + Resource group = 1; + + reserved 2 to 64; +} + +enum ConsumePolicy { + RESUME = 0; + PLAYBACK = 1; + DISCARD = 2; + TARGET_TIMESTAMP = 3; + + reserved 4 to 64; +} + +enum ConsumeMessageType { + ACTIVE = 0; + PASSIVE = 1; + + reserved 2 to 64; +} + +message ConsumerData { + Resource group = 1; + + repeated SubscriptionEntry subscriptions = 2; + + ConsumeModel consume_model = 3; + + ConsumePolicy consume_policy = 4; + + DeadLetterPolicy dead_letter_policy = 5; + + ConsumeMessageType consume_type = 6; + + reserved 7 to 64; +} + +message SubscriptionEntry { + Resource topic = 1; + FilterExpression expression = 2; + + reserved 3 to 64; +} + +enum AddressScheme { + IPv4 = 0; + IPv6 = 1; + DOMAIN_NAME = 2; + + reserved 3 to 64; +} + +message Address { + string host = 1; + int32 port = 2; + + reserved 3 to 64; +} + +message Endpoints { + AddressScheme scheme = 1; + repeated Address addresses = 2; + + reserved 3 to 64; +} + +message Broker { + // Name of the broker + string name = 1; + + // Broker index. Canonically, index = 0 implies that the broker is playing + // leader role while brokers with index > 0 play follower role. + int32 id = 2; + + // Address of the broker, complying with the following scheme + // 1. dns:[//authority/]host[:port] + // 2. ipv4:address[:port][,address[:port],...] – IPv4 addresses + // 3. ipv6:address[:port][,address[:port],...] – IPv6 addresses + Endpoints endpoints = 3; + + reserved 4 to 64; +} + +message Partition { + Resource topic = 1; + int32 id = 2; + Permission permission = 3; + Broker broker = 4; + repeated MessageType accept_message_types = 5; + + reserved 6 to 64; +} + +enum MessageType { + NORMAL = 0; + + // Sequenced message + FIFO = 1; + + // Messages that are delivered after the specified duration. + DELAY = 2; + + // Messages that are transactional. Only committed messages are delivered to + // subscribers. + TRANSACTION = 3; + + reserved 4 to 64; +} + +enum DigestType { + // CRC algorithm achieves goal of detecting random data error with lowest + // computation overhead. + CRC32 = 0; + + // MD5 algorithm achieves good balance between collision rate and computation + // overhead. + MD5 = 1; + + // SHA-family has substantially fewer collision with fair amount of + // computation. + SHA1 = 2; + + 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; + + reserved 3 to 64; +} + +enum Encoding { + IDENTITY = 0; + GZIP = 1; + + reserved 2 to 64; +} + +message SystemAttribute { + // Tag + string tag = 1; + + // Message keys + 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` + string message_id = 3; + + // Message body digest + Digest body_digest = 4; + + // Message body encoding. Candidate options are identity, gzip, snappy etc. + Encoding body_encoding = 5; + + // Message type, normal, FIFO or transactional. + MessageType message_type = 6; + + // Message born time-point. + google.protobuf.Timestamp born_timestamp = 7; + + // Message born host. Valid options are IPv4, IPv6 or client host domain name. + string born_host = 8; + + // Time-point at which the message is stored in the broker. + google.protobuf.Timestamp store_timestamp = 9; + + // The broker that stores this message. It may be name, IP or arbitrary + // identifier that uniquely identify the broker. + string store_host = 10; + + oneof timed_delivery { + // Time-point at which broker delivers to clients. + google.protobuf.Timestamp delivery_timestamp = 11; + + // Level-based delay strategy. + int32 delay_level = 12; + } + + // If a message is acquired by way of POP, this field holds the receipt. + // Clients use the receipt to acknowledge or negatively acknowledge the + // message. + string receipt_handle = 13; + + // Partition identifier in which a message is physically stored. + int32 partition_id = 14; + + // Partition offset at which a message is stored. + int64 partition_offset = 15; + + // Period of time servers would remain invisible once a message is acquired. + google.protobuf.Duration invisible_period = 16; + + // Business code may failed to process messages for the moment. Hence, clients + // may request servers to deliver them again using certain back-off strategy, + // the attempt is 1 not 0 if message is delivered first time. + int32 delivery_attempt = 17; + + // Message producer load-balance group if applicable. + Resource producer_group = 18; + + string message_group = 19; + + // Trace context. + string trace_context = 20; + + // Delay time of first recover orphaned transaction request from server. + google.protobuf.Duration orphaned_transaction_recovery_period = 21; + + reserved 22 to 64; +} + +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 + // 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; +} + +message Assignment { + Partition Partition = 1; + + reserved 2 to 64; +} + +enum QueryOffsetPolicy { + // Use this option if client wishes to playback all existing messages. + BEGINNING = 0; + + // Use this option if client wishes to skip all existing messages. + END = 1; + + // Use this option if time-based seek is targeted. + TIME_POINT = 2; + + reserved 3 to 64; +} \ No newline at end of file diff --git a/src/main/resources/proto/apache/rocketmq/v1/service.proto b/src/main/resources/proto/apache/rocketmq/v1/service.proto new file mode 100644 index 0000000..185eddf --- /dev/null +++ b/src/main/resources/proto/apache/rocketmq/v1/service.proto @@ -0,0 +1,551 @@ +// Licensed to the Apache Software Foundation (ASF) under one or more +// contributor license agreements. See the NOTICE file distributed with +// this work for additional information regarding copyright ownership. +// The ASF licenses this file to You under the Apache License, Version 2.0 +// (the "License"); you may not use this file except in compliance with +// the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +syntax = "proto3"; + +import "google/protobuf/duration.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/error_details.proto"; +import "google/rpc/status.proto"; + +import "apache/rocketmq/v1/definition.proto"; + +package apache.rocketmq.v1; + +option csharp_namespace = "Apache.Rocketmq.V1"; +option java_multiple_files = true; +option java_package = "apache.rocketmq.v1"; +option java_generate_equals_and_hash = true; +option java_string_check_utf8 = true; +option java_outer_classname = "MQService"; + +message ResponseCommon { + google.rpc.Status status = 1; + google.rpc.RequestInfo request_info = 2; + google.rpc.Help help = 3; + google.rpc.RetryInfo retry_info = 4; + google.rpc.DebugInfo debug_info = 5; + google.rpc.ErrorInfo error_info = 6; + + reserved 7 to 64; +} + +// 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 auxiliary 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; + + Endpoints endpoints = 2; + + reserved 3 to 64; +} + +message QueryRouteResponse { + ResponseCommon common = 1; + + repeated Partition partitions = 2; + + reserved 3 to 64; +} + +message SendMessageRequest { + Message message = 1; + Partition partition = 2; + + reserved 3 to 64; +} + +message SendMessageResponse { + ResponseCommon common = 1; + string message_id = 2; + string transaction_id = 3; + + reserved 4 to 64; +} + +message QueryAssignmentRequest { + Resource topic = 1; + Resource group = 2; + string client_id = 3; + + // Service access point + Endpoints endpoints = 4; + + reserved 5 to 64; +} + +message QueryAssignmentResponse { + ResponseCommon common = 1; + repeated Assignment assignments = 2; + + reserved 3 to 64; +} + +message ReceiveMessageRequest { + Resource group = 1; + string client_id = 2; + Partition partition = 3; + FilterExpression filter_expression = 4; + ConsumePolicy consume_policy = 5; + google.protobuf.Timestamp initialization_timestamp = 6; + int32 batch_size = 7; + google.protobuf.Duration invisible_duration = 8; + google.protobuf.Duration await_time = 9; + bool fifo_flag = 10; + + reserved 11 to 64; +} + +message ReceiveMessageResponse { + ResponseCommon common = 1; + repeated Message messages = 2; + google.protobuf.Timestamp delivery_timestamp = 3; + google.protobuf.Duration invisible_duration = 4; + + reserved 5 to 64; +} + +message AckMessageRequest { + Resource group = 1; + Resource topic = 2; + string client_id = 3; + oneof handle { + string receipt_handle = 4; + int64 offset = 5; + } + string message_id = 6; + + reserved 7 to 64; +} + +message AckMessageResponse { + ResponseCommon common = 1; + + reserved 2 to 64; +} + +message NackMessageRequest { + Resource group = 1; + Resource topic = 2; + string client_id = 3; + string receipt_handle = 4; + string message_id = 5; + int32 delivery_attempt = 6; + int32 max_delivery_attempts = 7; + + reserved 8 to 64; +} + +message NackMessageResponse { + ResponseCommon common = 1; + + reserved 2 to 64; +} + +message ForwardMessageToDeadLetterQueueRequest { + Resource group = 1; + Resource topic = 2; + string client_id = 3; + string receipt_handle = 4; + string message_id = 5; + int32 delivery_attempt = 6; + int32 max_delivery_attempts = 7; + + reserved 8 to 64; +} + +message ForwardMessageToDeadLetterQueueResponse { + ResponseCommon common = 1; + + reserved 2 to 64; +} + +message HeartbeatRequest { + string client_id = 1; + oneof client_data { + ProducerData producer_data = 2; + ConsumerData consumer_data = 3; + } + bool fifo_flag = 4; + + reserved 5 to 64; +} + +message HeartbeatResponse { + ResponseCommon common = 1; + + reserved 2 to 64; +} + +message HealthCheckRequest { + Resource group = 1; + string client_host = 2; + + reserved 3 to 64; +} + +message HealthCheckResponse { + ResponseCommon common = 1; + + reserved 2 to 64; +} + +message EndTransactionRequest { + Resource group = 1; + string message_id = 2; + string transaction_id = 3; + enum TransactionResolution { + COMMIT = 0; + ROLLBACK = 1; + } + TransactionResolution resolution = 4; + enum Source { + CLIENT = 0; + SERVER_CHECK = 1; + } + Source source = 5; + string trace_context = 6; + + reserved 7 to 64; +} + +message EndTransactionResponse { + ResponseCommon common = 1; + + reserved 2 to 64; +} + +message QueryOffsetRequest { + Partition partition = 1; + QueryOffsetPolicy policy = 2; + google.protobuf.Timestamp time_point = 3; + + reserved 4 to 64; +} + +message QueryOffsetResponse { + ResponseCommon common = 1; + int64 offset = 2; + + reserved 3 to 64; +} + +message PullMessageRequest { + Resource group = 1; + Partition partition = 2; + int64 offset = 3; + int32 batch_size = 4; + google.protobuf.Duration await_time = 5; + FilterExpression filter_expression = 6; + string client_id = 7; + + reserved 8 to 64; +} + +message PullMessageResponse { + ResponseCommon common = 1; + int64 min_offset = 2; + int64 next_offset = 3; + int64 max_offset = 4; + repeated Message messages = 5; + + reserved 6 to 64; +} + +message NoopCommand { reserved 1 to 64; } + +message PrintThreadStackTraceCommand { + string command_id = 1; + + reserved 2 to 64; +} + +message ReportThreadStackTraceRequest { + string command_id = 1; + string thread_stack_trace = 2; + + reserved 3 to 64; +} + +message ReportThreadStackTraceResponse { + ResponseCommon common = 1; + + reserved 2 to 64; +} + +message VerifyMessageConsumptionCommand { + string command_id = 1; + Message message = 2; + + reserved 3 to 64; +} + +message ReportMessageConsumptionResultRequest { + string command_id = 1; + + // 1. Return `INVALID_ARGUMENT` if message is corrupted. + // 2. Return `INTERNAL` if failed to consume message. + // 3. Return `OK` if success. + google.rpc.Status status = 2; + + reserved 3 to 64; +} + +message ReportMessageConsumptionResultResponse { + ResponseCommon common = 1; + + reserved 2 to 64; +} + +message RecoverOrphanedTransactionCommand { + Message orphaned_transactional_message = 1; + string transaction_id = 2; + + reserved 3 to 64; +} + +message PollCommandRequest { + string client_id = 1; + repeated Resource topics = 2; + oneof group { + Resource producer_group = 3; + Resource consumer_group = 4; + } + + reserved 5 to 64; +} + +message PollCommandResponse { + oneof type { + // Default command when no new command need to be delivered. + NoopCommand noop_command = 1; + // Request client to print thread stack trace. + PrintThreadStackTraceCommand print_thread_stack_trace_command = 2; + // Request client to verify the consumption of the appointed message. + VerifyMessageConsumptionCommand verify_message_consumption_command = 3; + // Request client to recover the orphaned transaction message. + RecoverOrphanedTransactionCommand recover_orphaned_transaction_command = 4; + } + + reserved 5 to 64; +} + +message NotifyClientTerminationRequest { + oneof group { + Resource producer_group = 1; + Resource consumer_group = 2; + } + string client_id = 3; + + reserved 4 to 64; +} + +message NotifyClientTerminationResponse { + ResponseCommon common = 1; + + reserved 2 to 64; +} + +message ChangeInvisibleDurationRequest { + Resource group = 1; + Resource topic = 2; + + // Unique receipt handle to identify message to change + string receipt_handle = 3; + + // New invisible duration + google.protobuf.Duration invisible_duration = 4; + reserved 5 to 64; +} + +message ChangeInvisibleDurationResponse { + ResponseCommon common = 1; + + // Server may generate a new receipt handle for the message. + string receipt_handle = 2; + + reserved 3 to 64; +} + +// 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`. +service MessagingService { + + // Queries 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. + // + // Returns `OK` if success. + // + // 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. + 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; + // 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) {} + + // Queries the assigned partition route info of a topic for current consumer, + // the returned assignment result is decided by server-side load balancer. + // + // If the corresponding topic doesn't exist, returns `NOT_FOUND`. + // If the specific endpoints is empty, returns `INVALID_ARGUMENT`. + 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 nacked 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. + 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. + // + // 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. + // + // 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. + rpc ForwardMessageToDeadLetterQueue(ForwardMessageToDeadLetterQueueRequest) + returns (ForwardMessageToDeadLetterQueueResponse) {} + + // Commits or rollback one transactional message. + rpc EndTransaction(EndTransactionRequest) returns (EndTransactionResponse) {} + + // Queries 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 partition. + 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 offsets 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. + rpc PullMessage(PullMessageRequest) returns (PullMessageResponse) {} + + // Multiplexing RPC(s) for various polling requests, which issue different + // commands to client. + // + // Sometimes client may need to receive and process the command from server. + // To prevent the complexity of streaming RPC(s), a unary RPC using + // long-polling is another solution. + // + // To mark the request-response of corresponding command, `command_id` in + // message is recorded in the subsequent RPC(s). For example, after receiving + // command of printing thread stack trace, client would send + // `ReportMessageConsumptionResultRequest` to server, which contain both of + // the stack trace and `command_id`. + // + // At same time, `NoopCommand` is delivered from server when no new command is + // needed, it is essential for client to maintain the ping-pong. + // + rpc PollCommand(PollCommandRequest) returns (PollCommandResponse) {} + + // After receiving the corresponding polling command, the thread stack trace + // is reported to the server. + rpc ReportThreadStackTrace(ReportThreadStackTraceRequest) + returns (ReportThreadStackTraceResponse) {} + + // After receiving the corresponding polling command, the consumption result + // of appointed message is reported to the server. + rpc ReportMessageConsumptionResult(ReportMessageConsumptionResultRequest) + returns (ReportMessageConsumptionResultResponse) {} + + // Notify the server that the client is terminated. + rpc NotifyClientTermination(NotifyClientTerminationRequest) + returns (NotifyClientTerminationResponse) {} + + // Once a message is retrieved from consume queue on behalf of the group, it + // will be kept invisible to other clients of the same group for a period of + // time. The message is supposed to be processed within the invisible + // duration. If the client, which is in charge of the invisible message, is + // not capable of processing the message timely, it may use + // ChangeInvisibleDuration to lengthen invisible duration. + rpc ChangeInvisibleDuration(ChangeInvisibleDurationRequest) + returns (ChangeInvisibleDurationResponse) {} +} \ No newline at end of file
