Documentation
¶
Overview ¶
Package server provides transport-agnostic server lifecycle helpers used by go-service.
This package defines small primitives that higher-level transport packages (for example HTTP and gRPC) can use to run servers consistently and integrate with process shutdown logic.
Concepts ¶
The main abstractions are:
Server: a minimal interface describing a runnable server that can be gracefully shut down.
Service: a small lifecycle manager that starts a Server asynchronously, logs start/stop events, and triggers application shutdown with os.ExitCodeServeFailure when the underlying Server.Serve returns an error.
Typical usage ¶
Transport-specific packages construct a concrete implementation of Server (wrapping a net/http.Server or grpc.Server), then wrap it in a Service and call Service.Start during application startup. On shutdown, the application stops the underlying server by calling Service.Stop with a context.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrDraining = errors.New("server: draining")
ErrDraining is returned when server shutdown has started.
Functions ¶
func Register ¶ added in v2.306.0
func Register(params RegisterParams)
Register wires server services into the application lifecycle.
It appends an Fx lifecycle hook that:
- OnStart: starts each provided *Service by calling `Start()`.
- OnStop: marks the drain state, stops each provided *Service by calling `Stop(ctx)`, and returns the joined shutdown errors.
Callers should ensure the slice does not contain nil entries.
Types ¶
type Drain ¶ added in v2.589.0
type Drain struct {
// contains filtered or unexported fields
}
Drain tracks whether server shutdown has started.
func (*Drain) Done ¶ added in v2.591.0
func (d *Drain) Done() <-chan struct{}
Done returns a channel that is closed after Start has been called.
type RegisterParams ¶ added in v2.589.0
type RegisterParams struct {
di.In
// Lifecycle receives the server start and stop hooks.
Lifecycle di.Lifecycle
// Drain tracks whether shutdown has started.
Drain *Drain
// Services are the server services managed by the lifecycle.
Services []*Service
}
RegisterParams defines dependencies for registering server services.
type Server ¶
type Server interface {
fmt.Stringer
// Serve starts serving requests.
//
// Serve is expected to block until the server stops. It should return a non-nil error when serving
// terminates unexpectedly (for example due to a listener failure). Graceful shutdown should typically
// cause Serve to return nil or a well-understood sentinel error, depending on the underlying server.
Serve() error
// Shutdown stops the server gracefully.
//
// Shutdown should attempt to stop the server without abruptly dropping active requests, respecting ctx
// for deadlines/cancellation. It should return any error encountered during shutdown.
Shutdown(ctx context.Context) error
}
Server defines the minimal interface required by Service to manage a transport server.
Implementations are typically thin adapters over concrete servers such as github.com/alexfalkowski/go-service/v2/net/http.Server or `grpc.Server`. The embedded fmt.Stringer is expected to return a human-readable address or identifier (used for logging).
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service manages starting and stopping a Server with optional logging and Fx shutdown integration.
Service is a thin lifecycle adapter. It does not own listener construction or startup readiness checks; it only calls Server.Serve, Server.Shutdown, and [Server.String] at the appropriate lifecycle points.
Concurrency and lifecycle semantics:
- Service.Start launches Server.Serve in a new goroutine and returns immediately.
- Service.Start does not report Serve errors to its caller. A non-nil Serve error is logged and triggers di.Shutdowner with os.ExitCodeServeFailure.
- A nil Serve return is treated as normal termination and does not trigger shutdown.
- Service.Stop calls Server.Shutdown synchronously with the provided context.
- Service does not guard against repeated or concurrent Start/Stop calls; callers should coordinate lifecycle transitions.
func NewService ¶
NewService constructs a Service that manages the lifetime of server.
name is used for attribution in log attributes under meta.SystemKey and as the prefix when Service.Stop returns a shutdown error. logger may be nil; the resulting Service relies on the logger package's nil-safe methods and simply skips log emission in that case.
server is expected to be a non-nil concrete implementation such as an HTTP or gRPC server adapter. sh is expected to be non-nil and is used to trigger application shutdown when server.Serve returns a non-nil error.
NewService does not validate its arguments and does not start serving. Call Service.Start to launch server.Serve in the background.
func (*Service) Start ¶
func (s *Service) Start()
Start launches the underlying server asynchronously.
Start returns immediately after spawning a goroutine that logs the server address and then calls Server.Serve.
If Serve returns a non-nil error, Start requests application shutdown via the configured di.Shutdowner and logs the failure. Because Start is asynchronous, it never returns that Serve error directly.
Start performs no deduplication or synchronization. Calling it more than once for the same Service will start multiple goroutines and invoke Serve multiple times.
func (*Service) Stop ¶
Stop requests a graceful shutdown of the underlying server.
The provided context controls shutdown deadlines and cancellation for Server.Shutdown. Stop logs the shutdown attempt regardless of whether the Service was previously started.
If Shutdown returns an error, Stop logs the failure and returns the same error wrapped with errors.Prefix using the service name for attribution. A successful shutdown returns nil.
Stop does not trigger di.Shutdowner; that mechanism is reserved for unexpected Serve failures observed by Service.Start.
func (*Service) String ¶ added in v2.327.0
String returns [Server.String] unchanged.
This is typically the human-readable address or identifier used by the underlying server and matches the value logged under the "addr" attribute during Service.Start.
Source Files