Resonate User/Track API

This is the main Resonate User/Track API written in Go, still WIP and not yet in production. If you're looking for the API that is currently running with http://beta.resonate.is, please check its documentation here.

The User/Track API uses Twirp, a RPC framework for service-to-service communication emphasizing simplicity and minimalism. Learn more about Twirp at its website. It also uses go-pg PostgreSQL ORM. Its structure is based on the Twirp starter kit Twisk.

Table of Contents

• Project Structure
• Getting started
  • Prerequisites
  • Dev database setup
  • Dependencies
  • Tools
  • Running the server
  • Implementing new services
• Documentation
• Testing
• Roadmap
• Contributing

Project Structure

The project structure mostly follows THIS example repository and Twirp best practices, except for the services that live in internal/server/<service>.

Getting started

Prerequisites

• Go 1.7 or higher.
• PostgreSQL 9.4 or higher.

Dev database setup

• Create user and database as follow (as found in the local config file in ./conf.local.yaml):

username = "resonate_dev_user"

password = "password"

dbname = "resonate_dev"

Add following postgres extensions: "hstore" and "uuid-ossp"

From ./cmd/migration:

• Init migrations

$ go run *.go init

• Run migrations

$ go run *.go

Dependencies

Dep is used as dependency management tool. vendor/ folder contains project dependencies and should be in sync with Gopkg.toml and Gopkg.lock.

Tools

• Install Protocol Buffers v3, the protoc compiler that is used to auto-generate code. The simplest way to do this is to download pre-compiled binaries for your platform from here: https://github.com/google/protobuf/releases

It is also available in MacOS through Homebrew:

$ brew install protobuf

• Install retool. It helps manage go tools like commands and linters. protoc-gen-go and protoc-gen-twirp plugins were installed into _tools folder using retool.

Build the generators and tool dependencies:

$ retool build

Then, to run the protoc command and autogenerate Go code for the server interface, make sure to prefix with retool do, for example:

$ retool do protoc --proto_path=$GOPATH/src:. --twirp_out=. --go_out=. ./rpc/user/service.proto

Running the server

First, put this repo into $GOPATH/src

Then, run the server

$ go run ./cmd/api/main.go

Alternatively, you can build and run an executable binary

$ cd ./cmd/api/
$ go build
$ ./api

Implementing new services

1. Under proto folder, create a new one named after your service.

2. Define your proto file. If you are not familiar with Protobufs, you can read more about it here. You can use already existing proto files (eg rpc/user/service.proto) as a template.

3. Run retool do protoc --proto_path=$GOPATH/src:. --twirp_out=. --go_out=. ./rpc/<service>/service.proto where <service> is your new service name.

4. Implement the service interface from service.twirp.go in internal/server/tenant.

5. Wire up everything in cmd/api/main.go.

Documentation

• Check out doc/api folder for API documentation. But we'll be transitioning to OpenAPI Specification and Swagger.
• doc/database contains autogenerated database documentation, using SchemaSpy. Open doc/database/index.html in your browser to check it out.

Testing

We use Ginkgo and Gomega for testing.

You need to create the testing database and run migrations manually before running tests.

• Create user and database as follow:

username = "resonate_testing_user"

password = ""

dbname = "resonate_testing"

Add following extensions: "hstore" and "uuid-ossp" (TODO: add them on initial migration)

• Run migrations from ./cmd/migration

$ go run *.go init testing
$ go run *.go testing

• Run tests ./internal/server/<service>

$ go test

Or run all tests using ginkgo CLI from ./

$ ginkgo -r

Roadmap

(see our projects for more details)

• Switch from API Blueprint to OpenAPI and autogenerated API documentation using SwaggerUI
• Implement logging interfaces for every service
• Add JWT based authentication and role-based access control (see internal/iam) to existing services

Contributing

Please check out the Contributing guide for guidelines about how to proceed.

We expect contributors to abide by our underlying code of conduct.