core

README

Core (Go)

A collection of packages for building a Go microservice on the LUSH platform.

Quick start

Below there's an example for how to get running quickly with a service using the LUSHDigital core package.

package main

import (
	"context"
	"net/http"
	"time"

	"github.com/LUSHDigital/core"
	"github.com/LUSHDigital/core/middleware/metricsmw"
	"github.com/LUSHDigital/core/workers/httpsrv"
	"github.com/LUSHDigital/core/workers/keybroker"
	"github.com/LUSHDigital/core/workers/metricsrv"
	"github.com/LUSHDigital/core/workers/readysrv"
)

var service = &core.Service{
	Name:    "example",
	Type:    "service",
	Version: "1.0.0",
}

func main() {
	metrics := metricsrv.New(nil)
	broker := keybroker.NewPublicRSA(nil)
	readiness := readysrv.New(nil, readysrv.Checks{
		"public_rsa_key": broker,
	})

	handler := metricsmw.MeasureRequests(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
		w.WriteHeader(200)
		w.Write([]byte("hello world"))
	}))

	server := httpsrv.New(&http.Server{
		ReadTimeout: 10 * time.Second,
		Handler:     handler,
	})

	service.MustRun(context.Background(),
		server,
		metrics,
		broker,
		readiness,
	)
}

Documentation

Documentation and examples are provided in README files in each package.

Core Concepts

These packages contain functionality for the core concepts of our services.

• core/auth
• core/env
• core/i18n
• core/middleware
• core/pagination
• core/rest
• core/test
• core/workers

Middlewares

These packages contain convenient middlewares for transport protocols like HTTP REST and gRPC.

• core/middleware/i18nmw
• core/middleware/metricsmw
• core/middleware/paginationmw
• core/middleware/tracingmw

Workers

These packages contain convenient workers things like network servers, background workers and message brokers.

• core/workers/grpcsrv
• core/workers/httpsrv
• core/workers/keybroker
• core/workers/metricsrv
• core/workers/readysrv

Plugins

There are a few libraries that can be used in conjunction with the core library containing their own service workers, ready checks and/or middlewares.

• LUSHDigital/core-redis: Packages for connecting to, and working with a Redis store.
• LUSHDigital/core-sql: Packages for connecting to, and working with an SQL database.
• LUSHDigital/core-lush: Packages specific to the LUSH platform.

Tools

There are a few tools that can be used with projects that use the core library.

• LUSHDigital/jwtl: A command line tool to help generating JWTs during development.
• LUSHDigital/core-mage: A library for the mage build tool including convenient build targets used in conjunction with a project using this core library.

Recommended Libraries

Some libraries have been designed to work together with the core library and some are even dependencies. Consider using these if you need extended functionality for certain things.

• LUSHDigital/scan: Scan database/sql rows directly to a struct, slice, or primitive any type. Originally forked from github.com/blockloop/scan
• LUSHDigital/uuid: A UUID package originally forked from github.com/gofrs/uuid & github.com/satori/go.uuid
• LUSHDigital/spew: A pretty-printer package originally forked from github.com/davecgh/go-spew/spew

Contributors

• Zee Philip Vieira: Author & Maintainer
• Ben Cable: Author & Maintainer
• Zach Jones: Code
• Dan P: Code
• Oliver Pauffley: Code
• Cerys Evans: Design

Documentation

Overview

Package core consists of a set of packages which are used in writing micro-service applications.

Each package defines conventional ways of handling common tasks, as well as a suite of tests to verify their behaviour.

Index

• func ContextWithSignals(ctx context.Context) (context.Context, <-chan int, context.CancelFunc)
• func SetupLogs()
• func WaitWithTimeout(delta int, cancelled <-chan int, timeout time.Duration) (<-chan int, <-chan int, func())
• type Halter
• type Runner
• type Service
  • func NewService(name, kind string) *Service
  • func (s *Service) MustRun(ctx context.Context, workers ...Worker)
  • func (s *Service) Run(ctx context.Context, workers ...Worker) int
  • func (s *Service) StartWorkers(ctx context.Context, workers ...Worker)
• type Worker

Examples

• NewService
• Service.StartWorkers

Functions

func ContextWithSignals

func ContextWithSignals(ctx context.Context) (context.Context, <-chan int, context.CancelFunc)

ContextWithSignals creates a new instance of signal context.

func SetupLogs

func SetupLogs()

SetupLogs will set up the appropriate log flags. DEPRECATED: Import github.com/LUSHDigital/core-lush/lushlog as a side-effect.

func WaitWithTimeout

func WaitWithTimeout(delta int, cancelled <-chan int, timeout time.Duration) (<-chan int, <-chan int, func())

WaitWithTimeout will wait for a number of pieces of work has finished and send a message on the completed channel.

Types

type Halter

type Halter interface {
	// Halt should tell the worker to stop doing work.
	Halt(context.Context) error
}

Halter represents the behaviour for stopping a service worker.

type Runner

type Runner interface {
	// Run should run start processing the worker and be a blocking operation.
	Run(context.Context) error
}

Runner represents the behaviour for running a service worker.

type Service

type Service struct {
	// Name represents the name of the service, typically the same as the github repository.
	Name string `json:"name"`
	// Type represents the type of the service, eg. service or aggregator.
	Type string `json:"type"`
	// Version represents the latest version or SVC tag of the service.
	Version string `json:"version"`
	// Revision represents the SVC revision or commit hash of the service.
	Revision string `json:"revision"`

	// GracePeriod represents the duration workers have to clean up before the process gets killed.
	GracePeriod time.Duration `json:"grace_period"`
}

Service represents the minimal information required to define a working service.

func NewService

func NewService(name, kind string) *Service

NewService creates a new service based on

Example

package main

import (
	"github.com/LUSHDigital/core"
)

func main() {
	core.NewService("example", "service")
}

func (*Service) MustRun

func (s *Service) MustRun(ctx context.Context, workers ...Worker)

MustRun will start the given service workers and block block indefinitely, until interupted. The process with an appropriate status code.

func (*Service) Run

func (s *Service) Run(ctx context.Context, workers ...Worker) int

Run will start the given service workers and block block indefinitely, until interupted.

func (*Service) StartWorkers

func (s *Service) StartWorkers(ctx context.Context, workers ...Worker)

StartWorkers will start the given service workers and block block indefinitely, until interupted. The process with an appropriate status code. DEPRECATED: Use MustRun in favour of StartWorkers.

Example

package main

import (
	"context"
	"net/http"

	"github.com/LUSHDigital/core"
	"github.com/LUSHDigital/core/workers/grpcsrv"
	"github.com/LUSHDigital/core/workers/httpsrv"
	"github.com/LUSHDigital/core/workers/keybroker"
	"github.com/LUSHDigital/core/workers/metricsrv"
)

var (
	ctx     context.Context
	handler http.Handler
)

func main() {
	service := core.NewService("example", "service")
	service.MustRun(ctx,
		grpcsrv.New(nil),
		httpsrv.NewDefault(handler),
		metricsrv.New(nil),
		keybroker.NewRSA(nil),
	)
}

type Worker

type Worker interface {
	Runner
	Halter
}

Worker represents the behaviour for a service worker.