From 5f3c57cb92332181b314e5ebe460f45c806adf53 Mon Sep 17 00:00:00 2001 From: Justin Li Date: Thu, 29 Aug 2013 21:26:27 -0400 Subject: [PATCH 1/3] Move some content to the wiki --- README.md | 77 +++++++++++++++++-------------------------------------- 1 file changed, 23 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index 6441be3..f021252 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,26 @@ # 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 should not be used -in production. Some of the planned features include. +written in the Go programming language. It is still heavily under development and the current `master` branch +should not be used in production. Planned features include: -- Low resource consumption -- *Fast* request processing +- Light resource consumption +- Fast request processing, sparing the network from exorbitant connection counts - Maximum compatibility with what exists of the BitTorrent spec - Correct IPv6 support -- A generic storage interfaces that is easily adapted to use any data store and web application +- Generic storage interfaces that are easily adapted to work with any existing web application - Scaling properties that directly correlate with those of the chosen data stores -## Architecture - -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. +## Technical Details +See [the wiki](https://github.com/pushrax/chihaya/wiki) for a discussion of the design behind Chihaya. ## Installing Make sure you have your $GOROOT and $GOPATH set up correctly and have your $GOBIN on your $PATH. ```sh -$ go install github.com/pushrax/chihaya +$ go get github.com/pushrax/chihaya ``` ## Testing @@ -41,61 +34,37 @@ $ go test -v ./... ## Configuring 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). +flag. An example configuration file can be found +[here](https://github.com/pushrax/chihaya/blob/master/config/example.json). ## Default drivers -### Cache +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: -Chihaya currently supports drivers for the following caches out of the box: +Cache: * [redis](http://redis.io) +* Memory -### Storage - -Chihaya currently supports drivers for the following storages out of the box: +Storage: * [batter-postgres](https://github.com/wafflesfm/batter) +* [gazelle-mysql](https://github.com/whatcd/gazelle) -## Custom drivers +[implement a new driver]: https://github.com/pushrax/chihaya/wiki/Implementing-a-driver -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 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 +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 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 IRC]: http://freenode.net +[freenode]: http://freenode.net And remember: good gophers always use gofmt! From a9f5420715ae1c1ca0c4ea445302720bee67ddbe Mon Sep 17 00:00:00 2001 From: Justin Li Date: Thu, 29 Aug 2013 21:48:48 -0400 Subject: [PATCH 2/3] Format the readme more [ci skip] --- README.md | 29 ++++++++++++++++------------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index f021252..d404457 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,9 @@ 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. Planned features include: +should not be used in production. + +Planned features include: - Light resource consumption - Fast request processing, sparing the network from exorbitant connection counts @@ -11,19 +13,26 @@ should not be used in production. Planned features include: - Generic storage interfaces that are easily adapted to work with any existing web application - Scaling properties that directly correlate with those of the chosen data stores -## Technical Details +### Technical Details See [the wiki](https://github.com/pushrax/chihaya/wiki) for a discussion of the design behind Chihaya. -## Installing +## Using Chihaya +### Installing -Make sure you have your $GOROOT and $GOPATH set up correctly and have your $GOBIN on your $PATH. +Make sure you have your `$GOROOT` and `$GOPATH` set up correctly, and have your `$GOBIN` in your `$PATH`. ```sh $ go get github.com/pushrax/chihaya ``` -## Testing +### 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 ```sh $ export TESTCONFIGPATH=$GOPATH/src/chihaya/config/example.json @@ -31,12 +40,6 @@ $ go get github.com/pushrax/chihaya $ go test -v ./... ``` -## 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). - ## Default drivers Chihaya is designed to remain agnostic about the choice of data store for an @@ -45,8 +48,8 @@ are a number of directly supported drivers: Cache: -* [redis](http://redis.io) -* Memory +* [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 Storage: From 6146cc85e3f0c23e9b70e01bcc8374fc389fa495 Mon Sep 17 00:00:00 2001 From: Justin Li Date: Thu, 29 Aug 2013 22:02:12 -0400 Subject: [PATCH 3/3] Bit of info on usage [ci skip] --- README.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index d404457..2c5bf6e 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,14 @@ Planned features include: See [the wiki](https://github.com/pushrax/chihaya/wiki) for a discussion of the design behind Chihaya. ## 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. + +[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`. @@ -40,7 +48,7 @@ $ go get github.com/pushrax/chihaya $ go test -v ./... ``` -## Default drivers +## Drivers 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