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!
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.
A service has commands that are configured using acmd. Each service has the following commands:
Server
- These are long running apps, e.g daemons.Client
- This are short lived apps, e.g control.
These are configured in the main function.
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
- Read from an env variable calledCONFIG
. The env variable must be a configuration and we expect the format ofextension:content
, whereextension
is the supported kinds andcontent
contains the contents of the config that is base64 encoded.file:path
- Read from the path.- If all the above fails it will try common locations, such as:
- The binary location.
- The
config
folder in your home directory. - The
/etc
folder.
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.
You can specify the environment of the service.
To configure, please specify the following:
environment: development
We support the following:
We support the following:
The framework currently supports the following caching solutions from the awesome Cachego.
To configure, please specify the following:
cache:
kind: redis | sync
compressor: none | s2 | zstd | snappy
encoder: json | toml | yaml | proto | gob
options:
url: path to url
The framework supports OpenFeature.
To configure, please specify the following:
feature:
address: localhost:9000
retry:
backoff: 100ms
timeout: 1s
attempts: 3
timeout: 10s
The framework supports Standard Webhooks.
To configure, please specify the following:
hooks:
secret: path to secret
The framework supports the generation of ids. The following are supported:
To configure, please specify the following:
id:
kind: uuid | ksuid | nanoid | ulid | xid
We enhance the runtime with the following:
For SQL databases we support the following:
We also support master, slave combinations with the awesome mssqlx.
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
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:
/name/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./name/livez
: Can be used for k8s liveness./name/readyz
: Can be used for k8s readiness.
This is modelled around Kubernetes API health endpoints.
Telemetry is broken down in the following sections:
For logging we use slog.
We have multiple options for logging.
To configure, please specify the following:
telemetry:
logger:
kind: json
level: info
To configure, please specify the following:
telemetry:
logger:
kind: text
level: info
To configure, please specify the following:
telemetry:
logger:
kind: otlp
level: info
url: http://localhost:3100/loki/api/v1/push
headers:
Authorization: path to key
For metrics we support the following:
Below is the configuration for each system.
To configure, please specify the following:
telemetry:
metrics:
kind: prometheus
To configure, please specify the following:
telemetry:
metrics:
kind: otlp
url: http://localhost:9009/otlp/v1/metrics
headers:
Authorization: path to key
For distributed tracing we support the following:
Below is the configuration for each system.
To configure, please specify the following:
telemetry:
tracer:
kind: otlp
url: localhost:4318
headers:
Authorization: path to key
The framework allows you to define different token generators and verifiers.
We have support for different access controls using casbin.
To configure, please specify the following:
token:
access:
policy: path to policy file
The model is based on the following config.
We use the awesome JWT.
To configure, please specify the following:
token:
kind: jwt
jwt:
sub: subject
aud: audience
iss: issuer
exp: 1h
kid: 1234567890
We use the awesome Paseto.
To configure, please specify the following:
token:
kind: paseto
paseto:
sub: subject
aud: audience
iss: issuer
exp: 1h
We use the awesome SSH.
To configure, please specify the following:
token:
kind: ssh
ssh:
key:
name: test
private: path to key
To configure, please specify the following:
token:
kind: ssh
ssh:
keys:
- name: test
public: path to key
The framework allows you to define a limiter. This will be applied to the different transports.
The different kinds are:
To configure, please specify the following:
limiter:
kind: user-agent
tokens: 10
interval: 1s
The framework allows you use network time services. We use:
To configure, please specify the following:
time:
kind: nts
address: time.cloudflare.com
The transport layer provides ways to abstract communication for in/out of the service. So we have the following integrations:
- gRPC - The author truly believes in IDLs.
- REST - An abstraction using content negotiation and the awesome resty.
- RPC - abstraction using content negotiation.
- MVC - We have a simple framework.
- CloudEvents - A specification for describing event data in a common way.
Below is list of the provided interceptors:
Below is list of the provided handlers:
To configure, please specify the following:
transport:
http:
address: :8000
retry:
backoff: 100ms
timeout: 1s
attempts: 3
timeout: 10s
grpc:
address: :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
The crypto package provides sensible defaults for symmetric, asymmetric, hashing and randomness.
We rely on the awesome crypto.
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
This section outlines all utilities added for you troubleshooting abilities.
GET http://localhost:6060/debug/statsviz
Check out statsviz.
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.
GET http://localhost:6060/debug/fgprof?seconds=10
Check out fgprof.
GET http://localhost:6060/debug/psutil
Check out gopsutil.
To configure, please specify the following:
debug:
address: :6060
timeout: 10s
If you would like to enable TLS, do the following:
debug:
tls:
cert: path of cert
key: path of key
This section describes how to run and contribute to the project, if you are interested.
We favour what is defined in the Uber Go Style Guide.
Please setup the following:
To get yourself setup, please run:
git submodule sync
git submodule update --init
mkcert -install
make create-certs
make dep
As we rely on external services these need to be configured:
Please run:
make start
Please run:
make stop
To be able to test locally, please run:
make specs