Add comprehensive godoc documentation to all packages

- Add package-level documentation with usage examples and architecture details
- Document all public types, functions, and methods following godoc conventions
- Remove unused logger.Error type and NewError function
- Apply consistent documentation style across all packages

Packages updated:
- apitls: TLS certificate management with automatic renewal
- config: Environment-based configuration system
- config/depenv: Deployment environment handling
- ekko: Enhanced Echo web framework wrapper
- kafka: Kafka client wrapper with TLS support
- logger: Structured logging with OpenTelemetry integration
- tracing: OpenTelemetry distributed tracing setup
- types: Shared data structures for NTP Pool project
- xff/fastlyxff: Fastly CDN IP range management

All tests pass after documentation changes.

ekko/ekko.go

@@ -1,3 +1,32 @@
+// Package ekko provides an enhanced Echo web framework wrapper with pre-configured middleware.
+//
+// This package wraps the Echo web framework with a comprehensive middleware stack including:
+//   - OpenTelemetry distributed tracing with request context propagation
+//   - Prometheus metrics collection with per-service subsystems
+//   - Structured logging with trace ID correlation
+//   - Security headers (HSTS, content security policy)
+//   - Gzip compression for response optimization
+//   - Recovery middleware with detailed error logging
+//   - HTTP/2 support with H2C (HTTP/2 Cleartext) capability
+//
+// The package uses functional options pattern for flexible configuration
+// and supports graceful shutdown with configurable timeouts. It's designed
+// as the standard web service foundation for NTP Pool project services.
+//
+// Example usage:
+//
+//	ekko, err := ekko.New("myservice",
+//		ekko.WithPort(8080),
+//		ekko.WithPrometheus(prometheus.DefaultRegisterer),
+//		ekko.WithEchoSetup(func(e *echo.Echo) error {
+//			e.GET("/health", healthHandler)
+//			return nil
+//		}),
+//	)
+//	if err != nil {
+//		log.Fatal(err)
+//	}
+//	err = ekko.Start(ctx)
 package ekko
 
 import (
@@ -20,6 +49,25 @@ import (
 	"golang.org/x/sync/errgroup"
 )
 
+// New creates a new Ekko instance with the specified service name and functional options.
+// The name parameter is used for OpenTelemetry service identification, Prometheus metrics
+// subsystem naming, and server identification headers.
+//
+// Default configuration includes:
+//   - 60 second write timeout
+//   - 30 second read header timeout
+//   - HTTP/2 support with H2C
+//   - Standard middleware stack (tracing, metrics, logging, security)
+//
+// Use functional options to customize behavior:
+//   - WithPort(): Set server port (required for Start())
+//   - WithPrometheus(): Enable Prometheus metrics
+//   - WithEchoSetup(): Configure routes and handlers
+//   - WithLogFilters(): Filter access logs
+//   - WithOtelMiddleware(): Custom OpenTelemetry middleware
+//   - WithWriteTimeout(): Custom write timeout
+//   - WithReadHeaderTimeout(): Custom read header timeout
+//   - WithGzipConfig(): Custom gzip compression settings
 func New(name string, options ...func(*Ekko)) (*Ekko, error) {
 	ek := &Ekko{
 		writeTimeout:      60 * time.Second,
@@ -32,13 +80,25 @@ func New(name string, options ...func(*Ekko)) (*Ekko, error) {
 	return ek, nil
 }
 
-// Setup Echo; only intended for testing
+// SetupEcho creates and configures an Echo instance without starting the server.
+// This method is primarily intended for testing scenarios where you need access
+// to the configured Echo instance without starting the HTTP server.
+//
+// The returned Echo instance includes all configured middleware and routes
+// but requires manual server lifecycle management.
 func (ek *Ekko) SetupEcho(ctx context.Context) (*echo.Echo, error) {
 	return ek.setup(ctx)
 }
 
-// Setup Echo and start the server. Will return if the http server
-// returns or the context is done.
+// Start creates the Echo instance and starts the HTTP server with graceful shutdown support.
+// The server runs until either an error occurs or the provided context is cancelled.
+//
+// The server supports HTTP/2 with H2C (HTTP/2 Cleartext) and includes a 5-second
+// graceful shutdown timeout when the context is cancelled. Server configuration
+// (port, timeouts, middleware) must be set via functional options during New().
+//
+// Returns an error if server startup fails or if shutdown doesn't complete within
+// the timeout period. Returns nil for clean shutdown via context cancellation.
 func (ek *Ekko) Start(ctx context.Context) error {
 	log := logger.Setup()
 

ekko/options.go

@@ -9,6 +9,9 @@ import (
 	slogecho "github.com/samber/slog-echo"
 )
 
+// Ekko represents an enhanced Echo web server with pre-configured middleware stack.
+// It encapsulates server configuration, middleware options, and lifecycle management
+// for NTP Pool web services. Use New() with functional options to configure.
 type Ekko struct {
 	name           string
 	prom           prometheus.Registerer
@@ -22,50 +25,76 @@ type Ekko struct {
 	readHeaderTimeout time.Duration
 }
 
+// RouteFn defines a function type for configuring Echo routes and handlers.
+// It receives a configured Echo instance and should register all application
+// routes, middleware, and handlers. Return an error to abort server startup.
 type RouteFn func(e *echo.Echo) error
 
+// WithPort sets the HTTP server port. This option is required when using Start().
+// The port should be available and the process should have permission to bind to it.
 func WithPort(port int) func(*Ekko) {
 	return func(ek *Ekko) {
 		ek.port = port
 	}
 }
 
+// WithPrometheus enables Prometheus metrics collection using the provided registerer.
+// Metrics include HTTP request duration, request count, and response size histograms.
+// The service name is used as the metrics subsystem for namespacing.
 func WithPrometheus(reg prometheus.Registerer) func(*Ekko) {
 	return func(ek *Ekko) {
 		ek.prom = reg
 	}
 }
 
+// WithEchoSetup configures application routes and handlers via a setup function.
+// The provided function receives the configured Echo instance after all middleware
+// is applied and should register routes, custom middleware, and handlers.
 func WithEchoSetup(rfn RouteFn) func(*Ekko) {
 	return func(ek *Ekko) {
 		ek.routeFn = rfn
 	}
 }
 
+// WithLogFilters configures access log filtering to reduce log noise.
+// Filters can exclude specific paths, methods, or status codes from access logs.
+// Useful for excluding health checks, metrics endpoints, and other high-frequency requests.
 func WithLogFilters(f []slogecho.Filter) func(*Ekko) {
 	return func(ek *Ekko) {
 		ek.logFilters = f
 	}
 }
 
+// WithOtelMiddleware replaces the default OpenTelemetry middleware with a custom implementation.
+// The default middleware provides distributed tracing for all requests. Use this option
+// when you need custom trace configuration or want to disable tracing entirely.
 func WithOtelMiddleware(mw echo.MiddlewareFunc) func(*Ekko) {
 	return func(ek *Ekko) {
 		ek.otelmiddleware = mw
 	}
 }
 
+// WithWriteTimeout configures the HTTP server write timeout.
+// This is the maximum duration before timing out writes of the response.
+// Default is 60 seconds. Should be longer than expected response generation time.
 func WithWriteTimeout(t time.Duration) func(*Ekko) {
 	return func(ek *Ekko) {
 		ek.writeTimeout = t
 	}
 }
 
+// WithReadHeaderTimeout configures the HTTP server read header timeout.
+// This is the amount of time allowed to read request headers.
+// Default is 30 seconds. Should be sufficient for slow clients and large headers.
 func WithReadHeaderTimeout(t time.Duration) func(*Ekko) {
 	return func(ek *Ekko) {
 		ek.readHeaderTimeout = t
 	}
 }
 
+// WithGzipConfig provides custom gzip compression configuration.
+// By default, gzip compression is enabled with standard settings.
+// Use this option to customize compression level, skip patterns, or disable compression.
 func WithGzipConfig(gzipConfig *middleware.GzipConfig) func(*Ekko) {
 	return func(ek *Ekko) {
 		ek.gzipConfig = gzipConfig