error_builder.go

package tower

import (
	"context"
	"fmt"
	"time"
)

/*
ErrorBuilder is an interface to create customizable error.

ErrorBuilder by itself is not an error type. You have to call .Freeze() method to create proper Error type.
*/
type ErrorBuilder interface {
	/*
		Sets the error code for this error.
		This is used to identify the error type and how towerhttp will interact with this error.

		The default implementation for Tower handles code like this:

		The default value, if anything in the error implements CodeHint interface,
		use the outermost CodeHint implementer, otherwise fallsback to 500.

		`tower.Error` that is generated by tower implements CodeHinter interface,
		and thus if the error is wrapped again, the default code for this error will be the code of the wrapped `tower.Error`.

		Example:

			if err != nil {
				return tower.Wrap(err).Code(500).Freeze()
			}
	*/
	Code(i int) ErrorBuilder

	/*
		Overrides the error message for this error.

		In built in implementation, If args are supplied, fmt.Sprintf will be called with s as base string.
	*/
	Message(s string, args ...any) ErrorBuilder

	/*
		Sets the origin error for ErrorBuilder. Very unlikely to need to set this because tower.Wrap already wraps the error.
		But the api is available to set the origin error.
	*/
	Error(err error) ErrorBuilder

	/*
		Sets additional data that will enrich how the error will look.

		`tower.Fields` is a type that is well integrated with built-in Messengers.
		Using this type as Context value will have the performance more optimized when being marshaled
		or provides additional quality of life improvements without having to implement those features
		yourself. Use `tower.F` as alias for this type.

		In built-in implementation, additional call to .Context() will make additional index, not replacing what you already set.

		Example:

			tower.Wrap(err).Code(400).Context(tower.F{"foo": "bar"}).Freeze()
	*/
	Context(ctx ...any) ErrorBuilder

	/*
		Sets the key for this error. This is how Messenger will use to identify if an error is the same as previous or not.

		In tower's built-in implementation, by default, no key is set.

		Usually by not setting the key, The Messenger will generate their own.

		In built in implementation, If args are supplied, fmt.Sprintf will be called with key as base string.
	*/
	Key(key string, args ...any) ErrorBuilder

	/*
		Sets the caller for this error.

		In tower's built-in implementation, by default, the caller is the location where you call `tower.Wrap` or `tower.WrapFreeze`
	*/
	Caller(c Caller) ErrorBuilder

	/*
		Sets the level for this error.

		In tower's built-in implementation, this defaults to ErrorLevel if not set.
	*/
	Level(lvl Level) ErrorBuilder

	/*
		Sets the time for this error.

		In tower's built-in implementation, this is already set to when tower.Wrap is called.
	*/
	Time(t time.Time) ErrorBuilder

	/*
		Freeze this ErrorBuilder, preventing further mutations and set this ErrorBuilder into proper error.

		The returned Error is safe for multithreaded usage because of its immutable nature.
	*/
	Freeze() Error

	/*
		Logs this error. Implicitly calls .Freeze() on this ErrorBuilder.
	*/
	Log(ctx context.Context) Error
	/*
		Notifies this error to Messengers. Implicitly calls .Freeze() on this ErrorBuilder.
	*/
	Notify(ctx context.Context, opts ...MessageOption) Error
}

type errorBuilder struct {
	code    int
	message string
	caller  Caller
	context []any
	key     string
	level   Level
	origin  error
	tower   *Tower
	time    time.Time
}

func (e *errorBuilder) Level(lvl Level) ErrorBuilder {
	e.level = lvl
	return e
}

func (e *errorBuilder) Caller(c Caller) ErrorBuilder {
	e.caller = c
	return e
}

func (e *errorBuilder) Code(i int) ErrorBuilder {
	e.code = i
	return e
}

func (e *errorBuilder) Error(err error) ErrorBuilder {
	e.origin = err
	return e
}

func (e *errorBuilder) Message(s string, args ...any) ErrorBuilder {
	if len(args) > 0 {
		e.message = fmt.Sprintf(s, args...)
	} else {
		e.message = s
	}
	return e
}

func (e *errorBuilder) Context(ctx ...any) ErrorBuilder {
	e.context = append(e.context, ctx...)
	return e
}

func (e *errorBuilder) Key(key string, args ...any) ErrorBuilder {
	if len(args) > 0 {
		e.key = fmt.Sprintf(key, args...)
	} else {
		e.key = key
	}
	return e
}

func (e *errorBuilder) Time(t time.Time) ErrorBuilder {
	e.time = t
	return e
}

func (e *errorBuilder) Freeze() Error {
	node := &ErrorNode{inner: e}
	if child, ok := e.origin.(*ErrorNode); ok {
		node.next = child
		child.prev = node
	}
	return node
}

func (e *errorBuilder) Log(ctx context.Context) Error {
	return e.Freeze().Log(ctx)
}

func (e *errorBuilder) Notify(ctx context.Context, opts ...MessageOption) Error {
	return e.Freeze().Notify(ctx, opts...)
}