docs(admission): add package and symbol doc comments

Add package-level documentation and Go doc comments for all exported
types, functions, and methods across the admission package, its plugin
sub-packages, and connection/listener wrappers.

admission/plugin/grpc.go

@@ -1,3 +1,9 @@
+// Package admission implements gRPC-based admission plugins.
+// An admission plugin delegates the admit/deny decision to an external
+// service via gRPC. This allows admission logic to be implemented in
+// a separate process using any language supported by protobuf.
+//
+// The gRPC service definition is in plugin/admission/proto.
 package admission
 
 import (
@@ -11,13 +17,27 @@ import (
 	"google.golang.org/grpc"
 )
 
+// grpcPlugin is an admission controller that delegates to an external
+// gRPC admission service.
+//
+// If the gRPC connection cannot be established at construction time,
+// the client field remains nil and Admit returns true (fail-open),
+// allowing all traffic through rather than blocking everything.
 type grpcPlugin struct {
 	conn   grpc.ClientConnInterface
 	client proto.AdmissionClient
 	log    logger.Logger
 }
 
-// NewGRPCPlugin creates an Admission plugin based on gRPC.
+// NewGRPCPlugin creates an admission controller that communicates with
+// an external gRPC admission service at the given address.
+//
+// The name is used only for log identification. The addr should be a
+// gRPC target string (e.g. "127.0.0.1:9000"). Additional plugin options
+// (TLS, token, retry) can be passed via opts.
+//
+// If the connection fails, the plugin logs the error and operates in
+// fail-open mode: all admission requests return true.
 func NewGRPCPlugin(name string, addr string, opts ...plugin.Option) admission.Admission {
 	var options plugin.Options
 	for _, opt := range opts {
@@ -43,6 +63,13 @@ func NewGRPCPlugin(name string, addr string, opts ...plugin.Option) admission.Ad
 	return p
 }
 
+// Admit sends an admission request to the external gRPC service.
+// It passes the network, address, and service name from the client
+// connection.
+//
+// If the gRPC client is nil (connection failed at startup), it returns
+// true (fail-open). If the RPC returns an error, it logs the error and
+// returns false.
 func (p *grpcPlugin) Admit(ctx context.Context, network, addr string, opts ...admission.Option) bool {
 	if p.client == nil {
 		return true
@@ -66,6 +93,7 @@ func (p *grpcPlugin) Admit(ctx context.Context, network, addr string, opts ...ad
 	return r.Ok
 }
 
+// Close closes the underlying gRPC connection if it implements io.Closer.
 func (p *grpcPlugin) Close() error {
 	if closer, ok := p.conn.(io.Closer); ok {
 		return closer.Close()

admission/plugin/http.go

@@ -11,16 +11,24 @@ import (
 	"github.com/go-gost/x/internal/plugin"
 )
 
+// httpPluginRequest is the JSON payload sent to the HTTP admission service.
 type httpPluginRequest struct {
 	Service string `json:"service"`
 	Network string `json:"network"`
 	Addr    string `json:"addr"`
 }
 
+// httpPluginResponse is the JSON response expected from the HTTP
+// admission service. OK indicates whether the address is admitted.
 type httpPluginResponse struct {
 	OK bool `json:"ok"`
 }
 
+// httpPlugin is an admission controller that delegates to an external
+// HTTP admission service via JSON POST requests.
+//
+// The HTTP client is created via plugin.NewHTTPClient, which configures
+// timeouts, TLS, and token-based authentication from plugin options.
 type httpPlugin struct {
 	url    string
 	client *http.Client
@@ -28,7 +36,14 @@ type httpPlugin struct {
 	log    logger.Logger
 }
 
-// NewHTTPPlugin creates an Admission plugin based on HTTP.
+// NewHTTPPlugin creates an admission controller that communicates with
+// an external HTTP admission service at the given URL.
+//
+// The name is used only for log identification. On each Admit call,
+// a JSON-encoded httpPluginRequest is POSTed to the URL. A 200 response
+// with {"ok": true} admits the address; any other response denies it.
+//
+// If the HTTP client is nil, all admission requests return false.
 func NewHTTPPlugin(name string, url string, opts ...plugin.Option) admission.Admission {
 	var options plugin.Options
 	for _, opt := range opts {
@@ -46,6 +61,16 @@ func NewHTTPPlugin(name string, url string, opts ...plugin.Option) admission.Adm
 	}
 }
 
+// Admit sends a JSON POST request to the configured HTTP endpoint.
+// The request includes the service name, network, and client address.
+//
+// The address is admitted only if ALL of the following are true:
+//   - The HTTP client is non-nil
+//   - The request is successfully sent
+//   - The response has status 200 OK
+//   - The response body decodes as JSON with "ok": true
+//
+// Any error, non-200 status, or decode failure results in denial.
 func (p *httpPlugin) Admit(ctx context.Context, network, addr string, opts ...admission.Option) (ok bool) {
 	if p.client == nil {
 		return
@@ -92,6 +117,8 @@ func (p *httpPlugin) Admit(ctx context.Context, network, addr string, opts ...ad
 	return res.OK
 }
 
+// Close closes idle connections in the HTTP client's connection pool.
+// It does not shut down the client itself.
 func (p *httpPlugin) Close() error {
 	if p.client != nil {
 		p.client.CloseIdleConnections()