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
- Variables
- func AddSecret(secrets map[string]string, name string, v value.Value) error
- func BuildSecrets(env Env, secretsFiles, secrets []string) (map[string]string, error)
- func BuildVariables(env Env, variablesFiles, variables []string) (map[string]value.Value, error)
- func CheckNoClash(variables map[string]value.Value, secrets map[string]string) error
- func EmitProject(p ProjectSkeleton) ([]byte, error)
- func EmitVariables(vars map[string]string) []byte
- func InferValue(raw string) (value.Value, error)
- func IsReserved(name string) bool
- func ParseDuration(s string, defaultUnit DurationUnit) (time.Duration, error)
- func ParseValue(raw string, kind TypeKind) (value.Value, error)
- func PropertyText(v value.Value) (string, error)
- func RemoveProperty(data []byte, name string) []byte
- func SelectEnv(flagEnv, sondeEnvVar, defaultEnv string) string
- func SetProperty(data []byte, name, raw string) ([]byte, error)
- func WriteEdits(root *sandbox.Root, edits []FileEdit) error
- type Assignment
- type Defaults
- type DurationUnit
- type Env
- func (e Env) ApplySecretEnvVars(secrets map[string]string) error
- func (e Env) ApplyVariableEnvVars(variables map[string]value.Value) error
- func (e Env) Bool(name string) (v, ok bool)
- func (e Env) Color(base bool) bool
- func (e Env) Duration(name string, defaultUnit DurationUnit) (d time.Duration, ok bool, err error)
- func (e Env) ErrorFormat() (format string, ok bool, err error)
- func (e Env) FilePath() (string, bool)
- func (e Env) FollowLocation(base bool) (bool, error)
- func (e Env) HTTPVersion() (version string, ok bool)
- func (e Env) Headers() (headers []string, ok bool, err error)
- func (e Env) IPResolve() (family string, ok bool)
- func (e Env) Int(name string) (v int64, ok bool, err error)
- func (e Env) IsCI() bool
- func (e Env) Lookup(name string) (val, key string, ok bool)
- func (e Env) SecretEnvVars() map[string]string
- func (e Env) String(name string) (v string, ok bool)
- func (e Env) Uint(name string) (v uint64, ok bool, err error)
- func (e Env) VariableEnvVars() map[string]string
- func (e Env) Verbosity() (level string, ok bool, err error)
- type EnvMerge
- type Environment
- type EnvironmentSkeleton
- type FileEdit
- type FileOptions
- type OpenAPI
- type Project
- func (p *Project) AddEnvironments(add map[string]EnvironmentSkeleton) ([]FileEdit, error)
- func (p *Project) MergeEnvironments(merges []EnvMerge, add map[string]EnvironmentSkeleton) (edits []FileEdit, kept map[string][]string, err error)
- func (p *Project) MissingSecrets(env string, secrets map[string]string, have func(name string) bool) []string
- func (p *Project) MissingSecretsError(env string, missing []string) error
- func (p *Project) RemoveVariable(env, name string) ([]FileEdit, error)
- func (p *Project) Resolve(env string) (variables map[string]value.Value, secrets map[string]string, err error)
- func (p *Project) SecretsFileFor(env string) (string, error)
- func (p *Project) SetSecret(env, name, secret string) ([]FileEdit, error)
- func (p *Project) SetVariable(env, name string, v value.Value) ([]FileEdit, error)
- func (p *Project) VariableNames(env string) (map[string]VariableSource, error)
- type ProjectCache
- type ProjectSkeleton
- type TypeKind
- type VariableSource
Constants ¶
const ProjectFileName = "sonde.yaml"
ProjectFileName is the name sonde.yaml discovery looks for.
Variables ¶
var ErrEditByHand = errors.New("edit sonde.yaml by hand")
ErrEditByHand reports a sonde.yaml shape the editor does not change (flow style, multi-line values): the user edits it by hand.
Functions ¶
func AddSecret ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
ParseValue turns raw text into a typed value under kind.
func PropertyText ¶ added in v1.4.0
PropertyText is the text of v in a variables file that reads back as v (ParseProperties, Inferred): a string that would read as another type ("true", "42") or with its quotes stripped is double-quoted.
func RemoveProperty ¶ added in v1.4.0
RemoveProperty returns data without any assignment of name.
func SelectEnv ¶
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).
func SetProperty ¶ added in v1.4.0
SetProperty returns data with the assignment of name set to raw (the text after '='): the line of its last assignment (the one that wins) is replaced, or a line is appended.
func WriteEdits ¶ added in v1.4.0
WriteEdits writes edits into root (the project's directory), each atomically: an existing file keeps its permission, a created one gets the edit's Perm. A symbolic link is refused (edited by hand), since an atomic write would replace the link rather than its target.
Types ¶
type Assignment ¶
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 ¶
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 ¶
ApplySecretEnvVars inserts every HURL_SECRET_*/SONDE_SECRET_* into secrets, erroring on a name defined twice.
func (Env) ApplyVariableEnvVars ¶
ApplyVariableEnvVars inserts every HURL_VARIABLE_*/SONDE_VARIABLE_* into variables, inferring each value's type.
func (Env) 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 ¶
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) ErrorFormat ¶
ErrorFormat reads HURL_ERROR_FORMAT/SONDE_ERROR_FORMAT: "short" or "long".
func (Env) FilePath ¶
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 ¶
FollowLocation resolves --location from HURL_LOCATION/HURL_LOCATION_TRUSTED, erroring on the contradictory combination location=false, location-trusted=true.
func (Env) HTTPVersion ¶
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 ¶
Headers reads HURL_HEADER/SONDE_HEADER: one or more "Name:value" pairs separated by '|'.
func (Env) Lookup ¶
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 ¶
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) VariableEnvVars ¶
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.
type EnvMerge ¶ added in v1.4.0
EnvMerge is an imported environment merged into one of the project's: its variables (string values) and the names of its secrets.
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
// Secrets is "secrets:", the names of the secrets the environment
// needs: their values come from its secrets files (which may then be
// missing, as on a fresh clone) or from any other secret source
// (SONDE_SECRET_*, --secret); MissingSecrets says which none sets.
Secrets []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
// Secrets is the "secrets:" list of secret names.
Secrets []string
}
EnvironmentSkeleton is one "environments:<name>:" entry for EmitProject.
type FileEdit ¶ added in v1.4.0
type FileEdit struct {
// Path is the file's absolute path.
Path string
Data []byte
// Perm is the permission of a created file: 0600 for a secrets file.
Perm fs.FileMode
// Created is set when the file does not exist yet.
Created bool
}
FileEdit is the new content of one file of a project.
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 ¶
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
// contains filtered or unexported fields
}
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 ¶
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) AddEnvironments ¶ added in v1.4.0
func (p *Project) AddEnvironments(add map[string]EnvironmentSkeleton) ([]FileEdit, error)
AddEnvironments adds the environments add to sonde.yaml, after its last one (under a new "environments:" when it has none), as an import writes them. A name sonde.yaml has already is an error: the caller leaves it out. The secrets files they name are not created.
func (*Project) MergeEnvironments ¶ added in v1.4.0
func (p *Project) MergeEnvironments(merges []EnvMerge, add map[string]EnvironmentSkeleton) (edits []FileEdit, kept map[string][]string, err error)
MergeEnvironments adds to each environment of merges the variables and secret names ("secrets:") it does not define yet, in order (an earlier merge into the same environment wins), then the environments add (as AddEnvironments). kept are the names left as the project has them, by environment, sorted.
func (*Project) MissingSecrets ¶ added in v1.4.0
func (p *Project) MissingSecrets(env string, secrets map[string]string, have func(name string) bool) []string
MissingSecrets returns the "secrets:" names of env that neither its secrets files (secrets, from Resolve) nor have (any other secret source of the run) set, in their listed order.
func (*Project) MissingSecretsError ¶ added in v1.4.0
MissingSecretsError is the error of a run of env with the listed secrets missing (MissingSecrets): each one, and where to set it.
func (*Project) RemoveVariable ¶ added in v1.4.0
RemoveVariable removes name from every source of environment env.
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) SecretsFileFor ¶ added in v1.4.0
SecretsFileFor is the secrets file a new secret of env goes to: the last one env lists, else secrets/<env>.secrets (as an import names it).
func (*Project) SetSecret ¶ added in v1.4.0
SetSecret sets secret name of environment env to secret. A name that is already a secret is set in its file; any other moves to the last secrets file env lists, or to secrets/<env>.secrets (created with permission 0600 and added to secrets_files), and is removed from the inline variables and the variables files of env.
func (*Project) SetVariable ¶ added in v1.4.0
SetVariable sets variable name of environment env to v in its effective source; a new name is added to the inline "variables:" of env. A name that is a secret stays one, with v's text as its value.
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.
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.