Skip to content

feat(git): serve cached refs during background refresh - #67

Closed
profiling wants to merge 1 commit into
rolandjitsu:mainfrom
profiling:feat/background-refresh
Closed

profiling wants to merge 1 commit into
rolandjitsu:mainfrom
profiling:feat/background-refresh

Conversation

@profiling

@profiling profiling commented Nov 3, 2026 •

Copy link
Copy Markdown

What kind of change does this PR introduce?

  • feat

Summary
When the fetch TTL expires, clients currently wait for an upstream fetch even if the mirror already contains their objects. This adds opt-in stale-while-revalidate: serve cached refs within a configured maximum age and refresh in the background. Closes #66.

Refreshes are coalesced per repository and bounded across repositories. Successful full-ref refreshes persist their observation start time in proxy-refresh.json. Restart restores age only when the record matches the repository, configured upstream and mirror directory identity. Missing, corrupt, oversized, future-dated or replaced records require a full refresh. Failed refreshes and SHA-only backfills do not renew full-ref age.

Stale mode separates body decoding, freshness inspection, mandatory upstream work and local delivery admission. Slow or cancelled upstream requests retain bounded owners without consuming every local-service slot. Overload returns 503 rather than queueing another expensive owner. Cached GET advertisements remain available when request-body admission is full. Strict mode retains its existing queueing behavior.

Cold clones must satisfy the age bound when they finish. Uploads recheck age and identity after waiting for an upload slot, immediately before Git starts; already started streams can complete after the refs expire. Mirror guards and stale-serving leases remain held until their Git child is reaped.

This is request-triggered refresh, not scheduled polling. The default remains unchanged. This PR does not include #72's concurrent upload-pack negotiation or introduce a general upstream timeout or shutdown-cancellation setting.

Tests

  • Local formatting, locked all-target/all-feature clippy with warnings denied, and all-feature tests pass.
  • 188 tests pass on Linux with Git 2.51.2 and Rust 1.94.1.
  • Regression coverage includes restart recovery, invalid/replaced metadata, full refs versus SHA-only age, metadata write failure, upstream identity changes, slow cold clones, queued-upload expiry, active-stream completion, admission saturation, cancelled owners, and per-request credentials/auth errors.
  • Existing HTTP, authentication, protocol and cache tests remain passing.

Checklist

  • Preserves read-only, pull-only behavior and system Git protocol handling.
  • Preserves request credential capture and typed upstream authentication failures.
  • README, CLI help and Helm configuration descriptions updated.
  • No new dependencies.

Breaking change?
No behavior change with the default settings. With stale serving enabled, clients may read older objects already present in the same mirror, and overloaded admission lanes now return 503. Persistent age recovery assumes a correct wall clock across downtime and a single proxy process owning the cache root. Cold mirrors still require a complete upstream mirror clone.

@codecov

codecov Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 98.36830% with 28 lines in your changes missing coverage. Please review.
✅ Project coverage is 98.13%. Comparing base (b9f2841) to head (3ba149d).
⚠️ Report is 1 commits behind head on main.

Files with missing lines Patch % Lines
src/git.rs 98.37% 27 Missing ⚠️
src/server.rs 97.72% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main      #67      +/-   ##
==========================================
+ Coverage   97.57%   98.13%   +0.56%     
==========================================
  Files           9        9              
  Lines        3707     5371    +1664     
==========================================
+ Hits         3617     5271    +1654     
- Misses         90      100      +10     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@profiling
profiling force-pushed the feat/background-refresh branch from 2e43b6a to bb2079b Compare November 3, 2026 11:39
@profiling
profiling force-pushed the feat/background-refresh branch 4 times, most recently from efd444e to 17c8719 Compare November 13, 2026 06:29
@profiling
profiling marked this pull request as draft November 14, 2026 05:16
profiling pushed a commit to profiling/git-cache-proxy that referenced this pull request Nov 14, 2026
Keep rolandjitsu#72, rolandjitsu#76 and rolandjitsu#77 with internal maintenance while deferring rolandjitsu#67.
Preserve the previous tree on its archive branch and in normal history.

Assisted-by: OpenAI:Codex

@rolandjitsu rolandjitsu left a comment •

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks again for the contribution. I left a few minor comments. I think you can squash the commits into a single one.

And try to get the patch coverage to pass too - codecov is reporting red.

Comment thread src/config.rs Resolved
Comment thread src/git.rs Resolved
Comment thread README.md Resolved
Comment thread src/server.rs Resolved
Comment thread src/server.rs Resolved
Opt in with --max-stale-seconds: serve cached refs within the age bound
and refresh in the background, so clients do not wait on a TTL-expired
upstream fetch. Age is persisted in proxy-refresh.json so a restart
does not reset it.

Refs: rolandjitsu#66

Assisted-by: Codex:gpt-6.1-terra
Assisted-by: Claude:claude-opus-4-8
@profiling

Copy link
Copy Markdown
Author

Thanks for the careful review, it improved the patch. Pushed 3ba149d, squashed into one commit and rebased on current main (one conflict in src/git.rs, resolved by taking the new unconditional upstream URL fetch).

Summary of what changed since your review:

  • Single commit, as suggested.
  • Admission: body_permit only for routes with a request body, released before lfs_batch; new regression test.
  • Readability: positive_usize moved below the public items; ensure_fresh_stale split by path with no behavior change.
  • Docs: README text moved to docs/configuration.md and docs/architecture.md, plus a security note about reading unreachable objects by SHA.
  • Coverage: codecov/patch and codecov/project pass.
  • Flaky tests in this PR: a freshly written fixture script could fail to spawn with ETXTBSY when another test thread forked at the same time. The fixtures now wait that out. This is test-only; no production code changed. Unit tests ran 500 times without a failure.

Separately, a few older tests on main write scripts the same way (tests/e2e.rs, tests/retry.rs) and can flake for the same reason. I left them out of this PR to keep it focused and can send a small follow-up if you want.

@profiling

Copy link
Copy Markdown
Author

@rolandjitsu thanks again for the thorough review. I have addressed all the comments (3ba149d, single commit, rebased on main, checks green).

Before you spend more time on this, I would like to ask whether it is still worth carrying. I have started to doubt the cost/benefit:

  • It is hard to tune. --max-stale-seconds has no good default. If it is long, clients may get refs that are too old and have no way to tell. If it is short, it only helps hot repos when combined with periodic refresh ([FEATURE] Optional periodic refresh of recently used repositories #78), which is what would actually cut the on-demand fetches.
  • It is large for that gain. About +2500 lines, roughly 2000 of them in src/git.rs: persisted refresh age (proxy-refresh.json), layered admission lanes, and restart recovery. That is a lot of surface to maintain for one opt-in knob.
  • It overlaps with [FEATURE] Optional periodic refresh of recently used repositories #78. This is request-triggered refresh only, not scheduled polling, so it may be superseded by periodic refresh.

If you think the feature is still wanted, I will keep going. If not, I am happy to close this PR. #66 can stay open for a smaller design, for example scheduled refresh on its own.

@rolandjitsu

Copy link
Copy Markdown
Owner

If you think the feature is still wanted, I will keep going. If not, I am happy to close this PR. #66 can stay open for a smaller design, for example scheduled refresh on its own.

I think #79 is more aligned with what was also on the roadmap and has fewer risks and reduced complexity. Let's close this one and focus on #79.

I appreciate the contributions so far. I hope this won't demotivate you.

@profiling profiling closed this Nov 16, 2026
@profiling
profiling deleted the feat/background-refresh branch November 16, 2026 15:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[FEATURE] Serve cached refs while refreshing in the background

2 participants