catcher

README

Catcher

A package to gracefully handle crap software. From the creator of closer.

See example.

func main() {
    defer catcher.Catch(
        catcher.RecvWrite(os.Stderr, true),
    )

    if err := safeCall(); err != nil {
        log.Println("[ERR] safeCall failed with:", err)
    }

    suspiciousFunc()
}

// suspiciousFunc will definitely panic. Usually this kind of functions
// panic only on Saturdays or holidays, but for test simplicity this one
// will panic 100% of the time.
func suspiciousFunc() {
    panic("sorry pls")
}

Result:

$ go run main.go

caught error: catch me
main.go:21: [ERR] safeCall failed with: catch me
caught panic: sorry pls from suspiciousFunc

stacktrace: panic
/usr/local/go/src/runtime/asm_amd64.s:479 (0x4f4cc)
    call32: CALLFN(·call32, 32)
/usr/local/go/src/runtime/panic.go:458 (0x26fc3)
    gopanic: reflectcall(nil, unsafe.Pointer(d.fn), deferArgs(d), uint32(d.siz), uint32(d.siz))
/Users/xlab/Documents/dev/go/src/github.com/xlab/catcher/example/main.go:28 (0x22fd)
    suspiciousFunc: panic("sorry")
/Users/xlab/Documents/dev/go/src/github.com/xlab/catcher/example/main.go:24 (0x2186)
    main: suspiciousFunc()
/usr/local/go/src/runtime/proc.go:183 (0x28c74)
    main: main_main()
/usr/local/go/src/runtime/asm_amd64.s:2059 (0x51f31)
    goexit: BYTE    $0x90   // NOP

License

MIT

Documentation

Overview

Package catcher provides utilites to gracefully handle crap software.

Index

• func Catch(recv ...Receiver)
• func CatchWithContext(context, meta interface{}, recv ...Receiver)
• func RegisterNotifiers(fn ...NotifierFunc)
• func SetCallerOffset(n int)
• type Error
  • func (e Error) Error() string
• type NotifierFunc
• type Receiver
  • func RecvDie(ret int, onPanic ...bool) Receiver
  • func RecvError(err *error, useSimple ...bool) Receiver
  • func RecvLog(writeStack ...bool) Receiver
  • func RecvWrite(wr io.Writer, writeStack ...bool) Receiver

Examples

• Catch

Functions

func Catch

func Catch(recv ...Receiver)

Catch must be used together with defer to catch panics from suspicious functions. All listed receivers and all the global notifiers will be invoked with the error itself, function name and a stack trace.

Example

ExampleCatch shows how to treat suspicious funcs properly.

defer Catch( // if this example panics (oh sure it would), just output the
	// panic message and its stacktrace to the stderr.
	RecvWrite(os.Stderr, true),
)

// SafeCall is an example of a function that uses two receivers.
// First one will put the panic message into the error value;
// second one will yield the message to the stderr without the stracktrace.
SafeCall := func() (err error) {
	defer Catch(
		RecvError(&err),
		RecvWrite(os.Stderr),
	)

	suspiciousFunc()
	return
}

// treat suspiciousFunc like a normal func that may return an error
if err := SafeCall(); err != nil {
	log.Println("[ERR] SafeCall failed with:", err)
}

// don't be afraid to call this func anymore
suspiciousFunc()

func CatchWithContext

func CatchWithContext(context, meta interface{}, recv ...Receiver)

CatchWithContext must be used together with defer to catch panics from suspicious functions. All listed receivers and all the global notifiers will be invoked with the error itself, function name and a stack trace, along with the provided context and meta.

func RegisterNotifiers

func RegisterNotifiers(fn ...NotifierFunc)

RegisterNotifiers adds all listed notifiers to a global list, each of them would be invoked upon an error occurs.

func SetCallerOffset

func SetCallerOffset(n int)

SetCallerOffset allows to customize stacktrace reporting in case the catcher is wrapped. Default is 0. Setting to positive or negative will shift caller's stacktrace window up and down.

Types

type Error

type Error struct {
	Err     error
	Context interface{}
	Caller  string
	Stack   []byte
}

Error has additional context and stack that can be accessed outside receivers; by storing it to a variable using the RecvError receiver.

func (Error) Error

func (e Error) Error() string

type NotifierFunc

type NotifierFunc func(err error, rawData ...interface{}) error

NotifierFunc is a func that may be used as a global notifier (via RegisterNotifiers()).

type Receiver

type Receiver interface {
	RecvError(err error, context interface{}, caller string, stack []byte)
	RecvPanic(err error, context interface{}, caller string, stack []byte)
}

Receiver handles panics and errors thrown with a panic.

func RecvDie

func RecvDie(ret int, onPanic ...bool) Receiver

RecvDie forces app to exit with the provided exit code. If onPanic is set to true, the app will die only on wild panics. N.B. panic(errors.New(...)) is not a wild panic.

func RecvError

func RecvError(err *error, useSimple ...bool) Receiver

RecvError puts the error catched in the variable by pointer. If useSimple is set to true, the error would not contain anything except the message.

func RecvLog

func RecvLog(writeStack ...bool) Receiver

RecvLog logs the error caught using the standard logger. If writeStack is set to true, a stacktrace will be written too.

func RecvWrite

func RecvWrite(wr io.Writer, writeStack ...bool) Receiver

RecvWrite writes the error caught to the writer, presumably the os.Stderr. If writeStack is set to true, a stacktrace will be written too.