utils

Documentation

Index

• func GenerateInt64ID() int64
• func TokenURIFromAccount(account string) string
• func WithFmtMsg(f func(err any) string) recoveryOption
• func WithHandledConditions(conditions HandledConditions) recoveryOption
• func WithHandlers(handlers ...RecoveryHandler) recoveryOption
• func WithHandlingCriteria(criteria func(err any) bool) recoveryOption
• func WithHttpError(code int) recoveryOption
• func WithLogOutput(l func(v ...any)) recoveryOption
• func WithNotification(notify func(msg string) error) recoveryOption
• type HandledConditions
• type RecoverableServeMux
  • func NewRecoverableServeMux(handle RecoveryHandler) *RecoverableServeMux
  • func (m *RecoverableServeMux) Handle(pattern string, handler http.Handler)
  • func (m *RecoverableServeMux) HandleFunc(pattern string, handler func(http.ResponseWriter, *http.Request))
  • func (m *RecoverableServeMux) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type RecoveryHandler
  • func NewConfigurableRecoveryHandler(opts ...recoveryOption) RecoveryHandler

Functions

func GenerateInt64ID

func GenerateInt64ID() int64

GenerateInt64ID generates a 10 digit int64 value which can be used as an ID in many datastore types.

NOTE: the generated ID can be cast to an int32 if required.

func TokenURIFromAccount

func TokenURIFromAccount(account string) string

TokenURIFromAccount forms a Google Cloud Storage URI for a YouTube token based on the provided account. If the account is empty, it's assumed that the legacy token is being used. Otherwise, the account is used to form the URI. This means we can have tokens stored for different YouTube accounts. The URI is of the form: gs://ausocean/<account>.youtube.token.json e.g. gs://ausocean/social@ausocean.org.youtube.token.json

func WithFmtMsg

func WithFmtMsg(f func(err any) string) recoveryOption

WithFmtMsg allows the caller to specify a function to format the panic message. By default, the panic message is formatted as "panic: <panic>, stack: <stack>". This msg is used for logging and notification.

func WithHandledConditions

func WithHandledConditions(conditions HandledConditions) recoveryOption

WithHandledConditions allows the caller to specify which conditions should be considered as handled. By default, all conditions are considered handled.

func WithHandlers

func WithHandlers(handlers ...RecoveryHandler) recoveryOption

WithHandlers allows the caller to specify one or more handlers to be called after logging, notification and returning an HTTP error. These handlers are are called in the order they are provided. If a handler returns true, the panic is considered handled and no further handlers are called. By default, no handlers are called.

func WithHandlingCriteria

func WithHandlingCriteria(criteria func(err any) bool) recoveryOption

WithHandlingCriteria allow the caller to specify a function that determines whether the panic should be handled by this handler. If the function returns false, the panic will not be handled by this handler. By default, all panics are handled.

func WithHttpError

func WithHttpError(code int) recoveryOption

WithHttpError allows the caller to specify an HTTP error code to return when a panic occurs. By default, no HTTP error is returned.

func WithLogOutput

func WithLogOutput(l func(v ...any)) recoveryOption

WithLogOutput allows the caller to specify a function to output log messages. By default, no log output is performed.

func WithNotification

func WithNotification(notify func(msg string) error) recoveryOption

WithNotification allows the caller to specify a function to send a notification e.g. email, SMS, etc. to alert of a panic. The function should return an error if the notification could not be sent. By default, no notification is sent.

Types

type HandledConditions

type HandledConditions struct {
	HandledOnLog          bool
	HandledOnNotification bool
	HandledOnHttpError    bool
}

HandledConditions specifies which conditions should be considered to have handled a panic.

type RecoverableServeMux

type RecoverableServeMux struct {
	*http.ServeMux
	// contains filtered or unexported fields
}

RecoverableServeMux extends the default http.ServeMux and accepts a callback function to be called in case of handler panic recovery.

func NewRecoverableServeMux

func NewRecoverableServeMux(handle RecoveryHandler) *RecoverableServeMux

NewRecoverableServeMux creates a new RecoverableServeMux. recover is the callback function to be called in case of handler panic recovery.

func (*RecoverableServeMux) Handle

func (m *RecoverableServeMux) Handle(pattern string, handler http.Handler)

Handle registers the handler for the given pattern.

func (*RecoverableServeMux) HandleFunc

func (m *RecoverableServeMux) HandleFunc(pattern string, handler func(http.ResponseWriter, *http.Request))

HandleFunc registers the handler function for the given pattern.

func (*RecoverableServeMux) ServeHTTP

func (m *RecoverableServeMux) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP applies the recovery middleware and serves the HTTP request.

type RecoveryHandler

type RecoveryHandler func(w http.ResponseWriter, err any) bool

RecoveryHandler is a function that handles a panic. It is called with the http.ResponseWriter and the panic value. If the panic is handled, the function should return true, otherwise false.

func NewConfigurableRecoveryHandler

func NewConfigurableRecoveryHandler(opts ...recoveryOption) RecoveryHandler

NewConfigurableRecoveryHandler provides a RecoveryHandler that can be configured with various options. It is capable of performing multiple actions when a panic occurs, such as logging, sending notifications, returning HTTP errors and calling further handlers. This means this factory can be used "nested" if required.

An example with the RecoverableServiceMux to create a handler that has common logging, notification and httpError, but then specific handlers for certain panics:

mux := utils.NewRecoverableServeMux(

utils.NewConfigurableRecoveryHandler(
	utils.WithHandledConditions(utils.HandledConditions{HandledOnNotification: true}),
	utils.WithLogOutput(log.Println),
	utils.WithNotification(func(msg string) error { return sendPanicNotification(publicKey, privateKey, msg) }),
	utils.WithHttpError(http.StatusInternalServerError),
	utils.WithHandlers(
		panicType1Handler,
		panicType2Handler,
		panicType3Handler
	),
),

)

or we can have different logging/notification for different panics using a nested style of handler construction. The idea is that we may have different panics with different levels of severity and we might want to perform different actions based on this.

mux := utils.NewRecoverableServeMux(

utils.NewConfigurableRecoveryHandler(
	utils.WithHandlers(
		utils.NewConfigurableRecoveryHandler(
			utils.WithHandlingCriteria(func(err any) bool { /* return true for panic 1 */ }),
			utils.WithLogOutput(panicType1Log),
		),
		utils.NewConfigurableRecoveryHandler(
			utils.WithHandlingCriteria(func(err any) bool { /* return true for panic 2 */ }),
			utils.WithNotification(panicType2Notifier),
		),
		utils.NewConfigurableRecoveryHandler(
			utils.WithHandlingCriteria(func(err any) bool { /* return true for panic 3 */ }),
			utils.WithHandlers(panicType3Handler),
		),
	),
),

)