Merge pull request #168 from uber/ajs-cleanup

Cleanup before 1.0 release

.travis.yml

@@ -3,4 +3,5 @@ go:
   - 1.4
   - 1.5
 install: make install_ci
-
+script: make test_ci
+after_success: make cover_ci

CHANGELOG.md

@@ -0,0 +1,15 @@
+Changelog
+=========
+
+# 1.0.0
+
+* First stable release.
+* Supports making calls with JSON, Thrift or raw payloads.
+* Services use thrift-gen, and implement handlers wiht a `func(ctx, arg) (res,
+  error)` signature.
+* Supports retries.
+* Peer selection (peer heap, prefer incoming strategy, for use with Hyperbahn).
+* Graceful channel shutdown.
+* TCollector trace reporter with sampling support.
+* Metrics collection with StatsD.
+* Thrift support, including includes.

CONTRIBUTING.md

@@ -0,0 +1,34 @@
+Contributing
+============
+
+We'd love your help making tchannel-go great!
+
+## Getting Started
+
+TChannel uses [godep](https://github.com/tools/godep) to manage dependencies.
+To get started:
+
+```bash
+go get github.com/uber/tchannel-go
+go get github.com/tools/godep
+cd $GOPATH/src/github.com/uber/tchannel-go
+godep restore
+make  # tests should pass
+```
+
+## Making A Change
+
+*Before making any significant changes, please [open an
+issue](https://github.com/uber/tchannel-go/issues).* Discussing your proposed
+changes ahead of time will make the contribution process smooth for everyone.
+
+Once we've discussed your changes and you've got your code ready, make sure
+that tests are passing (`make test` or `make cover`) and open your PR! Your
+pull request is most likely to be accepted if it:
+
+* Includes tests for new functionality.
+* Follows the guidelines in [Effective
+  Go](https://golang.org/doc/effective_go.html) and the [Go team's common code
+  review comments](https://github.com/golang/go/wiki/CodeReviewComments).
+* Has a [good commit
+  message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).

LICENSE.md

@@ -0,0 +1,19 @@
+Copyright (c) 2015 Uber Technologies, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

Makefile

@@ -46,6 +46,7 @@ install:
 	GOPATH=$(GODEPS) godep restore
 
 install_ci: get_thrift install
+	go get -u github.com/mattn/goveralls
 
 help:
 	@egrep "^# target:" [Mm]akefile | sort -
@@ -78,12 +79,17 @@ benchmark: clean setup
 	echo Running benchmarks:
 	go test $(PKGS) -bench=. -parallel=4
 
-cover: clean setup
-	echo Testing packages:
+cover_profile: clean setup
+	@echo Testing packages:
 	mkdir -p $(BUILD)
-	go test ./ $(TEST_ARG)  -coverprofile=$(BUILD)/coverage.out
+	go test ./ $(TEST_ARG) -coverprofile=$(BUILD)/coverage.out
+
+cover: cover_profile
 	go tool cover -html=$(BUILD)/coverage.out
 
+cover_ci: cover_profile
+	goveralls -coverprofile=$(BUILD)/coverage.out -service=travis-ci
+
 vet:
 	echo Vetting packages for potential issues...
 	go tool vet $(PKGS)

README.md

@@ -1,124 +1,67 @@
-# TChannel
+# TChannel [![GoDoc][doc-img]][doc] [![Build Status][ci-img]][ci] [![Coverage Status][cov-img]][cov]
 
-[![GoDoc](https://godoc.org/github.com/uber/tchannel-go?status.svg)](https://godoc.org/github.com/uber/tchannel-go)
-[![Build Status](https://travis-ci.org/uber/tchannel-go.svg?branch=master)](https://travis-ci.org/uber/tchannel-go)
+[TChannel][tchan-spec] is a multiplexing and framing protocol for RPC calls.
+tchannel-go is a Go implementation of the protocol, including client libraries
+for [Hyperbahn][hyperbahn].
 
-[TChannel](https://github.com/uber/tchannel/blob/master/docs/protocol.md) is a multiplexing and framing protocol for RPC calls.
-
-tchannel-go is a Go implementation of the TChannel protocol, and includes client libraries for [Hyperbahn](https://github.com/uber/hyperbahn).
-
-## Stability: experimental
-
-NOTE: `master:golang` is **not yet stable**
-
-## Thrift + TChannel Integration
-
-If you want to use Thrift+TChannel, you will want to read [this guide](guide/Thrift_Hyperbahn.md).
-
-## Getting Started
-
-Get Go from your package manager of choice or follow the [official installation instructions](https://golang.org/doc/install).
-
-```bash
-brew install go
-
-# This will be your GOPATH where all Go code will live.
-mkdir -p ~/gocode/src
-```
-
-Set up your environment for your shell of choice.
-
-```bash
-export GOPATH="${HOME}/gocode"
-export PATH="${PATH}":"${GOPATH}/bin"
-```
-
-TChannel uses [godep](https://github.com/tools/godep) to manage dependencies.  To get started:
-
-```bash
-go get github.com/uber/tchannel-go
-go get github.com/tools/godep
-cd $GOPATH/src/github.com/uber/tchannel-go
-godep restore
-make
-```
-### Examples
-
-Simple examples are included which demonstrate the TChannel API and features.
-
-
-#### PingPong
-```bash
-./build/examples/ping/pong
-```
-
-This example creates a client and server channel.  The server channel registers a PingService
-with a ping method, which takes request Headers and a Ping body and returns the
-same Headers along with a Pong body.  The client sends a ping request to the server
-
-Note that every instance is bidirectional, so the same channel can be used for both sending
-and receiving requests to peers.  New connections are initiated on demand.
-
-
-#### KeyValue
-```bash
-./build/examples/keyvalue/server
-./build/examples/keyvalue/client
-```
-
-This example exposes a simple keyvalue service over TChannel using the Thrift protocol.
-The client has an interactive CLI that can be used to make calls to the server.
+If you'd like to start by writing a small Thrift and TChannel service, check
+out [this guide](guide/Thrift_Hyperbahn.md). For a less opinionated setup, see
+the [contribution guidelines](CONTRIBUTING.md).
 
 ## Overview
 
-TChannel is a network protocol with the following goals:
+TChannel is a network protocol that supports:
 
- * request / response model
- * multiple requests multiplexed across the same TCP socket
- * out of order responses
- * streaming request and responses
- * all frames checksummed
- * transport arbitrary payloads
- * easy to implement in multiple languages
- * near-redis performance
+ * A request/response model,
+ * Multiplexing multiple requests across the same TCP socket,
+ * Out-of-order responses,
+ * Streaming requests and responses,
+ * Checksummed frames,
+ * Transport of arbitrary payloads,
+ * Easy implementation in many languages, and
+ * Redis-like performance.
 
-This protocol is intended to run on datacenter networks for inter-process communication.
+This protocol is intended to run on datacenter networks for inter-process
+communication.
 
 ## Protocol
 
-TChannel frames have a fixed length header and 3 variable length fields. The underlying protocol
-does not assign meaning to these fields, but the included client/server implementation uses
-the first field to represent a unique endpoint or function name in an RPC model.
-The next two fields can be used for arbitrary data. Some suggested way to use the 3 fields are:
+TChannel frames have a fixed-length header and 3 variable-length fields. The
+underlying protocol does not assign meaning to these fields, but the included
+client/server implementation uses the first field to represent a unique
+endpoint or function name in an RPC model.  The next two fields can be used for
+arbitrary data. Some suggested way to use the 3 fields are:
 
-* URI path, HTTP method and headers as JSON, body
-* function name, headers, thrift / protobuf
+* URI path + HTTP method and headers as JSON + body, or
+* Function name + headers + thrift/protobuf.
 
-Note however that the only encoding supported by TChannel is UTF-8.  If you want JSON, you'll need
-to stringify and parse outside of TChannel.
+Note, however, that the only encoding supported by TChannel is UTF-8.  If you
+want JSON, you'll need to stringify and parse outside of TChannel.
 
-This design supports efficient routing and forwarding of data where the routing information needs
-to parse only the first or second field, but the 3rd field is forwarded without parsing.
+This design supports efficient routing and forwarding: routers need to parse
+the first or second field, but can forward the third field without parsing.
 
-There is no notion of client and server in this system. Every TChannel instance is capable of
-making or receiving requests, and thus requires a unique port on which to listen. This requirement may
-change in the future.
+There is no notion of client and server in this system. Every TChannel instance
+is capable of making and receiving requests, and thus requires a unique port on
+which to listen. This requirement may change in the future.
 
- - See [protocol.md](https://github.com/uber/tchannel/blob/master/docs/protocol.md) for more details
+See the [protocol specification][tchan-proto-spec] for more details.
 
-## Further examples
+## Examples
 
- - [ping](examples/ping/main.go): A simple ping/pong example using raw TChannel.
+ - [ping](examples/ping): A simple ping/pong example using raw TChannel.
  - [thrift](examples/thrift): A Thrift server/client example.
  - [keyvalue](examples/keyvalue): A keyvalue Thrift service with separate server and client binaries.
 
-## Tests
-
-`make test` or `make cover`
-
-## Contributors
-
- - mmihic
- - prashantv
-
-## MIT Licenced
+<hr>
+This project is released under the [MIT License](LICENSE.md).
+
+[doc-img]: https://godoc.org/github.com/uber/tchannel-go?status.svg
+[doc]: https://godoc.org/github.com/uber/tchannel-go
+[ci-img]: https://travis-ci.org/uber/tchannel-go.svg?branch=master
+[ci]: https://travis-ci.org/uber/tchannel-go
+[cov-img]: https://coveralls.io/repos/uber/tchannel-go/badge.svg?branch=master&service=github
+[cov]: https://coveralls.io/github/uber/tchannel-go?branch=master
+[tchan-spec]: http://tchannel.readthedocs.org/en/latest/
+[tchan-proto-spec]: http://tchannel.readthedocs.org/en/latest/protocol/
+[hyperbahn]: https://github.com/uber/hyperbahn

examples/keyvalue/README.md

@@ -0,0 +1,10 @@
+# Key-Value Store
+
+```bash
+./build/examples/keyvalue/server
+./build/examples/keyvalue/client
+```
+
+This example exposes a simple key-value store over TChannel using the Thrift
+protocol.  The client has an interactive CLI that can be used to make calls to
+the server.