Daemons and signals: no fork dance, the SIGTERM contract, signal.NotifyContext as the one shutdown path

You are not the daemon — the supervisor is

Ten minutes from now you will understand why an incomplete signal handler is worse than no handler at all — and exactly how to wire the one that never corrupts state on deploy.

The classic Unix daemonization ritual — fork, setsid to escape the controlling terminal, fork again, chdir to /, close every descriptor, write a pidfile — solved a 1980s problem: surviving the logout of the admin who launched you from a shell. Go programs should never perform it, for two reasons. The practical one: a multithreaded runtime cannot safely fork without exec — after fork in a threaded process, only async-signal-safe operations are legal in the child, and the Go runtime is anything but. The architectural one: there is nothing left to gain. systemd with Type=simple, or a container runtime, is the daemonizer — it detaches you from any terminal, owns your process group, captures your output, restarts you on failure, and tracks your PID in its own bookkeeping. Pidfiles are legacy for the same reason: they exist so an init script could find a self-forked process; a supervisor that started you already knows exactly who you are. Your binary just runs in the foreground and logs to stderr — journald or the container log collector stamps, indexes, and rotates it.

The signal contract

Signals are the supervisor’s vocabulary, and each one is a promise you must keep. When you see a deployment corruption or a boot-loop in a postmortem, nine times out of ten one of these promises was broken:

• SIGTERM — graceful stop. The contract has three clauses: stop accepting new work, drain what is in flight, exit 0 — and do all of it before the supervisor’s patience runs out: TimeoutStopSec in systemd (default 90 s), terminationGracePeriodSeconds in Kubernetes (default 30 s). Past the deadline comes SIGKILL, which no process can catch, block, or delay.
• SIGINT — the same stop, interactively. Ctrl-C delivers it to the foreground process group; handle it identically to SIGTERM so local runs behave like production.
• SIGHUP — reload configuration. Historically “terminal hang-up”, and its default action still terminates the process — which is why an unhandled SIGHUP kills programs when a terminal closes. Under a supervisor there is no controlling terminal, so the signal is free real estate: the convention is re-read config and apply it atomically.
• SIGKILL and SIGSTOP — not yours. Uncatchable by design; the existence of SIGKILL is why the SIGTERM contract has a deadline.

Together these four signals define the full lifecycle vocabulary — miss any one and either you cannot be stopped politely or you cannot reload without an outage. And the mechanism that powered the Hook: signal.Notify does not observe a signal, it claims it — the runtime disables the default disposition for every signal you register. A registered-but-ignored SIGTERM produces a process that cannot be stopped politely at all.

signal.NotifyContext: shutdown is just cancellation

Your whole service already speaks one cancellation language — context. signal.NotifyContext translates signals into it, which collapses “shutdown logic” into the propagation you built in the HTTP and lifecycle lessons:

func main() { os.Exit(run()) }

func run() int {
	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGTERM, syscall.SIGINT)
	defer stop()

	srv := newServer()
	go srv.ListenAndServe()          // serves until Shutdown is called

	<-ctx.Done()                     // first SIGTERM/SIGINT lands here
	stop()                           // restore default disposition: second signal kills NOW

	drainCtx, cancel := context.WithTimeout(context.Background(), 25*time.Second)
	defer cancel()
	if err := srv.Shutdown(drainCtx); err != nil {
		return 1                     // drain budget blown — exit dirty, loudly
	}
	return 0
}

Two mechanics deserve a close read. First, the drain budget: the WithTimeout value must fit inside the supervisor’s deadline with margin — 25 s under a 30 s Kubernetes grace period, leaving room for the SIGTERM to even arrive after endpoint deregistration. A drain budget larger than the grace period is a polite fiction ending in SIGKILL. Second, the double-signal discipline: calling stop() immediately after the first signal unregisters your handler, so the next SIGTERM or ctrl-C hits the restored default disposition — instant death. That is a feature, not a bug: it is the operator’s escape hatch when your drain hangs, and every well-behaved daemon ships it. One signal: graceful. Two signals: now.

SIGHUP reload: re-read, validate, swap

Reload is a separate channel from shutdown, and its contract is transactional: build the entire new config, validate it, and only then publish — with atomic.Pointer[Config], the same swap pattern from the configuration lesson. Readers Load() the pointer per request and never see a half-applied state. The failure mode this kills: mutating the live config struct field-by-field while requests read it — a data race wearing a feature’s clothes. And when the new file fails validation, the answer is to keep serving the old config and log loudly: a daemon that dies on a bad reload converts a typo into an outage.

hup := make(chan os.Signal, 1)
signal.Notify(hup, syscall.SIGHUP)
go func() {
	for range hup {
		next, err := loadAndValidate(path)
		if err != nil { log.Printf("reload rejected: %v", err); continue }
		current.Store(next)          // atomic.Pointer[Config]: readers see old or new, whole
	}
}()

The systemd unit, honestly

[Service]
Type=simple
ExecStart=/usr/local/bin/queued
Restart=on-failure
TimeoutStopSec=30
WatchdogSec=30

Type=simple says it plainly: the supervisor is the daemonizer; your process just runs. Restart=on-failure restarts crashes but not clean exits — always is for processes that should never stop on purpose. TimeoutStopSec is the SIGTERM deadline you drain against. WatchdogSec deserves the honest framing: with the go-systemd library you send READY=1 via sd_notify at startup and WATCHDOG=1 periodically; miss the interval and systemd kills and restarts you. It is deadlock insurance — it catches a wedged main loop, nothing more. The classic way to make it lie: pinging from a dedicated goroutine that stays healthy while the actual work loop is deadlocked. Send the ping from the loop whose liveness you actually care about, or you have bought insurance on someone else’s house.