handler

package
v0.10.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 20, 2026 License: GPL-3.0 Imports: 62 Imported by: 0

Documentation

Overview

Package handler provides HTTP protocol handlers for package manager proxying.

Index

Constants

View Source 
const (

	// PyPIMetadataSuffix is the PEP 658 core-metadata sidecar suffix that pip
	// appends to a distribution URL when the index advertises core metadata.
	// A sidecar resolves to the same name and version as the distribution it
	// describes, so it is cached alongside it; consumers that expect an openable
	// archive must skip these.
	PyPIMetadataSuffix = ".metadata"
)

Variables

View Source 
var (
	ErrHostedUnsupported     = errors.New("pushing packages is not supported for this ecosystem")
	ErrHostedInvalidName     = errors.New("invalid package name or version")
	ErrHostedVersionNotFound = errors.New("no pushed artifacts for this version")

	// ErrHostedArtifactUnavailable and ErrHostedArtifactMissing report a
	// pushed artifact the cache can't serve. They stop the caller from
	// fetching the upstream copy, which would replace the pushed one.
	ErrHostedArtifactUnavailable = errors.New("pushed artifact is stored but can't be read")
	ErrHostedArtifactMissing     = errors.New("pushed artifact is no longer stored")
)
View Source 
var (
	ErrHostedInvalidArchive   = errors.New("archive has no readable package manifest")
	ErrHostedManifestMismatch = errors.New("package manifest does not match the pushed name and version")
)
View Source 
var ErrArtifactBlocked = errors.New("artifact blocked by security scan")

ErrArtifactBlocked indicates a pre-cache security scan blocked the artifact.

View Source 
var ErrArtifactDigestMismatch = errors.New("artifact digest mismatch")

ErrArtifactDigestMismatch indicates that fetched bytes did not match the checksum the upstream declared and were not recorded in the cache database.

View Source 
var ErrMetadataTooLarge = errors.New("metadata response exceeds size limit")

ErrMetadataTooLarge is returned when upstream metadata exceeds the configured limit.

View Source 
var ErrPackageNotFound = errors.New("package not found")

ErrPackageNotFound indicates the requested package metadata is not available through the proxy or upstream registry.

View Source 
var ErrUpstreamNotFound = fmt.Errorf("upstream: %w", fetch.ErrNotFound)

ErrUpstreamNotFound indicates the upstream returned 404.

View Source 
var ErrVersionDenied = errors.New("package version blocked by denylist")

ErrVersionDenied indicates an operator explicitly denied this package version.

View Source 
var ErrVersionNotFound = errors.New("version not found")

ErrVersionNotFound indicates the requested version is not available through the proxy, including when cooldown or other filtering removed it.

Functions

func DetachUpstreamFetch added in v0.10.0 

func DetachUpstreamFetch(ctx context.Context) context.Context

DetachUpstreamFetch marks ctx so that an artifact fetch started under it runs to completion even when ctx is cancelled. The server sets it on client requests: a client that gives up on a slow cache miss (pacman aborts after 10 s without data) would otherwise cancel the fetch, and every retry would start again from zero, so a large artifact never reaches the cache. The fetch stays bounded by the artifact HTTP client's timeout, and at most maxDetachedFetches run detached at once. Mirror jobs leave it unset so cancelling a job still aborts its fetches.

func HostedSupported added in v0.10.0 

func HostedSupported(ecosystem string) bool

HostedSupported reports whether packages can be pushed for ecosystem.

func JSONError 

func JSONError(w http.ResponseWriter, status int, message string)

JSONError writes a JSON error response.

func RegisterHomebrewArtifacts added in v0.8.0 

func RegisterHomebrewArtifacts(container *ContainerHandler, artifactUpstream string)

RegisterHomebrewArtifacts routes homebrew/core OCI requests to its configured registry and blocks other homebrew repositories from reaching the default OCI registry.

func ServeArtifact 

func ServeArtifact(w http.ResponseWriter, result *CacheResult)

ServeArtifact writes a CacheResult to an HTTP response.

func ServeArtifactRequest added in v0.9.1 

func ServeArtifactRequest(w http.ResponseWriter, r *http.Request, result *CacheResult)

ServeArtifactRequest writes a CacheResult to an HTTP response using request headers such as Range and If-Range.

Types

type APKHandler added in v0.8.0 

type APKHandler struct {
	// contains filtered or unexported fields
}

APKHandler handles Alpine APK repository protocol requests. Each configured upstream repository is mounted at /apk/{repository}/ and the remaining path mirrors the upstream layout ({release}/{repo}/{arch}/{file}).

Repository indexes (v2 APKINDEX.tar.gz, v3 Packages.adb) and detached signatures are served byte-for-byte unchanged through the metadata cache so apk signature verification keeps working. Package files are cached in the shared artifact cache and stay available when the upstream is unreachable.

func NewAPKHandler added in v0.8.0 

func NewAPKHandler(proxy *Proxy, proxyURL string, repositories map[string]string) *APKHandler

NewAPKHandler creates an Alpine APK repository protocol handler. When repositories is empty, a single repository named "alpine" pointing at the official Alpine mirror is used.

func (*APKHandler) Routes added in v0.8.0 

func (h *APKHandler) Routes() http.Handler

Routes returns the HTTP handler for APK requests. Mount this at /apk on your router.

type ArchHandler added in v0.10.0 

type ArchHandler struct {
	// contains filtered or unexported fields
}

ArchHandler serves pacman repositories at /arch/{repository}/. The rest of the path goes to the mirror unchanged, so the Arch Linux ARM layout works too. Databases are served byte for byte through the metadata cache, packages and their signatures through the artifact cache.

func NewArchHandler added in v0.10.0 

func NewArchHandler(proxy *Proxy, proxyURL string, repositories map[string]string) *ArchHandler

NewArchHandler creates an Arch Linux handler. Without repositories it serves the official GeoIP mirror as "archlinux".

func (*ArchHandler) Routes added in v0.10.0 

func (h *ArchHandler) Routes() http.Handler

Routes returns the HTTP handler for pacman requests. Mount this at /arch on your router.

type CRANHandler 

type CRANHandler struct {
	// contains filtered or unexported fields
}

CRANHandler handles CRAN (R) registry protocol requests.

func NewCRANHandler 

func NewCRANHandler(proxy *Proxy, proxyURL string) *CRANHandler

NewCRANHandler creates a new CRAN protocol handler.

func NewCRANHandlerWithUpstream added in v0.8.0 

func NewCRANHandlerWithUpstream(proxy *Proxy, proxyURL, upstreamURL string) *CRANHandler

NewCRANHandlerWithUpstream creates a CRAN handler with a custom upstream.

func (*CRANHandler) Routes 

func (h *CRANHandler) Routes() http.Handler

Routes returns the HTTP handler for CRAN requests.

type CacheResult 

type CacheResult struct {
	Reader      io.ReadCloser
	RedirectURL string
	Artifact    artifacts.Artifact
	Cached      bool
	// contains filtered or unexported fields
}

CacheResult contains information about a cached or fetched artifact.

type CargoConfig 

type CargoConfig struct {
	DL  string `json:"dl"`
	API string `json:"api,omitempty"`
}

CargoConfig is the registry configuration returned by config.json.

type CargoHandler 

type CargoHandler struct {
	// contains filtered or unexported fields
}

CargoHandler handles cargo registry protocol requests.

func NewCargoHandler 

func NewCargoHandler(proxy *Proxy, proxyURL, indexURL, downloadURL string) *CargoHandler

NewCargoHandler creates a new cargo protocol handler.

func (*CargoHandler) Routes 

func (h *CargoHandler) Routes() http.Handler

Routes returns the HTTP handler for cargo requests. Mount this at /cargo on your router.

type ChefHandler added in v0.10.0 

type ChefHandler struct {
	// contains filtered or unexported fields
}

ChefHandler serves a read-only Chef Supermarket at /chef. Berkshelf and Policyfiles resolve dependencies against /universe and then download each cookbook through the cookbook API. Every download location in those documents is rewritten to the proxy, so cookbooks are fetched through it and cached; dependency constraints and every other field pass through unchanged.

func NewChefHandler added in v0.10.0 

func NewChefHandler(proxy *Proxy, proxyURL, upstreamURL string) *ChefHandler

NewChefHandler creates a Chef Supermarket handler for the Supermarket at upstreamURL, such as https://supermarket.chef.io or a private Supermarket.

func (*ChefHandler) Routes added in v0.10.0 

func (h *ChefHandler) Routes() http.Handler

Routes returns the HTTP handler for Chef Supermarket requests.

type ComposerHandler 

type ComposerHandler struct {
	// contains filtered or unexported fields
}

ComposerHandler handles Composer/Packagist registry protocol requests.

func NewComposerHandler 

func NewComposerHandler(proxy *Proxy, proxyURL string) *ComposerHandler

NewComposerHandler creates a new Composer protocol handler.

func NewComposerHandlerWithUpstreams added in v0.8.0 

func NewComposerHandlerWithUpstreams(proxy *Proxy, proxyURL, upstreamURL, repoURL string) *ComposerHandler

NewComposerHandlerWithUpstreams creates a Composer handler with custom API and repository upstreams.

func (*ComposerHandler) Routes 

func (h *ComposerHandler) Routes() http.Handler

Routes returns the HTTP handler for Composer requests.

func (*ComposerHandler) WithPackageRoutes added in v0.10.0 

func (h *ComposerHandler) WithPackageRoutes(routes map[string]string) *ComposerHandler

WithPackageRoutes sends packages matching a pattern to a dedicated Composer repository instead of the default one. See packageRoutes.

type ConanHandler 

type ConanHandler struct {
	// contains filtered or unexported fields
}

ConanHandler handles Conan registry protocol requests.

func NewConanHandler 

func NewConanHandler(proxy *Proxy, proxyURL string) *ConanHandler

NewConanHandler creates a new Conan protocol handler.

func NewConanHandlerWithUpstream added in v0.8.0 

func NewConanHandlerWithUpstream(proxy *Proxy, proxyURL, upstreamURL string) *ConanHandler

NewConanHandlerWithUpstream creates a Conan handler with a custom upstream.

func (*ConanHandler) Routes 

func (h *ConanHandler) Routes() http.Handler

Routes returns the HTTP handler for Conan requests.

type CondaHandler 

type CondaHandler struct {
	// contains filtered or unexported fields
}

CondaHandler handles Conda/Anaconda registry protocol requests.

func NewCondaHandler 

func NewCondaHandler(proxy *Proxy, proxyURL string) *CondaHandler

NewCondaHandler creates a new Conda protocol handler.

func NewCondaHandlerWithUpstream added in v0.8.0 

func NewCondaHandlerWithUpstream(proxy *Proxy, proxyURL, upstreamURL string) *CondaHandler

NewCondaHandlerWithUpstream creates a Conda handler with a custom upstream.

func (*CondaHandler) Routes 

func (h *CondaHandler) Routes() http.Handler

Routes returns the HTTP handler for Conda requests.

type ContainerHandler 

type ContainerHandler struct {
	// contains filtered or unexported fields
}

ContainerHandler handles OCI/Docker container registry protocol requests. It implements the OCI Distribution Spec for pulling images. Reference: https://github.com/opencontainers/distribution-spec/blob/main/spec.md

func NewContainerHandlerWithRegistry added in v0.8.0 

func NewContainerHandlerWithRegistry(
	proxy *Proxy,
	proxyURL, registryURL string,
	namedRegistries ...map[string]string,
) *ContainerHandler

NewContainerHandlerWithRegistry creates a container handler with a custom default registry and optional named registries.

func (*ContainerHandler) BlockRegistry added in v0.8.0 

func (h *ContainerHandler) BlockRegistry(repositoryPrefix string)

BlockRegistry prevents a repository and its descendants from falling back to the default OCI registry. A more specific registered repository still wins.

func (*ContainerHandler) MirrorImage added in v0.10.0 

func (h *ContainerHandler) MirrorImage(ctx context.Context, ref ImageRef, platforms []Platform) (ImageResult, error)

MirrorImage fetches an image the way a client pull does: the manifest or index for each reference, the platform manifests, then config and layer blobs. Everything is stored under the keys a later pull through this handler reads, so the pull is served from cache. Platforms limit which index entries are followed; without them every platform is mirrored.

func (*ContainerHandler) RegisterRegistry added in v0.8.0 

func (h *ContainerHandler) RegisterRegistry(repositoryPrefix, registryURL string)

RegisterRegistry routes a repository and its descendants to a specific OCI registry. The longest matching repository prefix wins.

func (*ContainerHandler) Routes 

func (h *ContainerHandler) Routes() http.Handler

Routes returns the HTTP handler for container registry requests. Mount this at /v2 on your router.

func (*ContainerHandler) SetMirroredRegistries added in v0.10.0 

func (h *ContainerHandler) SetMirroredRegistries(mirrors map[string][]string)

SetMirroredRegistries records which registry hosts each named upstream mirrors, for example "ghcr" -> ["ghcr.io"] for an Artifactory remote of ghcr.io. Those hosts select the upstream in ns lookups and are accepted as ns on its upstream/{name}/ prefix. They rank below every host taken from a configured URL, so they are indexed after the constructor's index.

type CooldownPolicy added in v0.9.1 

type CooldownPolicy interface {
	IsAllowed(ecosystem, packagePURL string, publishedAt time.Time) bool
	Evaluate(ecosystem, packagePURL string, publishedAt, evaluatedAt time.Time) cooldown.Decision
	For(ecosystem, packagePURL string) time.Duration
	Enabled() bool
}

CooldownPolicy supplies version-age filtering and package-specific durations.

type DebianHandler 

type DebianHandler struct {
	// contains filtered or unexported fields
}

DebianHandler handles APT/Debian repository protocol requests. It proxies requests to upstream Debian/Ubuntu repositories and caches .deb packages.

The main archive is served at /debian/. Additional archives are mounted at /debian/{repository}/ and the remaining path mirrors the upstream layout.

func NewDebianHandler 

func NewDebianHandler(
	proxy *Proxy,
	proxyURL string,
	upstreamURL string,
	repositories map[string]string,
) *DebianHandler

NewDebianHandler creates a new Debian/APT protocol handler. When repositories is empty, only the main archive is reachable.

func (*DebianHandler) Routes 

func (h *DebianHandler) Routes() http.Handler

Routes returns the HTTP handler for Debian requests. Mount this at /debian on your router.

type GemHandler 

type GemHandler struct {
	// contains filtered or unexported fields
}

GemHandler handles RubyGems registry protocol requests.

func NewGemHandler 

func NewGemHandler(proxy *Proxy, proxyURL string) *GemHandler

NewGemHandler creates a new RubyGems protocol handler.

func NewGemHandlerWithUpstream added in v0.8.0 

func NewGemHandlerWithUpstream(proxy *Proxy, proxyURL, upstreamURL string) *GemHandler

NewGemHandlerWithUpstream creates a RubyGems handler with a custom upstream.

func (*GemHandler) Routes 

func (h *GemHandler) Routes() http.Handler

Routes returns the HTTP handler for RubyGems requests.

type GenericHandler added in v0.8.0 

type GenericHandler struct {
	// contains filtered or unexported fields
}

GenericHandler proxies plain HTTP downloads from configured upstream base URLs. Each configured upstream is mounted at /generic/{name}/ and the remaining request path (and query string) is appended to the upstream URL.

Only configured upstreams are reachable, so the proxy is not an open HTTP proxy. The handler is the caching layer behind tools that download from fixed URL shapes, such as mise's aqua backend fetching GitHub release assets, and is pointed at by URL-rewriting settings on the client.

Release-asset paths ({owner}/{repo}/releases/download/{tag}/{asset}), and paths matching the upstream's built-in or configured artifact patterns, are version-pinned and cached in the shared artifact cache, so they keep being served when the upstream is unreachable. Every other path is served through the metadata cache: fresh within the metadata TTL, revalidated with the upstream's validators after that, and served stale when the upstream fails or refuses the request. That covers API responses such as api.github.com/repos/{owner}/{repo}/releases/tags/{tag}.

func NewGenericHandler added in v0.8.0 

func NewGenericHandler(proxy *Proxy, repositories map[string]string, artifactPatterns ...map[string][]string) *GenericHandler

NewGenericHandler creates a generic HTTP download proxy handler. artifactPatterns maps upstream names to upstream.generic_artifacts patterns; a pattern that does not compile is logged and skipped.

func (*GenericHandler) Routes added in v0.8.0 

func (h *GenericHandler) Routes() http.Handler

Routes returns the HTTP handler for generic download requests. Mount this at /generic on your router.

type GoHandler 

type GoHandler struct {
	// contains filtered or unexported fields
}

GoHandler handles Go module proxy protocol requests.

func NewGoHandler 

func NewGoHandler(proxy *Proxy, proxyURL string) *GoHandler

NewGoHandler creates a new Go module proxy handler.

func NewGoHandlerWithUpstream added in v0.8.0 

func NewGoHandlerWithUpstream(proxy *Proxy, proxyURL, upstreamURL string) *GoHandler

NewGoHandlerWithUpstream creates a Go module handler with a custom upstream.

func (*GoHandler) Routes 

func (h *GoHandler) Routes() http.Handler

Routes returns the HTTP handler for Go proxy requests.

func (*GoHandler) SetSumDBs added in v0.10.0 

func (h *GoHandler) SetSumDBs(sumDBs map[string]string, offline bool)

SetSumDBs sets the checksum databases served at /sumdb/{name}/, mapping each database name to its base URL. An empty map keeps the default, sum.golang.org. offline makes a cached tree of any age enough to keep answering for a database the proxy cannot reach, for networks where clients have no route to the database of their own.

type GradleBuildCacheHandler added in v0.4.0 

type GradleBuildCacheHandler struct {
	// contains filtered or unexported fields
}

GradleBuildCacheHandler handles Gradle HttpBuildCache GET/HEAD/PUT requests.

This handler accepts /{key} when mounted under a base URL.

func NewGradleBuildCacheHandler added in v0.4.0 

func NewGradleBuildCacheHandler(proxy *Proxy) *GradleBuildCacheHandler

NewGradleBuildCacheHandler creates a Gradle HttpBuildCache handler.

func (*GradleBuildCacheHandler) Routes added in v0.4.0 

func (h *GradleBuildCacheHandler) Routes() http.Handler

Routes returns the HTTP handler for Gradle HttpBuildCache requests.

type HelmHandler added in v0.8.0 

type HelmHandler struct {
	// contains filtered or unexported fields
}

HelmHandler serves read-only HTTP Helm chart repositories. Each configured repository is mounted at /helm/{repository}/.

func NewHelmHandler added in v0.8.0 

func NewHelmHandler(proxy *Proxy, proxyURL string, repositories map[string]string) *HelmHandler

NewHelmHandler creates a Helm chart repository protocol handler.

func NewHelmHandlerWithOCIRegistries added in v0.9.0 

func NewHelmHandlerWithOCIRegistries(proxy *Proxy, proxyURL string, repositories map[string]string, defaultRegistry string, registries map[string]string) *HelmHandler

NewHelmHandlerWithOCIRegistries also rewrites OCI references for configured registries through the existing /v2 routes. Unmatched references stay intact.

func (*HelmHandler) Routes added in v0.8.0 

func (h *HelmHandler) Routes() http.Handler

Routes returns the HTTP handler for Helm chart repository requests.

type HexHandler 

type HexHandler struct {
	// contains filtered or unexported fields
}

HexHandler handles Hex.pm registry protocol requests.

func NewHexHandler 

func NewHexHandler(proxy *Proxy, proxyURL string) *HexHandler

NewHexHandler creates a new Hex.pm protocol handler.

func NewHexHandlerWithUpstreams added in v0.8.0 

func NewHexHandlerWithUpstreams(proxy *Proxy, proxyURL, upstreamURL, apiURL string) *HexHandler

NewHexHandlerWithUpstreams creates a Hex handler with custom repository and API upstreams.

func (*HexHandler) Routes 

func (h *HexHandler) Routes() http.Handler

Routes returns the HTTP handler for Hex requests.

type HomebrewHandler added in v0.8.0 

type HomebrewHandler struct {
	// contains filtered or unexported fields
}

HomebrewHandler proxies Homebrew's JSON API without modifying signed files.

func NewHomebrewHandler added in v0.8.0 

func NewHomebrewHandler(proxy *Proxy, apiUpstream string) *HomebrewHandler

NewHomebrewHandler creates a Homebrew JSON API handler.

func (*HomebrewHandler) Routes added in v0.8.0 

func (h *HomebrewHandler) Routes() http.Handler

Routes returns the Homebrew JSON API handler. Mount this at /homebrew.

type HostedArtifact added in v0.10.0 

type HostedArtifact struct {
	Version  string    `json:"version"`
	Filename string    `json:"filename"`
	SHA256   string    `json:"sha256"`
	Size     int64     `json:"size"`
	PushedAt time.Time `json:"pushed_at"`
}

HostedArtifact describes one pushed archive.

type HostedTarget added in v0.10.0 

type HostedTarget struct {
	Name     string
	Version  string
	Filename string
}

HostedTarget is where a pushed archive is stored: the package name and version it is cached under and the filename clients request it by. Download handlers look artifacts up by exactly these values, so a push under any other name would never be served.

func HostedTargetFor added in v0.10.0 

func HostedTargetFor(ecosystem, name, version string) (HostedTarget, error)

HostedTargetFor validates a push of name@version to ecosystem and returns where it is stored.

type ImageRef added in v0.10.0 

type ImageRef struct {
	// Registry is the registry host the image reference names, as containerd
	// sends it in the ns query parameter. Empty routes Name like a pull
	// without ns.
	Registry string
	// Name is the repository name.
	Name string
	// References are the tags and digests to mirror.
	References []string
}

ImageRef names an image to mirror.

type ImageResult added in v0.10.0 

type ImageResult struct {
	// Fetched counts manifests and blobs that were not cached before.
	Fetched int
	// Bytes is the size of the blobs fetched for this image.
	Bytes    int64
	Warnings []string
}

ImageResult reports what mirroring one image did.

type JuliaHandler added in v0.4.0 

type JuliaHandler struct {
	// contains filtered or unexported fields
}

JuliaHandler handles Julia Pkg server protocol requests.

See https://pkgdocs.julialang.org/v1/registries/ and the PkgServer.jl reference implementation. The protocol is content-addressed: registry, package and artifact resources are all identified by git tree hashes and are immutable once published.

func NewJuliaHandler added in v0.4.0 

func NewJuliaHandler(proxy *Proxy, _ string) *JuliaHandler

NewJuliaHandler creates a new Julia Pkg server handler.

func NewJuliaHandlerWithUpstream added in v0.8.0 

func NewJuliaHandlerWithUpstream(proxy *Proxy, upstreamURL string) *JuliaHandler

NewJuliaHandlerWithUpstream creates a Julia handler with a custom upstream.

func (*JuliaHandler) Routes added in v0.4.0 

func (h *JuliaHandler) Routes() http.Handler

Routes returns the HTTP handler for Julia requests.

type MavenHandler 

type MavenHandler struct {
	// contains filtered or unexported fields
}

MavenHandler handles Maven repository protocol requests.

func NewMavenHandler 

func NewMavenHandler(proxy *Proxy, proxyURL, upstreamURL, pluginPortalUpstreamURL string) *MavenHandler

NewMavenHandler creates a new Maven repository handler.

func (*MavenHandler) Routes 

func (h *MavenHandler) Routes() http.Handler

Routes returns the HTTP handler for Maven requests.

type NPMHandler 

type NPMHandler struct {
	// contains filtered or unexported fields
}

NPMHandler handles npm registry protocol requests.

func NewNPMHandler 

func NewNPMHandler(proxy *Proxy, proxyURL, upstreamURL string) *NPMHandler

NewNPMHandler creates a new npm protocol handler.

func (*NPMHandler) Routes 

func (h *NPMHandler) Routes() http.Handler

Routes returns the HTTP handler for npm requests. Mount this at /npm on your router.

func (*NPMHandler) WithPackageRoutes added in v0.10.0 

func (h *NPMHandler) WithPackageRoutes(routes map[string]string) *NPMHandler

WithPackageRoutes sends packages matching a pattern to a dedicated npm registry instead of the default one. See packageRoutes.

type NuGetHandler 

type NuGetHandler struct {
	// contains filtered or unexported fields
}

NuGetHandler handles NuGet V3 API protocol requests.

func NewNuGetHandler 

func NewNuGetHandler(proxy *Proxy, proxyURL string) *NuGetHandler

NewNuGetHandler creates a new NuGet protocol handler.

func NewNuGetHandlerWithUpstreams added in v0.8.0 

func NewNuGetHandlerWithUpstreams(proxy *Proxy, proxyURL, upstreamURL, searchURL string) *NuGetHandler

NewNuGetHandlerWithUpstreams creates a NuGet handler with custom API and search upstreams.

func (*NuGetHandler) Routes 

func (h *NuGetHandler) Routes() http.Handler

Routes returns the HTTP handler for NuGet requests.

type Platform added in v0.10.0 

type Platform struct {
	OS           string
	Architecture string
	Variant      string
}

Platform selects the entries of an image index to mirror. Empty fields match any value.

func ParsePlatform added in v0.10.0 

func ParsePlatform(value string) (Platform, error)

ParsePlatform parses os/architecture[/variant].

type Proxy 

type Proxy struct {
	DB                  *database.DB
	Storage             storage.Storage
	Fetcher             fetch.FetcherInterface
	Resolver            *fetch.Resolver
	Logger              *slog.Logger
	Cooldown            CooldownPolicy
	Denylist            *denylist.Policy
	CacheMetadata       bool
	MetadataTTL         time.Duration
	MetadataMaxSize     int64
	GradleReadOnly      bool
	HostedEnabled       bool
	GradleMaxUploadSize int64
	// NPMFullMetadata requests full npm packuments from upstream even when
	// cooldown is disabled, so served metadata carries publish times.
	NPMFullMetadata bool
	DirectServe     bool
	DirectServeTTL  time.Duration
	// DirectServeBaseURL, if set, replaces the scheme and host of presigned
	// URLs so clients receive a public address even when the proxy reaches
	// storage at an internal one.
	DirectServeBaseURL string
	HTTPClient         *http.Client

	// RateLimits is the gate under the upstream clients. Artifact fetches
	// check it before calling Fetcher, so held hosts never reach its breaker.
	RateLimits *registryclient.RateLimitGate

	// HostedNPMScopes and HostedComposerVendors name namespaces served from
	// pushed packages alone, without asking the upstream.
	HostedNPMScopes       []string
	HostedComposerVendors []string

	// StreamArtifacts streams artifacts from upstream without storing them.
	// Each request fetches its own copy: there is no cache to check and
	// nothing for concurrent misses to share.
	StreamArtifacts bool

	// Scanners runs pre-cache artifact scanning (e.g. trivy, ClamAV, Wiz).
	// Nil or disabled means artifacts are cached without scanning.
	Scanners *scanner.Group

	// ScanSigningKey authenticates pull requests to the internal
	// /_internal/scan-fetch route used by scanners to retrieve staged
	// artifacts, for every storage backend.
	ScanSigningKey []byte

	// ScanFetchBaseURL is the address scanners use to reach this proxy to
	// pull staged artifacts.
	ScanFetchBaseURL string
	// contains filtered or unexported fields
}

Proxy provides shared functionality for protocol handlers.

func NewProxy 

func NewProxy(db *database.DB, store storage.Storage, fetcher fetch.FetcherInterface, resolver *fetch.Resolver, logger *slog.Logger) *Proxy

NewProxy creates a new Proxy with the given dependencies.

func (*Proxy) ClearCachedArtifact added in v0.8.0 

func (p *Proxy) ClearCachedArtifact(ecosystem, name, version, filename string) error

ClearCachedArtifact clears an artifact cache record after an external integrity check fails, and queues its stored bytes for deletion.

func (*Proxy) DeleteLocalVersion added in v0.10.0 

func (p *Proxy) DeleteLocalVersion(ecosystem, name, version string) error

DeleteLocalVersion removes the archives pushed for name@version. If the upstream has the version, clients get the upstream archive again.

func (*Proxy) FetchOrCacheMetadata 

func (p *Proxy) FetchOrCacheMetadata(ctx context.Context, ecosystem, cacheKey, upstreamURL string, acceptHeaders ...string) ([]byte, string, error)

FetchOrCacheMetadata fetches metadata from upstream with caching. On success it returns the raw response bytes and content type. If upstream fails and a cached copy exists, the cached version is returned. cacheKey is typically the package name but can include subpath components. Optional acceptHeaders specify the Accept header(s) to send; defaults to application/json.

func (*Proxy) GetCachedArtifact added in v0.7.0 

func (p *Proxy) GetCachedArtifact(ctx context.Context, ecosystem, name, version, filename string) (*CacheResult, error)

GetCachedArtifact retrieves an artifact from cache without contacting an upstream. It returns nil when no usable cache entry exists.

func (*Proxy) GetLocalArtifact added in v0.10.0 

func (p *Proxy) GetLocalArtifact(ctx context.Context, ecosystem, name, version, filename string) (*CacheResult, error)

GetLocalArtifact serves a pushed artifact from storage, or returns nil when the artifact was not pushed. Handlers that must consult the upstream before serving a cached copy call it first, so pushed versions the upstream does not list are still served. Pushed artifacts are not a cache, so they are served even when StreamArtifacts is set.

func (*Proxy) GetOrFetchArtifact 

func (p *Proxy) GetOrFetchArtifact(ctx context.Context, ecosystem, name, version, filename string) (*CacheResult, error)

GetOrFetchArtifact retrieves an artifact from cache or fetches from upstream.

func (*Proxy) GetOrFetchArtifactFromURL 

func (p *Proxy) GetOrFetchArtifactFromURL(ctx context.Context, ecosystem, name, version, filename, downloadURL string) (*CacheResult, error)

GetOrFetchArtifactFromURL retrieves an artifact from cache or fetches from a specific URL. This is useful for registries where download URLs are determined from metadata.

func (*Proxy) GetOrFetchArtifactFromURLWithDigest added in v0.8.0 

func (p *Proxy) GetOrFetchArtifactFromURLWithDigest(ctx context.Context, ecosystem, name, version, filename, downloadURL, digest string) (*CacheResult, error)

GetOrFetchArtifactFromURLWithDigest retrieves an artifact and verifies its SHA-256 digest before adding a newly fetched response to the cache. Non-sha256 digests are proxied without verification.

func (*Proxy) GetOrFetchArtifactFromURLWithHeaders 

func (p *Proxy) GetOrFetchArtifactFromURLWithHeaders(ctx context.Context, ecosystem, name, version, filename, downloadURL string, headers http.Header) (*CacheResult, error)

GetOrFetchArtifactFromURLWithHeaders retrieves an artifact from cache or fetches from a URL with additional request-specific HTTP headers.

func (*Proxy) GetOrFetchArtifactFromURLWithIntegrity added in v0.10.0 

func (p *Proxy) GetOrFetchArtifactFromURLWithIntegrity(ctx context.Context, ecosystem, name, version, filename, downloadURL, declared string) (*CacheResult, error)

GetOrFetchArtifactFromURLWithIntegrity retrieves an artifact and verifies a newly fetched response against declared, the integrity the registry's metadata declares, before serving or caching it: a Subresource Integrity string, or a single algorithm-prefixed hex checksum such as "sha1-<hex>". declared is recorded with the cached version, so cache hits are verified against it as well. An empty declared fetches without verification.

func (*Proxy) HasCachedArtifact added in v0.10.0 

func (p *Proxy) HasCachedArtifact(ctx context.Context, ecosystem, name, version, filename string) (bool, error)

HasCachedArtifact reports whether an artifact is cached and its object is stored, without opening it or counting a cache hit, so a mirror run does not look like client traffic.

func (*Proxy) LocalArtifacts added in v0.10.0 

func (p *Proxy) LocalArtifacts(ecosystem, name string) ([]HostedArtifact, error)

LocalArtifacts lists the archives pushed for a package.

func (*Proxy) ProxyCached 

func (p *Proxy) ProxyCached(w http.ResponseWriter, r *http.Request, upstreamURL, ecosystem, cacheKey string, acceptHeaders ...string)

ProxyCached fetches metadata from upstream (with optional caching for offline fallback) and writes it to the response. Optional acceptHeaders specify the Accept header to send. When metadata caching is disabled, the response is streamed directly to avoid buffering large metadata responses (e.g. npm packages with many versions) in memory.

func (*Proxy) ProxyFile 

func (p *Proxy) ProxyFile(w http.ResponseWriter, r *http.Request, upstreamURL string)

ProxyFile forwards a file request, relaying end-to-end headers and trailers.

func (*Proxy) ProxyUpstream 

func (p *Proxy) ProxyUpstream(w http.ResponseWriter, r *http.Request, upstreamURL string, forwardHeaders []string)

ProxyUpstream forwards a request to an upstream URL without caching. It copies the request, forwards specified headers, and streams the response back. forwardHeaders controls the request headers sent upstream. End-to-end response headers and trailers are relayed independently of that list.

func (*Proxy) PushLocalArtifact added in v0.10.0 

func (p *Proxy) PushLocalArtifact(ctx context.Context, ecosystem string, target HostedTarget, body io.Reader, contentType string) (HostedArtifact, error)

PushLocalArtifact stores body as the artifact for target and records it as local, replacing any cached upstream copy. Download handlers serve it from the cache without contacting the upstream, and eviction never removes it. The archive's manifest must name target; it is kept so the ecosystem's metadata can list the version with its dependencies.

func (*Proxy) ReadMetadata added in v0.5.0 

func (p *Proxy) ReadMetadata(r io.Reader) ([]byte, error)

ReadMetadata reads an upstream response body with a size limit to prevent OOM from unexpectedly large responses. Returns ErrMetadataTooLarge if the response is truncated by the limit.

func (*Proxy) ServeScanFetch added in v0.8.0 

func (p *Proxy) ServeScanFetch(w http.ResponseWriter, r *http.Request)

ServeScanFetch streams a storage object to a caller presenting a valid short-lived HMAC token, so external scanners can pull a staged artifact without going through cooldown or the scan hook themselves. This handler never calls GetOrFetchArtifact/fetchAndCache/storeArtifact — the separation from the normal request path is structural, not a conditional bypass flag.

This route exists only for scanners configured under ScanningConfig; the URL is minted by scanFetchURL and passed as fetch_url in the scan notify request. It is not part of the public API and should be restricted to internal-network access at the ingress/network-policy layer — the HMAC scoping (one object, short TTL) limits what a leaked token can do, but isn't a substitute for network restriction.

@Summary Fetch a staged artifact for scanning @Description Streams the exact bytes staged in storage for a pre-cache security scan. @Description Requires a short-lived HMAC-signed token minted by the proxy itself and @Description delivered via the fetch_url field of the scan notify request (see the @Description Artifact Scanning section of docs/configuration.md). Not part of the @Description public API; restrict access to the scanner network at the ingress layer. @Tags scanning @Produce application/octet-stream @Param path query string true "Storage path of the staged artifact" @Param exp query int true "Token expiry, Unix seconds" @Param sig query string true "HMAC-SHA256 signature over the string path|exp" @Success 200 {file} file @Failure 403 {string} string "invalid, expired, or tampered token" @Failure 404 {string} string "object not found in storage, or scanning is not configured" @Router /_internal/scan-fetch [get]

func (*Proxy) SetMetadataRewriteCacheSize added in v0.9.1 

func (p *Proxy) SetMetadataRewriteCacheSize(maxBytes int64)

SetMetadataRewriteCacheSize enables the cache of rewritten metadata with room for maxBytes of output. Zero or less disables it.

type PubHandler 

type PubHandler struct {
	// contains filtered or unexported fields
}

PubHandler handles pub.dev registry protocol requests.

func NewPubHandler 

func NewPubHandler(proxy *Proxy, proxyURL string) *PubHandler

NewPubHandler creates a new pub.dev protocol handler.

func NewPubHandlerWithUpstream added in v0.8.0 

func NewPubHandlerWithUpstream(proxy *Proxy, proxyURL, upstreamURL string) *PubHandler

NewPubHandlerWithUpstream creates a pub handler with a custom upstream.

func (*PubHandler) Routes 

func (h *PubHandler) Routes() http.Handler

Routes returns the HTTP handler for pub requests.

type PyPIHandler 

type PyPIHandler struct {
	// contains filtered or unexported fields
}

PyPIHandler handles PyPI registry protocol requests.

func NewPyPIHandlerWithUpstreams added in v0.8.0 

func NewPyPIHandlerWithUpstreams(proxy *Proxy, proxyURL, upstreamURL, downloadURL string) *PyPIHandler

NewPyPIHandlerWithUpstreams creates a PyPI handler with custom API and package download upstreams.

func (*PyPIHandler) Routes 

func (h *PyPIHandler) Routes() http.Handler

Routes returns the HTTP handler for PyPI requests.

type RPMHandler 

type RPMHandler struct {
	// contains filtered or unexported fields
}

RPMHandler handles RPM/Yum repository protocol requests. It proxies requests to upstream RPM repositories and caches .rpm packages.

func NewRPMHandler 

func NewRPMHandler(proxy *Proxy, proxyURL string) *RPMHandler

NewRPMHandler creates a new RPM/Yum protocol handler.

func NewRPMHandlerWithUpstream added in v0.8.0 

func NewRPMHandlerWithUpstream(proxy *Proxy, proxyURL, upstreamURL string) *RPMHandler

NewRPMHandlerWithUpstream creates an RPM handler with a custom upstream.

func (*RPMHandler) Routes 

func (h *RPMHandler) Routes() http.Handler

Routes returns the HTTP handler for RPM requests. Mount this at /rpm on your router.

type SwiftHandler added in v0.8.0 

type SwiftHandler struct {
	// contains filtered or unexported fields
}

SwiftHandler handles the read-only Swift Package Registry v1 protocol.

func NewSwiftHandler added in v0.8.0 

func NewSwiftHandler(proxy *Proxy, proxyURL, upstreamURL string) *SwiftHandler

NewSwiftHandler creates a Swift Package Registry protocol handler.

func (*SwiftHandler) Routes added in v0.8.0 

func (h *SwiftHandler) Routes() http.Handler

Routes returns the HTTP handler for Swift registry requests.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.