core/dnsserver: support explicit registration for embedded hosts (#8525)

* core/dnsserver: test host-plugin embedding with forward

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

* core/dnsserver: add a directive setter for embedded hosts

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

* core/dnsserver: support explicit server registration for embedded hosts

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

---------

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

core/dnsserver/server.go

@@ -1,15 +1,44 @@
 // 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.
+// By default, importing this package registers the "dns" server type with Caddy.
+// Programs embedding CoreDNS can import only the plugins they need, call
+// [SetDirectives] before starting a server, and pass an in-memory Corefile to
+// [caddy.Start]. They should not import coremain or the generated all-plugin
+// bundle: coremain provides command-line behavior such as flag registration,
+// signal handling, and blocking until shutdown, and registers the server type.
 // Before stopping an embedded instance, run its shutdown callbacks so that
 // plugins can release resources.
 //
+// A host can register a custom directive with [plugin.Register] before starting
+// Caddy; it does not need to rebuild CoreDNS or modify plugin.cfg. Include the
+// directive in the list passed to SetDirectives at the desired execution
+// position, and use [GetConfig] and [Config.AddPlugin] in its setup function to
+// add the handler. The setup function can register startup and shutdown callbacks
+// on the Caddy controller.
+// Directives determines execution order, not the order in the Corefile.
+// Each directive must be registered only once per process.
+//
+// SetDirectives copies the supplied list and rejects empty or duplicate names.
+// Direct assignment to Directives remains supported for existing callers.
+// Neither entry point imports plugins or registers them on the host's behalf.
+//
 // Directives and Caddy's plugin registry are process-wide. Configure them
 // before starting any servers and do not mutate them while servers are running.
+// Automatic server-type registration is retained for existing embedding users;
+// it does not start listeners or prevent the host from selecting directives.
+//
+// To control when the DNS server type is registered, build the host with
+// -tags=coredns_manual_registration. This excludes this package's registration
+// init function. After selecting directives and registering host plugins, call
+// [Register] before caddy.Start. Register is idempotent and also works in default
+// builds. It returns an error if another caller already registered a DNS server
+// type, leaving that registration unchanged.
+//
+// The build tag does not disable initialization in Caddy or individual plugins,
+// or make their registries instance-local. Selected plugins must not import
+// coremain, directly or transitively, to avoid its command-line initialization
+// and server-type registration. The CoreDNS command-line program explicitly
+// registers the server type in both build modes.
 package dnsserver
 
 import (