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:182 applies a plain context.WithTimeout derived 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_blob is 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 main described 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.yaml is 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

Edited by Radamanthus Batnag

Merge request reports

Loading
Loading