Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ribice/twisk
Golang RPC starter kit with Twirp
https://github.com/ribice/twisk
golang protobuf rest-api rpc starter starter-kit
Last synced: 17 days ago
JSON representation
Golang RPC starter kit with Twirp
- Host: GitHub
- URL: https://github.com/ribice/twisk
- Owner: ribice
- License: mit
- Created: 2018-08-16T05:17:31.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2018-08-30T04:41:08.000Z (about 6 years ago)
- Last Synced: 2024-10-12T22:34:03.030Z (about 1 month ago)
- Topics: golang, protobuf, rest-api, rpc, starter, starter-kit
- Language: Go
- Homepage: https://www.ribice.ba/twisk/
- Size: 7.43 MB
- Stars: 127
- Watchers: 5
- Forks: 4
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Twisk - Golang RPC starter kit
[![Build Status](https://travis-ci.org/ribice/twisk.svg?branch=master)](https://travis-ci.org/ribice/twisk)
[![codecov](https://codecov.io/gh/ribice/twisk/branch/master/graph/badge.svg)](https://codecov.io/gh/ribice/twisk)
[![Go Report Card](https://goreportcard.com/badge/github.com/ribice/twisk)](https://goreportcard.com/report/github.com/ribice/twisk)Twisk is a starter kit for [Twirp](https://github.com/twitchtv/twirp) - a framework for service-to-service communication emphasizing simplicity and minimalism.
It contains things you need to kickstart your project - structured packaging, logging, autogenerated swagger docs, handlers for login/refresh and user CRUD.
I made this project as a preparation for Gophercon 2018 Lightning Talk - [Building robust APIs with Twirp](https://gc2018-lightning.herokuapp.com/blocks/c8d55346-012d-4d72-83db-fc8a3f92a9a3/slots/9ccad9a7-1e67-4f40-8889-dfa86110ba9e).
Read more about Twirp on the [official repo](https://github.com/twitchtv/twirp), [release blog post](https://blog.twitch.tv/twirp-a-sweet-new-rpc-framework-for-go-5f2febbf35f) and [documentation website](https://twitchtv.github.io/twirp/docs/intro.html).
Twisk currently has:
* Fully featured RESTful endpoints for authentication and CRUD operations on the user entity
* Session handling using JWT claims
* JWT Based authentication
* Application configuration via config file (yaml)
* RBAC (role-based access control)
* Structured logging
* Request marshaling and data validation
* Autogenerated API Docs using SwaggerUI
* Mocking using stdlib
* Basic test coverageThe following dependencies are used in this project (generated using [Glice](https://github.com/ribice/glice)):
```bash
|---------------------------------------|-----------------------------------------------|-------------|
| DEPENDENCY | REPOURL | LICENSE |
|---------------------------------------|-----------------------------------------------|-------------|
| github.com/golang/protobuf | https://github.com/golang/protobuf | bsd-3-clause|
| gopkg.in/yaml.v2 | https://github.com/go-yaml/yaml | Apache-2.0 |
| github.com/mwitkow/go-proto-validators| https://github.com/mwitkow/go-proto-validators| Apache-2.0 |
| github.com/twitchtv/twirp | https://github.com/twitchtv/twirp | Other |
| github.com/gorilla/mux | https://github.com/gorilla/mux | bsd-3-clause|
| github.com/justinas/alice | https://github.com/justinas/alice | MIT |
| github.com/go-pg/pg | https://github.com/go-pg/pg | bsd-2-clause|
| github.com/rs/xid | https://github.com/rs/xid | MIT |
| github.com/nbutton23/zxcvbn-go | https://github.com/nbutton23/zxcvbn-go | MIT |
| github.com/rakyll/statik | https://github.com/rakyll/statik | Apache-2.0 |
| github.com/dgrijalva/jwt-go | https://github.com/dgrijalva/jwt-go | MIT |
| github.com/rs/zerolog | https://github.com/rs/zerolog | MIT |
|---------------------------------------|-----------------------------------------------|-------------|
```1. Protobuf - Proto formats (timestamp)
2. Yaml - Unmarshalling YAML config file
3. Twirp - RPC Framework
4. Mux - Router
5. Alice - Chaining middlewares
6. PG - PostgreSQL ORM
7. Statik - Static files to binary generator
8. JWT-GO - JWT Authentication
9. Zerolog - Logging
10. XID - Refresh token generation
11. ZXCVBN-Go - Password strength checkerMost of these can easily be replaced with your own choices since their usage is abstracted and localized. In addition to these, the following tools were used:
* Retool - Go executables vendoring
* GoValidators - Proto (request/response) validation
* TwirpSwagger - Swagger docs generator from proto definitions## Project Structure
Twisk's project structure mostly follows [THIS](https://github.com/golang-standards/project-layout) example repository.
Twisk doesn't follow all best practices advices by Twirp. For example, functions are named `List`, `Create` and `Delete` instead of `ListUsers`, `CreateUser` and `DeleteUser` (I prefer shorter function names, handlers and functions named `user.List` istead of `user.ListUsers`). You can read on Twirp's best practices [here](https://twitchtv.github.io/twirp/docs/best_practices.html).
## Getting started
Using Twisk requires having Go 1.7 or above. Once you downloaded Twisk (either using Git or go get) you need to configure the following:
1. To use Twisk as a starting point of a real project whose package name is something like `github.com/author/project`, move the directory `$GOPATH/github.com/ribice/twisk` to `$GOPATH/github.com/author/project` and do a global replacement of the string `github.com/ribice/twisk` with `github.com/author/project`.
2. Change the configuration file according to your needs. The local config file is found in `cmd/api/conf.local.yaml`. You'll need to configure `database/psn` at least.
3. In cmd/migration/main.go set up psn variable and then run it (go run main.go). It will create all tables, and necessary data, with a new account username/password admin/admin.
4. Run the app using:
```bash
go run cmd/api/main.go
```The application runs as an HTTP server at port 8080. It exposes the following endpoints:
* `GET /openapi/swaggerui`: returns list of swagger specs in browser
* `POST /twirp/twisk.iam.IAM/Auth`: accepts username or email and password. Returns jwt token and refresh token
* `POST /twirp/twisk.iam.IAM/Refresh`: refreshes sessions and returns new jwt token
* `POST /twirp/twisk.user.User/Create`: creates a new user
* `POST /twirp/twisk.user.User/List`: returns list of users
* `POST /twirp/twisk.user.User/View`: returns single user
* `POST /twirp/twisk.user.User/Delete`: deletes a user
* `POST /twirp/twisk.user.User/Update`: updates user's contact infoYou can log in as admin to the application by sending a post request to localhost:8080/twirp/twisk.iam.IAM/Auth with auth `admin` and password `admin` in JSON body.
## Implementing new APIs
1. Under `proto` folder, create a new one named after your service. For example `tenant`. Inside it create `service.proto`
2. Define your proto file. If you are not familiar with Protobufs, you can read more about it [here](https://developers.google.com/protocol-buffers/docs/proto3). You can use already existing proto files (`proto/user/service.proto` & `proto/iam/service.proto`) as a template.
3. Run `make twirp -B`.
4. Implement the Tenant interface from `service.twirp.go` in `internal/tenant`.
5. Tenant service integrations are located in `internal/tenant/platform`. For example cloud storage, database, message queue etc.
6. Implement the interface in logging.go, wrapping around the service implementation.
7. Add service link to `openapi/swagger.html`. Alternatively, use build-links in your CI/CD pipeline to auto-generate the `swagger.html` from `swagger.html.template`.
8. Wire up everything in `cmd/api/main.go`. If neeeded, you can easily skip auth checking on certain routes by passing the service name to `hooks.WithJWTAuth()`. For example `hooks.WithJWTAuth(j, "View","List")`.
## License
Twisk is licensed under the MIT license. Check the [LICENSE](LICENSE.md) file for details.
## Honorable mention
Special thanks to [@tonto](https://github.com/tonto) for previously creating some parts of this project.
## Author
[Emir Ribic](https://ribice.ba)