exception.go

/*
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at https://mozilla.org/MPL/2.0/.
 */

// Package exception provides a lightweight exception model for Go.
//
// It supports attaching underlying causes, recording suppressed errors, storing
// recovered panic values, capturing stack traces, and attaching extras.
//
// Integration with zerolog is optional. It can be disabled with the `no_zerolog`
// build tag.
//
// Methods that return [Exception] may either modify the current exception in
// place or return a new exception instance. Callers should always use the
// returned value and must not assume that the original exception remains
// unchanged.
//
// Source code in this package is licensed under the Mozilla Public License 2.0
// (MPL-2.0).
package exception

// Exception defines a lightweight exception model for Go, providing mechanisms
// for chaining causes, tracking suppressed errors, storing recovered values,
// capturing stack traces, and attaching extras.
//
// Methods that return [Exception] may either modify the current exception in
// place or return a new exception instance. Callers should always use the
// returned value and must not assume that the original exception remains
// unchanged.
type Exception interface {
	// Error returns a string representation of this exception in the form of "Type:
	// Message"
	Error() string

	// GetType returns the type of this exception.
	GetType() string

	// GetMessage returns the message of this exception.
	GetMessage() string

	// SetMessage stores a message inside this exception.
	//
	// Note: This method may modify the current exception or return a new one. Always
	// use the returned [Exception].
	SetMessage(message string, parameters ...any) Exception

	// GetCause returns the list of underlying causes associated with this exception.
	// The slice may be empty if no causes have been specified.
	GetCause() []error

	// AddCause attaches one or more underlying causes to this exception. Causes are
	// typically used to represent the root errors that led to this exception being
	// raised.
	//
	// Note: This method may modify the current exception or return a new one. Always
	// use the returned [Exception].
	AddCause(errors ...error) Exception

	// GetSuppressed returns the list of suppressed errors that were intentionally
	// ignored or deferred while handling this exception. This can be useful when
	// multiple errors occur, but only one is chosen as the primary failure.
	GetSuppressed() []error

	// AddSuppressed attaches one or more suppressed errors to this exception.
	//
	// Note: This method may modify the current exception or return a new one. Always
	// use the returned [Exception].
	AddSuppressed(errors ...error) Exception

	// GetRecovered returns the value captured from a panic recovery, if any. It
	// returns nil if no value was recovered.
	GetRecovered() any

	// SetRecovered stores a recovered panic value inside this exception.
	//
	// Note: This method may modify the current exception or return a new one. Always
	// use the returned [Exception].
	SetRecovered(recovered any) Exception

	// GetStackTrace returns the stack trace captured for this exception, represented
	// as [StackFrames]. The result may be nil if no stack trace was filled.
	GetStackTrace() StackFrames

	// FillStackTrace captures the current call stack starting from the caller of
	// [FillStackTrace] itself and attaches it to this exception.
	//
	// The skip parameter controls how many additional stack frames are omitted. A
	// value of 0 includes the caller of [FillStackTrace], a value of 1 skips that
	// frame, and higher values skip more.
	//
	// Note: This method may modify the current exception or return a new one. Always
	// use the returned [Exception].
	FillStackTrace(skip int) Exception

	// GetExtras returns the additional metadata associated with this exception as a
	// key-value map.
	//
	// Extras can be used to attach arbitrary contextual information such as request
	// identifiers, user information, diagnostic values, or application-specific
	// state.
	//
	// The returned map may be nil if no extras have been set.
	GetExtras() map[string]any

	// SetExtras stores the additional metadata associated with this exception as a
	// key-value map.
	//
	// Extras can be used to attach arbitrary contextual information such as request
	// identifiers, user information, diagnostic values, or application-specific
	// state.
	//
	// Note: This method may modify the current exception or return a new one. Always
	// use the returned [Exception].
	SetExtras(extras map[string]any) Exception

	// GetExtra retrieves a single extra value associated with the given key.
	//
	// Extras can be used to attach arbitrary contextual information such as request
	// identifiers, user information, diagnostic values, or application-specific
	// state.
	//
	// The returned boolean reports whether the key exists.
	GetExtra(key string) (any, bool)

	// SetExtra stores an additional metadata value inside this exception under the
	// specified key.
	//
	// Extras can be used to attach arbitrary contextual information such as request
	// identifiers, user information, diagnostic values, or application-specific
	// state.
	//
	// If a value already exists for the key, it is replaced.
	//
	// Note: This method may modify the current exception or return a new one. Always
	// use the returned [Exception].
	SetExtra(key string, value any) Exception

	// Clone creates an independent copy of this [Exception] and returns it.
	//
	// After cloning, modifications to either [Exception] through its own methods do
	// not affect the other.
	//
	// Note: Referenced values are not deeply cloned and may still be shared.
	Clone() Exception

	__() // private
}