README
¶
metadata
Name
metadata - enables a metadata collector.
Description
By enabling metadata any plugin that implements metadata.Provider interface will be called for each DNS query, at the beginning of the process for that query, in order to add its own metadata to context.
The metadata collected will be available for all plugins, via the Context parameter provided in the ServeDNS function. The package (code) documentation has examples on how to inspect and retrieve metadata a plugin might be interested in.
The metadata is added by setting a label with a value in the context. These labels should be named
plugin/NAME
, where NAME is something descriptive. The only hard requirement the metadata
plugin enforces is that the labels contain a slash. See the documentation for
metadata.SetValueFunc
.
The value stored is a string. The empty string signals "no metadata". See the documentation for
metadata.ValueFunc
on how to retrieve this.
Syntax
metadata [ZONES... ]
- ZONES zones metadata should be invoked for.
Plugins
metadata.Provider
interface needs to be implemented by each plugin willing to provide metadata
information for other plugins. It will be called by metadata and gather the information from all
plugins in context.
Note: this method should work quickly, because it is called for every request.
Examples
The rewrite plugin uses meta data to rewrite requests.
Also See
The Provider interface and the package level documentation.
Documentation
¶
Overview ¶
Package metadata provides an API that allows plugins to add metadata to the context. Each metadata is stored under a label that has the form <plugin>/<name>. Each metadata is returned as a Func. When Func is called the metadata is returned. If Func is expensive to execute it is its responsibility to provide some form of caching. During the handling of a query it is expected the metadata stays constant.
Basic example:
Implement the Provider interface for a plugin p:
func (p P) Metadata(ctx context.Context, state request.Request) context.Context { metadata.SetValueFunc(ctx, "test/something", func() string { return "myvalue" }) return ctx }
Basic example with caching:
func (p P) Metadata(ctx context.Context, state request.Request) context.Context { cached := "" f := func() string { if cached != "" { return cached } cached = expensiveFunc() return cached } metadata.SetValueFunc(ctx, "test/something", f) return ctx }
If you need access to this metadata from another plugin:
// ... valueFunc := metadata.ValueFunc(ctx, "test/something") value := valueFunc() // use 'value'
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ContextWithMetadata ¶
ContextWithMetadata is exported for use by provider tests
func IsLabel ¶
IsLabel checks that the provided name is a valid label name, i.e. two words separated by a slash.
func Labels ¶
Labels returns all metadata keys stored in the context. These label names should be named as: plugin/NAME, where NAME is something descriptive.
func SetValueFunc ¶
SetValueFunc set the metadata label to the value function. If no metadata can be found this is a noop and false is returned. Any existing value is overwritten.
Types ¶
type Func ¶
type Func func() string
Func is the type of function in the metadata, when called they return the value of the label.
type Metadata ¶
Metadata implements collecting metadata information from all plugins that implement the Provider interface.
type Provider ¶
type Provider interface { // Metadata adds metadata to the context and returns a (potentially) new context. // Note: this method should work quickly, because it is called for every request // from the metadata plugin. Metadata(ctx context.Context, state request.Request) context.Context }
Provider interface needs to be implemented by each plugin willing to provide metadata information for other plugins.