diff --git a/README.md b/README.md index 2c5bf6e..6441be3 100644 --- a/README.md +++ b/README.md @@ -1,46 +1,36 @@ # Chihaya [![Build Status](https://travis-ci.org/pushrax/chihaya.png?branch=master)](https://travis-ci.org/pushrax/chihaya) Chihaya is a high-performance [BitTorrent tracker](http://en.wikipedia.org/wiki/BitTorrent_tracker) -written in the Go programming language. It is still heavily under development and the current `master` branch -should not be used in production. +written in the Go programming language. It is still heavily under development and should not be used +in production. Some of the planned features include. -Planned features include: - -- Light resource consumption -- Fast request processing, sparing the network from exorbitant connection counts +- Low resource consumption +- *Fast* request processing - Maximum compatibility with what exists of the BitTorrent spec - Correct IPv6 support -- Generic storage interfaces that are easily adapted to work with any existing web application +- A generic storage interfaces that is easily adapted to use any data store and web application - Scaling properties that directly correlate with those of the chosen data stores -### Technical Details +## Architecture -See [the wiki](https://github.com/pushrax/chihaya/wiki) for a discussion of the design behind Chihaya. +You are most likely looking to integrate Chihaya with a web application for organizing torrents +and managing a community. Chihaya was designed with this in mind, but also tries to remain +independent. Chihaya connects to two data stores. The first, known as "cache", is used between +Chihaya processes in order to keep up with fast changing data. The second, known as "storage", +is your web application's data store. Changes immediately take place in the cache, which is why +fast data stores are recommended. These changes are also collected and periodically applied to the +storage in order to avoid locking up your web application's data store. -## Using Chihaya -Chihaya is intended to work with existing torrent indexing web frameworks, such as [batter] and [Gazelle]. -Following the Unix way, it is built to perform a specific task, and interface with any system that -needs its functionality. See [below](#drivers) for more info. +## Installing -[batter]: https://github.com/wafflesfm/batter -[gazelle]: https://github.com/whatcd/gazelle - -### Installing - -Make sure you have your `$GOROOT` and `$GOPATH` set up correctly, and have your `$GOBIN` in your `$PATH`. +Make sure you have your $GOROOT and $GOPATH set up correctly and have your $GOBIN on your $PATH. ```sh -$ go get github.com/pushrax/chihaya +$ go install github.com/pushrax/chihaya ``` -### Configuring - -Configuration is done in a JSON formatted file specified with the `-config` -flag. An example configuration file can be found -[here](https://github.com/pushrax/chihaya/blob/master/config/example.json). - -### Running the tests +## Testing ```sh $ export TESTCONFIGPATH=$GOPATH/src/chihaya/config/example.json @@ -48,34 +38,64 @@ $ go get github.com/pushrax/chihaya $ go test -v ./... ``` -## Drivers +## Configuring -Chihaya is designed to remain agnostic about the choice of data store for an -application, and it is straightforward to [implement a new driver]. However, there -are a number of directly supported drivers: +Configuration is done in a JSON formatted file specified with the `-config` +flag. An example configuration can be seen in the `exampleConfig` variable of +[`config/config_test.go`](https://github.com/pushrax/chihaya/blob/master/config/config_test.go). -Cache: +## Default drivers -* [redis](http://redis.io) — allows for multiple tracker instances to run at the same time for the same swarm -* memory — only a single instance can run, but it requires no extra setup +### Cache -Storage: +Chihaya currently supports drivers for the following caches out of the box: + +* [redis](http://redis.io) + +### Storage + +Chihaya currently supports drivers for the following storages out of the box: * [batter-postgres](https://github.com/wafflesfm/batter) -* [gazelle-mysql](https://github.com/whatcd/gazelle) -[implement a new driver]: https://github.com/pushrax/chihaya/wiki/Implementing-a-driver +## Custom drivers +Please read the documentation and understand these interfaces as there are +assumptions made about thread-safety. After you've implemented a new driver, +all you have to do is remember to add `import _ path/to/your/package` to the +top of `main.go` and the side effects from `init()` will globally register +your driver so that config package will recognize your driver by name. +If you're writing a driver for a popular data store, consider contributing it. + +### Cache + +The [`cache`] package is heavily inspired by the standard library's +[`database/sql`] package. To write a new cache backend, create a new Go +package that has an implementation of the [`Pool`], [`Tx`], and [`Driver`] +interfaces. Within that package, you must also define an [`init()`] that calls +[`cache.Register`]. + +[`cache`]: http://godoc.org/github.com/pushrax/chihaya/cache +[`database/sql`]: http://godoc.org/database/sql +[`Pool`]: http://godoc.org/github.com/pushrax/chihaya/cache#Pool +[`Tx`]: http://godoc.org/github.com/pushrax/chihaya/cache#Tx +[`Driver`]: http://godoc.org/github.com/pushrax/chihaya/cache#Driver +[`init()`]: http://golang.org/ref/spec#Program_execution +[`cache.Register`]: http://godoc.org/github.com/pushrax/chihaya/cache#Register + +### Storage + +TODO ## Contributing -If you're interested in contributing, please contact us via IRC in **[#chihaya] on -[freenode]** or post to the GitHub issue tracker. Please don't write -massive patches with no prior communication, as it will most +If you're interested in contributing, please contact us in **[#chihaya] on +[freenode IRC]** or post to the GitHub issue tracker. Please don't offer +massive pull requests with no prior communication attempts as it will most likely lead to confusion and time wasted for everyone. However, small -unannounced fixes are always welcome! +unannounced fixes are always welcome. [#chihaya]: http://webchat.freenode.net?channels=chihaya -[freenode]: http://freenode.net +[freenode IRC]: http://freenode.net And remember: good gophers always use gofmt!