docs(hosts,hop): add doc comments, fix missing httpLoader.Close, accumulate reload errors

- hosts/hosts.go: add package and symbol doc comments, fix missing
  httpLoader.Close() in Close()
- hosts/plugin: add doc comments for HTTP and gRPC plugin types
- hop/hop.go: add doc comments, accumulate reload/parse errors via errors.Join
  instead of silently discarding them
- hop/plugin/http.go: add doc comments and missing Close() method
- Add unit tests for hosts (580 lines) and hop (991 lines)

hosts/plugin/grpc.go

@@ -13,13 +13,14 @@ import (
 	"google.golang.org/grpc"
 )
 
+// grpcPlugin is a HostMapper that delegates lookups to a remote gRPC service.
 type grpcPlugin struct {
 	conn   grpc.ClientConnInterface
 	client proto.HostMapperClient
 	log    logger.Logger
 }
 
-// NewGRPCPlugin creates a HostMapper plugin based on gRPC.
+// NewGRPCPlugin creates a HostMapper plugin that delegates lookups to a remote gRPC endpoint.
 func NewGRPCPlugin(name string, addr string, opts ...plugin.Option) hosts.HostMapper {
 	var options plugin.Options
 	for _, opt := range opts {
@@ -44,6 +45,7 @@ func NewGRPCPlugin(name string, addr string, opts ...plugin.Option) hosts.HostMa
 	return p
 }
 
+// Lookup calls the gRPC HostMapper service and returns the resolved IPs.
 func (p *grpcPlugin) Lookup(ctx context.Context, network, host string, opts ...hosts.Option) (ips []net.IP, ok bool) {
 	p.log.Debugf("lookup %s/%s", host, network)
 
@@ -70,6 +72,7 @@ func (p *grpcPlugin) Lookup(ctx context.Context, network, host string, opts ...h
 	return
 }
 
+// Close closes the underlying gRPC connection.
 func (p *grpcPlugin) Close() error {
 	if p.conn == nil {
 		return nil

hosts/plugin/http.go

@@ -24,6 +24,7 @@ type httpPluginResponse struct {
 	OK  bool     `json:"ok"`
 }
 
+// httpPlugin is a HostMapper that delegates lookups to a remote HTTP service.
 type httpPlugin struct {
 	url    string
 	client *http.Client
@@ -31,7 +32,7 @@ type httpPlugin struct {
 	log    logger.Logger
 }
 
-// NewHTTPPlugin creates an HostMapper plugin based on HTTP.
+// NewHTTPPlugin creates a HostMapper plugin that delegates lookups to a remote HTTP endpoint.
 func NewHTTPPlugin(name string, url string, opts ...plugin.Option) hosts.HostMapper {
 	var options plugin.Options
 	for _, opt := range opts {
@@ -49,6 +50,7 @@ func NewHTTPPlugin(name string, url string, opts ...plugin.Option) hosts.HostMap
 	}
 }
 
+// Lookup sends a JSON POST request to the configured HTTP endpoint and returns the resolved IPs.
 func (p *httpPlugin) Lookup(ctx context.Context, network, host string, opts ...hosts.Option) (ips []net.IP, ok bool) {
 	p.log.Debugf("lookup %s/%s", host, network)