Documentation
¶
Overview ¶
Package errors provides types and function used to implement MeshKit compatible errors across the Meshery code base.
Uniform definition of errors using these types and functions facilitates extracting error information directly from the code and generating and publishing error code reference documentation automatically. The error utility tool in this module, /cmd/errorutil, is part of this toolchain.
It depends on a few conventions in order to work:
1) An error code defined as a constant or variable (preferably constant), of type string. The naming convention for these variables is the regex "^Err[A-Z].+Code$", e.g. ErrApplyManifestCode. The initial value of the code is a placeholder string, e.g. "replace_me", set by the developer. The final value of the code is an integer, set by the errorutil tool, as part of a CI workflow.
2) Error details defined using the function New(...) in this package, see below for details.
Additionally, the following conventions apply:
Errors are defined in each package, in a file named error.go. Errors are namespaced to Meshery components, i.e. they need to be unique within a component. (Often, a specific component corresponds to one git repository.) There are no predefined error code ranges for components. Every component is free to use its own range. Codes carry no meaning, as e.g. HTTP status codes do.
See also the doc command of errorutil, and https://docs.meshery.io/project/contributing/contributing-error.
Example:
const ErrConnectCode = "11000"
func ErrConnect(err error) error {
return errors.New(ErrConnectCode,
errors.Alert,
[]string{"Connection to broker failed"},
[]string{err.Error()},
[]string{"Endpoint might not be reachable"},
[]string{"Make sure the NATS endpoint is reachable"})
}
Index ¶
Constants ¶
const ( Emergency = iota // System unusable None // None severity Alert // Immediate action needed Critical // Critical condition—default level Fatal // Fatal condition )
Variables ¶
var (
NoneString = []string{"None"}
)
Functions ¶
func GetSDescription ¶ added in v0.1.18
Types ¶
type Error ¶
type Error struct {
Code string
Severity Severity
ShortDescription []string
LongDescription []string
ProbableCause []string
SuggestedRemediation []string
}
func New ¶
func New(code string, severity Severity, sdescription []string, ldescription []string, probablecause []string, remedy []string) *Error
New returns a MeshKit error using the provided parameters.
In order to create MeshKit compatible errors that can be handled by the errorutil tool, consider the following points:
The first parameter, 'code', has to be passed as the error code constant (or variable), not a string literal.
The second parameter, 'severity', has its own type; consult its Go-doc for further details.
The remaining parameters are string arrays for short and long description, probable cause, and suggested remediation. Use string literals in these string arrays, not constants or variables, for any static texts or format strings. Capitalize the first letter of each statement. Call expressions can be used but will be ignored by the tool when exporting error details for the documentation. Do not concatenate strings using the '+' operator, just add multiple elements to the string array.
Example:
errors.New(ErrConnectCode,
errors.Alert,
[]string{"Connection to broker failed"},
[]string{err.Error()},
[]string{"Endpoint might not be reachable"},
[]string{"Make sure the NATS endpoint is reachable"})
func NewDefault
deprecated
type ErrorV2 ¶ added in v0.6.20
type ErrorV2 struct {
Code string
Severity Severity
ShortDescription []string
LongDescription []string
ProbableCause []string
SuggestedRemediation []string
AdditionalInfo interface{}
}
Limitations of Error struct defined above: There are different types of Errors. Each type of error contains different information. Short and Long Descriptions accept only strings and so they cannot contain structured information. e.g. The Validation Error information (instancePath, badValue etc.) cannot be contained in Error struct (or not in a structured way that the clients can make use of it)
ErrorV2 struct adds the ability to express all different types of errors. ErrorV2 is backwards compatible with Error struct
Source Files