Adopt golib/pg for migrations and pool construction

artifactapi's schema was a ~180-line inline DDL blob re-executed on every
start, growing an ALTER TABLE ... IF NOT EXISTS line per change with nothing
recording what had run. golib/pg already owns that mechanic for the estate, so
move the SQL into a versioned, embedded set and let the library apply it.

- Depend on git.unkin.net/unkin/golib v0.1.0.
- Move the DDL verbatim to migrations/0001_init.sql, embedded via the new
  migrations package, and build the pool with pg.NewMigrated (LockName
  "artifactapi-migrations"). The runner adds a cluster-wide advisory lock the
  old blob never took, so replicas starting together queue instead of racing
  each other through the DDL.
- The live database has the schema but no schema_migrations, so its first start
  on this build re-runs 0001. Every statement is IF NOT EXISTS-guarded, so that
  run is a no-op landing only the tracking row; a container-backed test drops
  the row from a migrated database and asserts exactly that, and a static guard
  keeps future migrations additive and idempotent.
- Keep config.DatabaseDSN as the DSN source rather than pg.DSNFromEnv: the
  variable names match, but golib has no default user or database name, and
  artifactapi documents and ships DBUSER/DBNAME defaults of "artifacts". The
  deployed env var contract is unchanged.
- Guard the embedded set against migrations/ and pin the derived advisory key,
  so neither can drift unnoticed.
- Plumb GOPRIVATE=git.unkin.net for the first cross-repo Go dependency:
  exported by the Makefile, set in the Dockerfile and the woodpecker Go steps,
  documented in the README.

.woodpecker/pre-commit.yaml

@@ -6,6 +6,9 @@ steps:
     image: git.unkin.net/unkin/almalinux9-gobuilder:20260606
     commands:
       - uvx pre-commit run --all-files
+    environment:
+      # golib lives on Gitea; skip the public proxy/sum db.
+      GOPRIVATE: git.unkin.net
     backend_options:
       kubernetes:
         resources:

.woodpecker/test.yaml

@@ -6,3 +6,6 @@ steps:
     image: golang:1.25
     commands:
       - go test -race -count=1 ./pkg/... ./internal/...
+    environment:
+      # golib lives on Gitea; skip the public proxy/sum db.
+      GOPRIVATE: git.unkin.net

Dockerfile

@@ -4,6 +4,10 @@ RUN apk add --no-cache git
 
 WORKDIR /build
 
+# golib is fetched straight from Gitea; the public proxy and sum db have no
+# view of git.unkin.net modules.
+ENV GOPRIVATE=git.unkin.net
+
 COPY go.mod go.sum ./
 RUN go mod download
 

Makefile

@@ -6,6 +6,11 @@ VERSION ?= $(shell git describe --tags --always --dirty 2>/dev/null || echo "0.0
 GO_VERSION_REQUIRED := 1.23
 GO_VERSION_ACTUAL := $(shell go version | sed 's/go version go\([0-9]*\.[0-9]*\).*/\1/')
 
+# git.unkin.net modules (golib) are fetched straight from Gitea, never via the
+# public proxy or sum db, which have no view of them. Exported here rather than
+# written with `go env -w`, so a fresh checkout needs no machine-local setup.
+export GOPRIVATE := git.unkin.net
+
 check-go:
 	@if [ "$$(printf '%s\n%s' "$(GO_VERSION_REQUIRED)" "$(GO_VERSION_ACTUAL)" | sort -V | head -1)" != "$(GO_VERSION_REQUIRED)" ]; then \
 		echo "ERROR: Go >= $(GO_VERSION_REQUIRED) required, found $(GO_VERSION_ACTUAL)"; exit 1; \

README.md

@@ -321,6 +321,28 @@ S3/MinIO    ─── content-addressable blob storage (blobs/sha256/{hash})
 
 S3 client supports MinIO, Ceph RGW, and AWS S3 (via minio-go).
 
+### Schema migrations
+
+The SQL schema lives in `migrations/` as numbered `.sql` files, embedded into
+the binary and applied at startup before the server listens, so there is no
+mirrored copy of the schema in the deployment to drift out of sync.
+
+The runner is [`golib/pg`](https://git.unkin.net/unkin/golib)'s `pg.NewMigrated`
+— artifactapi owns the SQL, the shared library owns the mechanics.
+
+Each start takes `pg_advisory_lock` on a fixed key (FNV-1a/64 of the lock name
+`artifactapi-migrations`), creates `schema_migrations` (`version`, `applied_at`)
+if missing, and applies every embedded file whose filename is not yet recorded —
+in lexical (version) order, each file's SQL and its tracking row in one
+transaction — then unlocks. Replicas starting together queue on the lock and
+then find nothing to do.
+
+A file absent from `schema_migrations` is re-run even when the database already
+has the schema, which is how a database migrated by the old untracked inline DDL
+picks `0001_init.sql` up: the statements are `IF NOT EXISTS`-guarded, so the
+re-run is a no-op that only lands the tracking row. New migrations must stay
+additive and idempotent for the same reason; a test enforces it.
+
 ## Environment Variables
 
 | Variable | Default | Description |
@@ -331,6 +353,7 @@ S3 client supports MinIO, Ceph RGW, and AWS S3 (via minio-go).
 | `DBUSER` | `artifacts` | PostgreSQL user |
 | `DBPASS` | | PostgreSQL password |
 | `DBNAME` | `artifacts` | PostgreSQL database |
+| `DBSSL` | `disable` | PostgreSQL `sslmode` |
 | `REDIS_URL` | `redis://localhost:6379` | Redis URL |
 | `MINIO_ENDPOINT` | `localhost:9000` | S3 endpoint |
 | `MINIO_ACCESS_KEY` | | S3 access key |
@@ -358,6 +381,22 @@ make lint        # golangci-lint + go vet
 make fmt         # gofmt + goimports
 ```
 
+### `GOPRIVATE`
+
+artifactapi depends on `git.unkin.net/unkin/golib`, which is served by Gitea and
+is unknown to `proxy.golang.org` / `sum.golang.org`. Module resolution therefore
+needs:
+
+```
+export GOPRIVATE=git.unkin.net
+```
+
+The `Makefile` exports it for every target, and the `Dockerfile` and the
+woodpecker Go steps set it themselves, so `make build|test|lint` and CI work on
+a clean checkout. Only bare `go` commands run outside `make` need it in your
+shell — set it there (or in your shell profile) rather than with `go env -w`,
+which is machine state this repo cannot carry.
+
 ### TUI
 
 ```bash

docker-compose.e2e.yml

@@ -9,6 +9,18 @@ services:
     # No host port needed: only the artifactapi container talks to it, and the
     # tests compare served bytes against the on-disk fixtures.
 
+  # Two constant-body upstreams for the multi-base_url suite: each returns a
+  # distinct, upstream-identifying body for any path, so round-robin
+  # distribution across a two-mirror remote is directly observable.
+  mockupstreama:
+    image: nginx:alpine
+    volumes:
+      - ./e2e-docker/mirror-conf/a.conf:/etc/nginx/conf.d/default.conf:ro,z
+  mockupstreamb:
+    image: nginx:alpine
+    volumes:
+      - ./e2e-docker/mirror-conf/b.conf:/etc/nginx/conf.d/default.conf:ro,z
+
   artifactapi:
     # The host port is set via ARTIFACTAPI_PORT (see scripts/docker-e2e.sh),
     # defaulting to 8000; the e2e run uses 8001 to avoid colliding with a
@@ -16,3 +28,7 @@ services:
     depends_on:
       mockupstream:
         condition: service_started
+      mockupstreama:
+        condition: service_started
+      mockupstreamb:
+        condition: service_started

e2e-docker/README.md

@@ -30,6 +30,18 @@ already-running stack.
   index), rpm (real package + **automatic repodata** generation).
 - **Virtual repositories** — pypi simple-index merge and helm `index.yaml` merge
   across two members.
+- **Mirrorlist** — an rpm remote with a `mirrorlist` of extra upstream mirrors
+  (pool = `base_url` + `mirrorlist`): round-robin distribution across both mirrors
+  (constant-body `mockupstreama` / `mockupstreamb`), failover past a dead primary,
+  no-mirrorlist regression, and a real `dnf` (stock `rockylinux:9` container)
+  `makecache` + `install` through a two-mirror rpm remote whose `base_url` is dead
+  — a dead mirror must not break the client.
+- **Mirror strategy (`least_conn`)** — a `mirror_strategy: least_conn` rpm remote
+  over the two constant-body mirrors exercises the least-connections selection
+  path end-to-end (both mirrors serve, all requests succeed), plus a real `dnf`
+  install through a `least_conn` remote with a dead primary (failover unchanged).
+  The precise least-loaded pick is asserted deterministically in the proxy unit
+  test, since an in-flight-skew assertion over HTTP is timing-sensitive.
 
 ## Fixtures
 

e2e-docker/fixtures/rpm-mirror/repodata/repomd.xml

@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<repomd xmlns="http://linux.duke.edu/metadata/repo" xmlns:rpm="http://linux.duke.edu/metadata/rpm">
+  <revision>1786573032</revision>
+  <data type="primary">
+    <checksum type="sha256">d82f717e4da1afe96b8e7857de9e852f5785c0d75734e50d0f8afdcbc6261b08</checksum>
+    <open-checksum type="sha256">3345bb631380ae6c0620fe2a29cf7dff2ed4e28c5cb06c91e8a1628ba1979bcb</open-checksum>
+    <location href="repodata/d82f717e4da1afe96b8e7857de9e852f5785c0d75734e50d0f8afdcbc6261b08-primary.xml.gz"/>
+    <timestamp>1786573032</timestamp>
+    <size>631</size>
+    <open-size>1192</open-size>
+  </data>
+  <data type="filelists">
+    <checksum type="sha256">daa313cc5eeb7df556e1d4885d7701b10b9f012f436ef239fa46827f966222be</checksum>
+    <open-checksum type="sha256">648bd0ce00fda09abbc6e9c3ff3278518a76f258576ac24cd10c12e41e0e5bd7</open-checksum>
+    <location href="repodata/daa313cc5eeb7df556e1d4885d7701b10b9f012f436ef239fa46827f966222be-filelists.xml.gz"/>
+    <timestamp>1786573032</timestamp>
+    <size>256</size>
+    <open-size>338</open-size>
+  </data>
+  <data type="other">
+    <checksum type="sha256">8510c74a6f288828bbc92abee5d0d8ae9687d3c31a2579ea95e31a4c3a320d85</checksum>
+    <open-checksum type="sha256">c42cfd3843e9c53a60ad84bded44aa46c65faae7b3da99a099a9ca0b018872a9</open-checksum>
+    <location href="repodata/8510c74a6f288828bbc92abee5d0d8ae9687d3c31a2579ea95e31a4c3a320d85-other.xml.gz"/>
+    <timestamp>1786573032</timestamp>
+    <size>296</size>
+    <open-size>399</open-size>
+  </data>
+  <data type="primary_db">
+    <checksum type="sha256">f6bd7755da13d9726381048f467992869104a4c5521338ef740dc35eb85b9b71</checksum>
+    <open-checksum type="sha256">c45c85d12ccb0f8172b7bfae466362c08ac1867559574a9fb9cb2118c04daddb</open-checksum>
+    <location href="repodata/f6bd7755da13d9726381048f467992869104a4c5521338ef740dc35eb85b9b71-primary.sqlite.bz2"/>
+    <timestamp>1786573032</timestamp>
+    <size>1740</size>
+    <open-size>106496</open-size>
+    <database_version>10</database_version>
+  </data>
+  <data type="filelists_db">
+    <checksum type="sha256">be3c6e4c7a13ece48bd5d6a4d6d5e6a2395fe006ef9c5f217f5b87144f465e57</checksum>
+    <open-checksum type="sha256">1ccfa3dff532d782ce3225aae807506a4ce4534291386f1c47455dcc6b70cfd6</open-checksum>
+    <location href="repodata/be3c6e4c7a13ece48bd5d6a4d6d5e6a2395fe006ef9c5f217f5b87144f465e57-filelists.sqlite.bz2"/>
+    <timestamp>1786573032</timestamp>
+    <size>764</size>
+    <open-size>28672</open-size>
+    <database_version>10</database_version>
+  </data>
+  <data type="other_db">
+    <checksum type="sha256">ba593cd8ab5ec1e127888707c1fd882920996f1ce173fd7a589d647918fd7da4</checksum>
+    <open-checksum type="sha256">5d4d38380f0e359bfc0a50033d4faa84c75c5ae8fe2ef11c1c82d64748e9b8e2</open-checksum>
+    <location href="repodata/ba593cd8ab5ec1e127888707c1fd882920996f1ce173fd7a589d647918fd7da4-other.sqlite.bz2"/>
+    <timestamp>1786573032</timestamp>
+    <size>738</size>
+    <open-size>24576</open-size>
+    <database_version>10</database_version>
+  </data>
+</repomd>

e2e-docker/leastconn_test.go

@@ -0,0 +1,105 @@
+//go:build dockere2e
+
+package e2edocker
+
+import (
+	"fmt"
+	"net/http"
+	"os"
+	"os/exec"
+	"strings"
+	"testing"
+)
+
+// TestLeastConnMultiBaseURL configures an rpm remote with mirror_strategy =
+// least_conn over a two-mirror pool and drives distinct cache-miss paths through
+// it, asserting every request succeeds and both mirrors serve traffic. This
+// exercises the least-connections selection path (leastConnOrder + the in-flight
+// gauge inc/dec around each upstream call) end-to-end through a real HTTP client.
+// A precise least-loaded assertion is timing-sensitive over HTTP and is covered
+// deterministically by the proxy unit test (TestLeastConnPicksLeastLoaded);
+// here, with requests issued serially, in-flight counts return to zero between
+// them so equal-load mirrors are spread by the round-robin tie-break.
+func TestLeastConnMultiBaseURL(t *testing.T) {
+	name := "e2e-leastconn"
+	createRepo(t, fmt.Sprintf(`{
+		"name": %q,
+		"package_type": "rpm",
+		"repo_type": "remote",
+		"base_url": %q,
+		"mirrorlist": [%q],
+		"mirror_strategy": "least_conn",
+		"stale_on_error": false
+	}`, name, mockUpstreamA(), mockUpstreamB()))
+	defer deleteRepo(t, name)
+
+	seenA, seenB := false, false
+	const n = 12
+	for i := 0; i < n; i++ {
+		url := api(fmt.Sprintf("/api/v1/remote/%s/lc/%d", name, i))
+		resp, body := doRequest(t, http.MethodGet, url, nil, "")
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("request %d: status %d: %s", i, resp.StatusCode, body)
+		}
+		switch strings.TrimSpace(string(body)) {
+		case "UPSTREAM-A":
+			seenA = true
+		case "UPSTREAM-B":
+			seenB = true
+		default:
+			t.Fatalf("request %d: unexpected body %q", i, body)
+		}
+	}
+	if !seenA || !seenB {
+		t.Fatalf("least_conn remote did not reach both upstreams: A=%v B=%v", seenA, seenB)
+	}
+}
+
+// TestLeastConnDnfInstall drives a real dnf (stock rockylinux container) at a
+// two-mirror rpm remote configured with mirror_strategy = least_conn whose
+// primary base_url is dead: makecache + install must succeed via the live mirror.
+// This proves a real package-manager client installs correctly through a
+// least_conn remote and that failover semantics are unchanged under the new
+// strategy. Requires the compose network exported by scripts/docker-e2e.sh.
+func TestLeastConnDnfInstall(t *testing.T) {
+	network := os.Getenv("COMPOSE_NETWORK")
+	internal := os.Getenv("ARTIFACTAPI_INTERNAL")
+	if network == "" || internal == "" {
+		t.Skip("COMPOSE_NETWORK/ARTIFACTAPI_INTERNAL not set; run via scripts/docker-e2e.sh")
+	}
+	if _, err := exec.LookPath("docker"); err != nil {
+		t.Skip("docker not available on the test host")
+	}
+
+	name := "e2e-leastconn-dnf"
+	createRepo(t, fmt.Sprintf(`{
+		"name": %q,
+		"package_type": "rpm",
+		"repo_type": "remote",
+		"base_url": "http://mockupstream-dead:80",
+		"mirrorlist": [%q],
+		"mirror_strategy": "least_conn",
+		"stale_on_error": false
+	}`, name, mockUpstream()))
+	defer deleteRepo(t, name)
+
+	repoURL := strings.TrimRight(internal, "/") + "/api/v1/remote/" + name + "/rpm-mirror"
+	repoConf := fmt.Sprintf("[dnflc]\nname=dnflc\nbaseurl=%s\nenabled=1\ngpgcheck=0\nsslverify=0\nmetadata_expire=0\n", repoURL)
+	script := "set -euo pipefail; " +
+		"printf '%s' \"$REPO\" > /etc/yum.repos.d/dnflc.repo; " +
+		"dnf -y --disablerepo='*' --enablerepo=dnflc makecache; " +
+		"dnf -y --disablerepo='*' --enablerepo=dnflc install e2e-testpkg; " +
+		"rpm -q e2e-testpkg"
+
+	cmd := exec.Command("docker", "run", "--rm",
+		"--network", network,
+		"-e", "REPO="+repoConf,
+		"rockylinux:9", "bash", "-c", script)
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		t.Fatalf("real dnf install through a least_conn remote failed: %v\n%s", err, out)
+	}
+	if !strings.Contains(string(out), "e2e-testpkg-1.0-1") {
+		t.Fatalf("dnf did not install the expected package via least_conn remote; output:\n%s", out)
+	}
+}

e2e-docker/local_test.go

@@ -3,11 +3,16 @@
 package e2edocker
 
 import (
+	"archive/tar"
 	"bytes"
+	"compress/gzip"
+	"io"
 	"net/http"
 	"strings"
 	"testing"
 	"time"
+
+	"git.unkin.net/unkin/artifactapi/internal/testsupport"
 )
 
 func uploadFile(t *testing.T, repo, filePath string, body []byte, contentType string) {
@@ -91,3 +96,98 @@ func TestLocalRPMRepodata(t *testing.T) {
 		t.Fatalf("repomd.xml not a valid repodata document: %s", s)
 	}
 }
+
+// TestLocalDebRepo uploads a .deb and validates that the flat apt index
+// (Packages / Release) is generated automatically from the parsed control
+// stanza (the deb-local analog of rpm repodata generation).
+func TestLocalDebRepo(t *testing.T) {
+	createRepo(t, `{"name":"local-deb","package_type":"deb","repo_type":"local"}`)
+	defer deleteRepo(t, "local-deb")
+
+	deb := testsupport.MinimalDeb("e2e-testpkg", "1.0.0", "amd64")
+	uploadFile(t, "local-deb", "e2e-testpkg_1.0.0_amd64.deb", deb, "application/vnd.debian.binary-package")
+
+	// The index is generated asynchronously after upload; poll for it.
+	resp, body := getEventually(t, api("/api/v1/local/local-deb/Packages"), 15*time.Second)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("Packages: status %d: %s", resp.StatusCode, body)
+	}
+	pkgs := string(body)
+	for _, want := range []string{"Package: e2e-testpkg", "Version: 1.0.0", "Architecture: amd64", "Filename: pool/e2e-testpkg_1.0.0_amd64.deb", "SHA256:"} {
+		if !strings.Contains(pkgs, want) {
+			t.Fatalf("Packages missing %q:\n%s", want, pkgs)
+		}
+	}
+
+	resp, body = doRequest(t, http.MethodGet, api("/api/v1/local/local-deb/Release"), nil, "")
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("Release: status %d: %s", resp.StatusCode, body)
+	}
+	rel := string(body)
+	for _, want := range []string{"Architectures: amd64", "SHA256:", "Packages"} {
+		if !strings.Contains(rel, want) {
+			t.Fatalf("Release missing %q:\n%s", want, rel)
+		}
+	}
+
+	// The .deb downloads back byte-identical from its pool path.
+	resp, body = doRequest(t, http.MethodGet, api("/api/v1/local/local-deb/pool/e2e-testpkg_1.0.0_amd64.deb"), nil, "")
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("download deb: status %d: %s", resp.StatusCode, body)
+	}
+	if !bytes.Equal(body, deb) {
+		t.Fatalf("deb content mismatch")
+	}
+}
+
+// TestLocalAlpineIndex uploads an .apk to an alpine local repo and validates
+// that a per-arch APKINDEX.tar.gz is generated automatically from the parsed
+// .PKGINFO (the apk-local analog of rpm repodata / deb Packages generation).
+func TestLocalAlpineIndex(t *testing.T) {
+	createRepo(t, `{"name":"local-alpine","package_type":"alpine","repo_type":"local"}`)
+	defer deleteRepo(t, "local-alpine")
+
+	apk := testsupport.MinimalApk("e2e-testpkg", "1.0-r0", "x86_64")
+	uploadFile(t, "local-alpine", "x86_64/e2e-testpkg-1.0-r0.apk", apk, "application/vnd.android.package-archive")
+
+	// The index is generated asynchronously after upload; poll for it.
+	resp, body := getEventually(t, api("/api/v1/local/local-alpine/x86_64/APKINDEX.tar.gz"), 15*time.Second)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("APKINDEX: status %d: %s", resp.StatusCode, body)
+	}
+
+	zr, err := gzip.NewReader(bytes.NewReader(body))
+	if err != nil {
+		t.Fatalf("APKINDEX not gzip: %v", err)
+	}
+	tarBytes, _ := io.ReadAll(zr)
+	tr := tar.NewReader(bytes.NewReader(tarBytes))
+	var index string
+	for {
+		hdr, err := tr.Next()
+		if err == io.EOF {
+			break
+		}
+		if err != nil {
+			t.Fatalf("APKINDEX not tar: %v", err)
+		}
+		if hdr.Name == "APKINDEX" {
+			b, _ := io.ReadAll(tr)
+			index = string(b)
+		}
+	}
+	for _, want := range []string{"P:e2e-testpkg", "V:1.0-r0", "A:x86_64", "C:Q1", "S:", "I:"} {
+		if !strings.Contains(index, want) {
+			t.Fatalf("APKINDEX missing %q:\n%s", want, index)
+		}
+	}
+
+	// The .apk downloads back byte-identical from its arch path.
+	resp, body = doRequest(t, http.MethodGet, api("/api/v1/local/local-alpine/x86_64/e2e-testpkg-1.0-r0.apk"), nil, "")
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("download apk: status %d: %s", resp.StatusCode, body)
+	}
+	if !bytes.Equal(body, apk) {
+		t.Fatalf("apk content mismatch")
+	}
+}

e2e-docker/mirror-conf/a.conf

@@ -0,0 +1,9 @@
+# Mock upstream A for the multi-base_url e2e: any path returns a constant,
+# upstream-identifying body so round-robin distribution is observable.
+server {
+    listen 80;
+    location / {
+        default_type text/plain;
+        return 200 "UPSTREAM-A";
+    }
+}

e2e-docker/mirror-conf/b.conf

@@ -0,0 +1,8 @@
+# Mock upstream B for the multi-base_url e2e (see a.conf).
+server {
+    listen 80;
+    location / {
+        default_type text/plain;
+        return 200 "UPSTREAM-B";
+    }
+}

e2e-docker/multibaseurl_test.go

@@ -0,0 +1,163 @@
+//go:build dockere2e
+
+package e2edocker
+
+import (
+	"fmt"
+	"net/http"
+	"os"
+	"os/exec"
+	"strings"
+	"testing"
+)
+
+// mockUpstreamA/B are the constant-body upstreams (see docker-compose.e2e.yml)
+// that let the round-robin test observe which mirror served each request.
+func mockUpstreamA() string {
+	if v := os.Getenv("MOCK_UPSTREAM_A_INTERNAL"); v != "" {
+		return strings.TrimRight(v, "/")
+	}
+	return "http://mockupstreama"
+}
+
+func mockUpstreamB() string {
+	if v := os.Getenv("MOCK_UPSTREAM_B_INTERNAL"); v != "" {
+		return strings.TrimRight(v, "/")
+	}
+	return "http://mockupstreamb"
+}
+
+// TestMultiBaseURLRoundRobin configures an rpm remote with base_url = mirror A
+// and mirrorlist = [mirror B] and drives distinct paths through it, asserting
+// both mirrors serve traffic. Each path is a cache miss, so every request reaches
+// upstream and the round-robin cursor alternates mirrors.
+func TestMultiBaseURLRoundRobin(t *testing.T) {
+	name := "e2e-rr"
+	createRepo(t, fmt.Sprintf(`{
+		"name": %q,
+		"package_type": "rpm",
+		"repo_type": "remote",
+		"base_url": %q,
+		"mirrorlist": [%q],
+		"stale_on_error": false
+	}`, name, mockUpstreamA(), mockUpstreamB()))
+	defer deleteRepo(t, name)
+
+	seenA, seenB := false, false
+	const n = 12
+	for i := 0; i < n; i++ {
+		url := api(fmt.Sprintf("/api/v1/remote/%s/rr/%d", name, i))
+		resp, body := doRequest(t, http.MethodGet, url, nil, "")
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("request %d: status %d: %s", i, resp.StatusCode, body)
+		}
+		switch strings.TrimSpace(string(body)) {
+		case "UPSTREAM-A":
+			seenA = true
+		case "UPSTREAM-B":
+			seenB = true
+		default:
+			t.Fatalf("request %d: unexpected body %q", i, body)
+		}
+	}
+	if !seenA || !seenB {
+		t.Fatalf("round-robin did not reach both upstreams: A=%v B=%v", seenA, seenB)
+	}
+}
+
+// TestMultiBaseURLFailover points a two-mirror remote at a dead primary and a
+// healthy secondary and asserts every request still succeeds via the secondary.
+func TestMultiBaseURLFailover(t *testing.T) {
+	name := "e2e-failover"
+	createRepo(t, fmt.Sprintf(`{
+		"name": %q,
+		"package_type": "rpm",
+		"repo_type": "remote",
+		"base_url": "http://mockupstream-dead:80",
+		"mirrorlist": [%q],
+		"stale_on_error": false
+	}`, name, mockUpstreamB()))
+	defer deleteRepo(t, name)
+
+	for i := 0; i < 6; i++ {
+		url := api(fmt.Sprintf("/api/v1/remote/%s/fo/%d", name, i))
+		resp, body := doRequest(t, http.MethodGet, url, nil, "")
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("request %d: dead primary broke fetch: status %d: %s", i, resp.StatusCode, body)
+		}
+		if got := strings.TrimSpace(string(body)); got != "UPSTREAM-B" {
+			t.Fatalf("request %d: body %q, want UPSTREAM-B (served via failover)", i, got)
+		}
+	}
+}
+
+// TestSingleBaseURLRegression asserts a remote with no mirrorlist works exactly
+// as before the mirrorlist change.
+func TestSingleBaseURLRegression(t *testing.T) {
+	name := "e2e-single"
+	createRepo(t, fmt.Sprintf(`{
+		"name": %q,
+		"package_type": "rpm",
+		"repo_type": "remote",
+		"base_url": %q,
+		"stale_on_error": false
+	}`, name, mockUpstreamA()))
+	defer deleteRepo(t, name)
+
+	resp, body := doRequest(t, http.MethodGet, api("/api/v1/remote/"+name+"/solo/0"), nil, "")
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("single-url fetch: status %d: %s", resp.StatusCode, body)
+	}
+	if got := strings.TrimSpace(string(body)); got != "UPSTREAM-A" {
+		t.Fatalf("single-url body %q, want UPSTREAM-A", got)
+	}
+}
+
+// TestMultiBaseURLDnfFailover drives a real dnf (stock rockylinux container) at
+// a two-mirror rpm remote whose primary is dead: makecache + install must
+// succeed via the live secondary mirror, proving a dead mirror does not break a
+// real package-manager client. Requires the compose network and internal API
+// URL exported by scripts/docker-e2e.sh; skipped when run standalone.
+func TestMultiBaseURLDnfFailover(t *testing.T) {
+	network := os.Getenv("COMPOSE_NETWORK")
+	internal := os.Getenv("ARTIFACTAPI_INTERNAL")
+	if network == "" || internal == "" {
+		t.Skip("COMPOSE_NETWORK/ARTIFACTAPI_INTERNAL not set; run via scripts/docker-e2e.sh")
+	}
+	if _, err := exec.LookPath("docker"); err != nil {
+		t.Skip("docker not available on the test host")
+	}
+
+	name := "e2e-dnf-failover"
+	// Primary base_url is dead; the live mirror serves the real yum repo under
+	// fixtures/rpm-mirror via the shared mock upstream.
+	createRepo(t, fmt.Sprintf(`{
+		"name": %q,
+		"package_type": "rpm",
+		"repo_type": "remote",
+		"base_url": "http://mockupstream-dead:80",
+		"mirrorlist": [%q],
+		"stale_on_error": false
+	}`, name, mockUpstream()))
+	defer deleteRepo(t, name)
+
+	repoURL := strings.TrimRight(internal, "/") + "/api/v1/remote/" + name + "/rpm-mirror"
+	repoConf := fmt.Sprintf("[dnffo]\nname=dnffo\nbaseurl=%s\nenabled=1\ngpgcheck=0\nsslverify=0\nmetadata_expire=0\n", repoURL)
+	script := "set -euo pipefail; " +
+		"printf '%s' \"$REPO\" > /etc/yum.repos.d/dnffo.repo; " +
+		"dnf -y --disablerepo='*' --enablerepo=dnffo makecache; " +
+		"dnf -y --disablerepo='*' --enablerepo=dnffo install e2e-testpkg; " +
+		"rpm -q e2e-testpkg"
+
+	cmd := exec.Command("docker", "run", "--rm",
+		"--network", network,
+		"-e", "REPO="+repoConf,
+		"rockylinux:9", "bash", "-c", script)
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		t.Fatalf("real dnf install through a dead primary mirror failed: %v\n%s", err, out)
+	}
+	if !strings.Contains(string(out), "e2e-testpkg-1.0-1") {
+		t.Fatalf("dnf did not install the expected package via failover; output:\n%s", out)
+	}
+}

go.mod

@@ -3,18 +3,21 @@ module git.unkin.net/unkin/artifactapi
 go 1.25.9
 
 require (
+	git.unkin.net/unkin/golib v0.1.0
 	github.com/cavaliergopher/rpm v1.3.0
 	github.com/charmbracelet/bubbletea v1.3.10
 	github.com/charmbracelet/lipgloss v1.1.0
 	github.com/go-chi/chi/v5 v5.3.0
 	github.com/google/uuid v1.6.0
 	github.com/jackc/pgx/v5 v5.10.0
+	github.com/klauspost/compress v1.19.2
 	github.com/minio/minio-go/v7 v7.2.0
 	github.com/redis/go-redis/v9 v9.20.0
-	github.com/testcontainers/testcontainers-go v0.42.0
-	github.com/testcontainers/testcontainers-go/modules/postgres v0.42.0
+	github.com/testcontainers/testcontainers-go v0.44.0
+	github.com/testcontainers/testcontainers-go/modules/postgres v0.44.0
 	github.com/testcontainers/testcontainers-go/modules/redis v0.42.0
-	golang.org/x/crypto v0.51.0
+	github.com/ulikunitz/xz v0.5.16
+	golang.org/x/crypto v0.54.0
 	golang.org/x/time v0.15.0
 	gopkg.in/yaml.v3 v3.0.1
 )
@@ -39,23 +42,22 @@ require (
 	github.com/cpuguy83/dockercfg v0.3.2 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/distribution/reference v0.6.0 // indirect
-	github.com/docker/go-connections v0.6.0 // indirect
+	github.com/docker/go-connections v0.7.0 // indirect
 	github.com/docker/go-units v0.5.0 // indirect
 	github.com/dustin/go-humanize v1.0.1 // indirect
-	github.com/ebitengine/purego v0.10.0 // indirect
+	github.com/ebitengine/purego v0.10.1 // indirect
 	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
-	github.com/felixge/httpsnoop v1.0.4 // indirect
+	github.com/felixge/httpsnoop v1.1.0 // indirect
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
-	github.com/go-ole/go-ole v1.2.6 // indirect
+	github.com/go-ole/go-ole v1.3.0 // indirect
 	github.com/jackc/pgpassfile v1.0.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
 	github.com/jackc/puddle/v2 v2.2.2 // indirect
-	github.com/klauspost/compress v1.18.6 // indirect
 	github.com/klauspost/cpuid/v2 v2.2.11 // indirect
 	github.com/klauspost/crc32 v1.3.0 // indirect
 	github.com/lucasb-eyer/go-colorful v1.4.0 // indirect
-	github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 // indirect
+	github.com/lufia/plan9stats v0.0.0-20260330125221-c963978e514e // indirect
 	github.com/magiconair/properties v1.8.10 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/mattn/go-localereader v0.0.1 // indirect
@@ -65,10 +67,10 @@ require (
 	github.com/minio/md5-simd v1.1.2 // indirect
 	github.com/moby/docker-image-spec v1.3.1 // indirect
 	github.com/moby/go-archive v0.2.0 // indirect
-	github.com/moby/moby/api v1.54.1 // indirect
-	github.com/moby/moby/client v0.4.0 // indirect
+	github.com/moby/moby/api v1.55.0 // indirect
+	github.com/moby/moby/client v0.5.0 // indirect
 	github.com/moby/patternmatcher v0.6.1 // indirect
-	github.com/moby/sys/sequential v0.6.0 // indirect
+	github.com/moby/sys/sequential v0.7.0 // indirect
 	github.com/moby/sys/user v0.4.0 // indirect
 	github.com/moby/sys/userns v0.1.0 // indirect
 	github.com/moby/term v0.5.2 // indirect
@@ -82,25 +84,25 @@ require (
 	github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/rs/xid v1.6.0 // indirect
-	github.com/shirou/gopsutil/v4 v4.26.3 // indirect
+	github.com/shirou/gopsutil/v4 v4.26.6 // indirect
 	github.com/sirupsen/logrus v1.9.4 // indirect
 	github.com/stretchr/testify v1.11.1 // indirect
 	github.com/tinylib/msgp v1.6.1 // indirect
-	github.com/tklauser/go-sysconf v0.3.16 // indirect
-	github.com/tklauser/numcpus v0.11.0 // indirect
+	github.com/tklauser/go-sysconf v0.4.0 // indirect
+	github.com/tklauser/numcpus v0.12.0 // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
 	github.com/yusufpapurcu/wmi v1.2.4 // indirect
 	github.com/zeebo/xxh3 v1.1.0 // indirect
 	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
-	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.60.0 // indirect
-	go.opentelemetry.io/otel v1.41.0 // indirect
-	go.opentelemetry.io/otel/metric v1.41.0 // indirect
-	go.opentelemetry.io/otel/trace v1.41.0 // indirect
+	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.69.0 // indirect
+	go.opentelemetry.io/otel v1.44.0 // indirect
+	go.opentelemetry.io/otel/metric v1.44.0 // indirect
+	go.opentelemetry.io/otel/trace v1.44.0 // indirect
 	go.uber.org/atomic v1.11.0 // indirect
 	go.yaml.in/yaml/v3 v3.0.4 // indirect
-	golang.org/x/net v0.53.0 // indirect
-	golang.org/x/sync v0.20.0 // indirect
-	golang.org/x/sys v0.44.0 // indirect
-	golang.org/x/text v0.37.0 // indirect
+	golang.org/x/net v0.56.0 // indirect
+	golang.org/x/sync v0.22.0 // indirect
+	golang.org/x/sys v0.47.0 // indirect
+	golang.org/x/text v0.40.0 // indirect
 	gopkg.in/ini.v1 v1.67.2 // indirect
 )

go.sum

@@ -1,5 +1,7 @@
 dario.cat/mergo v1.0.2 h1:85+piFYR1tMbRrLcDwR18y4UKJ3aH1Tbzi24VRW1TK8=
 dario.cat/mergo v1.0.2/go.mod h1:E/hbnu0NxMFBjpMIE34DRGLWqDy0g5FuKDhCb31ngxA=
+git.unkin.net/unkin/golib v0.1.0 h1:OjKT5TO7PuXiYQ/1A+I4S2VZ/IsAxXY1reGWwasDMqE=
+git.unkin.net/unkin/golib v0.1.0/go.mod h1:1e3PpMLEfa03Re/6tlk+I2XPWzBQMSpw2MB+Aw2lkX4=
 github.com/AdaLogics/go-fuzz-headers v0.0.0-20240806141605-e8a1dd7889d6 h1:He8afgbRMd7mFxO99hRNu+6tazq8nFF9lIwo9JFroBk=
 github.com/AdaLogics/go-fuzz-headers v0.0.0-20240806141605-e8a1dd7889d6/go.mod h1:8o94RPi1/7XTJvwPpRSzSUedZrtlirdB3r9Z20bi2f8=
 github.com/Azure/go-ansiterm v0.0.0-20250102033503-faa5f7b0171c h1:udKWzYgxTojEKWjV8V+WSxDXJ4NFATAsZjh8iIbsQIg=
@@ -51,18 +53,18 @@ github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/distribution/reference v0.6.0 h1:0IXCQ5g4/QMHHkarYzh5l+u8T3t73zM5QvfrDyIgxBk=
 github.com/distribution/reference v0.6.0/go.mod h1:BbU0aIcezP1/5jX/8MP0YiH4SdvB5Y4f/wlDRiLyi3E=
-github.com/docker/go-connections v0.6.0 h1:LlMG9azAe1TqfR7sO+NJttz1gy6KO7VJBh+pMmjSD94=
-github.com/docker/go-connections v0.6.0/go.mod h1:AahvXYshr6JgfUJGdDCs2b5EZG/vmaMAntpSFH5BFKE=
+github.com/docker/go-connections v0.7.0 h1:6SsRfJddP22WMrCkj19x9WKjEDTB+ahsdiGYf0mN39c=
+github.com/docker/go-connections v0.7.0/go.mod h1:no1qkHdjq7kLMGUXYAduOhYPSJxxvgWBh7ogVvptn3Q=
 github.com/docker/go-units v0.5.0 h1:69rxXcBk27SvSaaxTtLh/8llcHD8vYHT7WSdRZ/jvr4=
 github.com/docker/go-units v0.5.0/go.mod h1:fgPhTUdO+D/Jk86RDLlptpiXQzgHJF7gydDDbaIK4Dk=
 github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
 github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
-github.com/ebitengine/purego v0.10.0 h1:QIw4xfpWT6GWTzaW5XEKy3HXoqrJGx1ijYHzTF0/ISU=
-github.com/ebitengine/purego v0.10.0/go.mod h1:iIjxzd6CiRiOG0UyXP+V1+jWqUXVjPKLAI0mRfJZTmQ=
+github.com/ebitengine/purego v0.10.1 h1:dewVBCBT2GaMu1SrNTYxQhgQBethzfhiwvZiLGP/qyY=
+github.com/ebitengine/purego v0.10.1/go.mod h1:iIjxzd6CiRiOG0UyXP+V1+jWqUXVjPKLAI0mRfJZTmQ=
 github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f h1:Y/CXytFA4m6baUTXGLOoWe4PQhGxaX0KpnayAqC48p4=
 github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f/go.mod h1:vw97MGsxSvLiUE2X8qFplwetxpGLQrlU1Q9AUEIzCaM=
-github.com/felixge/httpsnoop v1.0.4 h1:NFTV2Zj1bL4mc9sqWACXbQFVBBg2W3GPvqp8/ESS2Wg=
-github.com/felixge/httpsnoop v1.0.4/go.mod h1:m8KPJKqk1gH5J9DgRY2ASl2lWCfGKXixSwevea8zH2U=
+github.com/felixge/httpsnoop v1.1.0 h1:3YtUj32ZZkqZtt3sZZsClsymw/QDuVfpNhoA31zeORc=
+github.com/felixge/httpsnoop v1.1.0/go.mod h1:Zqxgdd+1Rkcz8euOqdr7lqgCRJztwr5hp9vDSi5UZCE=
 github.com/go-chi/chi/v5 v5.3.0 h1:halUjDxhshgXHMrao5bB8eNBXo/rnzwr8m5m36glehM=
 github.com/go-chi/chi/v5 v5.3.0/go.mod h1:R+tYY2hNuVUUjxoPtqUdgBqevM9s9njzkTLutVsOCto=
 github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
@@ -70,9 +72,9 @@ github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
 github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
 github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
 github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
-github.com/go-ole/go-ole v1.2.6 h1:/Fpf6oFPoeFik9ty7siob0G6Ke8QvQEuVcuChpwXzpY=
 github.com/go-ole/go-ole v1.2.6/go.mod h1:pprOEPIfldk/42T2oK7lQ4v4JSDwmV0As9GaiUsvbm0=
-github.com/google/go-cmp v0.5.6/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
+github.com/go-ole/go-ole v1.3.0 h1:Dt6ye7+vXGIKZ7Xtk4s6/xVdGDQynvom7xCFEdWr6uE=
+github.com/go-ole/go-ole v1.3.0/go.mod h1:5LS6F96DhAwUc7C+1HLexzMXY1xGRSryjyPPKW6zv78=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
@@ -85,8 +87,8 @@ github.com/jackc/pgx/v5 v5.10.0 h1:VhSvgU2jSli8o3AqIEOTJr7rZwAEUVo4E4XhR94Zfr0=
 github.com/jackc/pgx/v5 v5.10.0/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QIIM0Jn4=
 github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
 github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
-github.com/klauspost/compress v1.18.6 h1:2jupLlAwFm95+YDR+NwD2MEfFO9d4z4Prjl1XXDjuao=
-github.com/klauspost/compress v1.18.6/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
+github.com/klauspost/compress v1.19.2 h1:hMRETovs/pu/dVWN7zIT1PGG8t509MwT6bO7XSi26R8=
+github.com/klauspost/compress v1.19.2/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
 github.com/klauspost/cpuid/v2 v2.0.1/go.mod h1:FInQzS24/EEf25PyTYn52gqo7WaD8xa0213Md/qVLRg=
 github.com/klauspost/cpuid/v2 v2.2.11 h1:0OwqZRYI2rFrjS4kvkDnqJkKHdHaRnCm68/DY4OxRzU=
 github.com/klauspost/cpuid/v2 v2.2.11/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
@@ -100,8 +102,8 @@ github.com/lib/pq v1.10.9 h1:YXG7RB+JIjhP29X+OtkiDnYaXQwpS4JEWq7dtCCRUEw=
 github.com/lib/pq v1.10.9/go.mod h1:AlVN5x4E4T544tWzH6hKfbfQvm3HdbOxrmggDNAPY9o=
 github.com/lucasb-eyer/go-colorful v1.4.0 h1:UtrWVfLdarDgc44HcS7pYloGHJUjHV/4FwW4TvVgFr4=
 github.com/lucasb-eyer/go-colorful v1.4.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
-github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 h1:6E+4a0GO5zZEnZ81pIr0yLvtUWk2if982qA3F3QD6H4=
-github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0/go.mod h1:zJYVVT2jmtg6P3p1VtQj7WsuWi/y4VnjVBn7F8KPB3I=
+github.com/lufia/plan9stats v0.0.0-20260330125221-c963978e514e h1:Q6MvJtQK/iRcRtzAscm/zF23XxJlbECiGPyRicsX+Ak=
+github.com/lufia/plan9stats v0.0.0-20260330125221-c963978e514e/go.mod h1:autxFIvghDt3jPTLoqZ9OZ7s9qTGNAWmYCjVFWPX/zg=
 github.com/magiconair/properties v1.8.10 h1:s31yESBquKXCV9a/ScB3ESkOjUYYv+X0rg8SYxI99mE=
 github.com/magiconair/properties v1.8.10/go.mod h1:Dhd985XPs7jluiymwWYZ0G4Z61jb3vdS329zhj2hYo0=
 github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
@@ -122,14 +124,14 @@ github.com/moby/docker-image-spec v1.3.1 h1:jMKff3w6PgbfSa69GfNg+zN/XLhfXJGnEx3N
 github.com/moby/docker-image-spec v1.3.1/go.mod h1:eKmb5VW8vQEh/BAr2yvVNvuiJuY6UIocYsFu/DxxRpo=
 github.com/moby/go-archive v0.2.0 h1:zg5QDUM2mi0JIM9fdQZWC7U8+2ZfixfTYoHL7rWUcP8=
 github.com/moby/go-archive v0.2.0/go.mod h1:mNeivT14o8xU+5q1YnNrkQVpK+dnNe/K6fHqnTg4qPU=
-github.com/moby/moby/api v1.54.1 h1:TqVzuJkOLsgLDDwNLmYqACUuTehOHRGKiPhvH8V3Nn4=
-github.com/moby/moby/api v1.54.1/go.mod h1:+RQ6wluLwtYaTd1WnPLykIDPekkuyD/ROWQClE83pzs=
-github.com/moby/moby/client v0.4.0 h1:S+2XegzHQrrvTCvF6s5HFzcrywWQmuVnhOXe2kiWjIw=
-github.com/moby/moby/client v0.4.0/go.mod h1:QWPbvWchQbxBNdaLSpoKpCdf5E+WxFAgNHogCWDoa7g=
+github.com/moby/moby/api v1.55.0 h1:2/sexvQyqIWS8pRSCFddBfpW2qE7vR7FCL+vN8pxwMc=
+github.com/moby/moby/api v1.55.0/go.mod h1:+RQ6wluLwtYaTd1WnPLykIDPekkuyD/ROWQClE83pzs=
+github.com/moby/moby/client v0.5.0 h1:5XhyPk2fuOWf6RlSFa3MkIIgDZkF25xToXW8Q/BH7cc=
+github.com/moby/moby/client v0.5.0/go.mod h1:rcVpF8ncl9vo5gaIBdol6CnbEtSj1uxMvEV/UrykF/s=
 github.com/moby/patternmatcher v0.6.1 h1:qlhtafmr6kgMIJjKJMDmMWq7WLkKIo23hsrpR3x084U=
 github.com/moby/patternmatcher v0.6.1/go.mod h1:hDPoyOpDY7OrrMDLaYoY3hf52gNCR/YOUYxkhApJIxc=
-github.com/moby/sys/sequential v0.6.0 h1:qrx7XFUd/5DxtqcoH1h438hF5TmOvzC/lspjy7zgvCU=
-github.com/moby/sys/sequential v0.6.0/go.mod h1:uyv8EUTrca5PnDsdMGXhZe6CCe8U/UiTWd+lL+7b/Ko=
+github.com/moby/sys/sequential v0.7.0 h1:ASQNGNROJSuOO6LL6bPHbKvuZu6NU8P4ldPWk31zj/8=
+github.com/moby/sys/sequential v0.7.0/go.mod h1:NfSTAp6V3fw4tmkD62PEcOKeZKquXT8VKCkf7aVR79o=
 github.com/moby/sys/user v0.4.0 h1:jhcMKit7SA80hivmFJcbB1vqmw//wU61Zdui2eQXuMs=
 github.com/moby/sys/user v0.4.0/go.mod h1:bG+tYYYJgaMtRKgEmuueC0hJEAZWwtIbZTB+85uoHjs=
 github.com/moby/sys/userns v0.1.0 h1:tVLXkFOxVu9A64/yh59slHVv9ahO9UIev4JZusOLG/g=
@@ -160,8 +162,8 @@ github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0t
 github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
 github.com/rs/xid v1.6.0 h1:fV591PaemRlL6JfRxGDEPl69wICngIQ3shQtzfy2gxU=
 github.com/rs/xid v1.6.0/go.mod h1:7XoLgs4eV+QndskICGsho+ADou8ySMSjJKDIan90Nz0=
-github.com/shirou/gopsutil/v4 v4.26.3 h1:2ESdQt90yU3oXF/CdOlRCJxrP+Am1aBYubTMTfxJ1qc=
-github.com/shirou/gopsutil/v4 v4.26.3/go.mod h1:LZ6ewCSkBqUpvSOf+LsTGnRinC6iaNUNMGBtDkJBaLQ=
+github.com/shirou/gopsutil/v4 v4.26.6 h1:Mzr/npDtQC/xpeEuQKHZt8Zo9CmPvhTj8nkR8w5TLDs=
+github.com/shirou/gopsutil/v4 v4.26.6/go.mod h1:LZ6ewCSkBqUpvSOf+LsTGnRinC6iaNUNMGBtDkJBaLQ=
 github.com/sirupsen/logrus v1.9.4 h1:TsZE7l11zFCLZnZ+teH4Umoq5BhEIfIzfRDZ1Uzql2w=
 github.com/sirupsen/logrus v1.9.4/go.mod h1:ftWc9WdOfJ0a92nsE2jF5u5ZwH8Bv2zdeOC42RjbV2g=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
@@ -177,18 +179,20 @@ github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO
 github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
-github.com/testcontainers/testcontainers-go v0.42.0 h1:He3IhTzTZOygSXLJPMX7n44XtK+qhjat1nI9cneBbUY=
-github.com/testcontainers/testcontainers-go v0.42.0/go.mod h1:vZjdY1YmUA1qEForxOIOazfsrdyORJAbhi0bp8plN30=
-github.com/testcontainers/testcontainers-go/modules/postgres v0.42.0 h1:GCbb1ndrF7OTDiIvxXyItaDab4qkzTFJ48LKFdM7EIo=
-github.com/testcontainers/testcontainers-go/modules/postgres v0.42.0/go.mod h1:IRPBaI8jXdrNfD0e4Zm7Fbcgaz5shKxOQv4axiL09xs=
+github.com/testcontainers/testcontainers-go v0.44.0 h1:/Fwh6HY1mIikhnm9e7HwoxGycx0lzRAE0f5VQpjFxzI=
+github.com/testcontainers/testcontainers-go v0.44.0/go.mod h1:IcnwQrYTO86xHXu5bvMaBH7ATlbS3Qn1M1QWW3c66rE=
+github.com/testcontainers/testcontainers-go/modules/postgres v0.44.0 h1:8fdv/9y3JMxjQ+ULAcOG8RtgeNu5t9XF9LolSXDuTwM=
+github.com/testcontainers/testcontainers-go/modules/postgres v0.44.0/go.mod h1:CFr2LncGYokw+OKjXcr8ARCKG1SaC2UEnGxFBovE86g=
 github.com/testcontainers/testcontainers-go/modules/redis v0.42.0 h1:id/6LH8ZeDrtAUVSuNvZUAJ1kVpb82y1pr9yweAWsRg=
 github.com/testcontainers/testcontainers-go/modules/redis v0.42.0/go.mod h1:uF0jI8FITagQpBNOgweGBmPf6rP4K0SeL1XFPbsZSSY=
 github.com/tinylib/msgp v1.6.1 h1:ESRv8eL3u+DNHUoSAAQRE50Hm162zqAnBoGv9PzScPY=
 github.com/tinylib/msgp v1.6.1/go.mod h1:RSp0LW9oSxFut3KzESt5Voq4GVWyS+PSulT77roAqEA=
-github.com/tklauser/go-sysconf v0.3.16 h1:frioLaCQSsF5Cy1jgRBrzr6t502KIIwQ0MArYICU0nA=
-github.com/tklauser/go-sysconf v0.3.16/go.mod h1:/qNL9xxDhc7tx3HSRsLWNnuzbVfh3e7gh/BmM179nYI=
-github.com/tklauser/numcpus v0.11.0 h1:nSTwhKH5e1dMNsCdVBukSZrURJRoHbSEQjdEbY+9RXw=
-github.com/tklauser/numcpus v0.11.0/go.mod h1:z+LwcLq54uWZTX0u/bGobaV34u6V7KNlTZejzM6/3MQ=
+github.com/tklauser/go-sysconf v0.4.0 h1:7H0uAN+7RkwWRaxhYXDLqa5V3LPrJeV8wmD9dRUgPQU=
+github.com/tklauser/go-sysconf v0.4.0/go.mod h1:8mTNWyog7H+MpKijp4VmKJAd2bbYQ2zuUwkYRbUArPI=
+github.com/tklauser/numcpus v0.12.0 h1:NR85qdvHA9pFse3x3weVZ0r0ST8R6l5RHbZrlRaqob4=
+github.com/tklauser/numcpus v0.12.0/go.mod h1:ABHeXzJnr/qqwguhClkZKT1/8VABcYrsyUiUGobwWJg=
+github.com/ulikunitz/xz v0.5.16 h1:ld6NyySjx5lowVKwJvMRLnW5nxKX/xnpSiFYZ/Lxur0=
+github.com/ulikunitz/xz v0.5.16/go.mod h1:H9Rt/W6/Qj27PGauhQc6nfCDy7vHpzsOThBSaYDoEhw=
 github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e h1:JVG44RsyaB9T2KIHavMF/ppJZNG9ZpyihvCd0w101no=
 github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e/go.mod h1:RbqR21r5mrJuqunuUZ/Dhy/avygyECGrLceyNeo4LiM=
 github.com/yusufpapurcu/wmi v1.2.4 h1:zFUKzehAFReQwLys1b/iSMl+JQGSCSjtVqQn9bBrPo0=
@@ -199,44 +203,44 @@ github.com/zeebo/xxh3 v1.1.0 h1:s7DLGDK45Dyfg7++yxI0khrfwq9661w9EN78eP/UZVs=
 github.com/zeebo/xxh3 v1.1.0/go.mod h1:IisAie1LELR4xhVinxWS5+zf1lA4p0MW4T+w+W07F5s=
 go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
 go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
-go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.60.0 h1:sbiXRNDSWJOTobXh5HyQKjq6wUC5tNybqjIqDpAY4CU=
-go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.60.0/go.mod h1:69uWxva0WgAA/4bu2Yy70SLDBwZXuQ6PbBpbsa5iZrQ=
-go.opentelemetry.io/otel v1.41.0 h1:YlEwVsGAlCvczDILpUXpIpPSL/VPugt7zHThEMLce1c=
-go.opentelemetry.io/otel v1.41.0/go.mod h1:Yt4UwgEKeT05QbLwbyHXEwhnjxNO6D8L5PQP51/46dE=
-go.opentelemetry.io/otel/metric v1.41.0 h1:rFnDcs4gRzBcsO9tS8LCpgR0dxg4aaxWlJxCno7JlTQ=
-go.opentelemetry.io/otel/metric v1.41.0/go.mod h1:xPvCwd9pU0VN8tPZYzDZV/BMj9CM9vs00GuBjeKhJps=
-go.opentelemetry.io/otel/sdk v1.35.0 h1:iPctf8iprVySXSKJffSS79eOjl9pvxV9ZqOWT0QejKY=
-go.opentelemetry.io/otel/sdk v1.35.0/go.mod h1:+ga1bZliga3DxJ3CQGg3updiaAJoNECOgJREo9KHGQg=
-go.opentelemetry.io/otel/sdk/metric v1.35.0 h1:1RriWBmCKgkeHEhM7a2uMjMUfP7MsOF5JpUCaEqEI9o=
-go.opentelemetry.io/otel/sdk/metric v1.35.0/go.mod h1:is6XYCUMpcKi+ZsOvfluY5YstFnhW0BidkR+gL+qN+w=
-go.opentelemetry.io/otel/trace v1.41.0 h1:Vbk2co6bhj8L59ZJ6/xFTskY+tGAbOnCtQGVVa9TIN0=
-go.opentelemetry.io/otel/trace v1.41.0/go.mod h1:U1NU4ULCoxeDKc09yCWdWe+3QoyweJcISEVa1RBzOis=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.69.0 h1:8tvICD4vSTOOsNrsI4Ljf6C+6UKvpTEH5XY3JMoyPoo=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.69.0/go.mod h1:z9+yiacE0IHRqM4qFfkbt/JYlmYXgss8GY/jXoNuPJI=
+go.opentelemetry.io/otel v1.44.0 h1:JjwHmHpA4iZ3wBxluu2fbbE7j4kqlE8jXyAyPXH7HqU=
+go.opentelemetry.io/otel v1.44.0/go.mod h1:BMgjTHL9WPRlRjL2oZCBTL4whCGtXch2H4BhOPIAyYc=
+go.opentelemetry.io/otel/metric v1.44.0 h1:1w0gILTcHdr3YI+ixLyjemwrVnsMURbTZFrSYCdDdmc=
+go.opentelemetry.io/otel/metric v1.44.0/go.mod h1:8O7hanEPBNgEMmybD3s2VBKcgWOCsA6tzHBPODAiquo=
+go.opentelemetry.io/otel/sdk v1.44.0 h1:nHYwb9lK+fJPU/dnT6s7W7Z8itMWyqrnVfbheVYrZ58=
+go.opentelemetry.io/otel/sdk v1.44.0/go.mod h1:Osuydd3Se74nqjAKxid74N5eC+jfEqfTegHRnq58oK0=
+go.opentelemetry.io/otel/sdk/metric v1.44.0 h1:3LlKgI+VjbVsjNRFZJZAJ30WjXC5VkNRks6si09iEfI=
+go.opentelemetry.io/otel/sdk/metric v1.44.0/go.mod h1:5B5pMARnXxKhltooO4xUuCBorl65a4EpnTalObqOigA=
+go.opentelemetry.io/otel/trace v1.44.0 h1:jxF5CsGYCe74MCRx2X4g7WsY/VBKRqqpNvXlX/6gtIk=
+go.opentelemetry.io/otel/trace v1.44.0/go.mod h1:oLl1jrMQAVo6v3GAggN+1VH9VIz9iUSvW53sW1Q8PIE=
 go.uber.org/atomic v1.11.0 h1:ZvwS0R+56ePWxUNi+Atn9dWONBPp/AUETXlHW0DxSjE=
 go.uber.org/atomic v1.11.0/go.mod h1:LUxbIzbOniOlMKjJjyPfpl4v+PKK2cNJn91OQbhoJI0=
 go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc=
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
-golang.org/x/crypto v0.51.0 h1:IBPXwPfKxY7cWQZ38ZCIRPI50YLeevDLlLnyC5wRGTI=
-golang.org/x/crypto v0.51.0/go.mod h1:8AdwkbraGNABw2kOX6YFPs3WM22XqI4EXEd8g+x7Oc8=
+golang.org/x/crypto v0.54.0 h1:YLIA59K4fiNzHzjnZt2tUJQjQtUWfWbeHBqKtk3eScw=
+golang.org/x/crypto v0.54.0/go.mod h1:KWL8ny2AZdGR2cWmzeHrp2azQPGogOv+HeQaVEXC2dk=
 golang.org/x/exp v0.0.0-20231006140011-7918f672742d h1:jtJma62tbqLibJ5sFQz8bKtEM8rJBtfilJ2qTU199MI=
 golang.org/x/exp v0.0.0-20231006140011-7918f672742d/go.mod h1:ldy0pHrwJyGW56pPQzzkH36rKxoZW1tw7ZJpeKx+hdo=
-golang.org/x/net v0.53.0 h1:d+qAbo5L0orcWAr0a9JweQpjXF19LMXJE8Ey7hwOdUA=
-golang.org/x/net v0.53.0/go.mod h1:JvMuJH7rrdiCfbeHoo3fCQU24Lf5JJwT9W3sJFulfgs=
-golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
-golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/net v0.56.0 h1:Rw8j/hFzGvJUZwNBXnAtf5sVDVt+65SK2C7IxCxZt5o=
+golang.org/x/net v0.56.0/go.mod h1:D3Ku6r+V6JROoZK144D2XfMHFcMq/0zSfLelVTCFKec=
+golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
+golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
 golang.org/x/sys v0.0.0-20190916202348-b4ddaad3f8a3/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20201204225414-ed752295db88/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210616094352-59db8d763f22/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20210809222454-d867a43fc93e/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.1.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.44.0 h1:ildZl3J4uzeKP07r2F++Op7E9B29JRUy+a27EibtBTQ=
-golang.org/x/sys v0.44.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
-golang.org/x/term v0.43.0 h1:S4RLU2sB31O/NCl+zFN9Aru9A/Cq2aqKpTZJ6B+DwT4=
-golang.org/x/term v0.43.0/go.mod h1:lrhlHNdQJHO+1qVYiHfFKVuVioJIheAc3fBSMFYEIsk=
-golang.org/x/text v0.37.0 h1:Cqjiwd9eSg8e0QAkyCaQTNHFIIzWtidPahFWR83rTrc=
-golang.org/x/text v0.37.0/go.mod h1:a5sjxXGs9hsn/AJVwuElvCAo9v8QYLzvavO5z2PiM38=
+golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
+golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/term v0.45.0 h1:NwWyBmoJCbfTHpxrWoZ9C6/VxOf7ic219I8xZZFdrf0=
+golang.org/x/term v0.45.0/go.mod h1:9aqxs0blBcrm/n0L9QW0aRVD+ktan8ssZromtqJC43w=
+golang.org/x/text v0.40.0 h1:Ub2Z6/xjgF1WrYQz2nuITOEegKFtiIy+rieRJ5lHZKs=
+golang.org/x/text v0.40.0/go.mod h1:hpnzDAfGV753zIKo+wk3u1bVKCGPbrnF7+7LBF/UHVY=
 golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
 golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=
-golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=

internal/api/v2/errorpaths_test.go

@@ -57,7 +57,7 @@ func do(t *testing.T, h http.Handler, method, path, body string) int {
 }
 
 func TestRemotesErrorPaths(t *testing.T) {
-	h := NewRemotesHandler(closedDB(t), nil).Routes()
+	h := NewRemotesHandler(closedDB(t), nil, nil).Routes()
 	if c := do(t, h, "GET", "/", ""); c != 500 {
 		t.Errorf("list with dead db = %d, want 500", c)
 	}

internal/api/v2/remotes.go

@@ -1,8 +1,10 @@
 package v2
 
 import (
+	"context"
 	"encoding/json"
 	"fmt"
+	"log/slog"
 	"net/http"
 
 	"github.com/go-chi/chi/v5"
@@ -12,18 +14,28 @@ import (
 )
 
 // Primer enqueues a background metadata prime for a newly created remote so the
-// create call never blocks on a derive. *rpm.Syncer satisfies it.
+// create call never blocks on a derive. *rpm.Syncer and *deb.Syncer satisfy it.
 type Primer interface {
 	EnqueuePrime(remote models.Remote)
 }
 
-type RemotesHandler struct {
-	db     *database.DB
-	primer Primer
+// MetadataFlusher purges a remote's cached mutable metadata (repodata / Release
+// / APKINDEX freshness keys). *cache.Redis satisfies it.
+type MetadataFlusher interface {
+	FlushRemote(ctx context.Context, remote string) error
 }
 
-func NewRemotesHandler(db *database.DB, primer Primer) *RemotesHandler {
-	return &RemotesHandler{db: db, primer: primer}
+type RemotesHandler struct {
+	db      *database.DB
+	cache   MetadataFlusher
+	primers map[models.PackageType]Primer
+}
+
+// NewRemotesHandler wires the handler to the metadata cache and per-type
+// primers. cache may be nil (flush-on-backend-change is skipped); primers may
+// be nil (a package type with no registered primer simply skips priming).
+func NewRemotesHandler(db *database.DB, cache MetadataFlusher, primers map[models.PackageType]Primer) *RemotesHandler {
+	return &RemotesHandler{db: db, cache: cache, primers: primers}
 }
 
 func (h *RemotesHandler) Routes() chi.Router {
@@ -76,6 +88,14 @@ func (h *RemotesHandler) create(w http.ResponseWriter, r *http.Request) {
 		http.Error(w, "base_url is required for remote repositories", http.StatusBadRequest)
 		return
 	}
+	if err := remote.ValidateMirrorlist(); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+	if err := remote.ValidateMirrorStrategy(); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
 	if err := remote.ValidatePatterns(); err != nil {
 		http.Error(w, err.Error(), http.StatusBadRequest)
 		return
@@ -84,10 +104,10 @@ func (h *RemotesHandler) create(w http.ResponseWriter, r *http.Request) {
 		http.Error(w, err.Error(), http.StatusInternalServerError)
 		return
 	}
-	// Prime a github_rpm remote's metadata in the background so its first
-	// repodata request is served from cache instead of a cold on-demand derive.
-	if h.primer != nil && remote.PackageType == models.PackageGitHubRPM {
-		h.primer.EnqueuePrime(remote)
+	// Prime a metadata-only remote (github_rpm/github_deb) in the background so
+	// its first index request is served from cache instead of a cold derive.
+	if primer := h.primers[remote.PackageType]; primer != nil {
+		primer.EnqueuePrime(remote)
 	}
 	writeJSON(w, http.StatusCreated, remote)
 }
@@ -100,14 +120,42 @@ func (h *RemotesHandler) update(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 	remote.Name = name
+	if err := remote.ValidateMirrorlist(); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+	if err := remote.ValidateMirrorStrategy(); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
 	if err := remote.ValidatePatterns(); err != nil {
 		http.Error(w, err.Error(), http.StatusBadRequest)
 		return
 	}
+	// Capture the current backend before the update so we can tell whether the
+	// remote's base_url (its upstream) changed. A read failure just means we
+	// skip the freshness flush; it must not block the update.
+	oldBaseURL, oldKnown := "", false
+	if existing, err := h.db.GetRemote(r.Context(), name); err == nil {
+		oldBaseURL, oldKnown = existing.BaseURL, true
+	}
 	if err := h.db.UpdateRemote(r.Context(), &remote); err != nil {
 		http.Error(w, err.Error(), http.StatusInternalServerError)
 		return
 	}
+	// Changing the backend invalidates any cached mutable metadata (repodata /
+	// Release / APKINDEX): purge it so the next request re-fetches from the new
+	// upstream instead of serving stale data until TTL expiry. A flush failure
+	// is logged but does not fail the request — the DB update already landed.
+	if oldKnown && oldBaseURL != remote.BaseURL && h.cache != nil {
+		if err := h.cache.FlushRemote(r.Context(), name); err != nil {
+			slog.Warn("flush cached metadata after base_url change failed",
+				"remote", name, "error", err)
+		} else {
+			slog.Info("flushed cached metadata after base_url change",
+				"remote", name, "old_base_url", oldBaseURL, "new_base_url", remote.BaseURL)
+		}
+	}
 	writeJSON(w, http.StatusOK, remote)
 }
 

internal/api/v2/remotes_flush_test.go

@@ -0,0 +1,96 @@
+package v2
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"git.unkin.net/unkin/artifactapi/internal/database"
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+// fakeFlusher records FlushRemote calls so a test can assert whether — and how
+// often — a remote's cached metadata was purged.
+type fakeFlusher struct {
+	calls []string
+	err   error
+}
+
+func (f *fakeFlusher) FlushRemote(_ context.Context, remote string) error {
+	f.calls = append(f.calls, remote)
+	return f.err
+}
+
+func seedRemote(t *testing.T, db *database.DB, name, baseURL string) {
+	t.Helper()
+	err := db.CreateRemote(context.Background(), &models.Remote{
+		Name:        name,
+		PackageType: models.PackageRPM,
+		RepoType:    models.RepoTypeRemote,
+		BaseURL:     baseURL,
+	})
+	if err != nil {
+		t.Fatalf("seed remote: %v", err)
+	}
+}
+
+// A base_url change must flush the remote's cached metadata exactly once, while
+// an update that leaves base_url untouched must not flush at all.
+func TestUpdateFlushesCacheOnBaseURLChange(t *testing.T) {
+	if testDSN == "" {
+		t.Skip("Docker unavailable")
+	}
+	db, err := database.New(testDSN)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer db.Close()
+
+	const name = "rpm-flush-change"
+	seedRemote(t, db, name, "https://old.example.com/repo")
+
+	ff := &fakeFlusher{}
+	h := NewRemotesHandler(db, ff, nil).Routes()
+
+	if c := do(t, h, "PUT", "/"+name, `{"package_type":"rpm","repo_type":"remote","base_url":"https://new.example.com/repo"}`); c != 200 {
+		t.Fatalf("update (backend change) = %d, want 200", c)
+	}
+	if len(ff.calls) != 1 || ff.calls[0] != name {
+		t.Fatalf("flush calls = %v, want exactly one flush of %q", ff.calls, name)
+	}
+
+	// Re-updating with the same (now current) base_url must not flush again.
+	ff.calls = nil
+	if c := do(t, h, "PUT", "/"+name, `{"package_type":"rpm","repo_type":"remote","base_url":"https://new.example.com/repo"}`); c != 200 {
+		t.Fatalf("update (no backend change) = %d, want 200", c)
+	}
+	if len(ff.calls) != 0 {
+		t.Fatalf("flush calls = %v, want no flush when base_url is unchanged", ff.calls)
+	}
+}
+
+// A flush error must be swallowed: the DB update already succeeded, so the
+// request still returns 200.
+func TestUpdateFlushFailureStillSucceeds(t *testing.T) {
+	if testDSN == "" {
+		t.Skip("Docker unavailable")
+	}
+	db, err := database.New(testDSN)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer db.Close()
+
+	const name = "rpm-flush-error"
+	seedRemote(t, db, name, "https://old.example.com/repo")
+
+	ff := &fakeFlusher{err: errors.New("redis down")}
+	h := NewRemotesHandler(db, ff, nil).Routes()
+
+	if c := do(t, h, "PUT", "/"+name, `{"package_type":"rpm","repo_type":"remote","base_url":"https://new.example.com/repo"}`); c != 200 {
+		t.Fatalf("update with failing flush = %d, want 200", c)
+	}
+	if len(ff.calls) != 1 {
+		t.Fatalf("flush calls = %v, want exactly one attempted flush", ff.calls)
+	}
+}

internal/database/alpine_github_sync.go

@@ -0,0 +1,71 @@
+package database
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"github.com/jackc/pgx/v5"
+
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+// ListGitHubAlpineRemotes returns every github_alpine remote so the syncer can
+// sweep them on each poll tick.
+func (db *DB) ListGitHubAlpineRemotes(ctx context.Context) ([]models.Remote, error) {
+	rows, err := db.Pool.Query(ctx, `SELECT `+remoteCols+` FROM remotes WHERE package_type = $1 ORDER BY name`, models.PackageGitHubAlpine)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var remotes []models.Remote
+	for rows.Next() {
+		var r models.Remote
+		if err := scanRemote(rows, &r); err != nil {
+			return nil, err
+		}
+		remotes = append(remotes, r)
+	}
+	return remotes, rows.Err()
+}
+
+// ClaimGitHubAlpineSyncLease atomically claims the per-remote sync lease. It
+// succeeds only when the remote is due (never synced, or synced longer than
+// freshness ago) and no live lease is held by another replica. A zero freshness
+// (prime scans) ignores the recency gate. The returned etag is the stored
+// releases-list ETag, shared across replicas.
+func (db *DB) ClaimGitHubAlpineSyncLease(ctx context.Context, remoteName, owner string, freshness, lease time.Duration) (bool, string, error) {
+	row := db.Pool.QueryRow(ctx, `
+		INSERT INTO github_alpine_sync_state AS s (remote_name, sync_lease_owner, sync_lease_expires)
+		VALUES ($1, $2, now() + make_interval(secs => $4))
+		ON CONFLICT (remote_name) DO UPDATE
+			SET sync_lease_owner   = $2,
+			    sync_lease_expires = now() + make_interval(secs => $4)
+			WHERE (s.last_synced_at IS NULL OR s.last_synced_at < now() - make_interval(secs => $3))
+			  AND (s.sync_lease_expires IS NULL OR s.sync_lease_expires < now())
+		RETURNING s.etag
+	`, remoteName, owner, freshness.Seconds(), lease.Seconds())
+
+	var etag string
+	if err := row.Scan(&etag); err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return false, "", nil
+		}
+		return false, "", err
+	}
+	return true, etag, nil
+}
+
+// ReleaseGitHubAlpineSyncLease records the completed scan and frees the lease.
+// Only the owning replica may release; last_synced_at advances so the next poll
+// waits a full freshness window, and etag is persisted for the next conditional
+// request.
+func (db *DB) ReleaseGitHubAlpineSyncLease(ctx context.Context, remoteName, owner, etag string, syncedAt time.Time) error {
+	_, err := db.Pool.Exec(ctx, `
+		UPDATE github_alpine_sync_state
+		   SET last_synced_at = $3, etag = $4, sync_lease_owner = '', sync_lease_expires = NULL
+		 WHERE remote_name = $1 AND sync_lease_owner = $2
+	`, remoteName, owner, syncedAt, etag)
+	return err
+}

internal/database/alpine_metadata.go

@@ -0,0 +1,70 @@
+package database
+
+import (
+	"context"
+	"strings"
+
+	"git.unkin.net/unkin/artifactapi/internal/provider"
+)
+
+func (db *DB) InsertAlpineMetadata(ctx context.Context, meta *provider.AlpineMetadata) error {
+	_, err := db.Pool.Exec(ctx, `
+		INSERT INTO alpine_metadata (
+			repo_name, file_path, content_hash, checksum,
+			name, version, arch, download_size, installed_size,
+			description, url, license, origin, maintainer,
+			build_time, commit_hash, provider_priority,
+			depends, provides, install_if
+		) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19,$20)
+		ON CONFLICT (repo_name, file_path) DO NOTHING
+	`,
+		meta.RepoName, meta.FilePath, meta.ContentHash, meta.Checksum,
+		meta.Name, meta.Version, meta.Arch, meta.DownloadSize, meta.InstalledSize,
+		meta.Description, meta.URL, meta.License, meta.Origin, meta.Maintainer,
+		meta.BuildTime, meta.Commit, meta.ProviderPriority,
+		strings.Join(meta.Depends, " "), strings.Join(meta.Provides, " "), strings.Join(meta.InstallIf, " "),
+	)
+	return err
+}
+
+func (db *DB) DeleteAlpineMetadata(ctx context.Context, repoName, filePath string) error {
+	_, err := db.Pool.Exec(ctx, `DELETE FROM alpine_metadata WHERE repo_name = $1 AND file_path = $2`, repoName, filePath)
+	return err
+}
+
+func (db *DB) ListAlpineMetadataEntries(ctx context.Context, repoName string) ([]provider.AlpineMetadata, error) {
+	rows, err := db.Pool.Query(ctx, `
+		SELECT repo_name, file_path, content_hash, checksum,
+			name, version, arch, download_size, installed_size,
+			description, url, license, origin, maintainer,
+			build_time, commit_hash, provider_priority,
+			depends, provides, install_if
+		FROM alpine_metadata
+		WHERE repo_name = $1
+		ORDER BY name, version, arch, file_path
+	`, repoName)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var result []provider.AlpineMetadata
+	for rows.Next() {
+		var m provider.AlpineMetadata
+		var depends, provides, installIf string
+		if err := rows.Scan(
+			&m.RepoName, &m.FilePath, &m.ContentHash, &m.Checksum,
+			&m.Name, &m.Version, &m.Arch, &m.DownloadSize, &m.InstalledSize,
+			&m.Description, &m.URL, &m.License, &m.Origin, &m.Maintainer,
+			&m.BuildTime, &m.Commit, &m.ProviderPriority,
+			&depends, &provides, &installIf,
+		); err != nil {
+			return nil, err
+		}
+		m.Depends = strings.Fields(depends)
+		m.Provides = strings.Fields(provides)
+		m.InstallIf = strings.Fields(installIf)
+		result = append(result, m)
+	}
+	return result, rows.Err()
+}

internal/database/database_test.go

@@ -99,6 +99,53 @@ func TestRemotesCRUD(t *testing.T) {
 	}
 }
 
+func TestRemoteMirrorlistRoundTrip(t *testing.T) {
+	requireDB(t)
+	mirrors := []string{"https://b.example", "https://c.example"}
+	if err := testDB.CreateRemote(ctx(), &models.Remote{
+		Name: "r-mirror", PackageType: models.PackageRPM, RepoType: models.RepoTypeRemote,
+		BaseURL: "https://a.example", Mirrorlist: mirrors, MutableTTL: 3600,
+	}); err != nil {
+		t.Fatalf("create mirrorlist remote: %v", err)
+	}
+	defer testDB.DeleteRemote(ctx(), "r-mirror")
+
+	got, err := testDB.GetRemote(ctx(), "r-mirror")
+	if err != nil {
+		t.Fatalf("get: %v", err)
+	}
+	if got.BaseURL != "https://a.example" {
+		t.Fatalf("BaseURL = %q, want https://a.example", got.BaseURL)
+	}
+	if len(got.Mirrorlist) != 2 || got.Mirrorlist[0] != mirrors[0] || got.Mirrorlist[1] != mirrors[1] {
+		t.Fatalf("Mirrorlist round-trip = %v, want %v", got.Mirrorlist, mirrors)
+	}
+	// An unset strategy is stored as the round_robin default.
+	if got.MirrorStrategy != models.MirrorStrategyRoundRobin {
+		t.Fatalf("MirrorStrategy default = %q, want %q", got.MirrorStrategy, models.MirrorStrategyRoundRobin)
+	}
+
+	// Updating to least_conn round-trips.
+	got.MirrorStrategy = models.MirrorStrategyLeastConn
+	if err := testDB.UpdateRemote(ctx(), got); err != nil {
+		t.Fatalf("update to least_conn: %v", err)
+	}
+	got, _ = testDB.GetRemote(ctx(), "r-mirror")
+	if got.MirrorStrategy != models.MirrorStrategyLeastConn {
+		t.Fatalf("MirrorStrategy after update = %q, want least_conn", got.MirrorStrategy)
+	}
+
+	// Clearing the mirrorlist on update persists an empty list.
+	got.Mirrorlist = nil
+	if err := testDB.UpdateRemote(ctx(), got); err != nil {
+		t.Fatalf("update clearing mirrorlist: %v", err)
+	}
+	got, _ = testDB.GetRemote(ctx(), "r-mirror")
+	if len(got.Mirrorlist) != 0 {
+		t.Fatalf("mirrorlist after clear = %v, want empty", got.Mirrorlist)
+	}
+}
+
 func TestArtifactsAndBlobs(t *testing.T) {
 	requireDB(t)
 	seedRemote(t, "r-art")

internal/database/deb_github_sync.go

@@ -0,0 +1,70 @@
+package database
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"github.com/jackc/pgx/v5"
+
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+// ListGitHubDebRemotes returns every github_deb remote so the syncer can sweep
+// them on each poll tick.
+func (db *DB) ListGitHubDebRemotes(ctx context.Context) ([]models.Remote, error) {
+	rows, err := db.Pool.Query(ctx, `SELECT `+remoteCols+` FROM remotes WHERE package_type = $1 ORDER BY name`, models.PackageGitHubDeb)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var remotes []models.Remote
+	for rows.Next() {
+		var r models.Remote
+		if err := scanRemote(rows, &r); err != nil {
+			return nil, err
+		}
+		remotes = append(remotes, r)
+	}
+	return remotes, rows.Err()
+}
+
+// ClaimGitHubDebSyncLease atomically claims the per-remote sync lease. It
+// succeeds only when the remote is due (never synced, or synced longer than
+// freshness ago) and no live lease is held by another replica. A zero freshness
+// (prime scans) ignores the recency gate. The returned etag is the stored
+// releases-list ETag, shared across replicas.
+func (db *DB) ClaimGitHubDebSyncLease(ctx context.Context, remoteName, owner string, freshness, lease time.Duration) (bool, string, error) {
+	row := db.Pool.QueryRow(ctx, `
+		INSERT INTO github_deb_sync_state AS s (remote_name, sync_lease_owner, sync_lease_expires)
+		VALUES ($1, $2, now() + make_interval(secs => $4))
+		ON CONFLICT (remote_name) DO UPDATE
+			SET sync_lease_owner   = $2,
+			    sync_lease_expires = now() + make_interval(secs => $4)
+			WHERE (s.last_synced_at IS NULL OR s.last_synced_at < now() - make_interval(secs => $3))
+			  AND (s.sync_lease_expires IS NULL OR s.sync_lease_expires < now())
+		RETURNING s.etag
+	`, remoteName, owner, freshness.Seconds(), lease.Seconds())
+
+	var etag string
+	if err := row.Scan(&etag); err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return false, "", nil
+		}
+		return false, "", err
+	}
+	return true, etag, nil
+}
+
+// ReleaseGitHubDebSyncLease records the completed scan and frees the lease. Only
+// the owning replica may release; last_synced_at advances so the next poll waits
+// a full freshness window, and etag is persisted for the next conditional request.
+func (db *DB) ReleaseGitHubDebSyncLease(ctx context.Context, remoteName, owner, etag string, syncedAt time.Time) error {
+	_, err := db.Pool.Exec(ctx, `
+		UPDATE github_deb_sync_state
+		   SET last_synced_at = $3, etag = $4, sync_lease_owner = '', sync_lease_expires = NULL
+		 WHERE remote_name = $1 AND sync_lease_owner = $2
+	`, remoteName, owner, syncedAt, etag)
+	return err
+}

internal/database/deb_github_sync_test.go

@@ -0,0 +1,90 @@
+package database
+
+import (
+	"testing"
+	"time"
+
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+func seedGitHubDebRemote(t *testing.T, name string) {
+	t.Helper()
+	if err := testDB.CreateRemote(ctx(), &models.Remote{
+		Name: name, PackageType: models.PackageGitHubDeb, RepoType: models.RepoTypeRemote,
+		BaseURL: "https://api.github.com/repos/acme/tools", ReleasesRemote: "github", MutableTTL: 3600,
+	}); err != nil {
+		t.Fatalf("seed github_deb remote: %v", err)
+	}
+}
+
+// TestGitHubDebSyncLease exercises the real SQL: exactly one replica may hold the
+// lease, the recency window blocks a too-soon periodic re-claim, and a prime
+// (freshness 0) bypasses recency but still respects a live lease.
+func TestGitHubDebSyncLease(t *testing.T) {
+	requireDB(t)
+	name := "ghdeb-lease-" + time.Now().Format("150405.000000")
+	seedGitHubDebRemote(t, name)
+
+	const lease = 15 * time.Minute
+	freshness := time.Hour
+
+	claimed, etag, err := testDB.ClaimGitHubDebSyncLease(ctx(), name, "replica-1", freshness, lease)
+	if err != nil || !claimed {
+		t.Fatalf("replica-1 first claim: claimed=%v err=%v", claimed, err)
+	}
+	if etag != "" {
+		t.Fatalf("initial etag should be empty, got %q", etag)
+	}
+
+	claimed2, _, err := testDB.ClaimGitHubDebSyncLease(ctx(), name, "replica-2", freshness, lease)
+	if err != nil {
+		t.Fatalf("replica-2 claim err: %v", err)
+	}
+	if claimed2 {
+		t.Fatal("replica-2 claimed while replica-1 holds the lease")
+	}
+
+	if err := testDB.ReleaseGitHubDebSyncLease(ctx(), name, "replica-1", `"etag-1"`, time.Now()); err != nil {
+		t.Fatalf("release: %v", err)
+	}
+
+	claimed3, _, err := testDB.ClaimGitHubDebSyncLease(ctx(), name, "replica-2", freshness, lease)
+	if err != nil {
+		t.Fatalf("replica-2 recency claim err: %v", err)
+	}
+	if claimed3 {
+		t.Fatal("periodic claim succeeded inside the freshness window")
+	}
+
+	claimed4, etag4, err := testDB.ClaimGitHubDebSyncLease(ctx(), name, "replica-2", 0, lease)
+	if err != nil || !claimed4 {
+		t.Fatalf("prime claim: claimed=%v err=%v", claimed4, err)
+	}
+	if etag4 != `"etag-1"` {
+		t.Fatalf("prime claim etag = %q, want persisted \"etag-1\"", etag4)
+	}
+}
+
+func TestListGitHubDebRemotes(t *testing.T) {
+	requireDB(t)
+	name := "ghdeb-list-" + time.Now().Format("150405.000000")
+	seedGitHubDebRemote(t, name)
+	seedRemote(t, "generic-"+time.Now().Format("150405.000000"))
+
+	remotes, err := testDB.ListGitHubDebRemotes(ctx())
+	if err != nil {
+		t.Fatalf("list: %v", err)
+	}
+	found := false
+	for _, r := range remotes {
+		if r.PackageType != models.PackageGitHubDeb {
+			t.Fatalf("non-github_deb remote returned: %s (%s)", r.Name, r.PackageType)
+		}
+		if r.Name == name {
+			found = true
+		}
+	}
+	if !found {
+		t.Fatalf("seeded remote %q not returned", name)
+	}
+}

internal/database/deb_metadata.go

@@ -0,0 +1,57 @@
+package database
+
+import (
+	"context"
+
+	"git.unkin.net/unkin/artifactapi/internal/provider"
+)
+
+func (db *DB) InsertDebMetadata(ctx context.Context, meta *provider.DebMetadata) error {
+	_, err := db.Pool.Exec(ctx, `
+		INSERT INTO deb_metadata (
+			repo_name, file_path, content_hash,
+			name, version, architecture, control,
+			size, md5, sha256
+		) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10)
+		ON CONFLICT (repo_name, file_path) DO NOTHING
+	`,
+		meta.RepoName, meta.FilePath, meta.ContentHash,
+		meta.Name, meta.Version, meta.Architecture, meta.Control,
+		meta.Size, meta.MD5, meta.SHA256,
+	)
+	return err
+}
+
+func (db *DB) DeleteDebMetadata(ctx context.Context, repoName, filePath string) error {
+	_, err := db.Pool.Exec(ctx, `DELETE FROM deb_metadata WHERE repo_name = $1 AND file_path = $2`, repoName, filePath)
+	return err
+}
+
+func (db *DB) ListDebMetadataEntries(ctx context.Context, repoName string) ([]provider.DebMetadata, error) {
+	rows, err := db.Pool.Query(ctx, `
+		SELECT repo_name, file_path, content_hash,
+			name, version, architecture, control,
+			size, md5, sha256, created_at
+		FROM deb_metadata
+		WHERE repo_name = $1
+		ORDER BY name, version, architecture, file_path
+	`, repoName)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var result []provider.DebMetadata
+	for rows.Next() {
+		var m provider.DebMetadata
+		if err := rows.Scan(
+			&m.RepoName, &m.FilePath, &m.ContentHash,
+			&m.Name, &m.Version, &m.Architecture, &m.Control,
+			&m.Size, &m.MD5, &m.SHA256, &m.CreatedAt,
+		); err != nil {
+			return nil, err
+		}
+		result = append(result, m)
+	}
+	return result, rows.Err()
+}

internal/database/migrations_test.go

@@ -0,0 +1,162 @@
+package database
+
+import (
+	"context"
+	"io/fs"
+	"maps"
+	"os"
+	"path/filepath"
+	"regexp"
+	"slices"
+	"strings"
+	"testing"
+
+	"git.unkin.net/unkin/golib/pg"
+
+	"git.unkin.net/unkin/artifactapi/migrations"
+)
+
+// migrationsDir is the repo's migrations/ directory, relative to this package.
+const migrationsDir = "../../migrations"
+
+func readMigrationsFromDisk(t *testing.T) map[string]string {
+	t.Helper()
+	entries, err := os.ReadDir(migrationsDir)
+	if err != nil {
+		t.Fatalf("read %s: %v", migrationsDir, err)
+	}
+	files := map[string]string{}
+	for _, e := range entries {
+		if e.IsDir() || !strings.HasSuffix(e.Name(), ".sql") {
+			continue
+		}
+		b, err := os.ReadFile(filepath.Join(migrationsDir, e.Name()))
+		if err != nil {
+			t.Fatalf("read %s: %v", e.Name(), err)
+		}
+		files[e.Name()] = string(b)
+	}
+	if len(files) == 0 {
+		t.Fatalf("no .sql files in %s", migrationsDir)
+	}
+	return files
+}
+
+// The embedded set is the shipped schema, so it must match the migrations/
+// directory exactly — a file added on disk but not embedded would never run.
+func TestEmbeddedMigrationsMatchDirectory(t *testing.T) {
+	onDisk := readMigrationsFromDisk(t)
+	entries, err := fs.ReadDir(migrations.FS, ".")
+	if err != nil {
+		t.Fatalf("read embedded migrations: %v", err)
+	}
+	embedded := map[string]string{}
+	for _, e := range entries {
+		if e.IsDir() || !strings.HasSuffix(e.Name(), ".sql") {
+			continue
+		}
+		b, err := migrations.FS.ReadFile(e.Name())
+		if err != nil {
+			t.Fatalf("read embedded %s: %v", e.Name(), err)
+		}
+		embedded[e.Name()] = string(b)
+	}
+	if len(embedded) != len(onDisk) {
+		t.Fatalf("embedded %d files, migrations/ has %d", len(embedded), len(onDisk))
+	}
+	for name, body := range embedded {
+		want, ok := onDisk[name]
+		if !ok {
+			t.Errorf("%s is embedded but not in migrations/", name)
+			continue
+		}
+		if body != want {
+			t.Errorf("%s: embedded body differs from migrations/%s", name, name)
+		}
+	}
+}
+
+var (
+	createTableRe = regexp.MustCompile(`(?i)\bCREATE\s+TABLE\b(\s+IF\s+NOT\s+EXISTS\b)?`)
+	createIndexRe = regexp.MustCompile(`(?i)\bCREATE\s+(UNIQUE\s+)?INDEX\b(\s+IF\s+NOT\s+EXISTS\b)?`)
+	addColumnRe   = regexp.MustCompile(`(?i)\bADD\s+COLUMN\b(\s+IF\s+NOT\s+EXISTS\b)?`)
+	destructiveRe = regexp.MustCompile(`(?i)\b(DROP\s+(TABLE|COLUMN|INDEX)|TRUNCATE|DELETE\s+FROM)\b`)
+)
+
+// A migration absent from schema_migrations is re-run even when the live
+// database already has the schema, which is exactly how the deployed database —
+// migrated for years by an untracked inline DDL blob — picks 0001 up. Every
+// statement must therefore be idempotent, or that first tracked run would fail
+// against production.
+func TestMigrationsAreIdempotent(t *testing.T) {
+	for name, body := range readMigrationsFromDisk(t) {
+		for _, m := range createTableRe.FindAllStringSubmatch(body, -1) {
+			if m[1] == "" {
+				t.Errorf("%s: %q is not IF NOT EXISTS-guarded", name, strings.Join(strings.Fields(m[0]), " "))
+			}
+		}
+		for _, m := range createIndexRe.FindAllStringSubmatch(body, -1) {
+			if m[2] == "" {
+				t.Errorf("%s: %q is not IF NOT EXISTS-guarded", name, strings.Join(strings.Fields(m[0]), " "))
+			}
+		}
+		for _, m := range addColumnRe.FindAllStringSubmatch(body, -1) {
+			if m[1] == "" {
+				t.Errorf("%s: %q is not IF NOT EXISTS-guarded", name, strings.Join(strings.Fields(m[0]), " "))
+			}
+		}
+		if loc := destructiveRe.FindString(body); loc != "" {
+			t.Errorf("%s: destructive statement %q; migrations are additive", name, loc)
+		}
+	}
+}
+
+// The deployed database was built by the untracked inline DDL this runner
+// replaces, so its very first tracked start runs 0001 against a schema that
+// already exists. Reproduce that by dropping the tracking row from an
+// already-migrated database and starting again: it must succeed and re-record
+// the version, changing nothing else.
+func TestMigratingAnAlreadyPopulatedSchemaIsANoOp(t *testing.T) {
+	requireDB(t)
+	c := context.Background()
+
+	if _, err := testDB.Pool.Exec(c, "DELETE FROM schema_migrations"); err != nil {
+		t.Fatalf("clear schema_migrations: %v", err)
+	}
+	db, err := New(testDSN)
+	if err != nil {
+		t.Fatalf("migrate over an existing schema: %v", err)
+	}
+	defer db.Close()
+
+	var versions []string
+	rows, err := db.Pool.Query(c, "SELECT version FROM schema_migrations ORDER BY version")
+	if err != nil {
+		t.Fatalf("read schema_migrations: %v", err)
+	}
+	defer rows.Close()
+	for rows.Next() {
+		var v string
+		if err := rows.Scan(&v); err != nil {
+			t.Fatalf("scan version: %v", err)
+		}
+		versions = append(versions, v)
+	}
+	if err := rows.Err(); err != nil {
+		t.Fatalf("read schema_migrations: %v", err)
+	}
+
+	want := slices.Sorted(maps.Keys(readMigrationsFromDisk(t)))
+	if !slices.Equal(versions, want) {
+		t.Fatalf("schema_migrations = %v, want %v", versions, want)
+	}
+}
+
+// The advisory lock key is derived from migrationLockName by golib. Pin it so a
+// rename cannot silently let two builds migrate the same cluster at once.
+func TestMigrationLockKeyIsPinned(t *testing.T) {
+	const wantKey int64 = -6981019939451326383
+	if got := pg.LockKey(migrationLockName); got != wantKey {
+		t.Fatalf("LockKey(%q) = %d, want %d", migrationLockName, got, wantKey)
+	}
+}

internal/database/postgres.go

@@ -2,182 +2,34 @@ package database
 
 import (
 	"context"
-	"fmt"
 
 	"github.com/jackc/pgx/v5/pgxpool"
+
+	"git.unkin.net/unkin/golib/pg"
+
+	"git.unkin.net/unkin/artifactapi/migrations"
 )
 
+// migrationLockName names the cluster-wide advisory lock the migration run
+// contends for; golib derives the key as FNV-1a/64 of it. Replicas starting
+// together queue on it instead of racing each other through the DDL.
+const migrationLockName = "artifactapi-migrations"
+
 type DB struct {
 	Pool *pgxpool.Pool
 }
 
 func New(dsn string) (*DB, error) {
-	pool, err := pgxpool.New(context.Background(), dsn)
+	ctx := context.Background()
+	pool, err := pg.NewMigrated(ctx, dsn, migrations.FS, pg.MigrateOptions{
+		LockName: migrationLockName,
+	})
 	if err != nil {
-		return nil, fmt.Errorf("connect to postgres: %w", err)
+		return nil, err
 	}
-
-	if err := pool.Ping(context.Background()); err != nil {
-		pool.Close()
-		return nil, fmt.Errorf("ping postgres: %w", err)
-	}
-
-	db := &DB{Pool: pool}
-	if err := db.migrate(); err != nil {
-		pool.Close()
-		return nil, fmt.Errorf("run migrations: %w", err)
-	}
-
-	return db, nil
+	return &DB{Pool: pool}, nil
 }
 
 func (db *DB) Close() {
 	db.Pool.Close()
 }
-
-func (db *DB) migrate() error {
-	ctx := context.Background()
-
-	_, err := db.Pool.Exec(ctx, `
-		CREATE TABLE IF NOT EXISTS remotes (
-			name            TEXT PRIMARY KEY,
-			package_type    TEXT NOT NULL,
-			repo_type       TEXT DEFAULT 'remote',
-			base_url        TEXT NOT NULL DEFAULT '',
-			description     TEXT DEFAULT '',
-			username        TEXT DEFAULT '',
-			password        TEXT DEFAULT '',
-			immutable_ttl   INTEGER DEFAULT 0,
-			mutable_ttl     INTEGER DEFAULT 3600,
-			check_mutable   BOOLEAN DEFAULT TRUE,
-			patterns            TEXT[] DEFAULT '{}',
-			blocklist           TEXT[] DEFAULT '{}',
-			mutable_patterns    TEXT[] DEFAULT '{}',
-			immutable_patterns  TEXT[] DEFAULT '{}',
-			ban_tags_enabled    BOOLEAN DEFAULT FALSE,
-			ban_tags            TEXT[] DEFAULT '{}',
-			quarantine_enabled  BOOLEAN DEFAULT FALSE,
-			quarantine_days     INTEGER DEFAULT 3,
-			stale_on_error      BOOLEAN DEFAULT TRUE,
-			releases_remote     TEXT DEFAULT '',
-			managed_by          TEXT DEFAULT '',
-			created_at      TIMESTAMPTZ DEFAULT NOW(),
-			updated_at      TIMESTAMPTZ DEFAULT NOW()
-		);
-
-		CREATE TABLE IF NOT EXISTS virtuals (
-			name            TEXT PRIMARY KEY,
-			package_type    TEXT NOT NULL,
-			description     TEXT DEFAULT '',
-			members         TEXT[] NOT NULL,
-			managed_by      TEXT DEFAULT '',
-			created_at      TIMESTAMPTZ DEFAULT NOW(),
-			updated_at      TIMESTAMPTZ DEFAULT NOW()
-		);
-
-		CREATE TABLE IF NOT EXISTS blobs (
-			content_hash    TEXT PRIMARY KEY,
-			s3_key          TEXT NOT NULL,
-			size_bytes      BIGINT NOT NULL,
-			content_type    TEXT DEFAULT 'application/octet-stream',
-			created_at      TIMESTAMPTZ DEFAULT NOW()
-		);
-
-		CREATE TABLE IF NOT EXISTS artifacts (
-			id              BIGSERIAL PRIMARY KEY,
-			remote_name     TEXT NOT NULL REFERENCES remotes(name) ON DELETE CASCADE,
-			path            TEXT NOT NULL,
-			content_hash    TEXT NOT NULL REFERENCES blobs(content_hash),
-			upstream_etag   TEXT DEFAULT '',
-			upstream_last_modified TIMESTAMPTZ,
-			first_seen_at   TIMESTAMPTZ DEFAULT NOW(),
-			last_fetched_at TIMESTAMPTZ DEFAULT NOW(),
-			last_accessed_at TIMESTAMPTZ DEFAULT NOW(),
-			fetch_count     BIGINT DEFAULT 1,
-			access_count    BIGINT DEFAULT 1,
-			UNIQUE(remote_name, path)
-		);
-
-		CREATE INDEX IF NOT EXISTS idx_artifacts_remote ON artifacts(remote_name);
-		CREATE INDEX IF NOT EXISTS idx_artifacts_last_accessed ON artifacts(last_accessed_at);
-
-		CREATE TABLE IF NOT EXISTS local_files (
-			id              BIGSERIAL PRIMARY KEY,
-			repo_name       TEXT NOT NULL,
-			file_path       TEXT NOT NULL,
-			content_hash    TEXT NOT NULL REFERENCES blobs(content_hash),
-			created_at      TIMESTAMPTZ DEFAULT NOW(),
-			UNIQUE(repo_name, file_path)
-		);
-
-		CREATE TABLE IF NOT EXISTS access_log (
-			id              BIGSERIAL PRIMARY KEY,
-			remote_name     TEXT NOT NULL,
-			path            TEXT NOT NULL,
-			cache_hit       BOOLEAN NOT NULL,
-			size_bytes      BIGINT DEFAULT 0,
-			upstream_ms     INTEGER DEFAULT 0,
-			client_ip       TEXT DEFAULT '',
-			created_at      TIMESTAMPTZ DEFAULT NOW()
-		);
-
-		CREATE INDEX IF NOT EXISTS idx_access_log_remote_time ON access_log(remote_name, created_at);
-
-		ALTER TABLE remotes ADD COLUMN IF NOT EXISTS repo_type TEXT DEFAULT 'remote';
-		ALTER TABLE remotes ADD COLUMN IF NOT EXISTS upstream_dial_timeout INTEGER DEFAULT 0;
-		ALTER TABLE remotes ADD COLUMN IF NOT EXISTS upstream_tls_timeout INTEGER DEFAULT 0;
-		ALTER TABLE remotes ADD COLUMN IF NOT EXISTS upstream_response_header_timeout INTEGER DEFAULT 0;
-
-		CREATE TABLE IF NOT EXISTS rpm_metadata (
-			id              BIGSERIAL PRIMARY KEY,
-			repo_name       TEXT NOT NULL,
-			file_path       TEXT NOT NULL,
-			content_hash    TEXT NOT NULL,
-			name            TEXT NOT NULL,
-			epoch           INTEGER DEFAULT 0,
-			version         TEXT NOT NULL,
-			release         TEXT NOT NULL,
-			arch            TEXT NOT NULL,
-			summary         TEXT DEFAULT '',
-			description     TEXT DEFAULT '',
-			rpm_size        BIGINT DEFAULT 0,
-			installed_size  BIGINT DEFAULT 0,
-			license         TEXT DEFAULT '',
-			vendor          TEXT DEFAULT '',
-			build_group     TEXT DEFAULT '',
-			build_host      TEXT DEFAULT '',
-			source_rpm      TEXT DEFAULT '',
-			url             TEXT DEFAULT '',
-			packager        TEXT DEFAULT '',
-			requires        JSONB DEFAULT '[]',
-			provides        JSONB DEFAULT '[]',
-			conflicts       JSONB DEFAULT '[]',
-			obsoletes       JSONB DEFAULT '[]',
-			files           JSONB DEFAULT '[]',
-			changelogs      JSONB DEFAULT '[]',
-			created_at      TIMESTAMPTZ DEFAULT NOW(),
-			UNIQUE(repo_name, file_path)
-		);
-
-		CREATE INDEX IF NOT EXISTS idx_rpm_metadata_repo ON rpm_metadata(repo_name);
-
-		ALTER TABLE rpm_metadata ADD COLUMN IF NOT EXISTS conflicts JSONB DEFAULT '[]';
-		ALTER TABLE rpm_metadata ADD COLUMN IF NOT EXISTS obsoletes JSONB DEFAULT '[]';
-
-		CREATE TABLE IF NOT EXISTS github_rpm_sync_state (
-			remote_name        TEXT PRIMARY KEY,
-			etag               TEXT DEFAULT '',
-			last_synced_at     TIMESTAMPTZ,
-			sync_lease_owner   TEXT DEFAULT '',
-			sync_lease_expires TIMESTAMPTZ
-		);
-
-		CREATE TABLE IF NOT EXISTS signing_keys (
-			purpose             TEXT PRIMARY KEY,
-			private_key_armor   TEXT NOT NULL,
-			key_id              TEXT NOT NULL,
-			created_at          TIMESTAMPTZ DEFAULT NOW()
-		);
-	`)
-	return err
-}

internal/database/remotes.go

@@ -6,7 +6,7 @@ import (
 	"git.unkin.net/unkin/artifactapi/pkg/models"
 )
 
-const remoteCols = `name, package_type, repo_type, base_url, description, username, password,
+const remoteCols = `name, package_type, repo_type, base_url, mirrorlist, mirror_strategy, description, username, password,
 	immutable_ttl, mutable_ttl, check_mutable,
 	patterns, blocklist, mutable_patterns, immutable_patterns,
 	ban_tags_enabled, ban_tags,
@@ -15,9 +15,18 @@ const remoteCols = `name, package_type, repo_type, base_url, description, userna
 	upstream_dial_timeout, upstream_tls_timeout, upstream_response_header_timeout,
 	created_at, updated_at`
 
+// normalizeMirrorStrategy maps an empty strategy to the round_robin default so
+// the NOT NULL mirror_strategy column always stores a canonical value.
+func normalizeMirrorStrategy(s string) string {
+	if s == "" {
+		return models.MirrorStrategyRoundRobin
+	}
+	return s
+}
+
 func scanRemote(scanner interface{ Scan(...any) error }, r *models.Remote) error {
 	return scanner.Scan(
-		&r.Name, &r.PackageType, &r.RepoType, &r.BaseURL, &r.Description, &r.Username, &r.Password,
+		&r.Name, &r.PackageType, &r.RepoType, &r.BaseURL, &r.Mirrorlist, &r.MirrorStrategy, &r.Description, &r.Username, &r.Password,
 		&r.ImmutableTTL, &r.MutableTTL, &r.CheckMutable,
 		&r.Patterns, &r.Blocklist, &r.MutablePatterns, &r.ImmutablePatterns,
 		&r.BanTagsEnabled, &r.BanTags,
@@ -58,22 +67,24 @@ func (db *DB) ListRemotes(ctx context.Context) ([]models.Remote, error) {
 func (db *DB) CreateRemote(ctx context.Context, r *models.Remote) error {
 	_, err := db.Pool.Exec(ctx, `
 		INSERT INTO remotes (
-			name, package_type, repo_type, base_url, description, username, password,
+			name, package_type, repo_type, base_url, mirrorlist, description, username, password,
 			immutable_ttl, mutable_ttl, check_mutable,
 			patterns, blocklist, mutable_patterns, immutable_patterns,
 			ban_tags_enabled, ban_tags,
 			quarantine_enabled, quarantine_days, stale_on_error,
 			releases_remote, managed_by,
-			upstream_dial_timeout, upstream_tls_timeout, upstream_response_header_timeout
-		) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19,$20,$21,$22,$23,$24)
+			upstream_dial_timeout, upstream_tls_timeout, upstream_response_header_timeout,
+			mirror_strategy
+		) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19,$20,$21,$22,$23,$24,$25,$26)
 	`,
-		r.Name, r.PackageType, r.RepoType, r.BaseURL, r.Description, r.Username, r.Password,
+		r.Name, r.PackageType, r.RepoType, r.BaseURL, r.Mirrorlist, r.Description, r.Username, r.Password,
 		r.ImmutableTTL, r.MutableTTL, r.CheckMutable,
 		r.Patterns, r.Blocklist, r.MutablePatterns, r.ImmutablePatterns,
 		r.BanTagsEnabled, r.BanTags,
 		r.QuarantineEnabled, r.QuarantineDays, r.StaleOnError,
 		r.ReleasesRemote, r.ManagedBy,
 		r.UpstreamDialTimeout, r.UpstreamTLSTimeout, r.UpstreamResponseHeaderTimeout,
+		normalizeMirrorStrategy(r.MirrorStrategy),
 	)
 	return err
 }
@@ -81,13 +92,14 @@ func (db *DB) CreateRemote(ctx context.Context, r *models.Remote) error {
 func (db *DB) UpdateRemote(ctx context.Context, r *models.Remote) error {
 	_, err := db.Pool.Exec(ctx, `
 		UPDATE remotes SET
-			package_type=$2, repo_type=$3, base_url=$4, description=$5, username=$6, password=$7,
+			package_type=$2, repo_type=$3, base_url=$4, mirrorlist=$25, description=$5, username=$6, password=$7,
 			immutable_ttl=$8, mutable_ttl=$9, check_mutable=$10,
 			patterns=$11, blocklist=$12, mutable_patterns=$13, immutable_patterns=$14,
 			ban_tags_enabled=$15, ban_tags=$16,
 			quarantine_enabled=$17, quarantine_days=$18, stale_on_error=$19,
 			releases_remote=$20, managed_by=$21,
 			upstream_dial_timeout=$22, upstream_tls_timeout=$23, upstream_response_header_timeout=$24,
+			mirror_strategy=$26,
 			updated_at=NOW()
 		WHERE name=$1
 	`,
@@ -98,6 +110,8 @@ func (db *DB) UpdateRemote(ctx context.Context, r *models.Remote) error {
 		r.QuarantineEnabled, r.QuarantineDays, r.StaleOnError,
 		r.ReleasesRemote, r.ManagedBy,
 		r.UpstreamDialTimeout, r.UpstreamTLSTimeout, r.UpstreamResponseHeaderTimeout,
+		r.Mirrorlist,
+		normalizeMirrorStrategy(r.MirrorStrategy),
 	)
 	return err
 }

internal/database/rpm_metadata.go

@@ -3,6 +3,7 @@ package database
 import (
 	"context"
 	"encoding/json"
+	"time"
 
 	"git.unkin.net/unkin/artifactapi/internal/provider"
 )
@@ -65,6 +66,7 @@ type RPMMetadataRow struct {
 	Obsoletes     json.RawMessage
 	Files         json.RawMessage
 	Changelogs    json.RawMessage
+	CreatedAt     time.Time
 }
 
 func (db *DB) ListRPMMetadataEntries(ctx context.Context, repoName string) ([]provider.RPMMetadata, error) {
@@ -94,6 +96,7 @@ func (db *DB) ListRPMMetadataEntries(ctx context.Context, repoName string) ([]pr
 			SourceRPM:     r.SourceRPM,
 			URL:           r.URL,
 			Packager:      r.Packager,
+			CreatedAt:     r.CreatedAt,
 		}
 		json.Unmarshal(r.Requires, &meta.Requires)
 		json.Unmarshal(r.Provides, &meta.Provides)
@@ -112,10 +115,11 @@ func (db *DB) ListRPMMetadata(ctx context.Context, repoName string) ([]RPMMetada
 			name, epoch, version, release, arch,
 			summary, description, rpm_size, installed_size,
 			license, vendor, build_group, build_host, source_rpm, url, packager,
-			requires, provides, conflicts, obsoletes, files, changelogs
+			requires, provides, conflicts, obsoletes, files, changelogs,
+			created_at
 		FROM rpm_metadata
 		WHERE repo_name = $1
-		ORDER BY name, epoch, version, release, arch
+		ORDER BY name, epoch, version, release, arch, file_path
 	`, repoName)
 	if err != nil {
 		return nil, err
@@ -131,6 +135,7 @@ func (db *DB) ListRPMMetadata(ctx context.Context, repoName string) ([]RPMMetada
 			&r.Summary, &r.Description, &r.RPMSize, &r.InstalledSize,
 			&r.License, &r.Vendor, &r.Group, &r.BuildHost, &r.SourceRPM, &r.URL, &r.Packager,
 			&r.Requires, &r.Provides, &r.Conflicts, &r.Obsoletes, &r.Files, &r.Changelogs,
+			&r.CreatedAt,
 		); err != nil {
 			return nil, err
 		}

internal/provider/alpine/alpine.go

@@ -1,12 +1,27 @@
 package alpine
 
 import (
+	"bufio"
+	"bytes"
+	"compress/gzip"
 	"context"
+	"crypto/sha1"
+	"encoding/base64"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
 	"net/http"
+	"path"
+	"strconv"
 	"strings"
+	"time"
+
+	"archive/tar"
 
 	"git.unkin.net/unkin/artifactapi/internal/auth"
 	"git.unkin.net/unkin/artifactapi/internal/provider"
+	"git.unkin.net/unkin/artifactapi/internal/storage"
 	"git.unkin.net/unkin/artifactapi/pkg/models"
 )
 
@@ -46,3 +61,349 @@ func (p *Provider) RewriteResponse(_ []byte, _ models.Remote, _ string) ([]byte,
 func (p *Provider) AuthHeaders(_ context.Context, remote models.Remote) (http.Header, error) {
 	return auth.BasicHeaders(remote), nil
 }
+
+// --- LocalUploader: hosting real .apk packages -----------------------------
+
+// ValidateUpload accepts any *.apk and preserves the client-supplied directory
+// (the arch prefix) as the storage path, since arch cannot be parsed from the
+// filename alone and the generic uploader hands us only the path. apk clients
+// fetch packages at <arch>/<file>.apk, so publishers upload to that same path;
+// AfterUpload records the true arch (from .PKGINFO) for index filtering.
+func (p *Provider) ValidateUpload(filePath string) (storagePath, contentType string, err error) {
+	clean := strings.TrimPrefix(path.Clean("/"+filePath), "/")
+	filename := clean
+	if i := strings.LastIndex(clean, "/"); i >= 0 {
+		filename = clean[i+1:]
+	}
+	if !strings.HasSuffix(strings.ToLower(filename), ".apk") {
+		return "", "", fmt.Errorf("file must be a .apk package")
+	}
+	return clean, "application/vnd.android.package-archive", nil
+}
+
+func (p *Provider) UploadResponse(storagePath, contentHash string, sizeBytes int64) map[string]any {
+	filename := storagePath
+	if i := strings.LastIndex(storagePath, "/"); i >= 0 {
+		filename = storagePath[i+1:]
+	}
+	return map[string]any{
+		"filename":     filename,
+		"content_hash": contentHash,
+		"size_bytes":   sizeBytes,
+	}
+}
+
+func (p *Provider) AfterUpload(ctx context.Context, repoName, storagePath, contentHash string, blobs provider.BlobReader, db provider.MetadataStore) {
+	s3Key := storage.BlobKey(strings.TrimPrefix(contentHash, "sha256:"))
+
+	reader, blobSize, err := blobs.Download(ctx, s3Key)
+	if err != nil {
+		slog.Error("alpine metadata: download failed", "repo", repoName, "path", storagePath, "error", err)
+		return
+	}
+	defer reader.Close()
+
+	raw, err := io.ReadAll(reader)
+	if err != nil {
+		slog.Error("alpine metadata: read failed", "repo", repoName, "path", storagePath, "error", err)
+		return
+	}
+
+	meta, err := parseApk(raw)
+	if err != nil {
+		slog.Error("alpine metadata: parse failed", "repo", repoName, "path", storagePath, "error", err)
+		return
+	}
+	meta.RepoName = repoName
+	meta.FilePath = storagePath
+	meta.ContentHash = contentHash
+	meta.DownloadSize = blobSize
+
+	if meta.Name == "" || meta.Arch == "" {
+		slog.Error("alpine metadata: .PKGINFO missing pkgname/arch", "repo", repoName, "path", storagePath)
+		return
+	}
+
+	store, ok := db.(provider.AlpineMetadataStore)
+	if !ok {
+		slog.Error("alpine metadata: store does not support alpine metadata", "repo", repoName)
+		return
+	}
+	if err := store.InsertAlpineMetadata(ctx, meta); err != nil {
+		slog.Error("alpine metadata: insert failed", "repo", repoName, "path", storagePath, "error", err)
+		return
+	}
+	slog.Info("alpine metadata: parsed", "repo", repoName, "name", meta.Name, "version", meta.Version, "arch", meta.Arch)
+}
+
+func (p *Provider) AfterDelete(ctx context.Context, repoName, storagePath string, db provider.MetadataDeleter) error {
+	deleter, ok := db.(provider.AlpineMetadataDeleter)
+	if !ok {
+		return nil
+	}
+	if err := deleter.DeleteAlpineMetadata(ctx, repoName, storagePath); err != nil {
+		slog.Error("alpine metadata: delete failed", "repo", repoName, "path", storagePath, "error", err)
+		return err
+	}
+	slog.Info("alpine metadata: deleted", "repo", repoName, "path", storagePath)
+	return nil
+}
+
+// --- LocalIndexer: generating a per-arch APKINDEX.tar.gz -------------------
+
+// normalizeIndexPath collapses apk's dot-segment prefix: an /etc/apk/repositories
+// line of "<url>/api/v1/local/<name>" makes apk request "./<arch>/APKINDEX.tar.gz".
+// Mirrors deb's flat-repo normalization.
+func normalizeIndexPath(p string) string {
+	return strings.TrimPrefix(path.Clean("/"+p), "/")
+}
+
+func (p *Provider) ServeLocalIndex(w http.ResponseWriter, r *http.Request, files provider.FileStore, repoName, reqPath string) bool {
+	clean := normalizeIndexPath(reqPath)
+	if !strings.HasSuffix(clean, "APKINDEX.tar.gz") {
+		return false
+	}
+	arch := strings.TrimSuffix(clean, "APKINDEX.tar.gz")
+	arch = strings.Trim(arch, "/")
+	if arch == "" || strings.Contains(arch, "/") {
+		http.Error(w, "APKINDEX must be requested per-arch: <arch>/APKINDEX.tar.gz", http.StatusNotFound)
+		return true
+	}
+
+	reader, ok := files.(provider.AlpineMetadataReader)
+	if !ok {
+		http.Error(w, "alpine metadata not available", http.StatusInternalServerError)
+		return true
+	}
+
+	metas, err := reader.ListAlpineMetadataEntries(r.Context(), repoName)
+	if err != nil {
+		if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
+			slog.Warn("alpine: metadata read canceled", "repo", repoName, "error", err)
+			http.Error(w, "metadata read canceled", http.StatusServiceUnavailable)
+			return true
+		}
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return true
+	}
+
+	var filtered []provider.AlpineMetadata
+	for _, m := range metas {
+		if m.Arch == arch {
+			filtered = append(filtered, m)
+		}
+	}
+
+	w.Header().Set("Content-Type", "application/gzip")
+	w.WriteHeader(http.StatusOK)
+	w.Write(generateAPKIndex(filtered))
+	return true
+}
+
+func (p *Provider) GenerateLocalIndex(ctx context.Context, files provider.FileStore, repoName, path string) ([]byte, error) {
+	return nil, fmt.Errorf("alpine local index generation for virtual repos not supported")
+}
+
+// --- pure-Go .apk parsing --------------------------------------------------
+
+// parseApk reads an .apk (up to three concatenated, independently gzipped tar
+// streams: optional signature, control, data). It locates the control stream by
+// its .PKGINFO member, computes the apk pull checksum C: = "Q1" +
+// base64(sha1(<control gzip stream bytes>)), and reads the .PKGINFO fields.
+func parseApk(raw []byte) (*provider.AlpineMetadata, error) {
+	members, err := gzipMembers(raw)
+	if err != nil {
+		return nil, err
+	}
+
+	for _, m := range members {
+		pkginfo, ok := pkginfoFromTar(m.tar)
+		if !ok {
+			continue
+		}
+		meta := parsePkginfo(pkginfo)
+		sum := sha1.Sum(m.raw)
+		meta.Checksum = "Q1" + base64.StdEncoding.EncodeToString(sum[:])
+		return meta, nil
+	}
+	return nil, errors.New("no .PKGINFO found in any .apk gzip stream")
+}
+
+type gzMember struct {
+	raw []byte // the raw bytes of this gzip stream (for the Q1 checksum)
+	tar []byte // the decompressed tar payload
+}
+
+// gzipMembers splits the concatenated gzip streams, returning each stream's raw
+// bytes alongside its decompressed tar. It relies on bytes.Reader being an
+// io.ByteReader (so compress/gzip does not over-read past a member's trailer)
+// to recover exact stream boundaries via Multistream(false)+Reset.
+func gzipMembers(data []byte) ([]gzMember, error) {
+	br := bytes.NewReader(data)
+	zr, err := gzip.NewReader(br)
+	if err != nil {
+		return nil, err
+	}
+	var members []gzMember
+	prev := 0
+	for {
+		zr.Multistream(false)
+		out, err := io.ReadAll(zr)
+		if err != nil {
+			return nil, err
+		}
+		end := len(data) - br.Len()
+		members = append(members, gzMember{raw: data[prev:end], tar: out})
+		prev = end
+		if err := zr.Reset(br); err != nil {
+			if err == io.EOF {
+				break
+			}
+			return nil, err
+		}
+	}
+	return members, nil
+}
+
+func pkginfoFromTar(tarBytes []byte) (string, bool) {
+	tr := tar.NewReader(bytes.NewReader(tarBytes))
+	for {
+		hdr, err := tr.Next()
+		if err != nil {
+			return "", false
+		}
+		if strings.TrimPrefix(hdr.Name, "./") == ".PKGINFO" {
+			b, err := io.ReadAll(tr)
+			if err != nil {
+				return "", false
+			}
+			return string(b), true
+		}
+	}
+}
+
+// parsePkginfo reads the "key = value" .PKGINFO text, collecting the repeated
+// depend/provides/install_if keys into slices.
+func parsePkginfo(text string) *provider.AlpineMetadata {
+	m := &provider.AlpineMetadata{}
+	sc := bufio.NewScanner(strings.NewReader(text))
+	sc.Buffer(make([]byte, 0, 64*1024), 1024*1024)
+	for sc.Scan() {
+		line := strings.TrimSpace(sc.Text())
+		if line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+		idx := strings.Index(line, "=")
+		if idx < 0 {
+			continue
+		}
+		key := strings.TrimSpace(line[:idx])
+		val := strings.TrimSpace(line[idx+1:])
+		switch key {
+		case "pkgname":
+			m.Name = val
+		case "pkgver":
+			m.Version = val
+		case "arch":
+			m.Arch = val
+		case "pkgdesc":
+			m.Description = val
+		case "url":
+			m.URL = val
+		case "license":
+			m.License = val
+		case "origin":
+			m.Origin = val
+		case "maintainer":
+			m.Maintainer = val
+		case "builddate":
+			if n, err := strconv.ParseInt(val, 10, 64); err == nil {
+				m.BuildTime = n
+			}
+		case "commit":
+			m.Commit = val
+		case "size":
+			if n, err := strconv.ParseInt(val, 10, 64); err == nil {
+				m.InstalledSize = n
+			}
+		case "provider_priority":
+			m.ProviderPriority = val
+		case "depend":
+			if val != "" {
+				m.Depends = append(m.Depends, val)
+			}
+		case "provides":
+			if val != "" {
+				m.Provides = append(m.Provides, val)
+			}
+		case "install_if":
+			if val != "" {
+				m.InstallIf = append(m.InstallIf, val)
+			}
+		}
+	}
+	return m
+}
+
+// generateAPKIndex builds the APKINDEX.tar.gz = gzip(tar(APKINDEX)) for the
+// given (already arch-filtered) rows. Records are blank-line separated; fields
+// follow the canonical C/P/V/A/S/I/T/U/L/o/m/t/c/k/D/p/i order and empties are
+// omitted. Unsigned (clients use --allow-untrusted), matching rpm gpgcheck=0.
+func generateAPKIndex(metas []provider.AlpineMetadata) []byte {
+	var idx bytes.Buffer
+	for i, m := range metas {
+		if i > 0 {
+			idx.WriteString("\n")
+		}
+		writeField(&idx, "C", m.Checksum)
+		writeField(&idx, "P", m.Name)
+		writeField(&idx, "V", m.Version)
+		writeField(&idx, "A", m.Arch)
+		writeField(&idx, "S", intField(m.DownloadSize))
+		writeField(&idx, "I", intField(m.InstalledSize))
+		writeField(&idx, "T", m.Description)
+		writeField(&idx, "U", m.URL)
+		writeField(&idx, "L", m.License)
+		writeField(&idx, "o", m.Origin)
+		writeField(&idx, "m", m.Maintainer)
+		writeField(&idx, "t", intField(m.BuildTime))
+		writeField(&idx, "c", m.Commit)
+		writeField(&idx, "k", m.ProviderPriority)
+		writeField(&idx, "D", strings.Join(m.Depends, " "))
+		writeField(&idx, "p", strings.Join(m.Provides, " "))
+		writeField(&idx, "i", strings.Join(m.InstallIf, " "))
+	}
+
+	var tarBuf bytes.Buffer
+	tw := tar.NewWriter(&tarBuf)
+	body := idx.Bytes()
+	// ModTime is pinned to the Unix epoch (never wall clock) so APKINDEX.tar.gz
+	// is byte-identical across replicas and regenerations (issue #117); apk
+	// clients ignore the tar mtime.
+	tw.WriteHeader(&tar.Header{Name: "APKINDEX", Mode: 0o644, Size: int64(len(body)), Typeflag: tar.TypeReg, ModTime: time.Unix(0, 0)})
+	tw.Write(body)
+	tw.Close()
+
+	var gzBuf bytes.Buffer
+	gz := gzip.NewWriter(&gzBuf)
+	gz.Write(tarBuf.Bytes())
+	gz.Close()
+	return gzBuf.Bytes()
+}
+
+func writeField(b *bytes.Buffer, key, val string) {
+	if val == "" {
+		return
+	}
+	b.WriteString(key)
+	b.WriteString(":")
+	b.WriteString(val)
+	b.WriteString("\n")
+}
+
+func intField(n int64) string {
+	if n == 0 {
+		return ""
+	}
+	return strconv.FormatInt(n, 10)
+}

internal/provider/alpine/alpine_deterministic_test.go

@@ -0,0 +1,72 @@
+package alpine
+
+import (
+	"archive/tar"
+	"bytes"
+	"compress/gzip"
+	"io"
+	"testing"
+	"time"
+
+	"git.unkin.net/unkin/artifactapi/internal/provider"
+)
+
+func apkFixture() []provider.AlpineMetadata {
+	return []provider.AlpineMetadata{
+		{
+			RepoName: "r", FilePath: "x86_64/aaa-1.0-r0.apk", Checksum: "Q1aaa",
+			Name: "aaa", Version: "1.0-r0", Arch: "x86_64", DownloadSize: 100, InstalledSize: 10,
+			Description: "pkg aaa", URL: "https://a", License: "MIT",
+			Depends: []string{"so:libc"}, Provides: []string{"cmd:aaa"}, BuildTime: 1710000000,
+		},
+		{
+			RepoName: "r", FilePath: "x86_64/bbb-2.0-r0.apk", Checksum: "Q1bbb",
+			Name: "bbb", Version: "2.0-r0", Arch: "x86_64", DownloadSize: 200, InstalledSize: 20,
+		},
+	}
+}
+
+// TestAPKIndexDeterministic asserts APKINDEX.tar.gz is byte-identical across two
+// generations separated by wall-clock time, so the two no-affinity replicas and
+// every regeneration serve the same bytes (issue #117).
+func TestAPKIndexDeterministic(t *testing.T) {
+	metas := apkFixture()
+
+	first := generateAPKIndex(metas)
+	time.Sleep(10 * time.Millisecond)
+	second := generateAPKIndex(metas)
+
+	if !bytes.Equal(first, second) {
+		t.Error("APKINDEX.tar.gz differs across generations")
+	}
+}
+
+// TestAPKIndexTarModTimePinned guards the tar header: its ModTime must be the
+// pinned Unix epoch, never wall clock. Fails if a future edit stamps time.Now().
+func TestAPKIndexTarModTimePinned(t *testing.T) {
+	metas := apkFixture()
+
+	zr, err := gzip.NewReader(bytes.NewReader(generateAPKIndex(metas)))
+	if err != nil {
+		t.Fatalf("gzip: %v", err)
+	}
+	if !zr.ModTime.IsZero() && zr.ModTime.Unix() != 0 {
+		t.Errorf("gzip header ModTime = %v, want zero/epoch", zr.ModTime)
+	}
+
+	tarBytes, err := io.ReadAll(zr)
+	if err != nil {
+		t.Fatalf("gunzip: %v", err)
+	}
+	tr := tar.NewReader(bytes.NewReader(tarBytes))
+	hdr, err := tr.Next()
+	if err != nil {
+		t.Fatalf("tar: %v", err)
+	}
+	if hdr.Name != "APKINDEX" {
+		t.Fatalf("tar entry = %q, want APKINDEX", hdr.Name)
+	}
+	if hdr.ModTime.Unix() != 0 {
+		t.Errorf("APKINDEX tar ModTime = %v (unix %d), want epoch (0)", hdr.ModTime, hdr.ModTime.Unix())
+	}
+}

internal/provider/alpine/alpine_local_test.go

@@ -0,0 +1,324 @@
+package alpine
+
+import (
+	"archive/tar"
+	"bytes"
+	"compress/gzip"
+	"context"
+	"crypto/sha1"
+	"encoding/base64"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"git.unkin.net/unkin/artifactapi/internal/provider"
+	"git.unkin.net/unkin/artifactapi/internal/testsupport"
+)
+
+type fakeBlobReader struct{ data []byte }
+
+func (f fakeBlobReader) Download(_ context.Context, _ string) (io.ReadCloser, int64, error) {
+	return io.NopCloser(bytes.NewReader(f.data)), int64(len(f.data)), nil
+}
+
+type errBlobReader struct{}
+
+func (errBlobReader) Download(_ context.Context, _ string) (io.ReadCloser, int64, error) {
+	return nil, 0, io.ErrUnexpectedEOF
+}
+
+// fakeAlpineStore satisfies provider.MetadataStore (shared) and
+// provider.AlpineMetadataStore, recording the row AfterUpload writes.
+type fakeAlpineStore struct{ inserted *provider.AlpineMetadata }
+
+func (f *fakeAlpineStore) InsertRPMMetadata(context.Context, *provider.RPMMetadata) error { return nil }
+func (f *fakeAlpineStore) InsertDebMetadata(context.Context, *provider.DebMetadata) error { return nil }
+func (f *fakeAlpineStore) InsertAlpineMetadata(_ context.Context, m *provider.AlpineMetadata) error {
+	f.inserted = m
+	return nil
+}
+
+// fakeAlpineDeleter satisfies provider.MetadataDeleter and AlpineMetadataDeleter.
+type fakeAlpineDeleter struct{ deleted bool }
+
+func (f *fakeAlpineDeleter) DeleteRPMMetadata(context.Context, string, string) error { return nil }
+func (f *fakeAlpineDeleter) DeleteDebMetadata(context.Context, string, string) error { return nil }
+func (f *fakeAlpineDeleter) DeleteAlpineMetadata(context.Context, string, string) error {
+	f.deleted = true
+	return nil
+}
+
+// fakeAlpineReader is a FileStore that also serves alpine metadata rows.
+type fakeAlpineReader struct{ metas []provider.AlpineMetadata }
+
+func (f fakeAlpineReader) ListAlpineMetadataEntries(context.Context, string) ([]provider.AlpineMetadata, error) {
+	return f.metas, nil
+}
+func (f fakeAlpineReader) ListFilesByPrefix(context.Context, string, string) ([]provider.FileEntry, error) {
+	return nil, nil
+}
+func (f fakeAlpineReader) ListPackages(context.Context, string) ([]string, error) { return nil, nil }
+
+type errAlpineReader struct{}
+
+func (errAlpineReader) ListAlpineMetadataEntries(context.Context, string) ([]provider.AlpineMetadata, error) {
+	return nil, io.ErrUnexpectedEOF
+}
+func (errAlpineReader) ListFilesByPrefix(context.Context, string, string) ([]provider.FileEntry, error) {
+	return nil, nil
+}
+func (errAlpineReader) ListPackages(context.Context, string) ([]string, error) { return nil, nil }
+
+func TestAlpineValidateUpload(t *testing.T) {
+	p := &Provider{}
+	sp, ct, err := p.ValidateUpload("x86_64/foo-1.0-r0.apk")
+	if err != nil || sp != "x86_64/foo-1.0-r0.apk" || ct != "application/vnd.android.package-archive" {
+		t.Errorf("sp=%q ct=%q err=%v", sp, ct, err)
+	}
+	// Dot-segment prefix is normalized away.
+	if sp, _, err := p.ValidateUpload("./aarch64/bar-2.0-r1.apk"); err != nil || sp != "aarch64/bar-2.0-r1.apk" {
+		t.Errorf("dot-seg: sp=%q err=%v", sp, err)
+	}
+	if _, _, err := p.ValidateUpload("foo.rpm"); err == nil {
+		t.Error("expected error for non-apk")
+	}
+	resp := p.UploadResponse("x86_64/foo-1.0-r0.apk", "sha256:abc", 42)
+	if resp["filename"] != "foo-1.0-r0.apk" || resp["content_hash"] != "sha256:abc" || resp["size_bytes"] != int64(42) {
+		t.Errorf("upload response %v", resp)
+	}
+}
+
+func TestAlpineAfterUpload(t *testing.T) {
+	data := testsupport.MinimalApk("hello", "1.0-r0", "x86_64")
+	store := &fakeAlpineStore{}
+	(&Provider{}).AfterUpload(context.Background(), "myrepo", "x86_64/hello-1.0-r0.apk",
+		"sha256:deadbeef", fakeBlobReader{data: data}, store)
+
+	m := store.inserted
+	if m == nil {
+		t.Fatal("no metadata inserted")
+	}
+	if m.Name != "hello" || m.Version != "1.0-r0" || m.Arch != "x86_64" {
+		t.Errorf("unexpected metadata: %+v", m)
+	}
+	if m.DownloadSize != int64(len(data)) {
+		t.Errorf("DownloadSize = %d, want %d", m.DownloadSize, len(data))
+	}
+	if m.InstalledSize != 4 {
+		t.Errorf("InstalledSize = %d, want 4", m.InstalledSize)
+	}
+	if m.License != "MIT" || m.Origin != "hello" || !strings.HasPrefix(m.Maintainer, "e2e") {
+		t.Errorf("scalar fields not parsed: %+v", m)
+	}
+	if len(m.Depends) != 1 || m.Depends[0] != "so:libc.musl-x86_64.so.1" {
+		t.Errorf("Depends = %v", m.Depends)
+	}
+	if len(m.Provides) != 1 || m.Provides[0] != "cmd:hello=1.0-r0" {
+		t.Errorf("Provides = %v", m.Provides)
+	}
+
+	// The Q1 checksum is the sha1 of the CONTROL gzip stream (the member whose
+	// tar carries .PKGINFO), not of the whole file.
+	controlRaw := controlStreamBytes(t, data)
+	sum := sha1.Sum(controlRaw)
+	want := "Q1" + base64.StdEncoding.EncodeToString(sum[:])
+	if m.Checksum != want {
+		t.Errorf("Checksum = %q, want %q (sha1 of control stream)", m.Checksum, want)
+	}
+	// And explicitly NOT the sha1 of the whole apk.
+	whole := sha1.Sum(data)
+	if m.Checksum == "Q1"+base64.StdEncoding.EncodeToString(whole[:]) {
+		t.Error("Checksum was computed over the whole file, not the control stream")
+	}
+}
+
+func TestAlpineAfterUploadErrors(t *testing.T) {
+	store := &fakeAlpineStore{}
+	(&Provider{}).AfterUpload(context.Background(), "r", "x86_64/p.apk", "sha256:x", errBlobReader{}, store)
+	if store.inserted != nil {
+		t.Error("no metadata should be inserted on download error")
+	}
+	store2 := &fakeAlpineStore{}
+	(&Provider{}).AfterUpload(context.Background(), "r", "x86_64/p.apk", "sha256:x", fakeBlobReader{data: []byte("not an apk")}, store2)
+	if store2.inserted != nil {
+		t.Error("no metadata should be inserted on parse error")
+	}
+}
+
+func TestAlpineAfterDelete(t *testing.T) {
+	d := &fakeAlpineDeleter{}
+	if err := (&Provider{}).AfterDelete(context.Background(), "r", "x86_64/p.apk", d); err != nil {
+		t.Fatalf("AfterDelete: %v", err)
+	}
+	if !d.deleted {
+		t.Error("DeleteAlpineMetadata not called")
+	}
+}
+
+func TestAlpineServeLocalIndex(t *testing.T) {
+	p := &Provider{}
+	reader := fakeAlpineReader{metas: []provider.AlpineMetadata{
+		{Name: "aaa", Version: "1.0-r0", Arch: "x86_64", Checksum: "Q1aaa", DownloadSize: 100, InstalledSize: 10,
+			Description: "pkg aaa", URL: "https://a", License: "MIT", Depends: []string{"so:libc"}, Provides: []string{"cmd:aaa"}},
+		{Name: "bbb", Version: "2.0-r0", Arch: "aarch64", Checksum: "Q1bbb", DownloadSize: 200, InstalledSize: 20},
+	}}
+
+	// x86_64 index contains only aaa, with its fields, and not bbb.
+	w := serveIndex(t, p, reader, "x86_64/APKINDEX.tar.gz")
+	if w.Code != 200 {
+		t.Fatalf("code %d", w.Code)
+	}
+	idx := untarIndex(t, w.Body.Bytes())
+	for _, want := range []string{"C:Q1aaa", "P:aaa", "V:1.0-r0", "A:x86_64", "S:100", "I:10", "T:pkg aaa", "U:https://a", "L:MIT", "D:so:libc", "p:cmd:aaa"} {
+		if !strings.Contains(idx, want) {
+			t.Errorf("x86_64 APKINDEX missing %q:\n%s", want, idx)
+		}
+	}
+	if strings.Contains(idx, "P:bbb") {
+		t.Errorf("x86_64 APKINDEX leaked aarch64 package:\n%s", idx)
+	}
+
+	// aarch64 index contains only bbb.
+	w = serveIndex(t, p, reader, "aarch64/APKINDEX.tar.gz")
+	idx = untarIndex(t, w.Body.Bytes())
+	if !strings.Contains(idx, "P:bbb") || strings.Contains(idx, "P:aaa") {
+		t.Errorf("aarch64 filtering wrong:\n%s", idx)
+	}
+
+	// Non-index and .apk paths are not owned by the indexer.
+	for _, path := range []string{"x86_64/foo-1.0-r0.apk", "x86_64/", "README"} {
+		w := httptest.NewRecorder()
+		r := httptest.NewRequest(http.MethodGet, "/"+path, nil)
+		if p.ServeLocalIndex(w, r, reader, "repo", path) {
+			t.Errorf("ServeLocalIndex should return false for %q", path)
+		}
+	}
+}
+
+// Empty fields are omitted from the record (bbb has no description/url).
+func TestAlpineIndexOmitsEmptyFields(t *testing.T) {
+	p := &Provider{}
+	reader := fakeAlpineReader{metas: []provider.AlpineMetadata{
+		{Name: "bbb", Version: "2.0-r0", Arch: "x86_64", Checksum: "Q1bbb", DownloadSize: 200, InstalledSize: 20},
+	}}
+	idx := untarIndex(t, serveIndex(t, p, reader, "x86_64/APKINDEX.tar.gz").Body.Bytes())
+	for _, absent := range []string{"T:", "U:", "L:", "D:", "p:", "i:", "o:", "m:", "c:", "k:"} {
+		if strings.Contains(idx, absent) {
+			t.Errorf("empty field %q should be omitted:\n%s", absent, idx)
+		}
+	}
+}
+
+// apk requests "./<arch>/APKINDEX.tar.gz" for a bare repo base URL; the
+// dot-segment must be collapsed and yield the same bytes as the plain path.
+func TestAlpineServeLocalIndexDotSegment(t *testing.T) {
+	p := &Provider{}
+	reader := fakeAlpineReader{metas: []provider.AlpineMetadata{
+		{Name: "aaa", Version: "1.0-r0", Arch: "x86_64", Checksum: "Q1aaa", DownloadSize: 100, InstalledSize: 10},
+	}}
+	plain := untarIndex(t, serveIndex(t, p, reader, "x86_64/APKINDEX.tar.gz").Body.Bytes())
+	dotted := untarIndex(t, serveIndex(t, p, reader, "./x86_64/APKINDEX.tar.gz").Body.Bytes())
+	if plain != dotted {
+		t.Errorf("dot-segment path differs:\nplain=%q\ndotted=%q", plain, dotted)
+	}
+}
+
+func TestAlpineServeLocalIndexArchRequired(t *testing.T) {
+	p := &Provider{}
+	reader := fakeAlpineReader{}
+	w := httptest.NewRecorder()
+	r := httptest.NewRequest(http.MethodGet, "/APKINDEX.tar.gz", nil)
+	if !p.ServeLocalIndex(w, r, reader, "repo", "APKINDEX.tar.gz") {
+		t.Fatal("bare APKINDEX should be owned (and rejected) by the indexer")
+	}
+	if w.Code != http.StatusNotFound {
+		t.Errorf("bare APKINDEX code = %d, want 404", w.Code)
+	}
+}
+
+func TestAlpineServeMetadataError(t *testing.T) {
+	p := &Provider{}
+	w := httptest.NewRecorder()
+	r := httptest.NewRequest(http.MethodGet, "/x86_64/APKINDEX.tar.gz", nil)
+	p.ServeLocalIndex(w, r, errAlpineReader{}, "repo", "x86_64/APKINDEX.tar.gz")
+	if w.Code != 500 {
+		t.Errorf("failing reader code = %d, want 500", w.Code)
+	}
+}
+
+func TestAlpineGenerateLocalIndexUnsupported(t *testing.T) {
+	if _, err := (&Provider{}).GenerateLocalIndex(context.Background(), fakeAlpineReader{}, "r", "x86_64/APKINDEX.tar.gz"); err == nil {
+		t.Error("expected unsupported error")
+	}
+}
+
+func serveIndex(t *testing.T, p *Provider, files provider.FileStore, path string) *httptest.ResponseRecorder {
+	t.Helper()
+	w := httptest.NewRecorder()
+	r := httptest.NewRequest(http.MethodGet, "/"+path, nil)
+	if !p.ServeLocalIndex(w, r, files, "repo", path) {
+		t.Fatalf("ServeLocalIndex returned false for %q", path)
+	}
+	return w
+}
+
+// untarIndex un-gzips and un-tars an APKINDEX.tar.gz and returns the APKINDEX text.
+func untarIndex(t *testing.T, gzTar []byte) string {
+	t.Helper()
+	zr, err := gzip.NewReader(bytes.NewReader(gzTar))
+	if err != nil {
+		t.Fatalf("APKINDEX not gzip: %v", err)
+	}
+	tarBytes, _ := io.ReadAll(zr)
+	tr := tar.NewReader(bytes.NewReader(tarBytes))
+	for {
+		hdr, err := tr.Next()
+		if err == io.EOF {
+			break
+		}
+		if err != nil {
+			t.Fatalf("APKINDEX not tar: %v", err)
+		}
+		if hdr.Name == "APKINDEX" {
+			b, _ := io.ReadAll(tr)
+			return string(b)
+		}
+	}
+	t.Fatal("no APKINDEX member in tarball")
+	return ""
+}
+
+// controlStreamBytes returns the raw bytes of the gzip stream whose tar carries
+// .PKGINFO, so the test can independently compute the expected Q1 checksum.
+func controlStreamBytes(t *testing.T, apk []byte) []byte {
+	t.Helper()
+	br := bytes.NewReader(apk)
+	zr, err := gzip.NewReader(br)
+	if err != nil {
+		t.Fatalf("gzip: %v", err)
+	}
+	prev := 0
+	for {
+		zr.Multistream(false)
+		out, _ := io.ReadAll(zr)
+		end := len(apk) - br.Len()
+		tr := tar.NewReader(bytes.NewReader(out))
+		for {
+			h, err := tr.Next()
+			if err != nil {
+				break
+			}
+			if strings.TrimPrefix(h.Name, "./") == ".PKGINFO" {
+				return apk[prev:end]
+			}
+		}
+		prev = end
+		if err := zr.Reset(br); err != nil {
+			break
+		}
+	}
+	t.Fatal("no control stream found")
+	return nil
+}

internal/provider/alpine/github.go

@@ -0,0 +1,714 @@
+package alpine
+
+import (
+	"bytes"
+	"compress/gzip"
+	"context"
+	"crypto/sha1"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/url"
+	"regexp"
+	"strings"
+	"sync"
+	"time"
+
+	"golang.org/x/time/rate"
+
+	"git.unkin.net/unkin/artifactapi/internal/githubauth"
+	"git.unkin.net/unkin/artifactapi/internal/provider"
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+// gitHubProvider is the process-wide singleton for github_alpine. The background
+// Syncer binds its shared rate limiter and work queue onto this instance so the
+// request path and the syncer drive the same derive machinery.
+var gitHubProvider = newGitHubProvider()
+
+func init() {
+	provider.Register(gitHubProvider)
+}
+
+// Tuning knobs for the no-precache control fetch. An .apk is up to three
+// concatenated gzip streams (optional signature, control, data); the control
+// stream carrying .PKGINFO sits near the front, so a small prefix reliably
+// covers it.
+const (
+	defaultHeaderRangeInitial = 32 << 10 // 32 KiB — covers the control stream of almost every .apk
+	defaultHeaderRangeMax     = 16 << 20 // 16 MiB — give up past this and skip the asset
+	defaultReleasePageCap     = 10       // 100 releases/page * 10 pages
+
+	defaultScanTimeout  = 10 * time.Minute
+	defaultServeTimeout = 30 * time.Second
+	defaultColdWait     = 8 * time.Second
+)
+
+// GitHubProvider is a metadata-only remote: it scans a GitHub repo's releases
+// for .apk assets, derives per-asset .PKGINFO metadata via a ranged prefix fetch
+// (never downloading whole packages), synthesizes a per-arch APKINDEX from that
+// cached metadata, and redirects package downloads to a backend "releases_remote"
+// (the generic github.com remote) that serves the actual bytes.
+type GitHubProvider struct {
+	client *http.Client
+
+	headerInitial int64
+	headerMax     int64
+	pageCap       int
+	scanTimeout   time.Duration
+	serveTimeout  time.Duration
+	coldWait      time.Duration
+
+	limiter *rate.Limiter
+	syncer  *Syncer
+
+	serverCred githubauth.Credential
+
+	mu       sync.Mutex
+	scanning map[string]bool
+	lastScan map[string]time.Time
+}
+
+func newGitHubProvider() *GitHubProvider {
+	return &GitHubProvider{
+		client:        &http.Client{},
+		headerInitial: defaultHeaderRangeInitial,
+		headerMax:     defaultHeaderRangeMax,
+		pageCap:       defaultReleasePageCap,
+		scanTimeout:   defaultScanTimeout,
+		serveTimeout:  defaultServeTimeout,
+		coldWait:      defaultColdWait,
+		scanning:      map[string]bool{},
+		lastScan:      map[string]time.Time{},
+	}
+}
+
+func (p *GitHubProvider) limiterWait(ctx context.Context) error {
+	if p.limiter == nil {
+		return nil
+	}
+	return p.limiter.Wait(ctx)
+}
+
+func (p *GitHubProvider) Type() models.PackageType { return models.PackageGitHubAlpine }
+
+func (p *GitHubProvider) Classify(path string) provider.Mutability {
+	if strings.HasSuffix(path, "APKINDEX.tar.gz") {
+		return provider.Mutable
+	}
+	return provider.Immutable
+}
+
+func (p *GitHubProvider) ContentType(path string) string {
+	switch {
+	case strings.HasSuffix(path, ".apk"):
+		return "application/vnd.android.package-archive"
+	case strings.HasSuffix(path, ".tar.gz"):
+		return "application/gzip"
+	}
+	return "application/octet-stream"
+}
+
+func (p *GitHubProvider) UpstreamURL(remote models.Remote, path string) string {
+	return strings.TrimRight(remote.BaseURL, "/") + "/" + strings.TrimLeft(path, "/")
+}
+
+func (p *GitHubProvider) RewriteResponse(_ []byte, _ models.Remote, _ string) ([]byte, error) {
+	return nil, nil
+}
+
+func (p *GitHubProvider) AuthHeaders(ctx context.Context, remote models.Remote) (http.Header, error) {
+	return p.githubHeaders(ctx, remote, false)
+}
+
+// ServeRemote answers a request against a github_alpine remote. It refreshes the
+// derived metadata (bounded by mutable_ttl), serves a synthesized per-arch
+// APKINDEX.tar.gz, and 302-redirects .apk downloads to the backend
+// releases_remote. Returns false only for paths it does not own.
+func (p *GitHubProvider) ServeRemote(w http.ResponseWriter, r *http.Request, remote models.Remote, reqPath, proxyBaseURL string, store provider.RemoteMetadataStore) bool {
+	p.onRequest(remote, store)
+
+	// apk requests the index at "./<arch>/APKINDEX.tar.gz"; collapse the
+	// dot-segment before matching, mirroring the local indexer.
+	path := normalizeIndexPath(reqPath)
+
+	if strings.HasSuffix(path, "APKINDEX.tar.gz") {
+		p.serveIndex(w, r, remote, path, store)
+		return true
+	}
+
+	if strings.HasSuffix(path, ".apk") {
+		if remote.ReleasesRemote == "" {
+			http.Error(w, "github_alpine remote has no releases_remote configured for downloads", http.StatusInternalServerError)
+			return true
+		}
+		p.serveApkRedirect(w, r, remote, path, proxyBaseURL, store)
+		return true
+	}
+
+	return false
+}
+
+// serveApkRedirect resolves an apk-reconstructed download path — apk builds
+// "<arch>/<name>-<version>.apk" itself because APKINDEX carries no filename — to
+// the real github-relative asset path stored on the metadata row, then redirects
+// to the backend releases_remote. Passing the inbound path through verbatim would
+// point at a nonexistent, allowlist-denied github.com path.
+func (p *GitHubProvider) serveApkRedirect(w http.ResponseWriter, r *http.Request, remote models.Remote, path, proxyBaseURL string, store provider.RemoteMetadataStore) {
+	arch := strings.TrimSuffix(path[:strings.LastIndex(path, "/")+1], "/")
+	basename := path[strings.LastIndex(path, "/")+1:]
+	if arch == "" || strings.Contains(arch, "/") {
+		http.Error(w, "apk download must be requested per-arch: <arch>/<name>-<version>.apk", http.StatusNotFound)
+		return
+	}
+
+	reader, ok := store.(provider.AlpineMetadataReader)
+	if !ok {
+		http.Error(w, "alpine metadata not available", http.StatusInternalServerError)
+		return
+	}
+	sctx, cancel := context.WithTimeout(context.WithoutCancel(r.Context()), p.serveTimeout)
+	defer cancel()
+	rows, err := reader.ListAlpineMetadataEntries(sctx, remote.Name)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	for _, row := range rows {
+		if row.Arch == arch && row.Name+"-"+row.Version+".apk" == basename {
+			loc := strings.TrimRight(proxyBaseURL, "/") + "/api/v1/remote/" + remote.ReleasesRemote + "/" + strings.TrimLeft(row.FilePath, "/")
+			http.Redirect(w, r, loc, http.StatusFound)
+			return
+		}
+	}
+	http.Error(w, "package not found", http.StatusNotFound)
+}
+
+func (p *GitHubProvider) serveIndex(w http.ResponseWriter, r *http.Request, remote models.Remote, path string, store provider.RemoteMetadataStore) {
+	arch := strings.TrimSuffix(path, "APKINDEX.tar.gz")
+	arch = strings.Trim(arch, "/")
+	if arch == "" || strings.Contains(arch, "/") {
+		http.Error(w, "APKINDEX must be requested per-arch: <arch>/APKINDEX.tar.gz", http.StatusNotFound)
+		return
+	}
+
+	// Serve on a context detached from the inbound request so a client disconnect
+	// never cancels the metadata DB read and surfaces as a 500.
+	sctx, cancel := context.WithTimeout(context.WithoutCancel(r.Context()), p.serveTimeout)
+	defer cancel()
+
+	if p.syncer != nil && !p.ensurePrimed(sctx, remote, store) {
+		w.Header().Set("Retry-After", "5")
+		http.Error(w, "metadata is being prepared, retry shortly", http.StatusServiceUnavailable)
+		return
+	}
+
+	reader, ok := store.(provider.AlpineMetadataReader)
+	if !ok {
+		http.Error(w, "alpine metadata not available", http.StatusInternalServerError)
+		return
+	}
+	metas, err := reader.ListAlpineMetadataEntries(sctx, remote.Name)
+	if err != nil {
+		if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
+			http.Error(w, "metadata read canceled", http.StatusServiceUnavailable)
+			return
+		}
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	var filtered []provider.AlpineMetadata
+	for _, m := range metas {
+		if m.Arch == arch {
+			filtered = append(filtered, m)
+		}
+	}
+
+	w.Header().Set("Content-Type", "application/gzip")
+	w.WriteHeader(http.StatusOK)
+	w.Write(generateAPKIndex(filtered))
+}
+
+// onRequest keeps a remote's derived metadata fresh off the request path.
+func (p *GitHubProvider) onRequest(remote models.Remote, store provider.RemoteMetadataStore) {
+	if p.syncer != nil {
+		p.syncer.enqueue(remote, false)
+		return
+	}
+	p.refresh(remote, store)
+}
+
+// ensurePrimed returns true once the remote has at least one cached row. On an
+// empty cache it enqueues a prime and polls briefly for it to land.
+func (p *GitHubProvider) ensurePrimed(ctx context.Context, remote models.Remote, store provider.RemoteMetadataStore) bool {
+	if !p.cacheEmpty(ctx, store, remote.Name) {
+		return true
+	}
+	if p.syncer != nil {
+		p.syncer.enqueue(remote, true)
+	}
+
+	deadline := time.Now().Add(p.coldWait)
+	for time.Now().Before(deadline) {
+		select {
+		case <-ctx.Done():
+			return false
+		case <-time.After(400 * time.Millisecond):
+		}
+		if !p.cacheEmpty(ctx, store, remote.Name) {
+			return true
+		}
+	}
+	return false
+}
+
+func (p *GitHubProvider) cacheEmpty(ctx context.Context, store provider.RemoteMetadataStore, name string) bool {
+	reader, ok := store.(provider.AlpineMetadataReader)
+	if !ok {
+		return false
+	}
+	rows, err := reader.ListAlpineMetadataEntries(ctx, name)
+	if err != nil {
+		return false
+	}
+	return len(rows) == 0
+}
+
+// refresh brings the derived metadata up to date without coupling the scan to
+// the inbound request (legacy inline path used without a syncer / in unit tests).
+func (p *GitHubProvider) refresh(remote models.Remote, store provider.RemoteMetadataStore) {
+	ttl := time.Duration(remote.MutableTTL) * time.Second
+	if ttl <= 0 {
+		ttl = 5 * time.Minute
+	}
+
+	p.mu.Lock()
+	last, ok := p.lastScan[remote.Name]
+	fresh := ok && time.Since(last) < ttl
+	if fresh || p.scanning[remote.Name] {
+		p.mu.Unlock()
+		return
+	}
+	p.scanning[remote.Name] = true
+	p.mu.Unlock()
+
+	if p.cacheEmpty(context.Background(), store, remote.Name) {
+		p.runScan(remote, store)
+		return
+	}
+	go p.runScan(remote, store)
+}
+
+func (p *GitHubProvider) runScan(remote models.Remote, store provider.RemoteMetadataStore) {
+	defer func() {
+		p.mu.Lock()
+		delete(p.scanning, remote.Name)
+		p.mu.Unlock()
+	}()
+
+	ctx, cancel := context.WithTimeout(context.Background(), p.scanTimeout)
+	defer cancel()
+
+	if err := p.scan(ctx, remote, store); err != nil {
+		slog.Error("github_alpine: release scan failed", "remote", remote.Name, "error", err)
+		return
+	}
+
+	p.mu.Lock()
+	p.lastScan[remote.Name] = time.Now()
+	p.mu.Unlock()
+}
+
+// scan runs a full unconditional derive. Retained for the legacy inline refresh
+// path and existing tests; the syncer uses scanWithState.
+func (p *GitHubProvider) scan(ctx context.Context, remote models.Remote, store provider.RemoteMetadataStore) error {
+	_, _, err := p.scanWithState(ctx, remote, store, "")
+	return err
+}
+
+// scanWithState derives metadata incrementally. It sends the prior releases-list
+// ETag as a conditional request: a 304 means nothing changed. On a 200 it diffs
+// the release assets against the cache, derives only new/changed assets, prunes
+// assets that disappeared, and returns the new ETag.
+func (p *GitHubProvider) scanWithState(ctx context.Context, remote models.Remote, store provider.RemoteMetadataStore, etag string) (newEtag string, changed bool, err error) {
+	inserter, ok := store.(provider.AlpineMetadataStore)
+	if !ok {
+		return etag, false, errors.New("store does not support alpine metadata writes")
+	}
+	deleter, ok := store.(provider.AlpineMetadataDeleter)
+	if !ok {
+		return etag, false, errors.New("store does not support alpine metadata deletes")
+	}
+	reader, ok := store.(provider.AlpineMetadataReader)
+	if !ok {
+		return etag, false, errors.New("store does not support alpine metadata reads")
+	}
+
+	releases, newEtag, notModified, err := p.fetchReleases(ctx, remote, etag)
+	if err != nil {
+		return etag, false, err
+	}
+	if notModified {
+		return etag, false, nil
+	}
+
+	existing, err := reader.ListAlpineMetadataEntries(ctx, remote.Name)
+	if err != nil {
+		return newEtag, false, err
+	}
+	existingByPath := make(map[string]provider.AlpineMetadata, len(existing))
+	for _, m := range existing {
+		existingByPath[m.FilePath] = m
+	}
+
+	allow, err := compilePatterns(remote.Patterns)
+	if err != nil {
+		return newEtag, false, err
+	}
+
+	seen := map[string]bool{}
+	for _, rel := range releases {
+		if rel.Draft {
+			continue
+		}
+		for _, asset := range rel.Assets {
+			if !strings.HasSuffix(strings.ToLower(asset.Name), ".apk") {
+				continue
+			}
+			if !matchesAny(allow, asset.Name) {
+				continue
+			}
+			fp := assetPath(asset)
+			if fp == "" {
+				continue
+			}
+			seen[fp] = true
+
+			if cur, ok := existingByPath[fp]; ok {
+				if asset.Digest == "" || cur.ContentHash == asset.Digest {
+					continue
+				}
+				_ = deleter.DeleteAlpineMetadata(ctx, remote.Name, fp)
+			}
+
+			meta, err := p.deriveAsset(ctx, remote, asset, fp)
+			if err != nil {
+				slog.Warn("github_alpine: derive asset failed", "remote", remote.Name, "asset", asset.Name, "error", err)
+				continue
+			}
+			if err := inserter.InsertAlpineMetadata(ctx, meta); err != nil {
+				slog.Error("github_alpine: insert metadata failed", "remote", remote.Name, "asset", asset.Name, "error", err)
+				continue
+			}
+			slog.Info("github_alpine: derived asset", "remote", remote.Name, "name", meta.Name, "version", meta.Version, "arch", meta.Arch)
+		}
+	}
+
+	for fp := range existingByPath {
+		if !seen[fp] {
+			_ = deleter.DeleteAlpineMetadata(ctx, remote.Name, fp)
+		}
+	}
+	return newEtag, true, nil
+}
+
+type ghRelease struct {
+	TagName string    `json:"tag_name"`
+	Draft   bool      `json:"draft"`
+	Assets  []ghAsset `json:"assets"`
+}
+
+type ghAsset struct {
+	Name               string `json:"name"`
+	Size               int64  `json:"size"`
+	BrowserDownloadURL string `json:"browser_download_url"`
+	Digest             string `json:"digest"`
+}
+
+// fetchReleases lists a repo's releases, sending the prior ETag as If-None-Match
+// on page 1 so an unchanged repo short-circuits to notModified. Every call waits
+// on the shared limiter first.
+func (p *GitHubProvider) fetchReleases(ctx context.Context, remote models.Remote, etag string) (all []ghRelease, newEtag string, notModified bool, err error) {
+	base := strings.TrimRight(remote.BaseURL, "/") + "/releases"
+	for page := 1; page <= p.pageCap; page++ {
+		u := fmt.Sprintf("%s?per_page=100&page=%d", base, page)
+		req, err := http.NewRequestWithContext(ctx, http.MethodGet, u, nil)
+		if err != nil {
+			return nil, "", false, err
+		}
+		hdr, err := p.githubHeaders(ctx, remote, true)
+		if err != nil {
+			return nil, "", false, err
+		}
+		copyHeaders(req, hdr)
+		if page == 1 && etag != "" {
+			req.Header.Set("If-None-Match", etag)
+		}
+
+		if err := p.limiterWait(ctx); err != nil {
+			return nil, "", false, err
+		}
+		resp, err := p.client.Do(req)
+		if err != nil {
+			return nil, "", false, err
+		}
+		if page == 1 && resp.StatusCode == http.StatusNotModified {
+			io.Copy(io.Discard, resp.Body)
+			resp.Body.Close()
+			return nil, etag, true, nil
+		}
+		body, err := io.ReadAll(resp.Body)
+		respEtag := resp.Header.Get("ETag")
+		resp.Body.Close()
+		if err != nil {
+			return nil, "", false, err
+		}
+		if resp.StatusCode != http.StatusOK {
+			return nil, "", false, fmt.Errorf("github releases API %s: status %d", u, resp.StatusCode)
+		}
+		if page == 1 {
+			newEtag = respEtag
+		}
+		var releases []ghRelease
+		if err := json.Unmarshal(body, &releases); err != nil {
+			return nil, "", false, fmt.Errorf("decode releases: %w", err)
+		}
+		if len(releases) == 0 {
+			break
+		}
+		all = append(all, releases...)
+		if len(releases) < 100 {
+			break
+		}
+	}
+	return all, newEtag, false, nil
+}
+
+func (p *GitHubProvider) deriveAsset(ctx context.Context, remote models.Remote, asset ghAsset, fp string) (*provider.AlpineMetadata, error) {
+	meta, err := p.fetchPkginfo(ctx, remote, asset.BrowserDownloadURL)
+	if err != nil {
+		return nil, err
+	}
+	if meta.Name == "" || meta.Arch == "" {
+		return nil, errors.New(".PKGINFO missing pkgname/arch")
+	}
+
+	meta.RepoName = remote.Name
+	meta.FilePath = fp
+	// S: the on-disk .apk size comes straight from the releases API, so we never
+	// download the body just to size it.
+	meta.DownloadSize = asset.Size
+	// ContentHash records the GitHub asset digest (when present) purely so the
+	// next scan can detect a changed asset; unlike deb it is not the index
+	// checksum (that is the Q1 control-stream sum already set in fetchPkginfo).
+	if asset.Digest != "" {
+		meta.ContentHash = asset.Digest
+	}
+	return meta, nil
+}
+
+// fetchPkginfo pulls only the front of the .apk with a ranged GET and derives the
+// .PKGINFO fields plus the apk pull checksum (C: = Q1 + base64(sha1(control gzip
+// stream))). The control stream sits near the front, so a small prefix suffices;
+// a prefix that truncates it doubles the range and retries.
+func (p *GitHubProvider) fetchPkginfo(ctx context.Context, remote models.Remote, downloadURL string) (*provider.AlpineMetadata, error) {
+	n := p.headerInitial
+	for {
+		body, full, err := p.rangeGet(ctx, remote, downloadURL, n)
+		if err != nil {
+			return nil, err
+		}
+		meta, complete, perr := pkginfoFromPrefix(body)
+		if perr != nil {
+			return nil, fmt.Errorf("parse apk .PKGINFO: %w", perr)
+		}
+		if complete {
+			return meta, nil
+		}
+		if full || n >= p.headerMax {
+			return nil, fmt.Errorf(".PKGINFO not found within %d bytes of %s", n, downloadURL)
+		}
+		n *= 2
+		if n > p.headerMax {
+			n = p.headerMax
+		}
+	}
+}
+
+// pkginfoFromPrefix parses the concatenated gzip streams present in a front
+// prefix of an .apk. It walks each fully-covered gzip member until it finds the
+// control stream (the one whose tar carries .PKGINFO), computes the Q1 pull
+// checksum from that stream's raw bytes, and reads the .PKGINFO fields. A prefix
+// too short to fully cover the control stream returns complete=false so the
+// caller can widen the range.
+func pkginfoFromPrefix(prefix []byte) (meta *provider.AlpineMetadata, complete bool, err error) {
+	br := bytes.NewReader(prefix)
+	zr, zerr := gzip.NewReader(br)
+	if zerr != nil {
+		if zerr == io.EOF || zerr == io.ErrUnexpectedEOF {
+			return nil, false, nil
+		}
+		return nil, false, zerr
+	}
+	prev := 0
+	for {
+		zr.Multistream(false)
+		out, rerr := io.ReadAll(zr)
+		if rerr != nil {
+			// A member truncated by the range boundary is not an error — widen.
+			if rerr == io.ErrUnexpectedEOF || rerr == io.EOF {
+				return nil, false, nil
+			}
+			return nil, false, rerr
+		}
+		end := len(prefix) - br.Len()
+		raw := prefix[prev:end]
+
+		if pkginfo, ok := pkginfoFromTar(out); ok {
+			m := parsePkginfo(pkginfo)
+			sum := sha1.Sum(raw)
+			m.Checksum = "Q1" + base64.StdEncoding.EncodeToString(sum[:])
+			return m, true, nil
+		}
+
+		prev = end
+		if rsterr := zr.Reset(br); rsterr != nil {
+			if rsterr == io.EOF {
+				// No more complete members in the prefix; the control stream is
+				// either not covered yet or genuinely absent — let the caller
+				// decide by widening (or hitting the full-object guard).
+				return nil, false, nil
+			}
+			if rsterr == io.ErrUnexpectedEOF {
+				return nil, false, nil
+			}
+			return nil, false, rsterr
+		}
+	}
+}
+
+// rangeGet returns the first n bytes of downloadURL. full is true when the
+// response body was shorter than n (i.e. we already have the whole object).
+func (p *GitHubProvider) rangeGet(ctx context.Context, remote models.Remote, downloadURL string, n int64) ([]byte, bool, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, downloadURL, nil)
+	if err != nil {
+		return nil, false, err
+	}
+	hdr, err := p.githubHeaders(ctx, remote, false)
+	if err != nil {
+		return nil, false, err
+	}
+	copyHeaders(req, hdr)
+	req.Header.Set("Range", fmt.Sprintf("bytes=0-%d", n-1))
+
+	if err := p.limiterWait(ctx); err != nil {
+		return nil, false, err
+	}
+	resp, err := p.client.Do(req)
+	if err != nil {
+		return nil, false, err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK && resp.StatusCode != http.StatusPartialContent {
+		return nil, false, fmt.Errorf("range GET %s: status %d", downloadURL, resp.StatusCode)
+	}
+
+	body, err := io.ReadAll(io.LimitReader(resp.Body, n))
+	if err != nil {
+		return nil, false, err
+	}
+	full := int64(len(body)) < n
+	return body, full, nil
+}
+
+// assetPath is the package's location relative to github.com — the path the
+// backend releases_remote (base https://github.com) proxies. It doubles as the
+// alpine_metadata key and the redirect target, so an .apk download resolves back
+// to this remote and redirects to the backend.
+func assetPath(asset ghAsset) string {
+	u, err := url.Parse(asset.BrowserDownloadURL)
+	if err != nil {
+		return ""
+	}
+	return strings.TrimPrefix(u.Path, "/")
+}
+
+// githubHeaders builds the outbound headers for a GitHub request, attaching a
+// bearer credential when one is available. A per-remote credential wins; absent
+// that, the process-wide server credential is used; absent both, the request is
+// unauthenticated.
+func (p *GitHubProvider) githubHeaders(ctx context.Context, remote models.Remote, api bool) (http.Header, error) {
+	h := http.Header{}
+	if api {
+		h.Set("Accept", "application/vnd.github+json")
+		h.Set("X-GitHub-Api-Version", "2022-11-28")
+	}
+	tok, err := p.githubToken(ctx, remote)
+	if err != nil {
+		return nil, err
+	}
+	if tok != "" {
+		h.Set("Authorization", "Bearer "+tok)
+	}
+	return h, nil
+}
+
+// githubToken resolves the bearer token for a remote. Precedence: a per-remote
+// credential (password, then username) overrides the server credential.
+func (p *GitHubProvider) githubToken(ctx context.Context, remote models.Remote) (string, error) {
+	if remote.Password != "" {
+		return remote.Password, nil
+	}
+	if remote.Username != "" {
+		return remote.Username, nil
+	}
+	if c := p.serverCredential(); c != nil {
+		return c.Token(ctx)
+	}
+	return "", nil
+}
+
+func (p *GitHubProvider) serverCredential() githubauth.Credential {
+	if p.serverCred != nil {
+		return p.serverCred
+	}
+	return githubauth.Server()
+}
+
+func copyHeaders(req *http.Request, h http.Header) {
+	for k, vals := range h {
+		for _, v := range vals {
+			req.Header.Add(k, v)
+		}
+	}
+}
+
+func compilePatterns(patterns []string) ([]*regexp.Regexp, error) {
+	var out []*regexp.Regexp
+	for _, p := range patterns {
+		re, err := regexp.Compile(p)
+		if err != nil {
+			return nil, fmt.Errorf("invalid pattern %q: %w", p, err)
+		}
+		out = append(out, re)
+	}
+	return out, nil
+}
+
+func matchesAny(res []*regexp.Regexp, s string) bool {
+	if len(res) == 0 {
+		return true
+	}
+	for _, re := range res {
+		if re.MatchString(s) {
+			return true
+		}
+	}
+	return false
+}

internal/provider/alpine/github_test.go

@@ -0,0 +1,497 @@
+package alpine
+
+import (
+	"archive/tar"
+	"bytes"
+	"compress/gzip"
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strconv"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"git.unkin.net/unkin/artifactapi/internal/provider"
+	"git.unkin.net/unkin/artifactapi/internal/testsupport"
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+// fakeStore is an in-memory provider.RemoteMetadataStore + AlpineMetadata
+// store/reader/deleter keyed by file_path, mirroring the (repo_name, file_path)
+// uniqueness of the real alpine_metadata table.
+type fakeStore struct {
+	mu   sync.Mutex
+	rows map[string]provider.AlpineMetadata
+}
+
+func newFakeStore() *fakeStore { return &fakeStore{rows: map[string]provider.AlpineMetadata{}} }
+
+func (f *fakeStore) InsertAlpineMetadata(_ context.Context, m *provider.AlpineMetadata) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if _, ok := f.rows[m.FilePath]; ok {
+		return nil // ON CONFLICT DO NOTHING
+	}
+	f.rows[m.FilePath] = *m
+	return nil
+}
+
+func (f *fakeStore) DeleteAlpineMetadata(_ context.Context, _, filePath string) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	delete(f.rows, filePath)
+	return nil
+}
+
+func (f *fakeStore) ListAlpineMetadataEntries(ctx context.Context, _ string) ([]provider.AlpineMetadata, error) {
+	if err := ctx.Err(); err != nil {
+		return nil, err
+	}
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	out := make([]provider.AlpineMetadata, 0, len(f.rows))
+	for _, m := range f.rows {
+		out = append(out, m)
+	}
+	return out, nil
+}
+
+// The generic RemoteMetadataStore surface (rpm/deb) is unused by the alpine
+// github provider but required to satisfy the interface passed to ServeRemote.
+func (f *fakeStore) InsertRPMMetadata(context.Context, *provider.RPMMetadata) error { return nil }
+func (f *fakeStore) DeleteRPMMetadata(context.Context, string, string) error        { return nil }
+func (f *fakeStore) ListRPMMetadataEntries(context.Context, string) ([]provider.RPMMetadata, error) {
+	return nil, nil
+}
+func (f *fakeStore) InsertDebMetadata(context.Context, *provider.DebMetadata) error { return nil }
+func (f *fakeStore) DeleteDebMetadata(context.Context, string, string) error        { return nil }
+
+var _ provider.RemoteMetadataStore = (*fakeStore)(nil)
+
+// githubFixture serves the releases API and the .apk asset downloads (with Range
+// support) for a set of packages. digest controls whether the asset carries a
+// sha256 digest (change-detection path) or not.
+type githubFixture struct {
+	srv         *httptest.Server
+	apkBytes    map[string][]byte
+	rangeHit    map[string]int
+	fullHit     map[string]int
+	etag        string
+	releasesHit int
+	notModHit   int
+	releaseAuth string
+	assetAuth   string
+	mu          sync.Mutex
+}
+
+func newGitHubFixture(t *testing.T, withDigest bool) *githubFixture {
+	t.Helper()
+	f := &githubFixture{
+		apkBytes: map[string][]byte{},
+		rangeHit: map[string]int{},
+		fullHit:  map[string]int{},
+	}
+	f.apkBytes["demo-1.2.3-r0.apk"] = testsupport.MinimalApk("demo", "1.2.3-r0", "x86_64")
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("/repos/acme/tools/releases", func(w http.ResponseWriter, r *http.Request) {
+		page := r.URL.Query().Get("page")
+		if page != "" && page != "1" {
+			w.Write([]byte("[]"))
+			return
+		}
+		f.mu.Lock()
+		f.releasesHit++
+		f.releaseAuth = r.Header.Get("Authorization")
+		etag := f.etag
+		if etag != "" && r.Header.Get("If-None-Match") == etag {
+			f.notModHit++
+			f.mu.Unlock()
+			w.WriteHeader(http.StatusNotModified)
+			return
+		}
+		f.mu.Unlock()
+		if etag != "" {
+			w.Header().Set("ETag", etag)
+		}
+		var assets []map[string]any
+		for name := range f.apkBytes {
+			a := map[string]any{
+				"name":                 name,
+				"size":                 len(f.apkBytes[name]),
+				"browser_download_url": f.srv.URL + "/acme/tools/releases/download/v1.2.3/" + name,
+			}
+			if withDigest {
+				sum := sha256.Sum256(f.apkBytes[name])
+				a["digest"] = "sha256:" + hex.EncodeToString(sum[:])
+			}
+			assets = append(assets, a)
+		}
+		rel := []map[string]any{{"tag_name": "v1.2.3", "draft": false, "assets": assets}}
+		json.NewEncoder(w).Encode(rel)
+	})
+	mux.HandleFunc("/acme/tools/releases/download/", func(w http.ResponseWriter, r *http.Request) {
+		name := r.URL.Path[strings.LastIndex(r.URL.Path, "/")+1:]
+		body, ok := f.apkBytes[name]
+		if !ok {
+			http.Error(w, "not found", 404)
+			return
+		}
+		rng := r.Header.Get("Range")
+		f.mu.Lock()
+		f.assetAuth = r.Header.Get("Authorization")
+		if rng != "" {
+			f.rangeHit[name]++
+		} else {
+			f.fullHit[name]++
+		}
+		f.mu.Unlock()
+
+		if rng == "" {
+			w.WriteHeader(200)
+			w.Write(body)
+			return
+		}
+		var end int
+		fmt.Sscanf(rng, "bytes=0-%d", &end)
+		if end >= len(body)-1 {
+			end = len(body) - 1
+		}
+		w.Header().Set("Content-Range", fmt.Sprintf("bytes 0-%d/%d", end, len(body)))
+		w.Header().Set("Content-Length", strconv.Itoa(end+1))
+		w.WriteHeader(http.StatusPartialContent)
+		w.Write(body[:end+1])
+	})
+	f.srv = httptest.NewServer(mux)
+	t.Cleanup(f.srv.Close)
+	return f
+}
+
+func (f *githubFixture) remote() models.Remote {
+	return models.Remote{
+		Name:           "acme-apk",
+		PackageType:    models.PackageGitHubAlpine,
+		BaseURL:        f.srv.URL + "/repos/acme/tools",
+		ReleasesRemote: "github",
+		MutableTTL:     3600,
+	}
+}
+
+func newTestProvider() *GitHubProvider {
+	p := newGitHubProvider()
+	p.headerInitial = 32 // force the ranged-fetch retry loop against the tiny fixture
+	p.headerMax = 1 << 20
+	return p
+}
+
+const demoPath = "acme/tools/releases/download/v1.2.3/demo-1.2.3-r0.apk"
+
+func TestGitHubScanDerivesPkginfoFromPrefix(t *testing.T) {
+	fx := newGitHubFixture(t, true)
+	p := newTestProvider()
+	store := newFakeStore()
+
+	if err := p.scan(context.Background(), fx.remote(), store); err != nil {
+		t.Fatalf("scan: %v", err)
+	}
+
+	metas, _ := store.ListAlpineMetadataEntries(context.Background(), "acme-apk")
+	if len(metas) != 1 {
+		t.Fatalf("want 1 metadata row, got %d", len(metas))
+	}
+	m := metas[0]
+	if m.Name != "demo" || m.Version != "1.2.3-r0" || m.Arch != "x86_64" {
+		t.Fatalf("bad .PKGINFO fields: %+v", m)
+	}
+	if m.FilePath != demoPath {
+		t.Fatalf("FilePath = %q, want %q", m.FilePath, demoPath)
+	}
+	if int(m.DownloadSize) != len(fx.apkBytes["demo-1.2.3-r0.apk"]) {
+		t.Fatalf("DownloadSize = %d, want %d", m.DownloadSize, len(fx.apkBytes["demo-1.2.3-r0.apk"]))
+	}
+	if !strings.HasPrefix(m.Checksum, "Q1") {
+		t.Fatalf("Checksum not a Q1 pull checksum: %q", m.Checksum)
+	}
+	// The C: checksum must equal Q1 over the raw control gzip stream, matching the
+	// local-upload parser applied to the same bytes.
+	want, err := parseApk(fx.apkBytes["demo-1.2.3-r0.apk"])
+	if err != nil {
+		t.Fatalf("reference parseApk: %v", err)
+	}
+	if m.Checksum != want.Checksum {
+		t.Fatalf("Checksum = %q, want %q (Q1 of control stream)", m.Checksum, want.Checksum)
+	}
+	if fx.fullHit["demo-1.2.3-r0.apk"] != 0 {
+		t.Fatalf("expected no full download, got %d", fx.fullHit["demo-1.2.3-r0.apk"])
+	}
+	if fx.rangeHit["demo-1.2.3-r0.apk"] == 0 {
+		t.Fatalf("expected ranged .PKGINFO fetch")
+	}
+}
+
+func TestGitHubServeRemoteIndexAndRedirect(t *testing.T) {
+	fx := newGitHubFixture(t, true)
+	p := newTestProvider()
+	store := newFakeStore()
+	remote := fx.remote()
+	const proxyBase = "https://artifactapi.example"
+
+	// The per-arch index is served and triggers the initial scan.
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/remote/acme-apk/x86_64/APKINDEX.tar.gz", nil)
+	if !p.ServeRemote(rec, req, remote, "x86_64/APKINDEX.tar.gz", proxyBase, store) {
+		t.Fatal("ServeRemote did not handle APKINDEX")
+	}
+	if rec.Code != 200 {
+		t.Fatalf("APKINDEX bad: code=%d body=%s", rec.Code, rec.Body.String())
+	}
+	idx := readAPKIndex(t, rec.Body.Bytes())
+	if !strings.Contains(idx, "P:demo") || !strings.Contains(idx, "A:x86_64") {
+		t.Fatalf("APKINDEX missing package record: %s", idx)
+	}
+	if !strings.Contains(idx, "C:Q1") {
+		t.Fatalf("APKINDEX missing pull checksum: %s", idx)
+	}
+
+	// A different arch yields an empty (but valid) index.
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodGet, "/x", nil)
+	if !p.ServeRemote(rec, req, remote, "aarch64/APKINDEX.tar.gz", proxyBase, store) {
+		t.Fatal("ServeRemote did not handle aarch64 APKINDEX")
+	}
+	if rec.Code != 200 {
+		t.Fatalf("empty-arch index bad: %d", rec.Code)
+	}
+	if got := readAPKIndex(t, rec.Body.Bytes()); strings.Contains(got, "P:demo") {
+		t.Fatalf("aarch64 index should not carry the x86_64 package: %s", got)
+	}
+
+	// An .apk request arrives in apk's reconstructed shape
+	// "<arch>/<name>-<version>.apk" (APKINDEX carries no filename), NOT as the
+	// github-relative FilePath. ServeRemote must resolve it back to the stored
+	// FilePath before redirecting to the backend releases_remote.
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodGet, "/api/v1/remote/acme-apk/x86_64/demo-1.2.3-r0.apk", nil)
+	if !p.ServeRemote(rec, req, remote, "x86_64/demo-1.2.3-r0.apk", proxyBase, store) {
+		t.Fatal("ServeRemote did not handle .apk")
+	}
+	if rec.Code != http.StatusFound {
+		t.Fatalf("want 302, got %d", rec.Code)
+	}
+	wantLoc := proxyBase + "/api/v1/remote/github/" + demoPath
+	if got := rec.Header().Get("Location"); got != wantLoc {
+		t.Fatalf("Location = %q, want %q (must be the stored FilePath, not the inbound path)", got, wantLoc)
+	}
+}
+
+// An apk download whose reconstructed "<arch>/<name>-<version>.apk" matches no
+// cached row must 404, never redirect to a bad path.
+func TestGitHubServeRemoteApkRedirectNotFound(t *testing.T) {
+	fx := newGitHubFixture(t, true)
+	p := newTestProvider()
+	store := newFakeStore()
+	remote := fx.remote()
+
+	// Warm the cache so the store is populated but lacks the requested package.
+	if err := p.scan(context.Background(), remote, store); err != nil {
+		t.Fatalf("warm scan: %v", err)
+	}
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/remote/acme-apk/x86_64/nope-9.9.9.apk", nil)
+	if !p.ServeRemote(rec, req, remote, "x86_64/nope-9.9.9.apk", "https://x", store) {
+		t.Fatal("ServeRemote did not handle .apk")
+	}
+	if rec.Code != http.StatusNotFound {
+		t.Fatalf("want 404 for unknown package, got %d (Location=%q)", rec.Code, rec.Header().Get("Location"))
+	}
+}
+
+// apk requests the index at "./<arch>/APKINDEX.tar.gz"; ServeRemote must collapse
+// the dot-segment and synthesize the same index as the un-prefixed request.
+func TestGitHubServeRemoteApkDotSegment(t *testing.T) {
+	fx := newGitHubFixture(t, true)
+	p := newTestProvider()
+	store := newFakeStore()
+	remote := fx.remote()
+	const proxyBase = "https://artifactapi.example"
+
+	serve := func(path string) *httptest.ResponseRecorder {
+		rec := httptest.NewRecorder()
+		req := httptest.NewRequest(http.MethodGet, "/api/v1/remote/acme-apk/"+path, nil)
+		if !p.ServeRemote(rec, req, remote, path, proxyBase, store) {
+			t.Fatalf("ServeRemote did not handle %q", path)
+		}
+		return rec
+	}
+
+	plain, dotted := serve("x86_64/APKINDEX.tar.gz"), serve("./x86_64/APKINDEX.tar.gz")
+	if plain.Code != 200 || dotted.Code != 200 {
+		t.Fatalf("index: plain=%d dotted=%d, want 200/200", plain.Code, dotted.Code)
+	}
+	if !bytes.Equal(plain.Body.Bytes(), dotted.Body.Bytes()) {
+		t.Error("./<arch>/APKINDEX.tar.gz body differs from the un-prefixed body")
+	}
+}
+
+func TestGitHubServeRemoteRejectsNonPerArchIndex(t *testing.T) {
+	fx := newGitHubFixture(t, true)
+	p := newTestProvider()
+	store := newFakeStore()
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/x", nil)
+	if !p.ServeRemote(rec, req, fx.remote(), "APKINDEX.tar.gz", "https://x", store) {
+		t.Fatal("expected handled")
+	}
+	if rec.Code != http.StatusNotFound {
+		t.Fatalf("bare APKINDEX must 404 (per-arch required), got %d", rec.Code)
+	}
+}
+
+// A canceled inbound request must still serve the warm cache (detached context),
+// not turn the metadata read into a 500.
+func TestGitHubServeRemoteCanceledRequestServesCache(t *testing.T) {
+	fx := newGitHubFixture(t, true)
+	p := newTestProvider()
+	store := newFakeStore()
+	remote := fx.remote()
+
+	if err := p.scan(context.Background(), remote, store); err != nil {
+		t.Fatalf("warm scan: %v", err)
+	}
+	p.mu.Lock()
+	p.lastScan[remote.Name] = time.Now()
+	p.mu.Unlock()
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/remote/acme-apk/x86_64/APKINDEX.tar.gz", nil).WithContext(ctx)
+
+	if !p.ServeRemote(rec, req, remote, "x86_64/APKINDEX.tar.gz", "https://x", store) {
+		t.Fatal("ServeRemote did not handle APKINDEX")
+	}
+	if rec.Code != http.StatusOK {
+		t.Fatalf("canceled request must serve cache, not error; got code=%d body=%s", rec.Code, rec.Body.String())
+	}
+	if got := readAPKIndex(t, rec.Body.Bytes()); !strings.Contains(got, "P:demo") {
+		t.Fatalf("expected index served from cache, got %s", got)
+	}
+}
+
+func TestGitHubServeRemoteRedirectRequiresReleasesRemote(t *testing.T) {
+	fx := newGitHubFixture(t, true)
+	p := newTestProvider()
+	store := newFakeStore()
+	remote := fx.remote()
+	remote.ReleasesRemote = ""
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/x", nil)
+	if !p.ServeRemote(rec, req, remote, demoPath, "https://x", store) {
+		t.Fatal("expected handled")
+	}
+	if rec.Code != http.StatusInternalServerError {
+		t.Fatalf("want 500 when releases_remote unset, got %d", rec.Code)
+	}
+}
+
+func TestGitHubScanPrunesRemovedAssets(t *testing.T) {
+	fx := newGitHubFixture(t, true)
+	p := newTestProvider()
+	store := newFakeStore()
+
+	if err := p.scan(context.Background(), fx.remote(), store); err != nil {
+		t.Fatalf("scan: %v", err)
+	}
+	if rows, _ := store.ListAlpineMetadataEntries(context.Background(), "acme-apk"); len(rows) != 1 {
+		t.Fatalf("want 1 row after first scan, got %d", len(rows))
+	}
+
+	delete(fx.apkBytes, "demo-1.2.3-r0.apk")
+	if err := p.scan(context.Background(), fx.remote(), store); err != nil {
+		t.Fatalf("rescan: %v", err)
+	}
+	if rows, _ := store.ListAlpineMetadataEntries(context.Background(), "acme-apk"); len(rows) != 0 {
+		t.Fatalf("want 0 rows after prune, got %d", len(rows))
+	}
+}
+
+func TestGitHubAssetPatternFilter(t *testing.T) {
+	fx := newGitHubFixture(t, true)
+	fx.apkBytes["other-9-r0.apk"] = testsupport.MinimalApk("other", "9-r0", "aarch64")
+	p := newTestProvider()
+	store := newFakeStore()
+	remote := fx.remote()
+	remote.Patterns = []string{`^demo-.*\.apk$`}
+
+	if err := p.scan(context.Background(), remote, store); err != nil {
+		t.Fatalf("scan: %v", err)
+	}
+	rows, _ := store.ListAlpineMetadataEntries(context.Background(), "acme-apk")
+	if len(rows) != 1 || rows[0].Name != "demo" {
+		t.Fatalf("pattern filter failed, rows=%+v", rows)
+	}
+}
+
+// Multi-arch: each asset's index record lands under its own arch bucket.
+func TestGitHubServeRemotePerArchGrouping(t *testing.T) {
+	fx := newGitHubFixture(t, true)
+	fx.apkBytes["demo-1.2.3-r0-aarch64.apk"] = testsupport.MinimalApk("demo", "1.2.3-r0", "aarch64")
+	p := newTestProvider()
+	store := newFakeStore()
+	remote := fx.remote()
+	const proxyBase = "https://x"
+
+	if err := p.scan(context.Background(), remote, store); err != nil {
+		t.Fatalf("scan: %v", err)
+	}
+
+	serve := func(arch string) string {
+		rec := httptest.NewRecorder()
+		req := httptest.NewRequest(http.MethodGet, "/x", nil)
+		if !p.ServeRemote(rec, req, remote, arch+"/APKINDEX.tar.gz", proxyBase, store) {
+			t.Fatalf("ServeRemote did not handle %s", arch)
+		}
+		return readAPKIndex(t, rec.Body.Bytes())
+	}
+
+	x86 := serve("x86_64")
+	if !strings.Contains(x86, "A:x86_64") || strings.Contains(x86, "A:aarch64") {
+		t.Fatalf("x86_64 index leaked another arch: %s", x86)
+	}
+	arm := serve("aarch64")
+	if !strings.Contains(arm, "A:aarch64") || strings.Contains(arm, "A:x86_64") {
+		t.Fatalf("aarch64 index leaked another arch: %s", arm)
+	}
+}
+
+func readAPKIndex(t *testing.T, gzBytes []byte) string {
+	t.Helper()
+	gz, err := gzip.NewReader(bytes.NewReader(gzBytes))
+	if err != nil {
+		t.Fatalf("gzip: %v", err)
+	}
+	tr := tar.NewReader(gz)
+	for {
+		hdr, err := tr.Next()
+		if err != nil {
+			t.Fatal("APKINDEX member missing from tar.gz")
+		}
+		if strings.TrimPrefix(hdr.Name, "./") == "APKINDEX" {
+			body, err := io.ReadAll(tr)
+			if err != nil {
+				t.Fatalf("read APKINDEX: %v", err)
+			}
+			return string(body)
+		}
+	}
+}

internal/provider/alpine/syncer.go

@@ -0,0 +1,238 @@
+package alpine
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"log/slog"
+	"os"
+	"sync"
+	"time"
+
+	"golang.org/x/time/rate"
+
+	"git.unkin.net/unkin/artifactapi/internal/provider"
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+const (
+	syncLeaseDuration    = 15 * time.Minute
+	defaultSyncFreshness = 5 * time.Minute
+	jobQueueDepth        = 256
+)
+
+// SyncStore is the persistence surface the alpine syncer needs: the metadata
+// cache it primes plus the shared sync-state coordination (remote enumeration
+// and the per-remote lease). *database.DB satisfies it.
+type SyncStore interface {
+	provider.RemoteMetadataStore
+	ListGitHubAlpineRemotes(ctx context.Context) ([]models.Remote, error)
+	ClaimGitHubAlpineSyncLease(ctx context.Context, remoteName, owner string, freshness, lease time.Duration) (claimed bool, etag string, err error)
+	ReleaseGitHubAlpineSyncLease(ctx context.Context, remoteName, owner, etag string, syncedAt time.Time) error
+}
+
+// SyncConfig tunes the shared syncer. Zero values fall back to safe defaults.
+type SyncConfig struct {
+	RatePerSec   float64
+	Burst        int
+	Workers      int
+	PollInterval time.Duration
+}
+
+type syncJob struct {
+	remote models.Remote
+	prime  bool
+}
+
+// Syncer is the single per-process background worker that keeps every
+// github_alpine remote's derived metadata fresh. It owns a deduped work queue, a
+// pool of workers, and a global token-bucket rate limiter shared across all
+// remotes and bound onto the github_alpine provider. Periodic checks are gated by
+// a shared DB lease so, across replicas, only one performs each scan.
+type Syncer struct {
+	store   SyncStore
+	prov    *GitHubProvider
+	limiter *rate.Limiter
+	cfg     SyncConfig
+	owner   string
+
+	jobs   chan syncJob
+	mu     sync.Mutex
+	active map[string]bool
+}
+
+// NewSyncer builds the syncer bound to the process-wide github_alpine provider
+// singleton. Call Run to start it.
+func NewSyncer(store SyncStore, cfg SyncConfig) *Syncer {
+	return newSyncer(store, gitHubProvider, cfg)
+}
+
+func newSyncer(store SyncStore, prov *GitHubProvider, cfg SyncConfig) *Syncer {
+	if cfg.RatePerSec <= 0 {
+		cfg.RatePerSec = 1
+	}
+	if cfg.Burst <= 0 {
+		cfg.Burst = 5
+	}
+	if cfg.Workers <= 0 {
+		cfg.Workers = 3
+	}
+	if cfg.PollInterval <= 0 {
+		cfg.PollInterval = 60 * time.Second
+	}
+
+	lim := rate.NewLimiter(rate.Limit(cfg.RatePerSec), cfg.Burst)
+	s := &Syncer{
+		store:   store,
+		prov:    prov,
+		limiter: lim,
+		cfg:     cfg,
+		owner:   leaseOwner(),
+		jobs:    make(chan syncJob, jobQueueDepth),
+		active:  map[string]bool{},
+	}
+	prov.limiter = lim
+	prov.syncer = s
+	return s
+}
+
+// Run starts the worker pool and the periodic scheduler and blocks until ctx is
+// canceled, at which point it drains in-flight scans and returns.
+func (s *Syncer) Run(ctx context.Context) {
+	slog.Info("github_alpine syncer started",
+		"rate_per_sec", s.cfg.RatePerSec, "burst", s.cfg.Burst,
+		"workers", s.cfg.Workers, "poll_interval", s.cfg.PollInterval, "owner", s.owner)
+
+	var wg sync.WaitGroup
+	for i := 0; i < s.cfg.Workers; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			s.worker(ctx)
+		}()
+	}
+
+	ticker := time.NewTicker(s.cfg.PollInterval)
+	defer ticker.Stop()
+
+	s.schedule(ctx)
+	for {
+		select {
+		case <-ctx.Done():
+			wg.Wait()
+			slog.Info("github_alpine syncer stopped")
+			return
+		case <-ticker.C:
+			s.schedule(ctx)
+		}
+	}
+}
+
+// schedule enqueues a periodic check for every github_alpine remote. The DB lease
+// enforces the per-remote mutable_ttl cadence and cross-replica coordination.
+func (s *Syncer) schedule(ctx context.Context) {
+	remotes, err := s.store.ListGitHubAlpineRemotes(ctx)
+	if err != nil {
+		slog.Error("github_alpine syncer: list remotes", "error", err)
+		return
+	}
+	for _, r := range remotes {
+		s.enqueue(r, false)
+	}
+}
+
+// EnqueuePrime queues an immediate background prime for a freshly created remote.
+func (s *Syncer) EnqueuePrime(remote models.Remote) {
+	if s == nil {
+		return
+	}
+	s.enqueue(remote, true)
+}
+
+// enqueue adds a job unless the remote is already queued or in-flight, coalescing
+// duplicate requests down to one scan. It never blocks.
+func (s *Syncer) enqueue(remote models.Remote, prime bool) {
+	s.mu.Lock()
+	if s.active[remote.Name] {
+		s.mu.Unlock()
+		return
+	}
+	s.active[remote.Name] = true
+	s.mu.Unlock()
+
+	select {
+	case s.jobs <- syncJob{remote: remote, prime: prime}:
+	default:
+		s.mu.Lock()
+		delete(s.active, remote.Name)
+		s.mu.Unlock()
+	}
+}
+
+func (s *Syncer) worker(ctx context.Context) {
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case job := <-s.jobs:
+			s.process(ctx, job)
+		}
+	}
+}
+
+// process claims the shared lease and, if won, runs an incremental scan. Losing
+// the claim (another replica scanning, or not yet due) is a no-op.
+func (s *Syncer) process(ctx context.Context, job syncJob) {
+	defer func() {
+		s.mu.Lock()
+		delete(s.active, job.remote.Name)
+		s.mu.Unlock()
+	}()
+
+	freshness := time.Duration(job.remote.MutableTTL) * time.Second
+	if freshness <= 0 {
+		freshness = defaultSyncFreshness
+	}
+	if job.prime {
+		freshness = 0
+	}
+
+	claimed, etag, err := s.store.ClaimGitHubAlpineSyncLease(ctx, job.remote.Name, s.owner, freshness, syncLeaseDuration)
+	if err != nil {
+		slog.Error("github_alpine syncer: claim lease", "remote", job.remote.Name, "error", err)
+		return
+	}
+	if !claimed {
+		return
+	}
+
+	scanCtx, cancel := context.WithTimeout(ctx, s.prov.scanTimeout)
+	defer cancel()
+
+	newEtag, changed, scanErr := s.prov.scanWithState(scanCtx, job.remote, s.store, etag)
+	releaseEtag := etag
+	if scanErr == nil {
+		releaseEtag = newEtag
+	} else {
+		slog.Error("github_alpine syncer: scan failed", "remote", job.remote.Name, "error", scanErr)
+	}
+
+	relCtx, relCancel := context.WithTimeout(context.WithoutCancel(ctx), 10*time.Second)
+	defer relCancel()
+	if err := s.store.ReleaseGitHubAlpineSyncLease(relCtx, job.remote.Name, s.owner, releaseEtag, time.Now()); err != nil {
+		slog.Warn("github_alpine syncer: release lease", "remote", job.remote.Name, "error", err)
+	}
+
+	if scanErr == nil && changed {
+		slog.Info("github_alpine syncer: refreshed", "remote", job.remote.Name, "prime", job.prime)
+	}
+}
+
+// leaseOwner is a per-replica identity for the lease: hostname plus a random
+// suffix so restarts and colocated replicas never collide.
+func leaseOwner() string {
+	host, _ := os.Hostname()
+	var b [6]byte
+	_, _ = rand.Read(b[:])
+	return host + "-" + hex.EncodeToString(b[:])
+}

internal/provider/alpine/syncer_test.go

@@ -0,0 +1,300 @@
+package alpine
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"testing"
+	"time"
+
+	"golang.org/x/time/rate"
+
+	"git.unkin.net/unkin/artifactapi/internal/provider"
+	"git.unkin.net/unkin/artifactapi/internal/testsupport"
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+// fakeSyncStore is an in-memory SyncStore: the metadata cache (via the embedded
+// fakeStore) plus the shared sync-state lease, whose claim mirrors the atomic
+// semantics of the real SQL (recency gate AND no live lease).
+type fakeSyncStore struct {
+	*fakeStore
+
+	mu         sync.Mutex
+	remotes    []models.Remote
+	leaseOwner map[string]string
+	leaseExp   map[string]time.Time
+	lastSynced map[string]time.Time
+	etags      map[string]string
+}
+
+func newFakeSyncStore() *fakeSyncStore {
+	return &fakeSyncStore{
+		fakeStore:  newFakeStore(),
+		leaseOwner: map[string]string{},
+		leaseExp:   map[string]time.Time{},
+		lastSynced: map[string]time.Time{},
+		etags:      map[string]string{},
+	}
+}
+
+func (f *fakeSyncStore) ListGitHubAlpineRemotes(_ context.Context) ([]models.Remote, error) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return append([]models.Remote(nil), f.remotes...), nil
+}
+
+func (f *fakeSyncStore) ClaimGitHubAlpineSyncLease(_ context.Context, name, owner string, freshness, lease time.Duration) (bool, string, error) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	now := time.Now()
+	ls, hasLS := f.lastSynced[name]
+	exp, hasExp := f.leaseExp[name]
+	freshOK := !hasLS || now.Sub(ls) >= freshness
+	leaseOK := !hasExp || exp.Before(now)
+	if freshOK && leaseOK {
+		f.leaseOwner[name] = owner
+		f.leaseExp[name] = now.Add(lease)
+		return true, f.etags[name], nil
+	}
+	return false, "", nil
+}
+
+func (f *fakeSyncStore) ReleaseGitHubAlpineSyncLease(_ context.Context, name, owner, etag string, syncedAt time.Time) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if f.leaseOwner[name] != owner {
+		return nil
+	}
+	f.lastSynced[name] = syncedAt
+	f.etags[name] = etag
+	delete(f.leaseOwner, name)
+	delete(f.leaseExp, name)
+	return nil
+}
+
+func testSyncConfig() SyncConfig {
+	return SyncConfig{RatePerSec: 1000, Burst: 100, Workers: 1, PollInterval: time.Hour}
+}
+
+// (a) A 304 conditional response must derive nothing: no asset fetches and
+// changed=false, so an unchanged repo is nearly free.
+func TestSyncerConditionalNotModifiedSkipsDerive(t *testing.T) {
+	fx := newGitHubFixture(t, true)
+	fx.etag = `"v1"`
+	p := newTestProvider()
+	store := newFakeStore()
+	remote := fx.remote()
+
+	etag1, changed, err := p.scanWithState(context.Background(), remote, store, "")
+	if err != nil {
+		t.Fatalf("first scan: %v", err)
+	}
+	if !changed || etag1 != `"v1"` {
+		t.Fatalf("first scan changed=%v etag=%q, want true and \"v1\"", changed, etag1)
+	}
+	priorRange := fx.rangeHit["demo-1.2.3-r0.apk"]
+	if priorRange == 0 {
+		t.Fatal("first scan should have fetched the asset .PKGINFO")
+	}
+
+	etag2, changed2, err := p.scanWithState(context.Background(), remote, store, etag1)
+	if err != nil {
+		t.Fatalf("second scan: %v", err)
+	}
+	if changed2 {
+		t.Fatal("304 scan must report changed=false")
+	}
+	if etag2 != etag1 {
+		t.Fatalf("etag changed across 304: %q -> %q", etag1, etag2)
+	}
+	if fx.notModHit != 1 {
+		t.Fatalf("want exactly one 304 releases response, got %d", fx.notModHit)
+	}
+	if got := fx.rangeHit["demo-1.2.3-r0.apk"]; got != priorRange {
+		t.Fatalf("304 scan re-fetched asset .PKGINFO: %d -> %d", priorRange, got)
+	}
+}
+
+// (b) On a real change, only the newly added asset is derived.
+func TestSyncerIncrementalDerivesOnlyNewAsset(t *testing.T) {
+	fx := newGitHubFixture(t, true)
+	fx.etag = `"v1"`
+	p := newTestProvider()
+	store := newFakeStore()
+	remote := fx.remote()
+
+	if _, _, err := p.scanWithState(context.Background(), remote, store, ""); err != nil {
+		t.Fatalf("first scan: %v", err)
+	}
+	demoRange := fx.rangeHit["demo-1.2.3-r0.apk"]
+
+	fx.apkBytes["other-9-r0.apk"] = testsupport.MinimalApk("other", "9-r0", "aarch64")
+	fx.etag = `"v2"`
+
+	if _, changed, err := p.scanWithState(context.Background(), remote, store, `"v1"`); err != nil || !changed {
+		t.Fatalf("second scan changed=%v err=%v", changed, err)
+	}
+
+	rows, _ := store.ListAlpineMetadataEntries(context.Background(), remote.Name)
+	if len(rows) != 2 {
+		t.Fatalf("want 2 cached rows after incremental derive, got %d", len(rows))
+	}
+	if got := fx.rangeHit["demo-1.2.3-r0.apk"]; got != demoRange {
+		t.Fatalf("already-cached asset was re-fetched: %d -> %d", demoRange, got)
+	}
+	if fx.rangeHit["other-9-r0.apk"] == 0 {
+		t.Fatal("newly added asset was not derived")
+	}
+}
+
+// (c) The shared limiter caps the request rate.
+func TestRateLimiterCapsRequestRate(t *testing.T) {
+	fx := newGitHubFixture(t, true)
+	p := newTestProvider()
+	p.limiter = rate.NewLimiter(rate.Every(120*time.Millisecond), 1)
+	remote := fx.remote()
+
+	start := time.Now()
+	for i := 0; i < 3; i++ {
+		if _, _, _, err := p.fetchReleases(context.Background(), remote, ""); err != nil {
+			t.Fatalf("fetchReleases %d: %v", i, err)
+		}
+	}
+	if elapsed := time.Since(start); elapsed < 200*time.Millisecond {
+		t.Fatalf("rate limiter did not throttle: 3 calls took %v, want >= 200ms", elapsed)
+	}
+}
+
+// (d) Concurrent enqueues for the same remote coalesce to a single queued job.
+func TestSyncerEnqueueDedup(t *testing.T) {
+	store := newFakeSyncStore()
+	p := newTestProvider()
+	s := newSyncer(store, p, testSyncConfig())
+	remote := models.Remote{Name: "acme-apk", PackageType: models.PackageGitHubAlpine, MutableTTL: 3600}
+
+	var wg sync.WaitGroup
+	for i := 0; i < 10; i++ {
+		wg.Add(1)
+		go func() { defer wg.Done(); s.enqueue(remote, false) }()
+	}
+	wg.Wait()
+
+	if got := len(s.jobs); got != 1 {
+		t.Fatalf("want exactly 1 coalesced job, got %d", got)
+	}
+}
+
+// (e) Prime-on-create enqueues a prime job.
+func TestSyncerEnqueuePrime(t *testing.T) {
+	store := newFakeSyncStore()
+	p := newTestProvider()
+	s := newSyncer(store, p, testSyncConfig())
+	remote := models.Remote{Name: "acme-apk", PackageType: models.PackageGitHubAlpine, MutableTTL: 3600}
+
+	s.EnqueuePrime(remote)
+	select {
+	case job := <-s.jobs:
+		if !job.prime || job.remote.Name != "acme-apk" {
+			t.Fatalf("bad prime job: %+v", job)
+		}
+	default:
+		t.Fatal("EnqueuePrime did not enqueue a job")
+	}
+}
+
+// (f) A held lease prevents a second replica from scanning.
+func TestSyncerLeasePreventsSecondReplica(t *testing.T) {
+	fx := newGitHubFixture(t, true)
+	fx.etag = `"v1"`
+	store := newFakeSyncStore()
+	p := newTestProvider()
+	s := newSyncer(store, p, testSyncConfig())
+	remote := fx.remote()
+
+	claimed, _, err := store.ClaimGitHubAlpineSyncLease(context.Background(), remote.Name, "replica-1", time.Duration(remote.MutableTTL)*time.Second, syncLeaseDuration)
+	if err != nil || !claimed {
+		t.Fatalf("replica-1 claim: claimed=%v err=%v", claimed, err)
+	}
+
+	s.process(context.Background(), syncJob{remote: remote})
+
+	if fx.releasesHit != 0 {
+		t.Fatalf("second replica scanned while lease held: %d releases calls", fx.releasesHit)
+	}
+	if rows, _ := store.ListAlpineMetadataEntries(context.Background(), remote.Name); len(rows) != 0 {
+		t.Fatalf("second replica derived metadata while lease held: %d rows", len(rows))
+	}
+}
+
+// With the syncer wired and the cache empty, an index request enqueues a prime
+// and returns a retryable 503 when it has not landed within the cold wait.
+func TestServeRemoteColdStartReturns503(t *testing.T) {
+	fx := newGitHubFixture(t, true)
+	store := newFakeSyncStore()
+	p := newTestProvider()
+	p.coldWait = 300 * time.Millisecond
+	_ = newSyncer(store, p, testSyncConfig()) // binds p.syncer, but no workers running
+	remote := fx.remote()
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/remote/acme-apk/x86_64/APKINDEX.tar.gz", nil)
+	if !p.ServeRemote(rec, req, remote, "x86_64/APKINDEX.tar.gz", "https://x", store) {
+		t.Fatal("ServeRemote did not handle APKINDEX")
+	}
+	if rec.Code != http.StatusServiceUnavailable {
+		t.Fatalf("cold empty cache must return 503, got %d", rec.Code)
+	}
+	if rec.Header().Get("Retry-After") == "" {
+		t.Fatal("503 should carry Retry-After")
+	}
+	if got := len(p.syncer.jobs); got != 1 {
+		t.Fatalf("cold start did not enqueue a prime, jobs=%d", got)
+	}
+}
+
+// With the cache warm, the same request serves the index immediately (no 503).
+func TestServeRemoteWarmCacheServesImmediately(t *testing.T) {
+	fx := newGitHubFixture(t, true)
+	store := newFakeSyncStore()
+	p := newTestProvider()
+	_ = newSyncer(store, p, testSyncConfig())
+	remote := fx.remote()
+
+	if err := p.scan(context.Background(), remote, store); err != nil {
+		t.Fatalf("warm scan: %v", err)
+	}
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/remote/acme-apk/x86_64/APKINDEX.tar.gz", nil)
+	if !p.ServeRemote(rec, req, remote, "x86_64/APKINDEX.tar.gz", "https://x", store) {
+		t.Fatal("ServeRemote did not handle APKINDEX")
+	}
+	if rec.Code != http.StatusOK {
+		t.Fatalf("warm cache must serve 200, got %d body=%s", rec.Code, rec.Body.String())
+	}
+}
+
+// A prime job (freshness 0) runs even right after a sync; a periodic job at the
+// same moment is gated by the recency window.
+func TestSyncerPrimeBypassesRecencyPeriodicDoesNot(t *testing.T) {
+	fx := newGitHubFixture(t, true)
+	fx.etag = `"v1"`
+	store := newFakeSyncStore()
+	p := newTestProvider()
+	s := newSyncer(store, p, testSyncConfig())
+	remote := fx.remote()
+
+	var _ provider.RemoteMetadataStore = store
+
+	s.process(context.Background(), syncJob{remote: remote, prime: true})
+	if rows, _ := store.ListAlpineMetadataEntries(context.Background(), remote.Name); len(rows) != 1 {
+		t.Fatalf("prime did not derive: %d rows", len(rows))
+	}
+	releasesAfterPrime := fx.releasesHit
+
+	s.process(context.Background(), syncJob{remote: remote, prime: false})
+	if fx.releasesHit != releasesAfterPrime {
+		t.Fatalf("periodic scan ran inside recency window: %d -> %d releases calls", releasesAfterPrime, fx.releasesHit)
+	}
+}

internal/provider/deb/deb.go

@@ -0,0 +1,462 @@
+package deb
+
+import (
+	"archive/tar"
+	"bufio"
+	"bytes"
+	"compress/gzip"
+	"context"
+	"crypto/md5"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"net/http"
+	"path"
+	"regexp"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/klauspost/compress/zstd"
+	"github.com/ulikunitz/xz"
+
+	"git.unkin.net/unkin/artifactapi/internal/auth"
+	"git.unkin.net/unkin/artifactapi/internal/provider"
+	"git.unkin.net/unkin/artifactapi/internal/storage"
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+func init() {
+	provider.Register(&Provider{})
+}
+
+// mutableRe marks the apt index surface (both the flat local repo and a proxied
+// Debian/Ubuntu mirror's dists/ tree) so the caching engine revalidates it
+// instead of freezing it like an immutable .deb.
+var mutableRe = []*regexp.Regexp{
+	regexp.MustCompile(`(^|/)Packages(\.gz|\.xz|\.bz2)?$`),
+	regexp.MustCompile(`(^|/)Sources(\.gz|\.xz|\.bz2)?$`),
+	regexp.MustCompile(`(^|/)Release$`),
+	regexp.MustCompile(`(^|/)InRelease$`),
+	regexp.MustCompile(`(^|/)Release\.gpg$`),
+	regexp.MustCompile(`(^|/)Contents-`),
+	regexp.MustCompile(`^dists/`),
+	regexp.MustCompile(`/by-hash/`),
+}
+
+type Provider struct{}
+
+func (p *Provider) Type() models.PackageType { return models.PackageDeb }
+
+func (p *Provider) Classify(path string) provider.Mutability {
+	for _, re := range mutableRe {
+		if re.MatchString(path) {
+			return provider.Mutable
+		}
+	}
+	return provider.Immutable
+}
+
+func (p *Provider) ContentType(path string) string {
+	switch {
+	case strings.HasSuffix(path, ".deb"):
+		return "application/vnd.debian.binary-package"
+	case strings.HasSuffix(path, ".gz"):
+		return "application/gzip"
+	case strings.HasSuffix(path, ".xz"):
+		return "application/x-xz"
+	case strings.HasSuffix(path, "Packages"), strings.HasSuffix(path, "Release"),
+		strings.HasSuffix(path, "InRelease"), strings.HasSuffix(path, "Sources"):
+		return "text/plain"
+	}
+	return "application/octet-stream"
+}
+
+func (p *Provider) UpstreamURL(remote models.Remote, path string) string {
+	return strings.TrimRight(remote.BaseURL, "/") + "/" + strings.TrimLeft(path, "/")
+}
+
+func (p *Provider) RewriteResponse(_ []byte, _ models.Remote, _ string) ([]byte, error) {
+	return nil, nil
+}
+
+func (p *Provider) AuthHeaders(_ context.Context, remote models.Remote) (http.Header, error) {
+	return auth.BasicHeaders(remote), nil
+}
+
+func (p *Provider) ValidateUpload(filePath string) (storagePath, contentType string, err error) {
+	filename := filePath
+	if idx := strings.LastIndex(filePath, "/"); idx >= 0 {
+		filename = filePath[idx+1:]
+	}
+
+	if !strings.HasSuffix(strings.ToLower(filename), ".deb") {
+		return "", "", fmt.Errorf("file must be a .deb package")
+	}
+
+	return "pool/" + filename, "application/vnd.debian.binary-package", nil
+}
+
+func (p *Provider) UploadResponse(storagePath, contentHash string, sizeBytes int64) map[string]any {
+	filename := strings.TrimPrefix(storagePath, "pool/")
+	return map[string]any{
+		"filename":     filename,
+		"content_hash": contentHash,
+		"size_bytes":   sizeBytes,
+	}
+}
+
+func (p *Provider) AfterUpload(ctx context.Context, repoName, storagePath, contentHash string, blobs provider.BlobReader, db provider.MetadataStore) {
+	s3Key := storage.BlobKey(strings.TrimPrefix(contentHash, "sha256:"))
+
+	reader, blobSize, err := blobs.Download(ctx, s3Key)
+	if err != nil {
+		slog.Error("deb metadata: download failed", "repo", repoName, "path", storagePath, "error", err)
+		return
+	}
+	defer reader.Close()
+
+	raw, err := io.ReadAll(reader)
+	if err != nil {
+		slog.Error("deb metadata: read failed", "repo", repoName, "path", storagePath, "error", err)
+		return
+	}
+
+	control, err := extractControl(raw)
+	if err != nil {
+		slog.Error("deb metadata: parse failed", "repo", repoName, "path", storagePath, "error", err)
+		return
+	}
+	fields := parseControlFields(control)
+
+	sum := md5.Sum(raw)
+	meta := &provider.DebMetadata{
+		RepoName:     repoName,
+		FilePath:     storagePath,
+		ContentHash:  contentHash,
+		Name:         fields["Package"],
+		Version:      fields["Version"],
+		Architecture: fields["Architecture"],
+		Control:      strings.TrimRight(control, "\n"),
+		Size:         blobSize,
+		MD5:          hex.EncodeToString(sum[:]),
+		SHA256:       strings.TrimPrefix(contentHash, "sha256:"),
+	}
+
+	if meta.Name == "" {
+		slog.Error("deb metadata: control missing Package field", "repo", repoName, "path", storagePath)
+		return
+	}
+
+	if err := db.InsertDebMetadata(ctx, meta); err != nil {
+		slog.Error("deb metadata: insert failed", "repo", repoName, "path", storagePath, "error", err)
+		return
+	}
+
+	slog.Info("deb metadata: parsed", "repo", repoName, "name", meta.Name, "version", meta.Version, "arch", meta.Architecture)
+}
+
+func (p *Provider) AfterDelete(ctx context.Context, repoName, storagePath string, db provider.MetadataDeleter) error {
+	if err := db.DeleteDebMetadata(ctx, repoName, storagePath); err != nil {
+		slog.Error("deb metadata: delete failed", "repo", repoName, "path", storagePath, "error", err)
+		return err
+	}
+	slog.Info("deb metadata: deleted", "repo", repoName, "path", storagePath)
+	return nil
+}
+
+// extractControl reads a .deb (an ar archive), locates the control.tar.* member,
+// decompresses it, and returns the raw ./control paragraph. Pure Go: no dpkg.
+func extractControl(deb []byte) (string, error) {
+	members, err := readAr(deb)
+	if err != nil {
+		return "", err
+	}
+
+	var name string
+	var data []byte
+	for _, m := range members {
+		if strings.HasPrefix(m.name, "control.tar") {
+			name = m.name
+			data = m.data
+			break
+		}
+	}
+	if data == nil {
+		return "", errors.New("no control.tar member in .deb")
+	}
+
+	tarBytes, err := decompress(name, data)
+	if err != nil {
+		return "", err
+	}
+
+	return readControlParagraph(tarBytes)
+}
+
+// readControlParagraph scans a decompressed control.tar and returns the raw
+// ./control paragraph. Shared by the local upload path (extractControl) and the
+// github_deb ranged-prefix parser.
+func readControlParagraph(controlTar []byte) (string, error) {
+	tr := tar.NewReader(bytes.NewReader(controlTar))
+	for {
+		hdr, err := tr.Next()
+		if err == io.EOF {
+			break
+		}
+		if err != nil {
+			return "", fmt.Errorf("read control.tar: %w", err)
+		}
+		clean := strings.TrimPrefix(hdr.Name, "./")
+		if clean == "control" {
+			b, err := io.ReadAll(tr)
+			if err != nil {
+				return "", fmt.Errorf("read control file: %w", err)
+			}
+			return string(b), nil
+		}
+	}
+	return "", errors.New("no ./control in control.tar")
+}
+
+func decompress(name string, data []byte) ([]byte, error) {
+	switch {
+	case strings.HasSuffix(name, ".gz"):
+		zr, err := gzip.NewReader(bytes.NewReader(data))
+		if err != nil {
+			return nil, err
+		}
+		defer zr.Close()
+		return io.ReadAll(zr)
+	case strings.HasSuffix(name, ".xz"):
+		xr, err := xz.NewReader(bytes.NewReader(data))
+		if err != nil {
+			return nil, err
+		}
+		return io.ReadAll(xr)
+	case strings.HasSuffix(name, ".zst"):
+		zr, err := zstd.NewReader(bytes.NewReader(data))
+		if err != nil {
+			return nil, err
+		}
+		defer zr.Close()
+		return io.ReadAll(zr)
+	case strings.HasSuffix(name, ".tar"):
+		return data, nil
+	}
+	return nil, fmt.Errorf("unsupported control.tar compression: %s", name)
+}
+
+type arMember struct {
+	name string
+	data []byte
+}
+
+// readAr parses the (trivial) Unix ar archive that wraps a .deb. Each member has
+// a 60-byte header; the size field is decimal ASCII and data is padded to an
+// even offset.
+func readAr(data []byte) ([]arMember, error) {
+	const magic = "!<arch>\n"
+	if len(data) < len(magic) || string(data[:len(magic)]) != magic {
+		return nil, errors.New("not an ar archive")
+	}
+	off := len(magic)
+
+	var members []arMember
+	for off+60 <= len(data) {
+		hdr := data[off : off+60]
+		off += 60
+
+		name := strings.TrimRight(string(hdr[0:16]), " ")
+		name = strings.TrimSuffix(name, "/")
+		size, err := strconv.ParseInt(strings.TrimSpace(string(hdr[48:58])), 10, 64)
+		if err != nil {
+			return nil, fmt.Errorf("bad ar size for %q: %w", name, err)
+		}
+		if off+int(size) > len(data) {
+			return nil, fmt.Errorf("truncated ar member %q", name)
+		}
+		members = append(members, arMember{name: name, data: data[off : off+int(size)]})
+		off += int(size)
+		if size%2 == 1 {
+			off++
+		}
+	}
+	return members, nil
+}
+
+// parseControlFields reads the single-line fields of an RFC822-style control
+// paragraph. Continuation lines (leading whitespace) belong to the previous
+// field and are ignored here since only Package/Version/Architecture are read.
+func parseControlFields(control string) map[string]string {
+	fields := map[string]string{}
+	sc := bufio.NewScanner(strings.NewReader(control))
+	sc.Buffer(make([]byte, 0, 64*1024), 1024*1024)
+	for sc.Scan() {
+		line := sc.Text()
+		if line == "" || line[0] == ' ' || line[0] == '\t' {
+			continue
+		}
+		idx := strings.IndexByte(line, ':')
+		if idx < 0 {
+			continue
+		}
+		key := strings.TrimSpace(line[:idx])
+		if _, seen := fields[key]; seen {
+			continue
+		}
+		fields[key] = strings.TrimSpace(line[idx+1:])
+	}
+	return fields
+}
+
+// normalizeIndexPath collapses apt's verbatim dist prefix from a flat-repo
+// request. For `deb ... <repo>/ ./`, apt appends the "./" dist literally and asks
+// for "./Packages" (and "./Release", "./InRelease"); dot-segments must be
+// collapsed so the index matcher sees "Packages". A no-op for pool/*.deb paths.
+func normalizeIndexPath(p string) string {
+	return strings.TrimPrefix(path.Clean("/"+p), "/")
+}
+
+func (p *Provider) ServeLocalIndex(w http.ResponseWriter, r *http.Request, files provider.FileStore, repoName, reqPath string) bool {
+	path := normalizeIndexPath(reqPath)
+	switch path {
+	case "Packages", "Packages.gz", "Release":
+	default:
+		return false
+	}
+
+	reader, ok := files.(provider.DebMetadataReader)
+	if !ok {
+		http.Error(w, "deb metadata not available", http.StatusInternalServerError)
+		return true
+	}
+
+	metas, err := reader.ListDebMetadataEntries(r.Context(), repoName)
+	if err != nil {
+		if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
+			slog.Warn("deb: metadata read canceled", "repo", repoName, "error", err)
+			http.Error(w, "metadata read canceled", http.StatusServiceUnavailable)
+			return true
+		}
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return true
+	}
+
+	switch path {
+	case "Packages":
+		w.Header().Set("Content-Type", "text/plain")
+		w.WriteHeader(http.StatusOK)
+		w.Write(generatePackages(metas))
+	case "Packages.gz":
+		w.Header().Set("Content-Type", "application/gzip")
+		w.WriteHeader(http.StatusOK)
+		w.Write(gzipBytes(generatePackages(metas)))
+	case "Release":
+		w.Header().Set("Content-Type", "text/plain")
+		w.WriteHeader(http.StatusOK)
+		w.Write(generateRelease(metas))
+	}
+	return true
+}
+
+func (p *Provider) GenerateLocalIndex(ctx context.Context, files provider.FileStore, repoName, path string) ([]byte, error) {
+	return nil, fmt.Errorf("deb local index generation for virtual repos not supported")
+}
+
+// generatePackages emits the flat-repo Packages file: each package's raw control
+// stanza followed by the apt-required Filename/Size/MD5sum/SHA256 fields, blank
+// line separated.
+func generatePackages(metas []provider.DebMetadata) []byte {
+	var b bytes.Buffer
+	for _, m := range metas {
+		b.WriteString(strings.TrimRight(m.Control, "\n"))
+		b.WriteString("\n")
+		fmt.Fprintf(&b, "Filename: %s\n", m.FilePath)
+		fmt.Fprintf(&b, "Size: %d\n", m.Size)
+		if m.MD5 != "" {
+			fmt.Fprintf(&b, "MD5sum: %s\n", m.MD5)
+		}
+		if m.SHA256 != "" {
+			fmt.Fprintf(&b, "SHA256: %s\n", m.SHA256)
+		}
+		b.WriteString("\n")
+	}
+	return b.Bytes()
+}
+
+func generateRelease(metas []provider.DebMetadata) []byte {
+	packages := generatePackages(metas)
+	packagesGz := gzipBytes(packages)
+
+	arches := uniqueArches(metas)
+
+	var b bytes.Buffer
+	fmt.Fprintf(&b, "Date: %s\n", releaseDate(metas).Format(time.RFC1123Z))
+	fmt.Fprintf(&b, "Architectures: %s\n", strings.Join(arches, " "))
+	b.WriteString("Acquire-By-Hash: no\n")
+
+	b.WriteString("MD5Sum:\n")
+	writeReleaseEntry(&b, md5Hex(packages), len(packages), "Packages")
+	writeReleaseEntry(&b, md5Hex(packagesGz), len(packagesGz), "Packages.gz")
+
+	b.WriteString("SHA256:\n")
+	writeReleaseEntry(&b, sha256Hex(packages), len(packages), "Packages")
+	writeReleaseEntry(&b, sha256Hex(packagesGz), len(packagesGz), "Packages.gz")
+
+	return b.Bytes()
+}
+
+// releaseDate derives the Release Date: from the newest package's persisted
+// created_at (in UTC) so the file is byte-identical across the no-affinity
+// replicas and across regenerations (issue #117); an empty repo falls back to
+// the Unix epoch. This never uses wall clock, which also keeps Date: from
+// running ahead of any Valid-Until logic.
+func releaseDate(metas []provider.DebMetadata) time.Time {
+	newest := time.Unix(0, 0)
+	for _, m := range metas {
+		if m.CreatedAt.After(newest) {
+			newest = m.CreatedAt
+		}
+	}
+	return newest.UTC()
+}
+
+func writeReleaseEntry(b *bytes.Buffer, hash string, size int, name string) {
+	fmt.Fprintf(b, " %s %d %s\n", hash, size, name)
+}
+
+func uniqueArches(metas []provider.DebMetadata) []string {
+	seen := map[string]bool{}
+	var out []string
+	for _, m := range metas {
+		a := m.Architecture
+		if a == "" || seen[a] {
+			continue
+		}
+		seen[a] = true
+		out = append(out, a)
+	}
+	return out
+}
+
+func gzipBytes(data []byte) []byte {
+	var buf bytes.Buffer
+	gz := gzip.NewWriter(&buf)
+	gz.Write(data)
+	gz.Close()
+	return buf.Bytes()
+}
+
+func md5Hex(data []byte) string {
+	h := md5.Sum(data)
+	return hex.EncodeToString(h[:])
+}
+
+func sha256Hex(data []byte) string {
+	h := sha256.Sum256(data)
+	return hex.EncodeToString(h[:])
+}

internal/provider/deb/deb_deterministic_test.go

@@ -0,0 +1,172 @@
+package deb
+
+import (
+	"bytes"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+
+	"git.unkin.net/unkin/artifactapi/internal/provider"
+)
+
+// debFixture returns a fixed set of rows with persisted created_at values, in
+// the total order ListDebMetadataEntries produces (name, version, arch,
+// file_path), so the generators are exercised on a stable input.
+func debFixture() []provider.DebMetadata {
+	t1 := time.Date(2026, 3, 1, 8, 30, 0, 0, time.UTC)
+	t2 := time.Date(2026, 4, 15, 12, 0, 0, 0, time.UTC) // newest
+	return []provider.DebMetadata{
+		{
+			RepoName: "r", FilePath: "pool/aaa_1.0_amd64.deb", ContentHash: "sha256:aa",
+			Name: "aaa", Version: "1.0", Architecture: "amd64",
+			Control: "Package: aaa\nVersion: 1.0\nArchitecture: amd64",
+			Size:    100, MD5: "d41d8cd98f00b204e9800998ecf8427e", SHA256: "aa", CreatedAt: t1,
+		},
+		{
+			RepoName: "r", FilePath: "pool/bbb_2.0_arm64.deb", ContentHash: "sha256:bb",
+			Name: "bbb", Version: "2.0", Architecture: "arm64",
+			Control: "Package: bbb\nVersion: 2.0\nArchitecture: arm64",
+			Size:    200, MD5: "0cc175b9c0f1b6a831c399e269772661", SHA256: "bb", CreatedAt: t2,
+		},
+	}
+}
+
+// TestDebGeneratorsDeterministic asserts the served bytes are a pure function of
+// DB state: Packages, Packages.gz and Release are byte-identical across two
+// generations separated by wall-clock time. Fails against the old
+// time.Now()-stamped Release Date:.
+func TestDebGeneratorsDeterministic(t *testing.T) {
+	metas := debFixture()
+
+	pkgs1 := generatePackages(metas)
+	rel1 := generateRelease(metas)
+	gz1 := gzipBytes(pkgs1)
+
+	time.Sleep(10 * time.Millisecond)
+
+	pkgs2 := generatePackages(metas)
+	rel2 := generateRelease(metas)
+	gz2 := gzipBytes(pkgs2)
+
+	if !bytes.Equal(pkgs1, pkgs2) {
+		t.Error("Packages differs across generations")
+	}
+	if !bytes.Equal(gz1, gz2) {
+		t.Error("Packages.gz differs across generations")
+	}
+	if !bytes.Equal(rel1, rel2) {
+		t.Errorf("Release differs across generations:\n--- first ---\n%s\n--- second ---\n%s", rel1, rel2)
+	}
+}
+
+// TestDebReleaseDateUsesPersistedCreatedAt pins the Release Date: to the newest
+// persisted created_at (RFC1123Z, UTC), not wall clock. Fails against the old
+// time.Now() code.
+func TestDebReleaseDateUsesPersistedCreatedAt(t *testing.T) {
+	metas := debFixture()
+	want := time.Date(2026, 4, 15, 12, 0, 0, 0, time.UTC).Format(time.RFC1123Z)
+
+	rel := string(generateRelease(metas))
+	var got string
+	for _, line := range strings.Split(rel, "\n") {
+		if strings.HasPrefix(line, "Date:") {
+			got = strings.TrimSpace(strings.TrimPrefix(line, "Date:"))
+			break
+		}
+	}
+	if got != want {
+		t.Errorf("Release Date: = %q, want %q (newest created_at)", got, want)
+	}
+}
+
+// TestDebReleaseDateEmptyRepoIsEpoch guards the fallback: an empty repo yields a
+// deterministic epoch Date: rather than wall clock.
+func TestDebReleaseDateEmptyRepoIsEpoch(t *testing.T) {
+	want := time.Unix(0, 0).UTC().Format(time.RFC1123Z)
+	rel := string(generateRelease(nil))
+	if !strings.Contains(rel, "Date: "+want+"\n") {
+		t.Errorf("empty-repo Release missing epoch Date: %q\n%s", want, rel)
+	}
+}
+
+// TestDebReleaseChecksumsMatchServedBytes is the exact apt invariant: the
+// sha256/size (and md5/size) advertised for Packages and Packages.gz in Release
+// equal the sha256/size of the actual bytes ServeLocalIndex serves. apt rejects
+// any mismatch.
+func TestDebReleaseChecksumsMatchServedBytes(t *testing.T) {
+	metas := debFixture()
+
+	packages := generatePackages(metas)
+	packagesGz := gzipBytes(packages)
+	rel := string(generateRelease(metas))
+
+	wantSHA := map[string]struct {
+		hash string
+		size int
+	}{
+		"Packages":    {sha256Hex(packages), len(packages)},
+		"Packages.gz": {sha256Hex(packagesGz), len(packagesGz)},
+	}
+	wantMD5 := map[string]struct {
+		hash string
+		size int
+	}{
+		"Packages":    {md5Hex(packages), len(packages)},
+		"Packages.gz": {md5Hex(packagesGz), len(packagesGz)},
+	}
+
+	sha := parseReleaseSection(rel, "SHA256:")
+	md5s := parseReleaseSection(rel, "MD5Sum:")
+
+	for name, w := range wantSHA {
+		got, ok := sha[name]
+		if !ok {
+			t.Fatalf("Release SHA256 section missing %q", name)
+		}
+		if got.hash != w.hash || got.size != w.size {
+			t.Errorf("Release SHA256 %s = (%s, %d), served bytes are (%s, %d)", name, got.hash, got.size, w.hash, w.size)
+		}
+	}
+	for name, w := range wantMD5 {
+		got, ok := md5s[name]
+		if !ok {
+			t.Fatalf("Release MD5Sum section missing %q", name)
+		}
+		if got.hash != w.hash || got.size != w.size {
+			t.Errorf("Release MD5Sum %s = (%s, %d), served bytes are (%s, %d)", name, got.hash, got.size, w.hash, w.size)
+		}
+	}
+}
+
+type releaseEntry struct {
+	hash string
+	size int
+}
+
+// parseReleaseSection reads the indented " <hash> <size> <name>" lines that
+// follow a "SHA256:" / "MD5Sum:" header until the next non-indented line.
+func parseReleaseSection(release, header string) map[string]releaseEntry {
+	out := map[string]releaseEntry{}
+	lines := strings.Split(release, "\n")
+	in := false
+	for _, line := range lines {
+		if line == header {
+			in = true
+			continue
+		}
+		if !in {
+			continue
+		}
+		if !strings.HasPrefix(line, " ") {
+			break
+		}
+		fields := strings.Fields(line)
+		if len(fields) != 3 {
+			continue
+		}
+		size, _ := strconv.Atoi(fields[1])
+		out[fields[2]] = releaseEntry{hash: fields[0], size: size}
+	}
+	return out
+}

internal/provider/deb/deb_test.go

@@ -0,0 +1,408 @@
+package deb
+
+import (
+	"archive/tar"
+	"bytes"
+	"compress/gzip"
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/klauspost/compress/zstd"
+	"github.com/ulikunitz/xz"
+
+	"git.unkin.net/unkin/artifactapi/internal/provider"
+	"git.unkin.net/unkin/artifactapi/internal/testsupport"
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+type fakeBlobReader struct{ data []byte }
+
+func (f fakeBlobReader) Download(_ context.Context, _ string) (io.ReadCloser, int64, error) {
+	return io.NopCloser(bytes.NewReader(f.data)), int64(len(f.data)), nil
+}
+
+type errBlobReader struct{}
+
+func (errBlobReader) Download(_ context.Context, _ string) (io.ReadCloser, int64, error) {
+	return nil, 0, io.ErrUnexpectedEOF
+}
+
+// fakeDebStore satisfies provider.MetadataStore (both insert methods) and
+// records the deb row that AfterUpload writes.
+type fakeDebStore struct{ inserted *provider.DebMetadata }
+
+func (f *fakeDebStore) InsertRPMMetadata(context.Context, *provider.RPMMetadata) error { return nil }
+func (f *fakeDebStore) InsertDebMetadata(_ context.Context, m *provider.DebMetadata) error {
+	f.inserted = m
+	return nil
+}
+
+type fakeDebReader struct{ metas []provider.DebMetadata }
+
+func (f fakeDebReader) ListDebMetadataEntries(context.Context, string) ([]provider.DebMetadata, error) {
+	return f.metas, nil
+}
+func (f fakeDebReader) ListFilesByPrefix(context.Context, string, string) ([]provider.FileEntry, error) {
+	return nil, nil
+}
+func (f fakeDebReader) ListPackages(context.Context, string) ([]string, error) { return nil, nil }
+
+type errDebReader struct{}
+
+func (errDebReader) ListDebMetadataEntries(context.Context, string) ([]provider.DebMetadata, error) {
+	return nil, io.ErrUnexpectedEOF
+}
+func (errDebReader) ListFilesByPrefix(context.Context, string, string) ([]provider.FileEntry, error) {
+	return nil, nil
+}
+func (errDebReader) ListPackages(context.Context, string) ([]string, error) { return nil, nil }
+
+func TestDebPureFuncs(t *testing.T) {
+	p := &Provider{}
+	if p.Type() != models.PackageDeb {
+		t.Errorf("type = %q", p.Type())
+	}
+	if out, _ := p.RewriteResponse(nil, models.Remote{}, "http://p"); out != nil {
+		t.Error("deb never rewrites")
+	}
+	if got := p.UpstreamURL(models.Remote{BaseURL: "https://mirror/"}, "/dists/bookworm/Release"); got != "https://mirror/dists/bookworm/Release" {
+		t.Errorf("upstream url %q", got)
+	}
+	h, _ := p.AuthHeaders(context.Background(), models.Remote{Username: "u", Password: "p"})
+	if h.Get("Authorization") == "" {
+		t.Error("auth header")
+	}
+}
+
+func TestDebClassify(t *testing.T) {
+	p := &Provider{}
+	tests := []struct {
+		path string
+		want provider.Mutability
+	}{
+		{"pool/foo_1.0_amd64.deb", provider.Immutable},
+		{"Packages", provider.Mutable},
+		{"Packages.gz", provider.Mutable},
+		{"Release", provider.Mutable},
+		{"InRelease", provider.Mutable},
+		{"Release.gpg", provider.Mutable},
+		{"dists/bookworm/main/binary-amd64/Packages", provider.Mutable},
+		{"dists/bookworm/Release", provider.Mutable},
+		{"dists/bookworm/main/by-hash/SHA256/abc", provider.Mutable},
+		{"dists/bookworm/main/Contents-amd64.gz", provider.Mutable},
+	}
+	for _, tt := range tests {
+		if got := p.Classify(tt.path); got != tt.want {
+			t.Errorf("Classify(%q) = %v, want %v", tt.path, got, tt.want)
+		}
+	}
+}
+
+func TestDebContentType(t *testing.T) {
+	p := &Provider{}
+	for path, want := range map[string]string{
+		"pool/foo_1.0_amd64.deb":              "application/vnd.debian.binary-package",
+		"dists/bookworm/main/bin/Packages.gz": "application/gzip",
+		"dists/bookworm/main/bin/Packages.xz": "application/x-xz",
+		"Packages":                            "text/plain",
+		"Release":                             "text/plain",
+		"InRelease":                           "text/plain",
+		"pool/other":                          "application/octet-stream",
+	} {
+		if got := p.ContentType(path); got != want {
+			t.Errorf("ContentType(%q) = %q, want %q", path, got, want)
+		}
+	}
+}
+
+func TestDebValidateUpload(t *testing.T) {
+	p := &Provider{}
+	sp, ct, err := p.ValidateUpload("dir/foo_1.0_amd64.deb")
+	if err != nil || sp != "pool/foo_1.0_amd64.deb" || ct != "application/vnd.debian.binary-package" {
+		t.Errorf("sp=%q ct=%q err=%v", sp, ct, err)
+	}
+	if _, _, err := p.ValidateUpload("foo.rpm"); err == nil {
+		t.Error("expected error for non-deb")
+	}
+	resp := p.UploadResponse("pool/foo_1.0_amd64.deb", "sha256:abc", 42)
+	if resp["filename"] != "foo_1.0_amd64.deb" || resp["content_hash"] != "sha256:abc" || resp["size_bytes"] != int64(42) {
+		t.Errorf("upload response %v", resp)
+	}
+}
+
+func TestDebAfterUpload(t *testing.T) {
+	data := testsupport.MinimalDeb("e2e-testpkg", "1.2.3", "amd64")
+	store := &fakeDebStore{}
+	(&Provider{}).AfterUpload(context.Background(), "myrepo", "pool/e2e-testpkg_1.2.3_amd64.deb",
+		"sha256:deadbeef", fakeBlobReader{data: data}, store)
+
+	m := store.inserted
+	if m == nil {
+		t.Fatal("no metadata inserted")
+	}
+	if m.Name != "e2e-testpkg" || m.Version != "1.2.3" || m.Architecture != "amd64" {
+		t.Errorf("unexpected metadata: %+v", m)
+	}
+	if m.Size != int64(len(data)) {
+		t.Errorf("Size = %d, want %d", m.Size, len(data))
+	}
+	if m.SHA256 != "deadbeef" {
+		t.Errorf("SHA256 = %q, want deadbeef", m.SHA256)
+	}
+	if m.MD5 == "" {
+		t.Error("MD5 not computed")
+	}
+	if !strings.Contains(m.Control, "Package: e2e-testpkg") {
+		t.Errorf("raw control not stored: %q", m.Control)
+	}
+	// The raw stanza is stored verbatim (no trailing newline) so Packages can
+	// reproduce it faithfully.
+	if strings.HasSuffix(m.Control, "\n") {
+		t.Error("control should be trimmed of trailing newline")
+	}
+}
+
+func TestDebAfterUploadErrors(t *testing.T) {
+	// Download failure: no insert, no panic.
+	store := &fakeDebStore{}
+	(&Provider{}).AfterUpload(context.Background(), "r", "p", "sha256:x", errBlobReader{}, store)
+	if store.inserted != nil {
+		t.Error("no metadata should be inserted on download error")
+	}
+	// Not a .deb (ar) archive.
+	store2 := &fakeDebStore{}
+	(&Provider{}).AfterUpload(context.Background(), "r", "p", "sha256:x", fakeBlobReader{data: []byte("not a deb")}, store2)
+	if store2.inserted != nil {
+		t.Error("no metadata should be inserted on parse error")
+	}
+}
+
+func TestDebControlDecompression(t *testing.T) {
+	// The control tarball may be gzip, xz, or zstd (goreleaser/nfpm emit gzip or
+	// xz); each must round-trip to the same control stanza.
+	for _, tc := range []struct {
+		name   string
+		member string
+		comp   func([]byte) []byte
+	}{
+		{"gzip", "control.tar.gz", gzipBytes},
+		{"xz", "control.tar.xz", xzBytes},
+		{"zstd", "control.tar.zst", zstdBytes},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			deb := buildDeb("pkg", "9.9", "arm64", tc.member, tc.comp)
+			control, err := extractControl(deb)
+			if err != nil {
+				t.Fatalf("extractControl: %v", err)
+			}
+			fields := parseControlFields(control)
+			if fields["Package"] != "pkg" || fields["Version"] != "9.9" || fields["Architecture"] != "arm64" {
+				t.Errorf("fields = %v", fields)
+			}
+		})
+	}
+}
+
+func TestDebParseControlContinuationLines(t *testing.T) {
+	control := "Package: p\nVersion: 1\n" +
+		"Description: short\n very long\n .\n more\n" +
+		"Architecture: all\n"
+	f := parseControlFields(control)
+	if f["Package"] != "p" || f["Version"] != "1" || f["Architecture"] != "all" {
+		t.Errorf("continuation lines corrupted parse: %v", f)
+	}
+	if f["Description"] != "short" {
+		t.Errorf("Description folded continuation into value: %q", f["Description"])
+	}
+}
+
+func TestDebServeLocalIndex(t *testing.T) {
+	p := &Provider{}
+	reader := fakeDebReader{metas: []provider.DebMetadata{
+		{Name: "aaa", Version: "1.0", Architecture: "amd64", FilePath: "pool/aaa_1.0_amd64.deb",
+			Control: "Package: aaa\nVersion: 1.0\nArchitecture: amd64", Size: 100, MD5: "md5aaa", SHA256: "sha256aaa"},
+		{Name: "bbb", Version: "2.0", Architecture: "arm64", FilePath: "pool/bbb_2.0_arm64.deb",
+			Control: "Package: bbb\nVersion: 2.0\nArchitecture: arm64", Size: 200, MD5: "md5bbb", SHA256: "sha256bbb"},
+	}}
+
+	serve := func(path string) *httptest.ResponseRecorder {
+		w := httptest.NewRecorder()
+		r := httptest.NewRequest(http.MethodGet, "/"+path, nil)
+		if !p.ServeLocalIndex(w, r, reader, "myrepo", path) {
+			t.Fatalf("ServeLocalIndex returned false for %q", path)
+		}
+		return w
+	}
+
+	// Packages lists both packages with their apt fields.
+	w := serve("Packages")
+	body := w.Body.String()
+	if w.Code != 200 {
+		t.Fatalf("Packages code %d", w.Code)
+	}
+	for _, want := range []string{
+		"Package: aaa", "Package: bbb",
+		"Filename: pool/aaa_1.0_amd64.deb", "Size: 100", "MD5sum: md5aaa", "SHA256: sha256aaa",
+		"Filename: pool/bbb_2.0_arm64.deb", "Size: 200",
+	} {
+		if !strings.Contains(body, want) {
+			t.Errorf("Packages missing %q:\n%s", want, body)
+		}
+	}
+	// Stanzas are blank-line separated.
+	if !strings.Contains(body, "SHA256: sha256aaa\n\n") {
+		t.Errorf("stanzas not blank-line separated:\n%s", body)
+	}
+
+	// Packages.gz decompresses to exactly the plain Packages bytes.
+	w = serve("Packages.gz")
+	if w.Code != 200 {
+		t.Fatalf("Packages.gz code %d", w.Code)
+	}
+	zr, err := gzip.NewReader(bytes.NewReader(w.Body.Bytes()))
+	if err != nil {
+		t.Fatalf("Packages.gz not gzip: %v", err)
+	}
+	plain, _ := io.ReadAll(zr)
+	if !bytes.Equal(plain, []byte(body)) {
+		t.Error("Packages.gz does not decompress to Packages")
+	}
+
+	// Release lists arches and both index files under MD5Sum/SHA256.
+	w = serve("Release")
+	rel := w.Body.String()
+	if w.Code != 200 {
+		t.Fatalf("Release code %d", w.Code)
+	}
+	for _, want := range []string{"Date:", "Architectures: amd64 arm64", "Acquire-By-Hash: no", "MD5Sum:", "SHA256:", " Packages\n", " Packages.gz\n"} {
+		if !strings.Contains(rel, want) {
+			t.Errorf("Release missing %q:\n%s", want, rel)
+		}
+	}
+
+	// Unsigned trust model: no InRelease / Release.gpg served here.
+	for _, path := range []string{"InRelease", "Release.gpg", "pool/aaa_1.0_amd64.deb"} {
+		w := httptest.NewRecorder()
+		r := httptest.NewRequest(http.MethodGet, "/"+path, nil)
+		if p.ServeLocalIndex(w, r, reader, "myrepo", path) {
+			t.Errorf("ServeLocalIndex should return false for %q", path)
+		}
+	}
+}
+
+// Real apt appends the flat-repo dist "./" verbatim, so it requests "./Packages"
+// / "./Release" (curl pre-normalizes /./ which masks this). The handler must
+// collapse the dot-segment and return the same bytes as the un-prefixed request.
+func TestDebServeLocalIndexAptDotSegment(t *testing.T) {
+	p := &Provider{}
+	reader := fakeDebReader{metas: []provider.DebMetadata{
+		{Name: "aaa", Version: "1.0", Architecture: "amd64", FilePath: "pool/aaa_1.0_amd64.deb",
+			Control: "Package: aaa\nVersion: 1.0\nArchitecture: amd64", Size: 100, MD5: "md5aaa", SHA256: "sha256aaa"},
+	}}
+
+	serve := func(path string) *httptest.ResponseRecorder {
+		w := httptest.NewRecorder()
+		r := httptest.NewRequest(http.MethodGet, "/"+path, nil)
+		if !p.ServeLocalIndex(w, r, reader, "myrepo", path) {
+			t.Fatalf("ServeLocalIndex returned false for %q", path)
+		}
+		return w
+	}
+
+	// Packages is deterministic: require exact byte identity.
+	if plain, dotted := serve("Packages"), serve("./Packages"); plain.Code != 200 || dotted.Code != 200 {
+		t.Fatalf("Packages: plain=%d dotted=%d, want 200/200", plain.Code, dotted.Code)
+	} else if !bytes.Equal(plain.Body.Bytes(), dotted.Body.Bytes()) {
+		t.Error("./Packages body differs from Packages body")
+	}
+
+	// Release carries a Date: header stamped from time.Now(); compare the rest.
+	plain, dotted := serve("Release"), serve("./Release")
+	if plain.Code != 200 || dotted.Code != 200 {
+		t.Fatalf("Release: plain=%d dotted=%d, want 200/200", plain.Code, dotted.Code)
+	}
+	if stripDate(plain.Body.String()) != stripDate(dotted.Body.String()) {
+		t.Error("./Release body differs from Release body (ignoring Date)")
+	}
+}
+
+func stripDate(s string) string {
+	var out []string
+	for _, line := range strings.Split(s, "\n") {
+		if strings.HasPrefix(line, "Date:") {
+			continue
+		}
+		out = append(out, line)
+	}
+	return strings.Join(out, "\n")
+}
+
+func TestDebServeMetadataError(t *testing.T) {
+	p := &Provider{}
+	for _, path := range []string{"Packages", "Packages.gz", "Release"} {
+		w := httptest.NewRecorder()
+		r := httptest.NewRequest(http.MethodGet, "/"+path, nil)
+		p.ServeLocalIndex(w, r, errDebReader{}, "repo", path)
+		if w.Code != 500 {
+			t.Errorf("%s with failing reader = %d, want 500", path, w.Code)
+		}
+	}
+}
+
+func TestDebGenerateLocalIndexUnsupported(t *testing.T) {
+	if _, err := (&Provider{}).GenerateLocalIndex(context.Background(), fakeDebReader{}, "r", "Packages"); err == nil {
+		t.Error("expected unsupported error")
+	}
+}
+
+// buildDeb assembles an ar .deb whose control member uses the given name and
+// compressor, so the decompression branches can be exercised directly.
+func buildDeb(name, version, arch, member string, comp func([]byte) []byte) []byte {
+	control := "Package: " + name + "\nVersion: " + version + "\nArchitecture: " + arch + "\n"
+	controlTar := comp(tarSingle("./control", []byte(control)))
+
+	var buf bytes.Buffer
+	buf.WriteString("!<arch>\n")
+	arWrite(&buf, "debian-binary", []byte("2.0\n"))
+	arWrite(&buf, member, controlTar)
+	arWrite(&buf, "data.tar.gz", gzipBytes(tarSingle("./x", []byte("x"))))
+	return buf.Bytes()
+}
+
+func tarSingle(name string, data []byte) []byte {
+	var buf bytes.Buffer
+	tw := tar.NewWriter(&buf)
+	tw.WriteHeader(&tar.Header{Name: name, Mode: 0o644, Size: int64(len(data)), Typeflag: tar.TypeReg})
+	tw.Write(data)
+	tw.Close()
+	return buf.Bytes()
+}
+
+func arWrite(buf *bytes.Buffer, name string, data []byte) {
+	fmt.Fprintf(buf, "%-16s%-12s%-6s%-6s%-8s%-10d`\n", name, "0", "0", "0", "100644", len(data))
+	buf.Write(data)
+	if len(data)%2 == 1 {
+		buf.WriteByte('\n')
+	}
+}
+
+func xzBytes(data []byte) []byte {
+	var buf bytes.Buffer
+	w, _ := xz.NewWriter(&buf)
+	w.Write(data)
+	w.Close()
+	return buf.Bytes()
+}
+
+func zstdBytes(data []byte) []byte {
+	var buf bytes.Buffer
+	w, _ := zstd.NewWriter(&buf)
+	w.Write(data)
+	w.Close()
+	return buf.Bytes()
+}

internal/provider/deb/github.go

@@ -0,0 +1,724 @@
+package deb
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/url"
+	"regexp"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	"golang.org/x/time/rate"
+
+	"git.unkin.net/unkin/artifactapi/internal/githubauth"
+	"git.unkin.net/unkin/artifactapi/internal/provider"
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+// gitHubProvider is the process-wide singleton for github_deb. The background
+// Syncer binds its shared rate limiter and work queue onto this instance so the
+// request path and the syncer drive the same derive machinery.
+var gitHubProvider = newGitHubProvider()
+
+func init() {
+	provider.Register(gitHubProvider)
+}
+
+// Tuning knobs for the no-precache control fetch. A .deb is an ar archive whose
+// control.tar member sits right after the tiny debian-binary member, so a small
+// front prefix reliably covers it.
+const (
+	defaultHeaderRangeInitial = 32 << 10 // 32 KiB — covers control.tar of almost every .deb
+	defaultHeaderRangeMax     = 16 << 20 // 16 MiB — give up past this and skip the asset
+	defaultReleasePageCap     = 10       // 100 releases/page * 10 pages
+
+	defaultScanTimeout  = 10 * time.Minute
+	defaultServeTimeout = 30 * time.Second
+	defaultColdWait     = 8 * time.Second
+)
+
+// GitHubProvider is a metadata-only remote: it scans a GitHub repo's releases
+// for .deb assets, derives per-asset control metadata via a ranged prefix fetch
+// (never downloading whole packages), synthesizes a flat apt repository from that
+// cached metadata, and redirects package downloads to a backend "releases_remote"
+// (the generic github.com remote) that serves the actual bytes.
+type GitHubProvider struct {
+	client *http.Client
+
+	headerInitial int64
+	headerMax     int64
+	pageCap       int
+	scanTimeout   time.Duration
+	serveTimeout  time.Duration
+	coldWait      time.Duration
+
+	limiter *rate.Limiter
+	syncer  *Syncer
+
+	serverCred githubauth.Credential
+
+	mu       sync.Mutex
+	scanning map[string]bool
+	lastScan map[string]time.Time
+}
+
+func newGitHubProvider() *GitHubProvider {
+	return &GitHubProvider{
+		client:        &http.Client{},
+		headerInitial: defaultHeaderRangeInitial,
+		headerMax:     defaultHeaderRangeMax,
+		pageCap:       defaultReleasePageCap,
+		scanTimeout:   defaultScanTimeout,
+		serveTimeout:  defaultServeTimeout,
+		coldWait:      defaultColdWait,
+		scanning:      map[string]bool{},
+		lastScan:      map[string]time.Time{},
+	}
+}
+
+func (p *GitHubProvider) limiterWait(ctx context.Context) error {
+	if p.limiter == nil {
+		return nil
+	}
+	return p.limiter.Wait(ctx)
+}
+
+func (p *GitHubProvider) Type() models.PackageType { return models.PackageGitHubDeb }
+
+func (p *GitHubProvider) Classify(path string) provider.Mutability {
+	switch path {
+	case "Packages", "Packages.gz", "Release", "InRelease", "Release.gpg":
+		return provider.Mutable
+	}
+	return provider.Immutable
+}
+
+func (p *GitHubProvider) ContentType(path string) string {
+	switch {
+	case strings.HasSuffix(path, ".deb"):
+		return "application/vnd.debian.binary-package"
+	case strings.HasSuffix(path, ".gz"):
+		return "application/gzip"
+	case path == "Packages" || path == "Release" || path == "InRelease":
+		return "text/plain"
+	}
+	return "application/octet-stream"
+}
+
+func (p *GitHubProvider) UpstreamURL(remote models.Remote, path string) string {
+	return strings.TrimRight(remote.BaseURL, "/") + "/" + strings.TrimLeft(path, "/")
+}
+
+func (p *GitHubProvider) RewriteResponse(_ []byte, _ models.Remote, _ string) ([]byte, error) {
+	return nil, nil
+}
+
+func (p *GitHubProvider) AuthHeaders(ctx context.Context, remote models.Remote) (http.Header, error) {
+	return p.githubHeaders(ctx, remote, false)
+}
+
+// ServeRemote answers a request against a github_deb remote. It refreshes the
+// derived metadata (bounded by mutable_ttl), serves a synthesized flat apt repo
+// (Packages/Packages.gz/Release), 404s the signed index variants (the repo is
+// consumed via [trusted=yes]), and 302-redirects .deb downloads to the backend
+// releases_remote. Returns false only for paths it does not own.
+func (p *GitHubProvider) ServeRemote(w http.ResponseWriter, r *http.Request, remote models.Remote, reqPath, proxyBaseURL string, store provider.RemoteMetadataStore) bool {
+	p.onRequest(remote, store)
+
+	// apt appends the flat-repo dist "./" verbatim, so it asks for "./Packages"
+	// etc.; collapse the dot-segment before matching the synthesized index.
+	path := normalizeIndexPath(reqPath)
+
+	switch path {
+	case "Packages", "Packages.gz", "Release":
+		p.serveIndex(w, r, remote, path, store)
+		return true
+	case "InRelease", "Release.gpg":
+		// Unsigned flat repo: apt consumes it with [trusted=yes]. Signal absence
+		// so apt falls back to the plain Release without waiting on a signature.
+		http.Error(w, "not found", http.StatusNotFound)
+		return true
+	}
+
+	if strings.HasSuffix(path, ".deb") {
+		if remote.ReleasesRemote == "" {
+			http.Error(w, "github_deb remote has no releases_remote configured for downloads", http.StatusInternalServerError)
+			return true
+		}
+		loc := strings.TrimRight(proxyBaseURL, "/") + "/api/v1/remote/" + remote.ReleasesRemote + "/" + strings.TrimLeft(path, "/")
+		http.Redirect(w, r, loc, http.StatusFound)
+		return true
+	}
+
+	return false
+}
+
+func (p *GitHubProvider) serveIndex(w http.ResponseWriter, r *http.Request, remote models.Remote, path string, store provider.RemoteMetadataStore) {
+	// Serve on a context detached from the inbound request so a client disconnect
+	// never cancels the metadata DB read and surfaces as a 500.
+	sctx, cancel := context.WithTimeout(context.WithoutCancel(r.Context()), p.serveTimeout)
+	defer cancel()
+
+	if p.syncer != nil && !p.ensurePrimed(sctx, remote, store) {
+		w.Header().Set("Retry-After", "5")
+		http.Error(w, "metadata is being prepared, retry shortly", http.StatusServiceUnavailable)
+		return
+	}
+
+	reader, ok := store.(provider.DebMetadataReader)
+	if !ok {
+		http.Error(w, "deb metadata not available", http.StatusInternalServerError)
+		return
+	}
+	metas, err := reader.ListDebMetadataEntries(sctx, remote.Name)
+	if err != nil {
+		if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
+			http.Error(w, "metadata read canceled", http.StatusServiceUnavailable)
+			return
+		}
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	switch path {
+	case "Packages":
+		w.Header().Set("Content-Type", "text/plain")
+		w.WriteHeader(http.StatusOK)
+		w.Write(generatePackages(metas))
+	case "Packages.gz":
+		w.Header().Set("Content-Type", "application/gzip")
+		w.WriteHeader(http.StatusOK)
+		w.Write(gzipBytes(generatePackages(metas)))
+	case "Release":
+		w.Header().Set("Content-Type", "text/plain")
+		w.WriteHeader(http.StatusOK)
+		w.Write(generateRelease(metas))
+	}
+}
+
+// onRequest keeps a remote's derived metadata fresh off the request path.
+func (p *GitHubProvider) onRequest(remote models.Remote, store provider.RemoteMetadataStore) {
+	if p.syncer != nil {
+		p.syncer.enqueue(remote, false)
+		return
+	}
+	p.refresh(remote, store)
+}
+
+// ensurePrimed returns true once the remote has at least one cached row. On an
+// empty cache it enqueues a prime and polls briefly for it to land.
+func (p *GitHubProvider) ensurePrimed(ctx context.Context, remote models.Remote, store provider.RemoteMetadataStore) bool {
+	if !p.cacheEmpty(ctx, store, remote.Name) {
+		return true
+	}
+	if p.syncer != nil {
+		p.syncer.enqueue(remote, true)
+	}
+
+	deadline := time.Now().Add(p.coldWait)
+	for time.Now().Before(deadline) {
+		select {
+		case <-ctx.Done():
+			return false
+		case <-time.After(400 * time.Millisecond):
+		}
+		if !p.cacheEmpty(ctx, store, remote.Name) {
+			return true
+		}
+	}
+	return false
+}
+
+func (p *GitHubProvider) cacheEmpty(ctx context.Context, store provider.RemoteMetadataStore, name string) bool {
+	reader, ok := store.(provider.DebMetadataReader)
+	if !ok {
+		return false
+	}
+	rows, err := reader.ListDebMetadataEntries(ctx, name)
+	if err != nil {
+		return false
+	}
+	return len(rows) == 0
+}
+
+// refresh brings the derived metadata up to date without coupling the scan to
+// the inbound request (legacy inline path used without a syncer / in unit tests).
+func (p *GitHubProvider) refresh(remote models.Remote, store provider.RemoteMetadataStore) {
+	ttl := time.Duration(remote.MutableTTL) * time.Second
+	if ttl <= 0 {
+		ttl = 5 * time.Minute
+	}
+
+	p.mu.Lock()
+	last, ok := p.lastScan[remote.Name]
+	fresh := ok && time.Since(last) < ttl
+	if fresh || p.scanning[remote.Name] {
+		p.mu.Unlock()
+		return
+	}
+	p.scanning[remote.Name] = true
+	p.mu.Unlock()
+
+	if p.cacheEmpty(context.Background(), store, remote.Name) {
+		p.runScan(remote, store)
+		return
+	}
+	go p.runScan(remote, store)
+}
+
+func (p *GitHubProvider) runScan(remote models.Remote, store provider.RemoteMetadataStore) {
+	defer func() {
+		p.mu.Lock()
+		delete(p.scanning, remote.Name)
+		p.mu.Unlock()
+	}()
+
+	ctx, cancel := context.WithTimeout(context.Background(), p.scanTimeout)
+	defer cancel()
+
+	if err := p.scan(ctx, remote, store); err != nil {
+		slog.Error("github_deb: release scan failed", "remote", remote.Name, "error", err)
+		return
+	}
+
+	p.mu.Lock()
+	p.lastScan[remote.Name] = time.Now()
+	p.mu.Unlock()
+}
+
+// scan runs a full unconditional derive. Retained for the legacy inline refresh
+// path and existing tests; the syncer uses scanWithState.
+func (p *GitHubProvider) scan(ctx context.Context, remote models.Remote, store provider.RemoteMetadataStore) error {
+	_, _, err := p.scanWithState(ctx, remote, store, "")
+	return err
+}
+
+// scanWithState derives metadata incrementally. It sends the prior releases-list
+// ETag as a conditional request: a 304 means nothing changed. On a 200 it diffs
+// the release assets against the cache, derives only new/changed assets, prunes
+// assets that disappeared, and returns the new ETag.
+func (p *GitHubProvider) scanWithState(ctx context.Context, remote models.Remote, store provider.RemoteMetadataStore, etag string) (newEtag string, changed bool, err error) {
+	releases, newEtag, notModified, err := p.fetchReleases(ctx, remote, etag)
+	if err != nil {
+		return etag, false, err
+	}
+	if notModified {
+		return etag, false, nil
+	}
+
+	reader, ok := store.(provider.DebMetadataReader)
+	if !ok {
+		return newEtag, false, errors.New("store does not support deb metadata reads")
+	}
+	existing, err := reader.ListDebMetadataEntries(ctx, remote.Name)
+	if err != nil {
+		return newEtag, false, err
+	}
+	existingByPath := make(map[string]provider.DebMetadata, len(existing))
+	for _, m := range existing {
+		existingByPath[m.FilePath] = m
+	}
+
+	allow, err := compilePatterns(remote.Patterns)
+	if err != nil {
+		return newEtag, false, err
+	}
+
+	seen := map[string]bool{}
+	for _, rel := range releases {
+		if rel.Draft {
+			continue
+		}
+		for _, asset := range rel.Assets {
+			if !strings.HasSuffix(strings.ToLower(asset.Name), ".deb") {
+				continue
+			}
+			if !matchesAny(allow, asset.Name) {
+				continue
+			}
+			fp := assetPath(asset)
+			if fp == "" {
+				continue
+			}
+			seen[fp] = true
+
+			if cur, ok := existingByPath[fp]; ok {
+				if asset.Digest == "" || cur.ContentHash == asset.Digest {
+					continue
+				}
+				_ = store.DeleteDebMetadata(ctx, remote.Name, fp)
+			}
+
+			meta, err := p.deriveAsset(ctx, remote, asset, fp)
+			if err != nil {
+				slog.Warn("github_deb: derive asset failed", "remote", remote.Name, "asset", asset.Name, "error", err)
+				continue
+			}
+			if err := store.InsertDebMetadata(ctx, meta); err != nil {
+				slog.Error("github_deb: insert metadata failed", "remote", remote.Name, "asset", asset.Name, "error", err)
+				continue
+			}
+			slog.Info("github_deb: derived asset", "remote", remote.Name, "name", meta.Name, "version", meta.Version, "arch", meta.Architecture)
+		}
+	}
+
+	for fp := range existingByPath {
+		if !seen[fp] {
+			_ = store.DeleteDebMetadata(ctx, remote.Name, fp)
+		}
+	}
+	return newEtag, true, nil
+}
+
+type ghRelease struct {
+	TagName string    `json:"tag_name"`
+	Draft   bool      `json:"draft"`
+	Assets  []ghAsset `json:"assets"`
+}
+
+type ghAsset struct {
+	Name               string `json:"name"`
+	Size               int64  `json:"size"`
+	BrowserDownloadURL string `json:"browser_download_url"`
+	Digest             string `json:"digest"`
+}
+
+// fetchReleases lists a repo's releases, sending the prior ETag as If-None-Match
+// on page 1 so an unchanged repo short-circuits to notModified. Every call waits
+// on the shared limiter first.
+func (p *GitHubProvider) fetchReleases(ctx context.Context, remote models.Remote, etag string) (all []ghRelease, newEtag string, notModified bool, err error) {
+	base := strings.TrimRight(remote.BaseURL, "/") + "/releases"
+	for page := 1; page <= p.pageCap; page++ {
+		u := fmt.Sprintf("%s?per_page=100&page=%d", base, page)
+		req, err := http.NewRequestWithContext(ctx, http.MethodGet, u, nil)
+		if err != nil {
+			return nil, "", false, err
+		}
+		hdr, err := p.githubHeaders(ctx, remote, true)
+		if err != nil {
+			return nil, "", false, err
+		}
+		copyHeaders(req, hdr)
+		if page == 1 && etag != "" {
+			req.Header.Set("If-None-Match", etag)
+		}
+
+		if err := p.limiterWait(ctx); err != nil {
+			return nil, "", false, err
+		}
+		resp, err := p.client.Do(req)
+		if err != nil {
+			return nil, "", false, err
+		}
+		if page == 1 && resp.StatusCode == http.StatusNotModified {
+			io.Copy(io.Discard, resp.Body)
+			resp.Body.Close()
+			return nil, etag, true, nil
+		}
+		body, err := io.ReadAll(resp.Body)
+		respEtag := resp.Header.Get("ETag")
+		resp.Body.Close()
+		if err != nil {
+			return nil, "", false, err
+		}
+		if resp.StatusCode != http.StatusOK {
+			return nil, "", false, fmt.Errorf("github releases API %s: status %d", u, resp.StatusCode)
+		}
+		if page == 1 {
+			newEtag = respEtag
+		}
+		var releases []ghRelease
+		if err := json.Unmarshal(body, &releases); err != nil {
+			return nil, "", false, fmt.Errorf("decode releases: %w", err)
+		}
+		if len(releases) == 0 {
+			break
+		}
+		all = append(all, releases...)
+		if len(releases) < 100 {
+			break
+		}
+	}
+	return all, newEtag, false, nil
+}
+
+func (p *GitHubProvider) deriveAsset(ctx context.Context, remote models.Remote, asset ghAsset, fp string) (*provider.DebMetadata, error) {
+	control, err := p.fetchControl(ctx, remote, asset.BrowserDownloadURL)
+	if err != nil {
+		return nil, err
+	}
+	fields := parseControlFields(control)
+
+	meta := &provider.DebMetadata{
+		RepoName:     remote.Name,
+		FilePath:     fp,
+		Name:         fields["Package"],
+		Version:      fields["Version"],
+		Architecture: fields["Architecture"],
+		Control:      strings.TrimRight(control, "\n"),
+		Size:         asset.Size,
+	}
+	if meta.Name == "" {
+		return nil, errors.New("control missing Package field")
+	}
+
+	// The Packages SHA256 must be the sha256 of the whole .deb. Prefer GitHub's
+	// asset digest so we never download the body; only when it is absent (or not
+	// sha256) do we stream the asset once. MD5sum is left unset — apt verifies the
+	// download against SHA256 alone under [trusted=yes].
+	if h, ok := sha256FromDigest(asset.Digest); ok {
+		meta.ContentHash = "sha256:" + h
+		meta.SHA256 = h
+	} else {
+		h, err := p.computeSHA256(ctx, remote, asset.BrowserDownloadURL)
+		if err != nil {
+			return nil, fmt.Errorf("compute sha256: %w", err)
+		}
+		meta.ContentHash = "sha256:" + h
+		meta.SHA256 = h
+	}
+
+	return meta, nil
+}
+
+// fetchControl pulls only the front of the .deb with a ranged GET and extracts
+// the control paragraph from it. control.tar sits right after the tiny
+// debian-binary member, so a small prefix suffices; a prefix that truncates the
+// control member doubles the range and retries.
+func (p *GitHubProvider) fetchControl(ctx context.Context, remote models.Remote, downloadURL string) (string, error) {
+	n := p.headerInitial
+	for {
+		body, full, err := p.rangeGet(ctx, remote, downloadURL, n)
+		if err != nil {
+			return "", err
+		}
+		control, complete, perr := controlFromPrefix(body)
+		if perr != nil {
+			return "", fmt.Errorf("parse deb control: %w", perr)
+		}
+		if complete {
+			return control, nil
+		}
+		if full || n >= p.headerMax {
+			return "", fmt.Errorf("control.tar not found within %d bytes of %s", n, downloadURL)
+		}
+		n *= 2
+		if n > p.headerMax {
+			n = p.headerMax
+		}
+	}
+}
+
+// controlFromPrefix parses the ar members present in a front prefix of a .deb.
+// It returns the ./control paragraph once control.tar.* is fully covered
+// (complete=true); a prefix too short to cover it returns complete=false so the
+// caller can widen the range. Later members (data.tar.*) are ignored.
+func controlFromPrefix(prefix []byte) (control string, complete bool, err error) {
+	const magic = "!<arch>\n"
+	if len(prefix) < len(magic) {
+		return "", false, nil
+	}
+	if string(prefix[:len(magic)]) != magic {
+		return "", false, errors.New("not an ar archive")
+	}
+	off := len(magic)
+	for {
+		if off+60 > len(prefix) {
+			return "", false, nil
+		}
+		hdr := prefix[off : off+60]
+		off += 60
+		name := strings.TrimSuffix(strings.TrimRight(string(hdr[0:16]), " "), "/")
+		size, err := strconv.ParseInt(strings.TrimSpace(string(hdr[48:58])), 10, 64)
+		if err != nil {
+			return "", false, fmt.Errorf("bad ar size for %q: %w", name, err)
+		}
+		if strings.HasPrefix(name, "control.tar") {
+			if off+int(size) > len(prefix) {
+				return "", false, nil
+			}
+			tarBytes, err := decompress(name, prefix[off:off+int(size)])
+			if err != nil {
+				return "", false, err
+			}
+			c, err := readControlParagraph(tarBytes)
+			if err != nil {
+				return "", false, err
+			}
+			return c, true, nil
+		}
+		if off+int(size) > len(prefix) {
+			return "", false, nil
+		}
+		off += int(size)
+		if size%2 == 1 {
+			off++
+		}
+	}
+}
+
+// rangeGet returns the first n bytes of downloadURL. full is true when the
+// response body was shorter than n (i.e. we already have the whole object).
+func (p *GitHubProvider) rangeGet(ctx context.Context, remote models.Remote, downloadURL string, n int64) ([]byte, bool, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, downloadURL, nil)
+	if err != nil {
+		return nil, false, err
+	}
+	hdr, err := p.githubHeaders(ctx, remote, false)
+	if err != nil {
+		return nil, false, err
+	}
+	copyHeaders(req, hdr)
+	req.Header.Set("Range", fmt.Sprintf("bytes=0-%d", n-1))
+
+	if err := p.limiterWait(ctx); err != nil {
+		return nil, false, err
+	}
+	resp, err := p.client.Do(req)
+	if err != nil {
+		return nil, false, err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK && resp.StatusCode != http.StatusPartialContent {
+		return nil, false, fmt.Errorf("range GET %s: status %d", downloadURL, resp.StatusCode)
+	}
+
+	body, err := io.ReadAll(io.LimitReader(resp.Body, n))
+	if err != nil {
+		return nil, false, err
+	}
+	full := int64(len(body)) < n
+	return body, full, nil
+}
+
+func (p *GitHubProvider) computeSHA256(ctx context.Context, remote models.Remote, downloadURL string) (string, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, downloadURL, nil)
+	if err != nil {
+		return "", err
+	}
+	hdr, err := p.githubHeaders(ctx, remote, false)
+	if err != nil {
+		return "", err
+	}
+	copyHeaders(req, hdr)
+
+	if err := p.limiterWait(ctx); err != nil {
+		return "", err
+	}
+	resp, err := p.client.Do(req)
+	if err != nil {
+		return "", err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		return "", fmt.Errorf("GET %s: status %d", downloadURL, resp.StatusCode)
+	}
+
+	h := sha256.New()
+	if _, err := io.Copy(h, resp.Body); err != nil {
+		return "", err
+	}
+	return hex.EncodeToString(h.Sum(nil)), nil
+}
+
+// assetPath is the package's location relative to github.com — the path the
+// backend releases_remote (base https://github.com) proxies. It doubles as the
+// deb_metadata key and the Filename field in the Packages index, so a .deb
+// download resolves back to this remote and redirects to the backend.
+func assetPath(asset ghAsset) string {
+	u, err := url.Parse(asset.BrowserDownloadURL)
+	if err != nil {
+		return ""
+	}
+	return strings.TrimPrefix(u.Path, "/")
+}
+
+func sha256FromDigest(digest string) (string, bool) {
+	if strings.HasPrefix(digest, "sha256:") {
+		return strings.TrimPrefix(digest, "sha256:"), true
+	}
+	return "", false
+}
+
+// githubHeaders builds the outbound headers for a GitHub request, attaching a
+// bearer credential when one is available. A per-remote credential wins; absent
+// that, the process-wide server credential is used; absent both, the request is
+// unauthenticated.
+func (p *GitHubProvider) githubHeaders(ctx context.Context, remote models.Remote, api bool) (http.Header, error) {
+	h := http.Header{}
+	if api {
+		h.Set("Accept", "application/vnd.github+json")
+		h.Set("X-GitHub-Api-Version", "2022-11-28")
+	}
+	tok, err := p.githubToken(ctx, remote)
+	if err != nil {
+		return nil, err
+	}
+	if tok != "" {
+		h.Set("Authorization", "Bearer "+tok)
+	}
+	return h, nil
+}
+
+// githubToken resolves the bearer token for a remote. Precedence: a per-remote
+// credential (password, then username) overrides the server credential.
+func (p *GitHubProvider) githubToken(ctx context.Context, remote models.Remote) (string, error) {
+	if remote.Password != "" {
+		return remote.Password, nil
+	}
+	if remote.Username != "" {
+		return remote.Username, nil
+	}
+	if c := p.serverCredential(); c != nil {
+		return c.Token(ctx)
+	}
+	return "", nil
+}
+
+func (p *GitHubProvider) serverCredential() githubauth.Credential {
+	if p.serverCred != nil {
+		return p.serverCred
+	}
+	return githubauth.Server()
+}
+
+func copyHeaders(req *http.Request, h http.Header) {
+	for k, vals := range h {
+		for _, v := range vals {
+			req.Header.Add(k, v)
+		}
+	}
+}
+
+func compilePatterns(patterns []string) ([]*regexp.Regexp, error) {
+	var out []*regexp.Regexp
+	for _, p := range patterns {
+		re, err := regexp.Compile(p)
+		if err != nil {
+			return nil, fmt.Errorf("invalid pattern %q: %w", p, err)
+		}
+		out = append(out, re)
+	}
+	return out, nil
+}
+
+func matchesAny(res []*regexp.Regexp, s string) bool {
+	if len(res) == 0 {
+		return true
+	}
+	for _, re := range res {
+		if re.MatchString(s) {
+			return true
+		}
+	}
+	return false
+}

internal/provider/deb/github_test.go

@@ -0,0 +1,462 @@
+package deb
+
+import (
+	"bytes"
+	"compress/gzip"
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strconv"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"git.unkin.net/unkin/artifactapi/internal/provider"
+	"git.unkin.net/unkin/artifactapi/internal/testsupport"
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+// fakeStore is an in-memory provider.RemoteMetadataStore + DebMetadataReader
+// keyed by file_path, mirroring the (repo_name, file_path) uniqueness of the
+// real deb_metadata table.
+type fakeStore struct {
+	mu   sync.Mutex
+	rows map[string]provider.DebMetadata
+}
+
+func newFakeStore() *fakeStore { return &fakeStore{rows: map[string]provider.DebMetadata{}} }
+
+func (f *fakeStore) InsertDebMetadata(_ context.Context, m *provider.DebMetadata) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if _, ok := f.rows[m.FilePath]; ok {
+		return nil // ON CONFLICT DO NOTHING
+	}
+	f.rows[m.FilePath] = *m
+	return nil
+}
+
+func (f *fakeStore) DeleteDebMetadata(_ context.Context, _, filePath string) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	delete(f.rows, filePath)
+	return nil
+}
+
+func (f *fakeStore) InsertRPMMetadata(context.Context, *provider.RPMMetadata) error { return nil }
+func (f *fakeStore) DeleteRPMMetadata(context.Context, string, string) error        { return nil }
+func (f *fakeStore) ListRPMMetadataEntries(context.Context, string) ([]provider.RPMMetadata, error) {
+	return nil, nil
+}
+
+func (f *fakeStore) ListDebMetadataEntries(ctx context.Context, _ string) ([]provider.DebMetadata, error) {
+	if err := ctx.Err(); err != nil {
+		return nil, err
+	}
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	out := make([]provider.DebMetadata, 0, len(f.rows))
+	for _, m := range f.rows {
+		out = append(out, m)
+	}
+	return out, nil
+}
+
+// githubFixture serves the releases API and the .deb asset downloads (with Range
+// support) for a set of packages. digest controls whether the asset carries a
+// sha256 digest (no-download path) or not (compute path).
+type githubFixture struct {
+	srv         *httptest.Server
+	debBytes    map[string][]byte
+	rangeHit    map[string]int
+	fullHit     map[string]int
+	etag        string
+	releasesHit int
+	notModHit   int
+	releaseAuth string
+	assetAuth   string
+	mu          sync.Mutex
+}
+
+func newGitHubFixture(t *testing.T, withDigest bool) *githubFixture {
+	t.Helper()
+	f := &githubFixture{
+		debBytes: map[string][]byte{},
+		rangeHit: map[string]int{},
+		fullHit:  map[string]int{},
+	}
+	f.debBytes["demo_1.2-3_amd64.deb"] = testsupport.MinimalDeb("demo", "1.2-3", "amd64")
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("/repos/acme/tools/releases", func(w http.ResponseWriter, r *http.Request) {
+		page := r.URL.Query().Get("page")
+		if page != "" && page != "1" {
+			w.Write([]byte("[]"))
+			return
+		}
+		f.mu.Lock()
+		f.releasesHit++
+		f.releaseAuth = r.Header.Get("Authorization")
+		etag := f.etag
+		if etag != "" && r.Header.Get("If-None-Match") == etag {
+			f.notModHit++
+			f.mu.Unlock()
+			w.WriteHeader(http.StatusNotModified)
+			return
+		}
+		f.mu.Unlock()
+		if etag != "" {
+			w.Header().Set("ETag", etag)
+		}
+		var assets []map[string]any
+		for name := range f.debBytes {
+			a := map[string]any{
+				"name":                 name,
+				"size":                 len(f.debBytes[name]),
+				"browser_download_url": f.srv.URL + "/acme/tools/releases/download/v1.2-3/" + name,
+			}
+			if withDigest {
+				sum := sha256.Sum256(f.debBytes[name])
+				a["digest"] = "sha256:" + hex.EncodeToString(sum[:])
+			}
+			assets = append(assets, a)
+		}
+		rel := []map[string]any{{"tag_name": "v1.2-3", "draft": false, "assets": assets}}
+		json.NewEncoder(w).Encode(rel)
+	})
+	mux.HandleFunc("/acme/tools/releases/download/", func(w http.ResponseWriter, r *http.Request) {
+		name := r.URL.Path[strings.LastIndex(r.URL.Path, "/")+1:]
+		body, ok := f.debBytes[name]
+		if !ok {
+			http.Error(w, "not found", 404)
+			return
+		}
+		rng := r.Header.Get("Range")
+		f.mu.Lock()
+		f.assetAuth = r.Header.Get("Authorization")
+		if rng != "" {
+			f.rangeHit[name]++
+		} else {
+			f.fullHit[name]++
+		}
+		f.mu.Unlock()
+
+		if rng == "" {
+			w.WriteHeader(200)
+			w.Write(body)
+			return
+		}
+		var end int
+		fmt.Sscanf(rng, "bytes=0-%d", &end)
+		if end >= len(body)-1 {
+			end = len(body) - 1
+		}
+		w.Header().Set("Content-Range", fmt.Sprintf("bytes 0-%d/%d", end, len(body)))
+		w.Header().Set("Content-Length", strconv.Itoa(end+1))
+		w.WriteHeader(http.StatusPartialContent)
+		w.Write(body[:end+1])
+	})
+	f.srv = httptest.NewServer(mux)
+	t.Cleanup(f.srv.Close)
+	return f
+}
+
+func (f *githubFixture) remote() models.Remote {
+	return models.Remote{
+		Name:           "acme-deb",
+		PackageType:    models.PackageGitHubDeb,
+		BaseURL:        f.srv.URL + "/repos/acme/tools",
+		ReleasesRemote: "github",
+		MutableTTL:     3600,
+	}
+}
+
+func newTestProvider() *GitHubProvider {
+	p := newGitHubProvider()
+	p.headerInitial = 32 // force the ranged-fetch retry loop against the tiny fixture
+	p.headerMax = 1 << 20
+	return p
+}
+
+const demoPath = "acme/tools/releases/download/v1.2-3/demo_1.2-3_amd64.deb"
+
+func TestGitHubScanDerivesControlFromPrefixAndDigest(t *testing.T) {
+	fx := newGitHubFixture(t, true)
+	p := newTestProvider()
+	store := newFakeStore()
+
+	if err := p.scan(context.Background(), fx.remote(), store); err != nil {
+		t.Fatalf("scan: %v", err)
+	}
+
+	metas, _ := store.ListDebMetadataEntries(context.Background(), "acme-deb")
+	if len(metas) != 1 {
+		t.Fatalf("want 1 metadata row, got %d", len(metas))
+	}
+	m := metas[0]
+	if m.Name != "demo" || m.Version != "1.2-3" || m.Architecture != "amd64" {
+		t.Fatalf("bad control fields: %+v", m)
+	}
+	if m.FilePath != demoPath {
+		t.Fatalf("FilePath = %q, want %q", m.FilePath, demoPath)
+	}
+	if int(m.Size) != len(fx.debBytes["demo_1.2-3_amd64.deb"]) {
+		t.Fatalf("Size = %d, want %d", m.Size, len(fx.debBytes["demo_1.2-3_amd64.deb"]))
+	}
+	sum := sha256.Sum256(fx.debBytes["demo_1.2-3_amd64.deb"])
+	if m.SHA256 != hex.EncodeToString(sum[:]) {
+		t.Fatalf("SHA256 = %q, want digest", m.SHA256)
+	}
+	if m.ContentHash != "sha256:"+hex.EncodeToString(sum[:]) {
+		t.Fatalf("ContentHash = %q", m.ContentHash)
+	}
+	if m.MD5 != "" {
+		t.Fatalf("MD5 should be unset for metadata-only derive, got %q", m.MD5)
+	}
+	if fx.fullHit["demo_1.2-3_amd64.deb"] != 0 {
+		t.Fatalf("expected no full download when digest present, got %d", fx.fullHit["demo_1.2-3_amd64.deb"])
+	}
+	if fx.rangeHit["demo_1.2-3_amd64.deb"] == 0 {
+		t.Fatalf("expected ranged control fetch")
+	}
+	if !strings.Contains(m.Control, "Package: demo") {
+		t.Fatalf("raw control not captured: %q", m.Control)
+	}
+}
+
+func TestGitHubChecksumComputedWhenDigestAbsent(t *testing.T) {
+	fx := newGitHubFixture(t, false)
+	p := newTestProvider()
+	store := newFakeStore()
+
+	if err := p.scan(context.Background(), fx.remote(), store); err != nil {
+		t.Fatalf("scan: %v", err)
+	}
+	metas, _ := store.ListDebMetadataEntries(context.Background(), "acme-deb")
+	if len(metas) != 1 {
+		t.Fatalf("want 1 row, got %d", len(metas))
+	}
+	sum := sha256.Sum256(fx.debBytes["demo_1.2-3_amd64.deb"])
+	if metas[0].SHA256 != hex.EncodeToString(sum[:]) {
+		t.Fatalf("computed checksum mismatch: %q", metas[0].SHA256)
+	}
+	if fx.fullHit["demo_1.2-3_amd64.deb"] == 0 {
+		t.Fatalf("expected a full download to compute sha256 when digest absent")
+	}
+}
+
+func TestGitHubServeRemoteIndexAndRedirect(t *testing.T) {
+	fx := newGitHubFixture(t, true)
+	p := newTestProvider()
+	store := newFakeStore()
+	remote := fx.remote()
+	const proxyBase = "https://artifactapi.example"
+
+	// Release is served and triggers the initial scan.
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/remote/acme-deb/Release", nil)
+	if !p.ServeRemote(rec, req, remote, "Release", proxyBase, store) {
+		t.Fatal("ServeRemote did not handle Release")
+	}
+	if rec.Code != 200 || !strings.Contains(rec.Body.String(), "Architectures:") {
+		t.Fatalf("Release bad: code=%d body=%s", rec.Code, rec.Body.String())
+	}
+	if !strings.Contains(rec.Body.String(), "amd64") {
+		t.Fatalf("Release missing arch: %s", rec.Body.String())
+	}
+
+	// Packages carries the package with a Filename that is the github-relative
+	// download path (so it resolves back to this remote and redirects).
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodGet, "/x", nil)
+	if !p.ServeRemote(rec, req, remote, "Packages", proxyBase, store) {
+		t.Fatal("ServeRemote did not handle Packages")
+	}
+	pkgs := rec.Body.String()
+	if !strings.Contains(pkgs, "Package: demo") {
+		t.Fatalf("Packages missing package: %s", pkgs)
+	}
+	if !strings.Contains(pkgs, "Filename: "+demoPath) {
+		t.Fatalf("Packages missing/incorrect Filename: %s", pkgs)
+	}
+	if !strings.Contains(pkgs, "SHA256: ") {
+		t.Fatalf("Packages missing SHA256: %s", pkgs)
+	}
+	if strings.Contains(pkgs, "MD5sum:") {
+		t.Fatalf("Packages should omit empty MD5sum: %s", pkgs)
+	}
+
+	// Packages.gz decompresses to the same content.
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodGet, "/x", nil)
+	if !p.ServeRemote(rec, req, remote, "Packages.gz", proxyBase, store) {
+		t.Fatal("ServeRemote did not handle Packages.gz")
+	}
+	gz, err := gzip.NewReader(rec.Body)
+	if err != nil {
+		t.Fatalf("gzip: %v", err)
+	}
+	unz, _ := io.ReadAll(gz)
+	if !strings.Contains(string(unz), "Package: demo") {
+		t.Fatalf("Packages.gz missing package: %s", unz)
+	}
+
+	// InRelease/Release.gpg 404 (unsigned, consumed via [trusted=yes]).
+	for _, sp := range []string{"InRelease", "Release.gpg"} {
+		rec = httptest.NewRecorder()
+		req = httptest.NewRequest(http.MethodGet, "/x", nil)
+		if !p.ServeRemote(rec, req, remote, sp, proxyBase, store) {
+			t.Fatalf("ServeRemote did not handle %s", sp)
+		}
+		if rec.Code != http.StatusNotFound {
+			t.Fatalf("%s want 404, got %d", sp, rec.Code)
+		}
+	}
+
+	// A .deb request redirects to the backend releases_remote.
+	rec = httptest.NewRecorder()
+	req = httptest.NewRequest(http.MethodGet, "/api/v1/remote/acme-deb/"+demoPath, nil)
+	if !p.ServeRemote(rec, req, remote, demoPath, proxyBase, store) {
+		t.Fatal("ServeRemote did not handle .deb")
+	}
+	if rec.Code != http.StatusFound {
+		t.Fatalf("want 302, got %d", rec.Code)
+	}
+	wantLoc := proxyBase + "/api/v1/remote/github/" + demoPath
+	if got := rec.Header().Get("Location"); got != wantLoc {
+		t.Fatalf("Location = %q, want %q", got, wantLoc)
+	}
+}
+
+// Real apt appends the flat-repo dist "./" verbatim, so the metadata-only remote
+// receives "./Packages" / "./Release"; ServeRemote must collapse the dot-segment
+// and synthesize the same index as the un-prefixed request.
+func TestGitHubServeRemoteAptDotSegment(t *testing.T) {
+	fx := newGitHubFixture(t, true)
+	p := newTestProvider()
+	store := newFakeStore()
+	remote := fx.remote()
+	const proxyBase = "https://artifactapi.example"
+
+	serve := func(path string) *httptest.ResponseRecorder {
+		rec := httptest.NewRecorder()
+		req := httptest.NewRequest(http.MethodGet, "/api/v1/remote/acme-deb/"+path, nil)
+		if !p.ServeRemote(rec, req, remote, path, proxyBase, store) {
+			t.Fatalf("ServeRemote did not handle %q", path)
+		}
+		return rec
+	}
+
+	// Packages is deterministic: byte-identical to the un-prefixed request.
+	plain, dotted := serve("Packages"), serve("./Packages")
+	if plain.Code != 200 || dotted.Code != 200 {
+		t.Fatalf("Packages: plain=%d dotted=%d, want 200/200", plain.Code, dotted.Code)
+	}
+	if !strings.Contains(dotted.Body.String(), "Package: demo") {
+		t.Fatalf("./Packages missing synthesized body: %s", dotted.Body.String())
+	}
+	if !bytes.Equal(plain.Body.Bytes(), dotted.Body.Bytes()) {
+		t.Error("./Packages body differs from Packages body")
+	}
+
+	// Release carries a time.Now() Date: header; compare the rest.
+	rPlain, rDotted := serve("Release"), serve("./Release")
+	if rPlain.Code != 200 || rDotted.Code != 200 {
+		t.Fatalf("Release: plain=%d dotted=%d, want 200/200", rPlain.Code, rDotted.Code)
+	}
+	if stripDate(rPlain.Body.String()) != stripDate(rDotted.Body.String()) {
+		t.Error("./Release body differs from Release body (ignoring Date)")
+	}
+}
+
+// A canceled inbound request must still serve the warm cache (detached context),
+// not turn the metadata read into a 500.
+func TestGitHubServeRemoteCanceledRequestServesCache(t *testing.T) {
+	fx := newGitHubFixture(t, true)
+	p := newTestProvider()
+	store := newFakeStore()
+	remote := fx.remote()
+
+	if err := p.scan(context.Background(), remote, store); err != nil {
+		t.Fatalf("warm scan: %v", err)
+	}
+	p.mu.Lock()
+	p.lastScan[remote.Name] = time.Now()
+	p.mu.Unlock()
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/remote/acme-deb/Packages", nil).WithContext(ctx)
+
+	if !p.ServeRemote(rec, req, remote, "Packages", "https://x", store) {
+		t.Fatal("ServeRemote did not handle Packages")
+	}
+	if rec.Code != http.StatusOK {
+		t.Fatalf("canceled request must serve cache, not error; got code=%d body=%s", rec.Code, rec.Body.String())
+	}
+	if !strings.Contains(rec.Body.String(), "Package: demo") {
+		t.Fatalf("expected Packages served from cache, got %s", rec.Body.String())
+	}
+}
+
+func TestGitHubServeRemoteRedirectRequiresReleasesRemote(t *testing.T) {
+	fx := newGitHubFixture(t, true)
+	p := newTestProvider()
+	store := newFakeStore()
+	remote := fx.remote()
+	remote.ReleasesRemote = ""
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/x", nil)
+	if !p.ServeRemote(rec, req, remote, demoPath, "https://x", store) {
+		t.Fatal("expected handled")
+	}
+	if rec.Code != http.StatusInternalServerError {
+		t.Fatalf("want 500 when releases_remote unset, got %d", rec.Code)
+	}
+}
+
+func TestGitHubScanPrunesRemovedAssets(t *testing.T) {
+	fx := newGitHubFixture(t, true)
+	p := newTestProvider()
+	store := newFakeStore()
+
+	if err := p.scan(context.Background(), fx.remote(), store); err != nil {
+		t.Fatalf("scan: %v", err)
+	}
+	if rows, _ := store.ListDebMetadataEntries(context.Background(), "acme-deb"); len(rows) != 1 {
+		t.Fatalf("want 1 row after first scan, got %d", len(rows))
+	}
+
+	delete(fx.debBytes, "demo_1.2-3_amd64.deb")
+	if err := p.scan(context.Background(), fx.remote(), store); err != nil {
+		t.Fatalf("rescan: %v", err)
+	}
+	if rows, _ := store.ListDebMetadataEntries(context.Background(), "acme-deb"); len(rows) != 0 {
+		t.Fatalf("want 0 rows after prune, got %d", len(rows))
+	}
+}
+
+func TestGitHubAssetPatternFilter(t *testing.T) {
+	fx := newGitHubFixture(t, true)
+	fx.debBytes["other_9_arm64.deb"] = testsupport.MinimalDeb("other", "9", "arm64")
+	p := newTestProvider()
+	store := newFakeStore()
+	remote := fx.remote()
+	remote.Patterns = []string{`^demo_.*_amd64\.deb$`}
+
+	if err := p.scan(context.Background(), remote, store); err != nil {
+		t.Fatalf("scan: %v", err)
+	}
+	rows, _ := store.ListDebMetadataEntries(context.Background(), "acme-deb")
+	if len(rows) != 1 || rows[0].Name != "demo" {
+		t.Fatalf("pattern filter failed, rows=%+v", rows)
+	}
+}

internal/provider/deb/syncer.go

@@ -0,0 +1,238 @@
+package deb
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"log/slog"
+	"os"
+	"sync"
+	"time"
+
+	"golang.org/x/time/rate"
+
+	"git.unkin.net/unkin/artifactapi/internal/provider"
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+const (
+	syncLeaseDuration    = 15 * time.Minute
+	defaultSyncFreshness = 5 * time.Minute
+	jobQueueDepth        = 256
+)
+
+// SyncStore is the persistence surface the deb syncer needs: the metadata cache
+// it primes plus the shared sync-state coordination (remote enumeration and the
+// per-remote lease). *database.DB satisfies it.
+type SyncStore interface {
+	provider.RemoteMetadataStore
+	ListGitHubDebRemotes(ctx context.Context) ([]models.Remote, error)
+	ClaimGitHubDebSyncLease(ctx context.Context, remoteName, owner string, freshness, lease time.Duration) (claimed bool, etag string, err error)
+	ReleaseGitHubDebSyncLease(ctx context.Context, remoteName, owner, etag string, syncedAt time.Time) error
+}
+
+// SyncConfig tunes the shared syncer. Zero values fall back to safe defaults.
+type SyncConfig struct {
+	RatePerSec   float64
+	Burst        int
+	Workers      int
+	PollInterval time.Duration
+}
+
+type syncJob struct {
+	remote models.Remote
+	prime  bool
+}
+
+// Syncer is the single per-process background worker that keeps every github_deb
+// remote's derived metadata fresh. It owns a deduped work queue, a pool of
+// workers, and a global token-bucket rate limiter shared across all remotes and
+// bound onto the github_deb provider. Periodic checks are gated by a shared DB
+// lease so, across replicas, only one performs each scan.
+type Syncer struct {
+	store   SyncStore
+	prov    *GitHubProvider
+	limiter *rate.Limiter
+	cfg     SyncConfig
+	owner   string
+
+	jobs   chan syncJob
+	mu     sync.Mutex
+	active map[string]bool
+}
+
+// NewSyncer builds the syncer bound to the process-wide github_deb provider
+// singleton. Call Run to start it.
+func NewSyncer(store SyncStore, cfg SyncConfig) *Syncer {
+	return newSyncer(store, gitHubProvider, cfg)
+}
+
+func newSyncer(store SyncStore, prov *GitHubProvider, cfg SyncConfig) *Syncer {
+	if cfg.RatePerSec <= 0 {
+		cfg.RatePerSec = 1
+	}
+	if cfg.Burst <= 0 {
+		cfg.Burst = 5
+	}
+	if cfg.Workers <= 0 {
+		cfg.Workers = 3
+	}
+	if cfg.PollInterval <= 0 {
+		cfg.PollInterval = 60 * time.Second
+	}
+
+	lim := rate.NewLimiter(rate.Limit(cfg.RatePerSec), cfg.Burst)
+	s := &Syncer{
+		store:   store,
+		prov:    prov,
+		limiter: lim,
+		cfg:     cfg,
+		owner:   leaseOwner(),
+		jobs:    make(chan syncJob, jobQueueDepth),
+		active:  map[string]bool{},
+	}
+	prov.limiter = lim
+	prov.syncer = s
+	return s
+}
+
+// Run starts the worker pool and the periodic scheduler and blocks until ctx is
+// canceled, at which point it drains in-flight scans and returns.
+func (s *Syncer) Run(ctx context.Context) {
+	slog.Info("github_deb syncer started",
+		"rate_per_sec", s.cfg.RatePerSec, "burst", s.cfg.Burst,
+		"workers", s.cfg.Workers, "poll_interval", s.cfg.PollInterval, "owner", s.owner)
+
+	var wg sync.WaitGroup
+	for i := 0; i < s.cfg.Workers; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			s.worker(ctx)
+		}()
+	}
+
+	ticker := time.NewTicker(s.cfg.PollInterval)
+	defer ticker.Stop()
+
+	s.schedule(ctx)
+	for {
+		select {
+		case <-ctx.Done():
+			wg.Wait()
+			slog.Info("github_deb syncer stopped")
+			return
+		case <-ticker.C:
+			s.schedule(ctx)
+		}
+	}
+}
+
+// schedule enqueues a periodic check for every github_deb remote. The DB lease
+// enforces the per-remote mutable_ttl cadence and cross-replica coordination.
+func (s *Syncer) schedule(ctx context.Context) {
+	remotes, err := s.store.ListGitHubDebRemotes(ctx)
+	if err != nil {
+		slog.Error("github_deb syncer: list remotes", "error", err)
+		return
+	}
+	for _, r := range remotes {
+		s.enqueue(r, false)
+	}
+}
+
+// EnqueuePrime queues an immediate background prime for a freshly created remote.
+func (s *Syncer) EnqueuePrime(remote models.Remote) {
+	if s == nil {
+		return
+	}
+	s.enqueue(remote, true)
+}
+
+// enqueue adds a job unless the remote is already queued or in-flight, coalescing
+// duplicate requests down to one scan. It never blocks.
+func (s *Syncer) enqueue(remote models.Remote, prime bool) {
+	s.mu.Lock()
+	if s.active[remote.Name] {
+		s.mu.Unlock()
+		return
+	}
+	s.active[remote.Name] = true
+	s.mu.Unlock()
+
+	select {
+	case s.jobs <- syncJob{remote: remote, prime: prime}:
+	default:
+		s.mu.Lock()
+		delete(s.active, remote.Name)
+		s.mu.Unlock()
+	}
+}
+
+func (s *Syncer) worker(ctx context.Context) {
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case job := <-s.jobs:
+			s.process(ctx, job)
+		}
+	}
+}
+
+// process claims the shared lease and, if won, runs an incremental scan. Losing
+// the claim (another replica scanning, or not yet due) is a no-op.
+func (s *Syncer) process(ctx context.Context, job syncJob) {
+	defer func() {
+		s.mu.Lock()
+		delete(s.active, job.remote.Name)
+		s.mu.Unlock()
+	}()
+
+	freshness := time.Duration(job.remote.MutableTTL) * time.Second
+	if freshness <= 0 {
+		freshness = defaultSyncFreshness
+	}
+	if job.prime {
+		freshness = 0
+	}
+
+	claimed, etag, err := s.store.ClaimGitHubDebSyncLease(ctx, job.remote.Name, s.owner, freshness, syncLeaseDuration)
+	if err != nil {
+		slog.Error("github_deb syncer: claim lease", "remote", job.remote.Name, "error", err)
+		return
+	}
+	if !claimed {
+		return
+	}
+
+	scanCtx, cancel := context.WithTimeout(ctx, s.prov.scanTimeout)
+	defer cancel()
+
+	newEtag, changed, scanErr := s.prov.scanWithState(scanCtx, job.remote, s.store, etag)
+	releaseEtag := etag
+	if scanErr == nil {
+		releaseEtag = newEtag
+	} else {
+		slog.Error("github_deb syncer: scan failed", "remote", job.remote.Name, "error", scanErr)
+	}
+
+	relCtx, relCancel := context.WithTimeout(context.WithoutCancel(ctx), 10*time.Second)
+	defer relCancel()
+	if err := s.store.ReleaseGitHubDebSyncLease(relCtx, job.remote.Name, s.owner, releaseEtag, time.Now()); err != nil {
+		slog.Warn("github_deb syncer: release lease", "remote", job.remote.Name, "error", err)
+	}
+
+	if scanErr == nil && changed {
+		slog.Info("github_deb syncer: refreshed", "remote", job.remote.Name, "prime", job.prime)
+	}
+}
+
+// leaseOwner is a per-replica identity for the lease: hostname plus a random
+// suffix so restarts and colocated replicas never collide.
+func leaseOwner() string {
+	host, _ := os.Hostname()
+	var b [6]byte
+	_, _ = rand.Read(b[:])
+	return host + "-" + hex.EncodeToString(b[:])
+}

internal/provider/deb/syncer_test.go

@@ -0,0 +1,300 @@
+package deb
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"testing"
+	"time"
+
+	"golang.org/x/time/rate"
+
+	"git.unkin.net/unkin/artifactapi/internal/provider"
+	"git.unkin.net/unkin/artifactapi/internal/testsupport"
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+// fakeSyncStore is an in-memory SyncStore: the metadata cache (via the embedded
+// fakeStore) plus the shared sync-state lease, whose claim mirrors the atomic
+// semantics of the real SQL (recency gate AND no live lease).
+type fakeSyncStore struct {
+	*fakeStore
+
+	mu         sync.Mutex
+	remotes    []models.Remote
+	leaseOwner map[string]string
+	leaseExp   map[string]time.Time
+	lastSynced map[string]time.Time
+	etags      map[string]string
+}
+
+func newFakeSyncStore() *fakeSyncStore {
+	return &fakeSyncStore{
+		fakeStore:  newFakeStore(),
+		leaseOwner: map[string]string{},
+		leaseExp:   map[string]time.Time{},
+		lastSynced: map[string]time.Time{},
+		etags:      map[string]string{},
+	}
+}
+
+func (f *fakeSyncStore) ListGitHubDebRemotes(_ context.Context) ([]models.Remote, error) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return append([]models.Remote(nil), f.remotes...), nil
+}
+
+func (f *fakeSyncStore) ClaimGitHubDebSyncLease(_ context.Context, name, owner string, freshness, lease time.Duration) (bool, string, error) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	now := time.Now()
+	ls, hasLS := f.lastSynced[name]
+	exp, hasExp := f.leaseExp[name]
+	freshOK := !hasLS || now.Sub(ls) >= freshness
+	leaseOK := !hasExp || exp.Before(now)
+	if freshOK && leaseOK {
+		f.leaseOwner[name] = owner
+		f.leaseExp[name] = now.Add(lease)
+		return true, f.etags[name], nil
+	}
+	return false, "", nil
+}
+
+func (f *fakeSyncStore) ReleaseGitHubDebSyncLease(_ context.Context, name, owner, etag string, syncedAt time.Time) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if f.leaseOwner[name] != owner {
+		return nil
+	}
+	f.lastSynced[name] = syncedAt
+	f.etags[name] = etag
+	delete(f.leaseOwner, name)
+	delete(f.leaseExp, name)
+	return nil
+}
+
+func testSyncConfig() SyncConfig {
+	return SyncConfig{RatePerSec: 1000, Burst: 100, Workers: 1, PollInterval: time.Hour}
+}
+
+// (a) A 304 conditional response must derive nothing: no asset fetches and
+// changed=false, so an unchanged repo is nearly free.
+func TestSyncerConditionalNotModifiedSkipsDerive(t *testing.T) {
+	fx := newGitHubFixture(t, true)
+	fx.etag = `"v1"`
+	p := newTestProvider()
+	store := newFakeStore()
+	remote := fx.remote()
+
+	etag1, changed, err := p.scanWithState(context.Background(), remote, store, "")
+	if err != nil {
+		t.Fatalf("first scan: %v", err)
+	}
+	if !changed || etag1 != `"v1"` {
+		t.Fatalf("first scan changed=%v etag=%q, want true and \"v1\"", changed, etag1)
+	}
+	priorRange := fx.rangeHit["demo_1.2-3_amd64.deb"]
+	if priorRange == 0 {
+		t.Fatal("first scan should have fetched the asset control")
+	}
+
+	etag2, changed2, err := p.scanWithState(context.Background(), remote, store, etag1)
+	if err != nil {
+		t.Fatalf("second scan: %v", err)
+	}
+	if changed2 {
+		t.Fatal("304 scan must report changed=false")
+	}
+	if etag2 != etag1 {
+		t.Fatalf("etag changed across 304: %q -> %q", etag1, etag2)
+	}
+	if fx.notModHit != 1 {
+		t.Fatalf("want exactly one 304 releases response, got %d", fx.notModHit)
+	}
+	if got := fx.rangeHit["demo_1.2-3_amd64.deb"]; got != priorRange {
+		t.Fatalf("304 scan re-fetched asset control: %d -> %d", priorRange, got)
+	}
+}
+
+// (b) On a real change, only the newly added asset is derived.
+func TestSyncerIncrementalDerivesOnlyNewAsset(t *testing.T) {
+	fx := newGitHubFixture(t, true)
+	fx.etag = `"v1"`
+	p := newTestProvider()
+	store := newFakeStore()
+	remote := fx.remote()
+
+	if _, _, err := p.scanWithState(context.Background(), remote, store, ""); err != nil {
+		t.Fatalf("first scan: %v", err)
+	}
+	demoRange := fx.rangeHit["demo_1.2-3_amd64.deb"]
+
+	fx.debBytes["other_9_arm64.deb"] = testsupport.MinimalDeb("other", "9", "arm64")
+	fx.etag = `"v2"`
+
+	if _, changed, err := p.scanWithState(context.Background(), remote, store, `"v1"`); err != nil || !changed {
+		t.Fatalf("second scan changed=%v err=%v", changed, err)
+	}
+
+	rows, _ := store.ListDebMetadataEntries(context.Background(), remote.Name)
+	if len(rows) != 2 {
+		t.Fatalf("want 2 cached rows after incremental derive, got %d", len(rows))
+	}
+	if got := fx.rangeHit["demo_1.2-3_amd64.deb"]; got != demoRange {
+		t.Fatalf("already-cached asset was re-fetched: %d -> %d", demoRange, got)
+	}
+	if fx.rangeHit["other_9_arm64.deb"] == 0 {
+		t.Fatal("newly added asset was not derived")
+	}
+}
+
+// (c) The shared limiter caps the request rate.
+func TestRateLimiterCapsRequestRate(t *testing.T) {
+	fx := newGitHubFixture(t, true)
+	p := newTestProvider()
+	p.limiter = rate.NewLimiter(rate.Every(120*time.Millisecond), 1)
+	remote := fx.remote()
+
+	start := time.Now()
+	for i := 0; i < 3; i++ {
+		if _, _, _, err := p.fetchReleases(context.Background(), remote, ""); err != nil {
+			t.Fatalf("fetchReleases %d: %v", i, err)
+		}
+	}
+	if elapsed := time.Since(start); elapsed < 200*time.Millisecond {
+		t.Fatalf("rate limiter did not throttle: 3 calls took %v, want >= 200ms", elapsed)
+	}
+}
+
+// (d) Concurrent enqueues for the same remote coalesce to a single queued job.
+func TestSyncerEnqueueDedup(t *testing.T) {
+	store := newFakeSyncStore()
+	p := newTestProvider()
+	s := newSyncer(store, p, testSyncConfig())
+	remote := models.Remote{Name: "acme-deb", PackageType: models.PackageGitHubDeb, MutableTTL: 3600}
+
+	var wg sync.WaitGroup
+	for i := 0; i < 10; i++ {
+		wg.Add(1)
+		go func() { defer wg.Done(); s.enqueue(remote, false) }()
+	}
+	wg.Wait()
+
+	if got := len(s.jobs); got != 1 {
+		t.Fatalf("want exactly 1 coalesced job, got %d", got)
+	}
+}
+
+// (e) Prime-on-create enqueues a prime job.
+func TestSyncerEnqueuePrime(t *testing.T) {
+	store := newFakeSyncStore()
+	p := newTestProvider()
+	s := newSyncer(store, p, testSyncConfig())
+	remote := models.Remote{Name: "acme-deb", PackageType: models.PackageGitHubDeb, MutableTTL: 3600}
+
+	s.EnqueuePrime(remote)
+	select {
+	case job := <-s.jobs:
+		if !job.prime || job.remote.Name != "acme-deb" {
+			t.Fatalf("bad prime job: %+v", job)
+		}
+	default:
+		t.Fatal("EnqueuePrime did not enqueue a job")
+	}
+}
+
+// (f) A held lease prevents a second replica from scanning.
+func TestSyncerLeasePreventsSecondReplica(t *testing.T) {
+	fx := newGitHubFixture(t, true)
+	fx.etag = `"v1"`
+	store := newFakeSyncStore()
+	p := newTestProvider()
+	s := newSyncer(store, p, testSyncConfig())
+	remote := fx.remote()
+
+	claimed, _, err := store.ClaimGitHubDebSyncLease(context.Background(), remote.Name, "replica-1", time.Duration(remote.MutableTTL)*time.Second, syncLeaseDuration)
+	if err != nil || !claimed {
+		t.Fatalf("replica-1 claim: claimed=%v err=%v", claimed, err)
+	}
+
+	s.process(context.Background(), syncJob{remote: remote})
+
+	if fx.releasesHit != 0 {
+		t.Fatalf("second replica scanned while lease held: %d releases calls", fx.releasesHit)
+	}
+	if rows, _ := store.ListDebMetadataEntries(context.Background(), remote.Name); len(rows) != 0 {
+		t.Fatalf("second replica derived metadata while lease held: %d rows", len(rows))
+	}
+}
+
+// With the syncer wired and the cache empty, an index request enqueues a prime
+// and returns a retryable 503 when it has not landed within the cold wait.
+func TestServeRemoteColdStartReturns503(t *testing.T) {
+	fx := newGitHubFixture(t, true)
+	store := newFakeSyncStore()
+	p := newTestProvider()
+	p.coldWait = 300 * time.Millisecond
+	_ = newSyncer(store, p, testSyncConfig()) // binds p.syncer, but no workers running
+	remote := fx.remote()
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/remote/acme-deb/Packages", nil)
+	if !p.ServeRemote(rec, req, remote, "Packages", "https://x", store) {
+		t.Fatal("ServeRemote did not handle Packages")
+	}
+	if rec.Code != http.StatusServiceUnavailable {
+		t.Fatalf("cold empty cache must return 503, got %d", rec.Code)
+	}
+	if rec.Header().Get("Retry-After") == "" {
+		t.Fatal("503 should carry Retry-After")
+	}
+	if got := len(p.syncer.jobs); got != 1 {
+		t.Fatalf("cold start did not enqueue a prime, jobs=%d", got)
+	}
+}
+
+// With the cache warm, the same request serves the index immediately (no 503).
+func TestServeRemoteWarmCacheServesImmediately(t *testing.T) {
+	fx := newGitHubFixture(t, true)
+	store := newFakeSyncStore()
+	p := newTestProvider()
+	_ = newSyncer(store, p, testSyncConfig())
+	remote := fx.remote()
+
+	if err := p.scan(context.Background(), remote, store); err != nil {
+		t.Fatalf("warm scan: %v", err)
+	}
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/remote/acme-deb/Packages", nil)
+	if !p.ServeRemote(rec, req, remote, "Packages", "https://x", store) {
+		t.Fatal("ServeRemote did not handle Packages")
+	}
+	if rec.Code != http.StatusOK {
+		t.Fatalf("warm cache must serve 200, got %d body=%s", rec.Code, rec.Body.String())
+	}
+}
+
+// A prime job (freshness 0) runs even right after a sync; a periodic job at the
+// same moment is gated by the recency window.
+func TestSyncerPrimeBypassesRecencyPeriodicDoesNot(t *testing.T) {
+	fx := newGitHubFixture(t, true)
+	fx.etag = `"v1"`
+	store := newFakeSyncStore()
+	p := newTestProvider()
+	s := newSyncer(store, p, testSyncConfig())
+	remote := fx.remote()
+
+	var _ provider.RemoteMetadataStore = store
+
+	s.process(context.Background(), syncJob{remote: remote, prime: true})
+	if rows, _ := store.ListDebMetadataEntries(context.Background(), remote.Name); len(rows) != 1 {
+		t.Fatalf("prime did not derive: %d rows", len(rows))
+	}
+	releasesAfterPrime := fx.releasesHit
+
+	s.process(context.Background(), syncJob{remote: remote, prime: false})
+	if fx.releasesHit != releasesAfterPrime {
+		t.Fatalf("periodic scan ran inside recency window: %d -> %d releases calls", releasesAfterPrime, fx.releasesHit)
+	}
+}

internal/provider/provider.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"io"
 	"net/http"
+	"time"
 
 	"git.unkin.net/unkin/artifactapi/pkg/models"
 )
@@ -61,6 +62,7 @@ type PostDeleteHook interface {
 
 type MetadataStore interface {
 	InsertRPMMetadata(ctx context.Context, meta *RPMMetadata) error
+	InsertDebMetadata(ctx context.Context, meta *DebMetadata) error
 }
 
 // RemoteServer lets a remote provider fully answer a request itself instead of
@@ -83,12 +85,85 @@ type RemoteMetadataStore interface {
 
 type MetadataDeleter interface {
 	DeleteRPMMetadata(ctx context.Context, repoName, filePath string) error
+	DeleteDebMetadata(ctx context.Context, repoName, filePath string) error
 }
 
 type RPMMetadataReader interface {
 	ListRPMMetadataEntries(ctx context.Context, repoName string) ([]RPMMetadata, error)
 }
 
+// DebMetadataReader is the read surface the deb LocalIndexer needs to
+// regenerate a flat apt repository (Packages/Release) from stored rows.
+// *database.DB satisfies it; ServeLocalIndex type-asserts the FileStore to it,
+// mirroring how the rpm provider reaches its RPMMetadataReader.
+type DebMetadataReader interface {
+	ListDebMetadataEntries(ctx context.Context, repoName string) ([]DebMetadata, error)
+}
+
+// DebMetadata is the derived per-package metadata for a Debian .deb, carrying
+// the full raw control stanza so the Packages index can be regenerated
+// faithfully alongside the computed size/md5/sha256 apt requires.
+type DebMetadata struct {
+	RepoName     string
+	FilePath     string
+	ContentHash  string
+	Name         string
+	Version      string
+	Architecture string
+	Control      string
+	Size         int64
+	MD5          string
+	SHA256       string
+	// CreatedAt is the persisted insert time; the Release Date: is derived from
+	// the newest value so the index is byte-identical across replicas and
+	// regenerations (issue #117) rather than stamped from wall clock.
+	CreatedAt time.Time
+}
+
+// AlpineMetadataStore / AlpineMetadataDeleter / AlpineMetadataReader are the
+// Alpine-specific persistence surfaces. They are kept separate from the shared
+// RPM/Deb metadata interfaces so the apk provider can type-assert the generic
+// MetadataStore/MetadataDeleter/FileStore it is handed without widening (and
+// thus perturbing the test doubles of) the rpm and deb providers. *database.DB
+// satisfies all three.
+type AlpineMetadataStore interface {
+	InsertAlpineMetadata(ctx context.Context, meta *AlpineMetadata) error
+}
+
+type AlpineMetadataDeleter interface {
+	DeleteAlpineMetadata(ctx context.Context, repoName, filePath string) error
+}
+
+type AlpineMetadataReader interface {
+	ListAlpineMetadataEntries(ctx context.Context, repoName string) ([]AlpineMetadata, error)
+}
+
+// AlpineMetadata is the derived per-package metadata for an Alpine .apk, holding
+// the fields an APKINDEX record carries plus the apk pull checksum (Q1…, the
+// sha1 of the control gzip stream) and the download/installed sizes.
+type AlpineMetadata struct {
+	RepoName         string
+	FilePath         string
+	ContentHash      string
+	Checksum         string   // C: "Q1" + base64(sha1(control gzip stream))
+	Name             string   // P:
+	Version          string   // V:
+	Arch             string   // A:
+	DownloadSize     int64    // S: on-disk .apk size
+	InstalledSize    int64    // I: unpacked size from .PKGINFO
+	Description      string   // T:
+	URL              string   // U:
+	License          string   // L:
+	Origin           string   // o:
+	Maintainer       string   // m:
+	BuildTime        int64    // t:
+	Commit           string   // c:
+	ProviderPriority string   // k:
+	Depends          []string // D:
+	Provides         []string // p:
+	InstallIf        []string // i:
+}
+
 type RPMMetadata struct {
 	RepoName      string
 	FilePath      string
@@ -115,6 +190,9 @@ type RPMMetadata struct {
 	Obsoletes     []RPMDep
 	Files         []RPMFile
 	Changelogs    []RPMChangelog
+	// CreatedAt is the persisted upload timestamp; used as a stable, replica-independent
+	// value for the repodata <time>/<revision> fields so generated indexes are deterministic.
+	CreatedAt time.Time
 }
 
 type RPMDep struct {

internal/provider/rpm/github_test.go

@@ -47,6 +47,9 @@ func (f *fakeStore) DeleteRPMMetadata(_ context.Context, _, filePath string) err
 	return nil
 }
 
+func (f *fakeStore) InsertDebMetadata(context.Context, *provider.DebMetadata) error { return nil }
+func (f *fakeStore) DeleteDebMetadata(context.Context, string, string) error        { return nil }
+
 func (f *fakeStore) ListRPMMetadataEntries(ctx context.Context, _ string) ([]provider.RPMMetadata, error) {
 	// Mirror pgx: a canceled/expired context fails the read. This is what
 	// poisons the repodata response if the read runs on the inbound request.

internal/provider/rpm/rpm.go

@@ -275,7 +275,7 @@ func (p *Provider) serveRepomd(w http.ResponseWriter, r *http.Request, reader pr
 	filelistsHash := sha256Hex(filelists)
 	otherHash := sha256Hex(other)
 
-	repomd := generateRepomd(primaryHash, len(primary), filelistsHash, len(filelists), otherHash, len(other))
+	repomd := generateRepomd(repomdRevision(metas), primaryHash, len(primary), filelistsHash, len(filelists), otherHash, len(other))
 
 	w.Header().Set("Content-Type", "application/xml")
 	w.WriteHeader(http.StatusOK)
@@ -315,8 +315,32 @@ func (p *Provider) serveOther(w http.ResponseWriter, r *http.Request, reader pro
 	w.Write(generateOtherXMLGZ(metas))
 }
 
-func generateRepomd(primaryHash string, primarySize int, filelistsHash string, filelistsSize int, otherHash string, otherSize int) []byte {
-	ts := fmt.Sprintf("%d", time.Now().Unix())
+// stableUnix maps a persisted timestamp to a fixed integer for repodata's
+// informational <time>/<timestamp> fields. Zero times (unset) collapse to 0 so
+// output stays byte-identical across replicas and requests. dnf does not
+// validate these values.
+func stableUnix(t time.Time) int64 {
+	if t.IsZero() {
+		return 0
+	}
+	return t.Unix()
+}
+
+// repomdRevision derives repomd.xml's <revision>/<timestamp> from persisted
+// state: the newest package upload time in the repo. It changes only when the
+// repo's package set does, and is identical on every replica reading the same
+// rows, so repomd.xml is byte-stable.
+func repomdRevision(metas []provider.RPMMetadata) string {
+	var max int64
+	for _, m := range metas {
+		if u := stableUnix(m.CreatedAt); u > max {
+			max = u
+		}
+	}
+	return fmt.Sprintf("%d", max)
+}
+
+func generateRepomd(ts string, primaryHash string, primarySize int, filelistsHash string, filelistsSize int, otherHash string, otherSize int) []byte {
 	var b bytes.Buffer
 	b.WriteString(xml.Header)
 	b.WriteString(`<repomd xmlns="http://linux.duke.edu/metadata/repo" xmlns:rpm="http://linux.duke.edu/metadata/rpm">` + "\n")
@@ -359,7 +383,7 @@ func generatePrimaryXMLGZ(metas []provider.RPMMetadata) []byte {
 		if m.URL != "" {
 			fmt.Fprintf(&xmlBuf, "  <url>%s</url>\n", xmlEscape(m.URL))
 		}
-		fmt.Fprintf(&xmlBuf, "  <time file=\"%d\" build=\"0\"/>\n", time.Now().Unix())
+		fmt.Fprintf(&xmlBuf, "  <time file=\"%d\" build=\"0\"/>\n", stableUnix(m.CreatedAt))
 		fmt.Fprintf(&xmlBuf, "  <size package=\"%d\" installed=\"%d\" archive=\"0\"/>\n", m.RPMSize, m.InstalledSize)
 		fmt.Fprintf(&xmlBuf, "  <location href=\"%s\"/>\n", xmlEscape(m.FilePath))
 		fmt.Fprintf(&xmlBuf, "  <format>\n")
@@ -484,6 +508,9 @@ func xmlEscape(s string) string {
 func gzipBytes(data []byte) []byte {
 	var buf bytes.Buffer
 	gz := gzip.NewWriter(&buf)
+	// Pin every header field so the compressed bytes (and their sha256) depend
+	// only on the payload, never on wall-clock time or the Go version's gzip defaults.
+	gz.Header = gzip.Header{OS: 255}
 	gz.Write(data)
 	gz.Close()
 	return buf.Bytes()

internal/provider/rpm/rpm_deterministic_test.go

@@ -0,0 +1,148 @@
+package rpm
+
+import (
+	"bytes"
+	"compress/gzip"
+	"encoding/xml"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"git.unkin.net/unkin/artifactapi/internal/provider"
+)
+
+func gunzip(t *testing.T, data []byte) string {
+	t.Helper()
+	zr, err := gzip.NewReader(bytes.NewReader(data))
+	if err != nil {
+		t.Fatalf("gzip reader: %v", err)
+	}
+	out, err := io.ReadAll(zr)
+	if err != nil {
+		t.Fatalf("gunzip: %v", err)
+	}
+	return string(out)
+}
+
+// sampleMetas returns a fixed two-package repo state whose upload timestamps are
+// pinned, so any nondeterminism must come from the generators themselves.
+func sampleMetas() []provider.RPMMetadata {
+	base := time.Date(2026, 1, 2, 3, 4, 5, 0, time.UTC)
+	return []provider.RPMMetadata{
+		{
+			Name: "alpha", Version: "1.0", Release: "1", Arch: "x86_64",
+			Summary: "a", Description: "d", ContentHash: "sha256:aaa",
+			FilePath: "Packages/alpha-1.0-1.x86_64.rpm", RPMSize: 10, InstalledSize: 20,
+			Provides:  []provider.RPMDep{{Name: "alpha"}},
+			Requires:  []provider.RPMDep{{Name: "libc", Flags: "GE", Version: "2.0"}},
+			CreatedAt: base,
+		},
+		{
+			Name: "beta", Version: "2.0", Release: "3", Arch: "noarch",
+			Summary: "b", Description: "d2", ContentHash: "sha256:bbb",
+			FilePath: "Packages/beta-2.0-3.noarch.rpm", RPMSize: 30, InstalledSize: 40,
+			CreatedAt: base.Add(time.Hour),
+		},
+	}
+}
+
+// TestRepodataGeneratorsDeterministic is the direct regression guard for #117:
+// generating each metadata document twice from identical state must yield
+// byte-identical output (hence an identical sha256). The old code embedded
+// time.Now() inside primary.xml.gz, so its bytes/hash drifted every second.
+func TestRepodataGeneratorsDeterministic(t *testing.T) {
+	metas := sampleMetas()
+	gens := map[string]func([]provider.RPMMetadata) []byte{
+		"primary":   generatePrimaryXMLGZ,
+		"filelists": generateFilelistsXMLGZ,
+		"other":     generateOtherXMLGZ,
+	}
+	for name, gen := range gens {
+		a := gen(metas)
+		b := gen(metas)
+		if sha256Hex(a) != sha256Hex(b) {
+			t.Errorf("%s: sha256 differs between two generations (nondeterministic): %s != %s",
+				name, sha256Hex(a), sha256Hex(b))
+		}
+	}
+
+	// repomd.xml itself must also be byte-stable across regenerations.
+	r1 := generateRepomd(repomdRevision(metas), sha256Hex(generatePrimaryXMLGZ(metas)), 1, "f", 2, "o", 3)
+	r2 := generateRepomd(repomdRevision(metas), sha256Hex(generatePrimaryXMLGZ(metas)), 1, "f", 2, "o", 3)
+	if string(r1) != string(r2) {
+		t.Error("repomd.xml differs between two generations")
+	}
+}
+
+// TestPrimaryTimeUsesPersistedCreatedAt proves the <time> element is a pure
+// function of the persisted upload timestamp, not the wall clock.
+func TestPrimaryTimeUsesPersistedCreatedAt(t *testing.T) {
+	metas := sampleMetas()
+	out := gunzip(t, generatePrimaryXMLGZ(metas))
+	if want := `<time file="1767323045" build="0"/>`; !strings.Contains(out, want) {
+		t.Errorf("primary.xml missing persisted <time> %q; got:\n%s", want, out)
+	}
+	// A zero (unset) CreatedAt collapses to a fixed 0, never a live clock value.
+	metas[0].CreatedAt = time.Time{}
+	out = gunzip(t, generatePrimaryXMLGZ(metas))
+	if !strings.Contains(out, `<time file="0" build="0"/>`) {
+		t.Errorf("zero CreatedAt should emit file=\"0\"; got:\n%s", out)
+	}
+}
+
+type repomdDoc struct {
+	Revision string `xml:"revision"`
+	Data     []struct {
+		Type     string `xml:"type,attr"`
+		Checksum struct {
+			Value string `xml:",chardata"`
+		} `xml:"checksum"`
+		Location struct {
+			Href string `xml:"href,attr"`
+		} `xml:"location"`
+	} `xml:"data"`
+}
+
+// TestRepomdHashMatchesServedBytes asserts the exact invariant #117 violated:
+// the sha256 advertised in repomd.xml equals the sha256 of the bytes the
+// content-addressed serve* handler returns for the same repo state.
+func TestRepomdHashMatchesServedBytes(t *testing.T) {
+	p := &Provider{}
+	reader := fakeRPMReader{metas: sampleMetas()}
+
+	serve := func(path string) *httptest.ResponseRecorder {
+		w := httptest.NewRecorder()
+		r := httptest.NewRequest(http.MethodGet, "/"+path, nil)
+		if !p.ServeLocalIndex(w, r, reader, "repo", path) {
+			t.Fatalf("ServeLocalIndex false for %q", path)
+		}
+		if w.Code != http.StatusOK {
+			t.Fatalf("%s: code %d", path, w.Code)
+		}
+		return w
+	}
+
+	var doc repomdDoc
+	if err := xml.Unmarshal(serve("repodata/repomd.xml").Body.Bytes(), &doc); err != nil {
+		t.Fatalf("parse repomd: %v", err)
+	}
+	if len(doc.Data) != 3 {
+		t.Fatalf("expected 3 <data> entries, got %d", len(doc.Data))
+	}
+
+	for _, d := range doc.Data {
+		// The advertised location is content-addressed: repodata/<sha256>-<type>.xml.gz.
+		body := serve("repodata/" + d.Location.Href[len("repodata/"):]).Body.Bytes()
+		got := sha256Hex(body)
+		if got != d.Checksum.Value {
+			t.Errorf("%s: repomd advertises %s but served bytes hash to %s (dnf would reject)",
+				d.Type, d.Checksum.Value, got)
+		}
+		if d.Location.Href != "repodata/"+d.Checksum.Value+"-"+d.Type+".xml.gz" {
+			t.Errorf("%s: location %q not addressed by its checksum %s", d.Type, d.Location.Href, d.Checksum.Value)
+		}
+	}
+}

internal/provider/rpm/rpm_meta_test.go

@@ -28,6 +28,8 @@ func (f *fakeMetaStore) InsertRPMMetadata(_ context.Context, m *provider.RPMMeta
 	return nil
 }
 
+func (f *fakeMetaStore) InsertDebMetadata(context.Context, *provider.DebMetadata) error { return nil }
+
 type fakeRPMReader struct{ metas []provider.RPMMetadata }
 
 func (f fakeRPMReader) ListRPMMetadataEntries(_ context.Context, _ string) ([]provider.RPMMetadata, error) {

internal/proxy/BENCHMARKS.md

@@ -0,0 +1,162 @@
+# Mirror-selection benchmarks
+
+These benchmarks (`selection_bench_test.go`) isolate the **mirror load-balancing
+selection overhead** — no network, no DB, no Redis. They build a zero-value
+`Engine` and call `baseURLAttemptOrder` / `beginAttempt` / `endAttempt`
+directly, the same way `leastconn_test.go` and `multibaseurl_test.go` do.
+
+Goal: quantify how much latency the load-balancing strategy (`round_robin` vs
+`least_conn`) adds versus a plain single-URL remote, and give a permanent
+regression guard.
+
+## Key context: selection is cache-miss-only
+
+`baseURLAttemptOrder` is called from exactly three places — `headUpstream`,
+`fetchFromUpstream`, and `checkUpstream` — all on the **upstream / cache-miss
+path**. A cache hit returns `Source: "cache"` from `GetArtifact` / `store.Stat`
+*before* any selection code runs. So none of the numbers below apply to the hot
+cache-hit path: cache hits pay **zero** selection cost regardless of strategy.
+The overhead here is paid once per upstream fetch, alongside a network round-trip
+measured in milliseconds.
+
+## How to run
+
+```
+go test -run=^$ -bench='BaseURLAttemptOrder|BeginEndAttempt' -benchmem \
+  -benchtime=1s -count=6 -cpu=8 ./internal/proxy/
+```
+
+## Results
+
+Machine: AMD Ryzen 7 4700U (8 threads), linux/amd64, go1.26.5.
+`-benchtime=1s -count=6`; figures below are the **median of 6 runs**.
+
+### Sequential (single-goroutine)
+
+| Benchmark                        | ns/op  | B/op | allocs/op |
+|----------------------------------|-------:|-----:|----------:|
+| BaseURLAttemptOrder_SingleURL    |   ~133 |   16 |         1 |
+| BaseURLAttemptOrder_RoundRobin/3 |   ~462 |  120 |         4 |
+| BaseURLAttemptOrder_RoundRobin/8 |   ~682 |  280 |         4 |
+| BaseURLAttemptOrder_LeastConn/3  |  ~2690 |  474 |        22 |
+| BaseURLAttemptOrder_LeastConn/8  | ~15200 | 2688 |       132 |
+| BeginEndAttempt (gauge inc/dec)  |   ~514 |  104 |         4 |
+
+### Parallel (`RunParallel`, GOMAXPROCS=8) — ns/op is wall-time across 8 cores
+
+| Benchmark                                 | ns/op | B/op | allocs/op |
+|-------------------------------------------|------:|-----:|----------:|
+| BaseURLAttemptOrder_RoundRobin_Parallel/3 | ~67.5 |  120 |         4 |
+| BaseURLAttemptOrder_RoundRobin_Parallel/8 |  ~130 |  280 |         4 |
+| BaseURLAttemptOrder_LeastConn_Parallel/3  |  ~292 |  474 |        22 |
+| BaseURLAttemptOrder_LeastConn_Parallel/8  | ~1673 | 2688 |       132 |
+| BeginEndAttempt_Parallel                  | ~71.5 |  104 |         4 |
+
+## Reading the numbers
+
+- **Single-URL is a near-no-op** (~133 ns, 1 alloc): the `len(urls) <= 1`
+  early return just returns the pool slice. Every non-mirrored remote takes this
+  path.
+- **round_robin is cheap**: ~462 ns for a 3-mirror pool, ~682 ns for 8. Cost is
+  one atomic cursor increment plus building the rotated `[]string`. Allocs are
+  constant at 4 (the ordered slice + its backing string headers), size grows
+  with pool length.
+- **least_conn is more expensive and scales super-linearly**: ~2.7 µs / 22
+  allocs at 3 mirrors, ~15 µs / 132 allocs at 8. The cost is the per-call
+  `sort.SliceStable`, whose comparator calls `inflightCounter` (a
+  `sync.Map.LoadOrStore` with a `remoteName\x00url` string-concat key plus a
+  speculative `new(atomic.Int64)`) O(n·log n) times. That is where the alloc
+  count and the time come from — not the sort itself. A future optimization
+  could snapshot each mirror's load once before sorting; out of scope for this
+  measurement PR.
+- **beginAttempt/endAttempt** (~514 ns seq, ~72 ns parallel) is one
+  `LoadOrStore` + two atomic adds; it only runs for least_conn multi-mirror
+  remotes, once per upstream attempt.
+- **Under concurrency the atomics/sync.Map do not collapse**: every parallel
+  variant reports *lower* ns/op than its sequential twin because work spreads
+  across 8 cores (RunParallel reports aggregate wall-time-per-op). No contention
+  cliff on the shared rrCounters cursor, the inflight `sync.Map`, or the
+  per-mirror `atomic.Int64` gauges.
+
+## Verdict
+
+At the per-request scale that matters (a cache-miss that is *already* doing a
+multi-millisecond network fetch), even the worst case here — least_conn across 8
+mirrors at ~15 µs — is <1% of a single upstream round-trip, and round_robin
+(~0.5 µs) is negligible. The strategy adds no meaningful latency, and it adds
+**exactly zero** to the cache-hit hot path because selection never runs there.
+
+## Raw output (all 6 runs)
+
+```
+goos: linux
+goarch: amd64
+pkg: git.unkin.net/unkin/artifactapi/internal/proxy
+cpu: AMD Ryzen 7 4700U with Radeon Graphics
+BenchmarkBaseURLAttemptOrder_SingleURL-8             	 8635875	       138.4 ns/op	      16 B/op	       1 allocs/op
+BenchmarkBaseURLAttemptOrder_SingleURL-8             	 9673108	       126.7 ns/op	      16 B/op	       1 allocs/op
+BenchmarkBaseURLAttemptOrder_SingleURL-8             	 8001002	       147.3 ns/op	      16 B/op	       1 allocs/op
+BenchmarkBaseURLAttemptOrder_SingleURL-8             	11303490	       135.0 ns/op	      16 B/op	       1 allocs/op
+BenchmarkBaseURLAttemptOrder_SingleURL-8             	10125138	       132.0 ns/op	      16 B/op	       1 allocs/op
+BenchmarkBaseURLAttemptOrder_SingleURL-8             	 8025687	       130.1 ns/op	      16 B/op	       1 allocs/op
+BenchmarkBaseURLAttemptOrder_RoundRobin/pool3-8      	 2706013	       453.2 ns/op	     120 B/op	       4 allocs/op
+BenchmarkBaseURLAttemptOrder_RoundRobin/pool3-8      	 2498718	       444.4 ns/op	     120 B/op	       4 allocs/op
+BenchmarkBaseURLAttemptOrder_RoundRobin/pool3-8      	 2605516	       471.6 ns/op	     120 B/op	       4 allocs/op
+BenchmarkBaseURLAttemptOrder_RoundRobin/pool3-8      	 2799928	       487.6 ns/op	     120 B/op	       4 allocs/op
+BenchmarkBaseURLAttemptOrder_RoundRobin/pool3-8      	 2463375	       418.6 ns/op	     120 B/op	       4 allocs/op
+BenchmarkBaseURLAttemptOrder_RoundRobin/pool3-8      	 2472265	       474.3 ns/op	     120 B/op	       4 allocs/op
+BenchmarkBaseURLAttemptOrder_RoundRobin/pool8-8      	 1741789	       689.4 ns/op	     280 B/op	       4 allocs/op
+BenchmarkBaseURLAttemptOrder_RoundRobin/pool8-8      	 1775467	       602.1 ns/op	     280 B/op	       4 allocs/op
+BenchmarkBaseURLAttemptOrder_RoundRobin/pool8-8      	 1829398	       688.4 ns/op	     280 B/op	       4 allocs/op
+BenchmarkBaseURLAttemptOrder_RoundRobin/pool8-8      	 1781149	       679.3 ns/op	     280 B/op	       4 allocs/op
+BenchmarkBaseURLAttemptOrder_RoundRobin/pool8-8      	 1795680	       599.4 ns/op	     280 B/op	       4 allocs/op
+BenchmarkBaseURLAttemptOrder_RoundRobin/pool8-8      	 1739122	       684.5 ns/op	     280 B/op	       4 allocs/op
+BenchmarkBaseURLAttemptOrder_LeastConn/pool3-8       	  424184	      2675 ns/op	     474 B/op	      22 allocs/op
+BenchmarkBaseURLAttemptOrder_LeastConn/pool3-8       	  426796	      2498 ns/op	     474 B/op	      22 allocs/op
+BenchmarkBaseURLAttemptOrder_LeastConn/pool3-8       	  427116	      2716 ns/op	     474 B/op	      22 allocs/op
+BenchmarkBaseURLAttemptOrder_LeastConn/pool3-8       	  430540	      2681 ns/op	     474 B/op	      22 allocs/op
+BenchmarkBaseURLAttemptOrder_LeastConn/pool3-8       	  418156	      2700 ns/op	     474 B/op	      22 allocs/op
+BenchmarkBaseURLAttemptOrder_LeastConn/pool3-8       	  423009	      2711 ns/op	     474 B/op	      22 allocs/op
+BenchmarkBaseURLAttemptOrder_LeastConn/pool8-8       	  163642	     14007 ns/op	    2688 B/op	     132 allocs/op
+BenchmarkBaseURLAttemptOrder_LeastConn/pool8-8       	   78501	     15457 ns/op	    2688 B/op	     131 allocs/op
+BenchmarkBaseURLAttemptOrder_LeastConn/pool8-8       	   76380	     14928 ns/op	    2688 B/op	     132 allocs/op
+BenchmarkBaseURLAttemptOrder_LeastConn/pool8-8       	  183634	     16091 ns/op	    2688 B/op	     132 allocs/op
+BenchmarkBaseURLAttemptOrder_LeastConn/pool8-8       	   73809	     15561 ns/op	    2688 B/op	     132 allocs/op
+BenchmarkBaseURLAttemptOrder_LeastConn/pool8-8       	   74546	     13962 ns/op	    2688 B/op	     132 allocs/op
+BenchmarkBeginEndAttempt-8                           	 2350348	       519.7 ns/op	     104 B/op	       4 allocs/op
+BenchmarkBeginEndAttempt-8                           	 2321659	       514.0 ns/op	     104 B/op	       4 allocs/op
+BenchmarkBeginEndAttempt-8                           	 2284635	       438.0 ns/op	     104 B/op	       4 allocs/op
+BenchmarkBeginEndAttempt-8                           	 2287051	       513.9 ns/op	     104 B/op	       4 allocs/op
+BenchmarkBeginEndAttempt-8                           	 2286481	       520.3 ns/op	     104 B/op	       4 allocs/op
+BenchmarkBeginEndAttempt-8                           	 2837775	       512.9 ns/op	     104 B/op	       4 allocs/op
+BenchmarkBaseURLAttemptOrder_RoundRobin_Parallel/pool3-8         	16052568	        67.78 ns/op	     120 B/op	       4 allocs/op
+BenchmarkBaseURLAttemptOrder_RoundRobin_Parallel/pool3-8         	17452791	        66.07 ns/op	     120 B/op	       4 allocs/op
+BenchmarkBaseURLAttemptOrder_RoundRobin_Parallel/pool3-8         	17549858	        69.25 ns/op	     120 B/op	       4 allocs/op
+BenchmarkBaseURLAttemptOrder_RoundRobin_Parallel/pool3-8         	18845167	        64.55 ns/op	     120 B/op	       4 allocs/op
+BenchmarkBaseURLAttemptOrder_RoundRobin_Parallel/pool3-8         	16285608	        69.81 ns/op	     120 B/op	       4 allocs/op
+BenchmarkBaseURLAttemptOrder_RoundRobin_Parallel/pool3-8         	17382639	        67.12 ns/op	     120 B/op	       4 allocs/op
+BenchmarkBaseURLAttemptOrder_RoundRobin_Parallel/pool8-8         	 9734368	       120.6 ns/op	     280 B/op	       4 allocs/op
+BenchmarkBaseURLAttemptOrder_RoundRobin_Parallel/pool8-8         	10154736	       133.3 ns/op	     280 B/op	       4 allocs/op
+BenchmarkBaseURLAttemptOrder_RoundRobin_Parallel/pool8-8         	10061422	       131.8 ns/op	     280 B/op	       4 allocs/op
+BenchmarkBaseURLAttemptOrder_RoundRobin_Parallel/pool8-8         	10212364	       127.4 ns/op	     280 B/op	       4 allocs/op
+BenchmarkBaseURLAttemptOrder_RoundRobin_Parallel/pool8-8         	10259030	       132.5 ns/op	     280 B/op	       4 allocs/op
+BenchmarkBaseURLAttemptOrder_RoundRobin_Parallel/pool8-8         	10069576	       122.4 ns/op	     280 B/op	       4 allocs/op
+BenchmarkBaseURLAttemptOrder_LeastConn_Parallel/pool3-8          	 4288112	       292.7 ns/op	     474 B/op	      22 allocs/op
+BenchmarkBaseURLAttemptOrder_LeastConn_Parallel/pool3-8          	 4009249	       295.9 ns/op	     474 B/op	      22 allocs/op
+BenchmarkBaseURLAttemptOrder_LeastConn_Parallel/pool3-8          	 4176378	       291.3 ns/op	     474 B/op	      22 allocs/op
+BenchmarkBaseURLAttemptOrder_LeastConn_Parallel/pool3-8          	 4104871	       289.9 ns/op	     474 B/op	      22 allocs/op
+BenchmarkBaseURLAttemptOrder_LeastConn_Parallel/pool3-8          	 4245262	       296.4 ns/op	     474 B/op	      22 allocs/op
+BenchmarkBaseURLAttemptOrder_LeastConn_Parallel/pool3-8          	 4079778	       290.3 ns/op	     474 B/op	      22 allocs/op
+BenchmarkBaseURLAttemptOrder_LeastConn_Parallel/pool8-8          	  748200	      1636 ns/op	    2688 B/op	     132 allocs/op
+BenchmarkBaseURLAttemptOrder_LeastConn_Parallel/pool8-8          	  763029	      1653 ns/op	    2688 B/op	     132 allocs/op
+BenchmarkBaseURLAttemptOrder_LeastConn_Parallel/pool8-8          	  663717	      1772 ns/op	    2688 B/op	     132 allocs/op
+BenchmarkBaseURLAttemptOrder_LeastConn_Parallel/pool8-8          	  739677	      1676 ns/op	    2688 B/op	     132 allocs/op
+BenchmarkBaseURLAttemptOrder_LeastConn_Parallel/pool8-8          	  763148	      1669 ns/op	    2688 B/op	     132 allocs/op
+BenchmarkBaseURLAttemptOrder_LeastConn_Parallel/pool8-8          	  610597	      1684 ns/op	    2688 B/op	     132 allocs/op
+BenchmarkBeginEndAttempt_Parallel-8                              	17266058	        69.46 ns/op	     104 B/op	       4 allocs/op
+BenchmarkBeginEndAttempt_Parallel-8                              	17151303	        72.05 ns/op	     104 B/op	       4 allocs/op
+BenchmarkBeginEndAttempt_Parallel-8                              	16919542	        74.17 ns/op	     104 B/op	       4 allocs/op
+BenchmarkBeginEndAttempt_Parallel-8                              	16948015	        72.49 ns/op	     104 B/op	       4 allocs/op
+BenchmarkBeginEndAttempt_Parallel-8                              	16918693	        69.52 ns/op	     104 B/op	       4 allocs/op
+BenchmarkBeginEndAttempt_Parallel-8                              	17376012	        70.99 ns/op	     104 B/op	       4 allocs/op
+```

internal/proxy/engine.go

@@ -10,7 +10,10 @@ import (
 	"io"
 	"log/slog"
 	"net/http"
+	"sort"
 	"strings"
+	"sync"
+	"sync/atomic"
 	"time"
 
 	"git.unkin.net/unkin/artifactapi/internal/cache"
@@ -35,6 +38,15 @@ type Engine struct {
 	cas       *storage.CAS
 	circuit   *CircuitBreaker
 	accessLog chan database.AccessLogEntry
+	// rrCounters holds a per-remote round-robin cursor (remoteName ->
+	// *atomic.Uint64) used to rotate the starting mirror across upstream base
+	// URLs. Distribution is per-replica and approximate, which is fine.
+	rrCounters sync.Map
+	// inflight holds a per-remote, per-upstream-URL in-flight request gauge
+	// (key "remoteName\x00baseURL" -> *atomic.Int64) used by the least_conn
+	// mirror strategy to prefer the mirror currently handling the fewest
+	// requests. Per-replica and approximate, which is fine.
+	inflight sync.Map
 }
 
 func NewEngine(db *database.DB, c *cache.Redis, s *storage.S3) *Engine {
@@ -222,7 +234,32 @@ func (e *Engine) Head(ctx context.Context, remote models.Remote, path string, pr
 	return e.headUpstream(ctx, remote, path, prov)
 }
 
+// headUpstream issues an upstream HEAD, load-balancing across the remote's base
+// URLs and failing over to the next mirror on a network error or 5xx.
 func (e *Engine) headUpstream(ctx context.Context, remote models.Remote, path string, prov provider.Provider) (*HeadResult, error) {
+	order := e.baseURLAttemptOrder(remote)
+	if len(order) == 0 {
+		return nil, &ProxyError{Status: http.StatusBadGateway, Message: "no upstream base_url configured"}
+	}
+	var lastErr error
+	for i, url := range order {
+		ctr := e.beginAttempt(remote, url)
+		result, err := e.headUpstreamOnce(ctx, withBaseURL(remote, url), path, prov)
+		endAttempt(ctr)
+		if err == nil {
+			return result, nil
+		}
+		lastErr = err
+		if i < len(order)-1 && shouldFailover(err) {
+			slog.Warn("upstream HEAD failed, failing over", "remote", remote.Name, "base_url", url, "error", err)
+			continue
+		}
+		return nil, err
+	}
+	return nil, lastErr
+}
+
+func (e *Engine) headUpstreamOnce(ctx context.Context, remote models.Remote, path string, prov provider.Provider) (*HeadResult, error) {
 	url := prov.UpstreamURL(remote, path)
 
 	authHeaders, err := prov.AuthHeaders(ctx, remote)
@@ -277,7 +314,33 @@ func (e *Engine) headUpstream(ctx context.Context, remote models.Remote, path st
 	return &HeadResult{ContentType: contentType, Size: resp.ContentLength, Source: "remote"}, nil
 }
 
+// fetchFromUpstream fetches an artifact from upstream, load-balancing across the
+// remote's base URLs and failing over to the next mirror on a network error or
+// 5xx before returning an error.
 func (e *Engine) fetchFromUpstream(ctx context.Context, remote models.Remote, path string, prov provider.Provider, class Classification, ttl time.Duration, clientHeaders http.Header) (*FetchResult, error) {
+	order := e.baseURLAttemptOrder(remote)
+	if len(order) == 0 {
+		return nil, &ProxyError{Status: http.StatusBadGateway, Message: "no upstream base_url configured"}
+	}
+	var lastErr error
+	for i, url := range order {
+		ctr := e.beginAttempt(remote, url)
+		result, err := e.fetchFromUpstreamOnce(ctx, withBaseURL(remote, url), path, prov, class, ttl, clientHeaders)
+		endAttempt(ctr)
+		if err == nil {
+			return result, nil
+		}
+		lastErr = err
+		if i < len(order)-1 && shouldFailover(err) {
+			slog.Warn("upstream fetch failed, failing over", "remote", remote.Name, "base_url", url, "error", err)
+			continue
+		}
+		return nil, err
+	}
+	return nil, lastErr
+}
+
+func (e *Engine) fetchFromUpstreamOnce(ctx context.Context, remote models.Remote, path string, prov provider.Provider, class Classification, ttl time.Duration, clientHeaders http.Header) (*FetchResult, error) {
 	url := prov.UpstreamURL(remote, path)
 
 	authHeaders, err := prov.AuthHeaders(ctx, remote)
@@ -454,7 +517,33 @@ func (e *Engine) serveFromStore(ctx context.Context, remote models.Remote, path
 	}, nil
 }
 
+// checkUpstream issues a conditional upstream HEAD (If-None-Match), load
+// balancing across the remote's base URLs and failing over to the next mirror on
+// a network error or 5xx.
 func (e *Engine) checkUpstream(ctx context.Context, remote models.Remote, path, etag string, prov provider.Provider) (bool, error) {
+	order := e.baseURLAttemptOrder(remote)
+	if len(order) == 0 {
+		return false, &ProxyError{Status: http.StatusBadGateway, Message: "no upstream base_url configured"}
+	}
+	var lastErr error
+	for i, url := range order {
+		ctr := e.beginAttempt(remote, url)
+		notModified, err := e.checkUpstreamOnce(ctx, withBaseURL(remote, url), path, etag, prov)
+		endAttempt(ctr)
+		if err == nil {
+			return notModified, nil
+		}
+		lastErr = err
+		if i < len(order)-1 && shouldFailover(err) {
+			slog.Warn("upstream revalidation failed, failing over", "remote", remote.Name, "base_url", url, "error", err)
+			continue
+		}
+		return false, err
+	}
+	return false, lastErr
+}
+
+func (e *Engine) checkUpstreamOnce(ctx context.Context, remote models.Remote, path, etag string, prov provider.Provider) (bool, error) {
 	url := prov.UpstreamURL(remote, path)
 
 	req, err := http.NewRequestWithContext(ctx, http.MethodHead, url, nil)
@@ -649,3 +738,111 @@ func isNetworkError(err error) bool {
 	var ue *UpstreamError
 	return errors.As(err, &ue)
 }
+
+// baseURLAttemptOrder returns the ordered upstream base URLs to try for a single
+// request, drawn from the remote's pool ([base_url] + mirrorlist). A multi-mirror
+// remote starts at a strategy-chosen position and advances linearly for
+// failover; a remote with no mirrorlist yields exactly [base_url], preserving the
+// original single-attempt behavior. The default (round_robin) rotates the
+// starting mirror; least_conn starts with the mirror handling the fewest
+// in-flight requests. Failover order after the first pick is unchanged.
+func (e *Engine) baseURLAttemptOrder(remote models.Remote) []string {
+	urls := remote.UpstreamPool()
+	if len(urls) <= 1 {
+		return urls
+	}
+	// Rotate by the round-robin cursor first so equal-load mirrors still spread
+	// evenly; least_conn then stable-sorts this rotation by in-flight count.
+	v, _ := e.rrCounters.LoadOrStore(remote.Name, new(atomic.Uint64))
+	start := int(v.(*atomic.Uint64).Add(1) - 1)
+	ordered := make([]string, len(urls))
+	for i := range urls {
+		ordered[i] = urls[(start+i)%len(urls)]
+	}
+	if remote.MirrorStrategy == models.MirrorStrategyLeastConn {
+		// Snapshot each mirror's in-flight count once, then sort the snapshot.
+		// Reading the gauge inside the comparator would repeat an allocating
+		// sync.Map lookup on every comparison (O(n log n) lookups); this is O(n).
+		snap := make([]inflightSnapshot, len(ordered))
+		for i, url := range ordered {
+			snap[i] = inflightSnapshot{url: url, count: e.inflightCount(remote.Name, url)}
+		}
+		sort.SliceStable(snap, func(a, b int) bool {
+			return snap[a].count < snap[b].count
+		})
+		for i := range snap {
+			ordered[i] = snap[i].url
+		}
+	}
+	return ordered
+}
+
+// inflightSnapshot pairs a mirror URL with its sampled in-flight count so the
+// least_conn sort compares plain ints instead of re-reading the gauge.
+type inflightSnapshot struct {
+	url   string
+	count int64
+}
+
+// inflightCount reads the in-flight request gauge for a given (remote, upstream
+// URL) without creating it, returning 0 when the counter is absent. This keeps
+// the selection read path allocation-free (plain Load, no LoadOrStore).
+func (e *Engine) inflightCount(remoteName, url string) int64 {
+	v, ok := e.inflight.Load(remoteName + "\x00" + url)
+	if !ok {
+		return 0
+	}
+	return v.(*atomic.Int64).Load()
+}
+
+// inflightCounter returns the shared in-flight request gauge for a given
+// (remote, upstream URL), creating it on first use.
+func (e *Engine) inflightCounter(remoteName, url string) *atomic.Int64 {
+	v, _ := e.inflight.LoadOrStore(remoteName+"\x00"+url, new(atomic.Int64))
+	return v.(*atomic.Int64)
+}
+
+// beginAttempt increments the in-flight gauge for a least_conn multi-mirror
+// remote before an upstream call and returns the counter to release; it is a
+// no-op (returns nil) for round-robin remotes and single-URL pools.
+func (e *Engine) beginAttempt(remote models.Remote, url string) *atomic.Int64 {
+	if remote.MirrorStrategy != models.MirrorStrategyLeastConn {
+		return nil
+	}
+	if len(remote.UpstreamPool()) <= 1 {
+		return nil
+	}
+	ctr := e.inflightCounter(remote.Name, url)
+	ctr.Add(1)
+	return ctr
+}
+
+// endAttempt decrements a gauge returned by beginAttempt, tolerating nil.
+func endAttempt(ctr *atomic.Int64) {
+	if ctr != nil {
+		ctr.Add(-1)
+	}
+}
+
+// withBaseURL narrows a remote's active BaseURL to a single selected mirror so
+// providers (UpstreamURL/AuthHeaders/RewriteResponse) operate on exactly that
+// upstream for this attempt.
+func withBaseURL(remote models.Remote, url string) models.Remote {
+	remote.BaseURL = url
+	remote.Mirrorlist = nil
+	return remote
+}
+
+// shouldFailover reports whether an upstream attempt error is worth retrying
+// against the next mirror: network errors/timeouts and upstream 5xx responses.
+// Definitive statuses (404/403/401/...) are returned to the caller unchanged.
+func shouldFailover(err error) bool {
+	if isNetworkError(err) {
+		return true
+	}
+	var pe *ProxyError
+	if errors.As(err, &pe) {
+		return pe.Status >= 500
+	}
+	return false
+}

internal/proxy/leastconn_test.go

@@ -0,0 +1,148 @@
+package proxy
+
+import (
+	"testing"
+
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+// baseURLAttemptOrder and the in-flight gauge only touch the engine's sync.Map
+// fields, so these tests run against a zero-value Engine without a DB/S3/redis
+// stack and can drive the gauge deterministically.
+
+// TestLeastConnPicksLeastLoaded pre-loads one mirror's in-flight gauge and
+// asserts a least_conn remote starts its attempt order with the idle mirror.
+func TestLeastConnPicksLeastLoaded(t *testing.T) {
+	e := &Engine{}
+	r := models.Remote{
+		Name:           "lc",
+		BaseURL:        "https://a.example",
+		Mirrorlist:     []string{"https://b.example"},
+		MirrorStrategy: models.MirrorStrategyLeastConn,
+	}
+
+	// Make A appear busy: least_conn must prefer B regardless of RR rotation.
+	e.inflightCounter(r.Name, "https://a.example").Add(3)
+	for i := 0; i < 5; i++ {
+		order := e.baseURLAttemptOrder(r)
+		if len(order) != 2 {
+			t.Fatalf("attempt %d: order len = %d, want 2", i, len(order))
+		}
+		if order[0] != "https://b.example" {
+			t.Fatalf("attempt %d: least_conn started with %q, want idle mirror https://b.example", i, order[0])
+		}
+	}
+
+	// Once B is the busier mirror, the starting pick flips to A.
+	e.inflightCounter(r.Name, "https://b.example").Add(10)
+	if order := e.baseURLAttemptOrder(r); order[0] != "https://a.example" {
+		t.Fatalf("after loading B, least_conn started with %q, want https://a.example", order[0])
+	}
+}
+
+// TestLeastConnStableTieBreak asserts that when every mirror carries equal
+// in-flight load, least_conn falls back to the round-robin rotation: the
+// snapshot sort is stable, so tied mirrors keep the RR-rotated order and the
+// starting pick advances across the whole pool on successive calls.
+func TestLeastConnStableTieBreak(t *testing.T) {
+	e := &Engine{}
+	r := models.Remote{
+		Name:           "lc-tie",
+		BaseURL:        "https://a.example",
+		Mirrorlist:     []string{"https://b.example", "https://c.example"},
+		MirrorStrategy: models.MirrorStrategyLeastConn,
+	}
+	pool := r.UpstreamPool()
+
+	// Equal (zero) load on every mirror: order must equal the RR rotation.
+	starts := map[string]int{}
+	for i := 0; i < len(pool); i++ {
+		order := e.baseURLAttemptOrder(r)
+		if len(order) != len(pool) {
+			t.Fatalf("attempt %d: order len = %d, want %d", i, len(order), len(pool))
+		}
+		// A stable sort of an all-tied slice is a pure RR rotation: for the
+		// call whose cursor selects start s, order must be pool rotated by s.
+		start := indexOf(pool, order[0])
+		for j := range order {
+			if want := pool[(start+j)%len(pool)]; order[j] != want {
+				t.Fatalf("attempt %d: order[%d] = %q, want RR-rotated %q", i, j, order[j], want)
+			}
+		}
+		starts[order[0]]++
+	}
+	if len(starts) != len(pool) {
+		t.Fatalf("tied least_conn did not rotate across the whole pool: %v", starts)
+	}
+}
+
+func indexOf(s []string, v string) int {
+	for i := range s {
+		if s[i] == v {
+			return i
+		}
+	}
+	return -1
+}
+
+// TestRoundRobinDefaultUnchanged asserts an unset strategy still rotates the
+// starting mirror across the pool and ignores the in-flight gauge.
+func TestRoundRobinDefaultUnchanged(t *testing.T) {
+	e := &Engine{}
+	r := models.Remote{
+		Name:       "rr",
+		BaseURL:    "https://a.example",
+		Mirrorlist: []string{"https://b.example"},
+	}
+
+	// Even with A heavily loaded, round-robin must still rotate (not avoid A).
+	e.inflightCounter(r.Name, "https://a.example").Add(100)
+	starts := map[string]int{}
+	for i := 0; i < 4; i++ {
+		starts[e.baseURLAttemptOrder(r)[0]]++
+	}
+	if starts["https://a.example"] == 0 || starts["https://b.example"] == 0 {
+		t.Fatalf("round-robin did not rotate starting mirror: %v", starts)
+	}
+}
+
+// TestLeastConnSingleURLNoOp asserts a single-URL pool yields exactly [base_url]
+// and beginAttempt is a no-op there and for round-robin remotes.
+func TestLeastConnSingleURLNoOp(t *testing.T) {
+	e := &Engine{}
+	solo := models.Remote{Name: "solo", BaseURL: "https://a.example", MirrorStrategy: models.MirrorStrategyLeastConn}
+	if order := e.baseURLAttemptOrder(solo); len(order) != 1 || order[0] != "https://a.example" {
+		t.Fatalf("single-url order = %v, want [base_url]", order)
+	}
+	if ctr := e.beginAttempt(solo, "https://a.example"); ctr != nil {
+		t.Fatal("beginAttempt on single-url pool should be a no-op (nil)")
+	}
+
+	rr := models.Remote{Name: "rr2", BaseURL: "https://a.example", Mirrorlist: []string{"https://b.example"}}
+	if ctr := e.beginAttempt(rr, "https://a.example"); ctr != nil {
+		t.Fatal("beginAttempt on round-robin remote should be a no-op (nil)")
+	}
+}
+
+// TestBeginEndAttemptGauge asserts the gauge increments on begin and returns to
+// zero after endAttempt, so it tracks live in-flight requests.
+func TestBeginEndAttemptGauge(t *testing.T) {
+	e := &Engine{}
+	r := models.Remote{
+		Name:           "g",
+		BaseURL:        "https://a.example",
+		Mirrorlist:     []string{"https://b.example"},
+		MirrorStrategy: models.MirrorStrategyLeastConn,
+	}
+	c1 := e.beginAttempt(r, "https://a.example")
+	c2 := e.beginAttempt(r, "https://a.example")
+	if got := e.inflightCounter(r.Name, "https://a.example").Load(); got != 2 {
+		t.Fatalf("gauge after two begins = %d, want 2", got)
+	}
+	endAttempt(c1)
+	endAttempt(c2)
+	if got := e.inflightCounter(r.Name, "https://a.example").Load(); got != 0 {
+		t.Fatalf("gauge after matching ends = %d, want 0", got)
+	}
+	endAttempt(nil) // tolerated
+}

internal/proxy/multibaseurl_test.go

@@ -0,0 +1,188 @@
+package proxy
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"sync/atomic"
+	"testing"
+
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+// TestFetchMultiBaseURLRoundRobin drives distinct artifact paths through a
+// remote configured with two upstreams and asserts both receive traffic.
+func TestFetchMultiBaseURLRoundRobin(t *testing.T) {
+	requireStack(t)
+	ctx := context.Background()
+
+	var hitsA, hitsB atomic.Int64
+	upA := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		hitsA.Add(1)
+		w.Write([]byte("A"))
+	}))
+	defer upA.Close()
+	upB := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		hitsB.Add(1)
+		w.Write([]byte("B"))
+	}))
+	defer upB.Close()
+
+	r := seed(t, models.Remote{
+		Name:         "eng-rr",
+		PackageType:  models.PackageGeneric,
+		RepoType:     models.RepoTypeRemote,
+		BaseURL:      upA.URL,
+		Mirrorlist:   []string{upB.URL},
+		StaleOnError: true,
+	})
+	p := prov(t, models.PackageGeneric)
+
+	const n = 10
+	for i := 0; i < n; i++ {
+		res, err := testEngine.Fetch(ctx, r, fmt.Sprintf("rr-%d.bin", i), p)
+		if err != nil {
+			t.Fatalf("fetch %d: %v", i, err)
+		}
+		res.Reader.Close()
+	}
+
+	if hitsA.Load() == 0 || hitsB.Load() == 0 {
+		t.Fatalf("round-robin did not spread across both upstreams: A=%d B=%d", hitsA.Load(), hitsB.Load())
+	}
+	if total := hitsA.Load() + hitsB.Load(); total != n {
+		t.Fatalf("expected %d upstream hits total, got %d (A=%d B=%d)", n, total, hitsA.Load(), hitsB.Load())
+	}
+}
+
+// TestFetchMultiBaseURLFailover asserts that a dead/erroring primary mirror
+// transparently fails over to a healthy secondary, for both a 5xx primary and a
+// network-unreachable primary.
+func TestFetchMultiBaseURLFailover(t *testing.T) {
+	requireStack(t)
+	ctx := context.Background()
+
+	var hitsB atomic.Int64
+	upB := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		hitsB.Add(1)
+		w.Write([]byte("served-by-B"))
+	}))
+	defer upB.Close()
+	up500 := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusInternalServerError)
+	}))
+	defer up500.Close()
+
+	p := prov(t, models.PackageGeneric)
+
+	// Primary returns 5xx: every request must still succeed via the secondary.
+	r5xx := seed(t, models.Remote{
+		Name:        "eng-failover-5xx",
+		PackageType: models.PackageGeneric,
+		RepoType:    models.RepoTypeRemote,
+		BaseURL:     up500.URL,
+		Mirrorlist:  []string{upB.URL},
+	})
+	for i := 0; i < 6; i++ {
+		res, err := testEngine.Fetch(ctx, r5xx, fmt.Sprintf("fo5-%d.bin", i), p)
+		if err != nil {
+			t.Fatalf("5xx failover fetch %d: %v", i, err)
+		}
+		if got := readAll(t, res); got != "served-by-B" {
+			t.Fatalf("5xx failover fetch %d body=%q, want served-by-B", i, got)
+		}
+	}
+
+	// Primary is network-unreachable: failover must still reach the secondary.
+	rNet := seed(t, models.Remote{
+		Name:        "eng-failover-net",
+		PackageType: models.PackageGeneric,
+		RepoType:    models.RepoTypeRemote,
+		BaseURL:     "http://127.0.0.1:1",
+		Mirrorlist:  []string{upB.URL},
+	})
+	res, err := testEngine.Fetch(ctx, rNet, "fonet.bin", p)
+	if err != nil {
+		t.Fatalf("network failover fetch: %v", err)
+	}
+	if got := readAll(t, res); got != "served-by-B" {
+		t.Fatalf("network failover body=%q, want served-by-B", got)
+	}
+	if hitsB.Load() == 0 {
+		t.Fatal("secondary upstream never served during failover")
+	}
+}
+
+// TestFetchDefinitiveStatusNoFailover asserts a definitive 404 from the first
+// mirror is returned as-is (not failed over): a missing artifact is not a mirror
+// outage. The remote is fresh so its round-robin cursor starts at index 0.
+func TestFetchDefinitiveStatusNoFailover(t *testing.T) {
+	requireStack(t)
+	ctx := context.Background()
+
+	var hitsB atomic.Int64
+	up404 := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.NotFound(w, r)
+	}))
+	defer up404.Close()
+	upB := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		hitsB.Add(1)
+		w.Write([]byte("B"))
+	}))
+	defer upB.Close()
+
+	r := seed(t, models.Remote{
+		Name:        "eng-no-failover-404",
+		PackageType: models.PackageGeneric,
+		RepoType:    models.RepoTypeRemote,
+		BaseURL:     up404.URL,
+		Mirrorlist:  []string{upB.URL},
+	})
+	_, err := testEngine.Fetch(ctx, r, "missing.bin", prov(t, models.PackageGeneric))
+	var pe *ProxyError
+	if err == nil || !asProxyError(err, &pe) || pe.Status != http.StatusNotFound {
+		t.Fatalf("expected 404 ProxyError without failover, got %v", err)
+	}
+	if hitsB.Load() != 0 {
+		t.Fatalf("404 from primary must not fail over, but secondary was hit %d times", hitsB.Load())
+	}
+}
+
+// TestFetchSingleBaseURLUnchanged asserts a single-URL remote behaves exactly as
+// before: one healthy URL succeeds, and one dead URL errors with no failover.
+func TestFetchSingleBaseURLUnchanged(t *testing.T) {
+	requireStack(t)
+	ctx := context.Background()
+
+	upB := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte("solo"))
+	}))
+	defer upB.Close()
+
+	p := prov(t, models.PackageGeneric)
+
+	rOK := seed(t, models.Remote{
+		Name:        "eng-solo",
+		PackageType: models.PackageGeneric,
+		RepoType:    models.RepoTypeRemote,
+		BaseURL:     upB.URL,
+	})
+	res, err := testEngine.Fetch(ctx, rOK, "solo.bin", p)
+	if err != nil {
+		t.Fatalf("single-url fetch: %v", err)
+	}
+	if got := readAll(t, res); got != "solo" {
+		t.Fatalf("single-url body=%q, want solo", got)
+	}
+
+	rDead := seed(t, models.Remote{
+		Name:        "eng-solo-dead",
+		PackageType: models.PackageGeneric,
+		RepoType:    models.RepoTypeRemote,
+		BaseURL:     "http://127.0.0.1:1",
+	})
+	if _, err := testEngine.Fetch(ctx, rDead, "x.bin", p); err == nil {
+		t.Fatal("single dead upstream should error, not succeed")
+	}
+}

internal/proxy/selection_bench_test.go

@@ -0,0 +1,156 @@
+package proxy
+
+import (
+	"fmt"
+	"testing"
+
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+// These benchmarks isolate the mirror-selection overhead only: they construct a
+// zero-value Engine (no DB/S3/redis) and call baseURLAttemptOrder /
+// beginAttempt / endAttempt directly, mirroring leastconn_test.go and
+// multibaseurl_test.go. This quantifies how much latency the load-balancing
+// strategy (round_robin vs least_conn) adds versus a single-URL remote. Note
+// that in the live proxy this selection runs only on the cache-miss/upstream
+// path; a cache hit never calls it.
+
+// mirrorPool builds a remote with n upstreams (base_url + n-1 mirrorlist
+// entries) under the given strategy.
+func mirrorPool(name, strategy string, n int) models.Remote {
+	r := models.Remote{
+		Name:           name,
+		BaseURL:        "https://mirror0.example/repo",
+		MirrorStrategy: strategy,
+	}
+	for i := 1; i < n; i++ {
+		r.Mirrorlist = append(r.Mirrorlist, fmt.Sprintf("https://mirror%d.example/repo", i))
+	}
+	return r
+}
+
+// skewInflight sets an ascending in-flight load across the pool so least_conn's
+// stable sort has real work to do (mirror0 busiest, last mirror idle).
+func skewInflight(e *Engine, r models.Remote) {
+	pool := r.UpstreamPool()
+	for i, u := range pool {
+		e.inflightCounter(r.Name, u).Add(int64(len(pool) - i))
+	}
+}
+
+// BenchmarkBaseURLAttemptOrder_SingleURL measures the early-return no-op path
+// (pool of 1): the branch that preserves original single-attempt behavior and
+// must add effectively zero overhead. This is the same code the cache-miss path
+// takes for every non-mirrored remote.
+func BenchmarkBaseURLAttemptOrder_SingleURL(b *testing.B) {
+	e := &Engine{}
+	r := models.Remote{Name: "solo", BaseURL: "https://mirror0.example/repo"}
+	b.ReportAllocs()
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		_ = e.baseURLAttemptOrder(r)
+	}
+}
+
+// BenchmarkBaseURLAttemptOrder_RoundRobin measures the default strategy: rotate
+// the starting mirror by an atomic cursor and materialize the ordered slice. No
+// in-flight sort.
+func BenchmarkBaseURLAttemptOrder_RoundRobin(b *testing.B) {
+	for _, n := range []int{3, 8} {
+		b.Run(fmt.Sprintf("pool%d", n), func(b *testing.B) {
+			e := &Engine{}
+			r := mirrorPool("rr", models.MirrorStrategyRoundRobin, n)
+			b.ReportAllocs()
+			b.ResetTimer()
+			for i := 0; i < b.N; i++ {
+				_ = e.baseURLAttemptOrder(r)
+			}
+		})
+	}
+}
+
+// BenchmarkBaseURLAttemptOrder_LeastConn measures the least_conn strategy: RR
+// rotation plus a stable sort of the pool by the atomic in-flight gauges. Skew
+// is preloaded so the sort compares distinct loads.
+func BenchmarkBaseURLAttemptOrder_LeastConn(b *testing.B) {
+	for _, n := range []int{3, 8} {
+		b.Run(fmt.Sprintf("pool%d", n), func(b *testing.B) {
+			e := &Engine{}
+			r := mirrorPool("lc", models.MirrorStrategyLeastConn, n)
+			skewInflight(e, r)
+			b.ReportAllocs()
+			b.ResetTimer()
+			for i := 0; i < b.N; i++ {
+				_ = e.baseURLAttemptOrder(r)
+			}
+		})
+	}
+}
+
+// BenchmarkBeginEndAttempt measures the gauge inc/dec pair that brackets each
+// least_conn upstream attempt (LoadOrStore + atomic add, then atomic add back).
+func BenchmarkBeginEndAttempt(b *testing.B) {
+	e := &Engine{}
+	r := mirrorPool("g", models.MirrorStrategyLeastConn, 3)
+	url := r.UpstreamPool()[0]
+	b.ReportAllocs()
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		ctr := e.beginAttempt(r, url)
+		endAttempt(ctr)
+	}
+}
+
+// BenchmarkBaseURLAttemptOrder_RoundRobin_Parallel surfaces atomic-cursor
+// contention on the shared rrCounters entry under concurrent selection.
+func BenchmarkBaseURLAttemptOrder_RoundRobin_Parallel(b *testing.B) {
+	for _, n := range []int{3, 8} {
+		b.Run(fmt.Sprintf("pool%d", n), func(b *testing.B) {
+			e := &Engine{}
+			r := mirrorPool("rrp", models.MirrorStrategyRoundRobin, n)
+			b.ReportAllocs()
+			b.ResetTimer()
+			b.RunParallel(func(pb *testing.PB) {
+				for pb.Next() {
+					_ = e.baseURLAttemptOrder(r)
+				}
+			})
+		})
+	}
+}
+
+// BenchmarkBaseURLAttemptOrder_LeastConn_Parallel surfaces sync.Map read
+// contention on the in-flight gauges plus the per-call sort under concurrency.
+func BenchmarkBaseURLAttemptOrder_LeastConn_Parallel(b *testing.B) {
+	for _, n := range []int{3, 8} {
+		b.Run(fmt.Sprintf("pool%d", n), func(b *testing.B) {
+			e := &Engine{}
+			r := mirrorPool("lcp", models.MirrorStrategyLeastConn, n)
+			skewInflight(e, r)
+			b.ReportAllocs()
+			b.ResetTimer()
+			b.RunParallel(func(pb *testing.PB) {
+				for pb.Next() {
+					_ = e.baseURLAttemptOrder(r)
+				}
+			})
+		})
+	}
+}
+
+// BenchmarkBeginEndAttempt_Parallel exercises the gauge inc/dec pair under
+// concurrency: all goroutines hammer the same atomic.Int64, the realistic
+// hot-mirror case, to surface counter contention.
+func BenchmarkBeginEndAttempt_Parallel(b *testing.B) {
+	e := &Engine{}
+	r := mirrorPool("gp", models.MirrorStrategyLeastConn, 3)
+	url := r.UpstreamPool()[0]
+	b.ReportAllocs()
+	b.ResetTimer()
+	b.RunParallel(func(pb *testing.PB) {
+		for pb.Next() {
+			ctr := e.beginAttempt(r, url)
+			endAttempt(ctr)
+		}
+	})
+}

internal/server/server.go

@@ -20,7 +20,8 @@ import (
 	"git.unkin.net/unkin/artifactapi/internal/database"
 	"git.unkin.net/unkin/artifactapi/internal/gc"
 	"git.unkin.net/unkin/artifactapi/internal/githubauth"
-	_ "git.unkin.net/unkin/artifactapi/internal/provider/alpine"
+	"git.unkin.net/unkin/artifactapi/internal/provider/alpine"
+	"git.unkin.net/unkin/artifactapi/internal/provider/deb"
 	_ "git.unkin.net/unkin/artifactapi/internal/provider/docker"
 	_ "git.unkin.net/unkin/artifactapi/internal/provider/generic"
 	_ "git.unkin.net/unkin/artifactapi/internal/provider/goproxy"
@@ -34,6 +35,7 @@ import (
 	"git.unkin.net/unkin/artifactapi/internal/storage"
 	"git.unkin.net/unkin/artifactapi/internal/tfsign"
 	"git.unkin.net/unkin/artifactapi/internal/virtual"
+	"git.unkin.net/unkin/artifactapi/pkg/models"
 )
 
 type Server struct {
@@ -49,6 +51,8 @@ type Server struct {
 	tfRegistry   *tfregistry.Handler
 	gc           *gc.Collector
 	syncer       *rpm.Syncer
+	debSyncer    *deb.Syncer
+	alpineSyncer *alpine.Syncer
 }
 
 func New(cfg *config.Config, version string) (*Server, error) {
@@ -96,6 +100,18 @@ func New(cfg *config.Config, version string) (*Server, error) {
 		Workers:      cfg.GitHubSyncWorkers,
 		PollInterval: time.Duration(cfg.GitHubSyncPollInterval) * time.Second,
 	})
+	debSyncer := deb.NewSyncer(db, deb.SyncConfig{
+		RatePerSec:   cfg.GitHubSyncRatePerSec,
+		Burst:        cfg.GitHubSyncBurst,
+		Workers:      cfg.GitHubSyncWorkers,
+		PollInterval: time.Duration(cfg.GitHubSyncPollInterval) * time.Second,
+	})
+	alpineSyncer := alpine.NewSyncer(db, alpine.SyncConfig{
+		RatePerSec:   cfg.GitHubSyncRatePerSec,
+		Burst:        cfg.GitHubSyncBurst,
+		Workers:      cfg.GitHubSyncWorkers,
+		PollInterval: time.Duration(cfg.GitHubSyncPollInterval) * time.Second,
+	})
 
 	// The terraform registry signs with a GPG key. A configured file wins (BYO
 	// key); otherwise artifactapi generates one on first start and persists it in
@@ -128,6 +144,8 @@ func New(cfg *config.Config, version string) (*Server, error) {
 		tfRegistry:   tfRegistry,
 		gc:           collector,
 		syncer:       syncer,
+		debSyncer:    debSyncer,
+		alpineSyncer: alpineSyncer,
 	}
 
 	s.router = s.routes()
@@ -157,7 +175,11 @@ func (s *Server) routes() chi.Router {
 	r.Mount("/api/v1", proxyHandler.Routes())
 	r.Mount("/v2", proxyHandler.DockerV2Routes())
 
-	remotesHandler := v2.NewRemotesHandler(s.db, s.syncer)
+	remotesHandler := v2.NewRemotesHandler(s.db, s.cache, map[models.PackageType]v2.Primer{
+		models.PackageGitHubRPM:    s.syncer,
+		models.PackageGitHubDeb:    s.debSyncer,
+		models.PackageGitHubAlpine: s.alpineSyncer,
+	})
 	virtualsHandler := v2.NewVirtualsHandler(s.db)
 	healthHandler := v2.NewHealthHandler(s.db, s.cache, s.store)
 	statsHandler := v2.NewStatsHandler(s.db)
@@ -225,6 +247,8 @@ func (s *Server) newHTTPServer() *http.Server {
 func (s *Server) Run(ctx context.Context) error {
 	go s.gc.Run(ctx)
 	go s.syncer.Run(ctx)
+	go s.debSyncer.Run(ctx)
+	go s.alpineSyncer.Run(ctx)
 
 	httpServer := s.newHTTPServer()
 
@@ -246,6 +270,8 @@ func (s *Server) Run(ctx context.Context) error {
 func (s *Server) RunOnListener(ctx context.Context, ln net.Listener) error {
 	go s.gc.Run(ctx)
 	go s.syncer.Run(ctx)
+	go s.debSyncer.Run(ctx)
+	go s.alpineSyncer.Run(ctx)
 
 	httpServer := s.newHTTPServer()
 

internal/testsupport/apk.go

@@ -0,0 +1,38 @@
+package testsupport
+
+import (
+	"bytes"
+	"fmt"
+)
+
+// MinimalApk builds a valid-enough Alpine package in pure Go (no committed
+// binary fixture, no abuild): two concatenated, independently gzipped tar
+// streams -- a control stream carrying .PKGINFO and a data stream carrying a
+// single payload file. It mirrors MinimalDeb/MinimalRPM and is parseable by the
+// alpine provider (which derives arch/name/version and the Q1 pull checksum from
+// the control stream).
+func MinimalApk(name, version, arch string) []byte {
+	pkginfo := fmt.Sprintf(
+		"# generated by testsupport\n"+
+			"pkgname = %s\n"+
+			"pkgver = %s\n"+
+			"arch = %s\n"+
+			"pkgdesc = minimal test package\n"+
+			"url = https://example.com/%s\n"+
+			"license = MIT\n"+
+			"origin = %s\n"+
+			"maintainer = e2e <e2e@example.com>\n"+
+			"builddate = 1700000000\n"+
+			"size = 4\n"+
+			"depend = so:libc.musl-x86_64.so.1\n"+
+			"provides = cmd:%s=%s\n",
+		name, version, arch, name, name, name, version)
+
+	control := gzipBytes(tarSingle(".PKGINFO", []byte(pkginfo)))
+	data := gzipBytes(tarSingle("usr/bin/"+name, []byte("body")))
+
+	var buf bytes.Buffer
+	buf.Write(control)
+	buf.Write(data)
+	return buf.Bytes()
+}

internal/testsupport/deb.go

@@ -0,0 +1,61 @@
+package testsupport
+
+import (
+	"archive/tar"
+	"bytes"
+	"compress/gzip"
+	"fmt"
+)
+
+// MinimalDeb builds a valid-enough Debian package in pure Go (no committed
+// binary fixture, no dpkg-deb): an ar archive of debian-binary, a gzip
+// control.tar.gz carrying ./control, and an (empty) gzip data.tar.gz. It is the
+// deb analog of MinimalRPM and is parseable by the deb provider.
+func MinimalDeb(name, version, arch string) []byte {
+	control := fmt.Sprintf(
+		"Package: %s\nVersion: %s\nArchitecture: %s\nMaintainer: e2e <e2e@example.com>\n"+
+			"Section: utils\nPriority: optional\nDescription: minimal test package\n",
+		name, version, arch)
+
+	controlTarGz := gzipBytes(tarSingle("./control", []byte(control)))
+	dataTarGz := gzipBytes(tarEmpty())
+
+	var buf bytes.Buffer
+	buf.WriteString("!<arch>\n")
+	arWrite(&buf, "debian-binary", []byte("2.0\n"))
+	arWrite(&buf, "control.tar.gz", controlTarGz)
+	arWrite(&buf, "data.tar.gz", dataTarGz)
+	return buf.Bytes()
+}
+
+func arWrite(buf *bytes.Buffer, name string, data []byte) {
+	fmt.Fprintf(buf, "%-16s%-12s%-6s%-6s%-8s%-10d`\n", name, "0", "0", "0", "100644", len(data))
+	buf.Write(data)
+	if len(data)%2 == 1 {
+		buf.WriteByte('\n')
+	}
+}
+
+func tarSingle(name string, data []byte) []byte {
+	var buf bytes.Buffer
+	tw := tar.NewWriter(&buf)
+	tw.WriteHeader(&tar.Header{Name: name, Mode: 0o644, Size: int64(len(data)), Typeflag: tar.TypeReg})
+	tw.Write(data)
+	tw.Close()
+	return buf.Bytes()
+}
+
+func tarEmpty() []byte {
+	var buf bytes.Buffer
+	tw := tar.NewWriter(&buf)
+	tw.Close()
+	return buf.Bytes()
+}
+
+func gzipBytes(data []byte) []byte {
+	var buf bytes.Buffer
+	gz := gzip.NewWriter(&buf)
+	gz.Write(data)
+	gz.Close()
+	return buf.Bytes()
+}

migrations/0001_init.sql

@@ -0,0 +1,206 @@
+CREATE TABLE IF NOT EXISTS remotes (
+	name            TEXT PRIMARY KEY,
+	package_type    TEXT NOT NULL,
+	repo_type       TEXT DEFAULT 'remote',
+	base_url        TEXT NOT NULL DEFAULT '',
+	mirrorlist      TEXT[] DEFAULT '{}',
+	mirror_strategy TEXT NOT NULL DEFAULT 'round_robin',
+	description     TEXT DEFAULT '',
+	username        TEXT DEFAULT '',
+	password        TEXT DEFAULT '',
+	immutable_ttl   INTEGER DEFAULT 0,
+	mutable_ttl     INTEGER DEFAULT 3600,
+	check_mutable   BOOLEAN DEFAULT TRUE,
+	patterns            TEXT[] DEFAULT '{}',
+	blocklist           TEXT[] DEFAULT '{}',
+	mutable_patterns    TEXT[] DEFAULT '{}',
+	immutable_patterns  TEXT[] DEFAULT '{}',
+	ban_tags_enabled    BOOLEAN DEFAULT FALSE,
+	ban_tags            TEXT[] DEFAULT '{}',
+	quarantine_enabled  BOOLEAN DEFAULT FALSE,
+	quarantine_days     INTEGER DEFAULT 3,
+	stale_on_error      BOOLEAN DEFAULT TRUE,
+	releases_remote     TEXT DEFAULT '',
+	managed_by          TEXT DEFAULT '',
+	created_at      TIMESTAMPTZ DEFAULT NOW(),
+	updated_at      TIMESTAMPTZ DEFAULT NOW()
+);
+
+CREATE TABLE IF NOT EXISTS virtuals (
+	name            TEXT PRIMARY KEY,
+	package_type    TEXT NOT NULL,
+	description     TEXT DEFAULT '',
+	members         TEXT[] NOT NULL,
+	managed_by      TEXT DEFAULT '',
+	created_at      TIMESTAMPTZ DEFAULT NOW(),
+	updated_at      TIMESTAMPTZ DEFAULT NOW()
+);
+
+CREATE TABLE IF NOT EXISTS blobs (
+	content_hash    TEXT PRIMARY KEY,
+	s3_key          TEXT NOT NULL,
+	size_bytes      BIGINT NOT NULL,
+	content_type    TEXT DEFAULT 'application/octet-stream',
+	created_at      TIMESTAMPTZ DEFAULT NOW()
+);
+
+CREATE TABLE IF NOT EXISTS artifacts (
+	id              BIGSERIAL PRIMARY KEY,
+	remote_name     TEXT NOT NULL REFERENCES remotes(name) ON DELETE CASCADE,
+	path            TEXT NOT NULL,
+	content_hash    TEXT NOT NULL REFERENCES blobs(content_hash),
+	upstream_etag   TEXT DEFAULT '',
+	upstream_last_modified TIMESTAMPTZ,
+	first_seen_at   TIMESTAMPTZ DEFAULT NOW(),
+	last_fetched_at TIMESTAMPTZ DEFAULT NOW(),
+	last_accessed_at TIMESTAMPTZ DEFAULT NOW(),
+	fetch_count     BIGINT DEFAULT 1,
+	access_count    BIGINT DEFAULT 1,
+	UNIQUE(remote_name, path)
+);
+
+CREATE INDEX IF NOT EXISTS idx_artifacts_remote ON artifacts(remote_name);
+CREATE INDEX IF NOT EXISTS idx_artifacts_last_accessed ON artifacts(last_accessed_at);
+
+CREATE TABLE IF NOT EXISTS local_files (
+	id              BIGSERIAL PRIMARY KEY,
+	repo_name       TEXT NOT NULL,
+	file_path       TEXT NOT NULL,
+	content_hash    TEXT NOT NULL REFERENCES blobs(content_hash),
+	created_at      TIMESTAMPTZ DEFAULT NOW(),
+	UNIQUE(repo_name, file_path)
+);
+
+CREATE TABLE IF NOT EXISTS access_log (
+	id              BIGSERIAL PRIMARY KEY,
+	remote_name     TEXT NOT NULL,
+	path            TEXT NOT NULL,
+	cache_hit       BOOLEAN NOT NULL,
+	size_bytes      BIGINT DEFAULT 0,
+	upstream_ms     INTEGER DEFAULT 0,
+	client_ip       TEXT DEFAULT '',
+	created_at      TIMESTAMPTZ DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_access_log_remote_time ON access_log(remote_name, created_at);
+
+ALTER TABLE remotes ADD COLUMN IF NOT EXISTS repo_type TEXT DEFAULT 'remote';
+ALTER TABLE remotes ADD COLUMN IF NOT EXISTS mirrorlist TEXT[] DEFAULT '{}';
+ALTER TABLE remotes ADD COLUMN IF NOT EXISTS mirror_strategy TEXT NOT NULL DEFAULT 'round_robin';
+ALTER TABLE remotes ADD COLUMN IF NOT EXISTS upstream_dial_timeout INTEGER DEFAULT 0;
+ALTER TABLE remotes ADD COLUMN IF NOT EXISTS upstream_tls_timeout INTEGER DEFAULT 0;
+ALTER TABLE remotes ADD COLUMN IF NOT EXISTS upstream_response_header_timeout INTEGER DEFAULT 0;
+
+CREATE TABLE IF NOT EXISTS rpm_metadata (
+	id              BIGSERIAL PRIMARY KEY,
+	repo_name       TEXT NOT NULL,
+	file_path       TEXT NOT NULL,
+	content_hash    TEXT NOT NULL,
+	name            TEXT NOT NULL,
+	epoch           INTEGER DEFAULT 0,
+	version         TEXT NOT NULL,
+	release         TEXT NOT NULL,
+	arch            TEXT NOT NULL,
+	summary         TEXT DEFAULT '',
+	description     TEXT DEFAULT '',
+	rpm_size        BIGINT DEFAULT 0,
+	installed_size  BIGINT DEFAULT 0,
+	license         TEXT DEFAULT '',
+	vendor          TEXT DEFAULT '',
+	build_group     TEXT DEFAULT '',
+	build_host      TEXT DEFAULT '',
+	source_rpm      TEXT DEFAULT '',
+	url             TEXT DEFAULT '',
+	packager        TEXT DEFAULT '',
+	requires        JSONB DEFAULT '[]',
+	provides        JSONB DEFAULT '[]',
+	conflicts       JSONB DEFAULT '[]',
+	obsoletes       JSONB DEFAULT '[]',
+	files           JSONB DEFAULT '[]',
+	changelogs      JSONB DEFAULT '[]',
+	created_at      TIMESTAMPTZ DEFAULT NOW(),
+	UNIQUE(repo_name, file_path)
+);
+
+CREATE INDEX IF NOT EXISTS idx_rpm_metadata_repo ON rpm_metadata(repo_name);
+
+ALTER TABLE rpm_metadata ADD COLUMN IF NOT EXISTS conflicts JSONB DEFAULT '[]';
+ALTER TABLE rpm_metadata ADD COLUMN IF NOT EXISTS obsoletes JSONB DEFAULT '[]';
+
+CREATE TABLE IF NOT EXISTS deb_metadata (
+	id              BIGSERIAL PRIMARY KEY,
+	repo_name       TEXT NOT NULL,
+	file_path       TEXT NOT NULL,
+	content_hash    TEXT NOT NULL,
+	name            TEXT NOT NULL,
+	version         TEXT NOT NULL,
+	architecture    TEXT NOT NULL,
+	control         TEXT NOT NULL,
+	size            BIGINT DEFAULT 0,
+	md5             TEXT DEFAULT '',
+	sha256          TEXT DEFAULT '',
+	created_at      TIMESTAMPTZ DEFAULT NOW(),
+	UNIQUE(repo_name, file_path)
+);
+
+CREATE INDEX IF NOT EXISTS idx_deb_metadata_repo ON deb_metadata(repo_name);
+
+CREATE TABLE IF NOT EXISTS alpine_metadata (
+	id                BIGSERIAL PRIMARY KEY,
+	repo_name         TEXT NOT NULL,
+	file_path         TEXT NOT NULL,
+	content_hash      TEXT NOT NULL,
+	checksum          TEXT NOT NULL,
+	name              TEXT NOT NULL,
+	version           TEXT NOT NULL,
+	arch              TEXT NOT NULL,
+	download_size     BIGINT DEFAULT 0,
+	installed_size    BIGINT DEFAULT 0,
+	description       TEXT DEFAULT '',
+	url               TEXT DEFAULT '',
+	license           TEXT DEFAULT '',
+	origin            TEXT DEFAULT '',
+	maintainer        TEXT DEFAULT '',
+	build_time        BIGINT DEFAULT 0,
+	commit_hash       TEXT DEFAULT '',
+	provider_priority TEXT DEFAULT '',
+	depends           TEXT DEFAULT '',
+	provides          TEXT DEFAULT '',
+	install_if        TEXT DEFAULT '',
+	created_at        TIMESTAMPTZ DEFAULT NOW(),
+	UNIQUE(repo_name, file_path)
+);
+
+CREATE INDEX IF NOT EXISTS idx_alpine_metadata_repo ON alpine_metadata(repo_name);
+CREATE INDEX IF NOT EXISTS idx_alpine_metadata_repo_arch ON alpine_metadata(repo_name, arch);
+
+CREATE TABLE IF NOT EXISTS github_rpm_sync_state (
+	remote_name        TEXT PRIMARY KEY,
+	etag               TEXT DEFAULT '',
+	last_synced_at     TIMESTAMPTZ,
+	sync_lease_owner   TEXT DEFAULT '',
+	sync_lease_expires TIMESTAMPTZ
+);
+
+CREATE TABLE IF NOT EXISTS github_deb_sync_state (
+	remote_name        TEXT PRIMARY KEY,
+	etag               TEXT DEFAULT '',
+	last_synced_at     TIMESTAMPTZ,
+	sync_lease_owner   TEXT DEFAULT '',
+	sync_lease_expires TIMESTAMPTZ
+);
+
+CREATE TABLE IF NOT EXISTS github_alpine_sync_state (
+	remote_name        TEXT PRIMARY KEY,
+	etag               TEXT DEFAULT '',
+	last_synced_at     TIMESTAMPTZ,
+	sync_lease_owner   TEXT DEFAULT '',
+	sync_lease_expires TIMESTAMPTZ
+);
+
+CREATE TABLE IF NOT EXISTS signing_keys (
+	purpose             TEXT PRIMARY KEY,
+	private_key_armor   TEXT NOT NULL,
+	key_id              TEXT NOT NULL,
+	created_at          TIMESTAMPTZ DEFAULT NOW()
+);

migrations/embed.go

@@ -0,0 +1,11 @@
+// Package migrations embeds the SQL schema files so artifactapi carries its own
+// schema and applies it at startup, with no externally mirrored copy to drift
+// out of sync.
+package migrations
+
+import "embed"
+
+// FS holds every numbered migration; lexical filename order is version order.
+//
+//go:embed *.sql
+var FS embed.FS

pkg/models/package_type.go

@@ -5,31 +5,37 @@ import "fmt"
 type PackageType string
 
 const (
-	PackageGeneric   PackageType = "generic"
-	PackageDocker    PackageType = "docker"
-	PackageHelm      PackageType = "helm"
-	PackagePyPI      PackageType = "pypi"
-	PackageNPM       PackageType = "npm"
-	PackageRPM       PackageType = "rpm"
-	PackageAlpine    PackageType = "alpine"
-	PackagePuppet    PackageType = "puppet"
-	PackageTerraform PackageType = "terraform"
-	PackageGoProxy   PackageType = "goproxy"
-	PackageGitHubRPM PackageType = "github_rpm"
+	PackageGeneric      PackageType = "generic"
+	PackageDocker       PackageType = "docker"
+	PackageHelm         PackageType = "helm"
+	PackagePyPI         PackageType = "pypi"
+	PackageNPM          PackageType = "npm"
+	PackageRPM          PackageType = "rpm"
+	PackageDeb          PackageType = "deb"
+	PackageAlpine       PackageType = "alpine"
+	PackagePuppet       PackageType = "puppet"
+	PackageTerraform    PackageType = "terraform"
+	PackageGoProxy      PackageType = "goproxy"
+	PackageGitHubRPM    PackageType = "github_rpm"
+	PackageGitHubDeb    PackageType = "github_deb"
+	PackageGitHubAlpine PackageType = "github_alpine"
 )
 
 var validPackageTypes = map[PackageType]bool{
-	PackageGeneric:   true,
-	PackageDocker:    true,
-	PackageHelm:      true,
-	PackagePyPI:      true,
-	PackageNPM:       true,
-	PackageRPM:       true,
-	PackageAlpine:    true,
-	PackagePuppet:    true,
-	PackageTerraform: true,
-	PackageGoProxy:   true,
-	PackageGitHubRPM: true,
+	PackageGeneric:      true,
+	PackageDocker:       true,
+	PackageHelm:         true,
+	PackagePyPI:         true,
+	PackageNPM:          true,
+	PackageRPM:          true,
+	PackageDeb:          true,
+	PackageAlpine:       true,
+	PackagePuppet:       true,
+	PackageTerraform:    true,
+	PackageGoProxy:      true,
+	PackageGitHubRPM:    true,
+	PackageGitHubDeb:    true,
+	PackageGitHubAlpine: true,
 }
 
 func (p PackageType) Valid() bool {

pkg/models/package_type_test.go

@@ -19,6 +19,8 @@ func TestPackageTypeValid(t *testing.T) {
 		models.PackageTerraform,
 		models.PackageGoProxy,
 		models.PackageGitHubRPM,
+		models.PackageGitHubDeb,
+		models.PackageGitHubAlpine,
 	}
 	for _, pt := range valid {
 		if !pt.Valid() {

pkg/models/remote.go

@@ -2,6 +2,7 @@ package models
 
 import (
 	"fmt"
+	"net/url"
 	"regexp"
 	"time"
 )
@@ -39,9 +40,17 @@ type Remote struct {
 	PackageType PackageType `json:"package_type"`
 	RepoType    RepoType    `json:"repo_type"`
 	BaseURL     string      `json:"base_url"`
-	Description string      `json:"description,omitempty"`
-	Username    string      `json:"-"`
-	Password    string      `json:"-"`
+	// Mirrorlist holds additional upstream mirror base URLs. The effective
+	// upstream pool is [base_url] + mirrorlist, load-balanced round-robin with
+	// failover by the proxy engine. Only valid on remote rpm/deb/apk repos.
+	Mirrorlist []string `json:"mirrorlist,omitempty"`
+	// MirrorStrategy selects how the proxy engine picks the starting upstream
+	// from the pool: round_robin (default/empty) rotates, least_conn favors the
+	// mirror with the fewest in-flight requests. Failover order is unchanged.
+	MirrorStrategy string `json:"mirror_strategy,omitempty"`
+	Description    string `json:"description,omitempty"`
+	Username       string `json:"-"`
+	Password       string `json:"-"`
 
 	ImmutableTTL int  `json:"immutable_ttl"`
 	MutableTTL   int  `json:"mutable_ttl"`
@@ -72,6 +81,74 @@ type Remote struct {
 	UpdatedAt time.Time `json:"updated_at"`
 }
 
+// Mirror balancing strategies for MirrorStrategy. An empty value is treated as
+// round_robin, so existing remotes keep their current behavior.
+const (
+	MirrorStrategyRoundRobin = "round_robin"
+	MirrorStrategyLeastConn  = "least_conn"
+)
+
+// mirrorlistPackageTypes are the package types for which a mirrorlist is
+// allowed: OS package repos (rpm, deb, apk/alpine) that fetch many small files
+// and benefit most from mirror load-balancing and failover.
+var mirrorlistPackageTypes = map[PackageType]bool{
+	PackageRPM:    true,
+	PackageDeb:    true,
+	PackageAlpine: true,
+}
+
+// UpstreamPool returns the ordered upstream base URLs for this remote: the
+// primary base_url first, followed by any mirrorlist entries. The proxy engine
+// load-balances round-robin across the pool and fails over between them.
+func (r Remote) UpstreamPool() []string {
+	pool := make([]string, 0, 1+len(r.Mirrorlist))
+	if r.BaseURL != "" {
+		pool = append(pool, r.BaseURL)
+	}
+	pool = append(pool, r.Mirrorlist...)
+	return pool
+}
+
+// ValidateMirrorlist enforces that a mirrorlist is only configured on remote
+// rpm/deb/apk repositories and that every entry is a parseable http/https URL.
+func (r *Remote) ValidateMirrorlist() error {
+	if len(r.Mirrorlist) == 0 {
+		return nil
+	}
+	if r.RepoType != RepoTypeRemote {
+		return fmt.Errorf("mirrorlist is only allowed on remote repositories")
+	}
+	if !mirrorlistPackageTypes[r.PackageType] {
+		return fmt.Errorf("mirrorlist is only allowed for rpm, deb and alpine package types, not %q", r.PackageType)
+	}
+	for _, u := range r.Mirrorlist {
+		parsed, err := url.ParseRequestURI(u)
+		if err != nil {
+			return fmt.Errorf("invalid mirrorlist url %q: %w", u, err)
+		}
+		if parsed.Scheme != "http" && parsed.Scheme != "https" {
+			return fmt.Errorf("mirrorlist url %q must be http or https", u)
+		}
+	}
+	return nil
+}
+
+// ValidateMirrorStrategy enforces that mirror_strategy is one of the allowed
+// values and that a non-default strategy (least_conn) is only set alongside a
+// non-empty mirrorlist, where balancing is meaningful. An empty strategy is
+// accepted and behaves as round_robin.
+func (r *Remote) ValidateMirrorStrategy() error {
+	switch r.MirrorStrategy {
+	case "", MirrorStrategyRoundRobin, MirrorStrategyLeastConn:
+	default:
+		return fmt.Errorf("invalid mirror_strategy %q: must be %q or %q", r.MirrorStrategy, MirrorStrategyRoundRobin, MirrorStrategyLeastConn)
+	}
+	if r.MirrorStrategy == MirrorStrategyLeastConn && len(r.Mirrorlist) == 0 {
+		return fmt.Errorf("mirror_strategy %q requires a non-empty mirrorlist", r.MirrorStrategy)
+	}
+	return nil
+}
+
 // ValidatePatterns ensures every configured regex compiles. Storing an
 // invalid pattern would otherwise be silently dropped at match time, which
 // for the blocklist is a fail-open: a mistyped deny rule becomes a no-op.

pkg/models/remote_test.go

@@ -1,6 +1,10 @@
 package models
 
-import "testing"
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
 
 func TestRemote_ValidatePatterns(t *testing.T) {
 	valid := &Remote{
@@ -17,3 +21,105 @@ func TestRemote_ValidatePatterns(t *testing.T) {
 		t.Fatal("expected error for invalid blocklist regex, got nil")
 	}
 }
+
+func TestRemoteMirrorlistJSON(t *testing.T) {
+	// base_url stays a plain string; mirrorlist round-trips as an array.
+	var r Remote
+	body := `{"name":"x","package_type":"rpm","repo_type":"remote","base_url":"https://a.example","mirrorlist":["https://b.example","https://c.example"]}`
+	if err := json.Unmarshal([]byte(body), &r); err != nil {
+		t.Fatal(err)
+	}
+	if r.BaseURL != "https://a.example" {
+		t.Errorf("BaseURL = %q, want https://a.example", r.BaseURL)
+	}
+	if len(r.Mirrorlist) != 2 || r.Mirrorlist[0] != "https://b.example" || r.Mirrorlist[1] != "https://c.example" {
+		t.Errorf("Mirrorlist = %v, want two entries", r.Mirrorlist)
+	}
+
+	out, err := json.Marshal(r)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(out), `"base_url":"https://a.example"`) {
+		t.Errorf("marshal lost base_url: %s", out)
+	}
+	if !strings.Contains(string(out), `"mirrorlist":["https://b.example","https://c.example"]`) {
+		t.Errorf("marshal lost mirrorlist: %s", out)
+	}
+}
+
+func TestRemoteMirrorlistOmitempty(t *testing.T) {
+	out, err := json.Marshal(Remote{Name: "x", PackageType: PackageRPM, RepoType: RepoTypeRemote, BaseURL: "https://a.example"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(string(out), "mirrorlist") {
+		t.Errorf("empty mirrorlist should be omitted: %s", out)
+	}
+}
+
+func TestUpstreamPool(t *testing.T) {
+	// base_url first, then mirrorlist.
+	r := Remote{BaseURL: "https://a.example", Mirrorlist: []string{"https://b.example", "https://c.example"}}
+	pool := r.UpstreamPool()
+	want := []string{"https://a.example", "https://b.example", "https://c.example"}
+	if strings.Join(pool, ",") != strings.Join(want, ",") {
+		t.Errorf("UpstreamPool = %v, want %v", pool, want)
+	}
+
+	// No mirrorlist ⇒ pool is just [base_url].
+	solo := Remote{BaseURL: "https://a.example"}
+	if got := solo.UpstreamPool(); len(got) != 1 || got[0] != "https://a.example" {
+		t.Errorf("solo UpstreamPool = %v, want [base_url]", got)
+	}
+}
+
+func TestValidateMirrorStrategy(t *testing.T) {
+	ml := []string{"https://m.example"}
+	cases := []struct {
+		name    string
+		remote  Remote
+		wantErr bool
+	}{
+		{"empty defaults ok", Remote{Mirrorlist: ml}, false},
+		{"explicit round_robin ok", Remote{MirrorStrategy: MirrorStrategyRoundRobin, Mirrorlist: ml}, false},
+		{"round_robin without mirrorlist ok", Remote{MirrorStrategy: MirrorStrategyRoundRobin}, false},
+		{"least_conn with mirrorlist ok", Remote{MirrorStrategy: MirrorStrategyLeastConn, Mirrorlist: ml}, false},
+		{"least_conn without mirrorlist rejected", Remote{MirrorStrategy: MirrorStrategyLeastConn}, true},
+		{"unknown strategy rejected", Remote{MirrorStrategy: "random", Mirrorlist: ml}, true},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			err := tc.remote.ValidateMirrorStrategy()
+			if (err != nil) != tc.wantErr {
+				t.Errorf("ValidateMirrorStrategy() err = %v, wantErr = %v", err, tc.wantErr)
+			}
+		})
+	}
+}
+
+func TestValidateMirrorlist(t *testing.T) {
+	cases := []struct {
+		name    string
+		remote  Remote
+		wantErr bool
+	}{
+		{"empty is ok on anything", Remote{RepoType: RepoTypeRemote, PackageType: PackageGeneric}, false},
+		{"rpm remote ok", Remote{RepoType: RepoTypeRemote, PackageType: PackageRPM, Mirrorlist: []string{"https://m.example"}}, false},
+		{"deb remote ok", Remote{RepoType: RepoTypeRemote, PackageType: PackageDeb, Mirrorlist: []string{"http://m.example"}}, false},
+		{"alpine remote ok", Remote{RepoType: RepoTypeRemote, PackageType: PackageAlpine, Mirrorlist: []string{"https://m.example"}}, false},
+		{"generic remote rejected", Remote{RepoType: RepoTypeRemote, PackageType: PackageGeneric, Mirrorlist: []string{"https://m.example"}}, true},
+		{"docker remote rejected", Remote{RepoType: RepoTypeRemote, PackageType: PackageDocker, Mirrorlist: []string{"https://m.example"}}, true},
+		{"local rpm rejected", Remote{RepoType: RepoTypeLocal, PackageType: PackageRPM, Mirrorlist: []string{"https://m.example"}}, true},
+		{"bad scheme rejected", Remote{RepoType: RepoTypeRemote, PackageType: PackageRPM, Mirrorlist: []string{"ftp://m.example"}}, true},
+		{"unparseable rejected", Remote{RepoType: RepoTypeRemote, PackageType: PackageRPM, Mirrorlist: []string{"://nope"}}, true},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			err := tc.remote.ValidateMirrorlist()
+			if (err != nil) != tc.wantErr {
+				t.Errorf("ValidateMirrorlist() err = %v, wantErr = %v", err, tc.wantErr)
+			}
+		})
+	}
+}

scripts/docker-e2e.sh

@@ -17,8 +17,8 @@ cleanup() {
 }
 trap cleanup EXIT
 
-echo "==> building and starting stack (postgres, redis, minio, mockupstream, artifactapi)"
-"${COMPOSE[@]}" up -d --build postgres redis minio mockupstream artifactapi
+echo "==> building and starting stack (postgres, redis, minio, mockupstream(s), artifactapi)"
+"${COMPOSE[@]}" up -d --build postgres redis minio mockupstream mockupstreama mockupstreamb artifactapi
 
 echo "==> waiting for artifactapi health at ${API_URL}"
 for i in $(seq 1 60); do
@@ -34,7 +34,17 @@ for i in $(seq 1 60); do
   sleep 1
 done
 
-echo "==> running dockerised e2e suite"
+# Resolve the compose network the artifactapi container is attached to, so the
+# real-package-manager test can launch a stock distro container on the same
+# network and reach artifactapi by service name.
+API_CID="$("${COMPOSE[@]}" ps -q artifactapi)"
+COMPOSE_NETWORK="$(docker inspect -f '{{range $k,$_ := .NetworkSettings.Networks}}{{$k}}{{end}}' "${API_CID}" 2>/dev/null || true)"
+
+echo "==> running dockerised e2e suite (compose network: ${COMPOSE_NETWORK:-unknown})"
 ARTIFACTAPI_URL="${API_URL}" \
 MOCK_UPSTREAM_INTERNAL="${MOCK_UPSTREAM_INTERNAL:-http://mockupstream}" \
+MOCK_UPSTREAM_A_INTERNAL="${MOCK_UPSTREAM_A_INTERNAL:-http://mockupstreama}" \
+MOCK_UPSTREAM_B_INTERNAL="${MOCK_UPSTREAM_B_INTERNAL:-http://mockupstreamb}" \
+ARTIFACTAPI_INTERNAL="${ARTIFACTAPI_INTERNAL:-http://artifactapi:8000}" \
+COMPOSE_NETWORK="${COMPOSE_NETWORK}" \
   go test -tags=dockere2e -count=1 -timeout=10m -v ./e2e-docker/...

ui/src/components/UsageInstructions.tsx

@@ -176,14 +176,44 @@ helm install <release> ${name}/<chart>`,
       ];
 
     case 'alpine':
-      return [
-        {
-          title: 'Add the APK repository',
-          language: 'bash',
-          code: `echo '${proxy}/' | sudo tee -a /etc/apk/repositories
+      return isLocal
+        ? [
+            {
+              title: 'Add the apk repo (real apk repo, APKINDEX auto-generated)',
+              language: 'bash',
+              code: `echo '${url}/api/v1/local/${name}' | sudo tee -a /etc/apk/repositories
+sudo apk update --allow-untrusted
+sudo apk add --allow-untrusted <package>`,
+              note: `Served unsigned (parity with the rpm repo's gpgcheck=0) — use --allow-untrusted, or install a signing key. apk fetches <arch>/APKINDEX.tar.gz under this base.`,
+            },
+            {
+              title: 'Publish a .apk (index regenerates automatically)',
+              language: 'bash',
+              code: `curl -fsSL --upload-file ./mypkg-1.0-r0.apk \\
+  ${url}/api/v2/remotes/${name}/files/x86_64/mypkg-1.0-r0.apk`,
+              note: 'Upload each package at <arch>/<name>-<version>.apk — apk reconstructs that exact path from the index (APKINDEX carries no filename), so a mismatched path will 404 on install.',
+            },
+          ]
+        : [
+            {
+              title: 'Add the APK repository',
+              language: 'bash',
+              code: `echo '${proxy}/' | sudo tee -a /etc/apk/repositories
 sudo apk update
 sudo apk add <package>`,
-          note: 'If the index is unsigned over the proxy, add --allow-untrusted or install the signing key into /etc/apk/keys.',
+              note: 'If the index is unsigned over the proxy, add --allow-untrusted or install the signing key into /etc/apk/keys.',
+            },
+          ];
+
+    case 'github_alpine':
+      return [
+        {
+          title: 'Add the apk repo (metadata-only, from GitHub releases)',
+          language: 'bash',
+          code: `echo '${proxy}' | sudo tee -a /etc/apk/repositories
+sudo apk update --allow-untrusted
+sudo apk add --allow-untrusted <package>`,
+          note: "The per-arch APKINDEX is synthesized from the configured GitHub repo's release .apk assets; package downloads are redirected to the backing releases remote. Served unsigned, so --allow-untrusted.",
         },
       ];
 
@@ -208,6 +238,47 @@ go mod download`,
         },
       ];
 
+    case 'deb':
+      return isLocal
+        ? [
+            {
+              title: 'Add the apt repo (real apt repo, flat — Packages/Release auto-generated)',
+              language: 'bash',
+              code: `echo 'deb [trusted=yes] ${url}/api/v1/local/${name}/ ./' | sudo tee /etc/apt/sources.list.d/${name}.list
+sudo apt-get update
+sudo apt-get install <package>`,
+              note: '[trusted=yes]: artifactapi serves the flat repo unsigned (matches the rpm repo\'s gpgcheck=0). The `./` is the flat-repo suite — apt fetches Packages/Release from the repo root.',
+            },
+            {
+              title: 'Publish a .deb (index regenerates automatically)',
+              language: 'bash',
+              code: `curl -fsSL --upload-file ./my-package_1.0_amd64.deb \\
+  ${url}/api/v2/remotes/${name}/files/my-package_1.0_amd64.deb`,
+            },
+          ]
+        : [
+            {
+              title: 'Add the apt repo (caching proxy)',
+              language: 'bash',
+              code: `echo 'deb ${proxy} <suite> <component>' | sudo tee /etc/apt/sources.list.d/${name}.list
+sudo apt-get update
+sudo apt-get install <package>`,
+              note: "Signatures are verified against the upstream mirror's real signed Release through the proxy (no [trusted=yes] needed). Example suite/component: bookworm main.",
+            },
+          ];
+
+    case 'github_deb':
+      return [
+        {
+          title: 'Add the apt repo (metadata-only, from GitHub releases)',
+          language: 'bash',
+          code: `echo 'deb [trusted=yes] ${proxy}/ ./' | sudo tee /etc/apt/sources.list.d/${name}.list
+sudo apt-get update
+sudo apt-get install <package>`,
+          note: "The apt index is synthesized from the configured GitHub repo's release .deb assets; package downloads are redirected to the backing releases remote. Served unsigned, so [trusted=yes].",
+        },
+      ];
+
     case 'generic':
     default:
       return [