errors

func GetClassification ¶

func GetClassification(err error) ErrorClassification

GetClassification extracts the ErrorClassification from an error. Returns ClassificationPermanent if the error is nil or not a PlatformError. This is a safe default that prevents inappropriate retry attempts.

This function handles the error chain and will extract the classification from the outermost PlatformError in the chain.

Example:

classification := errors.GetClassification(err)
if classification == errors.ClassificationRetryable {
    // Retry logic
}

func GetCode ¶

func GetCode(err error) ErrorCode

GetCode extracts the ErrorCode from an error. Returns CodeUnknown if the error is nil or not a PlatformError.

This function handles the error chain and will extract the code from the outermost PlatformError in the chain.

Example:

if errors.GetCode(err) == errors.CodeNotFound {
    // Handle not found
}

package main

import (
	"fmt"

	"github.com/jmgilman/go/errors"
)

func main() {
	err := errors.New(errors.CodeNotFound, "user not found")

	if errors.GetCode(err) == errors.CodeNotFound {
		fmt.Println("Handle not found case")
	}

}

Output:
Handle not found case

func ToJSON ¶

func ToJSON(err error) *ErrorResponse

ToJSON converts any error to an ErrorResponse suitable for JSON serialization. Returns nil if err is nil.

For PlatformError instances, extracts code, message, classification, and context. For standard errors, uses CodeUnknown, ClassificationPermanent, and the error message.

The wrapped error chain is intentionally excluded to prevent information leakage. Security consideration: Error chains may contain internal implementation details, stack traces, database queries, file paths, or other sensitive information.

Example:

func handleError(w http.ResponseWriter, err error) {
    response := errors.ToJSON(err)
    if response == nil {
        return // No error
    }
    w.Header().Set("Content-Type", "application/json")
    statusCode := getHTTPStatus(response.Code)
    w.WriteHeader(statusCode)
    json.NewEncoder(w).Encode(response)
}

package main

import (
	"encoding/json"
	"fmt"

	"github.com/jmgilman/go/errors"
)

func main() {
	err := errors.New(errors.CodeInvalidInput, "validation failed")
	err = errors.WithContext(err, "field", "email")
	err = errors.WithContext(err, "reason", "invalid format")

	response := errors.ToJSON(err)
	jsonBytes, _ := json.MarshalIndent(response, "", "  ")
	fmt.Println(string(jsonBytes))

}

Output:
{
  "code": "INVALID_INPUT",
  "message": "validation failed",
  "classification": "PERMANENT",
  "context": {
    "field": "email",
    "reason": "invalid format"
  }
}

package main

import (
	"encoding/json"
	"fmt"
	"net/http"

	"github.com/jmgilman/go/errors"
)

func main() {
	// Example HTTP error handler
	handleError := func(w http.ResponseWriter, err error) {
		response := errors.ToJSON(err)

		w.Header().Set("Content-Type", "application/json")

		// Map error code to HTTP status
		statusCode := http.StatusInternalServerError
		switch errors.GetCode(err) {
		case errors.CodeNotFound:
			statusCode = http.StatusNotFound
		case errors.CodeUnauthorized:
			statusCode = http.StatusUnauthorized
		case errors.CodeInvalidInput:
			statusCode = http.StatusBadRequest
		}

		w.WriteHeader(statusCode)
		_ = json.NewEncoder(w).Encode(response)
	}

	// Simulate error
	err := errors.New(errors.CodeNotFound, "resource not found")

	// Would write HTTP response
	_ = handleError
	fmt.Println(errors.GetCode(err))
}

Output:
NOT_FOUND

func New ¶

func New(code ErrorCode, message string) PlatformError

New creates a new PlatformError with the given code and message. The error classification is determined by the error code using default mappings.

Example:

err := errors.New(errors.CodeNotFound, "project not found")

package main

import (
	"fmt"

	"github.com/jmgilman/go/errors"
)

func main() {
	err := errors.New(errors.CodeNotFound, "user not found")
	fmt.Println(err.Error())
}

Output:
[NOT_FOUND] user not found

func Newf ¶

func Newf(code ErrorCode, format string, args ...interface{}) PlatformError

Newf creates a new PlatformError with a formatted message. The error classification is determined by the error code using default mappings.

Example:

err := errors.Newf(errors.CodeInvalidInput, "project name too long: %d characters (max %d)", len(name), maxLen)

package main

import (
	"fmt"

	"github.com/jmgilman/go/errors"
)

func main() {
	userID := "12345"
	err := errors.Newf(errors.CodeNotFound, "user %s not found", userID)
	fmt.Println(err.Error())
}

Output:
[NOT_FOUND] user 12345 not found

func WithClassification ¶

func WithClassification(err error, classification ErrorClassification) PlatformError

WithClassification overrides the classification of an error. Returns a new PlatformError with the specified classification.

This is useful when you need to override the default classification for an error code. For example, marking a normally permanent error as retryable in specific circumstances.

If err is not a PlatformError, it is converted to one with CodeUnknown. Returns nil if err is nil.

Example:

err := errors.New(errors.CodeDatabase, "connection failed")
// Normally retryable, but mark as permanent for this case
err = errors.WithClassification(err, errors.ClassificationPermanent)

package main

import (
	"fmt"

	"github.com/jmgilman/go/errors"
)

func main() {
	// Override default classification
	err := errors.New(errors.CodeDatabase, "database error")
	fmt.Println("Default:", errors.IsRetryable(err))

	// Mark as permanent for this specific case
	err = errors.WithClassification(err, errors.ClassificationPermanent)
	fmt.Println("Overridden:", errors.IsRetryable(err))

}

Output:
Default: true
Overridden: false

func WithContext ¶

func WithContext(err error, key string, value interface{}) PlatformError

WithContext adds a single context field to an error. Returns a new PlatformError with the context field added. Existing context fields are preserved.

If err is not a PlatformError, it is converted to one with CodeUnknown. Returns nil if err is nil.

Example:

err := errors.New(errors.CodeBuildFailed, "build failed")
err = errors.WithContext(err, "project", "my-app")
err = errors.WithContext(err, "phase", "test")

package main

import (
	"fmt"

	"github.com/jmgilman/go/errors"
)

func main() {
	err := errors.New(errors.CodeBuildFailed, "build failed")
	err = errors.WithContext(err, "project", "api")
	err = errors.WithContext(err, "phase", "test")

	ctx := err.Context()
	fmt.Printf("Project: %s, Phase: %s\n", ctx["project"], ctx["phase"])
}

Output:
Project: api, Phase: test

func WithContextMap ¶

func WithContextMap(err error, ctx map[string]interface{}) PlatformError

WithContextMap adds multiple context fields to an error. Returns a new PlatformError with the context fields merged. Existing context fields are preserved; new fields override existing ones with the same key.

If err is not a PlatformError, it is converted to one with CodeUnknown. Returns nil if err is nil.

Example:

err := errors.New(errors.CodeExecutionFailed, "execution failed")
err = errors.WithContextMap(err, map[string]interface{}{
    "command": "earthly",
    "target":  "+test",
})

package main

import (
	"fmt"

	"github.com/jmgilman/go/errors"
)

func main() {
	err := errors.New(errors.CodeExecutionFailed, "execution failed")
	err = errors.WithContextMap(err, map[string]interface{}{
		"command":   "earthly",
		"target":    "+test",
		"exit_code": 1,
	})

	ctx := err.Context()
	fmt.Printf("Command: %s, Exit: %d\n", ctx["command"], ctx["exit_code"])
}

Output:
Command: earthly, Exit: 1

func Wrap ¶

func Wrap(err error, code ErrorCode, message string) PlatformError

Wrap wraps an error with additional context while preserving the original error. The wrapped error is accessible via Unwrap() and compatible with errors.Is and errors.As.

If the wrapped error is a PlatformError, its classification is preserved. Otherwise, the default classification for the error code is used.

Returns nil if err is nil.

Example:

result, err := repo.Clone(ctx, url)
if err != nil {
    return errors.Wrap(err, errors.CodeNetwork, "failed to clone repository")
}

package main

import (
	"fmt"

	"github.com/jmgilman/go/errors"
)

func main() {
	// Simulate database error
	dbErr := fmt.Errorf("connection refused")

	// Wrap with platform error
	err := errors.Wrap(dbErr, errors.CodeDatabase, "failed to connect to database")

	fmt.Println(errors.GetCode(err))
}

Output:
DATABASE_ERROR

func WrapWithContext ¶

func WrapWithContext(err error, code ErrorCode, message string, ctx map[string]interface{}) PlatformError

WrapWithContext wraps an error and attaches context metadata in a single operation. The context map is copied to prevent external mutation.

Returns nil if err is nil.

Example:

if err := build(ctx); err != nil {
    return errors.WrapWithContext(err, errors.CodeBuildFailed, "build failed", map[string]interface{}{
        "project": projectName,
        "phase":   "test",
    })
}

func Wrapf ¶

func Wrapf(err error, code ErrorCode, format string, args ...interface{}) PlatformError

Wrapf wraps an error with a formatted message while preserving the original error.

Returns nil if err is nil.

Example:

if err := validate(input); err != nil {
    return errors.Wrapf(err, errors.CodeInvalidInput, "validation failed for field %s", fieldName)
}