add stream heartbeat

4 files changed, 14 insertions, 4 deletions

diff --git a/docs/api.md b/docs/api.md
index e813845..cdc722e 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -194,6 +194,9 @@ node or by sync:
 {"key":"settings/theme","deleted":true}
 ```
 
+While nothing changes, a blank line every 30 s (`--stream-heartbeat`) keeps proxies in
+front from taking the stream for dead; skip blank lines.
+
 An event carries the value as a read would return it then. Changes in quick succession
 may come as one event with the latest value: a stream tells the value, not every write.
 A change that leaves the value as it was sends nothing. The connection stays open; after
diff --git a/docs/example.toml b/docs/example.toml
index cef5754..00bfed3 100644
--- a/docs/example.toml
+++ b/docs/example.toml
@@ -68,6 +68,11 @@ htpasswd = "/etc/continuum/htpasswd"
 # authentication. The proxy must set or clear it on every request.
 # user-header = "X-Remote-User"
 
+# How often GET /stream sends a blank line while nothing changes, so proxies in front
+# keep it open: below their read timeout (nginx's proxy_read_timeout, 60 s by default).
+# 0: never.
+# stream-heartbeat = "30s"
+
 # Where the reverse proxies whose user-header is believed connect from: IP addresses (or
 # ranges, as ADDRESS/BITS), and unix for the API's Unix sockets (bind-addr). On a host
 # with other users, leave out the addresses and have the proxy use a Unix socket: others
diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index 387a7ac..701cdf9 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -329,7 +329,8 @@ paths:
       description: |
         Newline-delimited JSON: one event with the current value, then one whenever
         the resolved value changes (by a local write or by sync). The connection stays
-        open.
+        open; while nothing changes, a blank line every `--stream-heartbeat` (30 s)
+        keeps proxies from closing it: skip blank lines.
       responses:
         '200':
           description: Event stream.
diff --git a/docs/operations.md b/docs/operations.md
index da73fce..fae3b6c 100644
--- a/docs/operations.md
+++ b/docs/operations.md
@@ -162,9 +162,10 @@ The names the proxy gives are the users of `--protocol-writers` and of who wrote
 ([`api.md`](api.md)).
 
 What streams (`/stream`, the dashboard's events) says `X-Accel-Buffering: no`, so nginx
-passes it on as it comes. The dashboard's events have a keepalive every 15 s; `/stream`
-sends nothing while nothing changes, so nginx ends a quiet one after its
-`proxy_read_timeout` (60 s): raise that for it, or have clients reconnect.
+passes it on as it comes, and says it's alive while nothing changes: the dashboard's
+events every 15 s, `/stream` every 30 s (a blank line, `--stream-heartbeat`), within
+nginx's `proxy_read_timeout` (60 s). With a proxy that gives up sooner, lower
+`--stream-heartbeat` below its timeout.
 
 The API may also be served under a path of its own (`location /continuum/ {
 proxy_pass http://unix:/run/continuum/api.sock:/; }`): its redirects (`Location`), the dashboard's