api

package
v0.4.6 Latest Latest
Warning

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

 Go to latest Published: Nov 30, 2020 License: Apache-2.0 Imports: 11 Imported by: 3

Documentation

Overview

Package api contains interfaces that are used throughout the hiera code base

Index

Examples

Constants

View Source 
const HieraConfig = `Hiera::Config`

HieraConfig is an option that can be used to change absolute path of the hiera config. When specified, the HieraRoot and HieraConfigFileName will not have any effect.

View Source 
const HieraConfigFileName = `Hiera::ConfigFileName`

HieraConfigFileName is an option that can be used to change the default file name 'hiera.yaml'

View Source 
const HieraDialect = `Hiera::Dialect`

HieraDialect is an option that can be used to control the dialect of the type parser and streaming capabilities of Hiera. Valid values are "dgo" or "pcore".

View Source 
const HieraFunctions = `Hiera::Functions`

HieraFunctions is an option that can be used to pass custom lookup functions to Hiera. The value must be a dgo.Map with String keys and Function values.

View Source 
const HieraRoot = `Hiera::Root`

HieraRoot is an option key that can be used to change the default root which is the current working directory

View Source 
const HieraScope = `Hiera::Scope`

HieraScope is an option that can be used to pass a variable scope to Hiera. This scope is used by the 'scope' lookup_key provider function and when doing variable interpolations

View Source 
const KindDataDig = FunctionKind(`data_dig`)

KindDataDig is the function kind for data_dig functions

View Source 
const KindDataHash = FunctionKind(`data_hash`)

KindDataHash is the function kind for data_dig functions

View Source 
const KindLookupKey = FunctionKind(`lookup_key`)

KindLookupKey is the function kind for data_dig functions

View Source 
const LcGlob = LocationKind(`glob`)

LcGlob indicates that the location is glob

View Source 
const LcMappedPaths = LocationKind(`mapped_paths`)

LcMappedPaths indicates that the location is thee element array that describes a mapped path

View Source 
const LcPath = LocationKind(`path`)

LcPath indicates that the location is a path in a file system

View Source 
const LcURI = LocationKind(`uri`)

LcURI indicates that the location is URI

Variables

This section is empty.

Functions

func JSONNOtHash 

func JSONNOtHash(path string) error

JSONNOtHash creates an error with a descriptive text and returns it.

func MissingRequiredEnvironmentVariable 

func MissingRequiredEnvironmentVariable(name string) error

MissingRequiredEnvironmentVariable creates an error with a descriptive text and returns it.

func MissingRequiredOption 

func MissingRequiredOption(option string) error

MissingRequiredOption creates an error with a descriptive text and returns it.

func ToMap 

func ToMap(argName string, vi interface{}) dgo.Map

ToMap coerces the given interface{} argument to a dgo.Map and returns it. A panic is raised if the argument cannot be coerced into a map.

func YamlNotHash 

func YamlNotHash(path string) error

YamlNotHash creates an error with a descriptive text and returns it.

Types

type Config 

type Config interface {
	// Root returns the directory holding this Config
	Root() string

	// Path is the full path to this Config
	Path() string

	// Defaults returns the Defaults entry
	Defaults() Entry

	// Hierarchy returns the configuration hierarchy slice
	Hierarchy() []Entry

	// DefaultHierarchy returns the default hierarchy slice
	DefaultHierarchy() []Entry
}

A Config represents a full hiera.yaml version 5 configuration.

type DataProvider 

type DataProvider interface {
	// Hierarchy returns the entry where this provider was configured
	Hierarchy() Entry

	// FullName returns a descriptive name of the data provider. Used by the explainer
	FullName() string

	// Perform a lookup of the given key, invocation and location, and return the result.
	// The invocation is guaranteed to be a resolved locations derived from the locations
	// present in this providers hierarchy, or nil if no location is present.
	LookupKey(key Key, ic Invocation, location Location) dgo.Value
}

A DataProvider performs a lookup using a configured lookup function.

type Entry 

type Entry interface {
	// Create a copy of this entry for the given Config
	Copy(Config) Entry

	// Options returns the options
	Options() dgo.Map

	// DataDir returns datadir
	DataDir() string

	// PluginDir returns plugindir
	PluginDir() string

	// PluginFile returns pluginfile
	PluginFile() string

	// Function returns data_dir, data_hash, or lookup_key function
	Function() Function

	// Name returns the name
	Name() string

	// Resolve resolves this configuration on behalf of the given invocation and defaults entry
	Resolve(ic Invocation, defaults Entry) Entry

	// Locations returns the paths, globs, or uris. The method returns nil if no locations are defined
	Locations() []Location
}

An Entry is a definition an entry in the hierarchy.

type Explainer 

type Explainer interface {
	dgo.Value
	dgo.Indentable

	// AcceptFound accepts information that a value was found for a given key
	AcceptFound(key interface{}, value dgo.Value)

	// AcceptFoundInDefaults accepts information that a value was found for a given key in the defaults hash
	AcceptFoundInDefaults(key string, value dgo.Value)

	// AcceptFoundInOverrides accepts information that a value was found for a given key in the overrides hash
	AcceptFoundInOverrides(key string, value dgo.Value)

	// AcceptLocationNotFound accepts information that a location was not found. The actual location is determined
	// by the top explainer node of type Context "Location"
	AcceptLocationNotFound()

	// AcceptMergeSource accepts information that about as source for merge options such as the lookup_options hash
	AcceptMergeSource(mergeSource string)

	// AcceptModuleNotFound accepts that the current module was not found
	AcceptModuleNotFound()

	// AcceptNotFound accepts information that a key was not found
	AcceptNotFound(key interface{})

	// AcceptResult accepts information about the result of a merge
	AcceptMergeResult(value dgo.Value)

	// AcceptText accepts arbitrary text to be injected into the explanation
	AcceptText(text string)

	PushDataProvider(pvd DataProvider)

	PushInterpolation(expr string)

	PushInvalidKey(key interface{})

	PushLocation(loc Location)

	PushLookup(key Key)

	PushMerge(mrg MergeStrategy)

	PushModule(moduleName string)

	PushSegment(seg interface{})

	PushSubLookup(key Key)

	// Pop pops an explainer node from the stack of explanations
	Pop()

	// OnlyOptions returns true if lookups of lookup_options is the only thing that will be included in the explanation
	OnlyOptions() bool

	// Options returns true if lookups of lookup_options will be included in the explanation
	Options() bool
}

An Explainer collects information about a lookup and can present it in the form of a fairly verbose human readable explanation.

type Function 

type Function interface {
	// FunctionKind returns the function kind
	Kind() FunctionKind

	// Name returns the name of the function
	Name() string

	// Resolve resolves the function on behalf of the given invocation
	Resolve(ic Invocation) (Function, bool)
}

A Function is a definition of a Hiera lookup function, i.e. a data_dig, data_hash, or lookup_key.

type FunctionKind 

type FunctionKind string

FunctionKind denotes what kind of function this is.

type Invocation 

type Invocation interface {
	Session

	// Obtain the configuration appointed by the given configPath and moduleName. The configuration is considered
	// global if the moduleName is the empty string. A global configuration can find data and lookup options for
	// data regardless of if the key has a module prefix or not. A module configuration can only find data and lookup
	// options for keys prefixed with the name of the module.
	Config(configPath string, moduleName string) ResolvedConfig

	// DoWithScope associates the given scope with this invocation and calls the given Doer function. The
	// scope is then restored to what it was before the call.
	DoWithScope(scope dgo.Keyed, doer dgo.Doer)

	// Call doer and while it is executing, don't reveal any found values in logs
	DoRedacted(doer dgo.Doer)

	// Interpolate resolves interpolations in the given value and returns the result
	Interpolate(value dgo.Value, allowMethods bool) dgo.Value

	// InterpolateInScope resolves a key expression in the invocation scope
	InterpolateInScope(expr string, allowMethods bool) dgo.Value

	// InterpolateString resolves a string containing interpolation expressions
	InterpolateString(str string, allowMethods bool) (dgo.Value, bool)

	// Lookup performs a lookup using the given options
	Lookup(key Key, options dgo.Map) dgo.Value

	// LookupAndConvertData checks if the lookupOptions assigned to this invocation with SetMergeStrategy also
	// stipulates that a found value should be converted to a Sensitive. If that is the case, any occurrence of
	// the found value will be redacted in log statements written during the call of the given
	// function.
	//
	// The value will be converted prior to returned if the lookupOptions stipulates
	// it should converted.
	LookupAndConvertData(fn func() dgo.Value) dgo.Value

	// MergeHierarchy merges the result of performing a lookup usign each of the given
	// data providers
	MergeHierarchy(key Key, providers []DataProvider, merge MergeStrategy) dgo.Value

	// MergeLocations merges the result of lookups on all locations (or without location) for the
	// given provider and merge options
	MergeLocations(key Key, provider DataProvider, merge MergeStrategy) dgo.Value

	// ReportText will add the message returned by the given function to the
	// lookup explainer. The method will only get called when the explanation
	// support is enabled
	ReportText(messageProducer func() string)

	// ReportLocationNotFound reports that the current location wasn't found
	ReportLocationNotFound()

	// ReportFound reports that the given value was found using the given key
	ReportFound(key interface{}, value dgo.Value)

	// ReportMergeResult reports the result of a the current merge operation
	ReportMergeResult(value dgo.Value)

	// ReportMergeSource reports the source of the current merge (explicit options or lookup options)
	ReportMergeSource(source string)

	// ReportModuleNotFound reports that the current module was not found
	ReportModuleNotFound()

	// ReportNotFound reports that the given key was not found
	ReportNotFound(key interface{})

	// ServerContext returns a new server context for this invocation configured with the given options
	ServerContext(options dgo.Map) ServerContext

	// WithDataProvider pushes the given provider to the explanation stack and calls the producer, then pops the
	// provider again before returning.
	WithDataProvider(pvd DataProvider, f dgo.Producer) dgo.Value

	// WithInterpolation pushes the given expression to the explanation stack and calls the producer, then pops the
	// expression again before returning.
	WithInterpolation(expr string, f dgo.Producer) dgo.Value

	// WithInvalidKey pushes the given key to the explanation stack and calls the producer, then pops the
	// key again before returning.
	WithInvalidKey(key interface{}, f dgo.Producer) dgo.Value

	// WithLocation pushes the given location to the explanation stack and calls the producer, then pops the
	// location again before returning.
	WithLocation(loc Location, f dgo.Producer) dgo.Value

	// WithLookup pushes the given key to the explanation stack and calls the producer, then pops the
	// key again before returning.
	WithLookup(key Key, f dgo.Producer) dgo.Value

	// WithMerge pushes the given strategy to the explanation stack and calls the producer, then pops the
	// strategy again before returning.
	WithMerge(ms MergeStrategy, f dgo.Producer) dgo.Value

	// WithModule pushes the given module to the explanation stack and calls the producer, then pops the
	// module again before returning.
	WithModule(moduleName string, f dgo.Producer) dgo.Value

	// WithSegment pushes the given segment to the explanation stack and calls the producer, then pops the
	// segment again before returning.
	WithSegment(seg interface{}, f dgo.Producer) dgo.Value

	// WithLookup pushes the given key to the explanation stack and calls the producer, then pops the
	// key again before returning.
	WithSubLookup(key Key, f dgo.Producer) dgo.Value

	// ExplainMode returns true if explain support is active
	ExplainMode() bool

	// ForConfig returns an Invocation without explain support
	ForConfig() Invocation

	// ForData returns an Invocation returns an Invocation that has adjusted its explainer according to
	// how it should report lookup of data (as opposed to lookup of "lookup_options").
	ForData() Invocation

	// ForLookupOptions returns an Invocation that has adjusted its explainer according to
	// how it should report lookup of the "lookup_options" key.
	ForLookupOptions() Invocation

	// SetMergeStrategy sets the current merge strategy for the invocation from the given command line
	// option `merge` and lookupOptions for the key that is currently being looked up.
	SetMergeStrategy(cliMergeOpt dgo.Value, lookupOptions dgo.Map)

	// Returns the current merge strategy
	MergeStrategy() MergeStrategy

	// Returns the current lookup options
	LookupOptions() dgo.Map

	// Returns true if this invocation is adjusted to do lookup of the "lookup_options" key
	LookupOptionsMode() bool

	// Returns true if this invocation is adjusted to do lookup of data and not "lookup_options"
	DataMode() bool
}

An Invocation keeps track of one specific lookup invocation implements a guard against endless recursion

type Key 

type Key interface {
	dgo.Value

	// Return the result of using this key to dig into the given value. Nil is returned
	// unless the dig was a success
	Dig(Invocation, dgo.Value) dgo.Value

	// Bury is the opposite of Dig. It returns the value that represents what would be found
	// using the root of this key. If this key has one part, the value itself is returned, otherwise
	// a nested chain of single entry hashes is returned.
	Bury(dgo.Value) dgo.Value

	// Return the parts of this key. Each part is either a string or an int value
	Parts() []interface{}

	// Return the root key, i.e. the first part.
	Root() string

	// Source returns the string that this key was created from
	Source() string
}

A Key is a parsed version of the possibly dot-separated key to lookup. The parts of a key will be strings or integers

func NewKey 

func NewKey(str string) Key

NewKey parses the given string into a Key

Example (Dotted) 
package main

import (
	"fmt"

	"github.com/lyraproj/hiera/api"
)

func main() {
	key := api.NewKey(`a.b.c`)
	fmt.Printf(`%s, %d`, key.Source(), len(key.Parts()))
}

Output:

a.b.c, 3
Example (Dotted_int) 
package main

import (
	"fmt"

	"github.com/lyraproj/hiera/api"
)

func main() {
	key := api.NewKey(`a.3`)
	fmt.Printf(`%T`, key.Parts()[1])
}

Output:

int
Example (DoubleQuoted) 
package main

import (
	"fmt"

	"github.com/lyraproj/hiera/api"
)

func main() {
	key := api.NewKey(`"a.b.c"`)
	fmt.Printf(`%s, %d`, key.Source(), len(key.Parts()))
}

Output:

"a.b.c", 1
Example (Quoted) 
package main

import (
	"fmt"

	"github.com/lyraproj/hiera/api"
)

func main() {
	key := api.NewKey(`'a.b.c'`)
	fmt.Printf(`%s, %d`, key.Source(), len(key.Parts()))
}

Output:

'a.b.c', 1
Example (QuotedDot) 
package main

import (
	"fmt"

	"github.com/lyraproj/hiera/api"
)

func main() {
	key := api.NewKey(`a.'b.c'`)
	fmt.Printf(`%s, %d, %s`, key.Source(), len(key.Parts()), key.Parts()[1])
}

Output:

a.'b.c', 2, b.c
Example (Simple) 
package main

import (
	"fmt"

	"github.com/lyraproj/hiera/api"
)

func main() {
	key := api.NewKey(`simple`)
	fmt.Printf(`%s, %d`, key.Source(), len(key.Parts()))
}

Output:

simple, 1

type Location 

type Location interface {
	dgo.Value
	Kind() LocationKind
	Exists() bool
	Resolve(ic Invocation, dataDir string) []Location
	Original() string
	Resolved() string
}

Location represents a location in a hierarchy entry and can be in the form path, uri, glob, and mapped paths.

type LocationKind 

type LocationKind string

LocationKind describes the kind of location that is used in a Hiera entry.

type MergeStrategy 

type MergeStrategy interface {
	// Label returns a short descriptive label of this strategy.
	Label() string

	// Name returns the name of this strategy
	Name() string

	// MergeLookup performs a series of lookups for each variant found in the given variants slice. The actual
	// lookup value is returned by the given value function which will be called at least once. The argument to
	// the value function will be an element of the variants slice.
	MergeLookup(variants interface{}, invocation Invocation, value func(location interface{}) dgo.Value) dgo.Value

	// Options returns the options for this strategy or an empty map if strategy has no options
	Options() dgo.Map
}

MergeStrategy is responsible for merging or prioritizing the result of several lookups into one.

type ResolvedConfig 

type ResolvedConfig interface {
	// Config returns the original Config that the receiver was created from
	Config() Config

	// Hierarchy returns the DataProvider slice
	Hierarchy() []DataProvider

	// DefaultHierarchy returns the DataProvider slice for the configured default_hierarchy.
	// The slice will be empty if no such hierarchy has been defined.
	DefaultHierarchy() []DataProvider

	// LookupOptions returns the resolved lookup_options value for the given key or nil
	// if no such options exists.
	LookupOptions(key Key) dgo.Map
}

A ResolvedConfig represents a Config where everything has been resolved on behalf of an Invocation.

type ServerContext 

type ServerContext interface {
	hiera.ProviderContext

	// ReportText will add the message returned by the given function to the
	// lookup explainer. The method will only get called when the explanation
	// support is enabled
	Explain(messageProducer func() string)

	// Cache adds the given key - value association to the cache
	Cache(key string, value dgo.Value) dgo.Value

	// CacheAll adds all key - value associations in the given hash to the cache
	CacheAll(hash dgo.Map)

	// CachedEntry returns the value for the given key together with
	// a boolean to indicate if the value was found or not
	CachedValue(key string) (dgo.Value, bool)

	// CachedEntries calls the consumer with each association in the cache
	CachedEntries(consumer func(key string, value dgo.Value))

	// Interpolate resolves interpolations in the given value and returns the result
	Interpolate(value dgo.Value) dgo.Value

	// Invocation returns the active invocation.
	Invocation() Invocation

	// Returns a copy of this ServerContext with an Invocation that is configured for lookup of data
	ForData() ServerContext

	// Returns a copy of this ServerContext with an Invocation that is configured for lookup of lookup_options
	ForLookupOptions() ServerContext
}

ServerContext is the Hiera context used by lookup functions that operate in-process

type Session 

type Session interface {
	context.Context

	// AliasMap is the map that manages all type aliases used during the session.
	AliasMap() dgo.AliasMap

	// Dialect determines what language to use when parsing types and serializing/deserializing
	// rich data.
	Dialect() streamer.Dialect

	// KillPlugins ensures that all external plugin processes that were started by this session are killed.
	KillPlugins()

	// LoadFunction loads the lookup function defined in the given hierarchy entry and returns
	// it together with a flag indicating if the load was a success
	LoadFunction(he Entry) (dgo.Function, bool)

	// Invocation creates a new invocation for this session
	Invocation(scope interface{}, explainer Explainer) Invocation

	// SessionOptions returns the session specific options
	SessionOptions() dgo.Map

	// Loader returns the session specific loader
	Loader() dgo.Loader

	// Scope returns the session's scope
	Scope() dgo.Keyed

	// SharedCache returns the cache that is shared
	SharedCache() *sync.Map

	// TopProvider returns the lookup function that defines the hierarchy
	TopProvider() hiera.LookupKey

	// TopProviderCache returns the shared provider cache used by all lookups
	TopProviderCache() *sync.Map

	// Get returns a session variable, or nil if no such variable exists. Session variables
	// are used internally by Hiera and should not be confused with Scope variables.
	Get(key string) interface{}
}

A Session determines the life cycle of cached values during a Hiera session.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.