bittorrent

package
Version: v1.0.1-0...-7455c2a Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 19, 2022 License: BSD-2-Clause Imports: 8 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
var ErrInvalidIP = ClientError("invalid IP")

ErrInvalidIP indicates an invalid IP for an Announce.

View Source
var ErrInvalidInfohash = ClientError("provided invalid infohash")

ErrInvalidInfohash is returned when parsing a query encounters an infohash with invalid length.

View Source
var ErrInvalidPort = ClientError("invalid port")

ErrInvalidPort indicates an invalid Port for an Announce.

View Source
var ErrInvalidQueryEscape = ClientError("invalid query escape")

ErrInvalidQueryEscape is returned when a query string contains invalid escapes.

View Source
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.

View Source
var ErrUnknownEvent = errors.New("unknown event")

ErrUnknownEvent is returned when New fails to return an event.

View Source
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

func NewClientID(pid PeerID) ClientID

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
)

func NewEvent

func NewEvent(eventStr string) (Event, error)

NewEvent returns the proper Event given a string.

func (Event) String

func (e Event) String() string

String implements Stringer for an event.

type IP

type IP struct {
	net.IP
	AddressFamily
}

IP is a net.IP with an AddressFamily.

func (IP) String

func (ip IP) String() string

type InfoHash

type InfoHash [20]byte

InfoHash represents an infohash.

func InfoHashFromBytes

func InfoHashFromBytes(b []byte) InfoHash

InfoHashFromBytes creates an InfoHash from a byte slice.

It panics if b is not 20 bytes long.

func InfoHashFromString

func InfoHashFromString(s string) InfoHash

InfoHashFromString creates an InfoHash from a string.

It panics if s is not 20 bytes long.

func (InfoHash) RawString

func (i InfoHash) RawString() string

RawString returns a 20-byte string of the raw bytes of the InfoHash.

func (InfoHash) String

func (i InfoHash) String() string

String implements fmt.Stringer, returning the base16 encoded InfoHash.

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

type Peer struct {
	ID   PeerID
	IP   IP
	Port uint16
}

Peer represents the connection details of a peer that is returned in an announce response.

func (Peer) Equal

func (p Peer) Equal(x Peer) bool

Equal reports whether p and x are the same.

func (Peer) EqualEndpoint

func (p Peer) EqualEndpoint(x Peer) bool

EqualEndpoint reports whether p and x have the same endpoint.

func (Peer) LogFields

func (p Peer) LogFields() log.Fields

LogFields renders the current peer as a set of Logrus fields.

func (Peer) String

func (p Peer) String() string

String implements fmt.Stringer to return a human-readable representation. The string will have the format <PeerID>@[<IP>]:<port>, for example "0102030405060708090a0b0c0d0e0f1011121314@[10.11.12.13]:1234"

type PeerID

type PeerID [20]byte

PeerID represents a peer ID.

func PeerIDFromBytes

func PeerIDFromBytes(b []byte) PeerID

PeerIDFromBytes creates a PeerID from a byte slice.

It panics if b is not 20 bytes long.

func PeerIDFromString

func PeerIDFromString(s string) PeerID

PeerIDFromString creates a PeerID from a string.

It panics if s is not 20 bytes long.

func (PeerID) RawString

func (p PeerID) RawString() string

RawString returns a 20-byte string of the raw bytes of the ID.

func (PeerID) String

func (p PeerID) String() string

String implements fmt.Stringer, returning the base16 encoded PeerID.

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.

func (*QueryParams) String

func (qp *QueryParams) String(key string) (string, bool)

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.

func (*QueryParams) Uint

func (qp *QueryParams) Uint(key string, bitSize int) (uint64, error)

Uint returns a uint parsed from a query. After being called, it is safe to cast the uint64 to your desired length.

type RouteParam

type RouteParam struct {
	Key   string
	Value string
}

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 Scrape

type Scrape struct {
	InfoHash   InfoHash
	Snatches   uint32
	Complete   uint32
	Incomplete uint32
}

Scrape represents the state of a swarm that is returned in a scrape response.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL