From d126abf39b512b49f5713cd2fcda6230ba75f1e9 Mon Sep 17 00:00:00 2001
From: Philippe PITTOLI <p.pittoli@unistra.fr>
Date: Tue, 17 Dec 2019 22:08:54 +0100
Subject: [PATCH] README, with a rationale draft.

---
 .gitignore |  5 +++++
 README.md  | 42 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 47 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 README.md

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..5948af2
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,5 @@
+shard.lock
+bin
+lib
+
+.*
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e5643f3
--- /dev/null
+++ b/README.md
@@ -0,0 +1,42 @@
+# protocol overview
+
+1. AUTHENTICATION: authentication message and informations about messages to transfer
+2. RESPONSE: OK or ERROR
+3. loop:
+	# TRANSFER: message id, file chunk
+	# REPONSE: Ok
+
+# messages content
+
+format: IPC USER MESSAGE TYPE, JSON ENCODED MESSAGE
+
+1. AUTHENTICATION message
+	1, { message-id: "UUID", token: "JWT", files: [
+			{ name: "NAME", size: SIZE-IN-BYTES (unsigned int 64 bits) },
+			{ name: "NAME", size: SIZE-IN-BYTES (unsigned int 64 bits) },
+		], fid: "UUID", tags: [ TAG-NAME, TAG-NAME ]
+	}
+	note: The server knows the user id from the token (JWT) and stores the received files in a
+2. RESPONSE message
+    2, { message-id: "UUID", response: "Ok" }
+    or
+    2, { message-id: "UUID", response: "Error", reason: "REASON" }
+3. TRANSFER message
+	3, { message-id: "UUID", chunk: "UUID", data: [ BINARY DATA ] }
+
+# Rationale
+
+### Why don't we just trust TCP to carry the whole file?
+The application layer has to know which parts are missing so we can transfer them later (in another connection, maybe).
+
+### Why message id?
+The client and the server do not have a direct TCP connection together, there may be proxies.
+The client cannot trust its TCP connection to know exactly what are the parts the server really got.
+The file server to proxy connection can be dropped, we have to ensure the communication between the client and the server.
+
+
+# How this works:
+
+* libipc is used to communicate
+* messages are: JSON encoded, 1KB buffered data
+* message example: { message-id: "UUID", chunk: "UUID", data: [1KB BINARY DATA] }