godin

Godin - An opinionated toolkit for go-kit microservices

Work in progress, be careful.

After starting your journey into the realm of microservices with Go, you sooner or later start to get lazy and copy&paste stuff. Things get horrbile to maintain and all the joy of programming escapes.

Godin to the rescue! It helps you to create, update and maintain microservices using go-kit as foundation.

A quick summary of what Godin can do:

• initialize a new microservice project including Makefile, Dockerfile and Kubernetes deployment/service manifests
• generate a running go-kit microservice application based on a single service-interface.
• update all necessary files with one command godin update and all new functions in the service interface are prepared
• remove tedious copy&paste work when writing request/response de-/encoders
• add new bundles to quickly up the game (mysql, mongodb, pub/sub, ...)
• pre-generate tests

Built With

• cobra
• viper
• go-kit
• go-astra

Getting Started

Prerequisites

• Go (1.12)
• make
• packr v1(!)

Installation

Head over to the Releases page and download the appropriate archive. Simply unpack, put the binary in your $PATH and you're ready to roll.

Examples

Examples are now hosted in a separate repository: godin-examples

Usage

Available commands

godin init

Calling godin init will generate the following project structure in the CWD. First you need to answer a few prompts to configure the project. You only have to do this once, after that the configuration is stored in godin.json

.
├── cmd
│   └── greeter
├── Dockerfile
├── godin.json
├── go.mod
├── internal
│   ├── grpc
│   └── service
│       ├── endpoint
│       ├── greeter
│       ├── middleware
│       │   └── middleware.go
│       └── service.go
└── pkg
    └── grpc

godin update

After writing out the service interface in internal/service/service.go, calling godin update will generate everything required to serve a gRPC server. Middleware will automatically be added based on the project configuration in godin.json.

This is the structure godin update currently creates

.
├── cmd
│   └── user
│       └── main.go
├── Dockerfile
├── godin.json
├── go.mod
├── go.sum
├── internal
│   ├── grpc
│   │   ├── encode_decode.go
│   │   ├── request_response.go
│   │   └── server.go
│   └── service
│       ├── endpoint
│       │   ├── endpoints.go
│       │   ├── request_response.go
│       │   └── set.go
│       ├── middleware
│       │   ├── logging.go
│       │   └── middleware.go
│       ├── service.go
│       └── user
│           └── implementation.go
└── pkg
    └── grpc

Not all files will be generated fully every time update is executed. Below is a table to see which files you'd better not edit 😅.

configuration

After godin init is called, everything is based off your service definition plus the godin.json. An example of such a config file is listed below.

{
  "godin": {
    "version": "0.3.0"
  },
  "project": {
    "created": "Sun, 23 Jun 2019 10:15:02 CEST",
    "updated": "Sun, 23 Jun 2019 12:14:26 CEST"
  },
  "protobuf": {
    "package": "github.com/lukasjarosch/godin-examples/user/api",
    "service": "UserService"
  },
  "service": {
    "endpoints": {
      "create": {
        "protobuf": {
          "request": "CreateRequest",
          "response": "CreateResponse"
        }
      },
      "delete": {
        "protobuf": {
          "request": "DeleteRequest",
          "response": "DeleteResponse"
        }
      },
      "get": {
        "protobuf": {
          "request": "GetRequest",
          "response": "GetResponse"
        }
      },
      "list": {
        "protobuf": {
          "request": "ListRequest",
          "response": "ListResponse"
        }
      }
    },
    "middleware": {
      "authorization": false,
      "caching": false,
      "logging": true,
      "recovery": true
    },
    "module": "github.com/lukasjarosch/godin-examples/user",
    "name": "user",
    "namespace": "godin"
  },
  "transport": {
    "grpc": {
      "enabled": true
    }
  }
}

Middleware

There are three middleware levels: service, endpoint and transport

Service middleware

It's implementation specific and allows to define a middleware on domain-level. Here you have full access to request and response data of the business logic (implementation.go). By default, Godin will generate and maintain a logging middleware which logs the request and response data, errors and the execution time of your business logic.

Other use-cases of service middlewares are:

• caching
• authentication
• monitoring of business metrics (users_logged_in, queue_size, ...)

Endpoint middleware

It's only provided by godin and is applicable to every endpoint. The middleware does only have interface{} access to the request and response data. This makes the endpoint middleware a great place to put all the annoying stuff which most of the developers should not have to deal with, like:

• Endpoint instrumentation (prometheus)
• Circuit breaking
• Distributed tracing
• Rate limiting
• General logging (endpoint request duration)

Currently, Godin does not provide all of those middlewares. The following are implemented:

• Prometheus endpoint instrumentation (exposed via 0.0.0.0:3000/metrics).
  • endpoint_request_duration_ms
  • endpoint_requests_current
  • endpoint_requests_total
• General logging to capture endpoint request duration
• Circuit breaking
• Rate limiting
• Distributed tracing

Transport middleware

It's (obviously) transport specific. Godin is currently only providing a gRPC server as that's it's main use-case. In the future, HTTP might follow.

Godin automatically registers the go-grpc-prometheus interceptors. Thus these metrics are also registered and available via /metrics.

Tips and tricks

Rename protobuf request/responses

By default, Godin will construct Protobuf requests and responses like this: <EndpointName>Request and <EndpointName>Response. This might not always be correct as Godin does not parse the protobuf definition. If you need to change the name of a request/response, proceed as follows:

• call godin update to generate the default names and also to ensure that the endpoint exists in godin.json
• refactor the app (search and replace) to use the new request for example. Search for: *pb.<Endpoint>Request and replace with your actual name. Then also replace the name in godin.json
• calling godin update will now work as expected again, but using your custom type name

License

Distributed under the MIT License. See LICENSE for more information.