panicguard

README

go-panicguard

Panic recovery utilities for Go. Run goroutines safely, convert panics to errors, and protect HTTP handlers from crashes.

Installation

go get github.com/philiprehberger/go-panicguard

Usage

import "github.com/philiprehberger/go-panicguard"

Safe goroutines

panicguard.Go(func() {
    // If this panics, the panic is recovered and the OnPanic hook is called.
    riskyWork()
})

Goroutine with error result

ch := panicguard.GoErr(func() error {
    return doWork()
})
if err := <-ch; err != nil {
    // err is either the returned error or a *panicguard.PanicError
    log.Println(err)
}

Deferred panic-to-error conversion

func handler() (err error) {
    defer func() {
        if e := panicguard.Recover(recover()); e != nil {
            err = e
        }
    }()
    riskyOperation()
    return nil
}

Global panic hook

panicguard.SetOnPanic(func(recovered any, stack []byte) {
    log.Printf("panic recovered: %v\n%s", recovered, stack)
})

HTTP middleware

mux := http.NewServeMux()
mux.HandleFunc("/", handler)
http.ListenAndServe(":8080", panicguard.Middleware(mux))

Custom recovery response

middleware := panicguard.MiddlewareWithHandler(func(w http.ResponseWriter, r *http.Request, recovered any) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusInternalServerError)
    fmt.Fprintf(w, `{"error":"%v"}`, recovered)
})
http.ListenAndServe(":8080", middleware(mux))

API

Function / Type	Description
PanicError	Wraps a recovered panic value with Value and Stack fields
PanicError.Error()	Returns "panic: {value}"
Go(fn)	Runs fn in a goroutine with panic recovery
GoErr(fn)	Runs fn in a goroutine, returns a channel with the error result or *PanicError
Recover(r)	Call in a deferred func with recover() to convert a panic into a *PanicError
SetOnPanic(fn)	Sets a global handler called on every recovered panic
Middleware(next)	HTTP middleware that recovers panics and returns 500
MiddlewareWithHandler(onPanic)	HTTP middleware with a custom recovery response handler

License

MIT

Documentation

Overview

Package panicguard provides panic recovery utilities for Go.

Index

• func Go(fn func())
• func GoErr(fn func() error) <-chan error
• func Middleware(next http.Handler) http.Handler
• func MiddlewareWithHandler(onPanic func(w http.ResponseWriter, r *http.Request, recovered any)) func(http.Handler) http.Handler
• func Recover(r any) error
• func SetOnPanic(fn func(recovered any, stack []byte))
• type PanicError
  • func (e *PanicError) Error() string

Functions

func Go

func Go(fn func())

Go runs fn in a new goroutine with panic recovery. If fn panics, the panic is recovered and the global OnPanic handler is called (if set). The panic is not propagated.

func GoErr

func GoErr(fn func() error) <-chan error

GoErr runs fn in a new goroutine and returns a buffered channel that will receive the result. If fn returns an error, it is sent on the channel. If fn panics, a *PanicError is sent instead. The channel is closed after the value is sent.

func Middleware

func Middleware(next http.Handler) http.Handler

Middleware returns an http.Handler that recovers from panics in the next handler. When a panic occurs, it writes a 500 Internal Server Error response and calls the global OnPanic hook if one is set.

func MiddlewareWithHandler

func MiddlewareWithHandler(onPanic func(w http.ResponseWriter, r *http.Request, recovered any)) func(http.Handler) http.Handler

MiddlewareWithHandler returns HTTP middleware that recovers from panics and delegates the response to the provided onPanic function. This allows callers to customize the error response (e.g., returning JSON, logging, etc.).

func Recover

func Recover(r any) error

Recover converts a recovered panic value into a *PanicError. It is meant to be used inside a deferred function alongside the built-in recover():

defer func() {
    if err := panicguard.Recover(recover()); err != nil {
        // handle err (*PanicError)
    }
}()

Returns nil if r is nil (no panic occurred).

func SetOnPanic

func SetOnPanic(fn func(recovered any, stack []byte))

SetOnPanic sets a global panic handler that is called whenever a panic is recovered by Go, GoErr, or the HTTP middleware. The handler receives the recovered value and the stack trace captured at the point of the panic. Pass nil to clear the handler.

Types

type PanicError

type PanicError struct {
	// Value is the value that was passed to panic().
	Value any
	// Stack is the raw stack trace captured via runtime/debug.Stack().
	Stack []byte
}

PanicError wraps a recovered panic value along with the stack trace captured at the point of the panic.

func (*PanicError) Error

func (e *PanicError) Error() string

Error returns a string representation of the panic in the format "panic: {value}".