problem

Documentation

Overview

Package problem decodes the Normatik public API's RFC-7807 ProblemDetail responses and maps them to actionable CLI output + exit codes.

Design choice (the CLI's value-add): we decode the RAW error body into a generic map so that EVERY field — including hint fields the CLI does not yet know about — is preserved (Raw). Known fields are additionally lifted into typed fields for ergonomic access. Exit-code policy lives in one place (internal/catalog.ExitFor); the synthesized "next command" is a data-driven registry keyed by errorCode rather than a growing switch.

Index

• type Diagnostic
• type Problem
  • func Decode(status int, body []byte) (*Problem, bool)
  • func (p *Problem) Error() string
  • func (p *Problem) ExitCode() int
  • func (p *Problem) Suggestion(base string) string

Types

type Diagnostic

type Diagnostic struct {
	Code      string `json:"code"`
	Severity  string `json:"severity"`
	Line      int    `json:"line"`
	Column    int    `json:"column"`
	EndColumn int    `json:"endColumn"`
	Message   string `json:"message"`
}

type Problem

type Problem struct {
	Status          int
	Title           string
	Detail          string
	ErrorCode       string
	Hint            string
	Reason          string
	ValidKeys       []string
	ValidNames      []string
	InvalidKeys     []string
	UnknownKeys     []string
	ValidValues     []string
	AllowedMethods  []string
	CurrentStatus   string
	RequestedAction string
	RequiredRole    string
	Field           string
	ReceivedValue   string
	MinValue        string
	MaxValue        string
	ReceivedZone    string
	EntityType      string
	CurrentVersion  string
	UsageCount      *int
	// RetryAfterSeconds and InTrash drive recovery suggestions.
	RetryAfterSeconds *int
	InTrash           bool
	Diagnostics       []Diagnostic
	Raw               map[string]json.RawMessage
}

Problem is a decoded ProblemDetail. Known fields are typed; Raw holds every field verbatim for forward-compatible surfacing.

func Decode

func Decode(status int, body []byte) (*Problem, bool)

Decode parses an error body. ok=false means the body is NOT a recognizable ProblemDetail (e.g. a Tomcat HTML 404) — callers treat that as a distinct "malformed backend response" class instead of pretending it has an errorCode.

func (*Problem) Error

func (p *Problem) Error() string

func (*Problem) ExitCode

func (p *Problem) ExitCode() int

ExitCode maps a problem to a stable, documented exit code (see `explain exit-codes`). The policy is centralized in catalog.ExitFor so the CLI and the generated catalogue can never disagree. Agents branch on the exit code first, then on the errorCode for precision.

func (*Problem) Suggestion

func (p *Problem) Suggestion(base string) string

Suggestion synthesizes a runnable "next command" from the structured hint fields, so an agent (or human) can self-correct in one loop.