Merge pull request #3 from mangledbottles/readme

Readme

Author: mangledbottles

Assets/ClientApplication.png

@@ -1,11 +1,26 @@
-# Vue 3 + Typescript + Vite
+# Client ElectronJS Desktop Application
+This is the [ElectronJS](https://www.electronjs.org/) Desktop Application for the Client built using [VueJS](https://vuejs.org/) and [Typescript](https://www.typescriptlang.org).
 
-This template should help get you started developing with Vue 3 and Typescript in Vite. The template uses Vue 3 `<script setup>` SFCs, check out the [script setup docs](https://v3.vuejs.org/api/sfc-script-setup.html#sfc-script-setup) to learn more.
+The Client uses the Node.js UDP Datagram to communicate with the Switcher and send messages across the network of Routers to another another Client.
 
-## Recommended IDE Setup
+## Installation
+```bash
+npm install
 
-- [VSCode](https://code.visualstudio.com/) + [Volar](https://marketplace.visualstudio.com/items?itemName=johnsoncodehk.volar)
+# Start the Electron Application
+npm run electron:dev
 
-## Type Support For `.vue` Imports in TS
+# Build for production
+npm run app:build
+```
+## Application
+![Client Application](../Assets/ClientApplication.png)
+This application is started when the Client process is created. The Client attempts to connect to the Switcher and if successful, it will be allocated an IP address and port dependent on the network and available ports.
 
-Since TypeScript cannot handle type information for `.vue` imports, they are shimmed to be a generic Vue component type by default. In most cases this is fine if you don't really care about component prop types outside of templates. However, if you wish to get actual prop types in `.vue` imports (for example to get props validation when using manual `h(...)` calls), you can enable Volar's `.vue` type support plugin by running `Volar: Switch TS Plugin on/off` from VSCode command palette.
+`./src/App.vue`
+
+The GUI and main funcionality of the Client program is located in this file.
+
+### Sending Messages
+![Client Sending Message](../Assets/ClientSendingMessage.png)
+Once the network has been established with an active Switcher and 3 connected Routers, the sending Client can send a message through the network to the receiving Client via a UDP Datagram.

Assets/ClientSendingMessage.png

@@ -0,0 +1,68 @@
+# OpenFlow UDP Socket Protocol
+![OpenFlow Network](Assets/Network.png)
+
+This project is an implementation of the [OpenFlow Protocol](https://en.wikipedia.org/wiki/OpenFlow) using the [Node.js UDP Datagram Socket Library](https://nodejs.org/api/dgram.html). The core functionality of this system provides a front-end user interface for the client which connects to the OpenFlow Network.
+
+The OpenFlow network consists of a number of **routers** that **forward message**s and are controlled by a centralised switcher.
+
+The switcher is a simple device that allows the routers to communicate with each other. It also allows the routers to communicate with the network.
+
+## Project Structure
+This project is divided into the following sections:
+- [/Server](/Server)
+  - Writen in NodeJS using the [dgram](https://nodejs.org/api/dgram.html) module to create a Switcher and a number of Routers.
+- [/Client](/Client)
+  - An [ElectronJS](https://www.electronjs.org/) desktop GUI application which provides a user interface that connects to the OpenFlow Network (in /Server).
+  
+## Downloading Repository
+```
+git clone https://github.com/mangledbottles/OpenFlow-Forwarding.git
+
+cd OpenFlow-Forwarding
+
+# See documentation inside /Client for installation of ElectronJS application
+# See documentation inside /Server for installation of NodeJS Switcher and Routers
+```
+
+## Communication Protocol
+Communication between the Switcher, multiple Routers and multiple Clients is handled by a universal Protocol Type system.
+
+| Protocol Type | Description | Components [Origin -> Destination] |
+| ------------- | ----------- | ---------- |
+| #0 | Switcher accepted this current Router on network | Switcher -> Router |
+| #1             | New Router Detected on Network by Switcher | Router -> Switcher |
+| #2 | Router querying Switcher for information about Clients from Forwarding Table | Router -> Switcher |
+| #3 | Client connecting to Router to get information about Forwarding Table | Client -> Router |
+| #4 | Router received information about a Client from Switcher via Flowtable | Switcher -> Router |
+| #5 | Router received message instructions from Client to send message over the network | Client -> Router |
+| #6 | Router received updated information about current Router | Switcher -> Router |
+
+## Project Functionality
+![Flow Forwarding](Assets/FlowForwardingGraphic.png)
+1. Switcher is started to commence the network
+2. 3 Routers are started and join the network
+3. A client ("Alice") joins the network and is connected by the Switcher
+4. A secondary client ("Bob") joins the network and is connected by the Switcher
+5. Alice sends a message to Bob
+6. The message is forwarded from Alice to Router 1 to Router 2 to Router 3 and finally to Bob.
+
+
+## Wireshark
+The following diagram shows the communication between the Switcher, Routers and Clients.
+
+### Example 1: Router connecting to Network via Switcher
+| No. | Time | Source | Destination | Protocol | Length | Info |
+| ---- | ---- | ------ | ----------- | -------- | ----- | ---- |
+| 5 | 10.382165 | 127.0.0.1 | 127.0.0.1 | UDP | 61 | 65469 -> 51510 |
+
+| Hexadecimal Payload | Base10 Decoded |
+| ------------------- | -------------- |
+| 0000 0020 7b 22 74 79 70 65 22 3a 31 2c 22 6d 65 73 73 61 | {"type": 1, "messa |
+| 0010 67 65 22 3a 22 52 6f 75 74 65 72 22 7d | ge":"Router"} |
+
+- Router on port 65469 is sending a message to the Switcher on port 51510 trying to join the network. 
+- Type is set to 1, as seen in [Communication Table protocol type 1](#Communication-Protocol).
+
+## References
+- [0] OpenFlow - https://en.wikipedia.org/wiki/OpenFlow
+- [1] Node Datagram Library - https://nodejs.org/api/dgram.html

Assets/Dockerfile.png

@@ -0,0 +1,52 @@
+# Switcher and Router
+This folder is the source code for the Switcher and Routers on the OpenFlow Protocol Network.
+
+## Installation
+```
+npm install
+
+# Start the Switcher
+npm run switcher
+
+# Start a Router (can start as many as you want)
+npm run router
+```
+
+## Switcher
+`./src/Switcher.ts`
+
+The Switcher is a NodeJS application that listens on port 51510 for OpenFlow messages. The Switcher is responsible for managing the Routers and Clients.
+
+The Switcher contains a FlowTable that is used to control the flow of traffic between Clients and Routers.
+| Router | In | Out |
+|--------|----|-----|
+| R1 | E1 | R2 |
+| R2 | R1 | R2 |
+| R3 | R2 | E2 |
+
+
+## Router
+`./src/Router.ts`
+
+The Router is a NodeJS application that can be started as many different processes to create multiple OpenFlow layers that connect together.
+
+When a new Router process is created, it will send a message to the Switcher to connect and if successful, it will be added to the FlowTable.
+
+If the Router is #1 on the network, its details will be stored and forwarded to the Client once they join the network. 
+
+When the network is filled out with 2 other Routers and a receiving Client, the initial Client can send a message to the receiving Client and the message will be forwarded the #1 Router.
+
+Router #1 will then forward the message to Router #2 and Router #2 will forward the message to Router #3 and Router #3 will forward the message to the receiving Client.
+
+![Flow Forwarding](../Assets/FlowForwarding.png)
+
+## Dockerising the Switcher
+![Dockerfile](../Assets/Dockerfile.png)
+
+```
+# Build the Docker image
+docker build -t dermot/openflow:1.0 .
+
+# Run the Docker image inside a container
+docker run -it --rm --name openflow -p 51510:51510 dermot/openflow:1.0
+```