From 1ace87c9356f17799a5f331b9e813be502b68e02 Mon Sep 17 00:00:00 2001 From: Sam Truzjan Date: Tue, 26 Nov 2013 05:09:35 +0400 Subject: refine documentation --- src/Network/BitTorrent/Tracker/Message.hs | 57 ++++++++++++++++++------------- 1 file changed, 34 insertions(+), 23 deletions(-) (limited to 'src') diff --git a/src/Network/BitTorrent/Tracker/Message.hs b/src/Network/BitTorrent/Tracker/Message.hs index 22733a51..e49a9e58 100644 --- a/src/Network/BitTorrent/Tracker/Message.hs +++ b/src/Network/BitTorrent/Tracker/Message.hs @@ -6,7 +6,7 @@ -- Portability : portable -- -- Every tracker should support announce query. This query is used --- to discover peers within swarm and have two-fold effect: +-- to discover peers within a swarm and have two-fold effect: -- -- * peer doing announce discover other peers using peer list from -- the response to the announce query. @@ -14,8 +14,8 @@ -- * tracker store peer information and use it in the succeeding -- requests made by other peers, until the peer info expires. -- --- By convention most trackers support another form of request -- --- scrape query -- which queries the state of a given torrent (or +-- By convention most trackers support another form of request — +-- scrape query — which queries the state of a given torrent (or -- a list of torrents) that the tracker is managing. -- {-# LANGUAGE FlexibleInstances #-} @@ -77,7 +77,7 @@ import Network.BitTorrent.Core.PeerAddr -- Events -----------------------------------------------------------------------} --- | Events used to specify which kind of tracker request is performed. +-- | Events used to specify which kind of announce query is performed. data Event = Started -- ^ For the first request: when a peer join the swarm. | Stopped @@ -127,32 +127,34 @@ getEvent = do -- the torrent. The most important, requests are used by the tracker -- to keep track lists of active peer for a particular torrent. -- -data AnnounceQuery = AnnounceQuery { - reqInfoHash :: !InfoHash - -- ^ Hash of info part of the torrent usually obtained from +data AnnounceQuery = AnnounceQuery + { + -- | Hash of info part of the torrent usually obtained from -- 'Torrent'. + reqInfoHash :: !InfoHash + -- | ID of the peer doing request. , reqPeerId :: !PeerId - -- ^ ID of the peer doing request. + -- | Port to listen to for connections from other + -- peers. Tracker should respond with this port when + -- some /other/ peer request the tracker with the same info hash. + -- Normally, this port is choosed from 'defaultPorts'. , reqPort :: !PortNumber - -- ^ Port to listen to for connections from other - -- peers. Normally, tracker should respond with this port when - -- some peer request the tracker with the same info hash. + -- | Current progress of peer doing request. , reqProgress :: !Progress - -- ^ Current progress of peer doing request. - , reqIP :: Maybe HostAddress - -- ^ The peer IP. Needed only when client communicated with + -- | The peer IP. Needed only when client communicated with -- tracker throught a proxy. + , reqIP :: Maybe HostAddress - , reqNumWant :: Maybe Int - -- ^ Number of peers that the peers wants to receive from. See + -- | Number of peers that the peers wants to receive from. See -- note for 'defaultNumWant'. + , reqNumWant :: Maybe Int + -- | If not specified, the request is regular periodic request. , reqEvent :: Maybe Event - -- ^ If not specified, the request is regular periodic request. } deriving (Show, Typeable) $(deriveJSON (L.map toLower . L.dropWhile isLower) ''AnnounceQuery) @@ -208,11 +210,12 @@ instance Serialize AnnounceQuery where , reqPort = port , reqProgress = progress , reqIP = if ip == 0 then Nothing else Just ip - , reqNumWant = if want == -1 then Nothing else Just (fromIntegral want) + , reqNumWant = if want == -1 then Nothing + else Just (fromIntegral want) , reqEvent = ev } --- | Encoding announce query and add it to the base tracker URL. +-- | Encode announce query and add it to the base tracker URL. renderAnnounceQuery :: URI -> AnnounceQuery -> URI renderAnnounceQuery announceURI req = URL.urlEncode req @@ -230,7 +233,7 @@ data QueryParam deriving (Show, Eq, Ord, Enum) data ParamParseFailure - = Missing QueryParam -- ^ param not found in query string + = Missing QueryParam -- ^ param not found in query string; | Invalid QueryParam -- ^ param present but not valid. type ParamResult = Either ParamParseFailure @@ -255,7 +258,7 @@ paramName ParamInfoHash = "info_hash" paramName ParamPeerId = "peer_id" paramName ParamPort = "port" --- | Parse announce request from a query string. +-- | Parse announce request from a decoded query string. parseAnnounceQuery :: [(Text, Text)] -> Either ParamParseFailure AnnounceQuery parseAnnounceQuery params = AnnounceQuery <$> reqParam ParamInfoHash textToInfoHash params @@ -280,11 +283,17 @@ parseAnnounceQuery params = AnnounceQuery numwant = undefined event = undefined +-- TODO add extension datatype + {----------------------------------------------------------------------- -- Announce response -----------------------------------------------------------------------} --- | For more info see: +-- | Tracker can return peer list in either compact(BEP23) or not +-- compact form. +-- +-- For more info see: +-- data PeerList = PeerList { getPeerList :: [PeerAddr] } | CompactPeerList { getPeerList :: [PeerAddr] } @@ -408,10 +417,12 @@ missingOffset = 101 invalidOffset :: Int invalidOffset = 150 --- | Get +-- | Get HTTP response error code from a announce params parse +-- failure. -- -- For more info see: -- +-- paramFailureCode :: ParamParseFailure -> Int paramFailureCode (Missing param) = missingOffset + fromEnum param paramFailureCode (Invalid param) = invalidOffset + fromEnum param -- cgit v1.2.3