fw

README

Fw

A simple, unbiased application framework with sane defaults.

fw is a simple application framework for Go. Unlike most of the other frameworks, this one is not coupled to a single transport layer (HTTP, gRPC), in fact it does not make any assumptions about your application. It can be a daemon, a simple cron job, or an HTTP server, nearly anything.

On the other hand, it's bit opinionated in terms of some common application components:

• go-kit is used for logging
• emperror is used for error handling
• opentracing is used for application traces

That said, using these components in your application is optional.

Installation

Since this library uses Glide I recommend using it in your project as well.

$ glide get github.com/goph/fw

Usage

package main

import "github.com/goph/fw"

func main() {
    app := fw.NewApplication()
    defer app.Close()
    
    // your app logic
}

You can also take a look at some boilerplate code which relies on this framework.

History

When I first started to work with Go I was amazed by the standard library. (Almost) Everything I needed was already there. Of course not all of the tools were perfect, so I had to pull in some external libraries (logging, error handling, etc), but there was no need for any frameworks or complex configuration to build my applications.

Soon I realized that this "no framework" philosophy requires a lot of copy-pasting. So I created boilerplates to make copying easier. But it just didn't feel right either. It became clear that maintaining 5-6 applications still requires too much time.

So I went back to the table and came up with this library. Although it is a framework, I tried to build it in a way that supports easy extension. One could even just copy the whole thing.

Using this library one can avoid copying a lot of (unmodified) code. Furthermore, unlike the linked boilerplates the components in this library are fully tested.

License

The MIT License (MIT). Please see License File for more information.

Documentation

Index

• Variables
• func DefaultErrorHandler(a *Application)
• func DefaultLogger(a *Application)
• func DefaultTracer(a *Application)
• type Application
  • func NewApplication(opts ...ApplicationOption) *Application
  • func (a *Application) Close() error
  • func (a *Application) ErrorHandler() emperror.Handler
  • func (a *Application) Get(name string) (interface{}, bool)
  • func (a *Application) Logger() kitlog.Logger
  • func (a *Application) MustGet(name string) interface{}
  • func (a *Application) Run()
  • func (a *Application) Shutdown(ctx context.Context) error
  • func (a *Application) Start(ctx context.Context) (<-chan interface{}, error)
  • func (a *Application) Tracer() opentracing.Tracer
• type ApplicationOption
  • func Closer(c io.Closer) ApplicationOption
  • func Conditional(c bool, op ApplicationOption) ApplicationOption
  • func Entry(n string, e interface{}) ApplicationOption
  • func ErrorHandler(h emperror.Handler) ApplicationOption
  • func LifecycleHook(h Hook) ApplicationOption
  • func LifecycleTimeout(d time.Duration) ApplicationOption
  • func Logger(l kitlog.Logger) ApplicationOption
  • func OptionFunc(fn func(a *Application) ApplicationOption) ApplicationOption
  • func Options(opts ...ApplicationOption) ApplicationOption
  • func Tracer(t opentracing.Tracer) ApplicationOption
• type Hook

Variables

var SignalHook = Hook{
	OnStart: func(ctx context.Context, done chan<- interface{}) error {
		ch := make(chan os.Signal, 1)
		signal.Notify(ch, syscall.SIGINT, syscall.SIGTERM)

		go func() {
			done <- <-ch
			signal.Stop(ch)
		}()

		return nil
	},
}

SignalHook stops the application based on os signals.

Functions

func DefaultErrorHandler

func DefaultErrorHandler(a *Application)

DefaultErrorHandler is an ApplicationOption that sets the default error handler.

func DefaultLogger

func DefaultLogger(a *Application)

DefaultLogger is an ApplicationOption that sets the default logger.

func DefaultTracer

func DefaultTracer(a *Application)

DefaultTracer is an ApplicationOption that sets the default tracer.

Types

type Application

type Application struct {
	// contains filtered or unexported fields
}

Application collects all dependencies and exposes them in a single context.

func NewApplication

func NewApplication(opts ...ApplicationOption) *Application

func (*Application) Close

func (a *Application) Close() error

Close implements the common closer interface and closes the underlying resources. The resources are closed in a reversed order (just like how subsequent defer Close() calls would work). Errors are suppressed (again, like in case of defer calls).

func (*Application) ErrorHandler

func (a *Application) ErrorHandler() emperror.Handler

ErrorHandler returns the application error handler.

func (*Application) Get

func (a *Application) Get(name string) (interface{}, bool)

Get returns an entry from the application.

func (*Application) Logger

func (a *Application) Logger() kitlog.Logger

Logger returns the application logger.

func (*Application) MustGet

func (a *Application) MustGet(name string) interface{}

MustGet returns an entry from the application and panics if it's not found.

func (*Application) Run

func (a *Application) Run()

Run starts the application, blocks on the signals channel, and then gracefully shuts the application down. It uses DefaultTimeout for the start and stop timeouts.

See Start and Stop for application lifecycle details.

func (*Application) Shutdown

func (a *Application) Shutdown(ctx context.Context) error

Shutdown runs all PreShutdown, OnShutdown and PostShutdown hooks, returning immediately if it encounters an error.

func (*Application) Start

func (a *Application) Start(ctx context.Context) (<-chan interface{}, error)

Start runs all PreStart, OnStart and PostStart hooks, returning immediately if it encounters an error.

func (*Application) Tracer

func (a *Application) Tracer() opentracing.Tracer

Tracer returns the application tracer.

type ApplicationOption

type ApplicationOption func(a *Application)

ApplicationOption sets options in the Application.

func Closer

func Closer(c io.Closer) ApplicationOption

Closer returns an ApplicationOption that appends a closer to the Application's closer list.

func Conditional

func Conditional(c bool, op ApplicationOption) ApplicationOption

Conditional applies an option if the condition is true. This is useful to avoid using conditional logic when building the option list.

func Entry

func Entry(n string, e interface{}) ApplicationOption

Entry registers an arbitrary entry in the application.

func ErrorHandler

func ErrorHandler(h emperror.Handler) ApplicationOption

ErrorHandler returns an ApplicationOption that sets the error handler.

func LifecycleHook

func LifecycleHook(h Hook) ApplicationOption

LifecycleHook registers a lifecycle hook in the application.

func LifecycleTimeout

func LifecycleTimeout(d time.Duration) ApplicationOption

LifecycleTimeout sets the default lifecycle timeout for the application.

func Logger

func Logger(l kitlog.Logger) ApplicationOption

Logger returns an ApplicationOption that sets the logger.

func OptionFunc

func OptionFunc(fn func(a *Application) ApplicationOption) ApplicationOption

OptionFunc accepts a function which itself creates an ApplicationOption as well. It is useful when the inner ApplicationOption depends on the application itself (eg. requires the logger).

app := fw.NewApplication(
	fw.OptionFunc(func(a *fw.Application) fw.ApplicationOption {
		logger := a.Logger()

		return fw.ErrorHandler(
			error.NewHandler(
				error.Logger(logger),
			),
		)
	}),
)

func Options

func Options(opts ...ApplicationOption) ApplicationOption

Allows to bind two or more ApplicationOption instances together.

func Tracer

func Tracer(t opentracing.Tracer) ApplicationOption

Tracer returns an ApplicationOption that sets the tracer.

type Hook

type Hook struct {
	PreStart  func() error
	OnStart   func(ctx context.Context, done chan<- interface{}) error
	PostStart func() error

	PreShutdown  func() error
	OnShutdown   func(ctx context.Context) error
	PostShutdown func() error
}

Hook is a set of lifecycleHooks callbacks, either of which can be nil. They are called during the application lifecycleHooks.