Documentation
¶
Overview ¶
Package server manages the HTTP server lifecycle with graceful shutdown.
It wraps net/http.Server and handles OS signal interception (SIGINT, SIGTERM), in-flight request draining, and ordered cleanup of external resources.
Basic usage:
srv := server.New(mux, server.WithHost(":3000"))
if err := srv.Run(); err != nil {
log.Fatal(err)
}
Registering shutdown hooks:
srv := server.New(mux,
server.WithShutdownFunc(func(ctx context.Context) error {
return db.Close()
}),
)
Index ¶
- type Option
- func WithHost(host string) Option
- func WithIdleTimeout(d time.Duration) Option
- func WithLogger(log *slog.Logger) Option
- func WithReadTimeout(d time.Duration) Option
- func WithServer(srv *http.Server) Option
- func WithShutdownFunc(fn func(ctx context.Context) error) Option
- func WithShutdownTimeout(d time.Duration) Option
- func WithTLS(certFile, keyFile string) Option
- func WithWriteTimeout(d time.Duration) Option
- type Server
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Option ¶
type Option func(*options)
Option configures a Server.
func WithIdleTimeout ¶
WithIdleTimeout sets the maximum amount of time to wait for the next request when keep-alives are enabled. Default is 120s.
func WithLogger ¶
WithLogger sets the logger used for server lifecycle events. Default is slog.Default().
func WithReadTimeout ¶
WithReadTimeout sets the maximum duration for reading the entire request, including the body. Default is 5s.
func WithServer ¶
WithServer injects an existing http.Server as the base configuration. Any other options applied after this one override the corresponding fields on the provided server.
func WithShutdownFunc ¶
WithShutdownFunc registers a function to call during graceful shutdown, before the HTTP server is stopped. Multiple shutdown functions are called in the order they were registered.
Example ¶
package main
import (
"context"
"fmt"
"net/http"
"github.com/adamwoolhether/httper/web/server"
)
func main() {
cleanup := func(ctx context.Context) error {
fmt.Println("closing database")
return nil
}
mux := http.NewServeMux()
srv := server.New(mux,
server.WithShutdownFunc(cleanup),
)
// Simulate a graceful shutdown instead of calling srv.Run(),
// which blocks on OS signals.
if err := srv.Shutdown(context.Background()); err != nil {
fmt.Println("shutdown error:", err)
return
}
fmt.Println("shutdown complete")
}
Output: closing database shutdown complete
func WithShutdownTimeout ¶
WithShutdownTimeout sets the maximum duration Server.Run waits for in-flight requests to complete after receiving a shutdown signal. Default is 20s. Callers of Server.Shutdown control the deadline via context instead.
func WithTLS ¶
WithTLS configures the server to use TLS with the given certificate and key files. When set, the server calls ListenAndServeTLS instead of ListenAndServe.
Example ¶
package main
import (
"fmt"
"net/http"
"github.com/adamwoolhether/httper/web/server"
)
func main() {
srv := server.New(http.NewServeMux(),
server.WithHost(":8443"),
server.WithTLS("cert.pem", "key.pem"),
)
_ = srv
fmt.Println("TLS configured")
}
Output: TLS configured
func WithWriteTimeout ¶
WithWriteTimeout sets the maximum duration before timing out writes of the response. Default is 10s.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server wraps an http.Server with signal-driven graceful shutdown.
func New ¶
New creates a Server for the given handler. A default host of ":8080", sensible timeouts, and the default slog logger are used unless overridden via options.
Example ¶
package main
import (
"fmt"
"log/slog"
"net/http"
"time"
"github.com/adamwoolhether/httper/web/server"
)
func main() {
mux := http.NewServeMux()
mux.HandleFunc("GET /", func(w http.ResponseWriter, r *http.Request) {
fmt.Fprintln(w, "hello")
})
srv := server.New(mux,
server.WithHost(":3000"),
server.WithReadTimeout(10*time.Second),
server.WithLogger(slog.Default()),
)
_ = srv // srv.Run() blocks until signal
fmt.Println("server configured")
}
Output: server configured
Source Files