From 203f05855ae11c6ad5e1dbd0ff3eb2625ee26b6f Mon Sep 17 00:00:00 2001
From: Joongi Kim <me@daybreaker.info>
Date: Mon, 27 Jul 2026 03:28:50 +0000
Subject: [PATCH] =?UTF-8?q?feat:=20variant-proxy=20=E2=80=94=20server-comp?=
 =?UTF-8?q?uted=20variant=20index=20(Phase=20B)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

cmd/variant-proxy is a stateless reverse proxy in front of any V2
registry that serves GET /v2/<name>/_variants/<version> by running the
same BuildIndex tag-scan used by `index update`, so plain `docker push`
of labeled images is sufficient — no client-side index maintenance.
Everything else passes through unchanged (docker push/pull work
through the proxy). Errors use the OCI distribution error envelope;
the served index advertises the proxy authority as its repository.

Client side: FetchIndex now tries the _variants extension endpoint
first and falls back to the "<version>-variants" tag artifact, with a
size cap on the accepted document.

e2e: new proxy section — variants pushed only via plain docker push
through the proxy (asserting no index artifact tag exists upstream),
endpoint content and 404 behavior, and variant pull via the proxy
selecting cu128/null per mocked hardware.

Claude-Session: https://claude.ai/code/session_01D383U8kkQkJc1yzyC5H5Nk
---
 cmd/variant-proxy/main.go | 112 ++++++++++++++++++++++++++++++++++++++
 e2e/run.sh                |  43 ++++++++++++++-
 pkg/oci/index.go          |  42 +++++++++++++-
 3 files changed, 194 insertions(+), 3 deletions(-)
 create mode 100644 cmd/variant-proxy/main.go

diff --git a/cmd/variant-proxy/main.go b/cmd/variant-proxy/main.go
new file mode 100644
index 0000000..94ad67b
--- /dev/null
+++ b/cmd/variant-proxy/main.go
@@ -0,0 +1,112 @@
+// variant-proxy is the Phase B registry-side component (DESIGN.md §6): a
+// stateless reverse proxy in front of any V2 registry that additionally
+// serves computed variant indexes at
+//
+//	GET /v2/<name>/_variants/<version>
+//
+// The index is built on demand by scanning the upstream repository's
+// "<version>-<label>" tags and reading each image's config labels, so plain
+// `docker push` of labeled images is sufficient — no client-side index
+// maintenance. All other paths pass through to the upstream registry
+// unchanged.
+package main
+
+import (
+	"encoding/json"
+	"flag"
+	"fmt"
+	"log"
+	"net/http"
+	"net/http/httputil"
+	"net/url"
+	"os"
+	"regexp"
+
+	"github.com/achimnol/docker-variant/pkg/oci"
+	"github.com/achimnol/docker-variant/pkg/variant"
+)
+
+var variantPathRe = regexp.MustCompile(`^/v2/(.+)/_variants/([^/]+)$`)
+
+func main() {
+	var (
+		listen        = flag.String("listen", ":5599", "address to listen on")
+		upstream      = flag.String("upstream", "", "host:port of the backing registry (required)")
+		upstreamHTTPS = flag.Bool("upstream-https", false, "reach the upstream via HTTPS (default: plain HTTP)")
+	)
+	flag.Parse()
+	if *upstream == "" {
+		fmt.Fprintln(os.Stderr, "variant-proxy: --upstream is required")
+		os.Exit(2)
+	}
+	scheme := "http"
+	if *upstreamHTTPS {
+		scheme = "https"
+	}
+	upstreamURL := &url.URL{Scheme: scheme, Host: *upstream}
+	client, err := oci.NewClient(!*upstreamHTTPS)
+	if err != nil {
+		log.Fatalf("variant-proxy: %v", err)
+	}
+
+	proxy := httputil.NewSingleHostReverseProxy(upstreamURL)
+	baseDirector := proxy.Director
+	proxy.Director = func(req *http.Request) {
+		baseDirector(req)
+		req.Host = *upstream
+	}
+
+	handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if m := variantPathRe.FindStringSubmatch(r.URL.Path); m != nil && (r.Method == http.MethodGet || r.Method == http.MethodHead) {
+			serveVariants(client, *upstream, m[1], m[2], w, r)
+			return
+		}
+		proxy.ServeHTTP(w, r)
+	})
+
+	log.Printf("variant-proxy: listening on %s, upstream %s", *listen, upstreamURL)
+	log.Fatal(http.ListenAndServe(*listen, handler))
+}
+
+func serveVariants(client *oci.Client, upstream, name, version string, w http.ResponseWriter, r *http.Request) {
+	ref := oci.Ref{Registry: upstream, Repository: name}
+	ix, warnings, err := client.BuildIndex(r.Context(), ref, version)
+	for _, warning := range warnings {
+		log.Printf("variant-proxy: %s@%s: %s", name, version, warning)
+	}
+	if err != nil {
+		log.Printf("variant-proxy: building index for %s@%s: %v", name, version, err)
+		writeOCIError(w, http.StatusBadGateway, "UNAVAILABLE", "failed to build variant index from upstream")
+		return
+	}
+	if len(ix.Variants) == 0 {
+		writeOCIError(w, http.StatusNotFound, "MANIFEST_UNKNOWN", "no variants found for this version")
+		return
+	}
+	// Advertise the proxy's own authority as the repository so clients pull
+	// through the proxy (keeping digest-addressed pulls on the same host
+	// they queried).
+	ix.Repository = r.Host + "/" + name
+	data, err := ix.Marshal()
+	if err != nil {
+		writeOCIError(w, http.StatusInternalServerError, "UNKNOWN", err.Error())
+		return
+	}
+	w.Header().Set("Content-Type", variant.IndexArtifactType)
+	if r.Method == http.MethodHead {
+		w.WriteHeader(http.StatusOK)
+		return
+	}
+	w.Write(append(data, '\n'))
+	log.Printf("variant-proxy: served index %s@%s (%d variants)", name, version, len(ix.Variants))
+}
+
+// writeOCIError responds in the OCI distribution error envelope so registry
+// clients show something sensible.
+func writeOCIError(w http.ResponseWriter, status int, code, message string) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	json.NewEncoder(w).Encode(map[string]any{
+		"errors": []map[string]string{{"code": code, "message": message}},
+	})
+}
diff --git a/e2e/run.sh b/e2e/run.sh
index ea6548b..5e6f0ea 100755
--- a/e2e/run.sh
+++ b/e2e/run.sh
@@ -15,11 +15,18 @@ CONTAINER="variant-e2e-registry-${PORT}"
 
 fail() { echo "FAIL: $*" >&2; exit 1; }
 
+PROXY_PORT="${E2E_PROXY_PORT:-5592}"
+PROXY="127.0.0.1:${PROXY_PORT}"
+PROXY_REPO="${PROXY}/e2e/proxied"
+PROXY_PID=""
+
 cleanup() {
+    [ -n "${PROXY_PID}" ] && kill "${PROXY_PID}" >/dev/null 2>&1 || true
     docker rm -f "${CONTAINER}" >/dev/null 2>&1 || true
     docker rmi -f \
         "${REPO}:1.0.0" "${REPO}:1.0.0-cu128" "${REPO}:1.0.0-cu126" "${REPO}:1.0.0-null" \
-        "${PLAIN_REPO}:1.0.0" >/dev/null 2>&1 || true
+        "${PLAIN_REPO}:1.0.0" \
+        "${PROXY_REPO}:1.0.0" "${PROXY_REPO}:1.0.0-cu128" "${PROXY_REPO}:1.0.0-null" >/dev/null 2>&1 || true
     rm -rf "${WORKDIR}"
 }
 trap cleanup EXIT
@@ -117,4 +124,38 @@ if "${BIN}" variant pull "${PLAIN_REPO}:1.0.0" --no-fallback >/dev/null 2>&1; th
     fail "--no-fallback should have failed"
 fi
 
+echo "==> proxy: server-computed index over plain docker pushes"
+go build -o "${WORKDIR}/variant-proxy" ./cmd/variant-proxy
+"${WORKDIR}/variant-proxy" --listen "127.0.0.1:${PROXY_PORT}" --upstream "${REGISTRY}" \
+    > "${WORKDIR}/proxy.log" 2>&1 &
+PROXY_PID=$!
+for _ in $(seq 1 30); do
+    curl -fsS "http://${PROXY}/v2/" >/dev/null 2>&1 && break
+    sleep 0.5
+done
+
+# Push variants THROUGH the proxy with plain `docker push` only — no index
+# artifact is ever created for this repository.
+docker tag "${REPO}:1.0.0-cu128" "${PROXY_REPO}:1.0.0-cu128"
+docker tag "${REPO}:1.0.0-null"  "${PROXY_REPO}:1.0.0-null"
+docker push -q "${PROXY_REPO}:1.0.0-cu128" >/dev/null
+docker push -q "${PROXY_REPO}:1.0.0-null"  >/dev/null
+curl -fsS "http://${REGISTRY}/v2/e2e/proxied/tags/list" | grep -q '1.0.0-variants' \
+    && fail "proxied repo unexpectedly has an index artifact tag"
+
+echo "    endpoint serves computed index"
+curl -fsS "http://${PROXY}/v2/e2e/proxied/_variants/1.0.0" | grep -q '"cu128"' \
+    || fail "_variants endpoint missing cu128"
+curl -sS -o /dev/null -w '%{http_code}' "http://${PROXY}/v2/e2e/proxied/_variants/9.9.9" \
+    | grep -q 404 || fail "_variants for unknown version should be 404"
+
+proxied_pull_label() {
+    docker rmi -f "${PROXY_REPO}:1.0.0" >/dev/null 2>&1 || true
+    "${BIN}" variant pull "${PROXY_REPO}:1.0.0" --properties-file "$1" >/dev/null
+    docker image inspect --format '{{ index .Config.Labels "dev.pep817.variant-label" }}' "${PROXY_REPO}:1.0.0"
+}
+[ "$(proxied_pull_label "${WORKDIR}/gpu128.json")" = cu128 ] || fail "proxied pull (gpu) should select cu128"
+[ "$(proxied_pull_label "${WORKDIR}/cpu.json")" = null ] || fail "proxied pull (cpu) should select null"
+echo "    variant pull via proxy works without any index artifact"
+
 echo "PASS"
diff --git a/pkg/oci/index.go b/pkg/oci/index.go
index 1c327bd..82f4bdc 100644
--- a/pkg/oci/index.go
+++ b/pkg/oci/index.go
@@ -5,6 +5,9 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"io"
+	"net/http"
+	"net/url"
 	"sort"
 
 	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
@@ -20,9 +23,14 @@ import (
 // requested base version.
 var ErrNoIndex = errors.New("no variant index found")
 
-// FetchIndex retrieves and parses the variant index artifact for
-// (repository, version) via the "<version>-variants" tag.
+// FetchIndex retrieves the variant index for (repository, version): first
+// via the "/v2/<name>/_variants/<version>" extension endpoint (served by
+// variant-proxy or a native registry implementation), then falling back to
+// the "<version>-variants" tag artifact.
 func (c *Client) FetchIndex(ctx context.Context, ref Ref, version string) (*variant.Index, error) {
+	if ix, err := c.fetchIndexExtension(ctx, ref, version); err == nil {
+		return ix, nil
+	}
 	repo, err := c.Repo(ref)
 	if err != nil {
 		return nil, err
@@ -30,6 +38,36 @@ func (c *Client) FetchIndex(ctx context.Context, ref Ref, version string) (*vari
 	return FetchIndexFrom(ctx, repo, version)
 }
 
+// maxIndexSize bounds the accepted index document size (defense against a
+// misbehaving server).
+const maxIndexSize = 4 << 20
+
+// fetchIndexExtension queries the _variants extension endpoint.
+func (c *Client) fetchIndexExtension(ctx context.Context, ref Ref, version string) (*variant.Index, error) {
+	scheme := "https"
+	if c.PlainHTTP || isLoopback(ref.Registry) {
+		scheme = "http"
+	}
+	u := fmt.Sprintf("%s://%s/v2/%s/_variants/%s", scheme, ref.Registry, ref.Repository, url.PathEscape(version))
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, u, nil)
+	if err != nil {
+		return nil, err
+	}
+	resp, err := c.authClient.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("GET %s: %s", u, resp.Status)
+	}
+	data, err := io.ReadAll(io.LimitReader(resp.Body, maxIndexSize))
+	if err != nil {
+		return nil, err
+	}
+	return variant.ParseIndex(data)
+}
+
 // ReadOnlyTarget is the storage interface FetchIndexFrom needs: tag
 // resolution plus content fetch (satisfied by *remote.Repository and the
 // in-memory stores used in tests).