From b0d54a2c518d2f18112037e61608595945fd678e Mon Sep 17 00:00:00 2001
From: clawbot <35+clawbot@noreply.example.org>
Date: Tue, 20 Oct 2026 15:28:31 +0200
Subject: [PATCH] README and SPEC say what docker stop does to requests in
 progress when the app exits at once (closes #139)

runit stops smallwebwaf and the app at the same time, so the five seconds
smallwebwaf gives requests in progress help only while the app still
answers them. Both documents now say so, say what the client gets when the
app exits at once on SIGTERM, and say what an app does to let its requests
in progress finish.

Model: opus-5-5
---
 README.md | 10 ++++++++--
 SPEC.md   | 13 ++++++++++---
 2 files changed, 18 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index ba6142e..ee4ad25 100644
--- a/README.md
+++ b/README.md
@@ -1954,8 +1954,14 @@ main "$@"
   without one, it still starts. At each start the `run` script of `smallwebwaf`
   gives that directory and every file in it to the `smallwebwaf` user, so a host
   directory mounted there needs no change of owner.
-- `docker stop` has runit stop both processes. `smallwebwaf` then stops taking
-  requests and gives those in progress five seconds to finish.
+- `docker stop` has runit stop both processes at once, each with SIGTERM.
+  `smallwebwaf` then stops taking requests and gives those in progress five
+  seconds to finish, which they can do only while the app still answers. An app
+  that exits at once on SIGTERM ends them: the client gets `502`, or a response
+  cut short if the app had already begun to answer. An app that should let them
+  finish keeps taking and answering requests, not only the ones it already has,
+  for the whole five seconds after SIGTERM, since `smallwebwaf` can still pass
+  it requests it took before then.
 
 A rule file is one rule per line: a name, what to match against, what to do, and
 a regex.
diff --git a/SPEC.md b/SPEC.md
index cd190a4..f84d356 100644
--- a/SPEC.md
+++ b/SPEC.md
@@ -1324,9 +1324,16 @@ The two processes:
 - A `smallwebwaf` that stops at start, for example on invalid configuration, is
   started again every second and stops again, logging its message each time,
   until the cause is fixed. The health check fails meanwhile.
-- `docker stop` sends SIGTERM to `runsvinit`, which has runit stop both
-  services, each with SIGTERM, and exits once they have stopped. `smallwebwaf`
-  writes its state files as it stops (see "Persistent state").
+- `docker stop` sends SIGTERM to `runsvinit`, which has runit stop both services
+  at once, each with SIGTERM, and exits once they have stopped. `smallwebwaf`
+  stops taking requests, gives those in progress five seconds to finish, and
+  writes its state files as it stops (see "Persistent state"). The requests in
+  progress can finish only while the app still answers. An app that exits at
+  once on SIGTERM ends them: the client gets `502`, or a response cut short if
+  the app had already begun to answer. An app that should let them finish keeps
+  taking and answering requests, not only the ones it already has, for the whole
+  five seconds after SIGTERM, since `smallwebwaf` can still pass it requests it
+  took before then.
 - The container's root filesystem stays writable: runit writes each service's
   status into its directory under `/etc/service`.