httpserver

Documentation

Overview

Package httpserver adapts standard-library net/http servers to sup actors.

Getting started

Create an HTTP server actor and place it under a sup Supervisor:

server := httpserver.NewActor("http", func(context.Context) (*http.Server, error) {
	return &http.Server{
		Addr:    ":8080",
		Handler: handler,
	}, nil
})

supervisor := sup.NewSupervisor("root",
	sup.WithPolicy(sup.Transient),
	sup.WithActors(server),
)

The ServerFunc is called once for every execution attempt and must return a fresh *http.Server because a server cannot be reused after Shutdown. By default, the actor calls ListenAndServe. Use WithServe for TLS, custom listeners, or another serving mode. Use WithShutdownTimeout to bound the graceful shutdown period.

Context cancellation performs graceful shutdown with the configured timeout. http.ErrServerClosed is treated as a clean stop. Startup and unexpected serving errors are returned to the supervisor and handled by its restart policy.

A nil server produces ErrNilServer, and concurrent calls to Run produce ErrActorRunning. See the package README and the package reference at https://pkg.go.dev/github.com/webermarci/sup/httpserver for the complete API.

Index

• Variables
• type Actor
  • func NewActor(id string, server ServerFunc, options ...Option) *Actor
  • func (a *Actor) ID() string
  • func (a *Actor) Inspect() sup.Spec
  • func (a *Actor) Run(ctx context.Context) error
• type Option
  • func WithServe(serve ServeFunc) Option
  • func WithShutdownTimeout(timeout time.Duration) Option
• type ServeFunc
• type ServerFunc

Variables

var (
	// ErrActorRunning is returned when Run is called while the actor is already
	// serving a server.
	ErrActorRunning = errors.New("httpserver: actor is already running")

	// ErrNilServer is returned when a ServerFunc returns a nil server without an
	// error.
	ErrNilServer = errors.New("httpserver: server function returned nil")
)

Types

type Actor

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

Actor creates and serves a fresh net/http Server for each execution attempt. It is safe to call Run sequentially and rejects concurrent calls.

func NewActor

func NewActor(id string, server ServerFunc, options ...Option) *Actor

NewActor creates an HTTP server actor. The server function is called once for each execution attempt and must return a fresh *http.Server.

func (*Actor) ID

func (a *Actor) ID() string

ID returns the actor id.

func (*Actor) Inspect

func (a *Actor) Inspect() sup.Spec

Inspect returns the HTTP server actor spec.

func (*Actor) Run

func (a *Actor) Run(ctx context.Context) error

Run serves one HTTP server execution attempt. Context cancellation triggers graceful shutdown and is treated as a clean actor stop. http.ErrServerClosed is also treated as a clean stop.

type Option

type Option func(*Actor)

Option configures an HTTP server actor during construction.

func WithServe

func WithServe(serve ServeFunc) Option

WithServe configures how the HTTP server is started. By default the actor calls (*http.Server).ListenAndServe.

func WithShutdownTimeout

func WithShutdownTimeout(timeout time.Duration) Option

WithShutdownTimeout configures the maximum time allowed for graceful shutdown after the actor context is canceled.

type ServeFunc

type ServeFunc func(context.Context, *http.Server) error

ServeFunc runs one HTTP server execution attempt. The function should return when the server has been shut down. It is called once for every Run attempt. For custom listeners, create a fresh listener inside the function so that supervisor restarts can serve again.

type ServerFunc

type ServerFunc func(context.Context) (*http.Server, error)

ServerFunc creates a fresh HTTP server for one execution attempt.

A new server must be returned for every attempt because net/http servers cannot be reused after Shutdown has been called.