Add Gentoo distfiles proxy support with cache exclude feature

Introduce per-repository `exclude` config field and `"*"` wildcard
support in `suffixes` to cache all files except specified exclusions.
Add Gentoo repository config, e2e test, and documentation snippets.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: ganto

CHANGELOG.md

@@ -6,6 +6,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased](https://github.com/ganto/pkgproxy/commits/HEAD/)
 
+### Added
+
+- Per-repository `exclude` config field to prevent specific filenames or suffixes from being cached
+- Support caching Gentoo distfiles with `suffixes: ["*"]` wildcard and `exclude` list
+- Gentoo e2e test using `emerge --fetchonly` in a `gentoo/stage3` container
+
 ## [v0.1.2](https://github.com/ganto/pkgproxy/releases/tag/v0.1.2) - 2026-03-28
 
 ### Fixed

Makefile

@@ -107,7 +107,8 @@ $(if $(filter rockylinux,$(1)),TestRockyLinux,\
 $(if $(filter debian,$(1)),TestDebian,\
 $(if $(filter ubuntu,$(1)),TestUbuntu,\
 $(if $(filter archlinux,$(1)),TestArch,\
-$(error Unknown DISTRO: $(1). Use one of: fedora centos-stream almalinux rockylinux debian ubuntu archlinux)))))))))
+$(if $(filter gentoo,$(1)),TestGentoo,\
+$(error Unknown DISTRO: $(1). Use one of: fedora centos-stream almalinux rockylinux debian ubuntu archlinux gentoo))))))))))
 endef
 
 .PHONY: e2e

README.md

@@ -135,6 +135,13 @@ Can be used for any type of RPM-based enterprise distribution. E.g. `/etc/yum.re
 baseurl=http://<pkgproxy>:8080/epel/$releasever/Everything/$basearch/
 ```
 
+### Gentoo
+
+`/etc/portage/make.conf`:
+```
+GENTOO_MIRRORS="http://<pkgproxy>:8080/gentoo"
+```
+
 ### Fedora
 
 `/etc/yum.repos.d/fedora.repo` (adjust other repositories accordingly):
@@ -193,7 +200,7 @@ Run tests for a specific distribution and release:
 make e2e DISTRO=fedora RELEASE=42
 ```
 
-Supported `DISTRO` values: `fedora`, `centos-stream`, `almalinux`, `rockylinux`, `debian`, `ubuntu`, `archlinux`.
+Supported `DISTRO` values: `fedora`, `centos-stream`, `almalinux`, `rockylinux`, `debian`, `ubuntu`, `archlinux`, `gentoo`.
 
 When adding support for a new Linux distribution, corresponding e2e tests should be added as well.
 

configs/pkgproxy.yaml

@@ -56,6 +56,17 @@ repositories:
     mirrors:
       - https://mirror.init7.net/fedora/epel/
       - https://dl.fedoraproject.org/pub/epel/
+  gentoo:
+    suffixes:
+      - "*"
+    exclude:
+      - layout.conf
+      - timestamp.mirmon
+      - timestamp.dev-local
+    mirrors:
+      - https://mirror.init7.net/gentoo/
+      - https://pkg.adfinis-on-exoscale.ch/gentoo/
+      - https://distfiles.gentoo.org/
   fedora:
     suffixes:
       - .drpm

openspec/changes/gentoo-distfiles-proxy/tasks.md

@@ -1,28 +1,28 @@
 ## 1. Cache exclude feature
 
-- [ ] 1.1 Add `Exclude []string` field to `Repository` struct in `pkg/pkgproxy/repository.go`; in `validateConfig`, if a repository's `suffixes` list contains `"*"` alongside other entries, log a `slog.Warn` naming the repository and the redundant suffixes
-- [ ] 1.2 Add `Exclude []string` field to `CacheConfig` in `pkg/cache/cache.go`
-- [ ] 1.3 Pass `Exclude` from `Repository` into `CacheConfig` when constructing upstreams in `proxy.go`
-- [ ] 1.4 Update `IsCacheCandidate` in `cache.go` to: run exclude check first (exact name + suffix), then handle `"*"` wildcard, then existing suffix logic
-- [ ] 1.5 Add unit tests for `IsCacheCandidate` covering: wildcard match, exclude exact name, exclude suffix, exclude overrides wildcard, exclude overrides explicit suffix, no exclude field
-- [ ] 1.6 Add unit test for `validateConfig` covering: wildcard with redundant explicit suffixes emits a warning and returns no error
+- [x] 1.1 Add `Exclude []string` field to `Repository` struct in `pkg/pkgproxy/repository.go`; in `validateConfig`, if a repository's `suffixes` list contains `"*"` alongside other entries, log a `slog.Warn` naming the repository and the redundant suffixes
+- [x] 1.2 Add `Exclude []string` field to `CacheConfig` in `pkg/cache/cache.go`
+- [x] 1.3 Pass `Exclude` from `Repository` into `CacheConfig` when constructing upstreams in `proxy.go`
+- [x] 1.4 Update `IsCacheCandidate` in `cache.go` to: run exclude check first (exact name + suffix), then handle `"*"` wildcard, then existing suffix logic
+- [x] 1.5 Add unit tests for `IsCacheCandidate` covering: wildcard match, exclude exact name, exclude suffix, exclude overrides wildcard, exclude overrides explicit suffix, no exclude field
+- [x] 1.6 Add unit test for `validateConfig` covering: wildcard with redundant explicit suffixes emits a warning and returns no error
 
 ## 2. Gentoo repository config
 
-- [ ] 2.1 Add `gentoo` entry to `configs/pkgproxy.yaml` with `suffixes: ["*"]`, `exclude: [layout.conf, timestamp.mirmon, timestamp.dev-local]`, and mirrors: `mirror.init7.net`, `pkg.adfinis-on-exoscale.ch`, `distfiles.gentoo.org`
+- [x] 2.1 Add `gentoo` entry to `configs/pkgproxy.yaml` with `suffixes: ["*"]`, `exclude: [layout.conf, timestamp.mirmon, timestamp.dev-local]`, and mirrors: `mirror.init7.net`, `pkg.adfinis-on-exoscale.ch`, `distfiles.gentoo.org`
 
 ## 3. E2e test
 
-- [ ] 3.1 Add `assertNotCached` helper to `test/e2e/e2e_test.go` that asserts no file matching a given name exists anywhere under a cache subdirectory
-- [ ] 3.2 Write `test/e2e/test-gentoo.sh` shell script that: downloads `portage-latest.tar.xz` directly from `distfiles.gentoo.org`, unpacks it to `/var/db/repos/gentoo`, sets `GENTOO_MIRRORS` in `make.conf` to point at pkgproxy, runs `emerge --fetchonly app-text/tree`, then fetches `distfiles/layout.conf` via `wget` through the proxy
-- [ ] 3.3 Add `TestGentoo` to `test/e2e/e2e_test.go` using `docker.io/gentoo/stage3:latest`, mounting the script, asserting tree source archive is cached under `gentoo/distfiles/`, and asserting `layout.conf` is NOT cached using `assertNotCached`
+- [x] 3.1 Add `assertNotCached` helper to `test/e2e/e2e_test.go` that asserts no file matching a given name exists anywhere under a cache subdirectory
+- [x] 3.2 Write `test/e2e/test-gentoo.sh` shell script that: downloads `portage-latest.tar.xz` directly from `distfiles.gentoo.org`, unpacks it to `/var/db/repos/gentoo`, sets `GENTOO_MIRRORS` in `make.conf` to point at pkgproxy, runs `emerge --fetchonly app-text/tree`, then fetches `distfiles/layout.conf` via `wget` through the proxy
+- [x] 3.3 Add `TestGentoo` to `test/e2e/e2e_test.go` using `docker.io/gentoo/stage3:latest`, mounting the script, asserting tree source archive is cached under `gentoo/distfiles/`, and asserting `layout.conf` is NOT cached using `assertNotCached`
 
 ## 3b. Makefile
 
-- [ ] 3b.1 Add `gentoo → TestGentoo` mapping to the `distroToTest` macro in `Makefile` so `make e2e DISTRO=gentoo` works; add `gentoo` to the error message's list of valid values
+- [x] 3b.1 Add `gentoo → TestGentoo` mapping to the `distroToTest` macro in `Makefile` so `make e2e DISTRO=gentoo` works; add `gentoo` to the error message's list of valid values
 
 ## 4. Documentation
 
-- [ ] 4.1 Add Gentoo `make.conf` snippet to `README.md`
-- [ ] 4.2 Add Gentoo `make.conf` snippet to the HTTP landing page (`pkg/pkgproxy/landing.go` or template)
-- [ ] 4.3 Update `CHANGELOG.md` `[Unreleased]` section with new features
+- [x] 4.1 Add Gentoo `make.conf` snippet to `README.md`
+- [x] 4.2 Add Gentoo `make.conf` snippet to the HTTP landing page (`pkg/pkgproxy/landing.go` or template)
+- [x] 4.3 Update `CHANGELOG.md` `[Unreleased]` section with new features

pkg/cache/cache.go

@@ -56,6 +56,9 @@ type CacheConfig struct {
 
 	// List of file suffixes that will be cached
 	FileSuffixes []string
+
+	// List of filenames or suffixes that are never cached
+	Exclude []string
 }
 
 func New(cfg *CacheConfig) FileCache {
@@ -104,17 +107,30 @@ func (c *cache) GetFileSuffixes() []string {
 
 // Verifies if the given file URI is candidate to be cached
 func (c *cache) IsCacheCandidate(uri string) bool {
-	ca := false
-
 	name := utils.FilenameFromURI(uri)
+
+	// Exclude check first: exact name match or suffix match.
+	for _, entry := range c.config.Exclude {
+		if name == entry || strings.HasSuffix(name, entry) {
+			return false
+		}
+	}
+
+	// Wildcard: "*" in suffixes means cache everything (that wasn't excluded).
+	for _, suffix := range c.GetFileSuffixes() {
+		if suffix == "*" {
+			return true
+		}
+	}
+
+	// Existing suffix-match logic.
 	for _, suffix := range c.GetFileSuffixes() {
 		if strings.HasSuffix(name, suffix) {
-			ca = true
-			break
+			return true
 		}
 	}
 
-	return ca
+	return false
 }
 
 // Verifies if the file is already cached

pkg/cache/cache_test.go

@@ -187,6 +187,87 @@ func TestCommitTempFile(t *testing.T) {
 	})
 }
 
+func TestIsCacheCandidate(t *testing.T) {
+	tests := []struct {
+		name     string
+		suffixes []string
+		exclude  []string
+		uri      string
+		want     bool
+	}{
+		{
+			name:     "wildcard matches any file",
+			suffixes: []string{"*"},
+			uri:      "/repo/distfiles/ab/somefile.tar.xz",
+			want:     true,
+		},
+		{
+			name:     "exclude exact name blocks caching",
+			suffixes: []string{"*"},
+			exclude:  []string{"layout.conf"},
+			uri:      "/repo/distfiles/layout.conf",
+			want:     false,
+		},
+		{
+			name:     "exclude suffix blocks caching",
+			suffixes: []string{"*"},
+			exclude:  []string{".sig"},
+			uri:      "/repo/distfiles/ab/somefile.tar.xz.sig",
+			want:     false,
+		},
+		{
+			name:     "exclude overrides wildcard",
+			suffixes: []string{"*"},
+			exclude:  []string{"timestamp.mirmon"},
+			uri:      "/repo/distfiles/timestamp.mirmon",
+			want:     false,
+		},
+		{
+			name:     "exclude overrides explicit suffix",
+			suffixes: []string{".rpm"},
+			exclude:  []string{"verylarge.rpm"},
+			uri:      "/repo/verylarge.rpm",
+			want:     false,
+		},
+		{
+			name:     "no exclude field behaves normally",
+			suffixes: []string{".rpm"},
+			uri:      "/repo/package.rpm",
+			want:     true,
+		},
+		{
+			name:     "no exclude field rejects non-matching suffix",
+			suffixes: []string{".rpm"},
+			uri:      "/repo/readme.txt",
+			want:     false,
+		},
+		{
+			name:     "wildcard without exclude matches everything",
+			suffixes: []string{"*"},
+			uri:      "/repo/anything",
+			want:     true,
+		},
+		{
+			name:     "non-matching exclude does not affect caching",
+			suffixes: []string{"*"},
+			exclude:  []string{"layout.conf"},
+			uri:      "/repo/distfiles/ab/somefile.crate",
+			want:     true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			c := New(&CacheConfig{
+				BasePath:     "/cache",
+				FileSuffixes: tt.suffixes,
+				Exclude:      tt.exclude,
+			})
+			assert.Equal(t, tt.want, c.IsCacheCandidate(tt.uri))
+		})
+	}
+}
+
 func TestSaveToDiskStillWorks(t *testing.T) {
 	baseDir := t.TempDir()
 	c := New(&CacheConfig{BasePath: baseDir})

pkg/pkgproxy/landing.go

@@ -82,6 +82,9 @@ var snippetFuncs = map[string]func(string) string{
 			"# metalink=https://mirrors.fedoraproject.org/metalink?repo=epel-$releasever&arch=$basearch\n" +
 			"baseurl=http://" + addr + "/epel/$releasever/Everything/$basearch/"
 	},
+	"gentoo": func(addr string) string {
+		return "GENTOO_MIRRORS=\"http://" + addr + "/gentoo\""
+	},
 	"fedora": func(addr string) string {
 		return "[fedora]\n" +
 			"# metalink=https://mirrors.fedoraproject.org/metalink?repo=fedora-$releasever&arch=$basearch\n" +

pkg/pkgproxy/proxy.go

@@ -134,6 +134,7 @@ func New(config *PkgProxyConfig) PkgProxy {
 			cache: cache.New(&cache.CacheConfig{
 				BasePath:     config.CacheBasePath,
 				FileSuffixes: config.RepositoryConfig.Repositories[repo].CacheSuffixes,
+				Exclude:      config.RepositoryConfig.Repositories[repo].Exclude,
 			}),
 			mirrors: mirrors,
 			retries: retries,

pkg/pkgproxy/repository.go

@@ -5,6 +5,7 @@ package pkgproxy
 import (
 	"errors"
 	"fmt"
+	"log/slog"
 	"os"
 	"path/filepath"
 	"regexp"
@@ -22,6 +23,7 @@ type RepoConfig struct {
 
 type Repository struct {
 	CacheSuffixes []string `yaml:"suffixes"`
+	Exclude       []string `yaml:"exclude,omitempty"`
 	Mirrors       []string `yaml:"mirrors"`
 	Retries       int      `yaml:"retries,omitempty"`
 }
@@ -62,6 +64,20 @@ func validateConfig(config *RepoConfig) error {
 		if repoConfig.Mirrors == nil {
 			return fmt.Errorf("missing required key for repository '%s': mirrors", handle)
 		}
+		// Warn if suffixes contains "*" alongside other entries (redundant).
+		hasWildcard := false
+		var redundant []string
+		for _, s := range repoConfig.CacheSuffixes {
+			if s == "*" {
+				hasWildcard = true
+			} else {
+				redundant = append(redundant, s)
+			}
+		}
+		if hasWildcard && len(redundant) > 0 {
+			slog.Warn("repository has wildcard suffix '*' with redundant explicit suffixes",
+				"repository", handle, "redundant_suffixes", redundant)
+		}
 	}
 	return nil
 }