Documentation
¶
Overview ¶
Package errx provides structured, code-based errors for MCP runtime and CLI tooling.
The package implements a code-based error system where each error has:
- A stable 5-digit error code (e.g., "72000" for registry errors)
- A category description (e.g., "Registry error")
- A user-facing message
- Optional structured context (key-value pairs)
- Optional cause and base sentinel errors
Error codes follow a scheme where the first two digits represent the domain:
- 70xxx: CLI/argument validation errors
- 71xxx: Cluster/provisioning errors
- 72xxx: Registry errors
- 73xxx: Operator errors
- 74xxx: Pipeline errors
- 75xxx: Build errors
- 76xxx: Server definition errors
- 77xxx: Certificate/TLS errors
- 78xxx: Setup/installation errors
- 79xxx: Configuration errors
The last three digits are reserved for subcodes (future use).
Example usage:
err := errx.Registry("failed to connect to registry").
WithContext("url", "registry.mcpruntime.com").
WithBase(sentinelErr)
if errors.Is(err, sentinelErr) {
// Handle specific error
}
fmt.Println(errx.UserString(err)) // User-friendly message
fmt.Println(errx.DebugString(err)) // Full debug details
Index ¶
- Constants
- func DebugString(err error) string
- func DescriptionFor(code string) (string, bool)
- func IsError(err error) bool
- func IsValidCode(code string) bool
- func LogrKV(err error) ([]any, bool)
- func UserString(err error) string
- type Error
- func CLI(message string) *Error
- func CreateByCode(code, description, message string, cause error) *Error
- func FromSentinel(sentinel error, lookup func(error) (code, description string), message string, ...) *Error
- func New(code, description, message string) *Error
- func Operator(message string) *Error
- func Wrap(code, description, message string, cause error) *Error
- func WrapCLI(message string, cause error) *Error
- func WrapOperator(message string, cause error) *Error
- func (e *Error) Base() error
- func (e *Error) Cause() error
- func (e *Error) Code() string
- func (e *Error) Context() map[string]any
- func (e *Error) Description() string
- func (e *Error) Error() string
- func (e *Error) Is(target error) bool
- func (e *Error) Message() string
- func (e *Error) Unwrap() error
- func (e *Error) WithBase(base error) *Error
- func (e *Error) WithContext(key string, value any) *Error
- func (e *Error) WithContextMap(ctx map[string]any) *Error
- type RegistryEntry
Constants ¶
const ( CodeCLI = "70000" CodeCluster = "71000" CodeRegistry = "72000" CodeOperator = "73000" CodePipeline = "74000" CodeBuild = "75000" CodeServer = "76000" CodeCert = "77000" CodeSetup = "78000" CodeConfig = "79000" CodeAuth = "80000" )
Error codes follow a stable 5-digit scheme where the first two digits are the domain and the last three digits are reserved for subcodes.
const ( DescCLI = "CLI/argument validation error" DescCluster = "Cluster/provisioning error" DescRegistry = "Registry error" DescOperator = "Operator error" DescPipeline = "Pipeline error" DescBuild = "Build error" DescServer = "Server definition error" DescCert = "Certificate/TLS error" DescSetup = "Setup/installation error" DescConfig = "Configuration error" DescAuth = "Authentication / credential error" )
Variables ¶
This section is empty.
Functions ¶
func DebugString ¶
DebugString returns a verbose error string with codes, context, and chain.
func DescriptionFor ¶
DescriptionFor returns the registry description for a code.
func IsValidCode ¶
IsValidCode checks if the given error code is registered.
func LogrKV ¶
LogrKV returns controller-runtime logr-style key/value pairs for an errx.Error. The second return value is false when err is nil, not an *Error, or a typed nil *Error stored in an error interface (errors.As succeeds but the pointer value is nil).
func UserString ¶
UserString returns a user-safe error message. It extracts the most user-friendly message from an errx.Error, falling back to the standard error message for non-errx errors.
Types ¶
type Error ¶
type Error struct {
// contains filtered or unexported fields
}
Error is the base error type for MCP runtime errors.
func CLI ¶
CLI creates a CLI/argument validation error with code 70000. Use this for errors related to command-line argument validation, invalid user input, or CLI-specific issues. This is heavily used in internal/cli/errors.go for CLI sentinel errors.
func CreateByCode ¶
CreateByCode creates an Error using the provided code, description, and message. This is a convenience function that directly calls New() or Wrap().
func FromSentinel ¶
func FromSentinel(sentinel error, lookup func(error) (code, description string), message string, cause error) *Error
FromSentinel creates an Error from a sentinel error and optional message/cause. This is useful when you have a sentinel error and want to create an errx.Error with the same category. The sentinel is used to determine the category via a lookup function. Panics if sentinel is nil (sentinel is required for error identification).
func New ¶
New creates a new Error with the provided code, description, and message. Panics if code is empty (code is required for error identification).
func Operator ¶
Operator creates an operator error. This is used in internal/operator/errors.go for operator-specific errors.
func Wrap ¶
Wrap creates a new Error and attaches a cause error. Panics if code is empty (code is required for error identification).
func WrapCLI ¶
WrapCLI wraps a cause with a CLI/argument validation error. Use this when a CLI error is caused by another error that should be preserved.
func WrapOperator ¶
WrapOperator wraps a cause with an operator error. This is used in internal/operator/errors.go for operator-specific errors.
func (*Error) Description ¶
Description returns the category description.
func (*Error) Is ¶
Is implements error matching for sentinel errors. This allows errors.Is(err, sentinel) to match the base sentinel even though Unwrap() returns the cause.
func (*Error) Unwrap ¶
Unwrap returns the immediate wrapped error (cause). This follows Go's error wrapping convention where Unwrap() returns the direct cause, not the base sentinel.
func (*Error) WithBase ¶
WithBase sets the sentinel base error used for errors.Is matching. Returns a new error with the base set to avoid mutating the original. Panics if called on a nil receiver.
func (*Error) WithContext ¶
WithContext adds a context key/value pair. Returns a new error with the added context to avoid mutating the original. Panics if called on a nil receiver or if key is empty.
func (*Error) WithContextMap ¶
WithContextMap merges a context map into the error context. Returns a new error with the merged context to avoid mutating the original. Always returns a clone to maintain immutability, even if ctx is empty. Panics if called on a nil receiver or if any key in ctx is empty.
type RegistryEntry ¶
RegistryEntry describes a registered error code.
func ErrorRegistry ¶
func ErrorRegistry() []RegistryEntry
ErrorRegistry returns the error registry in deterministic order. This provides a list of all registered error codes and their descriptions.
Source Files