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 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.
Start with `Server` and `Service`.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
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 `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 shutdown integration.
Concurrency/lifecycle expectations:
- Start launches the server in a new goroutine.
- Stop requests a graceful shutdown and should be called during application shutdown.
- If Server.Serve returns a non-nil error, Service triggers application shutdown via di.Shutdowner.
func NewService ¶
NewService constructs a Service that manages the lifetime of an underlying Server.
name is used for attribution in logs (meta.SystemKey). server is the concrete server implementation (e.g. HTTP or gRPC). logger may be nil to disable logging. sh is used to trigger application shutdown when the underlying Server terminates unexpectedly.
NewService does not start the server; call (*Service).Start to begin serving.
Source Files