Commit `f8c1e35051`

f8c1e35051a416f451bc97dd49f0253c6673c765

parent: 3ac40e6851

Verified · cmc ci/build: success ci/test: error

cmc <hello@cleberg.net> · 2026-09-23 06:20 UTC

docs: queued follows, proxies

Ref #250

.gitbay/wiki/Admin.org +4

		@@ -81,6 +81,10 @@ rate limiting, to the last =X-Forwarded-For= hop that is not itself a
81	81	trusted proxy; from anyone else the header is ignored. Empty, the
82	82	default, is right when gitbayd terminates TLS itself.
83	83
	84	A reverse proxy in front of gitbay must not buffer responses, or the
	85	build page's live log arrives only when the build ends;
	86	=X-Accel-Buffering: no= covers nginx.
	87
84	88	** [web]
85	89	- =mode= — =view_only= (default) \| =accounts=. In view_only the mutating
86	90	web routes are never registered; in accounts, browser sessions are

.gitbay/wiki/CI.org +7 −5

		@@ -41,11 +41,13 @@ a matching tag push and nothing else.
41	41	A running build is followed with =build log <owner/name> <n> --follow=:
42	42	the stored log, then output as the runner sends it, then the outcome
43	43	as =build <n> <status>= on stderr once the build ends. The exit code is
44		0 whatever the outcome. The build page does the same without
45		JavaScript while a build is queued or running; =?follow=0= renders it
46		once. An account holds at most eight follows open, and signed-out
47		viewers share one account's eight. Over the JSON API the command
48		answers when the build ends, with the whole log.
	44	0 whatever the outcome. A follow of a build still queued after ten
	45	minutes ends on its own and says so on stderr, since nothing reaps a
	46	queued build. The build page does the same without JavaScript while a
	47	build is queued or running; =?follow=0= renders it once. An account
	48	holds at most eight follows open, and signed-out viewers share one
	49	account's eight. Over the JSON API the command answers when the build
	50	ends, with the whole log.
49	51
50	52	* The table
51	53

docs/specs/2026-09-23-build-log-follow-design.md +30 −9

		@@ -62,10 +62,14 @@ and the wait still wakes the loop.
62	62	`Ctx` gains `Done <-chan struct{}`, nil when the surface has none. The
63	63	embedded sshd closes it when the session's channel closes (the CLI's
64	64	shared connection outlives a Ctrl-C, the channel does not); `gitbayd
65		shell` passes nil, since its process ends with the session. httpd sets
66		it from `r.Context()` on the web and both API endpoints. A write
67		error also ends the loop. On `Done` the command returns
68		`protocol.ExitFailure` with no message; nobody is reading.
	65	shell` still passes nil, but its process does not end with the
	66	session: OpenSSH closes the child's pipes and sends no signal to a
	67	session with no pty, so a follow there ends at its next write, at the
	68	build's outcome, or at the queued limit below; the per-account cap is
	69	per process in that mode. httpd sets it from `r.Context()` on the web
	70	and both API endpoints. A write error also ends the loop. On `Done`
	71	the command returns `protocol.ExitFailure` with no message; nobody is
	72	reading.
69	73
70	74	At most 8 follows per account run at once (a counter in `control`,
71	75	decremented on return). The ninth exits 4: "8 follows are already open
		@@ -73,13 +77,23 @@ for this account; close one and retry". Signed-out web viewers are
73	77	account 0 and share the 8; the ninth gets the stored log once with the
74	78	refusal under it.
75	79
	80	Nothing reaps a queued build (`ReapStaleBuilds` only reaps `running`
	81	builds), and a running one is already bounded by the reaper's
	82	deadline, so a follow of a build that stays `pending` ends on its own
	83	after `followQueued` (10 minutes), writing to stderr `build <n> is
	84	still queued; nothing claimed it in 10m0s. Follow again once a runner
	85	has.` and exiting `protocol.ExitFailure`. The clock runs only while the
	86	follow has seen the build `pending`; once it sees `running` or a
	87	terminal status the limit no longer applies.
	88
76	89	The CLI's `pass("log", …)` help in `cmd/gitbay/main.go` names
77	90	`--follow`.
78	91
79	92	## Web
80	93
81	94	`GET /{owner}/{repo}/builds/{n}` streams when the build is `pending` or
82		`running` and the query has no `follow=0`. Otherwise it renders as now.
	95	`running`, the query has no `follow=0`, and the method is `GET`. A HEAD
	96	request (the route also matches it) renders once, like `?follow=0`.
83	97
84	98	Streaming:
85	99
		@@ -89,10 +103,17 @@ Streaming:
89	103	3. Dispatch `build log <repo> <n> --follow` with `Stdout` an escaping
90	104	writer (`template.HTMLEscape` per chunk, then flush through
91	105	`http.ResponseController`) and `Done` from the request context.
92		4. After the command returns, read the build and write
93		`<p class="notice" role="status">build finished: <status></p>` after
94		the `</pre>` that begins the tail, then the rest of the tail. A
95		dropped connection writes nothing more.
	106	4. If the request context is done (the client left), write nothing
	107	more. Otherwise write the `</pre>` that begins the tail, then, by
	108	the command's exit code: `ExitOK` reads the build and writes
	109	`<p class="notice" role="status">build finished: <status></p>`;
	110	`ExitDenied` (the follow cap) writes the stored log once above the
	111	`</pre>` and an error paragraph with the refusal, except a
	112	signed-out viewer (`viewer.ID == 0`) gets "Too many signed-out
	113	viewers are watching live builds. This is the log so far; reload to
	114	try again, or sign in." instead of the command's account-scoped
	115	wording; `ExitFailure` with a message (the queued limit) writes it
	116	as a `<p class="notice" role="status">`. Then the rest of the tail.
96	117
97	118	`build.html`, when `Live`, puts a line above the log: the log streams
98	119	until the build ends; a stream that stops with no "build finished" line

Commit f8c1e35051

Commit `f8c1e35051`