Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 3 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -127,10 +127,9 @@ API proxied; objects stored content-addressed and integrity-checked).
Early, single-maintainer software: no independent review or wide deployment yet.
Pin a version and try it against your own setup before relying on it.

Not yet implemented:

- A background/scheduled refresh (today every `info/refs` triggers an on-demand,
TTL-coalesced fetch).
Optional background refresh of recently used mirrors is available with
`--refresh-interval-seconds` (default `0`, disabled; minimum enabled value
`3600`). See [Configuration](docs/configuration.md#periodic-refresh).

**Non-goal: a git-free image.** The `git` binary is a permanent runtime
dependency: the proxy serves clients by running `git upload-pack`, and no
Expand Down
37 changes: 30 additions & 7 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,9 @@ works internally, and a throughput benchmark. For usage see the
replicating every repo, and it can lag the exact commit CI just pushed.

This proxy is **lazy and pull-only**: it caches on first request, and on every
request runs an incremental `git fetch` before serving - so a client always gets
the ref it asked for, and nothing is ever pushed or replicated to the origin.
request checks freshness before serving, using a TTL-coalesced incremental
`git fetch`. Optional background refresh updates recently used existing mirrors;
it never discovers or clones repositories. Nothing is pushed to the origin.
That pull-only property is what makes it viable against a sensitive origin.

## How it compares
Expand All @@ -34,8 +35,9 @@ That pull-only property is what makes it viable against a sensitive origin.
mirror can lag its refresh interval (`lag`); `--reference` is only as fresh as its local
seed (`seed`).
4. Only new objects cross the WAN per request; the bulk history is served from the local mirror.
5. Never writes to or proactively replicates from the origin - it only ever pulls what a
client requested.
5. Never writes to the origin. With background refresh disabled (the default),
upstream pulls serve client requests only. Optional refresh pulls recently used
existing mirrors without discovering or cloning repositories.
6. Works against any unmodified Git smart-HTTP origin. GitLab Geo needs GitLab on both ends.

## How it works
Expand Down Expand Up @@ -70,9 +72,10 @@ Retries stay inside the existing per-repository lock. Each failed clone's stagin
directory is removed before another attempt; an existing fetch mirror is kept.
Only success updates the freshness timestamp. After retries are exhausted the
request still fails with 502; stale refs are not served as a fallback. The retry
budget limits attempts and adds at most seven seconds of backoff; it does not
impose a new transfer timeout on large repositories. LFS and local upload-pack
operations are outside this retry policy.
budget limits attempts and adds at most seven seconds of backoff. Each upstream
Git operation also has one `--upstream-timeout-seconds` budget (default `3600`)
across all attempts and backoff, including background refresh. LFS and local
upload-pack operations are outside this retry policy and operation budget.

If a client `want`s a commit by SHA that the mirror never captured - typically a
GitHub pull-request merge commit, which lives only under the unadvertised
Expand Down Expand Up @@ -105,6 +108,26 @@ headers are sent terminate the response body. On Unix targets with
remaining group members are stopped before the leader is reaped. Other
targets wait for request completion and stdout EOF before observing exit.

### Background refresh

Optional background refresh keeps recently used existing mirrors warm without
repository discovery or cold clones. See [Periodic refresh configuration](./configuration.md#periodic-refresh)
for flags, defaults, scheduling, and failure behavior.

Refresh shares the per-repository fetch lock and TTL with requests and eviction.
Client recency controls eligibility so periodic work cannot keep a mirror active
forever. Background fetches do not promote the eviction LRU; successful fetches
mark tracked entries for deferred size measurement and capacity enforcement by
the existing evictor. Entries already selected for eviction are not recreated,
and an eviction cancels a refresh fetch running for that mirror instead of
waiting for it.

Round deadlines stop admission while running fetches drain, bounding schedule
overlap without discarding work already in progress. Shutdown instead cancels
upstream operations and waits for child cleanup. Refresh uses only the static
server credential or anonymous access, so scheduling cannot retain or replay
transient client credentials.

### git-LFS

LFS objects use a different HTTP API from the git protocol, so they are cached
Expand Down
39 changes: 39 additions & 0 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,11 @@ Every flag has an environment-variable equivalent.
| `--auth-ttl-seconds` | `GITCACHEPROXY_AUTH_TTL_SECONDS` | `0` | Reuse a validation verdict per `(credential, repo)` for this many seconds, so the requests of one clone, or repeated submodule fetches, validate once (`0` = validate every request) |
| `--auth-max-concurrent` | `GITCACHEPROXY_AUTH_MAX_CONCURRENT` | `32` | Max token-validation requests in flight; a check waits up to `--auth-timeout-seconds` for a slot, then fails with 503 (`0` = unlimited) |
| `--auth-allow-http` | `GITCACHEPROXY_AUTH_ALLOW_HTTP` | `false` | Provider modes: accept a plain `http://` validation endpoint, which sends client credentials in cleartext |
| `--upstream-timeout-seconds` | `GITCACHEPROXY_UPSTREAM_TIMEOUT_SECONDS` | `3600` | Total budget for each upstream Git operation, including attempts and retry backoff; at least 1 |
| `--fetch-ttl-seconds` | `GITCACHEPROXY_FETCH_TTL_SECONDS` | `10` | Skip upstream fetch if the last one started within this window (`0` = always fetch) |
| `--refresh-interval-seconds` | `GITCACHEPROXY_REFRESH_INTERVAL_SECONDS` | `0` | Background refresh round spacing; 0 disables it, otherwise at least 3600 |
| `--refresh-active-window-seconds` | `GITCACHEPROXY_REFRESH_ACTIVE_WINDOW_SECONDS` | `604800` | Only refresh mirrors requested within this window; at least 1 when enabled |
| `--max-concurrent-refreshes` | `GITCACHEPROXY_MAX_CONCURRENT_REFRESHES` | `4` | Maximum background fetches in flight; at least 1 when enabled |
| `--max-concurrent-requests` | `GITCACHEPROXY_MAX_CONCURRENT_REQUESTS` | `64` | Max concurrent in-flight requests; excess queue (`0` = unlimited) |
| `--max-concurrent-upload-packs` | `GITCACHEPROXY_MAX_CONCURRENT_UPLOAD_PACKS` | `0` | Max concurrent `git upload-pack` processes, held until each exits; bounds `pack-objects` memory. Clones waiting for a slot hold a `--max-concurrent-requests` slot (`0` = unlimited) |
| `--max-decoded-body-mb` | `GITCACHEPROXY_MAX_DECODED_BODY_MB` | `512` | Cap on a decoded upload-pack request body, in MiB (bounds memory / gzip bombs) |
Expand All @@ -33,6 +37,41 @@ Every flag has an environment-variable equivalent.
Endpoints: `/healthz`, `/readyz`, `/metrics` (see [Metrics](./metrics.md)).


## Periodic refresh

Refresh is disabled by default. When enabled, the first round starts after one
interval. Each round selects recently requested mirrors, most recent first.
Usage is kept only in memory and is reset on restart. Refresh never clones a
missing mirror, records client use, or promotes a mirror in the eviction LRU.
Successful background fetches schedule deferred size measurement and capacity
enforcement without changing LRU order. A TTL hit does not schedule measurement.
The active-window and concurrency settings have no effect when disabled.
The interval and its maximum backoff must fit in a monotonic deadline.
Disabled refresh neither records refresh usage nor locks refresh state on
requests. Library enabling counts only requests admitted after enabling.
Usage is recorded after successful cache preparation (ensure_fresh returning
Ok), including TTL hits, not after the full HTTP response or pack stream.
Failed, cancelled, and auth-rejected preparation leaves prior successful use
unchanged. Concurrent completions cannot move the timestamp backwards.

Rounds start every interval, measured from the previous round's start. At the
round deadline no new repository starts; running fetches finish. The next
round waits until both that deadline and all previous fetches have completed.
A deadline skip is not a fetch failure. Refresh shares the request fetch lock
and TTL. A request arriving during refresh waits for that fetch. Shutdown
cancels upstream operations and reaps child processes; library users must await
both request owners and the refresh handle.

Refresh uses only the static upstream auth header, or anonymous access when
none is configured. It never stores or reuses client credentials. An upstream
auth rejection blocks further refresh attempts for that mirror until a fetch
using the same server credential succeeds, or the process restarts. A client
credential success clears ordinary failure backoff but preserves this mark.
The first ordinary failure is eligible in the next scheduled round. Repeated
failures wait interval * 2^(failures - 1) after failure completion, capped at
32 intervals. Any successful upstream fetch clears
ordinary failure and backoff state. Request serving ignores refresh backoff.

## Reusing a cache after changing upstream

Mirrors are keyed by repo path under `--cache-root`, not by upstream URL.
Expand Down
57 changes: 56 additions & 1 deletion src/config.rs
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@

use std::fmt;
use std::path::PathBuf;
use std::time::Duration;

use tokio::time::Instant;

use anyhow::{Result, bail};
use clap::{Parser, ValueEnum};
Expand Down Expand Up @@ -221,6 +224,30 @@ pub struct Config {
#[arg(long, env = "GITCACHEPROXY_FETCH_TTL_SECONDS", default_value_t = 10)]
pub fetch_ttl_seconds: u64,

/// Pause between refresh round starts; 0 disables background refresh.
#[arg(
long,
env = "GITCACHEPROXY_REFRESH_INTERVAL_SECONDS",
default_value_t = 0
)]
pub refresh_interval_seconds: u64,

/// Refresh only mirrors requested within this many seconds.
#[arg(
long,
env = "GITCACHEPROXY_REFRESH_ACTIVE_WINDOW_SECONDS",
default_value_t = 604800
)]
pub refresh_active_window_seconds: u64,

/// Maximum background fetches in flight when refresh is enabled.
#[arg(
long,
env = "GITCACHEPROXY_MAX_CONCURRENT_REFRESHES",
default_value_t = 4
)]
pub max_concurrent_refreshes: usize,

/// Maximum number of requests handled concurrently, shared across all
/// connections. Excess requests queue until a slot frees. This bounds the
/// concurrent upstream clone/fetch work a burst can trigger (the slot is held
Expand Down Expand Up @@ -310,11 +337,39 @@ pub struct Config {

fn parse_upstream_timeout(value: &str) -> Result<u64, String> {
let seconds = value.parse::<u64>().map_err(|e| e.to_string())?;
crate::git::validate_upstream_timeout(std::time::Duration::from_secs(seconds))
crate::git::validate_upstream_timeout(Duration::from_secs(seconds))
.map_err(|e| e.to_string())?;
Ok(seconds)
}

impl Config {
/// Validate refresh options before starting background work.
pub fn validate_refresh(&self) -> Result<()> {
if self.refresh_interval_seconds != 0 {
if self.refresh_interval_seconds < 3600 {
bail!("--refresh-interval-seconds must be 0 or at least 3600");
}
let interval = Duration::from_secs(self.refresh_interval_seconds);
if interval
.checked_mul(32)
.and_then(|delay| Instant::now().checked_add(delay))
.is_none()
{
bail!(
"--refresh-interval-seconds and its maximum backoff must fit in a monotonic deadline"
);
}
if self.refresh_active_window_seconds == 0 {
bail!("--refresh-active-window-seconds must be at least 1 when refresh is enabled");
}
if self.max_concurrent_refreshes == 0 {
bail!("--max-concurrent-refreshes must be at least 1");
}
}
Ok(())
}
}

#[cfg(test)]
mod tests {
use super::*;
Expand Down
Loading
Loading