core/dnsserver: document in-process embedding (#8436)

Signed-off-by: houyuwushang <liuluoqianqiu@outlook.com>

core/dnsserver/example_test.go

@@ -0,0 +1,58 @@
+package dnsserver_test
+
+import (
+	"errors"
+	"fmt"
+
+	"github.com/coredns/caddy"
+	"github.com/coredns/coredns/core/dnsserver"
+	_ "github.com/coredns/coredns/plugin/bind"
+	_ "github.com/coredns/coredns/plugin/whoami"
+
+	"github.com/miekg/dns"
+)
+
+func Example_embedding() {
+	oldDirectives := dnsserver.Directives
+	oldCaddyQuiet := caddy.Quiet
+	oldDNSQuiet := dnsserver.Quiet
+	defer func() {
+		dnsserver.Directives = oldDirectives
+		caddy.Quiet = oldCaddyQuiet
+		dnsserver.Quiet = oldDNSQuiet
+	}()
+
+	// Import only the plugins the host needs and set their execution order
+	// before starting the first server.
+	dnsserver.Directives = []string{"bind", "whoami"}
+	caddy.Quiet = true
+	dnsserver.Quiet = true
+
+	instance, err := caddy.Start(caddy.CaddyfileInput{
+		Filepath:       "Corefile",
+		Contents:       []byte(".:0 {\nbind 127.0.0.1\nwhoami\n}\n"),
+		ServerTypeName: "dns",
+	})
+	if err != nil {
+		panic(err)
+	}
+	defer func() {
+		shutdownErr := errors.Join(instance.ShutdownCallbacks()...)
+		stopErr := instance.Stop()
+		instance.Wait()
+		if err := errors.Join(shutdownErr, stopErr); err != nil {
+			panic(err)
+		}
+	}()
+
+	server := instance.Servers()[0].LocalAddr().String()
+	query := new(dns.Msg)
+	query.SetQuestion("example.org.", dns.TypeA)
+	response, err := dns.Exchange(query, server)
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Println(response.Authoritative, response.Rcode == dns.RcodeSuccess)
+	// Output: true true
+}

core/dnsserver/server.go

@@ -1,4 +1,15 @@
-// Package dnsserver implements all the interfaces from Caddy, so that CoreDNS can be a servertype plugin.
+// Package dnsserver implements CoreDNS as a Caddy server type.
+//
+// Importing this package registers the "dns" server type with Caddy. Programs
+// embedding CoreDNS can import only the plugins they need, set Directives before
+// starting a server, and pass an in-memory Corefile to [caddy.Start]. They should
+// not call coremain.Run, which provides the command-line program behavior such
+// as flag parsing, signal handling, and blocking until shutdown.
+// Before stopping an embedded instance, run its shutdown callbacks so that
+// plugins can release resources.
+//
+// Directives and Caddy's plugin registry are process-wide. Configure them
+// before starting any servers and do not mutate them while servers are running.
 package dnsserver
 
 import (