golib/httpserver/README.md

httpserver Package

httpserver/pool Subpackage

The httpserver/pool package provides a high-level abstraction for managing a pool of httpserver Package.
It allows you to configure, start, stop, and monitor multiple HTTP server instances as a unified group, with advanced filtering, merging, and handler management capabilities.

Features

• Manage multiple HTTP server instances as a pool
• Add, remove, and retrieve servers by bind address
• Start, stop, and restart all servers in the pool with aggregated error handling
• Filter and list servers by name, bind address, or expose address (with pattern or regex)
• Merge pools and clone pool state
• Register global handler functions for all servers
• Monitor all servers and retrieve monitoring data
• Thread-safe operations

---

Main Types & Interfaces

Pool Interface

The main interface for managing a pool of HTTP servers. Key methods include:

• Start(ctx context.Context) error: Start all servers in the pool.
• Stop(ctx context.Context) error: Stop all servers in the pool.
• Restart(ctx context.Context) error: Restart all servers in the pool.
• IsRunning() bool: Check if any server in the pool is running.
• Uptime() time.Duration: Get the maximum uptime among all servers.
• Handler(fct FuncHandler): Register a global handler function for all servers.
• Monitor(vrs Version) ([]Monitor, error): Retrieve monitoring data for all servers.
• Clone(ctx context.Context) Pool: Clone the pool (optionally with a new context).
• Merge(p Pool, defLog FuncLog) error: Merge another pool into this one.
• Manage and Filter interfaces for advanced management and filtering.

Manage Interface

• Walk(fct FuncWalk) bool: Iterate over all servers.
• StoreNew(cfg Config, defLog FuncLog) error: Add a new server from config.
• Load(bindAddress string) Server: Retrieve a server by bind address.
• Delete(bindAddress string): Remove a server by bind address.
• MonitorNames() []string: List all monitor names.

Filter Interface

• Has(bindAddress string) bool: Check if a server exists.
• Len() int: Number of servers in the pool.
• List(fieldFilter, fieldReturn FieldType, pattern, regex string) []string: List server fields matching criteria.
• Filter(field FieldType, pattern, regex string) Pool: Filter servers by field and pattern/regex.

Config Type

A slice of server configuration objects. Provides helper methods to:

• Set global handler, TLS, and context functions for all configs
• Validate all configs
• Instantiate a pool from the configs

---

Example Usage

import (
    "github.com/nabbar/golib/httpserver/pool"
    "github.com/nabbar/golib/httpserver"
    "github.com/nabbar/golib/logger"
    "context"
)

cfgs := pool.Config{
    /* ... fill with httpserver.Config objects ... */
}

err := cfgs.Validate()
if err != nil {
    // handle config validation error
}

p, err := cfgs.Pool(nil, nil, logger.Default)
if err != nil {
    // handle pool creation error
}

// Start all servers
if err := p.Start(context.Background()); err != nil {
    // handle start error
}

// Stop all servers
if err := p.Stop(context.Background()); err != nil {
    // handle stop error
}

---

Error Handling

All errors are wrapped with custom codes for diagnostics, such as:

• ErrorParamEmpty
• ErrorPoolAdd
• ErrorPoolValidate
• ErrorPoolStart
• ErrorPoolStop
• ErrorPoolRestart
• ErrorPoolMonitor

Use err.Error() for user-friendly messages and check error codes for diagnostics.

---

Filtering and Listing

You can filter or list servers in the pool by name, bind address, or expose address, using exact match or regular expressions.

// List all bind addresses matching a pattern
binds := p.List(FieldBind, FieldBind, "127.0.0.1:8080", "")

// Filter pool by expose address regex
filtered := p.Filter(FieldExpose, "", "^/api")

---

Monitoring

Retrieve monitoring data for all servers in the pool:

monitors, err := p.Monitor(version)
if err != nil {
    // handle monitoring error
}

---

Notes

• The pool is thread-safe and suitable for concurrent use.
• All operations are designed for Go 1.18+.
• Integrates with the logger, context, and monitor packages for advanced features.

---

Package httpserver

The httpserver package provides advanced abstractions for configuring, running, and monitoring HTTP servers in Go. It is designed for robust, concurrent, and production-grade server management, supporting TLS, custom handlers, logging, and health monitoring.

---

Key Features

• Configurable HTTP/HTTPS servers with extensive options (timeouts, keep-alive, HTTP/2, TLS, etc.)
• Handler registration for flexible routing and API management
• Integrated logging and monitoring support
• Thread-safe and suitable for concurrent use
• Custom error codes for diagnostics and troubleshooting

---

Main Types

Config

Represents the configuration for a single HTTP server instance.
Key fields include:

• Name: Unique server name (required)
• Listen: Bind address (host:port or unix socket, required)
• Expose: Public/external address (URL, required)
• HandlerKey: Key to associate with a specific handler
• Disabled: Enable/disable the server without removing its config
• Monitor: Monitoring configuration
• TLSMandatory: Require valid TLS configuration to start
• TLS: TLS settings (can inherit defaults)
• HTTP/2 and HTTP options: timeouts, max handlers, keep-alive, etc.
• Logger: Logger configuration

Helper methods:

• Clone(): Deep copy of the config
• RegisterHandlerFunc(f): Register a handler function
• SetDefaultTLS(f): Set default TLS provider
• SetContext(f): Set parent context provider
• Validate(): Validate config fields and constraints
• Server(defLog): Instantiate a server from the config

---

Server Interface

Represents a running HTTP server instance.

• Start(ctx) error: Start the server
• Stop(ctx) error: Stop the server gracefully
• Restart(ctx) error: Restart the server
• IsRunning() bool: Check if the server is running
• GetConfig() *Config: Get the current config
• SetConfig(cfg, defLog) error: Update the config
• Handler(f): Register handler function
• Merge(srv, defLog) error: Merge another server's config
• Monitor(version): Get monitoring data
• MonitorName() string: Get monitor name
• GetName() string: Get server name
• GetBindable() string: Get bind address
• GetExpose() string: Get expose address
• IsDisable() bool: Check if server is disabled
• IsTLS() bool: Check if TLS is enabled

---

Handler Management

Handlers are registered via a function returning a map of handler keys to http.Handler instances.
You can associate a server with a specific handler using the HandlerKey field.

---

Monitoring

Integrated with the monitoring system, each server can expose runtime, build, and health information.
Use Monitor(version) to retrieve monitoring data.

---

Error Handling

All errors are wrapped with custom codes for diagnostics, such as:

• ErrorParamEmpty
• ErrorHTTP2Configure
• ErrorServerValidate
• ErrorServerStart
• ErrorPortUse

Use err.Error() for user-friendly messages and check error codes for diagnostics.

---

Example Usage

import (
    "github.com/nabbar/golib/httpserver"
    "github.com/nabbar/golib/logger"
    "context"
)

cfg := httpserver.Config{
    Name:   "api-server",
    Listen: "127.0.0.1:8080",
    Expose: "http://api.example.com:8080",
    // ... other fields
}
cfg.RegisterHandlerFunc(myHandlerFunc)
cfg.SetDefaultTLS(myTLSProvider)
cfg.SetContext(myContextProvider)

if err := cfg.Validate(); err != nil {
    // handle config error
}

srv, err := httpserver.New(cfg, logger.Default)
if err != nil {
    // handle server creation error
}

if err := srv.Start(context.Background()); err != nil {
    // handle start error
}

// ... later
if err := srv.Stop(context.Background()); err != nil {
    // handle stop error
}

---

Notes

• The package is designed for Go 1.18+.
• All operations are thread-safe.
• Integrates with logger, context, and monitor packages for advanced features.
• For advanced management of multiple servers, see the httpserver/pool package.