Add percentage limit for stale cache age

[bneradt]

A fixed stale-age window can let short-lived cached responses remain
usable for many times their original freshness lifetime. This makes
serving stale content disproportionately risky for responses with a
short max-age.

This adds an optional percentage limit and applies the smaller of the
percentage-based and absolute stale-age windows. The default keeps the
existing behavior, while transaction overrides and supported scripting
interfaces can opt in per use case.

Fixes: #12252

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated no new comments.

Suppressed comments (4)

tests/gold_tests/cache/replay/max_stale_age_percent.replay.yaml:89

• To reduce timing sensitivity, widen the margin on the "within percentage limit" transaction by increasing the delay and updating the comment to match the configured percentage window.

  # At five seconds old, the object is stale but remains within the two-second
  # percentage stale window.
  - client-request:
      delay: 5s
      method: "GET"

tests/gold_tests/cache/replay/max_stale_age_percent.replay.yaml:106

• Likewise, widen the margin on the "past percentage limit" transaction by increasing the delay and updating the comment to reflect the new percentage calculation.

  # At eight seconds old, the object exceeds max-age (4 seconds) plus 50%
  # (2 seconds), even though the absolute stale age limit is 100 seconds.
  - client-request:
      delay: 3s
      method: "GET"

src/proxy/http/HttpTransact.cc:6413

• get_max_age() returns -1 when neither s-maxage nor max-age is present, but this value is still used in max_age + max_stale_age. That effectively subtracts 1 second from the allowed stale window for responses without max-age, which also contradicts the doc change that says those responses are controlled by max_stale_age alone. Consider clamping the max_age used for the age-sum to at least 0 before doing the comparison (keeping the percentage logic gated on max_age >= 0).

  // Negative age is overflow
  if ((current_age < 0) || (current_age > max_age + max_stale_age)) {
    TxnDbg(dbg_ctl_http_trans, "document age is too large %" PRId64, (int64_t)current_age);

tests/gold_tests/cache/replay/max_stale_age_percent.replay.yaml:53

• This replay test uses a 4s max-age with a 50% stale window and only 1s of headroom on the "should still be served stale" request (5s vs allowed 6s). That can be timing-sensitive in CI. Consider using a larger margin (e.g., 100% with adjusted delays) so the pass/fail cases are less likely to flap due to scheduling jitter.

This issue also appears in the following locations of the same file:

• line 85
• line 102

      proxy.config.http.cache.max_stale_age: 100
      proxy.config.http.cache.max_stale_age_percent: 50
      proxy.config.http.parent_proxy.self_detect: 0