bittorrent

package
v1.0.1-0...-2f79440 Latest Latest
Warning

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

 Go to latest Published: Jun 15, 2023 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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.