app is a small lifecycle and composition kernel for Go services. It runs a set
of explicitly registered components with a controlled lifecycle: ordered start,
a signal-aware wait, and graceful shutdown in reverse order with a bounded
timeout.
It is deliberately not a framework: no hidden global state, no
dependency-injection container, no routing, no configuration parsing. Wiring
stays explicit and visible in your main. Zero dependencies, standard library
only.
go get github.com/goloop/appfunc main() {
if err := run(); err != nil {
log.Fatal(err)
}
}
func run() error {
mux := http.NewServeMux()
// ... register handlers ...
a := app.New("api",
app.WithLogger(slog.Default()),
app.WithShutdownTimeout(10*time.Second),
)
a.Use(app.HTTPServer("http", &http.Server{Addr: ":8080", Handler: mux}))
a.OnStop(func(context.Context) error {
pool.Close()
return nil
})
return a.Run(context.Background())
}Run starts the components in registration order, waits for SIGINT/SIGTERM
(or parent cancellation, or a fatal component error), then stops the components
in reverse order and runs the stop hooks. It returns nil on a clean,
signal-triggered shutdown. A second signal during shutdown forces an immediate
exit.
A component has a name, a non-blocking Start and a Stop:
type Component interface {
Name() string
Start(ctx context.Context) error
Stop(ctx context.Context) error
}Start launches the work (typically a goroutine) and returns once startup has
succeeded, or an error if it failed synchronously. A background failure is
reported with app.Fatal(ctx, err), which triggers a graceful shutdown.
Ready-made components:
| Constructor | Start | Stop |
|---|---|---|
HTTPServer(name, *http.Server) |
bind + Serve in a goroutine |
srv.Shutdown |
Worker(name, func(ctx) error) |
run the blocking function | wait for it to return |
Closer(name, func() error) |
no-op | call the cleanup function |
The App serves no HTTP and knows nothing about "health". It exposes Status(),
a read-only snapshot of component lifecycle state, as plain data:
st := a.Status()
if !st.Healthy() { /* a component failed */ }An external health registry (for example goloop/observe) turns that snapshot
into a check and mounts its own handlers, so app stays decoupled.
MIT - see LICENSE.
Publish the existing lifecycle API as version 1.0.0. The v1 release keeps the existing import path and public API. Future incompatible changes require a new major version.