deferred

README

go-deferred

defer handler creation like what?!?!?

package deferred asynchronously creates an HTTP handler by calling a function that may fail and retries in case of failure.

Example

// only return a http.Handler in some cases
func createLuckyHandler() (http.Handler, error) {
	num := rand.Intn(10)
	if num != 7 {
		return nil, fmt.Errorf("%d is not the lucky number", num)
	}
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("Lucky you!"))
	})
}

timeout, cancel := context.WithTimeout(context.Background(), time.Hour)
defer cancel()

// NewHandler returns instantly
h := deferred.NewHandler(
	// in case the context is cancelled the handler will stop buffering and fail permanently
	timeout,
	// in case no error is returned, the handler will stop buffering and use the returned handler
	createLuckyHandler,
	// optional settings
	deferred.WithNotify(err error) { // subscribe to errors
		fmt.Println("got error: ", err, ", trying again")
	},
	deferred.WithExponentialBackoff(time.Second), // retry after a second, then use exponential backoff
	deferred.WithTimeoutAfter(time.Second * 30), // buffered requests will timeout after 15 seconds
	deferred.WithFailedHandler(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		http.Error(w, "sorry, but i stopped trying", http.StatusServiceUnavailable)
	})),
)

http.Handle("/", h)

License

MIT © Frederik Ring

Documentation

Index

• Constants
• Variables
• func NewHandler(ctx context.Context, create func() (http.Handler, error), configs ...Config) http.Handler
• type Config
  • func WithExponentialBackoff(d time.Duration) Config
  • func WithFailedHandler(h http.Handler) Config
  • func WithNotify(n func(error)) Config
  • func WithRetryAfter(d time.Duration) Config
  • func WithTimeoutAfter(d time.Duration) Config

Constants

const (
	DefaultRetryAfter   = time.Second * 10
	DefaultTimeoutAfter = time.Second * 15
)

default values populating options objects

Variables

var (
	DefaultNotify        = func(error) {}
	DefaultFailedHandler = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		http.Error(w, "permanent error creating handler", http.StatusServiceUnavailable)
	})
)

default values populating options objects

Functions

func NewHandler

func NewHandler(ctx context.Context, create func() (http.Handler, error), configs ...Config) http.Handler

NewHandler returns a new http.Handler that will try to queue requests until handler creation succeeded. On a failed creation attempt the notify function will be called with the error returned by `create` if it is configured. In case the passed context is cancelled before a handler could be created, retrying will be terminated and the handler will permanently return 503 or use the behavior of a passed `FailedHandler` Config.

Types

type Config

type Config func(options) options

Config is a function that returns an updated options object when being passed another

func WithExponentialBackoff

func WithExponentialBackoff(d time.Duration) Config

WithExponentialBackoff returns a Config that will ensure the given duration is used for retrying handler creation with exponential delay

func WithFailedHandler

func WithFailedHandler(h http.Handler) Config

WithFailedHandler returns a Config that will ensure the given handler will be used when the creation has permanently failed

func WithNotify

func WithNotify(n func(error)) Config

WithNotify returns a Config that will ensure the given Notify func is called when handler creation fails

func WithRetryAfter

func WithRetryAfter(d time.Duration) Config

WithRetryAfter returns a Config that will ensure the given duration is used as the interval for retrying handler creation

func WithTimeoutAfter

func WithTimeoutAfter(d time.Duration) Config

WithTimeoutAfter returns a Config that will ensure the pending handler will timeout after the given duration