Skip to content
Closed
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
5 changes: 3 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,8 @@ Every flag has an environment-variable equivalent; the full reference is in
to upstream.
- `--serve-token` / `--auth-provider`: how clients authenticate to the proxy.
- `--cache-max-mb`: cap on-disk cache size (LRU eviction; `0` = unlimited).
- `--max-stale-seconds`: opt in to serving cached refs while a background fetch
refreshes them (see [Stale serving](./docs/configuration.md#stale-serving)).

## Metrics

Expand Down Expand Up @@ -129,8 +131,7 @@ 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).
- Scheduled refresh. Background refresh is triggered by requests.

**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
4 changes: 3 additions & 1 deletion chart/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,8 +114,10 @@ pointing at the Service.
| `clientAuth.signingKey.existingSecret` | `""` | Secret with the HMAC key signing LFS download grants; empty = a random key per pod |
| `clientAuth.signingKey.key` | `signing-key` | Key in that Secret |
| `config.fetchTtlSeconds` | `10` | Skip upstream fetch if refreshed within this window (`0` = always) |
| `config.maxStaleSeconds` | `0` | Maximum age of cached refs served while refreshing (`0` = disabled) |
| `config.maxBackgroundFetches` | `4` | Maximum concurrent background refreshes (at least `1`) |
| `config.cacheMaxMb` | `0` | Cap on on-disk cache, MiB; evicts LRU idle mirrors (`0` = unlimited) |
| `config.maxConcurrentRequests` | `64` | Max concurrent in-flight requests (`0` = unlimited) |
| `config.maxConcurrentRequests` | `64` | Request capacity; stale mode isolates local/upstream work and rejects overload (see [Stale serving](../docs/configuration.md#stale-serving)) |
| `config.maxDecodedBodyMb` | `512` | Cap on a decoded upload-pack request body, MiB |
| `config.logLevel` | `info` | Log filter directive |
| `config.logFormat` | `text` | `text` or `json` |
Expand Down
4 changes: 4 additions & 0 deletions chart/templates/deployment.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,10 @@ spec:
value: /var/cache/git-cache-proxy
- name: GITCACHEPROXY_FETCH_TTL_SECONDS
value: {{ .Values.config.fetchTtlSeconds | quote }}
- name: GITCACHEPROXY_MAX_STALE_SECONDS
value: {{ .Values.config.maxStaleSeconds | quote }}
- name: GITCACHEPROXY_MAX_BACKGROUND_FETCHES
value: {{ .Values.config.maxBackgroundFetches | quote }}
- name: GITCACHEPROXY_CACHE_MAX_MB
value: {{ .Values.config.cacheMaxMb | quote }}
- name: GITCACHEPROXY_MAX_CONCURRENT_REQUESTS
Expand Down
8 changes: 6 additions & 2 deletions chart/values.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -81,12 +81,16 @@ config:
# Skip the upstream fetch on info/refs if the mirror was refreshed within this
# many seconds; coalesces bursts of clones for one repo. 0 = always fetch.
fetchTtlSeconds: 10
# Serve cached refs for at most this age while refreshing. 0 disables it.
maxStaleSeconds: 0
# Maximum simultaneous background refreshes, at least 1.
maxBackgroundFetches: 4
# Cap on total on-disk mirror cache, in MiB; evicts least-recently-used idle
# mirrors when exceeded. 0 = unlimited (no eviction). Set this whenever the
# cache volume is bounded.
cacheMaxMb: 0
# Max concurrent in-flight requests; excess queue. Bounds the upstream
# clone/fetch a burst can trigger. 0 = unlimited.
# Request capacity: strict mode queues; stale mode isolates local and
# upstream work and rejects overload. See docs/configuration.md (Stale serving) for zero-limit behavior.
maxConcurrentRequests: 64
# Cap on a decoded upload-pack request body, in MiB (bounds memory, defuses a
# gzip bomb). Caps only the negotiation request, never the streamed packfile.
Expand Down
25 changes: 25 additions & 0 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,6 +114,31 @@ linked. Cached objects share the `--cache-max-mb` budget and LRU eviction with t
git mirrors. No configuration is needed: LFS is served on the same endpoints the git
client already routes through the proxy.

### Stale serving

With `--max-stale-seconds` set, the TTL-expired path changes from "fetch, then
serve" to "serve, and fetch in the background" (see
[Stale serving](./configuration.md#stale-serving) for the knobs).

- A request checks the mirror's age. Within the bound it serves from the mirror
and, if the TTL has passed, starts one coalesced background fetch. Past the
bound it waits for a clone or fetch, which must finish within the bound.
- Age is the start of the last successful full-ref refresh, persisted in
`proxy-refresh.json` so a restart does not reset it. The record is trusted only
when it matches the repository, configured upstream and directory identity;
directory mtime is not evidence of success. A failed refresh or a SHA-only
backfill never renews age.
- Body decoding, freshness inspection, mandatory upstream work and local delivery
admit through separate lanes, so slow upstream work cannot take every local
slot. A full lane returns 503 rather than queueing another expensive owner.
- An upload that waited for a slot rechecks identity and age right before Git
starts. A stream already started may finish after the refs expire.
- Fetch-triggered automatic maintenance is disabled so a refresh does not delete
objects just advertised. Active requests are protected from eviction until their
Git process exits, but nothing pins an object between an advertisement and the
following upload-pack, so eviction or external maintenance in that gap can
remove it. A missing SHA is fetched on demand when upstream allows it.

### Cache management

The cache is self-managing. Mirrors are created on first request, and with
Expand Down
29 changes: 28 additions & 1 deletion docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,9 @@ Every flag has an environment-variable equivalent.
| `--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 |
| `--fetch-ttl-seconds` | `GITCACHEPROXY_FETCH_TTL_SECONDS` | `10` | Skip upstream fetch if the last one started within this window (`0` = always fetch) |
| `--max-concurrent-requests` | `GITCACHEPROXY_MAX_CONCURRENT_REQUESTS` | `64` | Max concurrent in-flight requests; excess queue (`0` = unlimited) |
| `--max-stale-seconds` | `GITCACHEPROXY_MAX_STALE_SECONDS` | `0` | Maximum age of cached refs served during background refresh (`0` = disabled) |
| `--max-background-fetches` | `GITCACHEPROXY_MAX_BACKGROUND_FETCHES` | `4` | Maximum concurrent background refreshes (at least `1`) |
| `--max-concurrent-requests` | `GITCACHEPROXY_MAX_CONCURRENT_REQUESTS` | `64` | Request capacity: strict mode queues; stale mode isolates local and upstream work and rejects overload (see [Stale serving](#stale-serving) for `0`) |
| `--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) |
| `--cache-max-mb` | `GITCACHEPROXY_CACHE_MAX_MB` | `0` | Cap on total on-disk mirror cache, in MiB; evicts least-recently-used idle mirrors when exceeded (`0` = unlimited, no eviction) |
Expand All @@ -43,3 +45,28 @@ their recorded `origin` URL is not rewritten. Normal fetch TTL rules still apply
Old cached objects and local want-by-SHA pins remain and can still be served.
Changing the fetch URL is not a security-domain migration. When switching trust
domains, use a fresh or separate cache root, including for LFS objects.

## Stale serving

By default a request after the fetch TTL waits for an upstream fetch. With a
positive `--max-stale-seconds`, an existing mirror serves its cached refs
instead, while at most one background fetch per repository updates it. A cold
mirror still needs a complete clone first.

- **Age** is measured from the start of the last successful clone or fetch. Past
`--max-stale-seconds` a request waits for a refresh, or fails if that fails.
- **Restarts** keep the age: a successful full-ref refresh records its start time
in `proxy-refresh.json` inside the mirror. A missing, invalid, oversized or
future-dated record, or one that does not match the repository, upstream and
mirror directory, forces a refresh. This assumes a correct wall clock across
downtime and one proxy process per cache root.
- **Retries**: background attempts are limited globally by
`--max-background-fetches` and retried no sooner than the fetch TTL, or one
second, after the previous attempt completes.
- **Overload**: `--max-concurrent-requests` bounds body decoding, freshness
inspection and local serving in separate lanes. Mandatory upstream work has at
most `max(1, N - 1)` slots for limit `N`; with `N = 0` only that lane stays
bounded, by `--max-background-fetches`. A full lane returns 503 instead of
queueing. The strict default keeps its queueing behavior.

See [Architecture](./architecture.md#stale-serving) for how a request is handled.
4 changes: 4 additions & 0 deletions docs/security.md
Original file line number Diff line number Diff line change
Expand Up @@ -187,6 +187,10 @@ explicit before you expose it:
Each junk credential still costs one call, and failed logins count against
the proxy's egress IP at the git host: rate-limit unauthenticated clients at
the ingress.
- **Stale serving exposes unreachable objects.** With `--max-stale-seconds` set,
a client that can read a mirror can request any object already in it by SHA,
including one no longer reachable from an advertised ref (for example after a
force-push or branch deletion upstream), until it is garbage collected or the mirror is evicted.
- **Read-only.** Only `git-upload-pack` (clone/fetch) is served; `git-receive-pack`
(push) is refused and upstream is only ever pulled from, never written.

38 changes: 31 additions & 7 deletions src/config.rs
Original file line number Diff line number Diff line change
Expand Up @@ -215,12 +215,19 @@ pub struct Config {
#[arg(long, env = "GITCACHEPROXY_FETCH_TTL_SECONDS", default_value_t = 10)]
pub fetch_ttl_seconds: u64,

/// 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
/// for the handler, then released before the packfile streams, so it caps
/// setup rather than in-flight streaming; see `max_concurrent_upload_packs`).
/// `0` = unlimited. Complementary to any ingress-level rate limiting.
/// Maximum age of cached refs served while refreshing; 0 disables this mode.
#[arg(long, env = "GITCACHEPROXY_MAX_STALE_SECONDS", default_value_t = 0)]
pub max_stale_seconds: u64,

/// Maximum number of concurrent background refreshes.
#[arg(long, env = "GITCACHEPROXY_MAX_BACKGROUND_FETCHES", default_value_t = 4, value_parser = positive_usize)]
pub max_background_fetches: usize,

/// Request capacity shared across connections. Strict mode queues excess
/// handlers. Stale mode bounds decoding, inspection and local serving
/// independently and rejects overload; mandatory upstream work has at most
/// max(1, capacity - 1) slots. Zero disables local limits; stale upstream
/// preparation still uses max_background_fetches as its bound.
#[arg(
long,
env = "GITCACHEPROXY_MAX_CONCURRENT_REQUESTS",
Expand All @@ -231,7 +238,8 @@ pub struct Config {
/// Maximum number of `git upload-pack` processes at once, to bound
/// `pack-objects` memory on large repos. A slot frees when the process exits,
/// so it covers the streamed pack. Excess clones queue while holding a
/// `max_concurrent_requests` slot, so a full cap can also block `info/refs`.
/// `max_concurrent_requests` slot. In stale mode it stays held until Git is
/// reaped; a full cap can also return overload for `info/refs`.
/// `0` = unlimited.
#[arg(
long,
Expand Down Expand Up @@ -302,6 +310,14 @@ pub struct Config {
pub log_format: LogFormat,
}

fn positive_usize(value: &str) -> Result<usize, String> {
let value: usize = value.parse().map_err(|_| "expected a positive integer")?;
if value == 0 || value > tokio::sync::Semaphore::MAX_PERMITS {
return Err("value is outside the semaphore range".into());
}
Ok(value)
}

#[cfg(test)]
mod tests {
use super::*;
Expand Down Expand Up @@ -350,4 +366,12 @@ mod tests {
.to_string();
assert!(err.contains("--upstream-auth-header"), "{err}");
}

#[test]
fn background_fetch_limit_must_be_positive_and_fit_a_semaphore() {
assert_eq!(positive_usize("1").unwrap(), 1);
assert!(positive_usize("0").is_err());
assert!(positive_usize("invalid").is_err());
assert!(positive_usize(&usize::MAX.to_string()).is_err());
}
}
Loading
Loading