Merge pull request #369 from mrd0ll4r/storage-doc
storage: document PeerStore in more detail
This commit is contained in:
mrd0ll4r
GitHub
commit
dde5cd1586
2 changed files with 45 additions and 21 deletions
|
|
@ -14,13 +14,14 @@ var (
|
|||
drivers = make(map[string]Driver)
|
||||
)
|
||||
|
||||
// Driver is the interface used to initalize a new type of PeerStore.
|
||||
// Driver is the interface used to initialize a new type of PeerStore.
|
||||
type Driver interface {
|
||||
NewPeerStore(cfg interface{}) (PeerStore, error)
|
||||
}
|
||||
|
||||
// ErrResourceDoesNotExist is the error returned by all delete methods in the
|
||||
// store if the requested resource does not exist.
|
||||
// ErrResourceDoesNotExist is the error returned by all delete methods and the
|
||||
// AnnouncePeers method of the PeerStore interface if the requested resource
|
||||
// does not exist.
|
||||
var ErrResourceDoesNotExist = bittorrent.ClientError("resource does not exist")
|
||||
|
||||
// ErrDriverDoesNotExist is the error returned by NewPeerStore when a peer
|
||||
|
|
@ -29,39 +30,59 @@ var ErrDriverDoesNotExist = errors.New("peer store driver with that name does no
|
|||
|
||||
// PeerStore is an interface that abstracts the interactions of storing and
|
||||
// manipulating Peers such that it can be implemented for various data stores.
|
||||
//
|
||||
// Implementations of the PeerStore interface must do the following in addition
|
||||
// to implementing the methods of the interface in the way documented:
|
||||
//
|
||||
// - Implement a garbage-collection strategy that ensures stale data is removed.
|
||||
// For example, a timestamp on each InfoHash/Peer combination can be used
|
||||
// to track the last activity for that Peer. The entire database can then
|
||||
// be scanned periodically and too old Peers removed. The intervals and
|
||||
// durations involved should be configurable.
|
||||
// - IPv4 and IPv6 swarms must be isolated from each other.
|
||||
// A PeerStore must be able to transparently handle IPv4 and IPv6 Peers, but
|
||||
// must separate them. AnnouncePeers and ScrapeSwarm must return information
|
||||
// about the Swarm matching the given AddressFamily only.
|
||||
//
|
||||
// Implementations can be tested against this interface using the tests in
|
||||
// storage_tests.go and the benchmarks in storage_bench.go.
|
||||
type PeerStore interface {
|
||||
// PutSeeder adds a Seeder to the Swarm identified by the provided
|
||||
// infoHash.
|
||||
// InfoHash.
|
||||
PutSeeder(infoHash bittorrent.InfoHash, p bittorrent.Peer) error
|
||||
|
||||
// DeleteSeeder removes a Seeder from the Swarm identified by the
|
||||
// provided infoHash.
|
||||
// provided InfoHash.
|
||||
//
|
||||
// If the Swarm or Peer does not exist, this function should return
|
||||
// If the Swarm or Peer does not exist, this function returns
|
||||
// ErrResourceDoesNotExist.
|
||||
DeleteSeeder(infoHash bittorrent.InfoHash, p bittorrent.Peer) error
|
||||
|
||||
// PutLeecher adds a Leecher to the Swarm identified by the provided
|
||||
// infoHash.
|
||||
// InfoHash.
|
||||
// If the Swarm does not exist already, it is created.
|
||||
PutLeecher(infoHash bittorrent.InfoHash, p bittorrent.Peer) error
|
||||
|
||||
// DeleteLeecher removes a Leecher from the Swarm identified by the
|
||||
// provided infoHash.
|
||||
// provided InfoHash.
|
||||
//
|
||||
// If the Swarm or Peer does not exist, this function should return
|
||||
// If the Swarm or Peer does not exist, this function returns
|
||||
// ErrResourceDoesNotExist.
|
||||
DeleteLeecher(infoHash bittorrent.InfoHash, p bittorrent.Peer) error
|
||||
|
||||
// GraduateLeecher promotes a Leecher to a Seeder in the Swarm
|
||||
// identified by the provided infoHash.
|
||||
// identified by the provided InfoHash.
|
||||
//
|
||||
// If the given Peer is not present as a Leecher, add the Peer as a
|
||||
// Seeder and return no error.
|
||||
// If the given Peer is not present as a Leecher or the swarm does not exist
|
||||
// already, the Peer is added as a Seeder and no error is returned.
|
||||
GraduateLeecher(infoHash bittorrent.InfoHash, p bittorrent.Peer) error
|
||||
|
||||
// AnnouncePeers is a best effort attempt to return Peers from the Swarm
|
||||
// identified by the provided infoHash. The returned Peers are required
|
||||
// to be either all IPv4 or all IPv6.
|
||||
// identified by the provided InfoHash.
|
||||
// The numWant parameter indicates the number of peers requested by the
|
||||
// announcing Peer p. The seeder flag determines whether the Peer announced
|
||||
// as a Seeder.
|
||||
// The returned Peers are required to be either all IPv4 or all IPv6.
|
||||
//
|
||||
// The returned Peers should strive be:
|
||||
// - as close to length equal to numWant as possible without going over
|
||||
|
|
@ -70,17 +91,17 @@ type PeerStore interface {
|
|||
// - if seeder is false, should ideally return more seeders than
|
||||
// leechers
|
||||
//
|
||||
// Returns ErrResourceDoesNotExist if the provided infoHash is not tracked.
|
||||
// Returns ErrResourceDoesNotExist if the provided InfoHash is not tracked.
|
||||
AnnouncePeers(infoHash bittorrent.InfoHash, seeder bool, numWant int, p bittorrent.Peer) (peers []bittorrent.Peer, err error)
|
||||
|
||||
// ScrapeSwarm returns information required to answer a scrape request
|
||||
// about a swarm identified by the given infohash.
|
||||
// ScrapeSwarm returns information required to answer a Scrape request
|
||||
// about a Swarm identified by the given InfoHash.
|
||||
// The AddressFamily indicates whether or not the IPv6 swarm should be
|
||||
// scraped.
|
||||
// The Complete and Incomplete fields of the Scrape must be filled,
|
||||
// filling the Snatches field is optional.
|
||||
// If the infohash is unknown to the PeerStore, an empty Scrape is
|
||||
// returned.
|
||||
//
|
||||
// If the Swarm does not exist, an empty Scrape and no error is returned.
|
||||
ScrapeSwarm(infoHash bittorrent.InfoHash, addressFamily bittorrent.AddressFamily) bittorrent.Scrape
|
||||
|
||||
// stop.Stopper is an interface that expects a Stop method to stop the
|
||||
|
|
@ -89,7 +110,7 @@ type PeerStore interface {
|
|||
stop.Stopper
|
||||
|
||||
// log.Fielder returns a loggable version of the data used to configure and
|
||||
// operate a particular peer store.
|
||||
// operate a particular PeerStore.
|
||||
log.Fielder
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -9,7 +9,10 @@ import (
|
|||
"github.com/chihaya/chihaya/bittorrent"
|
||||
)
|
||||
|
||||
// PeerEqualityFunc is the boolean function to use to check two Peers for equality.
|
||||
// PeerEqualityFunc is the boolean function to use to check two Peers for
|
||||
// equality.
|
||||
// Depending on the implementation of the PeerStore, this can be changed to
|
||||
// use (Peer).EqualEndpoint instead.
|
||||
var PeerEqualityFunc = func(p1, p2 bittorrent.Peer) bool { return p1.Equal(p2) }
|
||||
|
||||
// TestPeerStore tests a PeerStore implementation against the interface.
|
||||
|
|
|
|||
Loading…
Reference in a new issue