httpserver

httpserver

import "github.com/brpaz/lib-go/httpserver"

Package httpserver provides a Server that wraps net/http.Server with sane defaults and graceful shutdown support.

Creating a server

Build a Server with New, passing a fully configured handler (e.g. a router). The server owns no routing logic of its own:

srv, err := httpserver.New(
    httpserver.WithHandler(router),
    httpserver.WithPort(8080),
)
if err != nil {
    return err
}

WithHandler is the only required option. WithPort, WithReadTimeout, WithWriteTimeout and WithIdleTimeout override the package defaults.

Running and stopping

Start blocks until the server stops, so run it in a goroutine and wait for a shutdown signal:

go func() {
    if err := srv.Start(); err != nil && !errors.Is(err, http.ErrServerClosed) {
        log.Fatal(err)
    }
}()

<-ctx.Done()

shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

if err := srv.Shutdown(shutdownCtx); err != nil {
    log.Fatal(err)
}

Shutdown drains active connections before returning, giving in-flight requests a chance to complete within the provided context's deadline.

Index

• type Option
  • func WithHandler(h http.Handler) Option
  • func WithIdleTimeout(d time.Duration) Option
  • func WithPort(port int) Option
  • func WithReadHeaderTimeout(d time.Duration) Option
  • func WithReadTimeout(d time.Duration) Option
  • func WithShutdownTimeout(d time.Duration) Option
  • func WithWriteTimeout(d time.Duration) Option
• type Server
  • func New(opts ...Option) (*Server, error)
  • func (s *Server) Addr() string
  • func (s *Server) Run(ctx context.Context) error
  • func (s *Server) Shutdown(ctx context.Context) error
  • func (s *Server) Start() error

type Option

Option configures a Server.

type Option func(*options)

func WithHandler

func WithHandler(h http.Handler) Option

WithHandler sets the HTTP handler for the server. Pass a fully configured Router here; the server owns no routing logic.

func WithIdleTimeout

func WithIdleTimeout(d time.Duration) Option

WithIdleTimeout sets the HTTP idle timeout.

func WithPort

func WithPort(port int) Option

WithPort sets the listening port.

func WithReadHeaderTimeout

func WithReadHeaderTimeout(d time.Duration) Option

WithReadHeaderTimeout sets the maximum duration for reading request headers. Setting this protects against slow-header attacks (e.g. Slowloris).

func WithReadTimeout

func WithReadTimeout(d time.Duration) Option

WithReadTimeout sets the HTTP read timeout.

func WithShutdownTimeout

func WithShutdownTimeout(d time.Duration) Option

WithShutdownTimeout sets how long Run waits for active connections to drain during a graceful shutdown before giving up.

func WithWriteTimeout

func WithWriteTimeout(d time.Duration) Option

WithWriteTimeout sets the HTTP write timeout.

type Server

Server wraps net/http.Server with lifecycle helpers.

type Server struct {
    // contains filtered or unexported fields
}

func New

func New(opts ...Option) (*Server, error)

New creates a Server with the given options. Returns an error if required options are missing or invalid.

func (*Server) Addr

func (s *Server) Addr() string

Addr returns the server's listen address.

func (*Server) Run

func (s *Server) Run(ctx context.Context) error

Run starts the server and blocks until ctx is cancelled, then performs a graceful shutdown bounded by the configured shutdown timeout (see WithShutdownTimeout). It returns nil on a clean shutdown, or the first error encountered from either Start or Shutdown.

func (*Server) Shutdown

func (s *Server) Shutdown(ctx context.Context) error

Shutdown gracefully drains active connections.

func (*Server) Start

func (s *Server) Start() error

Start begins serving HTTP requests. Blocks until the server stops.

Generated by gomarkdoc