Document fallthrough and fix rewrite (#537)

* Document fallthrough and fix *reverse*

While documenting the fallthrough behavior and testing it I noticed
the did not properly work. This PR does a tiny bit too much as it

- Documents fallthrough
- Fixes fallthrough in reverse
- Makes directives_generate complain on duplicate priorities
- Moved reverse *before* file in middleware.cfg
- Add a test that tests the reverse fallthrough behavior with a file
  backend

Fixes #515

* ....and fix the tests

1 files changed, 74 insertions, 2 deletions

diff --git a/middleware.md b/middleware.md
index 98a6adf89..46e6e0673 100644
--- a/middleware.md
+++ b/middleware.md
@@ -29,9 +29,12 @@ So CoreDNS treats:
 as special and will then assume nothing has written to the client. In all other cases it is assumes
 something has been written to the client (by the middleware).
 
-## Hooking it up
+## Hooking It Up
 
-TODO(miek): text here on how to hook up middleware.
+See a couple of blog posts on how to write and add middleware to CoreDNS:
+
+* <https://blog.coredns.io/#> TO BE PUBLISHED.
+* <https://blog.coredns.io/2016/12/19/writing-middleware-for-coredns/>, slightly older, but useful.
 
 ## Metrics
 
@@ -60,3 +63,72 @@ We use the Unix manual page style:
 * Optional text: in block quotes: `[optional]`.
 * Use three dots to indicate multiple options are allowed: `arg...`.
 * Item used literal: `literal`.
+
+### Example Domain Names
+
+Please be sure to use `example.org` or `example.net` in any examples you provide. These are the
+standard domain names created for this purpose.
+
+## Fallthrough
+
+In a perfect world the following would be true for middleware: "Either you are responsible for
+a zone or not". If the answer is "not", the middleware should call the next middleware in the chain.
+If "yes" it should handle *all* names that fall in this zone and the names below - i.e. it should
+handle the entire domain.
+
+~~~ txt
+. {
+    file example.org db.example
+}
+~~~
+In this example the *file* middleware is handling all names below (and including) `example.org`. If
+a query comes in that is not a subdomain (or equal to) `example.org` the next middleware is called.
+
+Now, the world isn't perfect, and there are good reasons to "fallthrough" to the next middlware,
+meaning a middleware is only responsible for a subset of names within the zone. The first of these
+to appear was the *reverse* middleware that synthesis PTR and A/AAAA responses (useful with IPv6).
+
+The nature of the *reverse* middleware is such that it only deals with A,AAAA and PTR and then only
+for a subset of the names. Ideally you would want to layer *reverse* **in front off** another
+middleware such as *file* or *auto* (or even *proxy*). This means *reverse* handles some special
+reverse cases and **all other** request are handled by the backing middleware. This is exactly what
+"fallthrough" does. To keep things explicit we've opted that middlewares implement such behavior
+should implement a `fallthrough` keyword.
+
+### Example Fallthrough Usage
+
+The following Corefile example, sets up the *reverse* middleware, but disables fallthrough. It
+also defines a zonefile for use with the *file* middleware for other names in the `compute.internal`.
+
+~~~ txt
+arpa compute.internal {
+    reverse 10.32.0.0/16 {
+        hostname ip-{ip}.{zone[2]}
+        #fallthrough
+    }
+    file db.compute.internal compute.internal
+}
+~~~
+
+This works for returning a response to a PTR request:
+
+~~~ sh
+% dig +nocmd @localhost +noall +ans -x 10.32.0.1
+1.0.32.10.in-addr.arpa.	3600	IN	PTR	ip-10-32-0-1.compute.internal.
+~~~
+
+And for the forward:
+
+~~~ sh
+% dig +nocmd @localhost +noall +ans A ip-10-32-0-1.compute.internal
+ip-10-32-0-1.compute.internal. 3600 IN	A	10.32.0.1
+~~~
+
+But a query for `mx compute.internal` will return SERVFAIL. Now when we remove the '#' from
+fallthrough and reload (on Unix: `kill -SIGUSR1 $(pidof coredns)`) CoreDNS, we *should* get an
+answer for the MX query:
+
+~~~ sh
+% dig +nocmd @localhost +noall +ans MX compute.internal
+compute.internal.	3600	IN	MX	10 mx.compute.internal.
+~~~