Documentation ¶
Overview ¶
Package bittorrent implements all of the abstractions used to decouple the protocol of a BitTorrent tracker from the logic of handling Announces and Scrapes.
Index ¶
- Variables
- func SanitizeAnnounce(r *AnnounceRequest, maxNumWant, defaultNumWant uint32) error
- func SanitizeScrape(r *ScrapeRequest, maxScrapeInfoHashes uint32) error
- type AddressFamily
- type AnnounceRequest
- type AnnounceResponse
- type ClientError
- type ClientID
- type Event
- type IP
- type InfoHash
- type Params
- type Peer
- type PeerID
- type QueryParams
- type RouteParam
- type RouteParams
- type Scrape
- type ScrapeRequest
- type ScrapeResponse
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidIP = ClientError("invalid IP")
ErrInvalidIP indicates an invalid IP for an Announce.
var ErrInvalidInfohash = ClientError("provided invalid infohash")
ErrInvalidInfohash is returned when parsing a query encounters an infohash with invalid length.
var ErrInvalidPort = ClientError("invalid port")
ErrInvalidPort indicates an invalid Port for an Announce.
var ErrInvalidQueryEscape = ClientError("invalid query escape")
ErrInvalidQueryEscape is returned when a query string contains invalid escapes.
var ErrKeyNotFound = errors.New("query: value for the provided key does not exist")
ErrKeyNotFound is returned when a provided key has no value associated with it.
var ErrUnknownEvent = errors.New("unknown event")
ErrUnknownEvent is returned when New fails to return an event.
var RouteParamsKey = routeParamsKey{}
RouteParamsKey is a key for the context of a request that contains the named parameters from the http router.
Functions ¶
func SanitizeAnnounce ¶
func SanitizeAnnounce(r *AnnounceRequest, maxNumWant, defaultNumWant uint32) error
SanitizeAnnounce enforces a max and default NumWant and coerces the peer's IP address into the proper format.
func SanitizeScrape ¶
func SanitizeScrape(r *ScrapeRequest, maxScrapeInfoHashes uint32) error
SanitizeScrape enforces a max number of infohashes for a single scrape request.
Types ¶
type AddressFamily ¶
type AddressFamily uint8
AddressFamily is the address family of an IP address.
const ( IPv4 AddressFamily = iota IPv6 )
AddressFamily constants.
func (AddressFamily) String ¶
func (af AddressFamily) String() string
type AnnounceRequest ¶
type AnnounceRequest struct { Event Event InfoHash InfoHash Compact bool EventProvided bool NumWantProvided bool IPProvided bool NumWant uint32 Left uint64 Downloaded uint64 Uploaded uint64 Peer Params }
AnnounceRequest represents the parsed parameters from an announce request.
func (AnnounceRequest) LogFields ¶
func (r AnnounceRequest) LogFields() log.Fields
LogFields renders the current response as a set of log fields.
type AnnounceResponse ¶
type AnnounceResponse struct { Compact bool Complete uint32 Incomplete uint32 Interval time.Duration MinInterval time.Duration IPv4Peers []Peer IPv6Peers []Peer }
AnnounceResponse represents the parameters used to create an announce response.
func (AnnounceResponse) LogFields ¶
func (r AnnounceResponse) LogFields() log.Fields
LogFields renders the current response as a set of log fields.
type ClientError ¶
type ClientError string
ClientError represents an error that should be exposed to the client over the BitTorrent protocol implementation.
func (ClientError) Error ¶
func (c ClientError) Error() string
Error implements the error interface for ClientError.
type ClientID ¶
type ClientID [6]byte
ClientID represents the part of a PeerID that identifies a Peer's client software.
func NewClientID ¶
NewClientID parses a ClientID from a PeerID.
type Event ¶
type Event uint8
Event represents an event done by a BitTorrent client.
const ( // None is the event when a BitTorrent client announces due to time lapsed // since the previous announce. None Event = iota // Started is the event sent by a BitTorrent client when it joins a swarm. Started // Stopped is the event sent by a BitTorrent client when it leaves a swarm. Stopped // Completed is the event sent by a BitTorrent client when it finishes // downloading all of the required chunks. Completed )
type InfoHash ¶
type InfoHash [20]byte
InfoHash represents an infohash.
func InfoHashFromBytes ¶
InfoHashFromBytes creates an InfoHash from a byte slice.
It panics if b is not 20 bytes long.
func InfoHashFromString ¶
InfoHashFromString creates an InfoHash from a string.
It panics if s is not 20 bytes long.
type Params ¶
type Params interface { // String returns a string parsed from a query. Every key can be // returned as a string because they are encoded in the URL as strings. String(key string) (string, bool) // RawPath returns the raw path from the request URL. // The path returned can contain URL encoded data. // For a request of the form "/announce?port=1234" this would return // "/announce". RawPath() string // RawQuery returns the raw query from the request URL, excluding the // delimiter '?'. // For a request of the form "/announce?port=1234" this would return // "port=1234" RawQuery() string }
Params is used to fetch (optional) request parameters from an Announce. For HTTP Announces this includes the request path and parsed query, for UDP Announces this is the extracted path and parsed query from optional URLData as specified in BEP41.
See ParseURLData for specifics on parsing and limitations.
type Peer ¶
Peer represents the connection details of a peer that is returned in an announce response.
func (Peer) EqualEndpoint ¶
EqualEndpoint reports whether p and x have the same endpoint.
type PeerID ¶
type PeerID [20]byte
PeerID represents a peer ID.
func PeerIDFromBytes ¶
PeerIDFromBytes creates a PeerID from a byte slice.
It panics if b is not 20 bytes long.
func PeerIDFromString ¶
PeerIDFromString creates a PeerID from a string.
It panics if s is not 20 bytes long.
type QueryParams ¶
type QueryParams struct {
// contains filtered or unexported fields
}
QueryParams parses a URL Query and implements the Params interface with some additional helpers.
func ParseURLData ¶
func ParseURLData(urlData string) (*QueryParams, error)
ParseURLData parses a request URL or UDP URLData as defined in BEP41. It expects a concatenated string of the request's path and query parts as defined in RFC 3986. As both the udp: and http: scheme used by BitTorrent include an authority part the path part must always begin with a slash. An example of the expected URLData would be "/announce?port=1234&uploaded=0" or "/?auth=0x1337". HTTP servers should pass (*http.Request).RequestURI, UDP servers should pass the concatenated, unchanged URLData as defined in BEP41.
Note that, in the case of a key occurring multiple times in the query, only the last value for that key is kept. The only exception to this rule is the key "info_hash" which will attempt to parse each value as an InfoHash and return an error if parsing fails. All InfoHashes are collected and can later be retrieved by calling the InfoHashes method.
Also note that any error that is encountered during parsing is returned as a ClientError, as this method is expected to be used to parse client-provided data.
func (*QueryParams) InfoHashes ¶
func (qp *QueryParams) InfoHashes() []InfoHash
InfoHashes returns a list of requested infohashes.
func (*QueryParams) RawPath ¶
func (qp *QueryParams) RawPath() string
RawPath returns the raw path from the parsed URL.
func (*QueryParams) RawQuery ¶
func (qp *QueryParams) RawQuery() string
RawQuery returns the raw query from the parsed URL.
type RouteParam ¶
RouteParam is a type that contains the values from the named parameters on the route.
type RouteParams ¶
type RouteParams []RouteParam
RouteParams is a collection of RouteParam instances.
func (RouteParams) ByName ¶
func (rp RouteParams) ByName(name string) string
ByName returns the value of the first RouteParam that matches the given name. If no matching RouteParam is found, an empty string is returned. In the event that a "catch-all" parameter is provided on the route and no value is matched, an empty string is returned. For example: a route of "/announce/*param" matches on "/announce/". However, ByName("param") will return an empty string.
type ScrapeRequest ¶
type ScrapeRequest struct { AddressFamily AddressFamily InfoHashes []InfoHash Params Params }
ScrapeRequest represents the parsed parameters from a scrape request.
func (ScrapeRequest) LogFields ¶
func (r ScrapeRequest) LogFields() log.Fields
LogFields renders the current response as a set of log fields.
type ScrapeResponse ¶
type ScrapeResponse struct {
Files []Scrape
}
ScrapeResponse represents the parameters used to create a scrape response.
The Scrapes must be in the same order as the InfoHashes in the corresponding ScrapeRequest.
func (ScrapeResponse) LogFields ¶
func (sr ScrapeResponse) LogFields() log.Fields
LogFields renders the current response as a set of Logrus fields.