From: Ramakrishnan Muthukrishnan <ram@rkrishnan.org>
Date: Sun, 17 Jul 2016 04:05:57 +0000 (+0530)
Subject: beginning of a design doc
X-Git-Url: https://git.rkrishnan.org/specifications/components/com_hotproperty/frontends?a=commitdiff_plain;h=e53a7fefaaec98a98da291afcfce89ad9c11d1d8;p=functorrent.git

beginning of a design doc
---

diff --git a/doc/design.md b/doc/design.md
new file mode 100644
index 0000000..e5dbd9d
--- /dev/null
+++ b/doc/design.md
@@ -0,0 +1,53 @@
+2016-03-10:
+
+A rough sketch of the design of the program.
+
+In the Unix tradition, FuncTorrent takes either a .torrent file as input or one
+can `cat' the .torrent file and pipe the output into the program:
+
+$ cat foo.torrent | ./functorrent
+
+As of 10/Mar/2016, FuncTorrent supports only HTTP tracker.
+
+Each module starts up as a thread, so we have FileSystem thread, we have a Tracker
+Client thread. We have a main client thread, that receives pieces. We also have a 
+Server thread that serves pieces.
+
+The messages themselves are not exposed outside the module. Instead, a function that
+create a message passing channel is exposed and also helper functions that talk via
+the channel to the module are also exposed. So, it is the duty of the Module to expose
+relevant functions that sends/receives messages.
+
+Tracker
+-------
+
+Tracker module has two submodules: one for Http and another for Udp. UDP one is not
+ready yet. So, let us talk about http. The tracker module would take care of dispatching
+to the apropriate module (udp or http) depending on the tracker server url that we
+decode from the .torrent file. The Tracker currently takes two messages: one to get the
+tracker status (tracker url could be defunct and could time out or the tracker server
+may return a genuine error response, which is captured in a bytestring). The module 
+has an 'newTracker' function, that just creates a new channel. It also has a 'runTracker'
+function that takes the above created channel and a bunch of parameters including the
+FileSystem channel (since FileSystem module is the 'owner' of the bytes read/write
+statistics). It then spawns a thread that talks to the tracker server and the rest of
+the function is a loop which is looking for and handling messages on the msg channel.
+
+Tracker messages are defined in Tracker/Types.hs
+
+data TrackerMsg = GetStatusMsg TrackerEventState
+                | GetConnectedPeersMsg (MVar [Peer])
+
+i.e. There are two messages. GetStatusMsg is to get the current state of the TrackerClient (us)
+to Tracker Server communication. TrackerEventState is also defined in Tracker/Types.hs as
+
+data TrackerEventState = None
+                       | Started
+                       | Completed
+                       | Error ByteString
+                       deriving (Show, Eq)
+
+In particular, the Error EventState signifies any possible error signalled by the
+server, based on which, the user of the Tracker module can take some action.
+
+So, once started,