From 6199dc50a5623f2f4e7f7c6b7c27120a4cebaae5 Mon Sep 17 00:00:00 2001
From: houyuwushang <liuluoqianqiu@outlook.com>
Date: Fri, 14 Aug 2026 14:26:01 +0800
Subject: [PATCH] core/dnsserver: document in-process embedding (#8436)

Signed-off-by: houyuwushang <liuluoqianqiu@outlook.com>
---
 core/dnsserver/example_test.go | 58 ++++++++++++++++++++++++++++++++++
 core/dnsserver/server.go       | 13 +++++++-
 2 files changed, 70 insertions(+), 1 deletion(-)
 create mode 100644 core/dnsserver/example_test.go

diff --git a/core/dnsserver/example_test.go b/core/dnsserver/example_test.go
new file mode 100644
index 000000000..ae0763b07
--- /dev/null
+++ b/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
+}
diff --git a/core/dnsserver/server.go b/core/dnsserver/server.go
index c684fba21..453285f8b 100644
--- a/core/dnsserver/server.go
+++ b/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 (