A proxy repository is a caching mirror of an external registry: clients always talk to Galleon, and Galleon downloads artifacts from the external registry on demand and stores them locally.
How a request is handled
A request to a proxy repository is handled as follows:
- the artifact is in the cache and its retention period has not expired — Galleon serves it from the cache, the external registry is not involved;
- the period has expired — Galleon asks the external registry whether the artifact has changed. If it has not, the client gets the cached copy and the retention period starts over; if it has, Galleon downloads the new version, replaces the cache with it, and serves it to the client;
- the artifact is not in the cache — Galleon downloads it from the external registry, stores it, and serves it to the client.
When the external registry is unreachable
As long as a copy is in the cache, clients receive it — even if the retention period has expired and the freshness check failed. Only requests for something absent from the cache fail.
If the failures persist and automatic blocking is enabled in the repository settings, Galleon stops contacting the registry and periodically checks whether it has recovered; the cache keeps being served all that time. Outbound requests can also be paused manually — then the repository works from the cache only.
The current connection state is shown in the “Remote” column of the repository list; the values of that column are described in Repositories of the Administration guide.
Retention periods
The cache distinguishes two kinds of data:
- Content — the artifacts themselves: package archives, image layers. The content of such files usually never changes for a given version.
- Metadata — version lists, indexes, and package descriptors that the external registry updates as new versions are released.
The periods are configured per repository with two parameters:
contentMaxAge for the content and metadataMaxAge for the metadata.
Both accept three kinds of values:
- A positive number — the retention period in minutes. The default is 1440, that is a day: during that time requests are served from the cache, after it Galleon asks the external registry whether the artifact has changed.
0— check the external registry on every request. The content comes from the cache if the registry answers “not modified”, but every request waits for the external registry.-1— cache indefinitely and never contact the external registry again. Suitable for immutable content and for isolated networks.
Which files belong to which class:
| Format | Metadata (metadataMaxAge) | Content (contentMaxAge) |
|---|---|---|
| Docker (OCI) | Tags: which image a tag points to, the tag list | — (manifests and layers are immutable, see below) |
| Maven | maven-metadata.xml and its checksums | Build artifacts (.jar, .pom) and their checksums |
| Go | The version list and the latest-version request | — (version files are immutable, see below) |
| npm | The package descriptor | Version tarballs |
| PyPI | The project page in the index | Distribution files |
| RubyGems | The Compact Index files (version and name lists) | Gem files |
| Cargo | The crate index | Crate files |
| raw | — | All files |
Files requested by checksum are cached indefinitely regardless of both
settings: their content cannot change. These are Go module version files
and the layers and manifests of container images.
For images, metadataMaxAge sets how often Galleon checks with the external
registry whether a tag points to another image.
For Maven repositories with the RELEASE version policy, content is cached indefinitely by default: release versions are never republished.
When the retention period expires, the artifact is not removed from the cache: Galleon merely checks its freshness on the next request. Cached content can be evicted with a cleanup policy — it deletes components by age, by how long ago they were downloaded, and by path (Cleanup policies).
The cache can also be dropped without waiting for the periods to expire — with the
“Invalidate cache” button in the settings of any proxy repository.
The content is not deleted but marked stale:
every following request is first checked against the external registry and only then served.
The negative cache is cleared along with it.
The mark applies under any retention period, -1 included;
content requested by checksum is not affected.
Negative caching
“Not found” responses from the external registry are cached as well — for 15 minutes by default. This protects the external registry from a stream of repeated requests to nonexistent paths.
If a package has just been published to the external registry but Galleon responds that it does not exist, the negative cache is probably in effect: it expires on its own, after 15 minutes by default, and it can be dropped at once with the “Invalidate cache” button in the repository settings.
Requests to the external registry
Transient errors of the external registry (overload, network failures) are handled with retries and increasing backoff; the number of attempts is configured in the repository settings.
If the external registry requires authentication, a private container registry for example, the credentials are configured in the same place, the proxy repository settings.