grace

README

grace

grace runs one net/http server and shuts it down cleanly when its context is cancelled.

ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()

logger := slog.Default().With("server", "public")
err := grace.Run(ctx, ":8080", handler, logger,
    grace.WithReadHeaderTimeout(10*time.Second),
    grace.WithShutdownTimeout(15*time.Second),
)

It supplies conservative defaults for header read, write, idle, and shutdown timeouts. Use the focused With... options to override them. Pass nil as the logger to disable lifecycle logging.

Documentation

Overview

Package grace runs HTTP servers with graceful shutdown support.

Index

• func Run(ctx context.Context, listenAddr string, handler http.Handler, ...) error
• func RunServer(ctx context.Context, server *http.Server, logger *slog.Logger) error
• func SignalContext(parent context.Context, signals ...os.Signal) (context.Context, context.CancelFunc)
• type Option
  • func WithIdleTimeout(timeout time.Duration) Option
  • func WithMaxHeaderValueCount(count int) Option
  • func WithOptions(opts Options) Option
  • func WithReadHeaderTimeout(timeout time.Duration) Option
  • func WithShutdownTimeout(timeout time.Duration) Option
  • func WithWriteTimeout(timeout time.Duration) Option
• type Options

Functions

func Run

func Run(
	ctx context.Context,
	listenAddr string,
	handler http.Handler,
	logger *slog.Logger,
	opts ...Option,
) error

Run creates and runs an HTTP server until ctx is canceled or startup fails.

Parameters:

• ctx controls the server lifetime; cancellation triggers graceful shutdown.
• listenAddr is passed to http.Server.Addr, for example ":8080".
• handler is assigned to http.Server.Handler.
• logger is used for lifecycle logs; if nil, lifecycle logging is disabled.
• opts override individual defaults or replace them through WithOptions.

Run returns an error when startup fails (for example, address already in use) or when graceful shutdown fails.

func RunServer

func RunServer(ctx context.Context, server *http.Server, logger *slog.Logger) error

RunServer starts server with ListenAndServe and manages graceful shutdown.

Parameters:

• ctx controls the server lifetime; cancellation triggers graceful shutdown.
• server is the fully configured http.Server instance to run.
• logger is used for lifecycle logs; if nil, lifecycle logging is disabled.

RunServer uses the default shutdown timeout. It returns an error when startup fails or when graceful shutdown fails.

func SignalContext

func SignalContext(parent context.Context, signals ...os.Signal) (context.Context, context.CancelFunc)

SignalContext returns a copy of parent that is canceled when one of the configured signals is received. The cancellation cause records the signal name, allowing Run and RunServer to include it in shutdown logs.

If no signals are provided, SignalContext listens for the platform defaults. On Unix platforms those are os.Interrupt and syscall.SIGTERM.

The returned stop function unregisters signal delivery and cancels the context. Callers should defer stop after creating the context.

Types

type Option

type Option func(*Options)

Option mutates Options used by Run.

func WithIdleTimeout

func WithIdleTimeout(timeout time.Duration) Option

WithIdleTimeout overrides the default idle connection timeout.

func WithMaxHeaderValueCount

func WithMaxHeaderValueCount(count int) Option

WithMaxHeaderValueCount overrides the maximum number of request header values.

func WithOptions

func WithOptions(opts Options) Option

WithOptions replaces all server options used by Run.

Prefer the focused With... options when overriding only individual settings.

func WithReadHeaderTimeout

func WithReadHeaderTimeout(timeout time.Duration) Option

WithReadHeaderTimeout overrides the default request-header read timeout.

func WithShutdownTimeout

func WithShutdownTimeout(timeout time.Duration) Option

WithShutdownTimeout overrides the default graceful shutdown timeout.

func WithWriteTimeout

func WithWriteTimeout(timeout time.Duration) Option

WithWriteTimeout overrides the default response write timeout.

type Options

type Options struct {
	// ReadHeaderTimeout limits how long to read request headers.
	ReadHeaderTimeout time.Duration
	// WriteTimeout limits the time spent writing the response.
	WriteTimeout time.Duration
	// IdleTimeout sets how long to keep idle connections open.
	IdleTimeout time.Duration
	// MaxHeaderValueCount limits the number of request header values accepted.
	MaxHeaderValueCount int
	// ShutdownTimeout bounds how long to wait for graceful shutdown.
	ShutdownTimeout time.Duration
}

Options configures the HTTP server settings applied by Run.