feat: serve plugins with dependencies at the commit pinned by the Go module proxy by mmatur · Pull Request #83 · traefik/plugin-service

mmatur · 2026-10-26T09:24:53Z

Plugins with dependencies are served from the GitHub zipball of their tag. If a tag moves after publication, the same version serves different code and no longer matches its recorded hash.

The download now reads the commit pinned by proxy.golang.org (/@v/<version>.info, Origin.Hash):

the tag still points at that commit: download the tag, as today. An annotated tag zipball is named after the tag object, so switching to the commit would change the bytes of every annotated version.
the tag moved or was deleted: download the pinned commit, and log it.
no Origin (version unknown to the proxy, or published before Origin existed): download the tag.
proxy error or timeout: download the tag, as before. GitHub error: fail the download.

The pinned commit is cached in memory per version. An empty --pin-proxy-url turns pinning off.

The tag check uses a conditional request on the pinned commit. A 304 does not count against the GitHub rate limit, so stable tags cost no extra quota.

Hashes that no longer match the bytes served (moved annotated tags, hashes recorded after a tag moved) are realigned with piceus realign --only on the -next catalog.

New flag --pin-proxy-url (default https://proxy.golang.org).

Tested locally against GitHub and proxy.golang.org with maxlerebourg/crowdsec-bouncer-traefik-plugin:

v1.1.5 (moved tag) serves a2fe60c and matches its recorded hash again
v1.8.0 and v1.8.1 (annotated tags) serve the same bytes as plugins.traefik.io

Part of traefik/hub-issues#3124

Copilot

🟡 Changes recommended

Mutable-tag resolution still permits unpinned downloads, and moved annotated tags can produce archives incompatible with recorded hashes.

2 open issues

What changed in this PR

This PR uses Go module proxy metadata to select GitHub archives for plugins with dependencies, aiming to preserve published code when tags move or disappear.

Changes:

Adds proxy-pinned commit lookup and tag verification, retaining tag downloads when unchanged.
Introduces --pin-proxy-url, defaulting to https://proxy.golang.org.
Adds reference-selection tests and updates handler construction.

File	Description
`pkg/handlers/pinned.go`	Resolves archive references using proxy metadata and GitHub tag checks.
`pkg/handlers/pinned_test.go`	Tests stable, moved, deleted, unknown, and error cases.
`pkg/handlers/module.go`	Uses the resolved reference for archive downloads.
`pkg/handlers/handlers.go`	Adds pinning configuration and an HTTP client with a timeout.
`pkg/handlers/handlers_test.go`	Updates constructor calls.
`pkg/handlers/blacklist_test.go`	Updates constructor calls.
`go.mod`	Promotes `golang.org/x/mod` to a direct dependency.
`cmd/serve/serve.go`	Passes the pinning proxy URL to handlers.
`cmd/serve/config.go`	Adds the pinning proxy configuration field.
`cmd/serve/command.go`	Registers and reads the new proxy flag.

_{Review effort: Balanced}

darkweaver87 · 2026-10-26T14:36:44Z

+// It is the tag while the tag still points at the commit pinned by the Go module proxy at publication,
+// and the pinned commit once the tag moved or was deleted.
+// Requesting the tag keeps the archive bytes: the zipball of an annotated tag is named after the tag object, not the commit.
+// The pinned commit of a moved annotated tag cannot give those bytes back, its hash is realigned instead.


Where does this realign happen? Not in this PR. If it's piceus realign --only, please say so here. Otherwise moved annotated tags fail validate as soon as this is deployed.

It's piceus realign --only <module>@<version> (traefik/piceus#163), run on the -next catalog and reviewed one by one before the switch. The comment now says so.

darkweaver87 · 2026-10-26T14:36:44Z

+		return version, nil
+	}
+
+	if err != nil {


The description says a proxy error fails the download, but here we serve the tag. Please update the description.

Right, it changed after the first review. Description updated.

darkweaver87 · 2026-10-26T14:36:44Z

+			Str("tag_commit", sha).Str("pinned_commit", pinned).
+			Msg("Tag moved after publication, serving the pinned commit")
+
+		return pinned, nil


If a version was first downloaded after its tag moved, its recorded hash is the moved one, and this now breaks it. How many versions are in that case?

10 of the 2,159 public versions. They will be realigned with piceus realign --only on -next before the switch, which changes the code served for them. We'll test each one there and tell the authors.

darkweaver87 · 2026-10-26T14:36:44Z

+		return version, nil
+	}
+
+	pinned, err := h.pinnedCommit(ctx, moduleName, version)


nit: the pinned commit never changes, but we look it up on every download. Could we store it? It will also reduce number of proxy calls.

Done, cached in memory per module@version. Only successful lookups are cached, as the proxy may learn a version later.

darkweaver87 · 2026-10-26T14:36:44Z

+	"github.com/stretchr/testify/require"
+)
+
+func TestArchiveRef(t *testing.T) {


nit: missing cases for a GitHub 404 and a proxy 410.

Added both.

darkweaver87 · 2026-10-26T14:36:44Z

 			Required: true,
 		},
+		&cli.StringFlag{
+			Name:    flagPinProxyURL,


Please add --pin-proxy-url to the readme.

…module proxy When a tag moved after publication, download the GitHub zipball at the commit proxy.golang.org pinned for that version instead of the tag. Part of traefik/hub-issues#3124, closes traefik/infra#12142.

Co-authored-by: aikido-pr-checks[bot] <169896070+aikido-pr-checks[bot]@users.noreply.github.com>

darkweaver87

LGTM

aikido-pr-checks Bot reviewed Oct 26, 2026

View reviewed changes

Comment thread pkg/handlers/pinned.go Resolved

aikido-pr-checks Bot reviewed Oct 26, 2026

View reviewed changes

Comment thread pkg/handlers/pinned.go Resolved

mmatur added kind/enhancement a new or improved feature. status/2-needs-review labels Oct 26, 2026

mmatur requested a balanced review from Copilot October 26, 2026 13:47

Copilot started reviewing on behalf of mmatur October 26, 2026 13:48

View session

Copilot AI reviewed Oct 26, 2026

View reviewed changes

Comment thread pkg/handlers/pinned.go Resolved

Comment thread pkg/handlers/pinned.go Resolved

darkweaver87 reviewed Oct 26, 2026

View reviewed changes

mmatur and others added 5 commits October 26, 2026 19:23

Update pkg/handlers/pinned.go

46da4c8

Co-authored-by: aikido-pr-checks[bot] <169896070+aikido-pr-checks[bot]@users.noreply.github.com>

fix: name the archive ref cases instead of falling through

ac8eadf

fix: serve the tag when the Go module proxy does not answer

39bba2d

fix: cache the pinned commit, document --pin-proxy-url

801d327

mmatur force-pushed the feat/serve-pinned-commit branch from 7ce8bdc to 801d327 Compare October 26, 2026 18:23

darkweaver87 approved these changes Oct 27, 2026

View reviewed changes

mmatur added status/3-needs-merge and removed status/2-needs-review labels Oct 27, 2026

traefiker merged commit 751a1de into traefik:master Oct 27, 2026
6 checks passed

traefiker removed the status/3-needs-merge label Oct 27, 2026

mmatur deleted the feat/serve-pinned-commit branch October 27, 2026 08:10

Conversation

mmatur commented Oct 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

darkweaver87 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

mmatur commented Oct 26, 2026 •

edited

Loading