Initial commit

pipe/dsl/context.go

@@ -0,0 +1,59 @@
+package dsl
+
+import (
+	"github.com/BytemarkHosting/go-pdns/pipe/backend"
+	"strconv"
+)
+
+// Callbacks are run with a context instance, which allows them to accumulate
+// answers while maintaining a short type signature. It will also make
+// concurrent callbacks easier, when we handle that, but for now one context
+// is maintained across all callbacks for a particular query
+type Context struct {
+	// Replies that don't specify a TTL will be given this instead.
+	DefaultTTL int
+
+	// The query that triggered this callback run. Note that its QType
+	// member may be "ANY"
+	Query *backend.Query
+
+	// QType this callback is being run as. Matches the qtype field given
+	// with the callback at the time DSL.Register was called
+	QType string
+
+	// The callback is registered with a regexp; if that regexp contains
+	// any match groups, then the matched text is placed here.
+	Matches []string
+
+	// Set this if an error has been encountered; no more callbacks will be
+	// run, and the error text (only) will be reported to the backend.
+	Error error
+
+	// Answers to be sent to the backend are stored here. Context.Reply()
+	// calls, etc, generate answers and put them here, for instance.
+	// If multiple callbacks are being run, then later callbacks will be
+	// able to see the answers earlier ones generated (for now)
+	Answers []*backend.Response
+}
+
+// Add an answer, using default QName and TTL for the query
+func (c *Context) Reply(content string) {
+	c.ReplyExtra(c.Query.QName, content, c.DefaultTTL)
+}
+
+// Add an answer, using the default QName but specifying a particular TTL
+func (c *Context) ReplyTTL(content string, ttl int) {
+	c.ReplyExtra(c.Query.QName, content, ttl)
+}
+
+// Add an answer, specifying both QName and TTL.
+func (c *Context) ReplyExtra(qname, content string, ttl int) {
+	c.Answers = append(c.Answers, &backend.Response{
+		QName:   qname,
+		QClass:  c.Query.QClass,
+		QType:   c.QType, // q.Query.QType may == "ANY"
+		Id:      c.Query.Id,
+		Content: content,
+		TTL:     strconv.Itoa(ttl),
+	})
+}

pipe/dsl/dsl.go

@@ -0,0 +1,223 @@
+// Copyright 2015 Bytemark Computer Consulting Ltd. All rights reserved
+// Licensed under the GNU General Public License, version 2. See the LICENSE
+// file for more details
+
+// Simple DSL for pipebackend. Usage:
+//
+//	// Create new handle. You have to specify a default TTL here.
+//	x := dsl.New()
+//	root := regexp.QuoteMeta("example.com")
+//
+//	// most zones need SOA + NS records
+//	x.SOA(root, func(c *dsl.Context) {
+//		c.Reply("ns1.example.com hostmaster.example.com 1 3600 1800 86400 3600")
+//	})
+//
+//	// Zones need NS records too. All replies will be returned
+//	x.NS(root, func(c *dsl.Context) {
+//		c.Reply("ns1.example.com")
+//		c.Reply("ns2.example.com")
+//		c.Reply("ns3.example.com")
+//	})
+//
+//	// You don't have to use anonymous functions, of course
+//	func answer(c *dsl.Context) {
+//		switch c.Query.QType {
+//			case "A"   : c.Reply("169.254.0.1")
+//			case "AAAA": c.Reply("fe80::1"    )
+//		}
+//	}
+//	x.A(root, answer)
+//	x.AAAA(root, answer)
+//
+//	// Setting c.Error at any point will suppress *all* replies from being
+//	// sent back. Instead, a FAIL response with the c.Error.Error() as the
+//	// content is returned to powerdns
+//	x.SSHFP(root, func(c *dsl.Context) {
+//		c.Reply("1 1 f1d2d2f924e986ac86fdf7b36c94bcdf32beec15")
+//		c.Error = errors.New("Don't use SSHFP on unsigned zones")
+//		c.Reply("1 2 e242ed3bffccdf271b7fbaf34ed72d089537b42f")
+//	})
+//
+//	// You can do anything in a callback, but be aware that powerdns has a
+//	// time limit on responses and there is no request concurrency within a
+//	// single pipe connection. pdns achieves concurrency through multiple
+//	// backend connections instead
+//	c := make(chan string)
+//	x.MX(root, func(c *dsl.Context) {
+//		c.Reply(<-c)
+//	})
+//
+//	// If your regexp includes capture groups, they are quoted back to you.
+//	// Here's a simple DNS echo server. Note the use of ReplyExtra to allow
+//	// a non-default TTL to be set.
+//	//
+//	// Don't forget: DNS is supposed to be case-insensitive. Be careful.
+//	c.TXT(`(.*)\.` + root, func(c *dsl.Context) {
+//		c.ReplyTTL(c.Query.QName, c.Matches[0], 0)
+//	})
+//
+//	// Dispatch is up to you. It will probably look like this, but you
+//	// might want to add logging around the request or something more
+//	// complicated (different DSL instance depending on backend version?)
+//	func doit(b *backend.Backend, q *backend.Query) ([]*backend.Response, error) {
+//		if q.QClass == "IN" {
+//			return x.Lookup(q)
+//		}
+//		return nil, errors.New("Only IN QClass is supported")
+//	}
+//
+//	pipe := backend.New( r, w, "Example backend" )
+//	err1 := pipe.Negotiate() // do check for errors
+//	err2 := pipe.Run(doit)
+//
+//
+//
+package dsl
+
+import (
+	"github.com/BytemarkHosting/go-pdns/pipe/backend"
+	"regexp"
+)
+
+// Instances of this struct are used to hold onto registered callbacks, etc.
+type DSL struct {
+	callbacks  map[string][]callbackNode
+	qtypeSort  []string
+	defaultTTL int
+
+	beforeCallback Callback
+}
+
+// Get a new builder with a default TTL of one hour
+func New() *DSL {
+	return NewWithTTL(3600)
+}
+
+// Get a new builder, specifying a default TTL explicitly
+func NewWithTTL(ttl int) *DSL {
+	return &DSL{
+		callbacks:  make(map[string][]callbackNode),
+		qtypeSort:  make([]string, 0),
+		defaultTTL: ttl,
+	}
+}
+
+// Callbacks are registered against the DSL instance and run against incoming
+// queries if the regexp they are registered with matches the QName of the query
+type Callback func(c *Context)
+
+type callbackNode struct {
+	matcher *regexp.Regexp
+	fn      Callback
+}
+
+// Register a callback to run before every request. Set c.Error to halt
+// processing, or mutate the context however you like.
+func (d *DSL) Before(f Callback) {
+	d.beforeCallback = f
+}
+
+// Register a callback to be run whenever a query with a QName matching the
+// regular expression comes in. The regex is provided as a string (matcher)
+// to keep ordinary invocations short; it's compiled immediately with
+// regexp.MustCompile. Don't forget to anchor your regexes!
+//
+// If match groups are included in the regex, then any matched text is placed in
+// the Context the callback receives.
+//
+// Callbacks are run with slightly obtuse ordering: all callbacks of a qtype
+// are run in the order they were registered. We iterate the list of qtypes
+// in the order that a callback with a matching qtype was *first* registered.
+// If your pdns server has the "noshuffle" configuration directive, the order
+// will be reflected in the responses returned by it; future concurrent DSL
+// should maintain this ordering.
+func (d *DSL) Register(qtype string, re *regexp.Regexp, f Callback) {
+
+	// Maintain our obtuse sense of order
+	alreadyIn := false
+	for _, prospect := range d.qtypeSort {
+		if prospect == qtype {
+			alreadyIn = true
+			break
+		}
+	}
+	if !alreadyIn {
+		d.qtypeSort = append(d.qtypeSort, qtype)
+	}
+
+	node := callbackNode{matcher: re, fn: f}
+	d.callbacks[qtype] = append(d.callbacks[qtype], node)
+}
+
+// Once we're concurrent, this method will create the context and return it
+func (d *DSL) runNode(c *Context, node *callbackNode) {
+	matches := node.matcher.FindStringSubmatch(c.Query.QName)
+
+	if matches != nil && len(matches) > 0 {
+		// Probably unnecessary, but ensure that the previous value of
+		// Matches is preserved. This could also be = nil
+		oldmatches := c.Matches
+		defer func(c *Context) { c.Matches = oldmatches }(c)
+
+		// The first match is the whole thing, followed by the capture
+		// groups. We're only interested in the latter.
+		c.Matches = matches[1:]
+
+		if d.beforeCallback != nil {
+			d.beforeCallback(c)
+		}
+
+		if c.Error == nil {
+			node.fn(c)
+		}
+	}
+}
+
+// Run all registered callbacks against the query. If any callbacks report an
+// error, we halt and return the error only (partially constructed responses are
+// discarded).
+//
+// For now, callbacks are run sequentially, rather than in parallel. There could
+// be a speedup to running each callback in its own goroutine. Currently, all
+// callbacks share the same context instance; we'd have to change that if we
+// ran them in parallel.
+func (d *DSL) Lookup(q *backend.Query) ([]*backend.Response, error) {
+	c := Context{
+		DefaultTTL: d.defaultTTL,
+		Query:      q,
+		Answers:    make([]*backend.Response, 0),
+		Error:      nil,
+	}
+
+	var runOn []string
+	if q.QType == "ANY" {
+		runOn = d.qtypeSort
+	} else {
+		runOn = []string{q.QType}
+	}
+
+	for _, qtype := range runOn {
+		c.QType = qtype
+		for _, node := range d.callbacks[qtype] {
+			d.runNode(&c, &node)
+			if c.Error != nil {
+				return nil, c.Error
+			}
+		}
+	}
+
+	return c.Answers, nil
+}
+
+// Reports the registered callbacks, in order. Handy for testing or status.
+func (d *DSL) String() string {
+	out := ""
+	for _, qtype := range d.qtypeSort {
+		out = out + qtype + "\t:"
+		for _, node := range d.callbacks[qtype] {
+			out = out + "\t" + node.matcher.String() + "\n"
+		}
+	}
+	return out
+}

pipe/dsl/dsl_test.go

@@ -0,0 +1,181 @@
+package dsl_test
+
+import (
+	"errors"
+	"fmt"
+	"github.com/BytemarkHosting/go-pdns/pipe/backend"
+	. "github.com/BytemarkHosting/go-pdns/pipe/dsl"
+	h "github.com/BytemarkHosting/go-pdns/pipe/test_helpers"
+	"strings"
+	"testing"
+)
+
+func ReplyHandler(x string) func(c *Context) {
+	return func(c *Context) { c.Reply(x) }
+}
+
+func NullHandler(c *Context) {}
+
+var ErrorReplyError = errors.New("Foo")
+
+func ErrorReplyHandler(c *Context) { c.Error = ErrorReplyError }
+
+func SOAQuery() *backend.Query {
+	q := h.FakeQuery(3)
+	q.QName = "example.com"
+	q.QType = "SOA"
+	return q
+}
+
+func AssertTableEntry(t *testing.T, d *DSL, qtype, matcher, msg string) {
+	table := qtype + "\t:\t" + matcher + "\n"
+	h.AssertEqualString(t, table, d.String(), msg)
+}
+
+func AssertLookup(t *testing.T, d *DSL, q *backend.Query, n int, err error) []*backend.Response {
+	rsp, rspErr := d.Lookup(q)
+	if err == nil {
+		h.RefuteError(t, err, "Lookup shouldn't return error")
+	} else if rspErr == nil {
+		t.Logf("Expected error %s but no error was returned", err)
+		t.FailNow()
+	} else {
+		h.AssertEqualString(t, err.Error(), rspErr.Error(), "Expected error not returned")
+	}
+
+	rspStrs := []string{}
+	for _, r := range rsp {
+		r.ProtocolVersion = 1
+		str, err := r.String()
+		h.RefuteError(t, err, "sanity")
+		rspStrs = append(rspStrs, str)
+	}
+
+	h.AssertEqualInt(t, n, len(rsp), fmt.Sprintf("One response expected, got:\n%s", strings.Join(rspStrs, "")))
+	return rsp
+}
+
+// Don't test all the autogenerated helpers explicitly, just a common one.
+func TestAutogeneratedExampleRegistersCorrectCallbackWhenRun(t *testing.T) {
+	d := New()
+	d.SOA(`example\.com`, NullHandler)
+	AssertTableEntry(t, d, "SOA", `^(?i)example\.com$`, "SOA callback not registered")
+}
+
+func TestDefaultTTLFromNewIsOneHour(t *testing.T) {
+	d := New()
+	d.SOA(`*`, ReplyHandler("Foo"))
+	rsp := AssertLookup(t, d, SOAQuery(), 1, nil)
+	h.AssertEqualString(t, "3600", rsp[0].TTL, "Default TTL not honoured")
+}
+
+func TestAlternativeTTLCanBeSpecifiedUsingNewWithTTL(t *testing.T) {
+	d := NewWithTTL(86400)
+	d.SOA(`*`, ReplyHandler("Foo"))
+	rsp := AssertLookup(t, d, SOAQuery(), 1, nil)
+	h.AssertEqualString(t, "86400", rsp[0].TTL, "Custom TTL not honoured")
+}
+
+func TestBeforeCallbackIsCalledIfSpecified(t *testing.T) {
+	d := New()
+	d.Before(ReplyHandler("Before"))
+	d.SOA(`*`, ReplyHandler("SOA 1"))
+	d.SOA(`*`, ReplyHandler("SOA 2"))
+	rsp := AssertLookup(t, d, SOAQuery(), 4, nil)
+	h.AssertEqualString(t, "Before", rsp[0].Content, "First Before not called")
+	h.AssertEqualString(t, "SOA 1", rsp[1].Content, "First SOA not called")
+	h.AssertEqualString(t, "Before", rsp[2].Content, "Second Before not called")
+	h.AssertEqualString(t, "SOA 2", rsp[3].Content, "Second SOA not called")
+}
+
+func TestLookupCallbackOrderIsDefined(t *testing.T) {
+	d := New()
+	d.SOA(`*`, ReplyHandler("SOA 1"))
+	d.MX(`*`, ReplyHandler("MX 1"))
+	d.SOA(`*`, ReplyHandler("SOA 2"))
+	d.SOA(`*`, ReplyHandler("SOA 3"))
+	d.AAAA(`*`, ReplyHandler("AAAA 1"))
+	d.A(`*`, ReplyHandler("AAAA 2"))
+	rsp := AssertLookup(t, d, h.FakeQuery(1), 6, nil)
+	msg := "Order is wrong"
+	h.AssertEqualString(t, "SOA 1", rsp[0].Content, msg)
+	h.AssertEqualString(t, "SOA 2", rsp[1].Content, msg)
+	h.AssertEqualString(t, "SOA 3", rsp[2].Content, msg)
+	h.AssertEqualString(t, "MX 1", rsp[3].Content, msg)
+	h.AssertEqualString(t, "AAAA 1", rsp[4].Content, msg)
+	h.AssertEqualString(t, "AAAA 2", rsp[5].Content, msg)
+}
+
+func TestOnlyMatchingCallbacksAreRun(t *testing.T) {
+	d := New()
+	d.SOA(`example\.com`, ReplyHandler("Good"))
+	d.SOA(`example\.org`, ReplyHandler("Bad"))
+	rsp := AssertLookup(t, d, SOAQuery(), 1, nil)
+	h.AssertEqualString(t, "Good", rsp[0].Content, "Wrong callback run")
+}
+
+func TestOnlyCallbacksOfTheRightQTypeAreRun(t *testing.T) {
+	d := New()
+	d.SOA(`example\.com`, ReplyHandler("Good"))
+	d.NS(`example\.com`, ReplyHandler("Bad"))
+	rsp := AssertLookup(t, d, SOAQuery(), 1, nil)
+	h.AssertEqualString(t, "Good", rsp[0].Content, "Wrong callback run")
+}
+
+func TestCaptureGroupsArePutIntoContextMatches(t *testing.T) {
+	d := New()
+	var captures []string
+	d.SOA(`([a-z]{3})\.([a-z]{3})\.([a-z]{3})\.example\.com`, func(c *Context) {
+		captures = c.Matches
+		c.Reply("OK")
+	})
+	q := SOAQuery()
+	q.QName = "BAZ.bar.foo.example.com"
+	rsp := AssertLookup(t, d, q, 1, nil)
+	h.AssertEqualInt(t, 3, len(captures), "Wrong number of match groups returned")
+	h.AssertEqualString(t, "OK", rsp[0].Content, "Wrong callback run?")
+	// case-insensitive, so we don't mangle these
+	h.AssertEqualString(t, "BAZ", captures[0], "Part 1 not captured")
+	h.AssertEqualString(t, "bar", captures[1], "Part 2 not captured")
+	h.AssertEqualString(t, "foo", captures[2], "Part 3 not captured")
+}
+
+func TestBeforeCanModifyCaptureGroups(t *testing.T) {
+	d := New()
+	d.Before(func(c *Context) { c.Matches = append(c.Matches, "modify-cg") })
+	d.SOA(`*`, func(c *Context) { c.Reply(c.Matches[0]) })
+	rsp := AssertLookup(t, d, SOAQuery(), 1, nil)
+	h.AssertEqualString(t, "modify-cg", rsp[0].Content, "Capture modification lost")
+}
+
+func TestChangesToMatchesInOrdinaryCallbacksDoNotPersist(t *testing.T) {
+	d := New()
+	var ok bool
+
+	d.SOA(`*`, func(c *Context) { c.Matches = append(c.Matches, "Bad") })
+	d.SOA(`*`, func(c *Context) { ok = (len(c.Matches) == 0) })
+	AssertLookup(t, d, SOAQuery(), 0, nil)
+	h.Assert(t, ok, "Change was persisted")
+}
+
+func TestCallbackReturningErrorIsReported(t *testing.T) {
+	d := New()
+	d.SOA(`*`, ErrorReplyHandler)
+	AssertLookup(t, d, SOAQuery(), 0, ErrorReplyError)
+}
+
+func TestCallbackReturningErrorBlanksAnswers(t *testing.T) {
+	d := New()
+	d.SOA(`*`, ReplyHandler("Foo"))
+	d.SOA(`*`, ErrorReplyHandler)
+	AssertLookup(t, d, SOAQuery(), 0, ErrorReplyError)
+}
+
+func TestCallbackReturningErrorStopsLaterCallbacksFromRunning(t *testing.T) {
+	d := New()
+	ok := true
+	d.SOA(`*`, ErrorReplyHandler)
+	d.SOA(`*`, func(c *Context) { ok = false })
+	AssertLookup(t, d, SOAQuery(), 0, ErrorReplyError)
+	h.Assert(t, ok, "Later callback was run")
+}

pipe/dsl/generate_dsl_helpers.sh

@@ -0,0 +1,41 @@
+#!/bin/sh
+
+# 
+
+records=`curl -sf http://www.iana.org/assignments/dns-parameters/dns-parameters-4.csv | cut -f1 -d',' | sort | uniq | awk '/^[A-Z][A-Z]*$/ { print $0 }'` || exit 1
+
+echo "// AUTOGENERATED helper methods for IANA-registered RRTYPES. Do not edit."
+echo "// See generate_dsl_helpers.sh for details"
+echo "package dsl"
+echo "
+import (
+	\"fmt\"
+	\"regexp\"
+)
+"
+# A list of RRTypes might come in handy, you never know
+echo "var RRTypes = []string{"
+for record in $records; do
+echo "	\"${record}\","
+done
+echo "}"
+for record in $records; do
+
+echo "
+// Helper function to register a callback for ${record} queries.
+// The matcher is given as a string, which is compiled to a regular expression
+// (using regexp.MustCompile) with the following rules:
+//
+// * The regexp is anchored to the start of the match string(\"^\" at start)
+// * The case-insensitivity option is added \"(?i)\"
+// * The regexp is anchored to the end of the match string (\"$\" at end)
+//
+// If any of these options are unwelcome, you can use the DSL.Register and pass
+// a regexp and the \"${record}\" string directly.
+func (d *DSL) ${record}(matcher string, f Callback) {
+	re := regexp.MustCompile(fmt.Sprintf(\"^(?i)%s$\", matcher))
+	d.Register(\"${record}\", re, f)
+}"
+
+done
+