Documentation
¶
Overview ¶
Package httpserver is the standard-library-idiomatic core of the server kit: a worker.Runnable that serves any http.Handler on its own listener with graceful shutdown.
The seam is net/http's own abstraction, http.Handler — so the handler can be a stdlib *http.ServeMux, the SDK's rest/router, a grpc-gateway runtime.ServeMux, or any third-party router. REST, the gRPC-gateway and the status server (debugsrv) are all just this one brick wrapped around a different handler; register each with a single worker.Group and they start, fail and drain independently, like Lego.
Usage ¶
srv := httpserver.New(httpserver.Config{
Name: "rest-server",
Addr: ":8080",
ShutdownTimeout: 10 * time.Second,
Logger: log.Slog(),
}, router)
grp := worker.NewGroup(log.Slog(), 10*time.Second)
grp.Add(srv) // alongside grpcserver.Server, debugsrv.Server, ...
_ = grp.Run(ctx)
Tests and callers that manage their own listener can use Serve instead of Start:
lis, _ := net.Listen("tcp", "localhost:0")
go srv.Serve(lis)
// ... drive lis.Addr(); then srv.Stop(ctx)
Config ¶
Only Addr is required; everything else has a safe default.
- Addr: listen address, e.g. ":8080".
- Name: supervisor/log name (default "http-server"); set it so REST/gateway/ status read distinctly.
- ReadHeaderTimeout: bounds reading request headers (default 5s) against Slowloris-style stalls; a negative value disables it.
- ReadTimeout / WriteTimeout / IdleTimeout: map to the http.Server fields of the same name; zero leaves each at the net/http default.
- ShutdownTimeout: bounds graceful shutdown when Stop's ctx has no deadline (default 10s).
- Logger: receives start/stop lines; defaults to slog.Default().
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// Addr is the listen address, e.g. ":8080".
Addr string
// Name identifies the server to the supervisor and in logs (default
// "http-server"). Set it so REST/gateway/status read distinctly.
Name string
// ReadHeaderTimeout bounds reading request headers (default 5s) to guard
// against Slowloris-style stalls. Set a negative duration to disable it.
ReadHeaderTimeout time.Duration
// ReadTimeout, WriteTimeout and IdleTimeout map to the http.Server fields of
// the same name; zero leaves each at the net/http default (no limit).
ReadTimeout time.Duration
WriteTimeout time.Duration
IdleTimeout time.Duration
// ShutdownTimeout bounds graceful shutdown when Stop's context carries no
// deadline (default 10s).
ShutdownTimeout time.Duration
// Logger receives start/stop lines; defaults to slog.Default().
Logger *slog.Logger
}
Config configures a Server. Only Addr is required; every other field falls back to a safe default.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server serves an http.Handler on its own listener and implements worker.Runnable (Start/Stop/Name). It is the standard-library-idiomatic core of the server kit: REST, the gRPC-gateway and the status server are all just this brick wrapped around a different http.Handler, so they compose in a single worker.Group.
func New ¶
New wraps h in an *http.Server configured by cfg. The server is not listening until Start (or Serve) is called.
func (*Server) Serve ¶
Serve serves on the provided listener until Stop. It is useful for tests (an ephemeral localhost:0 listener) and for callers that manage their own listener. ErrServerClosed is treated as a clean shutdown.
Source Files