Skip to content

alexfalkowski/go-service

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Gopher CircleCI codecov Go Report Card Go Reference Stability: Active

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.

CLI

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.

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 - Read from an env variable called CONFIG. The env variable must be a configuration and we expect the format of extension:content, where extension is the supported kinds and content 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.

Environment

You can specify the environment of the service.

Environment Configuration

To configure, please specify the following:

environment: development

Compression

We support the following:

Encoders

We support the following:

Caching

The framework currently supports the following caching solutions from the awesome Cachego.

Compression Configuration

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

Feature

The framework supports OpenFeature.

Feature Configuration

To configure, please specify the following:

feature:
  address: localhost:9000
  retry:
    backoff: 100ms
    timeout: 1s
    attempts: 3
  timeout: 10s

Hooks

The framework supports Standard Webhooks.

Hooks Configuration

To configure, please specify the following:

hooks:
  secret: path to secret

ID

The framework supports the generation of ids. The following are supported:

ID Configuration

To configure, please specify the following:

id:
  kind: uuid | ksuid | nanoid | ulid | xid

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.

SQL 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

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:

  • /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

Telemetry is broken down in the following sections:

Logging

For logging we use slog.

Logging Configuration

We have multiple options for logging.

JSON

To configure, please specify the following:

telemetry:
  logger:
    kind: json
    level: info
Text

To configure, please specify the following:

telemetry:
  logger:
    kind: text
    level: info
Logger OTLP

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

Metrics

For metrics we support the following:

Metrics Configuration

Below is the configuration for each system.

Prometheus

To configure, please specify the following:

telemetry:
  metrics:
    kind: prometheus
Metrics OTLP

To configure, please specify the following:

telemetry:
  metrics:
    kind: otlp
    url: http://localhost:9009/otlp/v1/metrics
    headers:
      Authorization: path to key

Trace

For distributed tracing we support the following:

Trace Configuration

Below is the configuration for each system.

Trace OTLP

To configure, please specify the following:

telemetry:
  tracer:
    kind: otlp
    url: localhost:4318
    headers:
      Authorization: path to key

Telemetry Dependencies

Dependencies

Token

The framework allows you to define different token generators and verifiers.

Access

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.

JWT

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

Paseto

We use the awesome Paseto.

To configure, please specify the following:

token:
  kind: paseto
  paseto:
    sub: subject
    aud: audience
    iss: issuer
    exp: 1h

SSH

We use the awesome SSH.

Generation

To configure, please specify the following:

token:
  kind: ssh
  ssh:
    key:
      name: test
      private: path to key

Verification

To configure, please specify the following:

token:
  kind: ssh
  ssh:
    keys:
      - name: test
        public: path to key

Limiter

The framework allows you to define a limiter. This will be applied to the different transports.

The different kinds are:

Limiter 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:

Time Configuration

To configure, please specify the following:

time:
  kind: nts
  address: 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:

Transport Configuration

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

Transport Dependencies

Dependencies

Cryptography

The crypto package provides sensible defaults for symmetric, asymmetric, hashing and randomness.

We rely on the awesome crypto.

Cryptography 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

Cryptography Dependencies

Dependencies

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.

Debug Configuration

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

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.

Development 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

Development 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

Packages

No packages published

Contributors 4

  •  
  •  
  •  
  •  

Languages