diff --git a/docs/source/design.rst b/docs/source/design.rst index 452f775b0..e59fbacc2 100644 --- a/docs/source/design.rst +++ b/docs/source/design.rst @@ -11,51 +11,44 @@ Design Guide Architecture ------------ -Concept Model -------------- - -The emqttd broker 1.0 is more like a network Switch or Router, not traditional enterprise message queue. Compared to a network router that routes packets based on IP or MPLS label, the emqttd broker routes MQTT messages based on a topic trie. +The emqttd broker 1.0 is more like a network Switch or Router, not a traditional enterprise message queue. Compared to a network router that routes packets based on IP or MPLS label, the emqttd broker routes MQTT messages based on topic trie. .. image:: _static/images/concept.png Design Philosophy ----------------- -1. Focus on handling millions of MQTT connections and route MQTT messages between clustered nodes. +1. Focus on handling millions of MQTT connections and routing MQTT messages between clustered nodes. -2. Embrace Erlang/OTP, The Soft-Realtime, Low-Latency, Concurrent and Fault-Tolerant platform. +2. Embrace Erlang/OTP, The Soft-Realtime, Low-Latency, Concurrent and Fault-Tolerant Platform. -3. Connection, Session, PubSub, Router and Distributed Layers. +3. Layered Design: Connection, Session, PubSub and Router Layers. -4. Seperate the Message Flow Plane and Control/Management Plane. +4. Separate the Message Flow Plane and the Control/Management Plane. -5. Stream out the MQTT messages to various backends. +5. Stream MQTT messages to various backends including MQ or databases. System Layers ------------- +1. Connection Layer: + Handle TCP and WebSocket connections, encode/decode MQTT packets. + +2. Session Layer: + Process MQTT PUBLISH/SUBSCRIBE Packets received from client, and deliver MQTT messages to client. + +3. PubSub Layer: + Dispatch MQTT messages to subscribers in a node. + +4. Routing(Distributed) Layer: + Route MQTT messages between clustered nodes. + .. code:: -------------- ----------- ---------- ---------- Client --> | Connection | --> | Session | --> | PubSub | --> | Router | -------------- ----------- ---------- ---------- -1. Connection Layer: - - Handle TCP and WebSocket connections, encode/decode MQTT packets. - -2. Session Layer: - - Process MQTT PUBLISH/SUBSCRIBE Packets recevied from client, and deliver MQTT messages to client. - -3. PubSub Layer: - - Route and dispatch MQTT messages to subscribers in a node - -4. Route(Distributed) Layer: - - Route MQTT messages between nodes in a cluster - ---------------- Connection Layer ---------------- @@ -96,7 +89,7 @@ Main modules of this layer: Session Layer ------------- -The session layer processes MQTT PUBLISH/SUBSCRIBE packets received from client, and deliver PUBLISH packets to client. +The session layer processes MQTT packets received from client, and deliver PUBLISH packets to client. A MQTT session will store the subscriptions and inflight messages in memory: @@ -105,14 +98,12 @@ A MQTT session will store the subscriptions and inflight messages in memory: 2. Inflight qos1/2 messages sent to the client but unacked, QoS 2 messages which have been sent to the Client, but have not been completely acknowledged. -3. Inflight qos2 messages received from client and waiting for pubrel. QoS 2 +3. Inflight qos2 messages received from client and waiting for PUBREL. QoS 2 messages which have been received from the Client, but have not been completely acknowledged. 4. All qos1, qos2 messages published to when client has been disconnected. -Main module of this layer is emqttd_session. - MQueue and Inflight Window -------------------------- @@ -124,7 +115,7 @@ IN -> | Messages Queue | Inflight Window | -> Out ----------------------------------------------- |<--- Win Size --->| -1. Inflight Window to store the messages delivered and awaiting for puback. +1. Inflight Window to store the messages delivered and awaiting for PUBACK. 2. Enqueue messages when the inflight window is full. @@ -136,9 +127,9 @@ The larger the inflight window size, the higher the throughput. The smaller the PacketId and MessageId ---------------------- -The 16bits PacketId is defined by MQTT Protocol Specification, used by client/server to PUBLISH/PUBACK packets. A GUID(128bits global unique Id) will be generated by the borker and assigend to a MQTT message. +The 16bits PacketId is defined by MQTT Protocol Specification, used by client/server to PUBLISH/PUBACK packets. A GUID(128bits global unique Id) will be generated by the broker and assigned to a MQTT message. -Format of the global unique messsage id:: +Format of the global unique message id:: +------------------------+----------------+------------+ | Timestamp | NodeID + PID | Sequence | @@ -186,7 +177,7 @@ For example, if node1 subscribed 't/+/x' and 't/+/y', node2 subscribed 't/#' and | t/a -> node3 | ------------------------- -The routing layer would route MQTT messages between clustered nodes by topic trie match and routing table lookup, and follow the ruels below: +The routing layer would route MQTT messages between clustered nodes by topic trie match and routing table lookup, and follow the rules below: 1. A message only gets forwarded to other cluster nodes if a cluster node is interested in it. This reduces the network traffic tremendously, because it prevents nodes from forwarding unnecessary messages. @@ -206,10 +197,10 @@ emqttd_access_control module provides two APIs that help register/unregister aut register_mod(auth | acl, atom(), list(), non_neg_integer()) -> ok | {error, any()}. -Authentication Bahavihour +Authentication Bahaviour ------------------------- -The emqttd_auth_mod defines an Erlang behavihour for authentication module:: +The emqttd_auth_mod defines an Erlang behaviour for authentication module:: -module(emqttd_auth_mod). @@ -337,7 +328,7 @@ Hooks defined by the emqttd 1.0 broker: +------------------------+------------------------------------------------------+ | message.acked | Run when a MQTT message is acked | +------------------------+------------------------------------------------------+ -| client.disconnected | Run when client disconnnected from broker | +| client.disconnected | Run when client disconnected from broker | +------------------------+------------------------------------------------------+ The emqttd broker uses the `Chain-of-responsibility_pattern`_ to implement hook mechanism. The callback functions registered to hook will be executed one bye one::