configdecode

Documentation

Overview

Package configdecode converts YAML and JSON configuration bytes into a uniform, position-aware node tree and provides strict decoding primitives on top of it.

The node tree is intentionally decoupled from the YAML dependency's token types and from Go's encoding/json internals, so that the rest of BatchWeaver depends only on this stable representation. Positions are one-based lines and columns with a repository- or user-relative file name attached by the caller.

Index

• Constants
• func AsBool(node *Node) (bool, bool)
• func AsInt(node *Node) (int64, bool)
• func AsString(node *Node) (string, bool)
• func CheckUnknownFields(node *Node, known []string, diags *diagnostics.Collection)
• func TypeName(node *Node) string
• type Kind
• type MapEntry
• type Node
  • func ParseJSON(file string, src []byte) (*Node, diagnostics.Collection)
  • func ParseYAML(file string, src []byte) (*Node, diagnostics.Collection)
  • func (n *Node) Get(key string) (*Node, diagnostics.Position, bool)
  • func (n *Node) IsMapping() bool
  • func (n *Node) IsNull() bool
  • func (n *Node) IsScalar() bool
  • func (n *Node) IsSequence() bool
  • func (n *Node) Keys() []string
• type ScalarType

Constants

const (
	// CodeSyntax reports a YAML or JSON syntax error.
	CodeSyntax diagnostics.Code = "BWCFG001"
	// CodeDuplicateKey reports a duplicate mapping key.
	CodeDuplicateKey diagnostics.Code = "BWCFG002"
	// CodeMultipleDocuments reports more than one document in a source.
	CodeMultipleDocuments diagnostics.Code = "BWCFG003"
	// CodeTrailingContent reports trailing content after a JSON document.
	CodeTrailingContent diagnostics.Code = "BWCFG004"
	// CodeTypeMismatch reports a value of an unexpected kind.
	CodeTypeMismatch diagnostics.Code = "BWCFG005"
	// CodeInvalidEnum reports an unknown enumeration value.
	CodeInvalidEnum diagnostics.Code = "BWCFG006"
	// CodeInvalidDuration reports an invalid duration value.
	CodeInvalidDuration diagnostics.Code = "BWCFG007"
	// CodeInvalidByteSize reports an invalid byte-size value.
	CodeInvalidByteSize diagnostics.Code = "BWCFG008"
	// CodeUnsupportedConstruct reports a disallowed YAML construct.
	CodeUnsupportedConstruct diagnostics.Code = "BWCFG009"
	// CodeLimitExceeded reports that a size or count limit was exceeded.
	CodeLimitExceeded diagnostics.Code = "BWCFG010"
	// CodeIncludeError reports a failure to read or resolve an include.
	CodeIncludeError diagnostics.Code = "BWCFG011"
	// CodeIncludeCycle reports an include cycle.
	CodeIncludeCycle diagnostics.Code = "BWCFG012"
	// CodeAbsoluteInclude reports a disallowed absolute include path.
	CodeAbsoluteInclude diagnostics.Code = "BWCFG013"
	// CodeRemoteInclude reports a forbidden remote include.
	CodeRemoteInclude diagnostics.Code = "BWCFG014"
	// CodeMissingField reports a missing required field.
	CodeMissingField diagnostics.Code = "BWCFG015"
	// CodeUnsupportedVersion reports an unsupported schema version.
	CodeUnsupportedVersion diagnostics.Code = "BWCFG016"
	// CodeNotFound reports that no configuration file was found.
	CodeNotFound diagnostics.Code = "BWCFG017"
	// CodeAmbiguous reports multiple candidate configuration files.
	CodeAmbiguous diagnostics.Code = "BWCFG018"
	// CodeDuplicateOperation reports a conflicting operation definition.
	CodeDuplicateOperation diagnostics.Code = "BWCFG019"
	// CodeSecurity reports a configuration security violation.
	CodeSecurity diagnostics.Code = "BWCFG020"
	// CodeUnknownField reports an unknown field.
	CodeUnknownField diagnostics.Code = "BWCFG021"
	// CodeInvalidValue reports a value that is invalid for its field.
	CodeInvalidValue diagnostics.Code = "BWCFG022"
	// CodeSemantic reports a semantic validation failure.
	CodeSemantic diagnostics.Code = "BWCFG023"
)

Configuration diagnostic codes (BWCFG range). These are shared across the configuration pipeline (decode, load, normalize, validate) and documented in docs/reference/diagnostic-codes.md. Once committed, a code keeps its meaning.

Functions

func AsBool

func AsBool(node *Node) (bool, bool)

AsBool returns the value of a boolean scalar and true, or false otherwise.

func AsInt

func AsInt(node *Node) (int64, bool)

AsInt returns the value of an integer scalar and true, or false otherwise.

func AsString

func AsString(node *Node) (string, bool)

AsString returns the value of a string scalar and true, or false for any other node. It is strict: numeric and boolean scalars are not treated as strings.

func CheckUnknownFields

func CheckUnknownFields(node *Node, known []string, diags *diagnostics.Collection)

CheckUnknownFields reports a diagnostic for each entry of node whose key is not in known, offering a "did you mean" suggestion when a close match exists.

func TypeName

func TypeName(node *Node) string

TypeName returns a human-readable name for a node's kind.

Types

type Kind

type Kind uint8

Kind classifies a node in the decoded tree.

const (
	// KindScalar is a leaf value.
	KindScalar Kind = iota
	// KindMapping is an ordered set of key/value entries.
	KindMapping
	// KindSequence is an ordered list of values.
	KindSequence
)

type MapEntry

type MapEntry struct {
	// Key is the mapping key.
	Key string
	// KeyPos is the source position of the key.
	KeyPos diagnostics.Position
	// Value is the associated value node.
	Value *Node
}

MapEntry is one key/value pair in a mapping node, retaining the key's source position for diagnostics.

type Node

type Node struct {
	// Kind is the node kind.
	Kind Kind
	// Pos is the source position of the node's value.
	Pos diagnostics.Position

	// ScalarType and Value are meaningful only for scalar nodes.
	ScalarType ScalarType
	Value      string

	// Entries is meaningful only for mapping nodes.
	Entries []MapEntry

	// Elems is meaningful only for sequence nodes.
	Elems []*Node
}

Node is a position-aware element of a decoded configuration document.

func ParseJSON

func ParseJSON(file string, src []byte) (*Node, diagnostics.Collection)

ParseJSON parses JSON bytes into a node tree with accurate positions. It is a small, dependency-free recursive-descent parser so that JSON gains the same position-aware, duplicate-key-rejecting, single-document semantics as YAML. It rejects duplicate object keys and trailing content.

func ParseYAML

func ParseYAML(file string, src []byte) (*Node, diagnostics.Collection)

ParseYAML parses YAML bytes into a node tree, attaching file as the position file name. It rejects multiple documents, duplicate mapping keys, and unsafe YAML constructs (anchors, aliases, tags, and merge keys). On a fatal parse error it returns a nil node and a collection describing the problem.

func (*Node) Get

func (n *Node) Get(key string) (*Node, diagnostics.Position, bool)

Get returns the value node and key position for key, and true when present. For a non-mapping node it returns false.

func (*Node) IsMapping

func (n *Node) IsMapping() bool

IsMapping reports whether the node is a mapping.

func (*Node) IsNull

func (n *Node) IsNull() bool

IsNull reports whether the node is a null scalar.

func (*Node) IsScalar

func (n *Node) IsScalar() bool

IsScalar reports whether the node is a scalar.

func (*Node) IsSequence

func (n *Node) IsSequence() bool

IsSequence reports whether the node is a sequence.

func (*Node) Keys

func (n *Node) Keys() []string

Keys returns the mapping keys in source order, or nil for a non-mapping node.

type ScalarType

type ScalarType uint8

ScalarType records the source type of a scalar so decoding can be strict about, for example, rejecting a bare number where a duration string is required.

const (
	// ScalarString is a string scalar.
	ScalarString ScalarType = iota
	// ScalarInt is an integer scalar.
	ScalarInt
	// ScalarFloat is a floating-point scalar.
	ScalarFloat
	// ScalarBool is a boolean scalar.
	ScalarBool
	// ScalarNull is a null scalar.
	ScalarNull
)