output

Documentation

Index

• func BuildErrorEnvelope(err error, meta map[string]any) map[string]any
• func BuildErrorRecord(err error) map[string]any
• type Context
• type EnvelopeHook
  • func (h EnvelopeHook) Name() string
  • func (h EnvelopeHook) Process(ctx *Context, data any) (any, error)
• type ErrorPayloadBuilder
• type FieldSelectorHook
  • func (h FieldSelectorHook) Name() string
  • func (h FieldSelectorHook) Process(ctx *Context, data any) (any, error)
• type FormatOptions
• type Formatter
• type IOWriter
• type OutputHook
• type Processor
  • func (p *Processor) Process(ctx context.Context, state *Context) error
  • func (p *Processor) RenderError(state *Context, err error) ([]byte, error)

Functions

func BuildErrorEnvelope

func BuildErrorEnvelope(err error, meta map[string]any) map[string]any

BuildErrorEnvelope returns the full {data:null, meta, error} envelope for err. Used by json/ndjson error rendering; table mode uses BuildErrorRecord directly and renders the inner record as a KV table.

func BuildErrorRecord

func BuildErrorRecord(err error) map[string]any

BuildErrorRecord returns the {code, message, retryable, ...} triple for err, suitable for embedding under the "error" key of the envelope. Resolution order:

1. If err (or any error in its chain) implements ErrorPayloadBuilder, use its payload verbatim.
2. Else if err is a *frameworkerrors.CLIError, derive code/message from its fields and retryable from IsRetryable().
3. Fallback for plain errors: code="UNKNOWN", message=err.Error(), retryable=false.

Types

type Context

type Context struct {
	Input   *frameworkadapter.RawInput
	Parsed  *frameworkrouter.ParsedCommand
	Values  map[string]any
	Result  *executor.RawResult
	Options *FormatOptions
}

type EnvelopeHook

type EnvelopeHook struct{}

EnvelopeHook wraps the result payload in {data, meta, error} when --envelope is set. It only fires on the success path; the error-path envelope (which must appear regardless of --envelope per the design spec §"错误处理契约") is built by BuildErrorEnvelope and emitted through Processor.RenderError — see processor.go and pkg/runtime/cliapp/app.go (executeParsed → renderErrorEnvelope) for the full flow. Keeping success and error envelope logic separate means EnvelopeHook never has to reason about nil data or partially-populated state.Result.

func (EnvelopeHook) Name

func (h EnvelopeHook) Name() string

func (EnvelopeHook) Process

func (h EnvelopeHook) Process(ctx *Context, data any) (any, error)

type ErrorPayloadBuilder

type ErrorPayloadBuilder interface {
	ErrorPayload() map[string]any
}

ErrorPayloadBuilder lets domain-specific error types (e.g. product-level MeegleError) plug their own {code, message, retryable, ...} shape into the unified envelope. When the implementation returns a non-nil map, its contents replace the default record built from CLIError fields; the caller MUST include at least "code", "message", and "retryable" keys so agents parsing the envelope can rely on the documented contract.

type FieldSelectorHook

type FieldSelectorHook struct{}

func (FieldSelectorHook) Name

func (h FieldSelectorHook) Name() string

func (FieldSelectorHook) Process

func (h FieldSelectorHook) Process(ctx *Context, data any) (any, error)

type FormatOptions

type FormatOptions struct {
	Mode     string
	Select   []string
	Envelope bool
	Verbose  bool
	// ErrorEnvelope is set by Processor.RenderError when formatting the
	// pre-built error envelope `{data:null, meta, error:{code,message,retryable}}`.
	// Downstream formatters must not re-wrap or peel the payload, and table
	// mode renders the inner error record as a KV table rather than the full
	// envelope. Not user-settable.
	ErrorEnvelope bool
}

type Formatter

type Formatter interface {
	Format(data any, opts *FormatOptions) ([]byte, error)
}

type IOWriter

type IOWriter interface {
	Write(ctx *Context, payload []byte) error
}

type OutputHook

type OutputHook interface {
	Name() string
	Process(ctx *Context, data any) (any, error)
}

type Processor

type Processor struct {
	Hooks     []OutputHook
	Formatter Formatter
	Writer    IOWriter
	Options   *FormatOptions
}

func (*Processor) Process

func (p *Processor) Process(ctx context.Context, state *Context) error

func (*Processor) RenderError

func (p *Processor) RenderError(state *Context, err error) ([]byte, error)

RenderError formats err as the unified error envelope and returns the rendered bytes for stderr. The hook chain is intentionally bypassed — hooks are designed for success data and assume a non-error payload. The formatter receives FormatOptions.ErrorEnvelope=true so downstream (e.g. CompositeFormatter) can switch table mode to render the inner error record as KV and skip wrapper-unwrapping. Returns (nil, nil) when err is nil.

Callers (usually App.Execute) should write the returned bytes to stderr and propagate the original err so the process exit code stays correct.