compositeerrors

type CompositeError ¶

type CompositeError interface {
	error // headline, the one-line message users see

	Type() Type
	Severity() Severity

	// Sections returns optional structured detail (what / why / fix).
	// Returning nil is fine; the headline alone is a valid view.
	Sections() []Section
}

CompositeError is a typed, structured error. Implementations satisfy the standard error interface (Error() returns the headline message), plus metadata used to persist and present the error in the dashboard.

type CompositeErrorData ¶

type CompositeErrorData struct {
	// Version is the payload schema version (SchemaVersion at write time).
	Version int `json:"version"`

	Type     Type      `json:"type"`
	Severity Severity  `json:"severity"`
	Message  string    `json:"message"`
	Sections []Section `json:"sections,omitempty"`

	// Data is the typed, per-error-type payload: WHAT the error is. Closed
	// schema per Type. Read to render sections and by any future view.
	Data json.RawMessage `json:"data" swaggertype:"object"`

	// SourceID / SourceType identify the row this error originated on
	// (polymorphic, same shape as OwnerID/OwnerType). Set at the record site,
	// e.g. ("runner_job_execution_results", "<result id>"). Enables a future
	// JOINable view without a separate error table.
	SourceID   string `json:"source_id,omitempty"`
	SourceType string `json:"source_type,omitempty"`

	// Hints is the open annotation/directive bag: HOW to handle or present the
	// error. Canonical keys (Hint*) are honored by specific consumers.
	Hints Hints `json:"hints,omitempty"`
}

CompositeErrorData is the JSONB GORM column attached to owner rows. It captures a typed CompositeError's payload along with its headline message and structured sections, all frozen at write time.

To use, add this to a GORM model struct:

CompositeError *compositeerrors.CompositeErrorData `json:"composite_error,omitempty" gorm:"type:jsonb"`

func New(e CompositeError, opts ...Option) (*CompositeErrorData, error)

func (CompositeErrorData) GormDataType() string

func (c *CompositeErrorData) Scan(value any) error

func (c *CompositeErrorData) Value() (driver.Value, error)

type Hints ¶ added in v0.19.1024

type Hints map[string]string

Hints is an open annotation bag carried on a CompositeError. Unlike Data (which is the typed, per-error-type description of WHAT the error is), Hints describes HOW the platform should handle or present the error. It is cross-cutting and not tied to any single error type's schema.

Values are always strings to keep a single, unambiguous wire format inside the JSONB payload (a map[string]any would round-trip numbers as float64 and drift). Consumers read canonical keys through the typed accessors below, which own the coercion. Non-scalar values belong in Data, not Hints.

The bag is open, but the keys a consumer ACTS ON are a documented, closed set (the Hint* constants). An error may attach arbitrary annotation keys, but only canonical keys carry behavior.

func NewHints() Hints

func (h Hints) Clone() Hints

func (h Hints) DocsURL() string

func (h Hints) RequeueAfter() (time.Duration, bool)

func (h Hints) SkipAutoRetry() bool

func (h Hints) Terminal() bool

func (h Hints) WithDocsURL(url string) Hints

func (h Hints) WithRequeueAfter(d time.Duration) Hints

func (h Hints) WithSkipAutoRetry() Hints

func (h Hints) WithTerminal() Hints

type HintsProvider ¶ added in v0.19.1024

type HintsProvider interface {
	Hints() Hints
}

HintsProvider is an optional capability implemented by typed CompositeError values that want to attach hints. New() captures Hints() at write time, the same way it captures Sections().

type Option ¶ added in v0.19.1024

type Option func(*CompositeErrorData)

Option customizes a CompositeErrorData at construction. Options apply record-site context (e.g. provenance) that the typed error doesn't know.

func WithSource(sourceType, sourceID string) Option

type Section ¶

type Section struct {
	Heading string      `json:"heading"`
	Body    string      `json:"body"`
	Kind    SectionKind `json:"kind,omitempty"`
}

Section is a heading + body attached to a CompositeError. Kind controls how the body is rendered and whether it is treated as trusted (see SectionKind).

func CodeSection(heading, body string) Section

func MarkdownSection(heading, body string) Section

func TextSection(heading, body string) Section

type SectionKind ¶ added in v0.19.1055

type SectionKind string

SectionKind tells the renderer how to interpret a Section body, and, for security, whether the body is trusted. Untrusted content (raw tool output, values extracted from an error) must never be rendered as markdown: the dashboard's markdown pipeline enables raw HTML and runs custom-component extraction over the string, so a crafted payload could escape a code fence and inject content. Use SectionText/SectionCode for anything derived from tool output, and reserve SectionMarkdown for hand-authored, trusted prose.

const (
	// SectionMarkdown renders the body as markdown. Only for trusted, code-
	// authored content. It is also the assumed kind for legacy records that
	// predate this field.
	SectionMarkdown SectionKind = "markdown"
	// SectionText renders the body as escaped plain text, preserving
	// whitespace. Safe for untrusted single- or multi-line values.
	SectionText SectionKind = "text"
	// SectionCode renders the body as an escaped monospace code block. Safe for
	// untrusted raw output (terraform/helm logs, an AWS response, ...).
	SectionCode SectionKind = "code"
)

type Severity ¶

type Severity string

Severity controls how the dashboard presents an error.

const (
	SeverityFatal   Severity = "fatal"
	SeverityError   Severity = "error"
	SeverityWarning Severity = "warning"
	SeverityInfo    Severity = "info"
)

type Type ¶

type Type string

Type is the discriminator string for a CompositeError implementation (e.g. "terraform.error", "validation").