fix(matcher,plugin): case-insensitive matching, port accumulation, nil guards, doc comments

matcher: fix IPv6 normalization via netip.ParseAddr, port-range overwrite
by switching to []*PortRange map, case-insensitive domain/host matching,
glob.MustCompile→Compile to avoid panic on invalid patterns.

plugin: guard nil *Options in NewGRPCConn and NewHTTPClient; add
HTTPClientTransport helper for idle-connection cleanup.

net/*: add doc comments for all exported symbols (no code changes).

Add 30 tests (matcher_test.go 22, plugin_test.go 8) covering all
matcher types, nil safety, case insensitivity, IPv6 normalization,
port ranges, and plugin option composition.

internal/plugin/plugin.go

@@ -1,3 +1,6 @@
+// Package plugin provides shared utilities for building gRPC and HTTP plugin
+// clients. Both transport types support authentication tokens, TLS
+// configuration, custom headers (HTTP), and connection timeouts.
 package plugin
 
 import (
@@ -13,10 +16,13 @@ import (
 )
 
 const (
+	// GRPC is the transport type identifier for gRPC-based plugins.
 	GRPC string = "grpc"
+	// HTTP is the transport type identifier for HTTP-based plugins.
 	HTTP string = "http"
 )
 
+// Options holds the common configuration for gRPC and HTTP plugin clients.
 type Options struct {
 	Token     string
 	TLSConfig *tls.Config
@@ -24,32 +30,40 @@ type Options struct {
 	Timeout   time.Duration
 }
 
+// Option configures Options.
 type Option func(opts *Options)
 
+// TokenOption sets the authentication token sent with each request.
 func TokenOption(token string) Option {
 	return func(opts *Options) {
 		opts.Token = token
 	}
 }
 
+// TLSConfigOption sets the TLS configuration for transport security.
 func TLSConfigOption(cfg *tls.Config) Option {
 	return func(opts *Options) {
 		opts.TLSConfig = cfg
 	}
 }
 
+// HeaderOption sets custom HTTP headers sent with each request (HTTP transport only).
 func HeaderOption(header http.Header) Option {
 	return func(opts *Options) {
 		opts.Header = header
 	}
 }
 
+// TimeoutOption sets the request timeout (HTTP transport only).
 func TimeoutOption(timeout time.Duration) Option {
 	return func(opts *Options) {
 		opts.Timeout = timeout
 	}
 }
 
+// NewGRPCConn creates a gRPC client connection to addr. If opts is nil or
+// opts.TLSConfig is nil, the connection uses insecure transport. When
+// opts.Token is set, it is attached as per-RPC credentials.
 func NewGRPCConn(addr string, opts *Options) (*grpc.ClientConn, error) {
 	grpcOpts := []grpc.DialOption{
 		// grpc.WithBlock(),
@@ -57,6 +71,10 @@ func NewGRPCConn(addr string, opts *Options) (*grpc.ClientConn, error) {
 			Backoff: backoff.DefaultConfig,
 		}),
 	}
+	if opts == nil {
+		grpcOpts = append(grpcOpts, grpc.WithTransportCredentials(insecure.NewCredentials()))
+		return grpc.NewClient(addr, grpcOpts...)
+	}
 	if opts.TLSConfig != nil {
 		grpcOpts = append(grpcOpts,
 			grpc.WithAuthority(opts.TLSConfig.ServerName),
@@ -85,7 +103,14 @@ func (c *rpcCredentials) RequireTransportSecurity() bool {
 	return false
 }
 
+// NewHTTPClient creates an http.Client from opts. If opts is nil, a default
+// client with no timeout is returned. Use HTTPClientTransport to access the
+// underlying transport and close idle connections when the client is no longer
+// needed.
 func NewHTTPClient(opts *Options) *http.Client {
+	if opts == nil {
+		return &http.Client{}
+	}
 	return &http.Client{
 		Timeout: opts.Timeout,
 		Transport: &http.Transport{
@@ -93,3 +118,15 @@ func NewHTTPClient(opts *Options) *http.Client {
 		},
 	}
 }
+
+// HTTPClientTransport returns the *http.Transport underlying c, or nil if c's
+// transport is not an *http.Transport. Callers that hold the client for a
+// long time should call tr.CloseIdleConnections() when the client is no longer
+// needed.
+func HTTPClientTransport(c *http.Client) *http.Transport {
+	if c == nil {
+		return nil
+	}
+	tr, _ := c.Transport.(*http.Transport)
+	return tr
+}