README
¶
Chihaya
Note: The master branch may be in an unstable or even broken state during development. Please use releases instead of the master branch in order to get stable binaries.
Chihaya is an open source BitTorrent tracker written in Go.
Differentiating features include:
- Protocol-agnostic middleware
- HTTP and UDP frontends
- IPv4 and IPv6 support
- YAML configuration
- Metrics via Prometheus
Why Chihaya?
Chihaya is built for developers looking to integrate BitTorrent into a preexisting production environment. Chihaya's pluggable architecture and middleware framework offers a simple and flexible integration point that abstracts the BitTorrent tracker protocols. The most common use case for Chihaya is integration with the deployment of cloud software.
Production Use
Facebook uses BitTorrent to deploy new versions of their software. In order to optimize the flow of traffic within their datacenters, Chihaya is configured to prefer peers within the same subnet. Because Facebook organizes their network such that server racks are allocated IP addresses in the same subnet, the vast majority of deployment traffic never impacts the congested areas of their network.
CoreOS
Quay is a container registry that offers the ability to download containers via BitTorrent in order to speed up large or geographically distant deployments. Announce URLs from Quay's torrent files contain a JWT in order to allow Chihaya to verify that an infohash was approved by the registry. By verifying the infohash, Quay can be sure that only their content is being shared by their tracker.
Development
Getting Started
Building from HEAD
In order to compile the project, the latest stable version of Go and knowledge of a working Go environment are required.
$ mkdir chihaya
$ export GOPATH=$PWD/chihaya
$ go get -t -u github.com/chihaya/chihaya/...
$ $GOPATH/bin/chihaya --help
Reproducible Builds
Reproducible builds are handled by using glide to vendor dependencies.
$ cd $GOPATH/src/github.com/chihaya/chihaya
$ glide install
$ go install github.com/chihaya/chihaya/...
$ $GOPATH/bin/chihaya --help
Docker
Docker containers are available for HEAD and stable releases.
Testing
The following will run all tests and benchmarks.
Removing -bench will just run unit tests.
$ go test -bench $(glide novendor | grep -v contrib)
Contributing
Long-term discussion and bug reports are maintained via GitHub Issues. Code review is done via GitHub Pull Requests. Real-time discussion is done via freenode IRC.
For more information read CONTRIBUTING.md.
Architecture
+----------------------+
| BitTorrent Client |<--------------+
+----------------------+ |
| |
| |
| |
+------------v--------------------------+-------------------+-------------------------+
|+----------------------+ +----------------------+frontend| chihaya|
|| Parser | | Writer | | |
|+----------------------+ +----------------------+ | |
| | ^ | |
+------------+--------------------------+-------------------+ |
+------------v--------------------------+-------------------+ |
|+----------------------+ +----------------------+ logic| |
|| PreHook Middleware |-->| Response Generator |<-------|-------------+ |
|+----------------------+ +----------------------+ | | |
| | | |
|+----------------------+ | +----------------------+|
|| PostHook Middleware |-----------------------------------|>| Storage ||
|+----------------------+ | +----------------------+|
| | |
+-----------------------------------------------------------+-------------------------+
BitTorrent clients send Announce and Scrape requests to a Frontend. Frontends parse requests and write responses for the particular protocol they implement. The TrackerLogic interface to is used to generate responses for their requests and optionally perform a task after responding to a client. A configurable chain of PreHook and PostHook middleware is used to construct an instance of TrackerLogic. PreHooks are middleware that are executed before the response has been written. After all PreHooks have executed, any missing response fields that are required are filled by reading out of the configured implementation of the Storage interface. PostHooks are asynchronous tasks that occur after a response has been delivered to the client. Request data is written to the storage asynchronously in one of these PostHooks.
Related projects
- BitTorrent.org: a static website containing the BitTorrent spec and all BEPs
- OpenTracker: a popular BitTorrent tracker written in C
- Ocelot: a private BitTorrent tracker written in C++
Directories
¶
| Path | Synopsis |
|---|---|
|
Package bittorrent implements all of the abstractions used to decouple the protocol of a BitTorrent tracker from the logic of handling Announces and Scrapes.
|
Package bittorrent implements all of the abstractions used to decouple the protocol of a BitTorrent tracker from the logic of handling Announces and Scrapes. |
|
cmd
|
|
|
http
Package http implements a BitTorrent frontend via the HTTP protocol as described in BEP 3 and BEP 23.
|
Package http implements a BitTorrent frontend via the HTTP protocol as described in BEP 3 and BEP 23. |
|
http/bencode
Package bencode implements bencoding of data as defined in BEP 3 using type assertion over reflection for performance.
|
Package bencode implements bencoding of data as defined in BEP 3 using type assertion over reflection for performance. |
|
udp
Package udp implements a BitTorrent tracker via the UDP protocol as described in BEP 15.
|
Package udp implements a BitTorrent tracker via the UDP protocol as described in BEP 15. |
|
Package middleware implements the TrackerLogic interface by executing a series of middleware hooks.
|
Package middleware implements the TrackerLogic interface by executing a series of middleware hooks. |
|
clientapproval
Package clientapproval implements a Hook that fails an Announce based on a whitelist or blacklist of BitTorrent client IDs.
|
Package clientapproval implements a Hook that fails an Announce based on a whitelist or blacklist of BitTorrent client IDs. |
|
jwt
Package jwt implements a Hook that fails an Announce if the client's request is missing a valid JSON Web Token.
|
Package jwt implements a Hook that fails an Announce if the client's request is missing a valid JSON Web Token. |
|
pkg
|
|
|
prand
Package prand allows parallel access to randomness based on indices or infohashes.
|
Package prand allows parallel access to randomness based on indices or infohashes. |
|
prometheus
Package prometheus implements a standalone HTTP server for serving a Prometheus metrics endpoint.
|
Package prometheus implements a standalone HTTP server for serving a Prometheus metrics endpoint. |
|
stop
Package stop implements a pattern for shutting down a group of processes.
|
Package stop implements a pattern for shutting down a group of processes. |
|
memory
Package memory implements the storage interface for a Chihaya BitTorrent tracker keeping peer data in memory.
|
Package memory implements the storage interface for a Chihaya BitTorrent tracker keeping peer data in memory. |
|
memorybysubnet
Package memorybysubnet implements the storage interface for a Chihaya BitTorrent tracker keeping peer data in memory organized by a pre-configured subnet mask.
|
Package memorybysubnet implements the storage interface for a Chihaya BitTorrent tracker keeping peer data in memory organized by a pre-configured subnet mask. |