metadata

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.

See Also

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

• func ContextWithMetadata(ctx context.Context) context.Context
• func IsLabel(label string) bool
• func Labels(ctx context.Context) []string
• func SetValueFunc(ctx context.Context, label string, f Func) bool
• func ValueFuncs(ctx context.Context) map[string]Func
• type Func
  • func ValueFunc(ctx context.Context, label string) Func
• type Metadata
  • func (m *Metadata) Collect(ctx context.Context, state request.Request) context.Context
  • func (m *Metadata) Name() string
  • func (m *Metadata) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error)
• type Provider

Functions

func ContextWithMetadata

func ContextWithMetadata(ctx context.Context) context.Context

ContextWithMetadata is exported for use by provider tests

func IsLabel

func IsLabel(label string) bool

IsLabel checks that the provided name is a valid label name, i.e. two or more words separated by a slash.

func Labels

func Labels(ctx context.Context) []string

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

func SetValueFunc(ctx context.Context, label string, f Func) bool

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.

func ValueFuncs

func ValueFuncs(ctx context.Context) map[string]Func

ValueFuncs returns the map[string]Func from the context, or nil if it does not exist.

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.

func ValueFunc

func ValueFunc(ctx context.Context, label string) Func

ValueFunc returns the value function of label. If none can be found nil is returned. Calling the function returns the value of the label.

type Metadata

type Metadata struct {
	Zones     []string
	Providers []Provider
	Next      plugin.Handler
}

Metadata implements collecting metadata information from all plugins that implement the Provider interface.

func (*Metadata) Collect

func (m *Metadata) Collect(ctx context.Context, state request.Request) context.Context

Collect will retrieve metadata functions from each metadata provider and update the context

func (*Metadata) Name

func (m *Metadata) Name() string

Name implements the Handler interface.

func (*Metadata) ServeDNS

func (m *Metadata) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error)

ServeDNS implements the plugin.Handler 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.