httpserver

Documentation

Overview

Package httpserver runs an HTTP server with a drain-aware shutdown sequence.

Index

• type Options
• type Server
  • func New(o Options) *Server
  • func (s *Server) Addr() string
  • func (s *Server) Run(ctx context.Context) error

Types

type Options

type Options struct {
	Addr              string
	Handler           http.Handler
	ReadHeaderTimeout time.Duration
	WriteTimeout      time.Duration
	Logger            *slog.Logger
}

type Server

type Server struct {

	// OnDrain runs first, before the drain delay. It flips readiness to 503 so
	// a load balancer stops sending new requests while this instance is still
	// able to finish the ones it has.
	OnDrain func()

	// DrainDelay is how long to keep serving after readiness starts failing.
	// It must cover the load balancer's health-check interval, or connections
	// will still be arriving when the listener closes.
	DrainDelay time.Duration

	// ShutdownTimeout bounds waiting for in-flight requests.
	ShutdownTimeout time.Duration

	// OnShutdown runs after the listener is closed and in-flight requests have
	// finished. This is where the click-event buffer gets its final flush.
	OnShutdown func(context.Context) error
	// contains filtered or unexported fields
}

Server wraps http.Server with the shutdown ordering the service needs.

func New

func New(o Options) *Server

func (*Server) Addr

func (s *Server) Addr() string

Addr reports the address the server is configured to listen on.

func (*Server) Run

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

Run serves until ctx is cancelled, then shuts down in order.

The ordering is what makes a rolling restart lossless:

1. readiness fails, so the load balancer deregisters this instance
2. wait DrainDelay, so in-flight and just-dispatched requests are absorbed
3. close the listener and wait for in-flight requests to finish
4. run OnShutdown, which flushes buffered analytics

Skipping step 2 is the common mistake: the listener closes while the load balancer still believes the instance is healthy, and clients see connection resets during every deploy.