Sd notify - API reference

Exported surface for the sd-notify subsystem. Part of the API reference.

Package `valis/src/sd-notify`

Functions

`notify-ready`

(notify-ready &key status)

Signal readiness to the supervisor: emit READY=1 to $NOTIFY_SOCKET, and a STATUS= line carrying STATUS when supplied. A no-op when $NOTIFY_SOCKET is unset. Returns NIL.

`notify-status`

(notify-status line)

Refresh the supervisor-visible status: emit STATUS=<LINE> to $NOTIFY_SOCKET. A no-op when $NOTIFY_SOCKET is unset. Returns NIL.

`notify-watchdog`

(notify-watchdog)

Ping the systemd watchdog: emit WATCHDOG=1 to $NOTIFY_SOCKET so the supervisor sees the resident is still serving. A no-op when $NOTIFY_SOCKET is unset (the dev/foreground/test case). Returns NIL.

`rewrite-notify-address`

(rewrite-notify-address addr)

Map a $NOTIFY_SOCKET value to the AF_UNIX address to connect to. An @-prefixed value names an abstract-namespace socket, encoded with a leading NUL and the @ dropped; a plain pathname (the production /run/systemd/notify case) is returned unchanged.

`serving-path-live-p`

(serving-path-live-p accept-loop-live-p postgres-reachable-p fabric-serving-p)

T only when the accept/serve loop is responsive AND Postgres is reachable (a bounded probe) AND the fabric is serving. The WATCHDOG=1 ping is downstream of this: a wedged loop or a lost DB yields NIL, no ping fires, WatchdogSec elapses, and systemd restarts. Each argument is a nullary predicate so the gate is proven at the predicate level with stubbed inputs.

`start-health-loop`

(start-health-loop &key accept-loop-live-p fabric-serving-p status-fn (postgres-reachable-p *postgres-reachable-p*) (interval *health-loop-interval*))

Start the serving-path health loop in a bordeaux-thread. A NO-OP (spawns no thread, returns NIL) when $NOTIFY_SOCKET is unset — that keeps dev-boot and the hermetic test image green (no watchdog thread off a supervisor). Each iteration pings WATCHDOG=1 only when serving-path-live-p holds over the three predicates, refreshes STATUS, then sleeps INTERVAL. Per-iteration errors are contained (logged via log4cl, loop continues) so a transient fault never kills the loop silently.

`stop-health-loop`

(stop-health-loop)

Tear down the health-loop thread if running. Idempotent; wrapped so a teardown fault cannot block shutdown.