errors

errors

import "github.com/go-coldbrew/errors"

Package errors provides an implementation of golang error with stack strace information attached to it, the error objects created by this package are compatible with https://golang.org/pkg/errors/

How To Use The simplest way to use this package is by calling one of the two functions

errors.New(...)
errors.Wrap(...)

You can also initialize custom error stack by using one of the `WithSkip` functions. `WithSkip` allows skipping the defined number of functions from the stack information.

if you want to create a new error use New
if you want to skip some functions on the stack use NewWithSkip
if you want to add GRPC status use NewWithStatus
if you want to skip some functions on the stack and add GRPC status use NewWithSkipAndStatus
if you want to wrap an existing error use Wrap
if you want to wrap an existing error and add GRPC status use WrapWithStatus
if you want to wrap an existing error and skip some functions on the stack use WrapWithSkip
if you want to wrap an existing error, skip some functions on the stack and add GRPC status use WrapWithSkipAndStatus
if you want to wrap an existing error and add notifier options use WrapWithNotifier
if you want to wrap an existing error, skip some functions on the stack and add notifier options use WrapWithSkipAndNotifier

Head to https://docs.coldbrew.cloud for more information.

package main

import (
	"fmt"
	"io"

	"github.com/go-coldbrew/errors"
)

func main() {
	root := io.EOF
	first := errors.Wrap(root, "read body")
	second := errors.Wrap(first, "handle request")

	fmt.Println("error:", second)
	fmt.Println("cause:", second.Cause())
}

error: handle request: read body: EOF
cause: EOF

package main

import (
	"fmt"

	"github.com/go-coldbrew/errors"
)

func main() {
	err := errors.New("something failed")
	frames := err.StackFrame()
	// Stack frames are captured automatically
	fmt.Println(len(frames) > 0)
}

true

Index

• Constants
• func SetBaseFilePath(path string)
• func SetMaxStackDepth(n int)
• type ErrorExt
  • func New(msg string) ErrorExt
  • func NewWithSkip(msg string, skip int) ErrorExt
  • func NewWithSkipAndStatus(msg string, skip int, status *grpcstatus.Status) ErrorExt
  • func NewWithStatus(msg string, status *grpcstatus.Status) ErrorExt
  • func Newf(format string, args ...any) ErrorExt
  • func Wrap(err error, msg string) ErrorExt
  • func WrapWithSkip(err error, msg string, skip int) ErrorExt
  • func WrapWithSkipAndStatus(err error, msg string, skip int, status *grpcstatus.Status) ErrorExt
  • func WrapWithStatus(err error, msg string, status *grpcstatus.Status) ErrorExt
  • func Wrapf(err error, format string, args ...any) ErrorExt
• type NotifyExt
• type StackFrame

Constants

SupportPackageIsVersion1 is a compile-time assertion constant. Downstream packages reference this to enforce version compatibility.

const SupportPackageIsVersion1 = true

func SetBaseFilePath

func SetBaseFilePath(path string)

SetBaseFilePath sets the base file path for linking source code with reported stack information

func SetMaxStackDepth

func SetMaxStackDepth(n int)

SetMaxStackDepth sets the maximum number of stack frames captured when creating errors. Accepts values in [1, 256]; out-of-range values are ignored. Default is 16. Safe for concurrent use.

type ErrorExt

ErrorExt is the interface that defines a error, any ErrorExt implementors can use and override errors and notifier package

type ErrorExt interface {

    // Callers returns the call poiners for the stack
    Callers() []uintptr
    // StackFrame returns the stack frame for the error
    StackFrame() []StackFrame
    //Cause returns the original error object that caused this error
    Cause() error
    //GRPCStatus allows ErrorExt to be treated as a GRPC Error
    GRPCStatus() *grpcstatus.Status
    // contains filtered or unexported methods
}

func New

func New(msg string) ErrorExt

New creates a new error with stack information

package main

import (
	"fmt"

	"github.com/go-coldbrew/errors"
)

func main() {
	err := errors.New("something went wrong")
	fmt.Println(err)
}

something went wrong

func NewWithSkip

func NewWithSkip(msg string, skip int) ErrorExt

NewWithSkip creates a new error skipping the number of function on the stack

func NewWithSkipAndStatus

func NewWithSkipAndStatus(msg string, skip int, status *grpcstatus.Status) ErrorExt

NewWithSkipAndStatus creates a new error skipping the number of function on the stack and GRPC status

func NewWithStatus

func NewWithStatus(msg string, status *grpcstatus.Status) ErrorExt

NewWithStatus creates a new error with statck information and GRPC status

func Newf

func Newf(format string, args ...any) ErrorExt

Newf creates a new error with a formatted message and stack information

package main

import (
	"fmt"

	"github.com/go-coldbrew/errors"
)

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

user alice not found

func Wrap

func Wrap(err error, msg string) ErrorExt

Wrap wraps an existing error and appends stack information if it does not exists

package main

import (
	"fmt"
	"io"

	"github.com/go-coldbrew/errors"
)

func main() {
	original := io.EOF
	wrapped := errors.Wrap(original, "failed to read config")
	fmt.Println(wrapped)
	fmt.Println("cause:", wrapped.Cause())
}

failed to read config: EOF
cause: EOF

package main

import (
	stderrors "errors"
	"fmt"
	"io"

	"github.com/go-coldbrew/errors"
)

func main() {
	original := io.EOF
	wrapped := errors.Wrap(original, "read failed")
	fmt.Println(stderrors.Is(wrapped, io.EOF))
}

true

func WrapWithSkip

func WrapWithSkip(err error, msg string, skip int) ErrorExt

WrapWithSkip wraps an existing error and appends stack information if it does not exists skipping the number of function on the stack

func WrapWithSkipAndStatus

func WrapWithSkipAndStatus(err error, msg string, skip int, status *grpcstatus.Status) ErrorExt

WrapWithSkip wraps an existing error and appends stack information if it does not exists skipping the number of function on the stack along with GRPC status

func WrapWithStatus

func WrapWithStatus(err error, msg string, status *grpcstatus.Status) ErrorExt

Wrap wraps an existing error and appends stack information if it does not exists along with GRPC status

package main

import (
	"fmt"

	"github.com/go-coldbrew/errors"
	"google.golang.org/grpc/codes"
	"google.golang.org/grpc/status"
)

func main() {
	original := fmt.Errorf("record not found")
	s := status.New(codes.NotFound, "user not found")
	wrapped := errors.WrapWithStatus(original, "lookup failed", s)

	fmt.Println(wrapped)
	fmt.Println("gRPC code:", wrapped.GRPCStatus().Code())
}

lookup failed: record not found
gRPC code: NotFound

func Wrapf

func Wrapf(err error, format string, args ...any) ErrorExt

Wrapf wraps an existing error with a formatted message and appends stack information if it does not exist

package main

import (
	"fmt"

	"github.com/go-coldbrew/errors"
)

func main() {
	err := fmt.Errorf("connection refused")
	wrapped := errors.Wrapf(err, "failed to connect to port %d", 5432)
	fmt.Println(wrapped)
}

failed to connect to port 5432: connection refused

type NotifyExt

NotifyExt is the interface definition for notifier related options

type NotifyExt interface {
    // ShouldNotify returns true if the error should be notified
    ShouldNotify() bool
    // Notified sets the error to be notified or not
    Notified(status bool)
}

type StackFrame

StackFrame represents the stackframe for tracing exception

type StackFrame struct {
    File string `json:"file"`
    Line int    `json:"line"`
    Func string `json:"function"`
}

Generated by gomarkdoc