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.Transient).AddActors(server)

The server factory 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 SetServeFunc for TLS, custom listeners, or another serving mode. Use SetShutdownTimeout to bound the graceful shutdown period. Configure these methods before the first Run call.

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.

See the package README and the package reference at https://pkg.go.dev/github.com/webermarci/sup/httpserver for the complete API.

Index

• type Actor
  • func NewActor(id string, server func(context.Context) (*http.Server, error)) *Actor
  • func (a *Actor) ID() string
  • func (a *Actor) Run(ctx context.Context) error
  • func (a *Actor) SetServeFunc(serve func(context.Context, *http.Server) error) *Actor
  • func (a *Actor) SetShutdownTimeout(timeout time.Duration) *Actor

Examples

• Actor

Types

type Actor

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

Actor creates and serves a fresh net/http Server for each execution attempt.

Example

package main

import (
	"context"
	"fmt"
	"io"
	"net"
	"net/http"
	"time"

	"github.com/webermarci/sup"
	"github.com/webermarci/sup/httpserver"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	addresses := make(chan string, 1)

	server := httpserver.NewActor("api", func(context.Context) (*http.Server, error) {
		mux := http.NewServeMux()
		mux.HandleFunc("GET /health", func(w http.ResponseWriter, _ *http.Request) {
			_, _ = io.WriteString(w, "ok")
		})
		return &http.Server{Handler: mux}, nil
	}).SetServeFunc(func(_ context.Context, server *http.Server) error {
		listener, err := net.Listen("tcp", "127.0.0.1:0")
		if err != nil {
			return err
		}
		addresses <- listener.Addr().String()
		return server.Serve(listener)
	})

	supervisor := sup.NewSupervisor("root", sup.Temporary).
		AddActors(server)
	done := make(chan error, 1)
	go func() { done <- supervisor.Run(ctx) }()

	client := &http.Client{Transport: &http.Transport{Proxy: nil}}
	response, err := client.Get("http://" + <-addresses + "/health")
	if err != nil {
		panic(err)
	}
	body, err := io.ReadAll(response.Body)
	if err != nil {
		panic(err)
	}
	_ = response.Body.Close()
	fmt.Println(response.StatusCode, string(body))

	cancel()
	if err := <-done; err != nil {
		panic(err)
	}

}

Output:
200 ok

func NewActor

func NewActor(
	id string,
	server func(context.Context) (*http.Server, error),
) *Actor

NewActor creates an HTTP server actor. The server function is called once for each execution attempt and must return a fresh *http.Server. Optional configuration is added with methods before the actor is run.

func (*Actor) ID

func (a *Actor) ID() string

ID returns the actor id.

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.

func (*Actor) SetServeFunc

func (a *Actor) SetServeFunc(
	serve func(context.Context, *http.Server) error,
) *Actor

SetServeFunc configures how the HTTP server is started and returns the actor for chaining. By default the actor calls (*http.Server).ListenAndServe. The function must return when the server is shut down. Custom listeners must be recreated for every execution attempt.

func (*Actor) SetShutdownTimeout

func (a *Actor) SetShutdownTimeout(timeout time.Duration) *Actor

SetShutdownTimeout configures the maximum time allowed for graceful shutdown after the actor context is canceled and returns the actor for chaining. When graceful shutdown exceeds the timeout, the actor forcibly closes the server.