README
¶
🚀 Squad
A shared shutdown primitive for graceful application lifecycle management in Go
Squad helps you orchestrate goroutines, manage graceful shutdowns, and handle application lifecycle events with minimal boilerplate.
Features • Installation • Quick Start • Documentation • Examples
📋 Table of Contents
- About
- Features
- Installation
- Quick Start
- Usage
- API Reference
- Examples
- Project Structure
- Development
- Testing
- FAQ
- Contributing
- License
- Author
🎯 About
Squad is a lightweight Go package that provides a shared shutdown primitive for managing application lifecycle. It allows you to:
- Coordinate multiple goroutines that must start and stop together
- Handle graceful shutdowns with configurable timeouts and grace periods
- Manage HTTP servers with proper shutdown sequences
- Run consumer workers (e.g., message queues, event streams) with graceful stop
- Execute bootstrap and cleanup functions for subsystems
- Automatically handle OS signals (SIGINT, SIGTERM, SIGHUP, SIGQUIT)
Squad is particularly useful for:
- Microservices and API servers
- Background workers and job processors
- Event-driven applications with multiple consumers
- Any Go application requiring coordinated startup/shutdown
The package is designed to be Kubernetes-aware, with default grace periods aligned with Pod termination lifecycle.
✨ Features
- ⚡ Zero dependencies - Uses only standard library and
github.com/moeryomenko/synx - 🔄 Coordinated lifecycle - If one goroutine exits, others are signaled to stop
- 🛡️ Graceful shutdowns - Configurable grace periods and shutdown timeouts
- 🌐 HTTP server support - Built-in wrapper for
http.Serverwith proper shutdown - 📨 Consumer pattern - Graceful stop for message/event consumers without interrupting active handlers
- 🎯 Signal handling - Automatic SIGINT/SIGTERM/SIGHUP/SIGQUIT handling
- 🔌 Bootstrap/cleanup hooks - Run initialization and cleanup functions
- ⏱️ Kubernetes-friendly - Default 30s grace period matches k8s pod termination
- 🧪 Well tested - Comprehensive test coverage
- 📦 Simple API - Minimal boilerplate, intuitive usage
📦 Installation
go get github.com/moeryomenko/squad
Requirements:
- Go 1.25 or higher
🚀 Quick Start
package main
import (
"context"
"log"
"github.com/moeryomenko/squad"
)
func main() {
// Create a new squad with signal handler
s, err := squad.New(squad.WithSignalHandler())
if err != nil {
log.Fatal(err)
}
// Run your application logic
s.Run(func(ctx context.Context) error {
// Your code here
<-ctx.Done()
return nil
})
// Wait for shutdown
if err := s.Wait(); err != nil {
log.Printf("shutdown error: %v", err)
}
}
📖 Usage
Basic Service
Create a simple service with signal handling:
s, err := squad.New(squad.WithSignalHandler())
if err != nil {
log.Fatal(err)
}
s.Run(func(ctx context.Context) error {
// Your background work
ticker := time.NewTicker(time.Second)
defer ticker.Stop()
for {
select {
case <-ctx.Done():
return nil
case <-ticker.C:
log.Println("tick")
}
}
})
s.Wait()
HTTP Server
Launch an HTTP server with graceful shutdown:
s, err := squad.New(squad.WithSignalHandler())
if err != nil {
log.Fatal(err)
}
http.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
w.WriteHeader(http.StatusOK)
})
s.RunServer(&http.Server{Addr: ":8080"})
s.Wait()
Consumer Workers
Run consumer workers that stop gracefully without interrupting active handlers:
s, err := squad.New(squad.WithSignalHandler())
if err != nil {
log.Fatal(err)
}
s.RunConsumer(func(consumeCtx, handleCtx context.Context) error {
// consumeCtx: cancelled when shutdown starts
// handleCtx: never cancelled, allows active handlers to complete
for {
select {
case <-consumeCtx.Done():
return nil
default:
msg := receiveMessage() // Your message source
go processMessage(handleCtx, msg)
}
}
})
s.Wait()
Graceful Shutdown
Run tasks with cleanup functions:
s, err := squad.New(squad.WithSignalHandler(
squad.WithGracefulPeriod(30 * time.Second),
squad.WithShutdownTimeout(5 * time.Second),
))
if err != nil {
log.Fatal(err)
}
s.RunGracefully(
// Background function
func(ctx context.Context) error {
// Your work
<-ctx.Done()
return nil
},
// Cleanup function (runs on shutdown)
func(ctx context.Context) error {
log.Println("cleaning up...")
return closeResources(ctx)
},
)
s.Wait()
Bootstrap & Cleanup
Initialize and cleanup subsystems:
s, err := squad.New(
squad.WithSignalHandler(),
squad.WithBootstrap(
func(ctx context.Context) error {
return initDatabase(ctx)
},
func(ctx context.Context) error {
return connectToCache(ctx)
},
),
squad.WithCloses(
func(ctx context.Context) error {
return closeDatabase(ctx)
},
),
squad.WithSubsystem(
func(ctx context.Context) error { return openMessageQueue(ctx) },
func(ctx context.Context) error { return closeMessageQueue(ctx) },
),
)
if err != nil {
log.Fatal("initialization failed:", err)
}
// Your application code...
s.Wait()
🔍 API Reference
Core Types
Squad- Main struct for coordinating goroutinesConsumerLoop- Function signature for consumer workers
Constructor
New(opts ...Option) (*Squad, error)- Create a new Squad instance
Options
WithSignalHandler(...ShutdownOpt)- Add OS signal handlingWithGracefulPeriod(duration)- Set graceful shutdown period (default: 30s)WithShutdownTimeout(duration)- Set shutdown timeout (default: 2s)WithShutdownInGracePeriod(duration)- Set both graceful and shutdown timeoutWithBootstrap(...func)- Add initialization functionsWithCloses(...func)- Add cleanup functionsWithSubsystem(init, close)- Add init+cleanup pair for a subsystem
Methods
Run(fn)- Run a function in the squadRunGracefully(backgroundFn, onDown)- Run with cleanup functionRunServer(*http.Server)- Run HTTP server with graceful shutdownRunConsumer(ConsumerLoop)- Run consumer workerWait() error- Block until all squad members exit
💡 Examples
See the example/ directory for complete examples:
- simple.go - HTTP server with signal handling and graceful shutdown
Run the example:
go run example/simple.go
📁 Project Structure
squad/
├── squad.go # Core Squad implementation
├── consumers.go # Consumer worker helpers
├── options.go # Configuration options
├── squad_test.go # Unit tests
├── example/ # Example applications
│ └── simple.go
├── tools/ # Development tools
├── go.mod # Go module definition
├── Makefile # Build automation
├── LICENSE-APACHE # Apache 2.0 license
├── LICENSE-MIT # MIT license
└── README.md # This file
🛠 Development
Prerequisites
- Go 1.25+
- golangci-lint (for linting)
- go-mod-upgrade (for dependency management)
Commands
# Run tests
make test
# Run tests with race detector
RACE_DETECTOR=1 make test
# View coverage report
make cover
# Run linter
make lint
# Update dependencies
make mod
# View all commands
make help
🧪 Testing
Squad includes comprehensive unit tests covering:
- Basic lifecycle management
- Bootstrap initialization
- Background task failures
- Shutdown failures and timeouts
- Error propagation
- Concurrent operations
Run tests:
go test ./...
# With race detector
go test -race ./...
# With coverage
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out
❓ FAQ
Q: What happens if a goroutine panics?
Squad uses synx.CtxGroup which recovers from panics and converts them to errors. The error will be returned from Wait().
Q: What's the difference between graceful period and shutdown timeout?
- Graceful period: Total time allowed for the entire shutdown process
- Shutdown timeout: Time reserved for executing cleanup functions
The signal handler waits gracefulPeriod - shutdownTimeout before canceling the squad context.
Q: Can I use Squad without signal handling?
Yes! Simply don't use WithSignalHandler(). You'll need to manage context cancellation yourself.
Q: How does RunConsumer differ from Run?
RunConsumer provides two contexts:
consumeContext: Cancelled on shutdown (stop accepting new work)handleContext: Never cancelled (allow in-flight work to complete)
This enables graceful consumer shutdown without interrupting active message handlers.
Q: Is Squad safe for concurrent use?
Yes, Squad is designed to be used concurrently. Internal state is protected by mutexes.
Q: What's the default grace period?
30 seconds, matching Kubernetes pod termination grace period. This ensures compatibility with k8s deployments.
🤝 Contributing
Contributions are welcome! Please feel free to submit issues, fork the repository, and send pull requests.
Guidelines
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Add tests for new functionality
- Run tests and linter (
make test lint) - Commit your changes
- Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
📄 License
This project is dual-licensed under your choice of:
- MIT License - See LICENSE-MIT
- Apache License 2.0 - See LICENSE-APACHE
You may use this project under the terms of either license.
👤 Author
Maxim Eryomenko
- GitHub: @moeryomenko
- Email: moeryomenko@gmail.com
If you find Squad useful, please consider giving it a ⭐️!
Made with ❤️ by Maxim Eryomenko
Documentation
¶
Overview ¶
helpers for run consumer workers.
Package squad contains a shared shutdown primitive.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ConsumerLoop ¶ added in v1.11.0
ConsumerLoop is interface for run graceful consumer, which take context different context for consumer events/messages and handle them.
type Option ¶ added in v1.3.0
type Option func(*Squad)
Option is an option that can be applied to Squad.
func WithBootstrap ¶ added in v1.3.0
WithBootstrap is a Squad option that adds bootstrap functions, which will be executed before squad started.
func WithCloses ¶ added in v1.3.0
WithCloses is a Squad options that adds cleanup functions, which will be executed after squad stopped.
func WithSignalHandler ¶
func WithSignalHandler(opts ...ShutdownOpt) Option
WithSignalHandler is a Squad option that adds signal handling goroutine to the squad. This goroutine will exit on SIGINT or SIGHUP or SIGTERM or SIGQUIT with graceful timeout and reserves time for the release of resources.
type ShutdownOpt ¶ added in v1.9.0
type ShutdownOpt func(*shutdown)
ShutdownOpt is an options that can be applied to signal handler.
func WithGracefulPeriod ¶ added in v1.9.0
func WithGracefulPeriod(period time.Duration) ShutdownOpt
WithGracefulPeriod sets graceful shutdown period to signal handler.
func WithShutdownInGracePeriod ¶ added in v1.15.0
func WithShutdownInGracePeriod(timeout time.Duration) ShutdownOpt
WithShutdownInGracePeriod sets timeout for shutdown process which will be run immediately in grace period.
func WithShutdownTimeout ¶ added in v1.9.0
func WithShutdownTimeout(timeout time.Duration) ShutdownOpt
WithShutdownTimeout sets timeout for reserves time for the release of resource.
type Squad ¶
type Squad struct {
// contains filtered or unexported fields
}
Squad is a collection of goroutines that go up and running altogether. If one goroutine exits, other goroutines also go down.
func (*Squad) RunConsumer ¶ added in v1.11.0
func (s *Squad) RunConsumer(consumer ConsumerLoop)
RunConsumer is wrapper function for run consumer worker after receiving shutdowning signal stop context for consumer events/messages without interrupting any active handler.
func (*Squad) RunGracefully ¶ added in v1.2.0
RunGracefully runs the backgroundFn. When fn is done, it signals all group members to stop. When stop signal has been received, squad run onDown function.
Source Files
Directories