errors.go

package nerva

import (
	"encoding/json"
	"errors"
	"fmt"
	"log/slog"
	"net/http"
	"strings"
)

// HTTPError is NERVA's controlled application error. Cause is retained for
// internal inspection and is never serialized by the default error handler.
type HTTPError struct {
	Status   int
	Code     string
	Message  string
	Metadata Map
	Cause    error
}

// NewError creates a controlled HTTP error.
func NewError(status int, code, message string) *HTTPError {
	return &HTTPError{Status: status, Code: code, Message: message}
}

// Error implements error.
func (e *HTTPError) Error() string {
	if e == nil {
		return "<nil>"
	}
	if e.Code == "" {
		return e.Message
	}
	return e.Code + ": " + e.Message
}

// Unwrap exposes the internal cause to errors.Is and errors.As.
func (e *HTTPError) Unwrap() error {
	if e == nil {
		return nil
	}
	return e.Cause
}

// WithMetadata returns a shallow copy containing controlled response metadata.
func (e *HTTPError) WithMetadata(metadata Map) *HTTPError {
	if e == nil {
		return nil
	}
	clone := *e
	if metadata != nil {
		clone.Metadata = make(Map, len(metadata))
		for key, value := range metadata {
			clone.Metadata[key] = value
		}
	}
	return &clone
}

// WithCause returns a shallow copy that wraps an internal error. The cause is
// not included in the HTTP response.
func (e *HTTPError) WithCause(cause error) *HTTPError {
	if e == nil {
		return nil
	}
	clone := *e
	clone.Cause = cause
	return &clone
}

// ErrorHandler converts handler errors into HTTP responses. It may be invoked
// concurrently for different requests and must protect shared state.
type ErrorHandler func(*Context, error)

type errorEnvelope struct {
	Error errorBody `json:"error"`
}

type errorBody struct {
	Code      string `json:"code"`
	Message   string `json:"message"`
	RequestID string `json:"request_id"`
	Metadata  Map    `json:"metadata,omitempty"`
}

func defaultErrorHandler(c *Context, err error) {
	if c.response.unavailable() {
		slog.ErrorContext(
			c.Request().Context(),
			"nerva handler failed after response commit",
			"request_id", sanitizeLogValue(c.RequestID(), 128),
			"error_type", fmt.Sprintf("%T", err),
		)
		panic(http.ErrAbortHandler)
	}

	httpError := normalizeHTTPError(err)
	var controlled *HTTPError
	if !errors.As(err, &controlled) || controlled == nil || httpError.Status >= http.StatusInternalServerError {
		slog.ErrorContext(
			c.Request().Context(),
			"nerva handler returned an error",
			"request_id", sanitizeLogValue(c.RequestID(), 128),
			"method", sanitizeLogValue(c.Method(), 32),
			"path", sanitizeLogValue(c.Path(), 2048),
			"status", httpError.Status,
			"error_type", fmt.Sprintf("%T", err),
		)
	}
	body := errorEnvelope{Error: errorBody{
		Code:      httpError.Code,
		Message:   httpError.Message,
		RequestID: c.RequestID(),
		Metadata:  httpError.Metadata,
	}}
	payload, marshalErr := json.Marshal(body)
	if marshalErr != nil {
		slog.ErrorContext(
			c.Request().Context(),
			"nerva failed to serialize controlled error metadata",
			"request_id", sanitizeLogValue(c.RequestID(), 128),
			"method", sanitizeLogValue(c.Method(), 32),
			"path", sanitizeLogValue(c.Path(), 2048),
			"error_type", fmt.Sprintf("%T", marshalErr),
		)
		httpError = internalServerError()
		body = errorEnvelope{Error: errorBody{
			Code:      httpError.Code,
			Message:   httpError.Message,
			RequestID: c.RequestID(),
		}}
		payload, _ = json.Marshal(body)
	}
	payload = append(payload, '\n')
	// Representation metadata set before an error does not describe this JSON
	// response. In particular, a stale Content-Length can make net/http reject
	// the body and a stale Content-Encoding can make clients misdecode it.
	c.response.Header().Del("Content-Length")
	c.response.Header().Del("Content-Encoding")
	c.response.Header().Set("Content-Type", "application/json; charset=utf-8")
	c.response.WriteHeader(httpError.Status)
	if _, writeErr := c.response.Write(payload); writeErr != nil {
		slog.ErrorContext(
			c.Request().Context(),
			"nerva failed to write centralized error response",
			"request_id", sanitizeLogValue(c.RequestID(), 128),
			"error_type", fmt.Sprintf("%T", writeErr),
		)
		panic(http.ErrAbortHandler)
	}
}

func normalizeHTTPError(err error) *HTTPError {
	if err == nil {
		return internalServerError()
	}
	var httpError *HTTPError
	if errors.As(err, &httpError) && httpError != nil {
		clone := *httpError
		if clone.Status < 400 || clone.Status > 599 {
			return internalServerError()
		}
		if clone.Code == "" {
			clone.Code = defaultErrorCode(clone.Status)
		}
		if clone.Message == "" {
			clone.Message = http.StatusText(clone.Status)
			if clone.Message == "" {
				clone.Message = "HTTP error"
			}
		}
		return &clone
	}
	return internalServerError().WithCause(fmt.Errorf("handler error: %w", err))
}

func defaultErrorCode(status int) string {
	statusText := http.StatusText(status)
	if statusText == "" {
		return fmt.Sprintf("HTTP_%d", status)
	}
	var builder strings.Builder
	underscore := false
	for _, character := range strings.ToUpper(statusText) {
		if (character >= 'A' && character <= 'Z') || (character >= '0' && character <= '9') {
			builder.WriteRune(character)
			underscore = false
			continue
		}
		if !underscore && builder.Len() > 0 {
			builder.WriteByte('_')
			underscore = true
		}
	}
	return strings.TrimSuffix(builder.String(), "_")
}

func internalServerError() *HTTPError {
	return NewError(
		http.StatusInternalServerError,
		"INTERNAL_SERVER_ERROR",
		"Internal server error",
	)
}