doc/design.md

   1 2016-03-10:
   2
   3 A rough sketch of the design of the program.
   4
   5 In the Unix tradition, FuncTorrent takes either a .torrent file as input or one
   6 can `cat' the .torrent file and pipe the output into the program:
   7
   8 $ cat foo.torrent | ./functorrent
   9
  10 As of 10/Mar/2016, FuncTorrent supports only HTTP tracker.
  11
  12 Each module starts up as a thread, so we have FileSystem thread, we have a Tracker
  13 Client thread. We have a main client thread, that receives pieces. We also have a
  14 Server thread that serves pieces.
  15
  16 The messages themselves are not exposed outside the module. Instead, a function that
  17 create a message passing channel is exposed and also helper functions that talk via
  18 the channel to the module are also exposed. So, it is the duty of the Module to expose
  19 relevant functions that sends/receives messages.
  20
  21 Tracker
  22 -------
  23
  24 Tracker module has two submodules: one for Http and another for Udp. UDP one is not
  25 ready yet. So, let us talk about http. The tracker module would take care of dispatching
  26 to the apropriate module (udp or http) depending on the tracker server url that we
  27 decode from the .torrent file. The Tracker currently takes two messages: one to get the
  28 tracker status (tracker url could be defunct and could time out or the tracker server
  29 may return a genuine error response, which is captured in a bytestring). The module
  30 has an 'newTracker' function, that just creates a new channel. It also has a 'runTracker'
  31 function that takes the above created channel and a bunch of parameters including the
  32 FileSystem channel (since FileSystem module is the 'owner' of the bytes read/write
  33 statistics). It then spawns a thread that talks to the tracker server and the rest of
  34 the function is a loop which is looking for and handling messages on the msg channel.
  35
  36 Tracker messages are defined in Tracker/Types.hs
  37
  38 data TrackerMsg = GetStatusMsg TrackerEventState
  39                 | GetConnectedPeersMsg (MVar [Peer])
  40
  41 i.e. There are two messages. GetStatusMsg is to get the current state of the TrackerClient (us)
  42 to Tracker Server communication. TrackerEventState is also defined in Tracker/Types.hs as
  43
  44 data TrackerEventState = None
  45                        | Started
  46                        | Completed
  47                        | Error ByteString
  48                        deriving (Show, Eq)
  49
  50 In particular, the Error EventState signifies any possible error signalled by the
  51 server, based on which, the user of the Tracker module can take some action.
  52
  53 So, once started,