Documentation
¶
Overview ¶
Package errors defines the structured error model used across the CLI.
Every user-facing failure is a *CLIError carrying a Category, a stable Code, a human message, an agent-facing hint and concrete next steps. The category maps deterministically to a process exit code (see codes.go) and to recovery guidance (see hints.go).
This package is shared by the openobserve-cli command layer and is also importable as a library; see the repository README. The Category set, the stable Codes, and their deterministic mapping to exit codes are an agent-facing contract relied on by the CLI and its companion Skill. Add new codes rather than renaming or repurposing existing ones, and keep the category -> exit-code mapping stable.
Index ¶
- Constants
- func ExitCode(err error) int
- type CLIError
- func (e *CLIError) Error() string
- func (e *CLIError) Payload() Payload
- func (e *CLIError) Unwrap() error
- func (e *CLIError) WithCause(cause error) *CLIError
- func (e *CLIError) WithHTTPStatus(status int) *CLIError
- func (e *CLIError) WithHint(hint string) *CLIError
- func (e *CLIError) WithNextSteps(steps ...string) *CLIError
- func (e *CLIError) WithRecovery(recovery Recovery) *CLIError
- type Category
- type Payload
- type PayloadBody
- type Recovery
Constants ¶
const ( ExitSuccess = 0 ExitInternal = 1 ExitUsage = 2 ExitConfig = 3 ExitAuth = 4 ExitPermission = 5 ExitNotFound = 6 ExitRateLimit = 7 ExitNetwork = 8 ExitServer = 9 ExitParse = 10 ExitConflict = 11 )
Exit codes. Each category maps to exactly one code so a calling agent can branch on the process exit status without parsing stderr.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type CLIError ¶
type CLIError struct {
Category Category
Code string
Message string
Hint string
NextSteps []string
Retryable bool
HTTPStatus int
Recovery *Recovery
// contains filtered or unexported fields
}
CLIError is the single error type surfaced to the user. It is JSON-encodable (see Payload) and unwraps to any wrapped cause.
func AsCLIError ¶
AsCLIError converts any error into a *CLIError, classifying unknown errors as internal. A nil error returns nil.
func New ¶
New builds a CLIError for the given category. The hint and next steps are filled from the category defaults unless overridden later via the With* helpers.
func (*CLIError) WithHTTPStatus ¶
WithHTTPStatus records the originating HTTP status code.
func (*CLIError) WithNextSteps ¶
WithNextSteps overrides the suggested next steps.
func (*CLIError) WithRecovery ¶ added in v0.7.0
WithRecovery records a structured recovery action for agent hosts.
type Category ¶
type Category string
Category classifies a failure. It drives both the exit code and the hints.
const ( CategoryUsage Category = "usage" CategoryConfig Category = "config" CategoryAuth Category = "auth" CategoryPermission Category = "permission" CategoryNotFound Category = "not_found" CategoryConflict Category = "conflict" CategoryRateLimit Category = "rate_limit" CategoryNetwork Category = "network" CategoryServer Category = "server" CategoryParse Category = "parse" CategoryInternal Category = "internal" )
func FromHTTPStatus ¶
FromHTTPStatus classifies an HTTP status code into a Category. Used by the API client to turn non-2xx responses into structured errors.
type Payload ¶
type Payload struct {
Error PayloadBody `json:"error"`
}
Payload is the JSON shape written to stderr for a failure.
type PayloadBody ¶
type PayloadBody struct {
Category Category `json:"category"`
Code string `json:"code"`
Message string `json:"message"`
Hint string `json:"hint,omitempty"`
NextSteps []string `json:"next_steps,omitempty"`
Retryable bool `json:"retryable"`
HTTPStatus int `json:"http_status,omitempty"`
Recovery *Recovery `json:"recovery,omitempty"`
}
PayloadBody is the inner object of Payload.
type Recovery ¶ added in v0.7.0
type Recovery struct {
Action string `json:"action"`
Scope string `json:"scope"`
Requires []string `json:"requires,omitempty"`
}
Recovery describes an environment change a caller can make before retrying. It is separate from Retryable: retrying in the same environment may still be pointless when, for example, a sandbox cannot access the user's keychain.
Source Files