config

package
v1.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 28, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Overview

Package config builds the run configuration a command line assembles before an entry ever runs: typed variables and secrets from the command line, properties files and environment variables, plus the small set of options read from a config file. It has no knowledge of cobra flags or the engine; internal/cli composes its results into engine.Options, applying the command line's own precedence on top.

Index

Constants

View Source
const ProjectFileName = "sonde.yaml"

ProjectFileName is the name sonde.yaml discovery looks for.

Variables

This section is empty.

Functions

func AddSecret

func AddSecret(secrets map[string]string, name string, v value.Value) error

AddSecret inserts name/v into secrets. It errors if name is already present: a secret can be defined once, from a single source.

func BuildSecrets

func BuildSecrets(env Env, secretsFiles, secrets []string) (map[string]string, error)

BuildSecrets merges secret sources in the same order as BuildVariables: HURL_SECRET_*/SONDE_SECRET_* env vars, then --secrets-file files, then --secret assignments. Unlike a variable, a name defined by more than one source is an error: a secret can never be reassigned.

func BuildVariables

func BuildVariables(env Env, variablesFiles, variables []string) (map[string]value.Value, error)

BuildVariables merges variable sources in the upstream precedence order (lowest to highest): HURL_VARIABLE_*/SONDE_VARIABLE_* env vars, then --variables-file files (in the order given, each read in full), then --variable "name=value" assignments (in the order given). A name defined by more than one source keeps the value of the last one.

func CheckNoClash

func CheckNoClash(variables map[string]value.Value, secrets map[string]string) error

CheckNoClash errors if any name is defined as both a variable and a secret.

func EmitProject

func EmitProject(p ProjectSkeleton) ([]byte, error)

EmitProject renders p as a "version: 1" sonde.yaml skeleton. Key order is deterministic (map keys are sorted by the YAML encoder) and the result is parseable by LoadProject.

func EmitVariables

func EmitVariables(vars map[string]string) []byte

EmitVariables renders vars as a variables/secrets file: one "name=value" line per entry (ParseProperties's format, internal/config/properties.go), sorted by name for determinism. A value must not contain a newline; the format has no way to escape one.

func InferValue

func InferValue(raw string) (value.Value, error)

InferValue infers a typed value from raw text: the literals true, false and null, an integer, an unsigned all-digit big integer, a floating point number, a double-quoted string, or else the text itself as a string.

func IsReserved

func IsReserved(name string) bool

IsReserved reports whether name conflicts with a template function.

func ParseDuration

func ParseDuration(s string, defaultUnit DurationUnit) (time.Duration, error)

ParseDuration parses a duration such as "5", "5s" or "500ms". A bare number is read in defaultUnit; the recognized suffixes are ms, s, m and h.

func ParseValue

func ParseValue(raw string, kind TypeKind) (value.Value, error)

ParseValue turns raw text into a typed value under kind.

func SelectEnv

func SelectEnv(flagEnv, sondeEnvVar, defaultEnv string) string

SelectEnv resolves the environment to run with, highest precedence first: an explicit --env flag, then the SONDE_ENV process environment variable, then sonde.yaml's defaults.env. An empty result means no environment was selected by any of the three (not an error by itself: Resolve("") returns no sonde.yaml variables or secrets).

Types

type Assignment

type Assignment struct {
	Name  string
	Value value.Value
}

Assignment is one "name=value" pair from the command line or a properties file.

func ParseAssignment

func ParseAssignment(s string, kind TypeKind) (Assignment, error)

ParseAssignment parses "name=value" text (as given to --variable or --secret) under kind.

func ParseProperties

func ParseProperties(data []byte, kind TypeKind) ([]Assignment, error)

ParseProperties parses a variables/secrets file: one "name=value" assignment per line, blank lines and lines starting with '#' (after trimming) skipped. Line endings may be LF or CRLF.

A malformed secrets line (kind == Forced) never echoes its text in the resulting error: the line may itself carry a secret value not yet registered for redaction, so only its line number is reported.

type Defaults

type Defaults struct {
	// Env is the environment used when neither --env nor SONDE_ENV is set.
	Env string
	// Jobs is the default --jobs value; 0 means unset (engine default).
	Jobs int
}

Defaults is a sonde.yaml "defaults:" block.

type DurationUnit

type DurationUnit int

DurationUnit is the unit assumed for a duration with no explicit suffix.

const (
	Millisecond DurationUnit = iota
	Second
	Minute
	Hour
)

Duration units, matching the upstream duration suffixes.

func (DurationUnit) String

func (u DurationUnit) String() string

type Env

type Env map[string]string

Env is a snapshot of process environment variables, or a fake one built for tests. Every option accessor mirrors an upstream HURL_<NAME> variable, with a SONDE_<NAME> variant of the same name taking precedence when both are set.

func FromOSEnviron

func FromOSEnviron() Env

FromOSEnviron snapshots the current process environment.

func (Env) ApplySecretEnvVars

func (e Env) ApplySecretEnvVars(secrets map[string]string) error

ApplySecretEnvVars inserts every HURL_SECRET_*/SONDE_SECRET_* into secrets, erroring on a name defined twice.

func (Env) ApplyVariableEnvVars

func (e Env) ApplyVariableEnvVars(variables map[string]value.Value) error

ApplyVariableEnvVars inserts every HURL_VARIABLE_*/SONDE_VARIABLE_* into variables, inferring each value's type.

func (Env) Bool

func (e Env) Bool(name string) (v, ok bool)

Bool reads a boolean option: "1"/"true" (case-insensitive) is true, "0"/"false" is false, anything else (including absence) reports not set.

func (Env) Color

func (e Env) Color(base bool) bool

Color resolves color on/off: NO_COLOR (any value, standard convention) disables; else HURL_NO_COLOR/SONDE_NO_COLOR; else HURL_COLOR/SONDE_COLOR; else base.

func (Env) Duration

func (e Env) Duration(name string, defaultUnit DurationUnit) (d time.Duration, ok bool, err error)

Duration reads a duration option in defaultUnit when its text has no suffix.

func (Env) ErrorFormat

func (e Env) ErrorFormat() (format string, ok bool, err error)

ErrorFormat reads HURL_ERROR_FORMAT/SONDE_ERROR_FORMAT: "short" or "long".

func (Env) FilePath

func (e Env) FilePath() (string, bool)

FilePath returns the config file path, in order of precedence $XDG_CONFIG_HOME/hurl/config if XDG_CONFIG_HOME is set, else $HOME/config/hurl/config if HOME is set (this second form reproduces the upstream 8.0.1 path exactly, including its "config" rather than ".config" component; sonde matches it for parity even though the upstream doc comment says ".config").

func (Env) FollowLocation

func (e Env) FollowLocation(base bool) (bool, error)

FollowLocation resolves --location from HURL_LOCATION/HURL_LOCATION_TRUSTED, erroring on the contradictory combination location=false, location-trusted=true.

func (Env) HTTPVersion

func (e Env) HTTPVersion() (version string, ok bool)

HTTPVersion resolves "1.0", "1.1", "2" or "3" from HURL_HTTP3, then HURL_HTTP2, then HURL_HTTP11, then HURL_HTTP10, mirroring the cascading rule of each flag implying the version below it when set false.

func (Env) Headers

func (e Env) Headers() (headers []string, ok bool, err error)

Headers reads HURL_HEADER/SONDE_HEADER: one or more "Name:value" pairs separated by '|'.

func (Env) IPResolve

func (e Env) IPResolve() (family string, ok bool)

IPResolve resolves "4" or "6" from HURL_IPV6, then HURL_IPV4.

func (Env) Int

func (e Env) Int(name string) (v int64, ok bool, err error)

Int reads an integer option.

func (Env) IsCI

func (e Env) IsCI() bool

IsCI reports whether CI or TF_BUILD is set, signalling a CI environment.

func (Env) Lookup

func (e Env) Lookup(name string) (val, key string, ok bool)

Lookup returns the value of SONDE_<name> or, if unset, HURL_<name>, and the actual variable name it came from (for error messages).

func (Env) SecretEnvVars

func (e Env) SecretEnvVars() map[string]string

SecretEnvVars returns every HURL_SECRET_<name>/SONDE_SECRET_<name> as name/raw-value pairs; a SONDE_SECRET_<name> wins over HURL_SECRET_<name> of the same name.

func (Env) String

func (e Env) String(name string) (v string, ok bool)

String reads a plain string option.

func (Env) Uint

func (e Env) Uint(name string) (v uint64, ok bool, err error)

Uint reads a non-negative integer option.

func (Env) VariableEnvVars

func (e Env) VariableEnvVars() map[string]string

VariableEnvVars returns every HURL_VARIABLE_<name>/SONDE_VARIABLE_<name> as name/raw-value pairs; a SONDE_VARIABLE_<name> wins over HURL_VARIABLE_<name> of the same name.

func (Env) Verbosity

func (e Env) Verbosity() (level string, ok bool, err error)

Verbosity resolves "brief", "verbose" or "debug" from HURL_VERBOSE, then HURL_VERY_VERBOSE, then HURL_VERBOSITY (SONDE_ variants take precedence per option, as elsewhere).

type Environment

type Environment struct {
	// Variables is the "variables:" map, already typed.
	Variables map[string]value.Value
	// VariablesFiles is "variables_files:", as written in sonde.yaml
	// (relative to Dir), applied in order after Variables.
	VariablesFiles []string
	// SecretsFiles is "secrets_files:", as written in sonde.yaml
	// (relative to Dir).
	SecretsFiles []string
}

Environment is one "environments:<name>:" entry.

type EnvironmentSkeleton

type EnvironmentSkeleton struct {
	// Variables is the "variables:" map; every value is written as a YAML
	// string scalar (quoted where needed), matching this skeleton's plain
	// string values.
	Variables map[string]string
	// SecretsFiles is the "secrets_files:" list.
	SecretsFiles []string
}

EnvironmentSkeleton is one "environments:<name>:" entry for EmitProject.

type FileOptions

type FileOptions struct {
	// Verbose is set true by a bare "--verbose" line.
	Verbose bool
	// Headers accumulates one entry per "--header" line, in file order.
	Headers []string
	// MaxRedirs is set by a "--max-redirs" line; nil means absent.
	MaxRedirs *int
	// UserAgent is set by a "--user-agent" line; nil means absent.
	UserAgent *string
}

FileOptions are the options a config file may set.

func LoadConfigFile

func LoadConfigFile(path string) (FileOptions, error)

LoadConfigFile reads and parses the config file at path. An empty path, or a path that does not exist, returns zero FileOptions and no error.

func ParseFile

func ParseFile(content string) (FileOptions, error)

ParseFile parses config file content: lines of "--option[ value]" or "--option=value", blank lines, lines starting with '#' and horizontal whitespace ignored. Recognized options are --verbose (no value), --header, --max-redirs and --user-agent (values may be double-quoted, and a quoted value may itself span multiple lines). The parser mirrors the upstream implementation position for position, so a parse error's line:col matches it exactly.

type OpenAPI

type OpenAPI struct {
	// Spec is the contract file, an absolute path inside the project
	// directory. A remote spec can only be given on the command line.
	Spec string
	// Server replaces the spec's servers for matching request URLs.
	Server string
	// Strict makes a request no operation matches a failure.
	Strict bool
	// ExcludeOperations are operations never validated, "METHOD /path"
	// with the path as written in the spec ("GET /health").
	ExcludeOperations []string
	// ExcludeFiles are globs of request files never validated, relative to
	// the project directory ("**" matches any number of directories).
	ExcludeFiles []string
}

OpenAPI is a sonde.yaml "openapi:" block: the contract every response of the project's files is validated against.

func (*OpenAPI) ExcludesFile

func (o *OpenAPI) ExcludesFile(dir, file string) bool

ExcludesFile reports whether file (a request file path) matches one of ExcludeFiles, taken relative to dir (the project directory).

type Project

type Project struct {
	// Path is the sonde.yaml file this project was loaded from.
	Path string
	// Dir is the directory containing Path; variables_files and
	// secrets_files resolve relative to it.
	Dir string
	// Version is the schema version; LoadProject rejects anything but 1.
	Version int
	// Environments is every "environments:" entry, by name.
	Environments map[string]Environment
	// Defaults holds "defaults:".
	Defaults Defaults
	// OpenAPI holds "openapi:" (nil when absent).
	OpenAPI *OpenAPI
}

Project is a loaded and validated sonde.yaml file: schema owned by docs/sonde-yaml.md. It never grants file access beyond its own directory (architecture.md §9): variables_files and secrets_files are read through a sandbox rooted there.

func LoadProject

func LoadProject(path string) (*Project, error)

LoadProject reads and strictly validates the sonde.yaml file at path: an unknown key or a value of the wrong type is rejected with the offending line; version must be 1; every variables_files/secrets_files path is checked against the sandbox rooted at path's directory (an absolute path, a path escaping that directory with "..", or one that would escape it through a symbolic link is rejected), without requiring the referenced file to exist yet (only the environment actually selected by Resolve needs to exist).

func (*Project) Resolve

func (p *Project) Resolve(env string) (variables map[string]value.Value, secrets map[string]string, err error)

Resolve returns the typed variables and secrets of env: its "variables" map, then its "variables_files" applied in order on top (a name in a later file wins), giving the sonde.yaml precedence tier described by docs/sonde-yaml.md. "secrets_files" is loaded the same way --secrets-file is: a name already defined by an earlier secrets source is an error.

An empty env returns empty, non-nil maps and no error: a run with no environment selected has no sonde.yaml variables or secrets. A non-empty env not present in p.Environments is an error listing the environments that do exist.

func (*Project) VariableNames

func (p *Project) VariableNames(env string) (map[string]VariableSource, error)

VariableNames returns the names env defines and where each comes from, for callers (the LSP) that only need names, never values. Precedence matches Resolve: variables, then variables_files in order, then secrets_files in order, each later source's names winning on a clash, via the same walkEnvironment both share.

Unlike Resolve, a file that can't be read or parsed does not discard everything collected so far: the walk continues through every remaining variables_files/secrets_files entry, and the first error encountered (if any) is returned alongside every name that could still be determined. A secrets_files name already used by an earlier secrets source is reported as its own error (AddSecret's message, the same one a run would fail with), and that one name is skipped.

An empty env returns an empty, non-nil map and no error, like Resolve; a non-empty env absent from p.Environments is an error listing the environments that do exist (with no partial result, since no environment means nothing to collect from either).

type ProjectCache

type ProjectCache struct {
	// contains filtered or unexported fields
}

ProjectCache finds the nearest ancestor sonde.yaml for a directory, memoizing the result per directory so a repeated lookup (common across input files sharing a directory tree) walks the filesystem only once. It is safe for concurrent use.

func NewProjectCache

func NewProjectCache() *ProjectCache

NewProjectCache returns an empty ProjectCache.

func (*ProjectCache) FindProject

func (c *ProjectCache) FindProject(dir string) (path string, ok bool, err error)

FindProject returns the path of the nearest sonde.yaml above (and including) dir: dir itself, then each parent in turn, stopping at the first sonde.yaml found, at a directory containing ".git" (inclusive: that directory's own sonde.yaml is still eligible, but discovery never looks above it), or at the filesystem root. ok is false when none exists in that range. A candidate sonde.yaml that is not owned by the current user, or that is writable by group or others, is treated as absent (a warning is recorded, see TakeWarnings) rather than used: see docs/sonde-yaml.md, Discovery, on why the walk is bounded this way.

func (*ProjectCache) TakeWarnings

func (c *ProjectCache) TakeWarnings() []string

TakeWarnings drains and returns every discovery warning accumulated so far (for example, a candidate sonde.yaml ignored for failing the ownership/permission check — see docs/sonde-yaml.md, Discovery), clearing them. A caller that never calls it simply never sees the warnings; LoadProject and Resolve never fail because of them. Safe for concurrent use.

type ProjectSkeleton

type ProjectSkeleton struct {
	// Environments is every "environments:" entry, by name.
	Environments map[string]EnvironmentSkeleton
	// DefaultEnv is "defaults.env"; "" omits the "defaults:" block.
	DefaultEnv string
	// OpenAPISpec is "openapi.spec"; "" omits the "openapi:" block.
	OpenAPISpec string
}

ProjectSkeleton is the data EmitProject renders to a sonde.yaml skeleton.

type TypeKind

type TypeKind int

TypeKind selects how a raw "name=value" text turns into a typed value.

const (
	// Inferred infers the value's type from its text (used for variables).
	Inferred TypeKind = iota
	// Forced always produces a string (used for secrets).
	Forced
)

Type kinds.

type VariableSource

type VariableSource struct {
	// File is the variables_files/secrets_files path (as written in
	// sonde.yaml, relative to the project), or "" for an inline
	// "variables:" entry.
	File string
	// Secret is set for a secrets_files entry: only its name is known,
	// its value is never returned or kept in the result. The value is
	// still decoded from the file (ParseProperties needs to, to find the
	// name and to detect a reassigned secret), but is discarded as soon as
	// that check is done and never appears in VariableNames' return.
	Secret bool
}

VariableSource says where one of an environment's variables comes from.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL