Merge pull request #76 from hasAdamr/example

Add example and update README.md

README.md

@@ -1,6 +1,6 @@
 # Truss [![Build Status](https://travis-ci.org/TuneLab/go-truss.svg?branch=master)](https://travis-ci.org/TuneLab/go-truss)
 
-Truss handles the painful parts of microservices, freeing you to focus on the business logic.
+Truss handles the painful parts of services, freeing you to focus on the business logic.
 
 **Please note that Truss is currently pre-release software, and may change drastically with no notice. There is no versioning, no guarantees, no stability at this time. However, if you want to play around, make suggestions, or submit changes, we welcome issues and pull requests!**
 
@@ -12,28 +12,38 @@ Currently, there is no binary distribution of Truss, you must install from sourc
 
 To install this software, you must:
 
-1. Install the standard C++ implementation of protocol buffers from https://developers.google.com/protocol-buffers/
-2. Of course, install the Go compiler and tools from https://golang.org/. See https://golang.org/doc/install for details or, if you are using gccgo, follow the instructions at https://golang.org/doc/install/gccgo
-4. Install the `protoc-gen-go` and `proto` packages for Go. The simplest way is to run `go get -u github.com/golang/protobuf/{proto,protoc-gen-go}`. The compiler plugin, protoc-gen-go, will be installed in `$GOBIN`, defaulting to `$GOPATH/bin`.  It must be in your `$PATH` for the protocol compiler, protoc, to find it.
-5. Install the gRPC: `$ go get -u google.golang.org/grpc`
-6. Install Truss with `$ go get -u github.com/TuneLab/go-truss/...`
+1. Install protocol buffers version 3 or greater. The easiest way is to download a release from the [github releases](https://github.com/google/protobuf/releases) and add the binary to your `$PATH`. Otherwise [install from source.](https://github.com/google/protobuf/releases)
+2. Of course, install the Go compiler and tools from https://golang.org/. See https://golang.org/doc/install for details.
+3. Install the `protoc-gen-go` and `proto` packages for Go. The simplest way is to run 
+
+	```
+	go get -u github.com/golang/protobuf/{proto,protoc-gen-go}
+	```
+
+	The compiler plugin, protoc-gen-go, will be installed in `$GOPATH/bin`.  It must be in your `$PATH` for the protocol compiler, `protoc`, to find it.
+4. Install Truss with 
+
+	```
+	go get -u github.com/TuneLab/go-truss/...
+	```
 
 ## Usage
 
-Using Truss is easy. You define your microservice in a protobuf file, and Truss
-uses that definition to create an entire microservice.
+Using Truss is easy. You define your service with [gRPC](http://www.grpc.io/) and [protoc buffers](https://developers.google.com/protocol-buffers/docs/proto3), and Truss uses that definition to create an entire service. You can even add [http annotations](
+https://github.com/googleapis/googleapis/blob/928a151b2f871b4239b7707e1bb59258df3fe10a/google/api/http.proto#L36) for HTTP 1.1/JSON transport!
 
-Once you've written the definition of your microservice, use the command `$ truss
-{NAME_OF_PROTO_FILE}` to generate your microservice into a directory called
-`NAME-service/` within your current directory where NAME is the package name of your service.
+Then you open the `handlers/server/server_handler.go`, add you business logic, and you're good to go.
 
-See [USAGE.md](./USAGE.md) for details
+Here is an example service definition: [Echo Service](./example/echo.proto)
+
+Try Truss for yourself on Echo Service to see the service that is generated:
+
+```
+truss example/echo.proto
+```
+
+See [USAGE.md](./USAGE.md) for more details.
 
 ## Developing
 
-See [DEVELOPING.md](./DEVELOPING.md) for details
-
-<!--
-TODO: Add example here of proto file, and the steps to create a microservice from it.
-   -->
-
+See [DEVELOPING.md](./DEVELOPING.md) for details.

example/echo.proto

@@ -0,0 +1,46 @@
+// In general, while you can use proto2 (the current default protocol buffers
+// version), we recommend that you use proto3 with gRPC as it lets you use the
+// full range of gRPC-supported languages, as well as avoiding compatibility
+// issues with proto2 clients talking to proto3 servers and vice versa.
+syntax = "proto3";
+
+// The package name determines the name of the directories that truss creates
+// for `package echo;` truss will create the directory "echo-service".
+package echo;
+
+import "google/api/annotations.proto";
+
+service Echo {
+  // Echo "echos" the incoming string
+  rpc Echo (EchoRequest) returns (EchoResponse) {
+    option (google.api.http) = {
+        // All fields (In) are query parameters of the http request unless otherwise specified
+        get: "/echo"
+      };
+  }
+
+  // Louder "echos" the incoming string with `Loudness` additional exclamation marks
+  rpc Louder (LouderRequest) returns (EchoResponse) {
+    option (google.api.http) = {
+        // Loudness is accepted in the http path
+        post: "/louder/{Loudness}"
+        // All other fields (In) are located in the body of the http/json request
+        body: "*"
+      };
+  }
+}
+
+message EchoRequest {
+  string In = 1;
+}
+
+message LouderRequest {
+  // In is the string to echo back
+  string In = 1;
+  // Loudness is the number of exclamations marks to add to the echoed string
+  int32 Loudness = 2;
+}
+
+message EchoResponse {
+  string Out = 1;
+}