docs(config): sizing guidance for request_total_timeout
Folds this MR's sizing guidance for request_total_timeout into the paragraph
that now covers the same ground on main, leaving the configuration reference
with one sizing paragraph instead of two.
Answers question 2 of the two open questions David raised on #269: whether the
configuration reference should carry an operator sizing rule for
request_total_timeout.
What changed since this MR opened
When this MR was created, the reference documented the field in one line —
"Overall deadline for a single upstream request, including reading the response
body." — and gave no way to pick a value. A sizing paragraph has landed on
main since then, written against the rate clients read at. It repeats this
MR's arithmetic (5GB / 30s / 167 MB/s), its retry point, and its sizing
instruction, so the section carried two paragraphs answering one question from
different sides, with nothing to tell an operator which bottleneck to measure.
The paragraph this MR added is therefore deleted, and what only it carried moves into the existing paragraph, which keeps its place in the section:
- The deadline does not extend while a transfer is making progress.
client.go:182applies a plaincontext.WithTimeoutderived from the request context, so there is no progress or idle reset. - Once upstream egress is slow enough, the deadline rather than
body_size_cap_blobis the effective ceiling on the artifact size an instance can proxy. - Past the deadline the upstream read fails as a transport error. That is the
vantage of the instance's own read; the paragraph on
maindescribed the same moment only from the client's side ("a truncated body rather than an error status"). Both now sit in one sentence, so the two readings cannot be taken as contradicting each other. - Upstream egress joins the client read rate as a sizing variable, so the opening sentence names both bottlenecks.
The figures were re-checked against the code rather than carried across:
internal/config/virtualrepositories.go for the 30s and 5,000,000,000-byte
defaults, and internal/remote/upstreamhttp/client.go for the single context
deadline that covers the body read. Size fields parse SI, so 5GB is 5×10⁹ bytes.
Why it is worded as a standing property
The configuration reference is user-facing and documents as-is behavior and constraints only. The sizing rule is written as a property the field always has: no "interim" framing, no forward reference to a progress-based deadline that would replace the flat cap, and no issue citation in the doc text itself.
Scope notes
- No schema change, so
config.example.yamlis untouched. The configuration guardrail runs schema → reference, not the reverse. - Question 1 on #269 — what value GitLab.com actually runs — is not answered
here. It lives in Vault (
ar-config), not in the repo, and is being fetched separately. docs-prefixed work is exempt from the related-issue rule; the link below is there because #269 is the reason the change exists.
Related to #269