roster

README

Roster Service

The simple service for a roster management.

Contents

• About
• Tools and Technologies
• Tests
• Production readiness
• Dependencies
• Installation
• Run
• Docker
• Cloud
• API

About

This tiny service was built to manage rosters with very limited abilities. The API is described in API section.

Tools, libraries and approaches were chosen with a focus on production readiness.

Tools and Technologies

There are some technical decisions made to bring more flexibility and scalability to the service. It may look overcomplicated, but there is extensibility and reliability behind the simplicity.

There are no frameworks due to simple infrastructure.

• MongoDB - chosen because it's easy to shard and has enough search engine power to fulfill service needs;
• Swagger - perfectly describes REST APIs and can be used to generate server and client API-code in a single command;
• JWT auth - used to secure changes via API. Used because it's a common choice for API auth.
• Docker - used to satisfy requirements and build and run the service in isolated environment. Multistage build is made to make resulted image as small as possible. Can be used on any cloud environment or as a part of orchestration systems like k8s;
• Heroku - chosen as a simplest hosting with CI/CD features because it is easy to setup and monitor.

Tests

All core logic (request handlers) is covered with unit-tests. No need to check infrastructure and generated core, because it doesn't change so much, but really hard to test. DB and web layers are isolated.

Production readiness

The service is ready to run as a standalone microservice in any environment, e.g. K8s.

It is built with a closer look to 12-factor app principle, and can be easily integrated into 12-f infrastructure with small changes or additions.

Dependencies

The tool has no runtime dependencies, but some development tools which you may need to contribute:

go-swagger

go-swagger is a tool for automate code generation based on swagger.yml schema.

Install on MacOS

brew install go-swagger 

Install on Linux

echo "deb https://dl.bintray.com/go-swagger/goswagger-debian ubuntu main" | sudo tee -a /etc/apt/sources.list 

Other installation options.

mockery

mockery is a tool for automate code generation for testing mocks.

Install

go get github.com/vektra/mockery/.../ 

More information.

Installation

Installation as a Go package

go get -v -u https://github.com/ilyakaznacheev/roster 

Installation as a git repo

git clone https://github.com/ilyakaznacheev/roster.git 

Run

There are several options. You can run the service as a standalone binary, but you should satisfy infrastructure requirements in this case. For more information run

go run cmd/roster/main.go -h 

Note! There is no possibility to create a roster via API, so you need to initialize the database by your own.

But there are some more useful ways to run it preconfigured for you.

Docker

To start the service in a docker-compose, you need docker and docker-compose to be installed on your machine.

Then you can run

make docker/up 

it will start to serve on localhost:8080.

To shut it down run

make docker/down 

Cloud

The project is preconfigured to run on Heroku. You can clone the repo and connect your own Heroku app - it should start Dockerfile. For more information read my article.

API

API is tiny but powerful. For detailed information check swagger.yml. For nice picture paste it into Swagger Editor.

Shortly you can do the following:

• [POST] /api/register - register a new API user
• [POST] /api/login - get JWT token (you need it to make changes)
• [GET] /api/rosters - get a list of rosters
• [GET] /api/rosters/{id} - get certain roster
• [GET] /api/rosters/{id}/active - get a roster with active players only
• [GET] /api/rosters/{id}/benched - get a roster with benched players only
• [POST] /api/rosters/{id}/add_player - add a new player
• [POST] /api/rosters/{id}/rearrange - rearrange players

Documentation

Overview

Package roster

This tiny service was built to manage rosters with very limited abilities. Check swagger.yml for more information.

Tools, libraries and approaches were chosen with a focus on production readiness.

Tools and Technologies

There are some technical decisions made to bring more flexibility and scalability to the service. It may look overcomplicated, but there is extensibility and reliability behind the simplicity.

There are no frameworks due to simple infrastructure.

- MongoDB - chosen because it's easy to shard and has enough search engine power to fulfill service needs; - Swagger - perfectly describes REST APIs and can be used to generate server and client API-code in a single command; - JWT auth - used to secure changes via API. Used because it's a common choice for API auth. - Docker - used to satisfy requirements and build and run the service in isolated environment. Multistage build is made to make resulted image as small as possible. Can be used on any cloud environment or as a part of orchestration systems like k8s; - Heroku - chosen as a simplest hosting with CI/CD features because it is easy to setup and monitor.

Tests

All core logic (request handlers) is covered with unit-tests. No need to check infrastructure and generated core, because it doesn't change so much, but really hard to test. DB and web layers are isolated.

Production readiness

The service is ready to run as a standalone microservice in any environment, e.g. k8s.

It is built with a closer look to 12-factor app principle, and can be easily integrated into 12-f infrastructure with small changes or additions.

To run the service as a library you need to run the Run function. It handles termination, so no need to set extra context.

var cfg config.Application
// fill the config
err := roster.Run(cfg)
if err != nil {
	os.Exit(1)
}

To run from command-line just call

go run cmd/roster/main.go

Index

• func Run(cfg config.Application) error

Functions

func Run

func Run(cfg config.Application) error

Run starts the server