service.go

// Package httpsvc exposes an HTTP server as a steward-managed service.

//

// Init builds the underlying *http.Server, Start binds the listener and

// runs Serve in a goroutine, Stop drains via Shutdown with a configurable

// timeout. A listener failure observed after Start is reported via the

// steward HealthChecker interface.

package httpsvc

import (

	"context"

	"errors"

	"log/slog"

	"net"

	"net/http"

	"sync"

	"sync/atomic"

	"time"

	"go.bigb.es/auxilia/culpa"

)

// defaultShutdownTimeout caps Service.Stop when ShutdownTimeout is zero.

const defaultShutdownTimeout = 30 * time.Second

// Service is a steward-managed HTTP server.

//

// Configure the public fields before adding the service to the steward

// Manager. Leave private fields zero. Init builds the underlying

// *http.Server; Start runs the listener in a goroutine; Stop drains via

// Shutdown with ShutdownTimeout.

type Service struct {

	// Addr is the listen address (e.g. ":8080" or "127.0.0.1:0"). Required.

	Addr string

	// Handler is the root http.Handler. Required.

	Handler http.Handler

	// ReadTimeout, WriteTimeout, and IdleTimeout map onto the matching

	// http.Server fields. Zero values fall through to net/http defaults.

	ReadTimeout  time.Duration

	WriteTimeout time.Duration

	IdleTimeout  time.Duration

	// ShutdownTimeout caps Stop's drain window. Zero means 30 seconds.

	ShutdownTimeout time.Duration

	// Logger is optional. When nil, slog.Default() is used.

	Logger *slog.Logger

	// BaseContext is optional; it is passed through to

	// http.Server.BaseContext. The default is the standard library default.

	BaseContext func(net.Listener) context.Context

	srv      *http.Server

	listener net.Listener

	serveErr atomic.Pointer[error]

	stopOnce sync.Once

	stopErr  error

	started  atomic.Bool

	doneCh   chan struct{}

}

// Init validates the configuration and constructs the underlying

// *http.Server. It is safe to inspect Addr and Handler after Init returns.

func (s *Service) Init(_ context.Context) error {

	if s.Addr == "" {

		return culpa.WithCode(culpa.New("httpsvc: Addr is required"), "HTTPSVC_INVALID_CONFIG")

	}

	if s.Handler == nil {

		return culpa.WithCode(culpa.New("httpsvc: Handler is required"), "HTTPSVC_INVALID_CONFIG")

	}

	s.srv = &http.Server{

		Addr:         s.Addr,

		Handler:      s.Handler,

		ReadTimeout:  s.ReadTimeout,

		WriteTimeout: s.WriteTimeout,

		IdleTimeout:  s.IdleTimeout,

		BaseContext:  s.BaseContext,

	}

	s.doneCh = make(chan struct{})

	return nil

}

// Start binds the listener (so bind errors surface synchronously) and

// runs Serve in a goroutine. Returns once the listener is bound.

func (s *Service) Start(_ context.Context) error {

	ln, err := net.Listen("tcp", s.Addr)

	if err != nil {

		return culpa.Wrap(err, "httpsvc: bind listener")

	}

	s.listener = ln

	s.started.Store(true)

	go s.serve()

	return nil

}

// serve runs the HTTP server until it stops, recording any non-graceful

// error for HealthCheck and logging it.

func (s *Service) serve() {

	defer close(s.doneCh)

	err := s.srv.Serve(s.listener)

	if err == nil || errors.Is(err, http.ErrServerClosed) {

		return

	}

	wrapped := culpa.Wrap(err, "http.Server.Serve")

	s.serveErr.Store(&wrapped)

	s.logger().Error("http server stopped unexpectedly", "err", wrapped)

}

// Stop drains in-flight requests via http.Server.Shutdown, capped by

// ShutdownTimeout (default 30s). Idempotent: a second call is a no-op.

func (s *Service) Stop(ctx context.Context) error {

	s.stopOnce.Do(func() {

		if s.srv == nil {

			return

		}

		timeout := s.ShutdownTimeout

		if timeout <= 0 {

			timeout = defaultShutdownTimeout

		}

		shutdownCtx, cancel := context.WithTimeout(ctx, timeout)

		defer cancel()

		if err := s.srv.Shutdown(shutdownCtx); err != nil {

			s.stopErr = culpa.Wrap(err, "httpsvc: shutdown")

			// Shutdown does not interrupt active connections on timeout;

			// force them closed so the serve goroutine exits and Stop

			// returns promptly. We intentionally drop Close's error: it

			// would only ever wrap "use of closed network connection"

			// from the listener Shutdown already closed.

			_ = s.srv.Close()

		}

		// Wait for the serve goroutine to exit so HealthCheck reflects

		// any final error and so the listener fd is released before we

		// return.

		if s.doneCh != nil {

			<-s.doneCh

		}

	})

	return s.stopErr

}

// HealthCheck returns nil while the listener is running, or the wrapped

// listener error after the goroutine exits unexpectedly.

func (s *Service) HealthCheck(_ context.Context) error {

	if errPtr := s.serveErr.Load(); errPtr != nil {

		return *errPtr

	}

	return nil

}

// Addr returns the actual listen address. Most useful when configured

// with a wildcard port like "127.0.0.1:0" — the OS-assigned port is only

// known after Start.

func (s *Service) ListenAddr() net.Addr {

	if s.listener == nil {

		return nil

	}

	return s.listener.Addr()

}

func (s *Service) logger() *slog.Logger {

	if s.Logger != nil {

		return s.Logger

	}

	return slog.Default()

}