Documentation
¶
Overview ¶
Package envelope is the one error shape every ovdb interface shares: the local API writes it, the CLI prints it (as JSON with --json, or as the "Couldn't …/Why/What you can do" problem pattern otherwise), and later the TUI and web console render it. Presentations never build one themselves; services and the shared client do.
See spec/features/configuration-parity#REQ:error-envelope and spec/features/first-run-onboarding#REQ:problem-pattern.
Index ¶
Constants ¶
const Schema = 1
Schema is the version of every local API body and --json document.
Variables ¶
var Codes = []Code{ InvalidArgument, ConfirmationRequired, NotFound, AlreadyExists, LocationNotEmpty, PortInUse, PortUnavailable, ServerNotRunning, ServerStartFailed, ServerVersionMismatch, ServerConfigMismatch, Unauthorized, Forbidden, StorageUnavailable, SchemaRequired, ValidationFailed, Unsupported, DependencyMissing, Timeout, Internal, }
Codes lists every valid code, in the spec's order.
Functions ¶
func Marshal ¶
Marshal renders any schema-1 document as compact JSON followed by one newline. The local API and the CLI both use it, which is what makes a command's --json output byte-for-byte equal to the API response body (configuration-parity#REQ:json-equals-api).
func MarshalError ¶
MarshalError renders e as the failure document.
func Write ¶
func Write(w http.ResponseWriter, e *Error)
Write sends e as an HTTP response with the status its code maps to.
func WriteJSON ¶
func WriteJSON(w http.ResponseWriter, status int, v any)
WriteJSON sends a schema-1 success document.
func WriteStatus ¶
func WriteStatus(w http.ResponseWriter, status int, e *Error)
WriteStatus sends e with an explicit status, for the few responses whose status is dictated by a route rather than by the code.
Types ¶
type Code ¶
type Code string
Code is one of the closed set of error codes.
const ( InvalidArgument Code = "invalid_argument" ConfirmationRequired Code = "confirmation_required" NotFound Code = "not_found" AlreadyExists Code = "already_exists" LocationNotEmpty Code = "location_not_empty" PortInUse Code = "port_in_use" ServerNotRunning Code = "server_not_running" ServerStartFailed Code = "server_start_failed" ServerVersionMismatch Code = "server_version_mismatch" ServerConfigMismatch Code = "server_config_mismatch" Forbidden Code = "forbidden" SchemaRequired Code = "schema_required" ValidationFailed Code = "validation_failed" Unsupported Code = "unsupported" DependencyMissing Code = "dependency_missing" Timeout Code = "timeout" Internal Code = "internal" )
The closed list of codes. Adding one is a spec change.
func (Code) HTTPStatus ¶
HTTPStatus is the local API status for code. Client-side-only codes (port_in_use, server_start_failed, …) never cross HTTP; they map to 500 so a misuse is loud rather than silently successful.
type Error ¶
type Error struct {
Code Code `json:"code"`
Message string `json:"message"`
Reason string `json:"reason,omitempty"`
Next []Next `json:"next"`
// Targets is what a command that failed for some of its targets did to
// the others (skills install: the outcomes of the folders that did
// change), as the same list its success document carries. It is absent
// when nothing changed, so a failure that touched nothing is the
// document it always was.
Targets json.RawMessage `json:"targets,omitempty"`
}
Error is a failure in envelope form. It is a Go error, so services return it through ordinary error paths and presentations recover it with As.
func (*Error) WithReason ¶
WithReason sets the "Why" line and returns e for chaining.
func (*Error) WithTargets ¶ added in v0.22.0
WithTargets sets the outcomes of the targets that did change before the failure; v is marshalled as the success document's list would be.
type Next ¶
type Next struct {
Label string `json:"label"`
Command string `json:"command,omitempty"`
Action string `json:"action,omitempty"`
}
Next is one thing the person (or agent) can do about a result or failure. Command is always runnable as written; Action names an in-UI remedy such as "use_port" that a TUI or web console offers as a button.
Source Files