Report fixes

Author: jmemcc

Project/cits3002_report_22238418_22983427.pdf

@@ -1,168 +1,117 @@
-# Protocol
+#### CITS3002 - Networks Project
 
-For our client-server protocol, communications are undertaken through used of a fixed size, 64 byte, UTF-8 header. This header is sent between the client and server in order to describe the manner in which communications will proceed. 
+*Jamie McCullough **22238418** and Cormac Sharkey **22983427***
 
-The header is comprised of up to three components: (1) communication code; (2) option flags; and (3) length of the message to be sent (called the payload).  The payload is then sent to the recipient, with it's data expected to match the header-described attributes. Payloads can be of variable length, which is why their length is indicated by the header.
+---
 
-## Communication Codes
+For our client-server protocol, communications are undertaken through used of a fixed size, 64 byte, UTF-8 header. The header is comprised of up to three components: communication code; option flags; and length of the message to be sent (payload). Payload is then sent to the recipient, with it's data expected to match the header-described attributes. 
 
-These are the first two bytes of the header, called the communication code, or `code`. The code is one of a set of preset values, each indicating the manner in which communications should proceed. These values are as follows:
+#### Communication Codes
 
-#### `DISCONN_MSG`  (!D)
+##### `DISCONN_MSG`  (!D)
 
-- **Client**: sends to server once it has finished with it.
-- **Server**: cleans up data structures for client
+**Client**: Sends to server once it has finished with it.
+**Server**: Cleans up data structures for client.
 
-#### `COMMAND_MSG`  (!C)
+##### `COMMAND_MSG`  (!C)
 
-- **Client**: Sends this with a payload of command to execute.
-- **Server**: Executes the payload from this packet, and captures exit state, stdout, stderr, and any generated files, and passes it off to the client
+**Client**: Sends this with a payload of command to execute.
+**Server**: Executes payload, captures exit state, stdout, stderr, and generated files, passing them to client.
 
-#### `REQUEST_MSG`  (!R)
+##### `REQUEST_MSG`  (!R)
 
-- **Client**: Sends this to indicate to the server that it will need to receive files
-- **Server**: Prepares to receive files from the client
+**Client**: Sends this to indicate to the server that it will need to receive files.
+**Server**: Prepares to receive files from the client.
 
-#### `SUCCEED_RSP` (!S)
+##### `SUCCEED_RSP` (!S)
 
-- **Client**: Indicates success, should keep processing the packet and rakefile. Exit code equals 0 since otherwise it would be a FAILURE_RSP packet
-- **Server**: Sends this to indicate execution was successful (exit code == 0)
+**Client**: Indicates success, keeps processing packet and Rakefile. 
+**Server**: Sent to indicate execution was successful (exit code == 0).
 
-#### `FAILURE_RSP`  (!F)
+##### `FAILURE_RSP`  (!F)
 
-- **Client**: Indicates failure, receive two packets, one containing the stderr and one containing the exit code.
-- **Server**: Sends this to indicate execution was unsuccessful. Detect based on exit code.
+**Client**: Indicates failure, receive two packets, one containing the stderr and one containing the exit code.
+**Server**: Sends this to indicate execution was unsuccessful. Detect based on exit code.
 
-#### `EXECUTE_GET`  (!E)
+**`EXECUTE_GET`  (!E)**
 
-- **Client**: Sends this to get current amount of requests server is servicing
-- **Server**: Sends active thread count to client, effectively the load of the server.
+**Client**: Sends this to get current amount of requests server is servicing
+**Server**: Sends active thread count to client, effectively the load of the server.
 
+#### Option Flags
 
+**`STDOUTP` (S)**: Set if the packet contains standard output
+**`INCFILE` (I):** Set if files to be sent back to client for it to prepare to receive a filestream.
+**`FILETRN` (F):** Set only on filestream packets
 
-## Option Flags
+#### Message Length
 
-The next three bytes are "options", only used on successful execution responses. These are positionally sensitive, and are either set, or unset(replaced with a space):
+Last bytes indicate the length of the payload. This value is padded out to be the length of the remaining bytes in the header. i.e. Message sent with code of `!E`  would be padded by 62 bytes of white space, bringing the length to 64 bytes total.
 
-* STDOUTP         = "S"
-* INCFILE         = "I"
-* FILETRN         = "F"
-* S is set if the packet contains standard output
-* I is set if output files are to be sent back to the client, and for it to prepare to receive a filestream
-* F is set only on filestream packets
+#### Filestream Protocol
 
-Finally, the next bytes indicate the length of the payload, and the rest of the header is padded out to 64 bytes total with spaces.
+Filestreams are multiple files to sent and received between the client and server. Each consists of a metadata packet, packets for each filename, filesize, and for transfer confirmation. Filestreams use these codes to replace the first two bytes of  "options", with last byte of options, set to` F` to indicate it is a filestream. Meta packets are have all three options set. i.e  `!S` + `SIF` + `length` + `padding`
 
-## Filestream protocol
+    FILENAME    = "!N"	FILETRAN    = "!T" FILESIZE    = "!Z"
+**Header**: `!S!NF7[57 spaces]`	**Payload**: `Dog.txt`
 
-Filestreams are just multiple files to be sent and received by a client and server. Each filestream consists of a metadata packet, and for each file, packets for filename, filesize, and for transfer confirmation. Filestreams use one of these codes in replacement of the first two bytes of the "options", with the last byte of options set to F to indicate that it is a filestream packet. The metadata packet is distinguished by having all three normal options set, e.g `!S` + `SIF` + payload length + padding
-
-    FILENAME    = "!N"
-    FILETRAN    = "!T"
-    FILESIZE    = "!Z"
-As an example, the client receiving a filestream might ask for the filename of one of the files its receiving by sending off (padded to 64 bytes)`!N`, and get this back:
-	Header: `!S!NF7[57 spaces]`
-	Payload: `Dog.txt`
-
-An example exchange between client and server, with the client sending a filestream of dog.txt(34 bytes) and feline.txt(88 bytes) to the server, as requirements. Note that all non file traffic is padded to 64 bytes with spaces, which is not shown here.
+**Example:** `dog.txt` and `feline.txt`.
 
 ```
 |--------!R--------->| Indicate requirements
 |------!SSIF2------->| Client sends metadata packet showing 2 files to be sent
-
 |<-------!N----------| Server asks for name of first file
-|------!S!N7-------->| Client sends 64 byte header indicating 7 byte filename payload
-|------dog.txt------>| Client sents payload of filename
+|------!S!N7-------->| Client sends header indicating 7 byte filename 
+|------dog.txt------>| Client sends payload of filename
 |<-------!Z----------| Server asks for filesize of first file
-|------!S!Z2-------->| Client sends 64 byte header indicating 2 byte file size payload
-|--------34--------->| Client sents payload of file size
+|------!S!Z2-------->| Client sends header indicating 2 byte file size
+|--------34--------->| Client sends payload of file size
 |<-------!T----------| Server requests transmission to start
-|-The dog or domes..>| Client begins transfer of file. Server receives based on filesize and saves to file based on received filename
-
-|<-------!N----------| Server asks for name of second file
-|------!S!N10------->| Client sends 64 byte header indicating 10 byte filename payload
-|------feline.txt--->| Client sents payload of filename
-|<-------!Z----------| Server asks for filesize of second file
-|------!S!Z2-------->| Client sends 64 byte header indicating 2 byte file size payload
-|--------88--------->| Client sents payload of file size
-|<-------!T----------| Server requests transmission to start
-|-Feline may refer..>| Client begins transfer of file. Server receives based on filesize and saves to file based on received filename
-
+|-The dog or domes..>| Client begins transfer of file. 
+Server receives based on filesize and saves to file based on received filename
+[Repeat steps 3 onward for feline.txt]
 ```
 
-# Execution Sequence
+#### Execution Walkthrough
 
-Test case: One client, two servers
-
-```PORT
+```makefile
 HOSTS = host1 host2
 
 actionset1:
 	remote-cc -c func1.c
 		requires func1.c
-	remote-cc -c func2.c
-		requires func2.c
+[...]
+```
 
-actionset2:
-	remote-cc -c program2.c
-		requires program2.c
+1. Client parses the rake file then looks at the actionset.
 
-actionset3:
-	remote-cc -o program2 program2.o func1.o func2.o
-		requires program2.o func1.o func2.o
-```
+2. `remote-cc -c func1.c requires func1.c`
 
-* Client parses the rake file successfully
-* Client looks at the first actionset, and for each action:
-  - `remote-cc -c func1.c requires func1.c`
-    - Polls host1 and host2 by sending `!E`(plus payload length and padding).
-      - Receives from host1:
-        - Header: `!E1[padding]`
-        - Payload: `0`
-      - Receives from host2
-        - Header: `!E1[padding]`
-        - Payload: `0`
-      - Neither are busy, so picks host1.
-    - Sees func1.c is required for action
-    - Sends `!R`(plus payload length and padding) to server, then sends filestream of func1.c
-    - Sends `!C`(plus payload length and padding) to server, with payload `remote-cc -c func1.c`
-    - Server executes command, and detects output to send back
-    - Client doesn''t wait for response, but adds host1's socket to a watchlist, and increments the count of commands sent by one
-  - `remote-cc -c func2.c requires func2.c`
-    + Polls host1 and 2.
-      - Receives from host1:
-        - Header: `!E1[padding]`
-        - Payload: `1`
-      - Receives from host2
-        - Header: `!E1[padding]`
-        - Payload: `0`
-    + 1 has one more active thread than 2 (it is currently compiling our first action), so we pick 2
-    + Sees func2.c is required for action
-    - Sends `!R` (plus payload length and padding) to server, then sends filestream of func2.c
-    - Sends `!C` (plus payload length and padding) to server, with payload `remote-cc -c func2.c
-    - Server executes command, and detects output to send back
-    - Client doesn''t wait for response, but adds host2's socket to a watchlist, and increments the count of commands sent by one
-  * Until commands sent = 0
-    - select() our watchlist, see 1 is ready
-      + Get header
-      + `!SSI 0[padding]`
-      + Get payload
-        * Nothing, no stdout
-      + I is set, so we pass the socket off to the filestream handler and receive func1.o
-    - select() our watchlist, see 2 is ready
-      + Get header
-      + `!SSI 0[padding]`
-      + Get payload
-        * Nothing, no stdout
-      + I is set, so we pass the socket off to the filestream handler and receive func2.o
-
-  Repeat this process for actionsets 2 and 3, unless one of these actions failed. If one did, terminate.
-
-# Remote compilation performace
+   - Polls host1 and host2 by sending `!E`(plus payload length).
 
-Remote compilation performs better under these conditions:
+   - Receives from host1: `!E1[padding]` and `0`
 
-* The server has a faster compilation time than the client. (Perhaps the client is a small, embedded device, and the server is a proper workstation)
-* This performance difference is larger than the performance penalty incurred by sending the files over a network. (If the network is slow enough, it can simply take more time to transfer requirements than any time saved by using a better CPU)
+   - Receives from host2`!E1[padding]` and  `0`
 
-Additional considerations include that large complex compilations can be spread across an arbitrary amount of servers, so a huge task which can be executed in parallel would perform better remotely than locally.
+   - Neither busy, picks host1, sees `func1.c` is required for command
+
+   - Sends `!R` + payload length, then sends filestream of `func1.c`
+
+   - Sends `!C` + payload length to server, with payload `remote-cc -c func1.c`
+
+   - Server executes command, detects output to send 
+
+   - Client doesn't wait, instead adds host1 socket to watchlist, incrementing command sent count. 
+
+3. Until commands waiting = `0`, `select()` watchlist, see host 1 is ready:
+   - Get header and payload `!SSI 0[padding]`and nothing (no stdout)
+   - `I` set, so pass socket to filestream handler and receive `func1.o`
+
+4. Repeat this process for other actionsets (unless a command failed, then terminate).
+
+### Remote Compilation Performance
+
+Remote compilation performs better under these conditions:
+(1) The server has a faster compilation time than the client. Perhaps the client is a small, embedded device, and the server is a proper workstation.
+(2) Performance difference is larger than performance penalty incurred by sending over a network. If the network is slow, it can take more time to transfer requirements than that saved through a better CPU.
+(3) Large complex compilations can be spread across an arbitrary amount of servers, a huge task which can be executed in parallel would perform better remotely than locally.