README
¶
xerrors
Structured error classification and extensible logging utilities for corporate Go applications.
This package provides a rich, dual-layer error abstraction designed to isolate user-side validation failures from unexpected infrastructure breakdowns. It enforces visual predictability across logs, microservices, and tracking channels without third-party dependencies.
Purpose
xerrors standardizes error tracking, observability, and debugging ergonomics across repositories by introducing two specialized error families:
- Error 400 Family (
IError400) — Lightweight, high-performance validation exceptions caused by invalid user inputs. Bypasses reflection and stack inspection to maintain high throughput. - Error 500 Family (
IError500) — Rich, technical failure instances capturing root causes, lazy-loaded runtime component/stack tracing, and debugging data payloads.
Furthermore, the package features an advanced polymorphic parsing engine (buildMask) that dynamically normalizes visual log layout blocks, automatically safe-guarding missing arguments with the mathematical empty set marker (ø).
Installation
Use go get pointing to the package module:
go get github.com/AeonDigital/Go-Core/xerrors@latest
In your code, import the package:
import (
"context"
"errors"
"log/slog"
"github.com/AeonDigital/Go-Core/xerrors"
)
Basic Usage
1. User Validation Failures (Error 400)
The NewError400 factory uses a flexible, variadic signature (args ...any). It automatically determines if you are triggering a core framework token, an extended domain-specific token, or a standard string format.
// Scenario A: Emitting a core framework error token
err := xerrors.NewError400(xerrors.XERR_FIELD_REQUIRED, "USER-FLOW", "", "email")
// Scenario B: Emitting a plain formatted error without a registered token (defaults to XERR_NONE)
errPlain := xerrors.NewError400("invalid temporary session token: %s", tokenID)
2. Unexpected System Failures (Error 500)
Use NewError500 to instantiate a rich error when an infrastructure or unexpected processing routine breaks down. It natively supports Go's modern unwrapping semantics.
dbErr := errors.New("connection timeout downstream")
richErr := xerrors.NewError500(
xerrors.XERR_PKGCTX, // Context tracking boundary (errCTX)
xerrors.XERR_UNKNOWN, // Internal ErrorCode constant
dbErr, // Raw low-level root cause error
"database repository failure", // Human-readable message summary
`{"retry_count": 3}`, // Raw debugging context chunk or payload
)
To adjust caller frame detection when wrapping the error within helper blocks or custom factories, utilize the fluent WithCallerSkip API to securely clone and shift the stack inspection depth:
return err.WithCallerSkip(1)
Domain Error Expansion (Extending xerrors)
To prevent collision anomalies across independent application packages (e.g., two domains using E1001), xerrors introduces a namespaced plugin registration architecture via RegisterDomainErrors.
Rules for Domain Expansion:
- Code Syntax Contract: Custom codes must follow the
E[Family][Sequence]convention (e.g.,E1001). - Isolated Namespace: Every domain package must declare a distinct package context constant (
XERR_PKGCTX). - Bootstrap Hook: Registrations must be executed during the package
init()phase.
Step 1: Define and Register your Custom Domain Codes
Inside your domain package (e.g., pkg/orders), declare your context, codes, and metadata:
package orders
import "github.com/AeonDigital/Go-Core/xerrors"
const (
// Unique package isolation boundary namespace
XERR_PKGCTX xerrors.ErrorCode = "ERR_ORDER"
// Custom domain code: Family 1 (State validation), Sequence 1
XERR_ORDER_EXPIRED xerrors.ErrorCode = "E1001"
)
func init() {
// Inject configurations into the centralized core registry safely
xerrors.RegisterDomainErrors(
XERR_PKGCTX,
map[xerrors.ErrorCode]xerrors.MetaMessage{
XERR_ORDER_EXPIRED: {
message: "checkout session execution window expired",
extraTags: []string{"FIELD", "VALUE"}, // Triggers the visual layout engine
},
},
)
}
Step 2: Triggering the Custom Namespaced Error
Thanks to the polymorphic signature of NewError400, developers can seamlessly pass the package context alongside the custom token without manual string typecasting:
package orders
import "github.com/AeonDigital/Go-Core/xerrors"
func ValidateSession(ctx string, expiredAt int64) error {
if isExpired {
// Automatically maps to namespace "ERR_ORDER:E1001" behind the scenes.
// Arguments sequence aligned with extraTags: FIELD ("session_id") then VALUE (expiredAt)
return xerrors.NewError400(
XERR_PKGCTX,
XERR_ORDER_EXPIRED,
ctx,
"",
"session_id",
expiredAt,
)
}
return nil
}
Supported APIs
The package exposes the following core contracts:
xerrors.IError400— Interface contract for client-side and validation failures.xerrors.IError500— Interface contract for system-side and infrastructure breakdowns.xerrors.NewError400(args ...any)— Polymorphic lightweight validation factory.xerrors.NewError500(ctx, code, err, msg, data)— Component-tracing structural error factory.xerrors.RegisterDomainErrors(pkgCtx, registry)— Domain registration hook for extension mapping.xerrors.Log(ctx, err, attrs, options...)— Structuredslogpublishing channel.
External Dependencies
xerrors strictly depends only on the Go standard library:
contexterrorsfmtlog/slogruntimestrings
No third-party modules or frameworks are required.
Documentation
¶
Index ¶
- func DisableDebugMode()
- func EnableDebugMode()
- func GetDebugMode() bool
- func MsgArraySize(args ...any) string
- func MsgData(args ...any) string
- func MsgOptions(args ...any) string
- func Print(err error)
- func RegisterDomainErrors(pkgCtx ErrorCode, customRegistry map[ErrorCode]MetaMessage)
- func ToggleDebugMode()
- type Error500
- type ErrorCode
- type IError400
- type IError500
- type MetaMessage
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DisableDebugMode ¶
func DisableDebugMode()
DisableDebugMode disables technical error details, switching outputs to a user-friendly format suitable for end-users.
func EnableDebugMode ¶
func EnableDebugMode()
EnableDebugMode enables technical error details, making logs and outputs more comprehensive for debugging purposes.
func GetDebugMode ¶
func GetDebugMode() bool
GetDebugMode returns the current status of the debug mode. When true, errors provide technical details; when false, they are user-friendly.
func MsgArraySize ¶
MsgArraySize processes a variadic sequence of alternating key-length arguments and builds a unified diagnostic string mapping collections to their dimensions.
Arguments must follow a strict sequential layout: string (name) paired with an integer (size). Numeric zeros (0) are explicitly preserved as they represent critical operational states.
func MsgData ¶
MsgData processes a variadic sequence of alternating key-value arguments and stringifies them into a highly predictable, comma-separated operational layout (e.g., "key1=val1, key2=val2").
Exclusion Mechanics:
- By default, it completely omits any pair where the VALUE resolves to nil, zero (0), or an empty string ("").
- If the very first argument is provided as a []any slice, it overrides the default value blacklist, enforcing only the elements specified within that slice as the new filtration parameters.
func MsgOptions ¶
MsgOptions aggregates a variadic sequence of arguments into a clean, comma-separated text representation where strings and complex types are dynamically enclosed in single quotes.
Exclusion Mechanics:
- By default, it ignores explicit nil values, zeros (0), and empty strings ("") to prevent visual clutter.
- If the very first argument is provided as a []any slice, it overrides the default exclusion rule.
func Print ¶
func Print(err error)
Print writes the error's string representation directly to the standard error stream (os.Stderr). It acts as a lightweight, zero-allocation wrapper around fmt.Fprintln, providing a swift debugging mechanism that bypasses context allocations or structured logging handler configurations. If the incoming error target is nil, the execution block returns early without writing to the stream.
func RegisterDomainErrors ¶
func RegisterDomainErrors(pkgCtx ErrorCode, customRegistry map[ErrorCode]MetaMessage)
RegisterDomainErrors injects custom domain error configurations into the centralized core registry. It automatically establishes a unique namespace using the pkgCtx token (e.g., transforming "E1001" into "ERR_USER:E1001") to seamlessly eliminate mapping collisions between independent packages.
func ToggleDebugMode ¶
func ToggleDebugMode()
ToggleDebugMode switches the current state of the debug mode (enables it if disabled, or disables it if enabled).
Types ¶
type Error500 ¶
type Error500 struct {
// contains filtered or unexported fields
}
Error500 provides a concrete structural implementation of the IError500 interface. It encapsulates contextual metadata alongside standard system exceptions to maximize observability and reduce cognitive friction during troubleshooting pipelines.
func (*Error500) CTX ¶
CTX retrieves the isolated contextual tracking identity assigned to this error payload.
func (*Error500) Component ¶
Component returns the dynamically reflected runtime namespace where the failure originated. It leverages lazy-loading evaluation, executing stack inspection only upon the first request.
func (*Error500) Error ¶
Error satisfies the standard Go library error handling interface contract specification. It dynamically alters its layout density based on the global debugMode state configuration.
func (*Error500) Info ¶
Info fetches the secondary raw context strings attached to this structural payload container.
func (*Error500) Message ¶
Message extracts the human-readable summary detailing the specific breakdown event.
func (*Error500) Unwrap ¶
Unwrap returns the underlying root cause error, enabling seamless integration with standard library features like errors.Is and errors.As.
func (*Error500) WithCallerSkip ¶
WithCallerSkip allows dynamically adjusting the runtime stack frame skip level. It creates a new instance copy to prevent side effects on the original error.
type ErrorCode ¶
type ErrorCode string
ErrorCode defines a domain-specific string representation for error classification.
const ( XERR_NONE ErrorCode = "" XERR_PKGCTX ErrorCode = "ERR_XERR" // XERR_UNKNOWN serves as the general fallback categorization for untracked exceptions. XERR_UNKNOWN ErrorCode = "E0001" // XERR_FIELD_REQUIRED belongs to Group 1 (Presence & Nullity). // Targets missing parameters, empty payloads, or fields whose total absence matches an 'undefined' state. // Format expects: CTX, MSG, FIELD, [error] XERR_FIELD_REQUIRED ErrorCode = "E1001" // XERR_NIL_NOT_ALLOWED belongs to Group 1 (Presence & Nullity). // Targets cases where a field or reference pointer is explicitly supplied but contains a forbidden nil value. // Format expects: CTX, MSG, FIELD, [error] XERR_NIL_NOT_ALLOWED ErrorCode = "E1002" // XERR_EMPTY_NOT_ALLOWED belongs to Group 1 (Presence & Nullity). // Targets fields that are allocated and non-nil, but their textual contents resolve to an empty string (""). // Format expects: CTX, MSG, FIELD, [error] XERR_EMPTY_NOT_ALLOWED ErrorCode = "E1003" // XERR_ZERO_NOT_ALLOWED belongs to Group 1 (Presence & Nullity). // Targets scenarios where numeric primitives, lengths, or uninitialized value types resolve to a forbidden zero state (0). // Format expects: CTX, MSG, FIELD, [error] XERR_ZERO_NOT_ALLOWED ErrorCode = "E1004" // XERR_ALREADY_EXISTS belongs to Group 1 (Presence & Nullity). // Targets uniqueness constraint violations where a valid field value cannot be accepted because it duplicates an active record. // Format expects: CTX, MSG, FIELD, VALUE, [error] XERR_ALREADY_EXISTS ErrorCode = "E1005" // XERR_NOT_FOUND belongs to Group 1 (Presence & Nullity). // Targets cases where a perfectly valid field lookup identifier fails to map to an active resource or file path. // Format expects: CTX, MSG, FIELD, TGT, [error] XERR_NOT_FOUND ErrorCode = "E1006" // XERR_PERMISSION_DENIED belongs to Group 1 (Presence & Nullity). // Targets security contract breaches where the application lacks the OS credentials, RBAC tokens, // or read/write privileges required to interact with the target resource. // Format expects: CTX, MSG, FIELD, TGT, [error] XERR_PERMISSION_DENIED ErrorCode = "E1007" // XERR_RESOURCE_UNAVAILABLE belongs to Group 1 (Presence & Nullity). // Targets IO blockages, hardware failures, timeout sequences, or networking disruptions // that prevent communication with an otherwise structurally valid target endpoint or file stream. // Format expects: CTX, MSG, FIELD, TGT, [error] XERR_RESOURCE_UNAVAILABLE ErrorCode = "E1008" // XERR_RESOURCE_CORRUPTED belongs to Group 1 (Presence & Nullity). // Targets integrity structural failures where the resource (file, payload, or state) // is physically present but its inner bytes break syntax rules, cryptographic checksums, or validation schemas. // Format expects: CTX, MSG, FIELD, TGT, [error] XERR_RESOURCE_CORRUPTED ErrorCode = "E1009" // XERR_RESOURCE_NOT_FOUND belongs to Group 1 (Presence & Nullity). // Targets system I/O, file systems, or directories that do not exist at the specified target path. // Format expects: CTX, MSG, FIELD, TGT, [error] XERR_RESOURCE_NOT_FOUND ErrorCode = "E1010" // XERR_INVALID_VALUE belongs to Group 2 (Numeric & Boundaries). // General fallback for values that satisfy basic structural parsing but fail specialized domain business rules. // Format expects: CTX, MSG, FIELD, VALUE, RULES, [error] XERR_INVALID_VALUE ErrorCode = "E2001" // XERR_INVALID_VALUE_GT_ZERO belongs to Group 2 (Numeric & Boundaries). // Enforces that an evaluated mathematical property must be strictly greater than zero (> 0). // Format expects: CTX, MSG, FIELD, VALUE, [RULES], [error] XERR_INVALID_VALUE_GT_ZERO ErrorCode = "E2002" // XERR_INVALID_VALUE_GE_ZERO belongs to Group 2 (Numeric & Boundaries). // Enforces that an evaluated mathematical property must be greater than or equal to zero (>= 0). // Format expects: CTX, MSG, FIELD, VALUE, [RULES], [error] XERR_INVALID_VALUE_GE_ZERO ErrorCode = "E2003" // XERR_INVALID_VALUE_LT_ZERO belongs to Group 2 (Numeric & Boundaries). // Enforces that an evaluated mathematical property must be strictly less than zero (< 0). // Format expects: CTX, MSG, FIELD, VALUE, [RULES], [error] XERR_INVALID_VALUE_LT_ZERO ErrorCode = "E2004" // XERR_INVALID_VALUE_LE_ZERO belongs to Group 2 (Numeric & Boundaries). // Enforces that an evaluated mathematical property must be less than or equal to zero (<= 0). // Format expects: CTX, MSG, FIELD, VALUE, [RULES], [error] XERR_INVALID_VALUE_LE_ZERO ErrorCode = "E2005" // XERR_INVALID_VALUE_OUT_OF_RANGE belongs to Group 2 (Numeric & Boundaries). // Enforces that numbers, calendar dates, or generic offsets must stay enclosed within explicit low-high thresholds. // Format expects: CTX, MSG, FIELD, VALUE, [RULES], [error] XERR_INVALID_VALUE_OUT_OF_RANGE ErrorCode = "E2006" // XERR_SELECTION_LIMIT_EXCEEDED belongs to Group 2 (Numeric & Boundaries). // Targets scenarios where the number of selected items breaks cardinality boundaries or exceeds the maximum quantity constraints. // Format expects: CTX, MSG, FIELD, OPT, COUNT, LIMIT, [error] XERR_SELECTION_LIMIT_EXCEEDED ErrorCode = "E2007" // XERR_INVALID_FORMAT belongs to Group 3 (Structure & Choices). // Targets syntax anomalies where string shapes break regex validations, structural encoding, or lexical requirements. // Format expects: CTX, MSG, FIELD, GIVEN, EXPECTED, [error] XERR_INVALID_FORMAT ErrorCode = "E3001" // XERR_INVALID_FORMAT_MARSHAL belongs to Group 3 (Structure & Choices). // Targets serialization anomalies where structural objects or typed domain entities fail to transform into target data shapes. // Format expects: CTX, MSG, FIELD, GIVEN, EXPECTED, [error] XERR_INVALID_FORMAT_MARSHAL ErrorCode = "E3002" // XERR_INVALID_FORMAT_UNMARSHAL belongs to Group 3 (Structure & Choices). // Targets deserialization anomalies where raw payload inputs break type structural specifications during structural unmarshaling. // Format expects: CTX, MSG, FIELD, GIVEN, EXPECTED, [error] XERR_INVALID_FORMAT_UNMARSHAL ErrorCode = "E3003" // XERR_INVALID_FORMAT_PARSE belongs to Group 3 (Structure & Choices). // Targets conversion anomalies where string primitives or unstructured slices fail lexical conversion into valid data primitives. // Format expects: CTX, MSG, FIELD, GIVEN, EXPECTED, [error] XERR_INVALID_FORMAT_PARSE ErrorCode = "E3004" // XERR_INVALID_TYPE belongs to Group 3 (Structure & Choices). // Targets type mismatch exceptions triggered during interface assertions, reflection mapping, or payload unmarshaling. // Format expects: CTX, MSG, FIELD, VALUE, EXPECTED_TYPE, [error] XERR_INVALID_TYPE ErrorCode = "E3005" // XERR_INVALID_OPTION belongs to Group 3 (Structure & Choices). // Targets invalid parameters outside a restrictive list of valid options or mutual exclusivity boundary contract violations. // Format expects: CTX, MSG, FIELD, OPT, OPTIONS, [error] XERR_INVALID_OPTION ErrorCode = "E3006" // XERR_MUTUAL_EXCLUSIVITY_VIOLATION belongs to Group 3 (Structure & Choices). // Targets structural contract breaches where choosing a specific field or option strictly invalidates the co-existence of others. // Format expects: CTX, MSG, FIELD, OPT, OPTIONS, [error] XERR_MUTUAL_EXCLUSIVITY_VIOLATION ErrorCode = "E3007" // XERR_ASYMMETRIC_SIZES belongs to Group 3 (Structure & Choices). // Targets structural contract breaches where interdependent collections fail to match linear sequence length. // Format expects: CTX, MSG, FIELDS, [error] XERR_ASYMMETRIC_SIZES ErrorCode = "E3008" // XERR_UNEXPECTED_FAIL belongs to Group 4 (Generic Operational Fallbacks). // Targets severe, non-deterministic system breakdowns, unmapped runtime panic states, or logic violations // that breach system stability invariants. Designed to act as a global strategic catch-all mechanism. // Format expects: CTX, MSG, DATA, [error] XERR_UNEXPECTED_FAIL ErrorCode = "E4001" // XERR_OPERATION_FAILED belongs to Group 4 (Generic Operational Fallbacks). // Targets state machine disruptions, unexecutable business commands, or processing // sequences that fail to complete their logic due to internal routine faults. // Format expects: CTX, MSG, FIELD, DATA, [error] XERR_OPERATION_FAILED ErrorCode = "E4002" )
type IError400 ¶
type IError400 interface {
// Code returns the categorical string constant domain mapping for this validation event.
Code() ErrorCode
// error ensures native alignment with Go standard library error handling semantics.
error
}
IError400 standardizes validation and client-side failures, allowing transport layers to seamlessly extract error codes without string parsing.
func NewError400 ¶
NewError400 acts as a highly flexible, polymorphic factory that creates and returns an IError400 instance. It abstracts away method overloading limitations in Go by inspecting the type sequence of its variadic arguments.
The evaluation hierarchy operates as follows:
- Composed Domain Token: If the first two arguments are identified as ErrorCode types, they are unified into a namespaced key (e.g., "PKGCTX:E1001") to match domain-extended registries.
- Core Package Token: If only the first argument is an ErrorCode, the factory falls back to the core infrastructure namespace ("ERR_XERR:E1001").
- Plain Text/Standard Format: If no initial ErrorCode tokens are detected, it evaluates the arguments as a standard fmt.Sprintf format string or raw message, defaulting the error code tracking state to XERR_NONE.
type IError500 ¶
type IError500 interface {
// CTX extracts the structural context identifier or tracking boundary metadata
// associated with the entry point of this operational flow.
CTX() ErrorCode
// Code returns the categorical string constant domain mapping for this failure event.
Code() ErrorCode
// Component pinpoints the specific architectural layer or tracking package path.
Component() string
// error ensures native alignment with Go standard library errors handling semantics.
error
// WithCallerSkip allows dynamically adjusting the runtime stack frame skip level to recompute
// the component identifier. This is essential when NewError is wrapped inside custom factory
// utilities or logging helper blocks, ensuring the framework pinpoints the true origin of the failure.
// It returns the updated IError500 to support fluent API call chaining.
WithCallerSkip(skip int) IError500
// Message returns the readable operational summary describing what went wrong.
Message() string
// Info returns information for debugging the context.
Info() string
}
IError500 standardizes the functional execution capabilities required to manage rich, decoupled diagnostic payloads across network borders, microservices, and system boundaries.
func NewError500 ¶
func NewError500( errCTX ErrorCode, errCode ErrorCode, err error, message string, info string, ) IError500
NewError500 initializes a rich IError500 instance. It pre-configures a default call stack frame skip level but postpones the actual heavy runtime inspection until the component property is explicitly requested by a logger or console channel.
type MetaMessage ¶
type MetaMessage struct {
// contains filtered or unexported fields
}
MetaMessage encapsulates static corporate fallback strings and semantic tagging rules required to build standardized, predictable error formatting structures.
func NewMetaMessage ¶
func NewMetaMessage( message string, fieldRule string, extraTags []string, ) MetaMessage
NewMetaMessage acts as a secure constructor that initializes and returns a populated MetaMessage instance. By exposing this factory, the package enables external domain extensions to define fallback metadata while strictly preserving the encapsulation of internal structural layout properties.
Source Files