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 Cobra. Each service has the following commands (you can add more):
Server- This will provide your server needs.Client- This will provide your client needs.
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_FILE- Read from an env variable calledCONFIG_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 ofextension:ENV_VARIABLE, where extension is the supported kinds andENV_VARIABLEcontains 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.
You can specify the environment of the service.
To configure, please specify the following:
environment: developmentWe support the following:
We support the following:
The framework currently supports the following caching solutions:
To configure, please specify the following:
cache:
redis:
compressor: snappy
encoder: proto
addresses:
server: localhost:6379
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: 10sThe framework supports Standard Webhooks.
To configure, please specify the following:
hooks:
secret: path to secretWe 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:
/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 is broken down in the following sections:
For logging we use Uber Zap.
To configure, please specify the following:
telemetry:
logger:
level: infoFor metrics we support the following:
Below is the configuration for each system.
To configure, please specify the following:
telemetry:
metrics:
kind: prometheusTo configure, please specify the following:
telemetry:
metrics:
kind: otlp
url: http://localhost:9009/otlp/v1/metrics
headers:
Authorization: path to keyFor 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. This is left up to you!
We recommend that you look at better auth strategies, such as:
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: 1sThe framework allows you use network time services. We use:
To configure, please specify the following:
time:
kind: nts
address: time.cloudflare.comThe 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 - This is achieved with http mux. We have an 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: 10sIf 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 following libraries:
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/statsvizCheck 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/traceCheck out pprof.
GET http://localhost:6060/debug/fgprof?seconds=10Check out fgprof.
GET http://localhost:6060/debug/psutilCheck out gopsutil.
To configure, please specify the following:
debug:
address: :6060
timeout: 10sIf you would like to enable TLS, do the following:
debug:
tls:
cert: path of cert
key: path of keyThis 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 depAs we rely on external services these need to be configured:
Please run:
make startPlease run:
make stopTo be able to test locally, please run:
make specs