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/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() {
	core.SetupLogs()

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

	server := httpsrv.New(&http.Server{
		ReadTimeout: 10 * time.Second,
		Handler: http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
			w.WriteHeader(200)
			w.Write([]byte("hello world"))
		}),
	})

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

Documentation

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

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

Middlewares

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

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

Service Workers

These packages contain convenient service 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.

• core-redis: Libraries for connecting to, and working with a Redis store.
• core-sql: Libraries for connecting to, and working with an SQL database.

Tools

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

• jwtl: A command line tool to help generating JWTs during development.

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 structs, slices, and primitive types, originally forked from github.com/blockloop/scan
• LUSHDigital/uuid: A UUID package originally forked from github.com/gofrs/uuid & github.com/satori/go.uuid

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 SetupLogs()
• type Service
  • func NewService() *Service
  • func (s *Service) StartWorkers(ctx context.Context, workers ...ServiceWorker)
• type ServiceWorker

Examples

• NewService
• Service.StartWorkers

Functions

func SetupLogs

func SetupLogs()

SetupLogs will set up the appropriate log flags.

Types

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"`
}

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

func NewService

func NewService() *Service

NewService reads a service definition from the environment.

Example

package main

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

func main() {
	core.NewService()
}

func (*Service) StartWorkers

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

StartWorkers will start the given service workers and block block indefinitely.

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() {
	svc := core.NewService()
	svc.StartWorkers(ctx,
		grpcsrv.New(nil),
		httpsrv.NewDefault(handler),
		metricsrv.New(nil),
		keybroker.NewRSA(nil),
	)
}

type ServiceWorker

type ServiceWorker interface {
	// Run should be a blocking operation
	Run(context.Context, io.Writer) error
}

ServiceWorker represents the behaviour for running a service worker.