lu

README

lu

What is it?

lu is an application framework

Documentation

Overview

Package lu is an application framework for Luno microservices

Index

• func ErrGroupWait(eg *errgroup.Group) <-chan error
• func SyncGroupWait(wg *sync.WaitGroup) <-chan struct{}
• func Wait(ctx context.Context, cl clock.Clock, d time.Duration) error
• func WaitFor[T any](ctx context.Context, ch <-chan T) (T, error)
• func WaitUntil(ctx context.Context, cl clock.Clock, t time.Time) error
• type App
  • func NoApp() *App
  • func (a *App) AddProcess(processes ...Process)
  • func (a *App) GetProcesses() []Process
  • func (a *App) Launch(ctx context.Context) error
  • func (a *App) OnShutdown(f ProcessFunc, opts ...HookOption)
  • func (a *App) OnStartUp(f ProcessFunc, opts ...HookOption)
  • func (a *App) Run() int
  • func (a *App) RunningProcesses() []string
  • func (a *App) Shutdown() error
  • func (a *App) WaitForShutdown() <-chan struct{}
• type AppContext
  • func NewAppContext(ctx context.Context) AppContext
  • func (c AppContext) Stop()
• type Event
• type EventType
  • func (i EventType) String() string
• type HookOption
  • func WithHookName(s string) HookOption
  • func WithHookPriority(p HookPriority) HookOption
• type HookPriority
• type OnEvent
• type Process
• type ProcessFunc
  • func WrapProcessFunc[P Processable](p P) ProcessFunc
• type Processable

Functions

func ErrGroupWait

func ErrGroupWait(eg *errgroup.Group) <-chan error

func SyncGroupWait

func SyncGroupWait(wg *sync.WaitGroup) <-chan struct{}

SyncGroupWait wait for the wait group (websocket connections) to finalize

func Wait

func Wait(ctx context.Context, cl clock.Clock, d time.Duration) error

Wait is a cancellable wait, it will return either when d has passed or ctx is cancelled. It will return an error if cancelled early.

func WaitFor

func WaitFor[T any](ctx context.Context, ch <-chan T) (T, error)

func WaitUntil

func WaitUntil(ctx context.Context, cl clock.Clock, t time.Time) error

Types

type App

type App struct {
	// StartupTimeout is the deadline for running the start-up hooks and starting all the Processes
	// Defaults to 15 seconds.
	StartupTimeout time.Duration

	// ShutdownTimeout is the deadline for stopping all the app Processes and
	// running the shutdown hooks.
	// Defaults to 15 seconds.
	ShutdownTimeout time.Duration

	// OnEvent will be called for every lifecycle event in the app. See EventType for details.
	OnEvent OnEvent

	// UseProcessFile will write a file at /tmp/lu.pid whilst the app is still running.
	// The file will be removed after a graceful shutdown.
	UseProcessFile bool

	// OnShutdownErr is called after failing to shut down cleanly.
	// You can use this hook to change the error or do last minute reporting.
	// This hook is only called when using Run not when using Shutdown
	OnShutdownErr func(ctx context.Context, err error) error
	// contains filtered or unexported fields
}

App will manage the lifecycle of the service. Emitting events for each stage of the application.

func NoApp

func NoApp() *App

NoApp returns a nil app. It can be used when you call a function that accepts a *App, but there's no lu app in scope. f(lu.NoApp()) reads more clearly than f(nil).

func (*App) AddProcess

func (a *App) AddProcess(processes ...Process)

AddProcess adds a Process that is started in parallel after start up. If any Process finish with an error, then the application will be stopped.

func (*App) GetProcesses

func (a *App) GetProcesses() []Process

GetProcesses returns all the configured processes for the App

func (*App) Launch

func (a *App) Launch(ctx context.Context) error

Launch will run all the startup hooks and launch all the processes. If any hook returns an error, we will return early, processes will not be started. ctx will be used for startup and also the main application context. If the hooks take longer than StartupTimeout then launch will return a deadline exceeded error.

func (*App) OnShutdown

func (a *App) OnShutdown(f ProcessFunc, opts ...HookOption)

OnShutdown will call f just before the application terminates Use this to close database connections or release resources

func (*App) OnStartUp

func (a *App) OnStartUp(f ProcessFunc, opts ...HookOption)

OnStartUp will call f before the app starts working

func (*App) Run

func (a *App) Run() int

Run will start the App, running the startup Hooks, then the Processes. It will wait for any signals before shutting down first the Processes then the shutdown Hooks. This behaviour can be customised by using Launch, WaitForShutdown, and Shutdown.

func (*App) RunningProcesses

func (a *App) RunningProcesses() []string

func (*App) Shutdown

func (a *App) Shutdown() error

Shutdown will synchronously stop all the resources running in the app.

func (*App) WaitForShutdown

func (a *App) WaitForShutdown() <-chan struct{}

WaitForShutdown returns a channel that waits for the application to be cancelled. Note the application has not finished terminating when this channel is closed. Shutdown should be called after waiting on the channel from this function.

type AppContext

type AppContext struct {

	// AppContext should be used for running the application.
	// When it's cancelled, the application should stop running all processes.
	AppContext context.Context

	// TerminationContext should be used for the execution of application.
	// When it's cancelled the application binary should terminate.
	// AppContext will be cancelled with this context as well.
	TerminationContext context.Context
	// contains filtered or unexported fields
}

AppContext manages two contexts for running an app. It responds to different signals by cancelling one or both of these contexts. This behaviour allows us to do graceful shutdown in kubernetes using a stop script. If the application terminates before the stop script finishes then we get an error event from Kubernetes, so we need to be able to shut the application down using one signal, then exit the stop script and let Kubernetes send another signal to do the final termination. See this for more details on the hook behaviour https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/

For SIGINT and SIGTERM, we will cancel both contexts, the application should finish all processes and call os.Exit

For SIGQUIT, we cancel just the AppContext, the application should shut down all processes and wait for termination.

func NewAppContext

func NewAppContext(ctx context.Context) AppContext

func (AppContext) Stop

func (c AppContext) Stop()

type Event

type Event struct {
	Type EventType
	Name string
}

type EventType

type EventType int

const (
	Unknown        EventType = iota
	AppStartup               // First event, emitted right at the start
	PreHookStart             // Emitted just before running each Hook.Start
	PostHookStart            // Emitted just after completing a Hook.Start
	AppRunning               // Emitted after starting every process
	ProcessStart             // Emitted before starting to run a Process
	ProcessEnd               // Emitted when a Process terminates
	AppTerminating           // Emitted when the application starts termination
	PreHookStop              // Emitted before running each Hook.Stop
	PostHookStop             // Emitted after running each Hook.Stop
	AppTerminated            // Emitted before calling os.Exit
)

func (EventType) String

func (i EventType) String() string

type HookOption

type HookOption func(*hook)

func WithHookName

func WithHookName(s string) HookOption

WithHookName is used for logging so each Hook can be identified

func WithHookPriority

func WithHookPriority(p HookPriority) HookOption

WithHookPriority controls the order in which hooks are run, the lower the value of p the earlier it will be run (compared to other hooks) The default priority is 0, negative priorities will be run before positive ones

type HookPriority

type HookPriority int

const (
	HookPriorityFirst   HookPriority = -100
	HookPriorityDefault HookPriority = 0
	HookPriorityLast    HookPriority = 100
)

type OnEvent

type OnEvent func(context.Context, Event)

type Process

type Process struct {

	// Name is used for logging lifecycle events with the Process
	Name string
	// Run takes a context, if that context is canceled then the ProcessFunc
	// should return as soon as possible
	// If Run returns an error, the application will begin the shutdown procedure
	Run ProcessFunc
	// Shutdown will be called to terminate the Process
	// prior to cancelling the Run context.
	// This is for Processes where synchronous shutdown is necessary
	Shutdown func(ctx context.Context) error
	// contains filtered or unexported fields
}

Process will be a long-running part of the application which, if/when it errors, should bring the application down with it. It takes a context, if that context is canceled then the Process should return as soon as possible.

type ProcessFunc

type ProcessFunc func(ctx context.Context) error

ProcessFunc is a core process. See Process.Run for more details

func WrapProcessFunc

func WrapProcessFunc[P Processable](p P) ProcessFunc

WrapProcessFunc helper method to generate a ProcessFunc from an interface implementing the Processable methods

type Processable

type Processable interface {
	func() | func(ctx context.Context) | func() error
}