Graceful shutdown

Canonical guidance

• use signal.NotifyContext or equivalent once at process scope
• stop accepting new work, then drain in-flight work with a timeout
• cancel or stop background goroutines as part of the same shutdown flow

Use when

• HTTP or gRPC servers
• queue workers
• long-lived background services

Avoid

• ListenAndServe with no signal handling path
• unbounded Shutdown waits
• letting request-scoped or background work outlive the process owner accidentally

Preferred pattern

ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()

<-ctx.Done()

shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
_ = srv.Shutdown(shutdownCtx)

Anti-pattern

• catching SIGTERM but continuing to accept new work while “shutting down”

Explanation: This is tempting because the process is technically responding to signals, but it defeats the whole drain strategy.

Why

• graceful shutdown is lifecycle control: trigger, admission stop, drain, timeout, exit