What can a proxy repository still serve your builds when the public registry it caches goes down on release day?
answer
- filled on demand, not mirrored
- what was fetched before survives
- stale metadata beats no metadata
- assumed offline after repeated errors
- never-requested versions fail
basics
~20 sA proxy repository can still serve whatever it already cached: artifact files and, in products such as Artifactory and Harbor, its last copy of the metadata. Anything no build requested through it was never stored, so it fails until the upstream returns.
solid answer
~50 sA proxy repository caches **on demand**: it stores only what some build already requested through it. When the upstream goes down, cached artifact files keep being served, and so does the last cached copy of metadata such as `maven-metadata.xml` or an npm packument, now stale. Anything never requested through it fails, including a version published upstream yesterday. Artifactory documents the mechanics: after a connection error it retries up to 10 times, then treats the remote repository as *assumed offline* for the Assumed Offline Period (default 300 seconds) and serves cached copies; a metadata refresh that exceeds the Metadata Retrieval Cache Timeout returns the previous metadata. Harbor's proxy cache project likewise serves the cached image when the target registry is unreachable. So outage resilience is decided beforehand: every build goes through the proxy, and cleanup must not evict what releases need.
go deeper
Recall that a proxy repository caches only what was requested through it, that cached content keeps being served when the upstream is down, and that never-requested versions fail.
Explain the two kinds of cached content, artifact files and metadata, why stale metadata is served during an outage instead of nothing, and how the assumed-offline window and its retries work.
Show you prepare before the outage: every build through the proxy, cleanup that does not evict release-critical dependencies, hosted copies of what cannot be lost, and the Offline switch when an upstream hangs.
Weigh how much outage tolerance the organisation needs against storage and operating cost: long cache retention, hosted copies of critical dependencies and a fully disconnected repository each buy more independence for more work.
## What a proxy repository actually holds A **proxy repository** sits between your builds and a public registry such as Maven Central, the npm registry, PyPI or Docker Hub. Each product has its own word for it: Artifactory calls it a *remote* repository, Nexus Repository a *proxy* repository, and Harbor a *proxy cache project*. In every case it is a cache filled **on demand**, not a copy of the registry. Artifactory's documentation says so directly: a remote repository acts as a proxy, not as a mirror, and artifacts are fetched and cached only when a client requests them. That one fact decides almost everything about an outage. The proxy holds two kinds of content: - **Artifact files**: the JAR, the npm tarball, the wheel, the image layer. A released version's file is expected never to change, so a cached copy stays valid. - **Metadata**: the documents that list what exists, such as `maven-metadata.xml`, an npm packument with its `dist-tags`, a PyPI simple index page, or the manifest a container tag points to. These change whenever the upstream publishes, so the proxy refreshes them on a timer. ## What happens when the upstream stops answering Artifactory documents the sequence, and it is a good model of the idea: 1. A request arrives for something not cached, or for metadata whose cache period has run out, so the remote repository calls the upstream. 2. The call fails. Artifactory retries, with the interval growing each time, up to 10 times. 3. If every retry fails, the repository is treated as **assumed offline** for the *Assumed Offline Period* (default 300 seconds). During that window it stops calling the dead upstream and serves the stale copies it already holds. 4. When a metadata refresh does not finish within the *Metadata Retrieval Cache Timeout* (default 60 seconds), the previous metadata is returned to the client instead. 5. After the offline period an online check runs; if the upstream is back, normal caching resumes. Harbor's proxy cache project describes the same choice for container images: if the target registry is not reachable, the proxy cache project serves the cached image. ## What still works and what fails | Request during the outage | Outcome | |---|---| | A version an earlier build downloaded through the proxy | Served from the cache | | Metadata the proxy cached earlier | Served stale, without versions published since | | A version published upstream but never requested through the proxy | Fails, because it was never stored | | A package no build has ever asked for | Fails | | A cached version that a cleanup run removed | Fails until the upstream returns | The stale-metadata row deserves attention. A build that resolves "the newest matching version" chooses from the cached version list, so during the outage it may quietly build against an older version than it would have the day before. On release day that is usually what you want; it is still worth knowing it happened. ## Preparing before the outage, not during it - **Route every build through the proxy**, release builds included. A build that talks to the public registry directly gets no protection, and it never warms the cache for anyone else. - **Watch what cleanup evicts.** Artifactory's *Unused Artifacts Cleanup Period* removes cached artifacts nobody has used for a while; leaving the field empty keeps them indefinitely. Evicting a release-critical dependency the week before an outage turns a cache hit into a failure. - **Use the Offline switch deliberately.** Artifactory's per-repository *Offline* checkbox makes a remote repository use only what is already cached, with no further fetch attempts. That helps when the upstream hangs rather than refuses, so builds stop waiting on timeouts. - **Copy what you cannot lose.** For the few dependencies a release cannot ship without, a copy deployed into a hosted repository no longer depends on the remote cache surviving. ## Common misconceptions - "The proxy mirrors the registry." It stores only what was requested through it. - "An outage switches the proxy off." Cached content keeps flowing; only uncached requests fail. - "Clearing the cache will help." In Artifactory, a zap only marks metadata as expired, and when the refresh cannot reach the upstream the previous copy is served, so it gains nothing; actually deleting cached files during an outage throws away the only copy you have.
- What does Artifactory's Offline checkbox on a remote repository change during an outage?It stops that remote repository contacting its upstream: only artifacts already in its cache are used, and no further fetch attempts are made. That turns slow timeouts into fast answers when the upstream hangs instead of refusing connections, at the price of seeing nothing new until you clear the checkbox. Global Offline Mode does the same for every remote repository at once.
- How do you make sure the cache already holds what a release needs before the upstream fails?Send every build, CI and release alike, through the proxy so dependencies are cached as a side effect of normal work. Keep the unused-artifact cleanup period long, or empty for indefinite retention, on the remote repositories releases depend on. Deploy copies of the few dependencies a release cannot ship without into a hosted repository, which no upstream outage or remote-cache cleanup removes.
A proxy repository is like a corner shop that restocks only items customers have asked for before: when the wholesaler closes, the shelves still hold earlier orders, but nothing nobody ever bought.
- A proxy repository mirrors the whole public registry, so an outage changes nothing.
- Once the upstream is down, the proxy stops serving even what it has cached.
- Clearing the proxy's cache during an outage forces a fresh, current download.
- Deleting cached artifacts is harmless because the proxy can always fetch them again.