errors.go

// Package ewrap provides enhanced error handling capabilities with stack traces,
// error wrapping, custom error types, and logging integration.
package ewrap

import (
	"errors"
	"fmt"
	"maps"
	"runtime"
	"strings"
	"sync"

	"github.com/hyp3rd/ewrap/internal/logger"
)

const (
	baseLogDataSize = 4 // error, msg, stack, and potentially cause
	runtimeCallers  = 3
)

// Error represents a custom error type with stack trace and metadata.
type Error struct {
	msg      string
	cause    error
	stack    []uintptr
	metadata map[string]any
	logger   logger.Logger
	observer Observer
	mu       sync.RWMutex // Protects metadata, logger, and observer
}

// Option defines the signature for configuration options.
type Option func(*Error)

// WithLogger sets a logger for the error.
func WithLogger(log logger.Logger) Option {
	return func(err *Error) {
		err.mu.Lock()
		err.logger = log
		err.mu.Unlock()

		// Log error creation if logger is available
		if log != nil {
			log.Debug("error created",
				"message", err.msg,
				"stack", err.Stack(),
			)
		}
	}
}

// WithObserver sets an observer for the error.
func WithObserver(observer Observer) Option {
	return func(err *Error) {
		err.mu.Lock()
		err.observer = observer
		err.mu.Unlock()
	}
}

// New creates a new Error with a stack trace and applies the provided options.
func New(msg string, opts ...Option) *Error {
	err := &Error{
		msg:      msg,
		stack:    CaptureStack(),
		metadata: make(map[string]any),
	}

	for _, opt := range opts {
		opt(err)
	}

	return err
}

// Newf creates a new Error with a formatted message and applies the provided options.
func Newf(format string, args ...any) *Error {
	return New(fmt.Sprintf(format, args...))
}

// Wrap wraps an existing error with additional context and stack trace.
func Wrap(err error, msg string, opts ...Option) *Error {
	if err == nil {
		return nil
	}

	var (
		stack      []uintptr
		metadata   map[string]any
		observer   Observer
		log        logger.Logger
		wrappedErr *Error
	)
	// If the error is already wrapped, preserve its stack trace and metadata
	if errors.As(err, &wrappedErr) {
		wrappedErr.mu.RLock()

		stack = wrappedErr.stack
		// Clone metadata map using maps.Clone for simplicity
		metadata = maps.Clone(wrappedErr.metadata)
		observer = wrappedErr.observer
		log = wrappedErr.logger

		wrappedErr.mu.RUnlock()
	} else {
		stack = CaptureStack()
		metadata = make(map[string]any)
	}

	wrapped := &Error{
		msg:      msg,
		cause:    err,
		stack:    stack,
		metadata: metadata,
		observer: observer,
		logger:   log,
	}

	for _, opt := range opts {
		opt(wrapped)
	}

	return wrapped
}

// Wrapf wraps an error with a formatted message.
func Wrapf(err error, format string, args ...any) *Error {
	if err == nil {
		return nil
	}

	return Wrap(err, fmt.Sprintf(format, args...))
}

// Error implements the error interface.
func (e *Error) Error() string {
	if e.cause != nil {
		return fmt.Sprintf("%s: %v", e.msg, e.cause)
	}

	return e.msg
}

// Cause returns the underlying cause of the error.
func (e *Error) Cause() error {
	return e.cause
}

// WithMetadata adds metadata to the error.
func (e *Error) WithMetadata(key string, value any) *Error {
	e.mu.Lock()
	e.metadata[key] = value

	if e.logger != nil {
		e.logger.Debug("metadata added",
			"key", key,
			"value", value,
			"error", e.msg,
		)
	}

	e.mu.Unlock()

	return e
}

// WithContext adds context information to the error.
func (e *Error) WithContext(ctx *ErrorContext) *Error {
	e.mu.Lock()
	defer e.mu.Unlock()

	e.metadata["error_context"] = ctx

	if e.logger != nil {
		e.logger.Debug("context added",
			"context", ctx,
			"error", e.msg,
		)
	}

	return e
}

// WithRecoverySuggestion attaches recovery guidance to the error.
func WithRecoverySuggestion(rs *RecoverySuggestion) Option {
	return func(err *Error) {
		err.mu.Lock()
		err.metadata["recovery_suggestion"] = rs
		err.mu.Unlock()

		if err.logger != nil && rs != nil {
			logData := []any{"message", rs.Message}
			if len(rs.Actions) > 0 {
				logData = append(logData, "actions", rs.Actions)
			}

			if rs.Documentation != "" {
				logData = append(logData, "documentation", rs.Documentation)
			}

			err.logger.Info("recovery suggestion added", logData...)
		}
	}
}

// GetMetadata retrieves metadata from the error.
func (e *Error) GetMetadata(key string) (any, bool) {
	e.mu.RLock()
	defer e.mu.RUnlock()

	val, ok := e.metadata[key]

	return val, ok
}

// GetMetadataValue retrieves metadata and attempts to cast it to type T.
func GetMetadataValue[T any](e *Error, key string) (T, bool) {
	e.mu.RLock()
	defer e.mu.RUnlock()

	var zero T

	val, ok := e.metadata[key]
	if !ok {
		return zero, false
	}

	typedVal, ok := val.(T)
	if !ok {
		return zero, false
	}

	return typedVal, true
}

// GetErrorContext retrieves the context from the error.
func (e *Error) GetErrorContext() *ErrorContext {
	e.mu.RLock()
	defer e.mu.RUnlock()

	if ctx, ok := e.metadata["error_context"].(*ErrorContext); ok {
		return ctx
	}

	return nil
}

// Stack returns the stack trace as a string.
func (e *Error) Stack() string {
	var builder strings.Builder

	frames := runtime.CallersFrames(e.stack)

	for {
		frame, more := frames.Next()
		// Skip runtime frames and error package frames
		if !strings.Contains(frame.File, "runtime/") && !strings.Contains(frame.File, "ewrap/errors.go") {
			_, _ = fmt.Fprintf(&builder, "%s:%d - %s\n", frame.File, frame.Line, frame.Function)
		}

		if !more {
			break
		}
	}

	return builder.String()
}

// Log logs the error using the configured logger.
func (e *Error) Log() {
	e.mu.RLock()
	observer := e.observer
	log := e.logger
	e.mu.RUnlock()

	if observer != nil {
		observer.RecordError(e.msg)
	}

	if log == nil {
		return
	}

	// Create a metadata map for logging
	logData := make([]any, 0, len(e.metadata)*2+baseLogDataSize)
	logData = append(logData, "error", e.msg)

	if e.cause != nil {
		logData = append(logData, "cause", e.cause.Error())
	}

	logData = append(logData, "stack", e.Stack())

	e.mu.RLock()

	for key, val := range e.metadata {
		if key == "recovery_suggestion" {
			logData = e.appendRecoverySuggestion(logData, val)

			continue
		}

		logData = append(logData, key, val)
	}

	e.mu.RUnlock()

	log.Error("error occurred", logData...)
}

// CaptureStack captures the current stack trace.
func CaptureStack() []uintptr {
	const depth = 32

	var pcs [depth]uintptr

	n := runtime.Callers(runtimeCallers, pcs[:])

	return pcs[:n]
}

// Is reports whether target matches err in the error chain.
func (e *Error) Is(target error) bool {
	if target == nil {
		return false
	}

	err := e
	for err != nil {
		if err.msg == target.Error() {
			return true
		}

		if err.cause == nil {
			return false
		}

		if causeErr, ok := err.cause.(*Error); ok {
			err = causeErr

			continue
		}

		return err.cause.Error() == target.Error()
	}

	return false
}

// Unwrap provides compatibility with Go 1.13 error chains.
func (e *Error) Unwrap() error {
	return e.cause
}

// appendRecoverySuggestion extracts recovery suggestion data for logging.
func (*Error) appendRecoverySuggestion(logData []any, val any) []any {
	rs, ok := val.(*RecoverySuggestion)
	if !ok {
		return logData
	}

	logData = append(logData, "recovery_message", rs.Message)

	if len(rs.Actions) > 0 {
		logData = append(logData, "recovery_actions", rs.Actions)
	}

	if rs.Documentation != "" {
		logData = append(logData, "recovery_documentation", rs.Documentation)
	}

	return logData
}