You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@rocketmq.apache.org by yu...@apache.org on 2021/10/01 13:17:24 UTC
[rocketmq-apis] 01/01: Init first draft version of rocketmq new apis
This is an automated email from the ASF dual-hosted git repository.
yukon pushed a commit to branch api_draft
in repository https://gitbox.apache.org/repos/asf/rocketmq-apis.git
commit c0ebbf8981373a703c101ecdfac6f1b2e7ad77da
Author: lizhanhui <li...@apache.org>
AuthorDate: Fri Oct 1 21:17:12 2021 +0800
Init first draft version of rocketmq new apis
---
README.md | 14 +-
apache/rocketmq/v1/admin.proto | 32 +++
apache/rocketmq/v1/definition.proto | 311 +++++++++++++++++++++++++++++
apache/rocketmq/v1/service.proto | 384 ++++++++++++++++++++++++++++++++++++
4 files changed, 740 insertions(+), 1 deletion(-)
diff --git a/README.md b/README.md
index 1010423..c1252fa 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,13 @@
-# rocketmq-apis
+## Overview
+
+## Extension Spec
+
+## Message Model
+
+## Producer Flow
+
+## Consumer Flow
+
+## Reserved Fields
+
+This API spec has reserved the numeric value of PB enum to 64 and the field numeric value of PB message to 64. These reserved values will be used by RocketMQ's official implementation. Beyond the reserved values are free to use by external organizations.
\ No newline at end of file
diff --git a/apache/rocketmq/v1/admin.proto b/apache/rocketmq/v1/admin.proto
new file mode 100644
index 0000000..8ed2037
--- /dev/null
+++ b/apache/rocketmq/v1/admin.proto
@@ -0,0 +1,32 @@
+syntax = "proto3";
+
+package apache.rocketmq.v1;
+
+option cc_enable_arenas = true;
+option java_multiple_files = true;
+option java_package = "apache.rocketmq.v1";
+option java_generate_equals_and_hash = true;
+option java_string_check_utf8 = true;
+
+// Ali Cloud Service
+option java_outer_classname = "ACS";
+
+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/apache/rocketmq/v1/definition.proto b/apache/rocketmq/v1/definition.proto
new file mode 100644
index 0000000..9ecd46a
--- /dev/null
+++ b/apache/rocketmq/v1/definition.proto
@@ -0,0 +1,311 @@
+syntax = "proto3";
+
+import "google/protobuf/timestamp.proto";
+import "google/protobuf/duration.proto";
+
+package 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;
+
+// Ali Cloud Service
+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 5 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;
+
+ reserved 5 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;
+}
+
+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.
+ 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.
+ 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/apache/rocketmq/v1/service.proto b/apache/rocketmq/v1/service.proto
new file mode 100644
index 0000000..5deb63c
--- /dev/null
+++ b/apache/rocketmq/v1/service.proto
@@ -0,0 +1,384 @@
+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 java_multiple_files = true;
+option java_package = "apache.rocketmq.v1";
+option java_generate_equals_and_hash = true;
+option java_string_check_utf8 = true;
+
+// Ali Cloud Service
+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;
+}
+
+message QueryRouteRequest {
+ Resource topic = 1;
+
+ // Service access point
+ 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 UpdateOffsetRequest {
+ Resource group = 1;
+ Partition partition = 2;
+ int64 partition_offset = 3;
+
+ reserved 4 to 64;
+}
+
+message UpdateOffsetResponse {
+ ResponseCommon common = 1;
+
+ reserved 2 to 64;
+}
+
+message GenericPollingRequest {
+ string client_id = 1;
+ repeated Resource topics = 2;
+ oneof group {
+ Resource producer_group = 3;
+ Resource consumer_group = 4;
+ }
+
+ reserved 5 to 64;
+}
+
+message GenericPollingResponse {
+ ResponseCommon common = 1;
+
+ reserved 2 to 64;
+}
+
+message PrintThreadStackRequest {
+ string mid = 1;
+
+ reserved 2 to 64;
+}
+
+message PrintThreadStackResponse {
+ ResponseCommon common = 1;
+ string mid = 2;
+ string stack_trace = 3;
+
+ reserved 4 to 64;
+}
+
+message VerifyMessageConsumptionRequest {
+ string mid = 1;
+ Message message = 2;
+
+ reserved 3 to 64;
+}
+
+message VerifyMessageConsumptionResponse {
+ string mid = 1;
+ ResponseCommon common = 2;
+
+ reserved 3 to 64;
+}
+
+message RecoverOrphanedTransactionRequest {
+ Message orphaned_transactional_message = 1;
+ string transaction_id = 2;
+
+ reserved 3 to 64;
+}
+
+message MultiplexingRequest {
+ oneof type {
+ GenericPollingRequest polling_request = 1;
+ PrintThreadStackResponse print_thread_stack_response = 2;
+ VerifyMessageConsumptionResponse verify_message_consumption_response = 3;
+ }
+
+ reserved 4 to 64;
+}
+
+message MultiplexingResponse {
+ oneof type {
+ GenericPollingResponse polling_response = 1;
+ PrintThreadStackRequest print_thread_stack_request = 2;
+ VerifyMessageConsumptionRequest verify_message_consumption_request = 3;
+ RecoverOrphanedTransactionRequest recover_orphaned_transaction_request = 4;
+ }
+
+ reserved 5 to 64;
+}
+
+message NotifyClientTerminationRequest {
+ Resource group = 1;
+ string client_id = 2;
+
+ reserved 3 to 64;
+}
+
+message NotifyClientTerminationResponse {
+ ResponseCommon common = 1;
+
+ reserved 2 to 64;
+}
+
+service MessagingService {
+ rpc QueryRoute(QueryRouteRequest) returns (QueryRouteResponse) {}
+
+ rpc Heartbeat(HeartbeatRequest) returns (HeartbeatResponse) {}
+
+ rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse) {}
+
+ rpc SendMessage(SendMessageRequest) returns (SendMessageResponse) {}
+
+ rpc QueryAssignment(QueryAssignmentRequest)
+ returns (QueryAssignmentResponse) {}
+
+ rpc ReceiveMessage(ReceiveMessageRequest) returns (ReceiveMessageResponse) {}
+
+ rpc AckMessage(AckMessageRequest) returns (AckMessageResponse) {}
+
+ rpc NackMessage(NackMessageRequest) returns (NackMessageResponse) {}
+
+ rpc ForwardMessageToDeadLetterQueue(ForwardMessageToDeadLetterQueueRequest)
+ returns (ForwardMessageToDeadLetterQueueResponse) {}
+
+ rpc EndTransaction(EndTransactionRequest) returns (EndTransactionResponse) {}
+
+ rpc QueryOffset(QueryOffsetRequest) returns (QueryOffsetResponse) {}
+
+ rpc PullMessage(PullMessageRequest) returns (PullMessageResponse) {}
+
+ rpc UpdateOffset(UpdateOffsetRequest) returns (UpdateOffsetResponse) {}
+
+ rpc MultiplexingCall(MultiplexingRequest) returns (MultiplexingResponse) {}
+
+ rpc NotifyClientTermination(NotifyClientTerminationRequest)
+ returns (NotifyClientTerminationResponse) {}
+}
\ No newline at end of file