Tegde MQTT bridge internal docs

gistfile1.txt

## Bridging local messages to the cloud

The two `half-bridge` instances cooperate:

- The `half_bridge(local_event_loop,cloud_client)` receives local messages and publishes these message on the cloud.
- The `half_bridge(cloud_event_loop,local_client)` handles the acknowledgements: waiting for messages be acknowledged by the cloud, before sending acks for the original messages.



                  ┌───────────────┐                                   ┌───────────────┐                                           
                  │               │                                   │               │                                           
  Incoming::PubAck│     ┌──┐      │                  ┌──┐             │               │ Outgoing::PubAck                          
  ────────────────┼────►│6.├──────┼──────────────────►7.├─────────────┼───────────────┼──────────────►                            
                  │     └──┘      │                  └▲─┘             │               │                                           
                  │               │                   │               │               │                                           
                  │               │             ┌─────┼────────┐      │               │                                           
                  │               │             │     │        │      │               │                                           
                  │     ┌──┐      │             │    ┌┴─┐      │      │               │                                           
                  │     │4.├──────┼─────────────┼───►│5.│      │      │               │                                           
                  │     └─▲┘      │             │    └▲─┘      │      │               │                                           
                  │       │       │             │     │        │      │               │                                           
                  │       │       │             │     │        │      │               │                                           
                  │       │       │             │     │        │      │               │                                           
                  │       │       │             │     │        │      │               │                                           
                  │       │       │             │     │        │      │               │ half_bridge(cloud_event_loop,local_client)
                  │       │       │             │     │        │      │               │                                           
                  │       │       │             │     │        │      │               │                                           
        xxxxxxxxxxxxxxxxxx│xxxxxxxxxxxxxxxxxxxxx│xxxxx│xxxxxxxx│xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
                  │       │       │             │     │        │      │               │                                           
                  │       │       │             │     │        │      │               │                                           
                  │       │       │             │     │        │      │               │ half_bridge(local_event_loop,cloud_client)
                  │       │       │             │     │        │      │               │                                           
                  │       │       │             │     │        │      │               │                                           
                  │       │       │             │     │        │      │               │                                           
Outgoing::Publish │      ┌┴─┐     │             │    ┌┴─┐      │      │     ┌──┐      │ Incoming::Publish                         
  ◄───────────────┼──────┤3.◄─────┼─────────────┼────┤2.◄──────┼──────┼─────┤1.│◄─────┼───────────────                            
                  │      └──┘     │             │    └──┘      │      │     └──┘      │                                           
                  │               │             │              │      │               │                                           
                  │   MQTT        │             │              │      │    MQTT       │                                           
                  │               │             │   channel    │      │               │                                           
                  │   cloud       │             └──────────────┘      │    local      │                                           
                  │               │                                   │               │                                           
                  │   connection  │                                   │    connection │                                           
                  │               │                                   │               │                                           
                  └───────────────┘                                   └───────────────┘                                           


1. On the local_event_loop is received a message.
2. This message is sent unchanged to the second half_bridge which owns the local_client: so the latter will be able to acknowledge it when fully processed.
3. A copy of this message is published by the cloud_client on the cloud topic derived from the local topic.
4. The cloud_event_loop is notified that the message has been published by the cloud client. The notification event provides the `pkid` of the message used on the cloud connection.
5. The message cloud `pkid` is joined with the original local message sent step 2. The pair (cloud `pkid`, local message) is cached 
6. The cloud MQTT end-point acknowledges the message, providing its cloud `pkid`.
7. The pair (cloud `pkid`, local message) is extracted from the cache and the local message is finaly acknowledged.
 
## Bridging cloud messages to local

The very same two `half-bridge` instances ensure the reverse flow. Their role are simply swapped:

- The `half_bridge(cloud_event_loop,local_client)` receives cloud messages and publishes these message locally.
- The `half_bridge(local_event_loop,cloud_client)` handles the acknowledgements: waiting for messages be acknowledged locally, before sending acks for the original messages.