Merge branch 'main' into routing-protocol

HAW-RN · Jun 10, 2024 · 8b1f7f8 · 8b1f7f8
2 parents be3758b + f04fbdf
commit 8b1f7f8
Show file tree

Hide file tree

Showing 10 changed files with 184 additions and 48 deletions.
diff --git a/protocol/00_header.md b/protocol/00_header.md
@@ -1,5 +1,7 @@
 ![Logo](./images/banner.png)
 
+# SWAG: **S**imple **W**ebbased **A**synchronous **G**roupchat Protcool
+
 ## Authors
 
 ### Chair

diff --git a/protocol/01_introduction.md b/protocol/01_introduction.md
@@ -1,5 +1,13 @@
 # Introduction
 
+SWAG is a protocol for Simple Web-based Asynchronous Group chat. It is designed to be easy to use and easy to implement.
+
 ## Purpose
 
+The purpose of this document is to provide a detailed description of the SWAG protocol. It is intended for developers who want to implement the SWAG protocol in their applications.
+
 ## General requirements
+
+The SWAG protocol is designed to be easy to use and easy to implement. It is built on top of the TCP protocol and uses JSON for data serialization. The protocol is designed to be extensible, so that new features can be added in the future by appending new fields to the JSON messages.
+
+Individuals don't require a direct connection to each other to communicate. Instead, they are able to forward messages via other participants. The clients are responsible for routing messages between clients and maintaining the state of the chat room with no central server.
diff --git a/protocol/02_use_cases.md b/protocol/02_use_cases.md
@@ -1 +1,26 @@
 # Use-Cases
+<img src="./images/UseCase.png" width="806" height="806">
+
+### 1. Start New Connection
+Client A establishes a connection to another Client B using TCP. Client A sends a new_connection message to Client B which responds with its routing table, updating Client A's routing table. Both Clients add information about the connection to their routing tables.
+
+### 2. Forward Message
+Client A receives a message and checks its destination address. If Client A is not the destination, it checks its routing table for the destination address and sends the message to the destination, if directly connected or to the next address on the route, if one is available.
+
+### 3. Update Routing Table
+Every X (mili)seconds Client A requests all directly connected Clients to send a routing_table_update containing all information in their routing table besides the routing information it got from Client A. When receiving routing_table_update, Client A will update its routing table with any new information from it. If a Client does not answer this request, they will treated as unavailable.
+
+### 4. Send Routing Table
+When requested Client A sends a routing_table_update to the requesting Client containing all information in Client A's routing table besides the information it got from the requesting Client.
+
+### 5. Quit Client
+Client A sends a quit_message to all directly connected Clients. Afterwards the program ends itself.
+
+### 6. source is unavailable
+Client A marks all routes in its routing table reachable through the source including the source itself as unreachable and sends a routing table update.
+
+#### Client specific
+- send message
+- receive message
+- display message
+- display available participants
diff --git a/protocol/03_0_encoding.md b/protocol/03_0_encoding.md
@@ -0,0 +1,51 @@
+# Encoding
+
+## Requirements
+- The protocols must use JavaScript Object Notation (JSON).
+- The JSON string must be UTF-8 encoded.
+- ...
+
+## Format
+A message is made up of two JSON strings, one for the header and the other for the data.
+
+### Header
+The header is always 53 _UTF-8_ characters long. That means the payload should be exactly 53 bytes long. 
+
+This allows the receiving side to first fill an input buffer with the data for exactly one JSON string, and extract further information from there. The content of the header is `{"length":"01234","crc32":"0123456789","type_id":"1"}`, or formatted to look more legible:
+```json
+{
+  "length": "01234",
+  "crc32" : "0123456789",
+  "type_id": "1"
+}
+```
+
+The information here is used to receive the data JSON.
+
+| Name   | Description                                             | Target Type         |
+|--------|---------------------------------------------------------|---------------------|
+| length | Length of the 2nd JSON string (Data) in bytes.          | `uint16` or `int32` | 
+| crc32  | CRC32 checksum over the buffer of the 2nd JSON string.  | `uint32` or `int64` |
+| type_id| The type of the message.                                | `byte (uint8)`      |
+
+To ensure that the header is always 53 characters long, all values are encoded as strings with leading zeros. The number of digits depends on the largest possible number of these values. All values must be treated as unsigned integers. If the chosen programming language does not support this, a larger data type must be selected. The recommended types are listed in the table above.
+
+### Packet Type
+The `type_id` field is used to determine the type of the message. The following types are defined:
+
+| ID | Type          | Description                |
+|----|---------------|----------------------------|
+| 1  | Message       | A routed message packet             |
+| 2  | CR            | Connection Request (Send Routingtable)  |
+| 3  | CRR           | Connect Request Reply (Send Routingtable)  |
+| 4  | SCC           | Send Connection Check  |
+| 5  | SCCR          | Reply |
+| 6  | STU           | Send Table Update  |
+
+## Handling Headers
+
+If a client is sending a message, it should first write a header. To do this, the size of the string-formatted JSON data and the CRC32 checksum of this data must be calculated and packed into a JSON-formatted header. This header must be aligned to 53 bytes as stated above. The header and the data are then sent immediately one after the other, with the header preceding the data (encapsulation).
+
+If a client is receiving a message, it should read 53 bytes from the input buffer to receive the header. After reading the data size from the header, the client can start reading the data section of the message using the data size. Then, the CRC32 checksum of the data section should be calculated and compared to the checksum specified in the header:  
+If the checksums are equal, the client can proceed with further processing, such as message forwarding or updating the routing table.  
+If the checksums are not equal, the message can be discarded and ignored.
diff --git a/protocol/03_1_shared_header.md b/protocol/03_1_shared_header.md
@@ -0,0 +1,25 @@
+# Shared Header
+
+The shared header is part of the data after the initial common header. It has a lot of information that is used to determine the type of the message, potential target and how to handle it.
+
+## Fields
+
+| Name | Description | Target Type |
+|------|-------------|-------------|
+| Source IP | IPv4 address of the sender | `string` |
+| Source Port | Port of the sender | `uint16 or int32` |
+| Destination IP | IPv4 address of the destination | `string` |
+| Destination Port | Port of the destination | `uint16 or int32` |
+| TTL | time to live of the package. maximum of 16 to 64 | `byte (uint8)` |
+
+## Example
+
+```json
+{
+    "source_ip": "192.168.101.1",
+    "source_port": 1234,
+    "dest_ip": "192.168.102.1",
+    "dest_port": 1234,
+    "ttl": 16
+}
+```
diff --git a/protocol/03_encoding.md b/protocol/03_encoding.md
diff --git a/protocol/04_routing_protocol.md b/protocol/04_routing_protocol.md
@@ -21,38 +21,35 @@ Participants must be able to forward Messages
 See "Shared Header" section
 
 ### Table
-| Target_IP |Target_Port | Next_IP | Next_Port | Hop-Count  |   
-|---|---|---|---|---| 
-|  IP | Port | IP | Port  | Integer  |   
-|  192.168.101.12 | 1234 | 192.168.101.13 |1243  | 2 |   
-|   |   |   | 
+| target_ip | target_port | next_ip  | next_port | hop_count  |   
+|---|---|---|--|---|
+|  192.168.101.12 | 1234 | 192.168.101.13 | 1243  | 2 |   
+|  10.0.0.5 | 1234 | 10.0.0.3 | 1234  | 4 |
+|  10.0.0.11 | 1234 | 10.0.0.6 | 1234  | 2 |
 
 ### Example Data
 
 ```json
 {
   "header":     {[...]}, // SEE SHARED HEADER
-  "data": "Participant A",
   "table": [
     {
       "target_ip": "10.0.0.5",
-      "target_port": "1234",
-      "next_ip": "10.0.0.3",
-      "next_port": "1243",
-      "hop_count": "4"
+      "target_port": 1234,
+      "next": "10.0.0.3",
+      "next_port": 1234,
+      "hop_count": 4
     },
     {
       "target_ip": "10.0.0.11",
-      "target_port": "1234",
+      "target_port": 1234,
       "next_ip": "10.0.0.6",
-      "next_port": "1243",
-      "hop_count": "2"
+      "next_port": 1234,
+      "hop_count": 2
     }
   ]
 }
-
 ```
-
 ## Packet Types (Ruben Marin Grez)
 
 Defined within the `type_id` field of the common header.
@@ -77,4 +74,4 @@ Defined within the `type_id` field of the common header.
 8. Participant A resets Timer to 10 seconds
 
 ## Example
-![Logo](./images/Routing_Protokoll_Sequenz_Diagram.png)
+![Logo](./images/Routing_Protokoll_Sequenz_Diagram.png)
diff --git a/protocol/05_routed_protocol.md b/protocol/05_routed_protocol.md
@@ -3,36 +3,18 @@ The task of the routed protocol is to transfer chat messages from one client to
 ## Requirements
 
 ## Packet format
-| Content          | Size in Byte | Max. size in JSON |
-|:---------------- | ------------:|------------------:|
-| Packagetyp       |            1 |                15 |
-| Source IP        |            4 |                 5 |
-| Source Port      |            2 |                15 |
-| Destination IP   |            4 |                 5 |
-| Destination Port |            2 |                 5 |
-| TTL              |            1 |                 2 |
-| Data             |          128 |               128 |
 
-## Procedure
+| Name     | Description | Target Type |
+|----------|-------------|-------------|
+| nickname | The nickname of the sender | `string` |
+| message  | The message to be sent | `string` |
 
 ## Example
 
 ```json
 {
-    "package_type":       "data_message"
-    "source_ip":          "192.168.123.122"
-    "source_port":        "6827"
-    "destination_ip":     "192.168.234.233"
-    "destination_port":   "234"
-    "ttl":                "16"
-    "data":               "Test Data"
+    "header":     {[...]}, // SEE SHARED HEADER
+    "nickname":           "Max Mustermann",
+    "message":               "Hello World!"
 }
 ```
-
-Flag: differentiation between Message, Routing-protocol, disconnection, connection failure ...
-Source IP: IPv4 address of the sender
-Source Port: Port of the sender
-Destination IP: IPv4 address of the destination
-Destination Port: Port of the destination
-TTL: time to live of the package. maximum of 16 to 64
-Data: message value limited to 128 chars in utf-8 for smaller package size
diff --git a/protocol/diagramme/UseCase.uxf b/protocol/diagramme/UseCase.uxf
@@ -0,0 +1,53 @@
+<diagram program="umletino" version="15.1"><zoom_level>11</zoom_level><help_text>Space for diagram notes
+</help_text><element><id>UMLActor</id><coordinates><x>0</x><y>352</y><w>66</w><h>121</h></coordinates><panel_attributes>User</panel_attributes><additional_attributes></additional_attributes></element><element><id>UMLGeneric</id><coordinates><x>198</x><y>22</y><w>517</w><h>836</h></coordinates><panel_attributes>Client A
+halign=left</panel_attributes><additional_attributes></additional_attributes></element><element><id>UMLUseCase</id><coordinates><x>231</x><y>143</y><w>132</w><h>66</h></coordinates><panel_attributes>*establish tcp*
+*connection*</panel_attributes><additional_attributes></additional_attributes></element><element><id>Relation</id><coordinates><x>66</x><y>165</y><w>187</w><h>231</h></coordinates><panel_attributes>
+
+start new Connection
+cbase=d
+</panel_attributes><additional_attributes>10;190;150;10</additional_attributes></element><element><id>Relation</id><coordinates><x>286</x><y>187</y><w>99</w><h>88</h></coordinates><panel_attributes>lt=.&gt;
+
+&lt;&lt;includes&gt;&gt;
+cbase=ur
+</panel_attributes><additional_attributes>10;20;10;60</additional_attributes></element><element><id>UMLActor</id><coordinates><x>726</x><y>264</y><w>110</w><h>121</h></coordinates><panel_attributes>other Clients</panel_attributes><additional_attributes></additional_attributes></element><element><id>UMLUseCase</id><coordinates><x>220</x><y>253</y><w>154</w><h>66</h></coordinates><panel_attributes>*send new_connection*
+*message*</panel_attributes><additional_attributes></additional_attributes></element><element><id>Relation</id><coordinates><x>352</x><y>165</y><w>429</w><h>132</h></coordinates><panel_attributes>lt=-&gt;</panel_attributes><additional_attributes>10;10;370;100</additional_attributes></element><element><id>UMLUseCase</id><coordinates><x>220</x><y>363</y><w>154</w><h>55</h></coordinates><panel_attributes>*update routing table*</panel_attributes><additional_attributes></additional_attributes></element><element><id>Relation</id><coordinates><x>286</x><y>308</y><w>99</w><h>77</h></coordinates><panel_attributes>lt=.&gt;
+
+&lt;&lt;includes&gt;&gt;
+cbase=r
+</panel_attributes><additional_attributes>10;10;10;50</additional_attributes></element><element><id>Relation</id><coordinates><x>363</x><y>275</y><w>396</w><h>77</h></coordinates><panel_attributes>lt=&lt;-</panel_attributes><additional_attributes>340;50;10;10</additional_attributes></element><element><id>Relation</id><coordinates><x>363</x><y>341</y><w>396</w><h>66</h></coordinates><panel_attributes>lt=&lt;-&gt;</panel_attributes><additional_attributes>10;40;340;10</additional_attributes></element><element><id>UMLUseCase</id><coordinates><x>462</x><y>231</y><w>165</w><h>66</h></coordinates><panel_attributes>*send*
+*routing_table_update*</panel_attributes><additional_attributes></additional_attributes></element><element><id>Relation</id><coordinates><x>616</x><y>253</y><w>143</w><h>66</h></coordinates><panel_attributes>lt=&lt;-&gt;
+</panel_attributes><additional_attributes>110;40;10;10</additional_attributes></element><element><id>UMLUseCase</id><coordinates><x>220</x><y>440</y><w>154</w><h>55</h></coordinates><panel_attributes>*send message*</panel_attributes><additional_attributes></additional_attributes></element><element><id>Relation</id><coordinates><x>649</x><y>374</y><w>121</w><h>286</h></coordinates><panel_attributes>lt=&lt;-</panel_attributes><additional_attributes>10;240;90;10</additional_attributes></element><element><id>Relation</id><coordinates><x>44</x><y>440</y><w>209</w><h>198</h></coordinates><panel_attributes>lt=&lt;-</panel_attributes><additional_attributes>10;10;170;160</additional_attributes></element><element><id>Relation</id><coordinates><x>55</x><y>407</y><w>187</w><h>77</h></coordinates><panel_attributes>new message to participant
+cbase=u
+
+</panel_attributes><additional_attributes>10;20;150;50</additional_attributes></element><element><id>UMLUseCase</id><coordinates><x>495</x><y>484</y><w>154</w><h>55</h></coordinates><panel_attributes>*source is*
+*unreachable*</panel_attributes><additional_attributes></additional_attributes></element><element><id>Relation</id><coordinates><x>561</x><y>528</y><w>99</w><h>88</h></coordinates><panel_attributes>lt=.&gt;
+   &lt;&lt;extends&gt;&gt;
+cbase=r
+</panel_attributes><additional_attributes>10;10;10;60</additional_attributes></element><element><id>UMLUseCase</id><coordinates><x>231</x><y>594</y><w>154</w><h>55</h></coordinates><panel_attributes>*display message*</panel_attributes><additional_attributes></additional_attributes></element><element><id>Relation</id><coordinates><x>374</x><y>605</y><w>132</w><h>77</h></coordinates><panel_attributes>lt=.&gt;
+&lt;&lt;extends&gt;&gt;
+cbase=u
+</panel_attributes><additional_attributes>10;10;100;45</additional_attributes></element><element><id>UMLNote</id><coordinates><x>231</x><y>682</y><w>242</w><h>44</h></coordinates><panel_attributes>Condition: {Client A is destination}
+extension point: receive message
+bg=pink</panel_attributes><additional_attributes></additional_attributes></element><element><id>UMLNote</id><coordinates><x>220</x><y>528</y><w>286</w><h>55</h></coordinates><panel_attributes>Condition: {Client A is destination and its a
+quit message}
+extension point: receive message
+bg=pink</panel_attributes><additional_attributes></additional_attributes></element><element><id>Relation</id><coordinates><x>495</x><y>550</y><w>99</w><h>33</h></coordinates><panel_attributes>lt=.()</panel_attributes><additional_attributes>10;10;70;10</additional_attributes></element><element><id>Relation</id><coordinates><x>418</x><y>627</y><w>33</w><h>77</h></coordinates><panel_attributes>lt=.()</panel_attributes><additional_attributes>10;50;10;10</additional_attributes></element><element><id>UMLUseCase</id><coordinates><x>484</x><y>594</y><w>176</w><h>121</h></coordinates><panel_attributes>*receive message*
+--
+*extension points*
+source is unreachable
+display message
+forward message
+valign=top</panel_attributes><additional_attributes></additional_attributes></element><element><id>UMLUseCase</id><coordinates><x>231</x><y>55</y><w>132</w><h>66</h></coordinates><panel_attributes>*quit client*</panel_attributes><additional_attributes></additional_attributes></element><element><id>Relation</id><coordinates><x>33</x><y>77</y><w>220</w><h>286</h></coordinates><panel_attributes></panel_attributes><additional_attributes>10;240;180;10</additional_attributes></element><element><id>Text</id><coordinates><x>759</x><y>231</y><w>44</w><h>33</h></coordinates><panel_attributes>1..*
+style=wordwrap</panel_attributes><additional_attributes></additional_attributes></element><element><id>Relation</id><coordinates><x>363</x><y>363</y><w>396</w><h>121</h></coordinates><panel_attributes>lt=&lt;-</panel_attributes><additional_attributes>340;10;10;90</additional_attributes></element><element><id>UMLUseCase</id><coordinates><x>231</x><y>792</y><w>154</w><h>55</h></coordinates><panel_attributes>*display available*
+*participants*</panel_attributes><additional_attributes></additional_attributes></element><element><id>Relation</id><coordinates><x>33</x><y>462</y><w>220</w><h>374</h></coordinates><panel_attributes></panel_attributes><additional_attributes>10;10;180;320</additional_attributes></element><element><id>Relation</id><coordinates><x>352</x><y>242</y><w>132</w><h>44</h></coordinates><panel_attributes>lt=.&gt;
+&lt;&lt;includes&gt;&gt;</panel_attributes><additional_attributes>10;20;100;20</additional_attributes></element><element><id>Relation</id><coordinates><x>352</x><y>77</y><w>429</w><h>198</h></coordinates><panel_attributes>lt=&lt;-
+       quit message
+cbase=u
+</panel_attributes><additional_attributes>370;160;10;10</additional_attributes></element><element><id>Relation</id><coordinates><x>561</x><y>704</y><w>99</w><h>88</h></coordinates><panel_attributes>lt=.&gt;
+   &lt;&lt;extends&gt;&gt;
+</panel_attributes><additional_attributes>10;60;10;10</additional_attributes></element><element><id>UMLUseCase</id><coordinates><x>495</x><y>770</y><w>154</w><h>55</h></coordinates><panel_attributes>*forward message*</panel_attributes><additional_attributes></additional_attributes></element><element><id>Relation</id><coordinates><x>352</x><y>396</y><w>242</w><h>110</h></coordinates><panel_attributes>lt=.&gt;
+
+
+&lt;&lt;includes&gt;&gt;</panel_attributes><additional_attributes>200;80;10;10</additional_attributes></element><element><id>UMLNote</id><coordinates><x>231</x><y>737</y><w>264</w><h>44</h></coordinates><panel_attributes>Condition: {Client A is not destination}
+extension point: receive message
+bg=pink</panel_attributes><additional_attributes></additional_attributes></element><element><id>Relation</id><coordinates><x>484</x><y>737</y><w>110</w><h>33</h></coordinates><panel_attributes>lt=.()</panel_attributes><additional_attributes>10;10;80;10</additional_attributes></element></diagram>
diff --git a/protocol/images/UseCase.png b/protocol/images/UseCase.png