Documentation
¶
Overview ¶
Package template renders Flow-I's {{…}} templates. Each placeholder holds an expr-lang expression evaluated against a Scope of namespaces (env, vars, nodes, secret, request, response, …).
Undefined references are errors unless guarded with ?? or ?., so typos surface instead of sending empty values. Values read from the secret namespace mark the result as tainted, which lets callers mask whole fields that were built from secrets.
Before compiling, expressions are rewritten so the spec's notation works: generators ($first-name, $int(1, 9)) become calls, duration literals (2s, 800ms) become duration("…"), and comparisons with empty match null, "", and empty lists and maps.
Index ¶
- Variables
- func ApplyEmpty(v any, p EmptyPolicy) (value string, keep bool, err error)
- func CheckSyntax(src string) error
- func NewSeed() uint64
- func String(v any) string
- func Undefined(err error) []string
- type EmptyPolicy
- type Generation
- type Generator
- type GeneratorFunc
- type Namespace
- type Reference
- type Result
- type Scope
- type SyntaxError
- type Template
- type UndefinedError
- type UnknownGeneratorError
Constants ¶
This section is empty.
Variables ¶
var ErrEmpty = errors.New("value is empty")
ErrEmpty is returned by ApplyEmpty under EmptyError.
Functions ¶
func ApplyEmpty ¶
func ApplyEmpty(v any, p EmptyPolicy) (value string, keep bool, err error)
ApplyEmpty turns a header or query value into text. keep is false when the field should be left out.
func CheckSyntax ¶
CheckSyntax reports whether src, a boolean expression without braces (an assert check or a when condition), compiles.
func NewSeed ¶
func NewSeed() uint64
NewSeed returns a random non-zero seed for runs that were given none; it is reported so the run can be repeated.
Types ¶
type EmptyPolicy ¶
type EmptyPolicy int
EmptyPolicy says what to do with a null or empty-string value in a header or query parameter (design §6.2).
const ( EmptyKeep EmptyPolicy = iota + 1 EmptyOmit EmptyError )
Empty policies.
func ParseEmptyPolicy ¶
func ParseEmptyPolicy(s string) (EmptyPolicy, error)
ParseEmptyPolicy reads the empty setting ("keep", "omit", "error").
type Generation ¶
type Generation struct {
// contains filtered or unexported fields
}
Generation produces generator values for one run from one seed, so a run's generated data can be reproduced. Not safe for concurrent use.
func NewGeneration ¶
func NewGeneration(seed uint64, now func() time.Time) *Generation
NewGeneration starts a generation from seed; now supplies the clock.
func (*Generation) Func ¶
func (g *Generation) Func() GeneratorFunc
Func returns the GeneratorFunc for a Scope.
type Generator ¶
type Generator struct {
Name string
Description string
Args string // human signature, e.g. "(min, max)"; "" when it takes none
Fn func(f *gofakeit.Faker, now time.Time, args []any) (any, error)
}
Generator is one $name generator. Description and Args drive the generated reference docs.
type GeneratorFunc ¶
GeneratorFunc produces the value of a $generator.
type Namespace ¶
Namespace is a lazily resolved scope, such as secrets that unlock the vault on first read. Lookup reports whether the key exists.
type Reference ¶
Reference is a variable a template or expression reads, as its constant steps: {{nodes.login.token}} is ["nodes", "login", "token"] and an index step [0] is "0". A step that is not a constant ends the chain. Guarded is set when every use of the path is under ?? or ?., so a miss is nil, not an error.
func References ¶
References lists what src reads, in source order and without duplicates (a path used both guarded and unguarded is unguarded). expression says src is a bare expression (an assert check, a when) rather than a {{…}} template. Syntax errors are *SyntaxError.
type Result ¶
type Result struct {
Value any
// Tainted is true when a secret.* value was read, so callers can mask
// the whole field (a Basic header built from a secret, for example).
Tainted bool
}
Result is an evaluated template.
func Check ¶
Check evaluates src, a boolean expression without braces (assert checks, when conditions).
func RenderJSON ¶
RenderJSON renders a JSON body template so the result stays valid JSON whatever the values contain. Each placeholder is encoded by where it sits in the JSON text:
- the whole content of a string literal ("{{x}}"): a string becomes a JSON string, nil becomes null, anything else a quoted string;
- inside a longer string literal ("Bearer {{x}}"): the text is escaped;
- outside any string ({"n": {{x}}}): the value is JSON-encoded.
type Scope ¶
type Scope struct {
// Values maps namespace names (env, vars, nodes, secret, request,
// response, status, with, …) to map[string]any, []any, Namespace or
// scalar values.
Values map[string]any
// Bare lists the namespaces searched, narrowest first, for a name
// written without a namespace ({{email}}).
Bare []string
// Gen produces generator values; nil makes any generator use fail.
Gen GeneratorFunc
// Lenient makes undefined references nil instead of errors. Used for
// the best-effort view of a request that pre-hooks read.
Lenient bool
}
Scope is what expressions can read.
type SyntaxError ¶
SyntaxError reports a template that cannot be parsed. Offset is the byte offset in the template source of the placeholder at fault.
func (*SyntaxError) Error ¶
func (e *SyntaxError) Error() string
type Template ¶
type Template struct {
// contains filtered or unexported fields
}
Template is a parsed template. The zero value renders "".
func Parse ¶
Parse splits src into text and {{…}} expressions and compiles each expression. A "}}" outside a placeholder is ordinary text (JSON bodies are full of them); a "{{" without a closing "}}" is an error.
func (Template) Eval ¶
Eval evaluates the template. A template that is exactly one placeholder keeps the expression's type; anything else is a string.
func (Template) References ¶
References lists the variables the template reads, as dotted paths ("env.base_url", "email"), in order of appearance.
type UndefinedError ¶
type UndefinedError struct{ Name string }
UndefinedError reports a reference that does not resolve. Name is the full dotted path as written, e.g. "nodes.login.token".
func (*UndefinedError) Error ¶
func (e *UndefinedError) Error() string
type UnknownGeneratorError ¶
type UnknownGeneratorError struct{ Name string }
UnknownGeneratorError reports a $generator that does not exist, or any generator use when the scope has none.
func (*UnknownGeneratorError) Error ¶
func (e *UnknownGeneratorError) Error() string
Source Files