plugin/metadata: add metadata plugin (#1894)

* plugin/metadata: add metadata plugin

* plugin/metadata: Add MD struct, refactor code, fix doc

* plugin/metadata: simplify metadata key

* plugin/metadata: improve setup_test

* Support of metadata by rewrite plugin. Move calculated variables to metadata.

* Move variables from metadata to pkg, add UTs, READMEs change, metadata small fixes

* Add client port validation to variables_test

* plugin/metadata: improve README

* plugin/metadata: rename methods

* plugin/metadata: Update Metadataer interface, update doc, cosmetic code changes

* plugin/metadata: move colllisions check to OnStartup(). Fix default variables metadataer.

* plugin/metadata: Fix comment for method setValue

* plugin/metadata: change variables order to fix linter warning

* plugin/metadata: rename Metadataer to Provider

1 files changed, 47 insertions, 0 deletions

diff --git a/plugin/metadata/README.md b/plugin/metadata/README.md
new file mode 100644
index 000000000..32f58baa8
--- /dev/null
+++ b/plugin/metadata/README.md
@@ -0,0 +1,47 @@
+# metadata
+
+## Name
+
+*metadata* - enable a metadata collector.
+
+## Description
+
+By enabling *metadata* any plugin that implements [metadata.Provider interface](https://godoc.org/github.com/coredns/coredns/plugin/metadata#Provider) will be called for each DNS query, at being of the process for that query, in order to add it's own Metadata to context. The metadata collected will be available for all plugins handler, via the Context parameter provided in the ServeDNS function.
+Metadata plugin is automatically adding the so-called default medatada (extracted from the query) to the context. Those default metadata are: {qname}, {qtype}, {client_ip}, {client_port}, {protocol}, {server_ip}, {server_port}
+
+
+## Syntax
+
+~~~
+metadata [ZONES... ]
+~~~
+
+## 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
+from the metadata plugin.
+If **ZONES** is specified then metadata add is limited by zones. Metadata is added to every context going through metadata.Provider if **ZONES** are not specified.
+
+
+## Examples
+
+Enable metadata for all requests. Rewrite uses one of the provided by default metadata variables.
+
+~~~ corefile
+. {
+    metadata
+    rewrite edns0 local set 0xffee {client_ip}
+    forward . 8.8.8.8:53
+}
+~~~
+
+Add metadata for all requests within `example.org.`. Rewrite uses one of provided by default metadata variables. Any other requests won't have metadata.
+
+~~~ corefile
+. {
+    metadata example.org
+    rewrite edns0 local set 0xffee {client_ip}
+    forward . 8.8.8.8:53
+}
+~~~