track-server-api

README

🛠 Status: Maintenance Mode | Stable

This project is currently in maintenance mode - users should feel free to continue to use this app and expect bug fixes, but not expect many additional features.

Resonate Track Server API

The track-server-api delivers streaming track downloads, and accepts track uploads. It's still WIP. It 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 main service that lives in internal/server/.

Getting started

Prerequisites

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

Dev database setup

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

username = "track_resonate_dev_user"

password = "password"

dbname = "track_resonate_dev"

Add following postgres extension: "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

Documentation

• There is no API documentation yet, except for this README. Eventually, documentation will be provided in doc/api using OpenAPI Specification and Swagger.

• TODO: 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 = "track_resonate_testing_user"

password = ""

dbname = "track_resonate_testing"

Add following extension: "uuid-ossp"

• Run migrations from ./cmd/migration

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

• Run tests ./internal/server/

$ go test

Or run all tests using ginkgo CLI from ./

$ ginkgo -r

Roadmap

• The service that is currently implemented is based on an experimental Twirp v6_streams_alpha branch. Adding streaming support to Twirp is still being discussed within the community. Given the recent discussions, we might need to find another way to implement it.
• Write documentation with OpenAPI and autogenerated API documentation using SwaggerUI
• TBC

Contributing

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

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