zen/core/zerr/error.go

package zerr

import (
	"context"
	"log/slog"
	"time"

	"connectrpc.com/connect"
	"gitlab.bareksa.com/backend/zen/core/zoptions"
)

type Error interface {
	error
	// LogValue returns log fields to be consumed by logger.
	LogValue() slog.Value
	// LogRecord returns log records to be consumed by logger.
	LogRecord() slog.Record

	// Code sets error code.
	Code(code connect.Code) Error
	GetCode() connect.Code

	// Message sets error message. It uses fmt.Sprintf to format the message.
	Message(msg string, args ...any) Error
	GetMessage() string

	PublicMessage(msg string, args ...any) Error
	GetPublicMessage() string

	Caller(pc uintptr) Error
	GetCaller() uintptr

	// Details sets error details. It's a key-value pair where the odd index is the key and the even index is the value.
	//
	// Invalid key-value pair number and format will cause the misplaced value to be paired up with "!BADKEY".
	//
	// Example:
	//
	//    err.Details(
	//      "key1", 12345,
	//      "key2", float64(12345.67),
	//    )
	Details(fields ...any) Error
	GetDetails() []any

	// Time sets the error time.
	//
	// Time is already set to current when the error is created or wrapped,
	// so this method is only useful when you want to set a different time.
	Time(t time.Time) Error
	GetTime() time.Time

	// ID sets the error ID.
	//
	// ID is used to identify the error. Used by Zen to consider if an error is the same as another.
	//
	// If unset, the ID will be automatically generated depending
	// on the backend logging and notification.
	ID(s string, args ...any) Error
	GetID() string

	// Join appends given errors to this zerr.Error.
	//
	// Join discards nil errors.
	//
	// When searching for Code, Message, PublicMessage, etc,
	// only the first error containing valid values will be used.
	//
	// The searching method is depth-first.
	//
	// It's undefined behavior to call Join when another thread calls
	// .Sequence().Iter() on this error.
	Join(errs ...error) Error

	// Log logs the error to stderr.
	//
	// Format will be pretty if current runtime is run in interactive
	// environment (TTY is detected), e.g. running inside terminal via `go run` command.
	//
	// Format will be JSON if current runtime does not have TTY, e.g.
	// running inside Docker container, Kubernetes pod, or any non-interactive environment
	// like VSCode debugger.
	Log(ctx context.Context) Error

	// Notify sends the error to the zen Server
	// which will then handle the error and create reports.
	Notify(ctx context.Context, opts ...zoptions.NotifyOption) Error

	// Sequence returns the state of the error sequence.
	//
	// Sequence must not be nil.
	Sequence() Sequence

	// IsMulti returns true if the error is a multiple error.
	IsMulti() bool

	// Resolve returns error (self) if all the errors
	// are valid (not nil) and Error contains at least one error
	// wrapped.
	Resolve() error
}