Define Attach method

At this time doesn't exist a native support to UUID type, so we used a string type. [Issue]: protocolbuffers/protobuf#2224 Signed-off-by: Antonio Gisondi <antonio.gisondi@secomind.com>
harlem88 · Sep 21, 2022 · d0d8221 · d0d8221
1 parent ba36366
commit d0d8221
Show file tree

Hide file tree

Showing 5 changed files with 164 additions and 2 deletions.
diff --git a/README.md b/README.md
@@ -4,4 +4,91 @@
   SPDX-License-Identifier: Apache-2.0
 -->
 
-# astarte-message-hub
+# Astarte Message Hub
+
+A central service that runs on (Linux) devices for collecting and delivering messages from N apps using 1 MQTT connection to Astarte.
+
+## Architecture
+The Astarte Message Hub is the main component that shares the Astarte connection to the nodes attached to it.
+The communication between the Hub and nodes is based on `gRPC` which is great for scenarios like real-time communication, low-power, low-bandwidth systems, and multi-language environments.
+`gRPC` makes the most out of `HTTP/2`, with multiplexed streaming and binary protocol framing. In addition, it offers performance advantages through the `Protobuf` message structure and features built-in code generation capability, which enables a multi-language environment.
+
+```mermaid
+flowchart LR
+  subgraph arch[  ]
+    direction TB
+    subgraph cloud[ ]
+        style cloud fill:#00b0f1,stroke:#ffffff
+        direction LR
+        subgraph astarte[Astarte]
+        style astarte fill:#127ab2,stroke:#ffffff,color:#fff
+        end
+    end
+    subgraph device[   ]
+    style device fill:#00b0f1, stroke:#ffffff
+    direction TB
+        astarte-mh[Astarte Message Hub]
+            style astarte-mh fill:#127ab2,stroke:#ffffff,color:#fff
+        astarte-mh <--> node1[Node 1]
+        astarte-mh <--> node2[Node 2]
+        astarte-mh <--> noden[Node...N]
+        style node1 stroke:#ffffff
+        style node2 stroke:#ffffff
+        style noden stroke:#ffffff
+    end
+  end
+  astarte <==> astarte-mh
+  style arch fill:#25516e,stroke:#c4c4c4,stroke-width:1 px,color:#fff,stroke-dasharray: 2 1
+```
+
+## GRPC MessageHub Service
+### Node
+A node is an entity connected to Astarte Message Hub, it can receive/send messages from/to Astarte via the Message Hub.
+A node is uniquely identified by its Node UUID and has an Introspection that is a list of Interfaces used by it for exchanging data with Astarte. 
+
+``` protobuf
+message Node {
+  string uuid = 1;
+  repeated Interface introspection = 2;
+}
+```
+### Interface 
+[Interfaces](https://docs.astarte-platform.org/snapshot/030-interface.html) are a core concept of Astarte which defines how data is exchanged between Astarte and its peers.
+
+``` protobuf
+message Interface {
+  string name = 1;
+  int32 major = 2;
+  int32 minor = 3;
+}
+```
+
+### Attach Method
+When a new node is connected to Message Hub, it will have to call `Attach` method to exchange data with Astarte.
+If the node was successfully attached, the method returns a gRPC stream into which the events received from Astarte(based on the declared Introspection) will be redirected.
+
+``` protobuf
+service MessageHub {
+  rpc Attach(Node) returns (stream NodeMessage) {}
+  ....
+}
+```
+
+``` mermaid
+sequenceDiagram
+    participant Node1
+    participant AstarteMessageHub
+    participant Astarte
+    Node1->>AstarteMessageHub: attach(node)
+    AstarteMessageHub->>Astarte: sendIntrospection()
+    
+    alt when the introspection process fails
+         AstarteMessageHub->>Node1: Unable to attach the node
+    end
+    
+    Astarte->>AstarteMessageHub: Event data for node1
+    AstarteMessageHub->>Node1: Event data
+    Astarte->AstarteMessageHub: Event data for node1
+    AstarteMessageHub->>Node1: Event data
+```
+
diff --git a/build.rs b/build.rs
@@ -19,7 +19,11 @@
  */
 
 fn main() {
-    let proto_files = &["proto/astarteplatform/msghub/message_hub_service.proto"];
+    let proto_files = &[
+        "proto/astarteplatform/msghub/message_hub_service.proto",
+        "proto/astarteplatform/msghub/node.proto",
+        "proto/astarteplatform/msghub/interface.proto",
+    ];
 
     tonic_build::configure()
         .compile(proto_files, &["proto"])

diff --git a/proto/astarteplatform/msghub/interface.proto b/proto/astarteplatform/msghub/interface.proto
@@ -0,0 +1,29 @@
+/*
+ * This file is part of Astarte.
+ *
+ * Copyright 2022 SECO Mind Srl
+ *
+ * Licensed 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+syntax = "proto3";
+
+package astarteplatform.msghub;
+
+message Interface {
+  string name = 1;
+  int32 major = 2;
+  int32 minor = 3;
+}
diff --git a/proto/astarteplatform/msghub/message_hub_service.proto b/proto/astarteplatform/msghub/message_hub_service.proto
@@ -21,3 +21,15 @@
 syntax = "proto3";
 
 package astarteplatform.msghub;
+
+import "astarteplatform/msghub/interface.proto";
+import "astarteplatform/msghub/node.proto";
+
+service MessageHub {
+  rpc Attach(Node) returns (stream NodeMessage) {}
+}
+
+message NodeMessage{
+  Interface interface = 1;
+  string path = 2;
+}
diff --git a/proto/astarteplatform/msghub/node.proto b/proto/astarteplatform/msghub/node.proto
@@ -0,0 +1,30 @@
+/*
+ * This file is part of Astarte.
+ *
+ * Copyright 2022 SECO Mind Srl
+ *
+ * Licensed 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+syntax = "proto3";
+
+package astarteplatform.msghub;
+
+import "astarteplatform/msghub/interface.proto";
+
+message Node {
+  string uuid = 1;
+  repeated Interface introspection = 2;
+}