Documentation
¶
Index ¶
- Constants
- Variables
- func GetStopCause(ctx context.Context) error
- func Serve(ctx context.Context, ctors ...any) error
- func SetupSignalWith(signals ...os.Signal) func(lc *Lifecycle) *SignalService
- type Actor
- type FuncActor
- func (f *FuncActor) GetName() string
- func (f *FuncActor) GetStage() int
- func (f *FuncActor) RequiresReadinessProbe() *ReadinessProbe
- func (f *FuncActor) RequiresStop() bool
- func (f *FuncActor) Start(ctx context.Context) (xerr error)
- func (f *FuncActor) Stop(ctx context.Context) error
- func (f *FuncActor) WithName(name string) *FuncActor
- func (f *FuncActor) WithReadiness() *FuncActor
- func (f *FuncActor) WithStage(stage int) *FuncActor
- type FuncService
- func (b *FuncService) Done() <-chan struct{}
- func (b *FuncService) Err() error
- func (b *FuncService) GetName() string
- func (b *FuncService) IsStarted() bool
- func (b *FuncService) Start(_ context.Context) error
- func (b *FuncService) Stop(ctx context.Context) error
- func (b *FuncService) WithName(name string) *FuncService
- func (b *FuncService) WithStop(stop func(ctx context.Context) error) *FuncService
- type Lifecycle
- func (lc *Lifecycle) Add(actor Actor)
- func (lc *Lifecycle) IsStarted() bool
- func (lc *Lifecycle) Provide(ctors ...any) error
- func (lc *Lifecycle) RequiresReadinessProbe() *ReadinessProbe
- func (lc *Lifecycle) Serve(ctx context.Context, ctors ...any) (xerr error)
- func (lc *Lifecycle) Start(ctx context.Context) (xerr error)
- func (lc *Lifecycle) WithLogger(logger *slog.Logger) *Lifecycle
- func (lc *Lifecycle) WithName(name string) *Lifecycle
- func (lc *Lifecycle) WithStop(stop func(ctx context.Context) error) *Lifecycle
- func (lc *Lifecycle) WithStopEachTimeout(timeout time.Duration) *Lifecycle
- func (lc *Lifecycle) WithStopTimeout(timeout time.Duration) *Lifecycle
- type Named
- type ReadinessProbe
- type RequiresReadinessProbe
- type RequiresStop
- type Service
- type SignalService
- type Staged
Constants ¶
const ( // StageDefault is the default stage for actors without explicit stage. StageDefault = 0 // StageReadiness is the default stage for actors with readiness probe enabled. // It's very high to ensure readiness-probe actors start last. StageReadiness = math.MaxInt - 1000 )
Variables ¶
var DefaultStopEachTimeout = 5 * time.Second
DefaultStopEachTimeout is the default timeout for stopping each individual actor.
var DefaultStopTimeout = 30 * time.Second
DefaultStopTimeout is the default timeout for stopping all actors during shutdown.
var ErrNoServices = errors.New("no long-running services to serve")
ErrNoServices is returned when no long-running services are registered.
var ErrServed = errors.New("lifecycle already served")
ErrServed is returned when Serve is called.
Functions ¶
func GetStopCause ¶
func Serve ¶
Serve is a convenience function that creates a new Lifecycle instance and calls Serve on it.
func SetupSignalWith ¶
func SetupSignalWith(signals ...os.Signal) func(lc *Lifecycle) *SignalService
SetupSignalWith returns a setup function that creates and registers a signal handling service that listens for the specified signals. If no signals are provided, it defaults to SIGINT and SIGTERM. The returned function can be used with dependency injection or called directly with a Lifecycle instance.
Types ¶
type Actor ¶
Actor defines the interface for simple actors that only need start/stop operations. Examples: configuration loaders, database migrations, one-time setup tasks.
type FuncActor ¶
type FuncActor struct {
// contains filtered or unexported fields
}
FuncActor wraps start and stop functions into an Actor implementation. This is useful for creating actors from simple functions without defining new types.
func NewFuncActor ¶
NewFuncActor creates a new FuncActor with the provided start and stop functions.
func (*FuncActor) RequiresReadinessProbe ¶ added in v1.2.0
func (f *FuncActor) RequiresReadinessProbe() *ReadinessProbe
RequiresReadinessProbe returns the readiness probe if enabled via WithReadiness.
func (*FuncActor) RequiresStop ¶ added in v1.0.2
acquired resources during construction and needs cleanup regardless of whether Start is called.
func (*FuncActor) Start ¶
Start calls the wrapped start function. If readiness probe is enabled via WithReadiness, it signals completion after start.
func (*FuncActor) WithName ¶
WithName sets the name of the actor. If a readiness probe is enabled, its name is also updated.
func (*FuncActor) WithReadiness ¶ added in v1.2.0
WithReadiness enables a readiness probe for this actor. Note: When enabled, this actor is assigned a very high stage value (for example, close to math.MaxInt) so that it starts after most other actors. This is typically desirable because readiness/health endpoints depend on the rest of the system being up, not the other way around. If another actor must start after this one, give that actor a higher stage (but still lower than the readiness-probe stage) by using WithStage to override its default behavior. Returns the actor for method chaining.
type FuncService ¶
type FuncService struct {
// contains filtered or unexported fields
}
FuncService runs a function in a background goroutine and implements Service interface. Useful for long-running background tasks that need to be monitored.
func NewFuncService ¶
func NewFuncService(taskFunc func(ctx context.Context) error) *FuncService
NewFuncService creates a new FuncService with the provided task function.
func (*FuncService) Done ¶
func (b *FuncService) Done() <-chan struct{}
Done returns a channel that is closed when the background task completes.
func (*FuncService) Err ¶
func (b *FuncService) Err() error
Err returns any error that occurred during background task execution.
func (*FuncService) GetName ¶
func (b *FuncService) GetName() string
GetName returns the name of the service.
func (*FuncService) IsStarted ¶
func (b *FuncService) IsStarted() bool
IsStarted returns whether the service has been started
func (*FuncService) Start ¶
func (b *FuncService) Start(_ context.Context) error
Start launches the background task in a separate goroutine.
func (*FuncService) Stop ¶
func (b *FuncService) Stop(ctx context.Context) error
Stop cancels the background task and waits for completion.
func (*FuncService) WithName ¶
func (b *FuncService) WithName(name string) *FuncService
WithName sets the name of the service.
func (*FuncService) WithStop ¶
func (b *FuncService) WithStop(stop func(ctx context.Context) error) *FuncService
WithStop sets the stop function for the service.
type Lifecycle ¶
type Lifecycle struct {
*inject.Injector // Embedded injector for dependency management
*FuncService
// contains filtered or unexported fields
}
Lifecycle manages the lifecycle of multiple actor instances. It provides coordinated startup, monitoring, and cleanup of both simple actors and long-running services.
func New ¶
func New() *Lifecycle
New creates a new Lifecycle instance with embedded injector and default stop timeout.
func Provide ¶ added in v1.1.2
Provide is a convenience function that creates a new Lifecycle instance and calls Provide on it.
func Start ¶
Start is a convenience function that creates a new Lifecycle instance, provides the constructors, and calls Start on it.
func (*Lifecycle) Add ¶
Add registers an actor to the lifecycle manager. Actors are started in the order they are added and stopped in reverse order.
func (*Lifecycle) Provide ¶
Provide registers constructors and tracks all non-error return types for auto-resolution. This overrides the embedded Injector's Provide method to enable auto-resolution of types.
func (*Lifecycle) RequiresReadinessProbe ¶ added in v1.1.2
func (lc *Lifecycle) RequiresReadinessProbe() *ReadinessProbe
RequiresReadinessProbe returns the readiness probe for this lifecycle. The probe is signaled when Start completes successfully. This allows parent lifecycles to wait for nested lifecycles to be ready.
func (*Lifecycle) Serve ¶
Serve provides a complete lifecycle management solution. It automatically resolves all provided types, starts all actors, monitors long-running services, and ensures proper cleanup.
Process: 1. Automatically resolves all provided types with context support 2. Checks if there are long-running services to monitor 3. Starts all registered actors via internal start logic 4. Sets up automatic cleanup via defer for each started actor 5. Monitors long-running services 6. Returns when any service completes or context is cancelled
The cleanup is guaranteed to run even if any step fails, using defer to ensure each started actor is properly stopped. The ctx parameter controls the long-running monitoring process and can be used to cancel the entire operation.
func (*Lifecycle) WithLogger ¶
WithLogger sets the logger for the lifecycle and returns the Lifecycle instance. This allows for method chaining during initialization.
func (*Lifecycle) WithName ¶
WithName sets the name for the lifecycle. Also updates the readiness probe name.
func (*Lifecycle) WithStopEachTimeout ¶
WithStopEachTimeout sets the timeout duration for stopping each individual actor.
type Named ¶
type Named interface {
GetName() string
}
Named defines an optional interface for actors that can provide a human-readable name. This is useful for logging and debugging purposes.
type ReadinessProbe ¶ added in v1.1.2
type ReadinessProbe struct {
// contains filtered or unexported fields
}
ReadinessProbe is a simple readiness probe that can be used to signal when the application is ready to serve traffic.
func NewReadinessProbe ¶ added in v1.1.2
func NewReadinessProbe() *ReadinessProbe
NewReadinessProbe creates a new readiness probe.
func (*ReadinessProbe) Done ¶ added in v1.1.2
func (rp *ReadinessProbe) Done() <-chan struct{}
Done returns a channel that is closed when the readiness probe is signaled.
func (*ReadinessProbe) Error ¶ added in v1.1.2
func (rp *ReadinessProbe) Error() error
Error returns the error that caused the readiness probe to fail, or nil if successful.
func (*ReadinessProbe) GetName ¶ added in v1.2.2
func (rp *ReadinessProbe) GetName() string
GetName returns the name of the readiness probe.
func (*ReadinessProbe) Signal ¶ added in v1.1.2
func (rp *ReadinessProbe) Signal(err error)
Signal signals the completion of readiness check. Pass nil error to indicate success, or non-nil error to indicate failure.
func (*ReadinessProbe) WithName ¶ added in v1.2.2
func (rp *ReadinessProbe) WithName(name string) *ReadinessProbe
WithName sets the name of the readiness probe for logging and debugging.
type RequiresReadinessProbe ¶ added in v1.1.2
type RequiresReadinessProbe interface {
RequiresReadinessProbe() *ReadinessProbe
}
RequiresReadinessProbe is an interface for types that provide a readiness probe. Actors implementing this interface will have their probes collected and waited on during lifecycle startup.
type RequiresStop ¶ added in v1.0.2
type RequiresStop interface {
RequiresStop() bool
}
RequiresStop defines an interface for actors that need cleanup even if their Start method is not called. This is useful for actors that acquire resources during construction and need cleanup regardless of whether Start is called.
type Service ¶
type Service interface {
Actor
Done() <-chan struct{} // Signals when the service has completed or failed
Err() error // Returns any error that caused the service to stop
}
Service defines the interface for long-running services that can signal completion. Examples: HTTP servers, gRPC servers, message queue consumers, background workers.
type SignalService ¶
type SignalService struct {
*FuncService
}
SignalService is a specialized service for handling OS signals. This provides a distinct type for dependency injection while reusing FuncService functionality.
func NewSignalService ¶
func NewSignalService(signals ...os.Signal) *SignalService
NewSignalService creates a new SignalService that listens for SIGINT and SIGTERM.
func SetupSignal ¶
func SetupSignal(lc *Lifecycle) *SignalService
SetupSignal creates and registers a signal handling service that listens for SIGINT and SIGTERM. Returns a SignalService that will complete when a signal is received.
func (*SignalService) WithName ¶
func (s *SignalService) WithName(name string) *SignalService
WithName sets the name for the signal service.
func (*SignalService) WithStop ¶
func (s *SignalService) WithStop(stop func(ctx context.Context) error) *SignalService
WithStop is not supported for SignalService.
Source Files