From 5bd3b3efb387fe2c8134854c764465b6bea8c5a2 Mon Sep 17 00:00:00 2001 From: Jimmy Zelinskie Date: Fri, 18 Jul 2014 19:09:06 -0400 Subject: [PATCH] update docs all around --- backend/noop/driver.go | 1 + chihaya.go | 2 ++ http/writer.go | 4 ++++ tracker/announce.go | 15 +++++++++++++-- tracker/models/models.go | 5 ++--- tracker/scrape.go | 2 ++ 6 files changed, 24 insertions(+), 5 deletions(-) diff --git a/backend/noop/driver.go b/backend/noop/driver.go index 8fba995..93fd3dc 100644 --- a/backend/noop/driver.go +++ b/backend/noop/driver.go @@ -51,6 +51,7 @@ func (n *NoOp) LoadAllUsers(ids []uint64) ([]*models.User, error) { return nil, nil } +// Init registers the noop driver as a backend for Chihaya. func init() { backend.Register("noop", &driver{}) } diff --git a/chihaya.go b/chihaya.go index 30ab48a..e697626 100644 --- a/chihaya.go +++ b/chihaya.go @@ -33,6 +33,8 @@ func init() { flag.StringVar(&configPath, "config", "", "path to the configuration file") } +// Boot starts Chihaya. By exporting this function, anyone can import their own +// custom drivers into their own package main and then call chihaya.Boot. func Boot() { defer glog.Flush() diff --git a/http/writer.go b/http/writer.go index f6e6516..e29aec6 100644 --- a/http/writer.go +++ b/http/writer.go @@ -12,10 +12,12 @@ import ( "github.com/chihaya/chihaya/tracker/models" ) +// Writer implements the tracker.Writer interface for the HTTP protocol. type Writer struct { http.ResponseWriter } +// WriteError writes a bencode dict with a failure reason. func (w *Writer) WriteError(err error) error { bencoder := bencode.NewEncoder(w) @@ -24,6 +26,7 @@ func (w *Writer) WriteError(err error) error { }) } +// WriteAnnounce writes a bencode dict representation of an AnnounceResponse. func (w *Writer) WriteAnnounce(res *models.AnnounceResponse) error { dict := bencode.Dict{ "complete": res.Complete, @@ -45,6 +48,7 @@ func (w *Writer) WriteAnnounce(res *models.AnnounceResponse) error { return bencoder.Encode(dict) } +// WriteScrape writes a bencode dict representation of a ScrapeResponse. func (w *Writer) WriteScrape(res *models.ScrapeResponse) error { dict := bencode.Dict{ "files": filesDict(res.Files), diff --git a/tracker/announce.go b/tracker/announce.go index e27ee4f..8ef3dbf 100644 --- a/tracker/announce.go +++ b/tracker/announce.go @@ -10,6 +10,8 @@ import ( "github.com/chihaya/chihaya/tracker/models" ) +// HandleAnnounce encapsulates all of the logic of handling a BitTorrent +// client's Announce without being coupled to any transport protocol. func (t *Tracker) HandleAnnounce(ann *models.Announce, w Writer) error { conn, err := t.Pool.Get() if err != nil { @@ -62,7 +64,7 @@ func (t *Tracker) HandleAnnounce(ann *models.Announce, w Writer) error { peer := models.NewPeer(ann, user, torrent) - created, err := updateTorrent(conn, ann, peer, torrent) + created, err := updateSwarm(conn, ann, peer, torrent) if err != nil { return err } @@ -87,7 +89,8 @@ func (t *Tracker) HandleAnnounce(ann *models.Announce, w Writer) error { return w.WriteAnnounce(newAnnounceResponse(ann, peer, torrent)) } -func updateTorrent(c Conn, ann *models.Announce, p *models.Peer, t *models.Torrent) (created bool, err error) { +// updateSwarm handles the changes to a torrent's swarm given an announce. +func updateSwarm(c Conn, ann *models.Announce, p *models.Peer, t *models.Torrent) (created bool, err error) { c.TouchTorrent(t.Infohash) switch { @@ -125,6 +128,8 @@ func updateTorrent(c Conn, ann *models.Announce, p *models.Peer, t *models.Torre return } +// handleEvent checks to see whether an announce has an event and if it does, +// properly handles that event. func handleEvent(c Conn, ann *models.Announce, p *models.Peer, u *models.User, t *models.Torrent) (snatched bool, err error) { switch { case ann.Event == "stopped" || ann.Event == "paused": @@ -187,6 +192,8 @@ func newAnnounceResponse(ann *models.Announce, announcer *models.Peer, t *models return res } +// getPeers returns lists IPv4 and IPv6 peers on a given torrent sized according +// to the wanted parameter. func getPeers(ann *models.Announce, announcer *models.Peer, t *models.Torrent, wanted int) (ipv4s, ipv6s models.PeerList) { ipv4s, ipv6s = models.PeerList{}, models.PeerList{} @@ -200,6 +207,7 @@ func getPeers(ann *models.Announce, announcer *models.Peer, t *models.Torrent, w return appendPeers(ipv4s, ipv6s, ann, announcer, t.Leechers, wanted-len(ipv4s)-len(ipv6s)) } +// appendPeers implements the logic of adding peers to the IPv4 or IPv6 lists. func appendPeers(ipv4s, ipv6s models.PeerList, ann *models.Announce, announcer *models.Peer, peers models.PeerMap, wanted int) (models.PeerList, models.PeerList) { if ann.Config.PreferredSubnet { return appendSubnetPeers(ipv4s, ipv6s, ann, announcer, peers, wanted) @@ -228,6 +236,8 @@ func appendPeers(ipv4s, ipv6s models.PeerList, ann *models.Announce, announcer * return ipv4s, ipv6s } +// appendSubnetPeers is an alternative version of appendPeers used when the +// config variable PreferredSubnet is enabled. func appendSubnetPeers(ipv4s, ipv6s models.PeerList, ann *models.Announce, announcer *models.Peer, peers models.PeerMap, wanted int) (models.PeerList, models.PeerList) { var subnet net.IPNet @@ -264,6 +274,7 @@ func appendSubnetPeers(ipv4s, ipv6s models.PeerList, ann *models.Announce, annou return ipv4s, ipv6s } +// peersEquivalent checks if two peers are one in the same. func peersEquivalent(a, b *models.Peer) bool { return a.ID == b.ID || a.UserID != 0 && a.UserID == b.UserID } diff --git a/tracker/models/models.go b/tracker/models/models.go index 594cba4..6e89c47 100644 --- a/tracker/models/models.go +++ b/tracker/models/models.go @@ -14,7 +14,7 @@ import ( ) var ( - // ErrMalformedRequest is returned when an http.Request does not have the + // ErrMalformedRequest is returned when a client request does not have the // required parameters to create a model. ErrMalformedRequest = errors.New("malformed request") ) @@ -69,8 +69,7 @@ func NewPeer(a *Announce, u *User, t *Torrent) *Peer { } } -// Key returns the unique key used to look-up a peer in a swarm (i.e -// Torrent.Seeders & Torrent.Leechers). +// Key returns the unique key used to look-up a peer in a PeerMap. func (p Peer) Key() string { return p.ID + ":" + strconv.FormatUint(p.UserID, 36) } diff --git a/tracker/scrape.go b/tracker/scrape.go index 2ca1c91..6585cc2 100644 --- a/tracker/scrape.go +++ b/tracker/scrape.go @@ -8,6 +8,8 @@ import ( "github.com/chihaya/chihaya/tracker/models" ) +// HandleScrape encapsulates all the logic of handling a BitTorrent client's +// scrape without being coupled to any transport protocol. func (t *Tracker) HandleScrape(scrape *models.Scrape, w Writer) error { conn, err := t.Pool.Get() if err != nil {