goforge

Documentation

Index

• func FormatStackTrace(stack []StackFrame) string
• func LoggerFromContext(ctx context.Context) *slog.Logger
• func LoggerFromContextOr(ctx context.Context, fallback *slog.Logger) *slog.Logger
• func PtrValue[T any](p *T) T
• func RespondError(w http.ResponseWriter, err error) error
• func RespondJSON[T any](w http.ResponseWriter, data T, statusCode int) error
• func WithLogger(ctx context.Context, logger *slog.Logger) context.Context
• type Endpoint
• type EndpointRegistry
• type Error
  • func NewError(cause error) *Error
  • func (e *Error) Error() string
  • func (e *Error) StackTrace() []StackFrame
  • func (e *Error) StackTraceString() string
  • func (e *Error) Unwrap() error
  • func (e *Error) WithCapturedStack(skip int) *Error
  • func (e *Error) WithCode(code string) *Error
  • func (e *Error) WithHTTPStatus(status int) *Error
  • func (e *Error) WithMessage(message string) *Error
  • func (e *Error) WithStack(stack []StackFrame) *Error
• type StackFrame
  • func CaptureStackTrace(skip int) []StackFrame

Functions

func FormatStackTrace

func FormatStackTrace(stack []StackFrame) string

FormatStackTrace formats captured stack frames into a multi-line string.

func LoggerFromContext

func LoggerFromContext(ctx context.Context) *slog.Logger

LoggerFromContext retrieves the logger from the context. If no logger is found, it returns a default logger.

func LoggerFromContextOr

func LoggerFromContextOr(ctx context.Context, fallback *slog.Logger) *slog.Logger

LoggerFromContextOr retrieves the logger from the context, falling back to fallback when no logger is present. A nil fallback uses the default logger.

func PtrValue

func PtrValue[T any](p *T) T

func RespondError

func RespondError(w http.ResponseWriter, err error) error

func RespondJSON

func RespondJSON[T any](w http.ResponseWriter, data T, statusCode int) error

func WithLogger

func WithLogger(ctx context.Context, logger *slog.Logger) context.Context

WithLogger adds a *log/slog.Logger to the context.

Types

type Endpoint

type Endpoint interface {
	Scheme() string
	Host() string
	Method() string
	Path() string
	Headers() http.Header
}

Endpoint is the standard contract for all goforge endpoints.

type EndpointRegistry

type EndpointRegistry interface {
	Register(endpoint Endpoint) error
	Start() error
}

EndpointRegistry is the standard contract for goforge endpoint registry.

type Error

type Error struct {
	HTTPStatus int          // E.g., 400, 404, 500
	Code       string       // Internal tracking code, e.g., "ERR_USER_FORBIDDEN_PASSWORD_CHANGE", can be used for user-facing translations.
	Message    string       // Safe, user-facing message
	Cause      error        // The underlying wrapped error for logs (should not be exposed to clients)
	Stack      []StackFrame // Captured call stack for logs and error reporters such as Sentry.
}

Error is the standard contract for all goforge errors.

func NewError

func NewError(cause error) *Error

NewError creates a new goforge error with a default 500 status code and the given cause.

func (*Error) Error

func (e *Error) Error() string

Error implements the error interface.

func (*Error) StackTrace

func (e *Error) StackTrace() []StackFrame

StackTrace returns a defensive copy of the captured stack frames.

func (*Error) StackTraceString

func (e *Error) StackTraceString() string

StackTraceString formats the captured stack in the same file:line/function shape most log sinks and error reporters expect.

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap allows standard errors.Is and errors.As to work perfectly.

func (*Error) WithCapturedStack

func (e *Error) WithCapturedStack(skip int) *Error

WithCapturedStack captures a fresh stack trace. The skip value excludes additional caller frames above WithCapturedStack.

func (*Error) WithCode

func (e *Error) WithCode(code string) *Error

WithCode sets the internal tracking code for the error.

func (*Error) WithHTTPStatus

func (e *Error) WithHTTPStatus(status int) *Error

WithHTTPStatus sets the HTTP status code for the error.

func (*Error) WithMessage

func (e *Error) WithMessage(message string) *Error

WithMessage sets the user-facing message for the error.

func (*Error) WithStack

func (e *Error) WithStack(stack []StackFrame) *Error

WithStack replaces the captured stack frames.

type StackFrame

type StackFrame struct {
	Function       string
	File           string
	Line           int
	ProgramCounter uintptr
}

StackFrame is a single call frame captured when a goforge error is created.

func CaptureStackTrace

func CaptureStackTrace(skip int) []StackFrame

CaptureStackTrace captures the current goroutine stack. The skip value excludes additional caller frames above CaptureStackTrace.