[rocketmq-clients] 01/01: Docs: add design document(WiP)

[aa...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

aaronai pushed a commit to branch docs
in repository https://gitbox.apache.org/repos/asf/rocketmq-clients.git

commit 67cdec61db751b9c762720a9a8ac7fb35580ce77
Author: Aaron Ai <ya...@gmail.com>
AuthorDate: Sat Jun 25 23:16:07 2022 +0800

    Docs: add design document(WiP)
---
 docs/artwork/message_types_and_topic_types.png | Bin 0 -> 598707 bytes
 docs/artwork/unified_apis_and_spec.png         | Bin 0 -> 119393 bytes
 docs/design.md                                 |  76 +++++++++++++++++++++++++
 docs/message_id.md                             |   4 +-
 4 files changed, 79 insertions(+), 1 deletion(-)

diff --git a/docs/artwork/message_types_and_topic_types.png b/docs/artwork/message_types_and_topic_types.png
new file mode 100644
index 0000000..e9fbfed
Binary files /dev/null and b/docs/artwork/message_types_and_topic_types.png differ
diff --git a/docs/artwork/unified_apis_and_spec.png b/docs/artwork/unified_apis_and_spec.png
new file mode 100644
index 0000000..9b471fc
Binary files /dev/null and b/docs/artwork/unified_apis_and_spec.png differ
diff --git a/docs/design.md b/docs/design.md
new file mode 100644
index 0000000..049ee12
--- /dev/null
+++ b/docs/design.md
@@ -0,0 +1,76 @@
+# Design
+
+This project aims to build lightweight, cloud-native clients, and establish the unified messaging model/APIs design acorss languages.
+
+## Messaging Model
+
+We assume that you are familiar with the basic concepts and terminologies about Apache RocketMQ. Therefore, we will not go into details about that.
+
+### Message/Topic Types
+
+In order to adapt different scenarios, we defined different types for messages to publish.
+
+* **FIFO**(First In, First Out): follows standard [FIFO](https://en.wikipedia.org/wiki/FIFO) semantics, this type of message must set the `message group`. This type of message need to be used with FIFO consumer group, which gurantees that the message must be received first if the it is published first with the same message group.
+* **DELAY**: the message about to be sent is not immediately visible to the consumer, this type of message must set the `delivery timestamp`, which decides the visible time to consumers;
+* **TRANSACTIONAL**: wrap the publishing of one or more messages into a transaction, provide commit/rollback method to decide the visibility of messages;
+* **NORMAL**: default type, which means the message is normal type if it does not belong to the other types above.
+
+The different types are mutually exclusive, when means that the message to publish could not be both FIFO type and DELAY type at the same time. Actually the type of the message is bound to the topic type in, and the type of the topic determines the type of the message. For example, FIFO topic do not allow the publishing of other types of messages.
+
+<div align="center">
+<img src="./artwork/message_types_and_topic_types.png" width="50%">
+</div>
+
+### Consumer Group
+
+As we all know, consumer group is the basic unit of load balancing for consumers. Messages are evenly distributed to all consumers in the same consumer group. Now, we assigned more attributes to consumer group rather than the consumer itself.
+
+* Consume timeout: maximum time window bewteen receiving messages and returning an response of acknowledgement. Message will be visible again if time runs out.
+* FIFO consumption switch: enable/disable FIFO consumption for FIFO messages.
+* Message consumption retry policy: decide the max delivery times and backoff algorithm for the message which is failed to be consumed in push consumer.
+
+Especially, this table shows the sequence of message receiption with the combination of FIFO/non-FIFO topics and FIFO/non-FIFO consumer groups.
+
+<div align="center">
+
+|                | FIFO Consumer Group | non-FIFO Consumer Group |
+| :------------: | :-----------------: | :---------------------: |
+|   FIFO Topic   |        FIFO         |        non-FIFO         |
+| non-FIFO Topic |      non-FIFO       |        non-FIFO         |
+
+</div>
+
+### Client Categories
+
+There are four types of client.
+
+* Producer: the client to publish message.
+* Push consumer: full-managed consumer. Message listener are provided for consumption.
+* Simple consumer: the simplest consumer, providing methods to receive messages and change invisible time for messages.
+* Pull consumer: for streaming, it allows to get route info manually and select message queues to bind for pulling message.
+
+### Message Identifier
+
+Message identifer provides identity information for each message stored in broker, which means producer can not get the message identifier until it is sent out successfully.
+
+>**Note**: Internal retries during message publishing may cause message duplication, the duplicate messages here have the same message indentifier.
+
+The message identifer layout is redesigned, see more details [here](./message_id.md).
+
+## New and Unified APIs
+
+<div align="center">
+<img src="./artwork/unified_apis_and_spec.png" width="40%">
+</div>
+
+### Original
+
+[RIP-37: New and Unified APIs](https://shimo.im/docs/m5kv92OeRRU8olqX): RocketMQ proposal of new and unified APIs across different languages.
+
+### Background & Rationale
+
+In fact, current rocketmq APIs exist some problems:
+
+* Lack of well-designed messaging models, which is the prerequisite for unified APIs specification. What’s more, the model strongly affects the definition about behavior. Ambiguous definition makes it harder to predict the behavior of the client.
+* Implementation-oriented. It is not friendly to developers. Many features are based on implementation rather than interface. In addition, users are exposed to redundant and complex interfaces with too many details, increasing probability of making mistakes.
+* Without an unified APIs lifecycle management system, deprecated APIs are reserved for a long time, making APIs difficult to be upgraded.
diff --git a/docs/message_id.md b/docs/message_id.md
index aa58cb7..89f02e8 100644
--- a/docs/message_id.md
+++ b/docs/message_id.md
@@ -19,7 +19,9 @@ As for the second type, there are some major flaws in the algorithm design. Firs
 
 ## Detailed Design
 
-![The Message Identifier Illustration](../docs/artwork/message_id.png)
+<div align="center">
+<img src="./artwork/message_id.png" width="70%">
+</div>
 
 This illustration shows an example of message identifier. The version number of the newly designed version is 0x01, and number of all previous versions is 0x00. The message identifier's length is 17 bytes if its version is higher than 0x00, then we convert it to uppercase hexadecimal to get the message identifier in string format.