prain stack: requires_NAME refuses to start without its services, merged --help

README.md

@@ -9,7 +9,8 @@ The proxy itself is not written yet; this repo holds the stack around it so far.
 and `logs` drive the stack's OpenRC user services. Every other subcommand (`serve`, `web`,
 `tui`, `check`, ...) goes to prain's own CLI in `PRAIN_ROOT/.venv`, with `scripts/env.sh`
 sourced first, so you no longer need to source it yourself. (In a shell where you did, the
-venv's `prain` comes first on PATH and `prain up` is unknown there.)
+venv's `prain` comes first on PATH and `prain up` is unknown there.) `prain --help` shows
+prain's own help with the stack commands merged into its command list.
 
     prain up [NAME...]        start the services (all by default), waiting until each is ready
     prain down [NAME...]      stop them, in reverse order
@@ -18,14 +19,22 @@ venv's `prain` comes first on PATH and `prain up` is unknown there.)
     prain logs [NAME...]      tail -F their logs (~/.local/state/prain/NAME.log)
 
 Services live in `~/.config/prain/prain.conf` (`PRAIN_CONF` overrides): `PRAIN_SERVICES`
-lists them, and per service `cmd_NAME` (the command, run in `PRAIN_ROOT` with env.sh
+lists them. Per service:
-sourced), `ready_NAME` (a URL `prain up` waits for) and `need_NAME` (dependencies). See
+- `cmd_NAME`: the command, run in `PRAIN_ROOT` with env.sh sourced.
-`scripts/prain.conf.example`.
+- `ready_NAME`: a URL `prain up` waits for.
+- `requires_NAME`: services that must already be up. If one isn't, NAME refuses to start
+  with a message (`prain: web needs vllm, which is not running ... Start it first: prain up
+  vllm`). It never starts them itself.
+
+See `scripts/prain.conf.example`.
 
 One OpenRC script, `openrc/init.d/prain`, serves them all through links named `prain.NAME`.
-OpenRC's supervise-daemon restarts a crashed service. It gives up after more than
+OpenRC settings go in `~/.config/rc/conf.d/prain.NAME`:
-`respawn_max` (3) crashes within `respawn_period` seconds (600; 1800 for vLLM in
+- `rc_after="prain.vllm"`: start order when both are in a runlevel. It doesn't start vLLM.
-`openrc/conf.d/prain.vllm`), so crashes further apart are restarted forever.
+- `respawn_max` (3) and `respawn_period` (600 s; 1800 for vLLM): supervise-daemon restarts
+  a crashed service, and gives up after more than `respawn_max` crashes within
+  `respawn_period`. Crashes further apart are restarted forever.
+- `respawn_delay` (5 s).
 
 ### Install
 
@@ -34,8 +43,9 @@ OpenRC's supervise-daemon restarts a crashed service. It gives up after more tha
     cp scripts/prain.conf.example ~/.config/prain/prain.conf
     ln -s "$PWD/openrc/init.d/prain" ~/.config/rc/init.d/prain
     for n in vllm web; do ln -s prain ~/.config/rc/init.d/prain.$n; done
-    cp openrc/conf.d/prain.vllm ~/.config/rc/conf.d/
+    cp openrc/conf.d/prain.* ~/.config/rc/conf.d/
-    rc-update --user add prain.web default     # optional: start with the session (pulls in vllm)
+    # optional, start both with the session (web waits for vLLM through rc_after):
+    rc-update --user add prain.vllm default && rc-update --user add prain.web default
 
 A new service is a `cmd_NAME` line, its name in `PRAIN_SERVICES` and one more `prain.NAME`
 link.

openrc/conf.d/prain.web

@@ -0,0 +1,3 @@
+# Order only: in a runlevel with both, web starts after vLLM is ready. Starting web alone
+# never starts vLLM; requires_web in prain.conf makes it fail with a message instead.
+rc_after="prain.vllm"

openrc/init.d/prain

@@ -1,7 +1,8 @@
 #!/sbin/openrc-run
 # One service of the prain stack, picked by the link name: prain.vllm, prain.web, ...
-# What it runs comes from prain.conf (`prain run NAME`); supervision settings from
+# What it runs and what must already run come from prain.conf (`prain run NAME`,
-# conf.d/prain.NAME (respawn_max, respawn_period, respawn_delay).
+# `prain deps NAME`); supervision settings and start order from conf.d/prain.NAME
+# (respawn_max, respawn_period, respawn_delay, rc_after).
 
 stack_name=${RC_SVCNAME#prain.}
 description="prain stack: ${stack_name}"
@@ -14,16 +15,13 @@ respawn_period=${respawn_period:-600}
 output_log=${XDG_STATE_HOME:-$HOME/.local/state}/prain/${stack_name}.log
 error_log=${output_log}
 
-depend() {
-	need $("${prain_bin:-$HOME/.local/bin/prain}" need "${RC_SVCNAME#prain.}")
-}
-
 start_pre() {
 	if [ "${RC_SVCNAME}" = prain ]; then
 		eerror "Start a link to this script, like prain.vllm"
 		return 1
 	fi
 	checkpath -d "${output_log%/*}"
+	"${command}" deps "${stack_name}"  # requires_NAME in prain.conf: refuse, never start them
 }
 
 start_post() {

scripts/prain

@@ -1,6 +1,6 @@
 #!/bin/bash
 # prain front door. up, down, restart, status and logs drive the stack's OpenRC user
-# services (prain.NAME); run, need and wait are what those services call. Anything else
+# services (prain.NAME); run, deps and wait are what those services call. Anything else
 # goes to prain's own CLI in PRAIN_ROOT/.venv, with its scripts/env.sh sourced.
 set -euo pipefail
 
@@ -50,9 +50,18 @@ run)
 	prain_env
 	eval "exec ${cmd//$'\n'/ }"
 	;;
-need)
+deps)  # fail, without starting anything, unless the services NAME requires are up
-	get need "$2"
+	for d in $(get requires "$2"); do
-	echo
+		url=$(get ready "$d")
+		if [ -n "$url" ]; then
+			curl -sf -o /dev/null "$url" && continue
+		else
+			rc-service --user "prain.$d" status > /dev/null 2>&1 && continue
+		fi
+		echo "prain: $2 needs $d, which is not running${url:+ (no answer from $url)}." \
+			"Start it first: prain up $d" >&2
+		exit 1
+	done
 	;;
 wait)
 	url=$(get ready "$2")
@@ -64,10 +73,19 @@ wait)
 		sleep 2
 	done
 	;;
-'' | -h | --help)
+'' | -h | --help)  # prain's own help, with the stack commands merged into its list
-	echo "stack: prain up|down|restart|status|logs [NAME...]  (services: ${services[*]})"
 	prain_env
-	exec "$PRAIN_ROOT/.venv/bin/prain" --help
+	"$PRAIN_ROOT/.venv/bin/prain" --help | awk -v stack="$(cat <<-EOF
+		    up [NAME...]        start services (all: ${services[*]}), each waits until ready
+		    down [NAME...]      stop services, in reverse order
+		    restart [NAME...]   restart services
+		    status [NAME...]    show whether services run
+		    logs [NAME...]      follow service logs ($logdir/NAME.log)
+	EOF
+	)" '
+		/^(usage: prain|  )[^{]*\{/ { sub(/\{/, "{up,down,restart,status,logs,") }
+		{ print }
+		/^  \{/ { print stack }'
 	;;
 *)
 	prain_env

scripts/prain.conf.example

@@ -7,8 +7,9 @@ PRAIN_ROOT=/home/fabian/coding/misc/prain
 PRAIN_SERVICES="vllm web"          # `prain up` starts in this order, `prain down` stops in reverse
 
 # cmd_NAME: what service prain.NAME runs. ready_NAME: URL that answers once it can serve
-# (`prain up` waits for it, PRAIN_READY_TIMEOUT seconds, default 900). need_NAME: services
+# (`prain up` waits for it, PRAIN_READY_TIMEOUT seconds, default 900). requires_NAME:
-# it depends on (OpenRC starts them first and stops it with them).
+# services that must already be up (their ready URL answers); if not, NAME refuses to start
+# and says so. They are never started for it.
 cmd_vllm='prain serve build/agent-int4.toml models/gemma-4-26B-A4B-it-Uncensored-MAX --
   --served-model-name gemma4 --language-model-only --max-model-len 16384
   --max-num-batched-tokens 1024 --enable-prefix-caching --port 8000
@@ -16,4 +17,4 @@ cmd_vllm='prain serve build/agent-int4.toml models/gemma-4-26B-A4B-it-Uncensored
 ready_vllm=http://127.0.0.1:8000/health
 
 cmd_web='prain web --host 0.0.0.0 --port 8080 --url http://127.0.0.1:8000 --config build/agent-int4.toml'
-need_web=vllm
+requires_web=vllm

scripts/test_prain.sh

@@ -10,7 +10,15 @@ cat > "$t/root/scripts/env.sh" <<EOF
 export FROM_ENV_SH=yes
 PATH=$t/root/.venv/bin:\$PATH
 EOF
-printf '#!/bin/sh\necho "prain $* env=$FROM_ENV_SH cwd=$PWD"\n' > "$t/root/.venv/bin/prain"
+cat > "$t/root/.venv/bin/prain" <<'EOF'
+#!/bin/sh
+if [ "$1" = --help ]; then
+	printf 'usage: prain [-h] {check,web} ...\n\npositional arguments:\n  {check,web}\n'
+	printf '    check               validate\n'
+	exit 0
+fi
+echo "prain $* env=$FROM_ENV_SH cwd=$PWD"
+EOF
 printf '#!/bin/sh\necho "$*"\n' > "$t/bin/rc-service"
 chmod +x "$t/root/.venv/bin/prain" "$t/bin/rc-service"
 cat > "$t/prain.conf" <<EOF
@@ -19,10 +27,12 @@ PRAIN_SERVICES="a b"
 cmd_a='echo a: \$FROM_ENV_SH
   in \$PWD'
 cmd_b='prain web --port 1'
-need_b=a
 ready_b=http://127.0.0.1:9/never
+requires_b=a
+requires_x=b
 EOF
 export PRAIN_CONF=$t/prain.conf PRAIN_READY_TIMEOUT=1 PATH=$t/bin:$PATH
+unset XDG_STATE_HOME
 fail=0
 check() {  # name expected actual
 	if [ "$2" = "$3" ]; then echo "ok   $1"; else echo "FAIL $1: expected [$2], got [$3]"; fail=1; fi
@@ -32,8 +42,6 @@ check passthrough "prain check x.toml env=yes cwd=/" "$("$p" check x.toml)"
 check run-joins-lines-in-root "a: yes in $t/root" "$("$p" run a)"
 check run-uses-venv-prain "prain web --port 1 env=yes cwd=$t/root" "$("$p" run b)"
 check run-unknown-fails 1 "$("$p" run zzz 2>/dev/null; echo $?)"
-check need "a" "$("$p" need b)"
-check need-none "" "$("$p" need a)"
 check wait-without-url 0 "$("$p" wait a; echo $?)"
 check wait-times-out 1 "$("$p" wait b 2>/dev/null; echo $?)"
 check up-in-order "--user prain.a start
@@ -41,4 +49,17 @@ check up-in-order "--user prain.a start
 check down-in-reverse "--user prain.b stop
 --user prain.a stop" "$("$p" down)"
 check status-one "--user prain.b status" "$("$p" status b)"
+check deps-ok-when-running 0 "$("$p" deps b; echo $?)"
+check deps-fail-without-starting-them "prain: x needs b, which is not running (no answer from http://127.0.0.1:9/never). Start it first: prain up b
+1" "$("$p" deps x 2>&1; echo $?)"
+check help-merges-stack-commands "usage: prain [-h] {up,down,restart,status,logs,check,web} ...
+
+positional arguments:
+  {up,down,restart,status,logs,check,web}
+    up [NAME...]        start services (all: a b), each waits until ready
+    down [NAME...]      stop services, in reverse order
+    restart [NAME...]   restart services
+    status [NAME...]    show whether services run
+    logs [NAME...]      follow service logs ($HOME/.local/state/prain/NAME.log)
+    check               validate" "$("$p" --help)"
 exit $fail