You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@rocketmq.apache.org by aa...@apache.org on 2022/07/15 03:27:35 UTC
[rocketmq-apis] 02/38: Add proto
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: 凌楚 <ya...@alibaba-inc.com>
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