![](https://masterminds.github.io/stability/active.svg)
Go Service
A framework to build services in go. This came out of out building services over the years and what I have considered good practices in building services. Hence it is highly subjective and opinionated.
This framework stands on the shoulder of giants so we don't reinvent the wheel!
Dependency Injection
This framework heavily relies on DI. We have chosen to use Uber FX. So there is great information online to get you up to speed.
Commands
A service has commands that are configured using Cobra. Each service has the following commands (you can add more):
Server
- This will host your server.
Client
- This will provide your client needs.
These are configured in the main function.
Configuration
The supported configuration kinds are as follows:
The configuration can be read from multiple sources by specifying a flag called --input
or -i
. As per the following:
env:CONFIG_FILE
- Read from an env variable called CONFIG_FILE
. This is the default if nothing is passed. The env variable can be file path or the configuration. If it is the config, we expect the format of extension:ENV_VARIABLE
, where extension is the supported kinds and ENV_VARIABLE
contains the contents of the config that are base64 encoded. This can be overridden.
file:path
- Read from the path.
The reason for this is that we want to be able to separate how configuration is retrieved. This way we can use and application configuration system.
This is the configuration. We will outline the config required in each section. The following configuration examples will use YAML.
Environment
You can specify the environment of the service.
Configuration
To configure, please specify the following:
environment: development
Compression
We support the following:
Marshalling
We support the following:
Caching
The framework currently supports the following caching solutions:
Configuration
To configure, please specify the following:
cache:
redis:
compressor: snappy
marshaller: proto
addresses:
server: localhost:6379
url: path to url
ristretto:
num_counters: 10000000
max_cost: 100000000
buffer_items: 64
Dependencies
![Dependencies](https://github.com/alexfalkowski/go-service/raw/v1.238.0/assets/cache.png)
Feature
The framework supports OpenFeature.
Configuration
To configure, please specify the following:
feature:
kind: flipt
host: localhost:9000
retry:
backoff: 100ms
timeout: 1s
attempts: 3
timeout: 10s
Hooks
The framework supports Standard Webhooks.
Configuration
To configure, please specify the following:
hooks:
secret: path to secret
Runtime
We enhance the runtime with the following:
SQL
For SQL databases we support the following:
We also support master, slave combinations with the awesome mssqlx.
Configuration
To configure, please specify the following:
sql:
pg:
masters:
-
url: path to url
slaves:
-
url: path to url
max_open_conns: 5
max_idle_conns: 5
conn_max_lifetime: 1h
Dependencies
![Dependencies](https://github.com/alexfalkowski/go-service/raw/v1.238.0/assets/database.png)
Health
The health package is based on go-health. This package allows us to create all sorts of ways to check external and internal systems.
We also provide ways to integrate into container integration systems. So we provide the following endpoints:
/healthz
- This allows us to check any external dependency and provide a breakdown of what is not functioning. This should only be used for verification.
/livez
: Can be used for k8s liveness.
/readyz
: Can be used for k8s readiness.
This is modelled around Kubernetes API health endpoints.
Telemetry
Telemetry is broken down in the following sections:
Logging
For logging we use Uber Zap.
Configuration
To configure, please specify the following:
telemetry:
logger:
level: info
Metrics
For metrics we support the following:
Configuration
Below is the configuration for each system.
Prometheus
To configure, please specify the following:
telemetry:
metrics:
kind: prometheus
OTLP
To configure, please specify the following:
telemetry:
metrics:
kind: otlp
host: http://localhost:9009/otlp/v1/metrics
key: path to key
Trace
For distributed tracing we support the following:
Configuration
Below is the configuration for each system.
OTLP
To configure, please specify the following:
telemetry:
tracer:
kind: otlp
host: localhost:4318
key: path to key
Dependencies
![Dependencies](https://github.com/alexfalkowski/go-service/raw/v1.238.0/assets/telemetry.png)
Token
The framework allows you to define different token generators and verifiers.
Out to the box we provide the following:
We recommend that you look at better auth strategies, such as:
Configuration
To configure, please specify the following:
token:
argon2:
key: path to the key
hash: hash of the key
Limiter
The framework allows you to define a limiter. This will be applied to the different transports.
The different kinds are:
Configuration
To configure, please specify the following:
limiter:
kind: user-agent
tokens: 10
interval: 1s
Time
The framework allows you use network time services. We use:
Configuration
To configure, please specify the following:
time:
kind: nts
host: time.cloudflare.com
Transport
The transport layer provides ways to abstract communication for in/out of the service. So we have the following integrations:
gRPC
Below is list of the provided interceptors:
REST
Below is list of the provided handlers:
Configuration
To configure, please specify the following:
transport:
http:
port: 8000
retry:
backoff: 100ms
timeout: 1s
attempts: 3
timeout: 10s
grpc:
port: 9000
retry:
backoff: 100ms
timeout: 1s
attempts: 3
timeout: 10s
If you would like to enable TLS, do the following:
transport:
http:
tls:
cert: path of cert
key: path of key
grpc:
tls:
cert: path of cert
key: path of key
Dependencies
![Dependencies](https://github.com/alexfalkowski/go-service/raw/v1.238.0/assets/transport.png)
Cryptography
The crypto package provides sensible defaults for symmetric, asymmetric, hashing and randomness.
We rely on the following libraries:
Configuration
To configure, please specify the following:
crypto:
aes:
key: path to the key
ed25519:
public: path to the public
private: path to the private
hmac:
key: path to the key
rsa:
public: path to the public
private: path to the private
ssh:
public: path to the public
private: path to the private
Dependencies
![Dependencies](https://github.com/alexfalkowski/go-service/raw/v1.238.0/assets/crypto.png)
Debug
This section outlines all utilities added for you troubleshooting abilities.
statsviz
GET http://localhost:6060/debug/statsviz
Check out statsviz.
pprof
GET http://localhost:6060/debug/pprof/
GET http://localhost:6060/debug/pprof/cmdline
GET http://localhost:6060/debug/pprof/profile
GET http://localhost:6060/debug/pprof/symbol
GET http://localhost:6060/debug/pprof/trace
Check out pprof.
fgprof
GET http://localhost:6060/debug/fgprof?seconds=10
Check out fgprof.
gopsutil
GET http://localhost:6060/debug/psutil
Check out gopsutil.
Configuration
To configure, please specify the following:
debug:
port: 6060
timeout: 10s
If you would like to enable TLS, do the following:
debug:
tls:
cert: path of cert
key: path of key
Development
This section describes how to run and contribute to the project, if you are interested.
Style
We favour what is defined in the Uber Go Style Guide.
Dependencies
Please setup the following:
Setup
To get yourself setup, please run:
git submodule sync
git submodule update --init
mkcert -install
make create-certs
make dep
Environment
As we rely on external services these need to be configured:
Starting
Please run:
make start
Stopping
Please run:
make stop
Testing
To be able to test locally, please run:
make specs