Documentation
¶
Overview ¶
Package server provides utilities for creating and running HTTP servers with environment-based configuration and graceful shutdown handling.
The server package integrates with the config package to automatically load server settings (port, timeouts) from environment variables. It provides graceful shutdown on interrupt signals with proper resource cleanup.
Basic usage:
func main() {
mux := http.NewServeMux()
mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
w.Write([]byte("Hello, World!"))
})
if err := server.Run(context.Background(), mux); err != nil {
log.Fatal(err)
}
}
The Run function handles all server lifecycle management including:
- Loading configuration from environment variables
- Starting the HTTP server in a goroutine
- Listening for interrupt signals (SIGINT, SIGTERM)
- Performing graceful shutdown with a 10-second timeout
For more control over the server instance, use NewServerWithConfig to create an *http.Server and manage its lifecycle manually.
All functions are safe for concurrent use.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewServerWithConfig ¶
NewServerWithConfig creates a new http.Server configured from environment variables.
The server is configured using config.ServerConfig, which loads settings for:
- Port (env: PORT, default: 8080)
- ReadTimeout (env: READ_TIMEOUT, default: 5 seconds)
- WriteTimeout (env: WRITE_TIMEOUT, default: 10 seconds)
- IdleTimeout (env: IDLE_TIMEOUT, default: 120 seconds)
- Environment (env: ENVIRONMENT, default: Local)
The function returns an error if the configuration cannot be parsed or validated. Common error cases include invalid port numbers or timeout values.
The returned server is ready to use with ListenAndServe or Shutdown methods. For automatic lifecycle management with graceful shutdown, use the Run function instead.
This function is safe for concurrent use.
func Run ¶
Run starts the HTTP server with the provided handler and manages its lifecycle.
This function handles the complete server lifecycle including:
- Loading configuration from environment variables via NewServerWithConfig
- Starting the HTTP server in a background goroutine
- Listening for interrupt signals (SIGINT) on the provided context
- Performing graceful shutdown with a 10-second timeout when interrupted
The function blocks until the server is shut down, either by:
- An interrupt signal (Ctrl+C)
- Cancellation of the provided context
- A fatal error during server creation
Returns an error only if server creation fails (e.g., invalid configuration). Errors during ListenAndServe or Shutdown are logged to stderr but do not cause the function to return an error, as they may occur during normal shutdown.
Example usage:
mux := http.NewServeMux()
mux.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
w.WriteHeader(http.StatusOK)
})
if err := server.Run(context.Background(), mux); err != nil {
log.Fatal(err)
}
This function is safe for concurrent use.
Types ¶
This section is empty.
Source Files