Add package documentation and examples

doc.go

@@ -0,0 +1,31 @@
+/*
+Package rdns implements a variety of functionality to make DNS resulution configurable
+and extensible. It offers DNS resolvers as well as listeners with a number of protcols
+such as DNS-over-TLS, DNS-over-HTTP, and plain wire format DNS. In addition it is
+possible to route queries based on the query name or type. There are 4 fundamental types
+of objects available in this library.
+
+Resolvers
+
+Resolvers implement name resolution with upstream resolvers. All of them implement connection
+reuse as well as pipelining (sending multiple queries and receiving them out-of-order).
+
+Groups
+
+Groups typically wrap multiple resolvers and implement failover or load-balancing algorithms
+accross all resolvers in the group. Groups too are resolvers and can therefore be nested
+into other groups for more complex query routing.
+
+Routers
+
+Routers are used to send DNS queries to resolvers, groups, or even other routers based on
+the query content. As with groups, routers too are resolvers that can be combined to form
+more advanced configurations.
+
+Listeners
+
+While resolvers handle outgoing queries to upstream servers, listeners are the receivers
+of queries. Multiple listeners can be started for different protocols and on different ports.
+Each listener forwards received queries to one resolver, group, or router.
+*/
+package rdns

example_test.go

@@ -0,0 +1,58 @@
+package rdns_test
+
+import (
+	"fmt"
+
+	rdns "github.com/folbricht/routedns"
+	"github.com/miekg/dns"
+)
+
+func Example_resolver() {
+	// Define resolver
+	r := rdns.NewDoTClient("dns.google:853")
+
+	// Build a query
+	q := new(dns.Msg)
+	q.SetQuestion("google.com.", dns.TypeA)
+
+	// Resolve the query
+	a, _ := r.Resolve(q)
+	fmt.Println(a)
+}
+
+func Example_group() {
+	// Define resolvers
+	r1 := rdns.NewDNSClient("8.8.8.8:53", "udp")
+	r2 := rdns.NewDNSClient("8.8.4.4:53", "udp")
+
+	// Combine them int a group that does round-robin over the two resolvers
+	g := rdns.NewRoundRobin(r1, r2)
+
+	// Build a query
+	q := new(dns.Msg)
+	q.SetQuestion("google.com.", dns.TypeA)
+
+	// Resolve the query
+	a, _ := g.Resolve(q)
+	fmt.Println(a)
+}
+
+func Example_router() {
+	// Define resolvers
+	google := rdns.NewDNSClient("8.8.8.8:53", "udp")
+	cloudflare := rdns.NewDNSClient("1.1.1.1:53", "udp")
+
+	// Build a router that will send all "*.cloudflare.com" to the cloudflare
+	// resolvber while everything else goes to the google resolver (default)
+	r := rdns.NewRouter()
+	r.Add(`\.cloudflare\.com\.$`, "", cloudflare)
+	r.Add("", "", google)
+
+	// Build a query
+	q := new(dns.Msg)
+	q.SetQuestion("www.cloudflare.com.", dns.TypeA)
+
+	// Resolve the query
+	a, _ := r.Resolve(q)
+	fmt.Println(a)
+}