DOC/MINOR: document the 'before' directive in dependencies example

Update the dependencies documentation and example to demonstrate the 'before' configuration option alongside 'after'. A new 'zeroth' process was added to the example YAML and test suite to verify the correct startup sequence (zeroth -> first -> second).

This clarifies how 'before' acts as a mirror edge to 'after', which is particularly useful for inserting a service into the startup order without modifying existing process configurations. Additionally, minor updates were initiated in the restart-backoff documentation.

Author: oktalz

documentation/dependencies/README.md

@@ -1,11 +1,11 @@
 # Dependencies
 
-`after:` controls startup ordering. A service listed in another's `after` is started first; gopherd computes the order with a topological sort.
+`after:` and `before:` control startup ordering. A service listed in another's `after` is started first; `before` is the same edge written from the other side. gopherd computes the order with a topological sort.
 
 ## Config
 
 ```yaml
-# Order startup with `after`: `first` runs before `second`.
+# Order startup with `after` and `before`: zeroth -> first -> second.
 processes:
   - name: second
     command: /bin/sh
@@ -16,21 +16,28 @@ processes:
     command: /bin/sh
     args: ["-c", "echo first >> ORDERLOG && sleep 300"]
     on-failure: shutdown
+  - name: zeroth
+    command: /bin/sh
+    args: ["-c", "echo zeroth >> ORDERLOG && sleep 300"]
+    before: [first]
+    on-failure: shutdown
 ```
 
 - `second` declares `after: [first]`, so gopherd starts `first` first.
+- `zeroth` declares `before: [first]` — the mirror form, useful when the
+  inserted service is the one being added and the existing configs should
+  stay untouched.
 - Declaration order in the file does not matter — the dependency graph does.
-- `after` orders startup only; use `requires` if a dependency failure should also fail the dependent.
+- `after`/`before` order startup only; use `requires` if a dependency failure should also fail the dependent.
 
 ## Expected behavior
 
-- `first` starts and appends `first` to the log.
-- `second` starts afterward and appends `second`.
-- The log reads `first` then `second`.
+- `zeroth` starts first, then `first`, then `second`; the log reads
+  `zeroth`, `first`, `second`.
 
 ## Test
 
-`ORDERLOG` is replaced with a temp path via `RunConfig`. The test asserts gopherd starts `first` before `second` (the daemon's `started` lines). Note `after` orders gopherd's start calls; the echoes themselves run in separate shells, so use a `ready-check` when the dependent needs the dependency's work completed.
+`ORDERLOG` is replaced with a temp path via `RunConfig`. The test asserts gopherd's `started` lines appear in `zeroth`, `first`, `second` order. Note `after`/`before` order gopherd's start calls; the echoes themselves run in separate shells, so use a `ready-check` when the dependent needs the dependency's work completed.
 
 ```bash
 go test ./documentation/dependencies/ -v

documentation/dependencies/example.yml

@@ -1,4 +1,4 @@
-# Order startup with `after`: `first` runs before `second`.
+# Order startup with `after` and `before`: zeroth -> first -> second.
 processes:
   - name: second
     command: /bin/sh
@@ -9,3 +9,9 @@ processes:
     command: /bin/sh
     args: ["-c", "echo first >> ORDERLOG && sleep 300"]
     on-failure: shutdown
+  # before: the mirror edge — zeroth starts ahead of first
+  - name: zeroth
+    command: /bin/sh
+    args: ["-c", "echo zeroth >> ORDERLOG && sleep 300"]
+    before: [first]
+    on-failure: shutdown

documentation/dependencies/example_test.go

@@ -42,13 +42,17 @@ func TestDependenciesExample(t *testing.T) {
 	// second running implies gopherd reached it in the start sequence.
 	d.WaitRunning("second", 5*time.Second)
 
-	// `after` guarantees gopherd's start order (fork/exec), not the order the
-	// two shells reach their echo, so assert on the daemon's own log.
+	// `after`/`before` guarantee gopherd's start order (fork/exec), not the
+	// order the shells reach their echo, so assert on the daemon's own log.
 	out := d.Output()
+	zi := strings.Index(out, "started zeroth")
 	fi := strings.Index(out, "started first")
 	si := strings.Index(out, "started second")
-	if fi == -1 || si == -1 {
-		t.Fatalf("expected both start lines in daemon output, got: %q", out)
+	if zi == -1 || fi == -1 || si == -1 {
+		t.Fatalf("expected all three start lines in daemon output, got: %q", out)
+	}
+	if zi > fi {
+		t.Errorf("expected zeroth (before: [first]) started before first, got: %q", out)
 	}
 	if fi > si {
 		t.Errorf("expected first started before second, got: %q", out)

documentation/restart-backoff/README.md

@@ -19,6 +19,13 @@ processes:
     backoff-delay: 500ms
     backoff-factor: 2.0
     backoff-limit: 5s
+
+  - name: batch
+    command: /usr/local/bin/batch-job
+    on-success: restart
+    on-failure: shutdown
+    backoff-delay: 500ms
+    backoff-limit: 5s
 ```
 
 - `backoff-delay` — delay before the first restart (default `500ms`).
@@ -28,21 +35,26 @@ processes:
   continue at this fixed pace forever. There is no retry count limit.
 - A run that survives longer than `backoff-limit` resets the counter, so a
   service that crashes once a day always restarts after `backoff-delay`.
-- `on-success: restart` also exists for workers that should rerun after a
-  clean exit; the default `on-success` is `shutdown`.
+- `on-success: restart` (the `batch` service) reruns a worker after every
+  clean exit with the same backoff pacing — a poor man's cron loop. The
+  default `on-success` is `shutdown`, and a genuine failure still takes the
+  container down via `on-failure: shutdown`.
 
 ## Expected behavior
 
 - `flaky` crashes, gopherd logs the exit and restarts it after the backoff
   delay; `gopherd status` shows the `restarts=` counter climbing.
-- `app` and gopherd itself are unaffected by the crash loop.
+- `batch` exits 0, is rerun after the backoff delay, and its counter climbs
+  the same way.
+- `app` and gopherd itself are unaffected by either loop.
 
 ## Test
 
-Run level. The flaky placeholder is substituted with `/bin/false` (always
-exits 1) and the backoff shortened; the test polls `status` until the
-restart counter reaches 3, proving the restart loop, then checks the daemon
-is still healthy. SIGTERM yields a clean exit 0.
+Run level. The placeholders are substituted with `/bin/false` (flaky, always
+exits 1) and `/bin/true` (batch, always exits 0) and the backoff shortened;
+the test polls `status` until both restart counters reach 3, proving the
+crash-restart and clean-rerun loops, then checks the daemon is still
+healthy. SIGTERM yields a clean exit 0.
 
 ```bash
 go test ./documentation/restart-backoff/ -v

documentation/restart-backoff/example.yml

@@ -13,3 +13,11 @@ processes:
     backoff-delay: 500ms
     backoff-factor: 2.0
     backoff-limit: 5s
+
+  # batch worker: reruns after every clean exit, same backoff pacing
+  - name: batch
+    command: /usr/local/bin/batch-job
+    on-success: restart
+    on-failure: shutdown
+    backoff-delay: 500ms
+    backoff-limit: 5s

documentation/restart-backoff/example_test.go

@@ -35,14 +35,26 @@ func readExample(t *testing.T, path string) string {
 }
 
 // Counters only appear in the full status listing, not `status <name>`.
-var restartsRe = regexp.MustCompile(`(?m)^\s*flaky\s+\S+\s+exits=\d+ restarts=(\d+)`)
+// Counters only appear in the full status listing, not `status <name>`.
+func restartsOf(t *testing.T, d *doctest.Daemon, service string) int {
+	t.Helper()
+	re := regexp.MustCompile(`(?m)^\s*` + service + `\s+\S+\s+exits=\d+ restarts=(\d+)`)
+	m := re.FindStringSubmatch(d.Command("status"))
+	if m == nil {
+		return 0
+	}
+	n, _ := strconv.Atoi(m[1])
+	return n
+}
 
-// The flaky placeholder becomes /bin/false (always exits 1); with a shortened
-// backoff the restart counter climbs while app and the daemon stay healthy.
+// flaky becomes /bin/false (crash loop) and batch /bin/true (clean-exit
+// rerun loop); with a shortened backoff both restart counters climb while
+// app and the daemon stay healthy.
 func TestRestartBackoff(t *testing.T) {
 	cfg := readExample(t, "example.yml")
 	cfg = strings.ReplaceAll(cfg, "/usr/local/bin/myapp", "sleep")
 	cfg = strings.ReplaceAll(cfg, "/usr/local/bin/flaky-worker", "/bin/false")
+	cfg = strings.ReplaceAll(cfg, "/usr/local/bin/batch-job", "/bin/true")
 	cfg = strings.ReplaceAll(cfg, "backoff-delay: 500ms", "backoff-delay: 50ms")
 	cfg = strings.ReplaceAll(cfg, "backoff-limit: 5s", "backoff-limit: 200ms")
 
@@ -51,15 +63,19 @@ func TestRestartBackoff(t *testing.T) {
 	d.WaitRunning("app", 5*time.Second)
 
 	deadline := time.Now().Add(10 * time.Second)
-	restarts := 0
-	for time.Now().Before(deadline) && restarts < 3 {
-		if m := restartsRe.FindStringSubmatch(d.Command("status")); m != nil {
-			restarts, _ = strconv.Atoi(m[1])
+	var flaky, batch int
+	for time.Now().Before(deadline) {
+		flaky, batch = restartsOf(t, d, "flaky"), restartsOf(t, d, "batch")
+		if flaky >= 3 && batch >= 3 {
+			break
 		}
 		time.Sleep(100 * time.Millisecond)
 	}
-	if restarts < 3 {
-		t.Fatalf("expected >=3 restarts within 10s, got %d", restarts)
+	if flaky < 3 {
+		t.Fatalf("expected >=3 flaky restarts within 10s, got %d", flaky)
+	}
+	if batch < 3 {
+		t.Fatalf("expected >=3 batch reruns (on-success: restart) within 10s, got %d", batch)
 	}
 
 	// crash loop must not take the supervisor or the healthy service down