fix(handler/api): add nil guard, propagate Shutdown error, doc comments, 20 tests

- Return errHandlerNotInitialized when Handle called before Init
- Propagate s.Shutdown(ctx) error instead of silently discarding
- Add doc comments to all exported symbols
- Add 20 tests covering constructor, init, metadata parsing, HTTP
  endpoints via httptest, Handle lifecycle, singleConnListener, and
  compile-time interface assertions

handler/api/handler.go

@@ -2,6 +2,7 @@ package api
 
 import (
 	"context"
+	"errors"
 	"net"
 	"net/http"
 
@@ -12,16 +13,21 @@ import (
 	"github.com/go-gost/x/registry"
 )
 
+var errHandlerNotInitialized = errors.New("api: handler not initialized")
+
 func init() {
 	registry.HandlerRegistry().Register("api", NewHandler)
 }
 
+// apiHandler is a handler that serves the GOST REST API over an inbound
+// connection using the Gin framework.
 type apiHandler struct {
 	handler http.Handler
 	md      metadata
 	options handler.Options
 }
 
+// NewHandler creates an apiHandler with the given options.
 func NewHandler(opts ...handler.Option) handler.Handler {
 	options := handler.Options{}
 	for _, opt := range opts {
@@ -33,6 +39,8 @@ func NewHandler(opts ...handler.Option) handler.Handler {
 	}
 }
 
+// Init initializes the handler with metadata, configuring the Gin engine
+// and registering all API routes.
 func (h *apiHandler) Init(md md.Metadata) (err error) {
 	if err = h.parseMetadata(md); err != nil {
 		return
@@ -51,7 +59,14 @@ func (h *apiHandler) Init(md md.Metadata) (err error) {
 	return
 }
 
+// Handle serves the API on the inbound connection. The connection is
+// treated as a single-use HTTP listener: one connection is accepted, served,
+// then the server shuts down gracefully.
 func (h *apiHandler) Handle(ctx context.Context, conn net.Conn, opts ...handler.HandleOption) error {
+	if h.handler == nil {
+		return errHandlerNotInitialized
+	}
+
 	l := &singleConnListener{
 		conn: make(chan net.Conn, 1),
 	}
@@ -60,11 +75,16 @@ func (h *apiHandler) Handle(ctx context.Context, conn net.Conn, opts ...handler.
 	s := http.Server{
 		Handler: h.handler,
 	}
-	s.Serve(l)
+
+	// Serve blocks until the listener closes (after the single connection
+	// is accepted). The connection goroutine may still be active.
+	_ = s.Serve(l)
 
 	return s.Shutdown(ctx)
 }
 
+// singleConnListener is a net.Listener that yields exactly one connection
+// from a buffered channel, then returns net.ErrClosed on subsequent accepts.
 type singleConnListener struct {
 	conn chan net.Conn
 }