maven

package
v1.4.0 Latest Latest
Warning

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

 Go to latest Published: May 22, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Overview

Package maven implements the Maven repository protocol for caching Maven artifacts.

Index

Constants

View Source 
const (
	// DefaultArtifactNegativeCacheTTL is how long a per-upstream 404 for an
	// immutable artifact path is remembered. Long: artifact coordinates are
	// immutable (a new version is a new path), so stale negative cache is
	// harmless. Reduces repeat 404 probes that trigger upstream rate limiting
	// and IP blocklisting (e.g. Sonatype's "abusive client" heuristic).
	DefaultArtifactNegativeCacheTTL = 24 * time.Hour

	// DefaultMetadataNegativeCacheTTL is how long a per-upstream 404 for a
	// mutable metadata path (maven-metadata.xml, root catalogs) is remembered.
	// Short, so newly published versions become discoverable quickly.
	DefaultMetadataNegativeCacheTTL = 1 * time.Minute
)
View Source 
const (
	ExtensionJAR = "jar"
	ExtensionPOM = "pom"
	ExtensionWAR = "war"
	ExtensionEAR = "ear"
	ExtensionAAR = "aar"
	ExtensionZIP = "zip"
)

Common file extensions for Maven artifacts.

View Source 
const (
	ChecksumMD5    = "md5"
	ChecksumSHA1   = "sha1"
	ChecksumSHA256 = "sha256"
	ChecksumSHA512 = "sha512"
)

Checksum file extensions.

View Source 
const (
	// DefaultTimeout is the default timeout for upstream requests.
	DefaultTimeout = 30 * time.Second

	// DefaultPerUpstreamTimeout caps a single upstream attempt when multiple
	// upstreams are configured, so a slow upstream doesn't block fallback.
	DefaultPerUpstreamTimeout = 5 * time.Second
)
View Source 
const DefaultRepositoryURL = "https://repo.maven.apache.org/maven2"

DefaultRepositoryURL is the default Maven Central repository URL.

Variables

View Source 
var ErrNotFound = errors.New("artifact not found")

ErrNotFound is returned when an artifact is not found upstream.

Functions

This section is empty.

Types

type ArtifactCoordinate 

type ArtifactCoordinate struct {
	GroupID    string
	ArtifactID string
	Version    string
	Classifier string
	Extension  string
}

ArtifactCoordinate identifies a Maven artifact.

func (ArtifactCoordinate) Filename 

func (c ArtifactCoordinate) Filename() string

Filename returns the standard Maven filename for this artifact.

func (ArtifactCoordinate) FullPath 

func (c ArtifactCoordinate) FullPath() string

FullPath returns the full repository path for this artifact.

func (ArtifactCoordinate) GroupPath 

func (c ArtifactCoordinate) GroupPath() string

GroupPath returns the group ID as a path (dots replaced with slashes).

type CachedArtifact 

type CachedArtifact struct {
	GroupID    string            `json:"group_id"`
	ArtifactID string            `json:"artifact_id"`
	Version    string            `json:"version"`
	Classifier string            `json:"classifier,omitempty"` // e.g., "sources", "javadoc"
	Extension  string            `json:"extension"`            // e.g., "jar", "pom", "war"
	Hash       contentcache.Hash `json:"hash"`                 // BLAKE3 hash in CAFS
	Size       int64             `json:"size"`
	Checksums  Checksums         `json:"checksums"`
	CachedAt   time.Time         `json:"cached_at"`
}

CachedArtifact stores cached artifact information.

type CachedMetadata 

type CachedMetadata struct {
	GroupID    string    `json:"group_id"`
	ArtifactID string    `json:"artifact_id"`
	Metadata   []byte    `json:"metadata"` // Raw XML content
	CachedAt   time.Time `json:"cached_at"`
	UpdatedAt  time.Time `json:"updated_at"`
}

CachedMetadata stores cached maven-metadata.xml information.

type Checksums 

type Checksums struct {
	MD5    string `json:"md5,omitempty"`
	SHA1   string `json:"sha1,omitempty"`
	SHA256 string `json:"sha256,omitempty"`
	SHA512 string `json:"sha512,omitempty"`
}

Checksums holds various checksum values for an artifact.

type Handler 

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

Handler implements the Maven repository protocol as an HTTP handler.

func NewHandler 

func NewHandler(index *Index, store store.Store, opts ...HandlerOption) *Handler

NewHandler creates a new Maven repository handler.

func (*Handler) Close 

func (h *Handler) Close()

Close shuts down the handler and waits for background operations to complete.

func (*Handler) ServeHTTP 

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements http.Handler.

type HandlerOption 

type HandlerOption func(*Handler)

HandlerOption configures a Handler.

func WithDownloader 

func WithDownloader(dl *download.Downloader) HandlerOption

WithDownloader sets the singleflight downloader for deduplicating concurrent fetches.

func WithLogger 

func WithLogger(logger *slog.Logger) HandlerOption

WithLogger sets the logger for the handler.

func WithMetadataTTL 

func WithMetadataTTL(ttl time.Duration) HandlerOption

WithMetadataTTL sets the TTL for maven-metadata.xml caching.

func WithUpstream 

func WithUpstream(upstream *Upstream) HandlerOption

WithUpstream sets the upstream repository.

type Index 

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

Index manages the Maven artifact index using metadb envelope storage.

func NewIndex 

func NewIndex(metadataIndex, artifactIndex *metadb.EnvelopeIndex) *Index

NewIndex creates a new Maven artifact index using EnvelopeIndex instances. metadataIndex: protocol="maven", kind="metadata" for maven-metadata.xml artifactIndex: protocol="maven", kind="artifact" for CachedArtifact with blob refs

func (*Index) DeleteArtifact 

func (idx *Index) DeleteArtifact(ctx context.Context, coord ArtifactCoordinate) error

DeleteArtifact removes cached artifact information.

func (*Index) DeleteMetadata 

func (idx *Index) DeleteMetadata(ctx context.Context, groupID, artifactID string) error

DeleteMetadata removes cached metadata for an artifact.

func (*Index) GetArtifactHash 

func (idx *Index) GetArtifactHash(ctx context.Context, coord ArtifactCoordinate) (contentcache.Hash, error)

GetArtifactHash retrieves the content hash for a specific artifact.

func (*Index) GetCachedArtifact 

func (idx *Index) GetCachedArtifact(ctx context.Context, coord ArtifactCoordinate) (*CachedArtifact, error)

GetCachedArtifact retrieves cached artifact information.

func (*Index) GetCachedMetadata 

func (idx *Index) GetCachedMetadata(ctx context.Context, groupID, artifactID string) (*CachedMetadata, error)

GetCachedMetadata retrieves cached maven-metadata.xml information.

func (*Index) IsMetadataExpired 

func (idx *Index) IsMetadataExpired(metadata *CachedMetadata, ttl time.Duration) bool

IsMetadataExpired checks if cached metadata has exceeded the TTL.

func (*Index) ListArtifacts 

func (idx *Index) ListArtifacts(ctx context.Context, groupID, artifactID string) ([]string, error)

ListArtifacts returns all cached artifact keys for a given group and artifact.

func (*Index) PutCachedArtifact 

func (idx *Index) PutCachedArtifact(ctx context.Context, artifact *CachedArtifact) error

PutCachedArtifact stores cached artifact information.

func (*Index) PutCachedMetadata 

func (idx *Index) PutCachedMetadata(ctx context.Context, metadata *CachedMetadata) error

PutCachedMetadata stores cached maven-metadata.xml information.

type MavenMetadata 

type MavenMetadata struct {
	XMLName    xml.Name   `xml:"metadata" json:"-"`
	GroupID    string     `xml:"groupId" json:"group_id"`
	ArtifactID string     `xml:"artifactId" json:"artifact_id"`
	Version    string     `xml:"version,omitempty" json:"version,omitempty"`
	Versioning Versioning `xml:"versioning" json:"versioning"`
}

MavenMetadata represents the content of a maven-metadata.xml file.

type NegativeCacheStore added in v1.4.0 

type NegativeCacheStore interface {
	PutNegativeCache(ctx context.Context, key string, statusCode uint32, ttl time.Duration) error
	GetEnvelope(ctx context.Context, key string) (*metadb.MetadataEnvelope, error)
}

NegativeCacheStore persists per-(upstream, path) 404 markers with TTL. *metadb.EnvelopeIndex satisfies this interface.

type Upstream 

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

Upstream fetches artifacts from one or more upstream Maven repositories. When multiple base URLs are configured, fetches try them in order and fall through on 404, with negative caching per (upstream, path) (see negcache.go) to avoid repeatedly probing upstreams that have already returned 404.

func NewUpstream 

func NewUpstream(opts ...UpstreamOption) *Upstream

NewUpstream creates a new upstream repository client.

func (*Upstream) ArtifactURL 

func (u *Upstream) ArtifactURL(coord ArtifactCoordinate) string

ArtifactURL returns the full URL for an artifact against the primary upstream. This is informational; actual fetches iterate the chain.

func (*Upstream) FetchArtifact 

func (u *Upstream) FetchArtifact(ctx context.Context, coord ArtifactCoordinate) (io.ReadCloser, int64, error)

FetchArtifact fetches an artifact file (JAR, POM, etc.). Returns a ReadCloser that must be closed by the caller.

Unlike short fetches, this does not apply a per-upstream timeout because the returned body must remain readable after the request returns. Total fetch duration is bounded by the underlying http.Client.Timeout.

func (*Upstream) FetchChecksum 

func (u *Upstream) FetchChecksum(ctx context.Context, coord ArtifactCoordinate, checksumType string) (string, error)

FetchChecksum fetches a checksum file for an artifact.

func (*Upstream) FetchMetadata 

func (u *Upstream) FetchMetadata(ctx context.Context, groupID, artifactID string) (*MavenMetadata, error)

FetchMetadata fetches maven-metadata.xml for an artifact.

func (*Upstream) FetchMetadataRaw 

func (u *Upstream) FetchMetadataRaw(ctx context.Context, groupID, artifactID string) ([]byte, error)

FetchMetadataRaw fetches raw maven-metadata.xml content.

func (*Upstream) FetchRootFile 

func (u *Upstream) FetchRootFile(ctx context.Context, filename string) ([]byte, error)

FetchRootFile fetches a root-level file like archetype-catalog.xml.

func (*Upstream) HeadArtifact 

func (u *Upstream) HeadArtifact(ctx context.Context, coord ArtifactCoordinate) (int64, error)

HeadArtifact checks if an artifact exists and returns its size.

func (*Upstream) MetadataURL 

func (u *Upstream) MetadataURL(groupID, artifactID string) string

MetadataURL returns the full URL for maven-metadata.xml against the primary upstream. This is informational; actual fetches iterate the chain.

type UpstreamOption 

type UpstreamOption func(*Upstream)

UpstreamOption configures an Upstream.

func WithArtifactNegativeCacheTTL added in v1.4.0 

func WithArtifactNegativeCacheTTL(d time.Duration) UpstreamOption

WithArtifactNegativeCacheTTL sets how long a per-upstream 404 for an immutable artifact path is remembered. Zero disables artifact negative caching.

func WithHTTPClient 

func WithHTTPClient(client *http.Client) UpstreamOption

WithHTTPClient sets a custom HTTP client.

func WithMetadataNegativeCacheTTL added in v1.4.0 

func WithMetadataNegativeCacheTTL(d time.Duration) UpstreamOption

WithMetadataNegativeCacheTTL sets how long a per-upstream 404 for a mutable metadata path is remembered. Zero disables metadata negative caching.

func WithNegativeCacheStore added in v1.4.0 

func WithNegativeCacheStore(s NegativeCacheStore) UpstreamOption

WithNegativeCacheStore enables persistent negative caching. Without a store, every miss re-probes every upstream on every request — fine for tests, dangerous in production against rate-limiting upstreams like Maven Central.

func WithPerUpstreamTimeout added in v1.4.0 

func WithPerUpstreamTimeout(d time.Duration) UpstreamOption

WithPerUpstreamTimeout caps a single per-upstream attempt. Zero disables.

func WithRepositoryURL 

func WithRepositoryURL(url string) UpstreamOption

WithRepositoryURL sets a single upstream repository URL. Replaces any previously configured URLs.

func WithRepositoryURLs added in v1.4.0 

func WithRepositoryURLs(urls ...string) UpstreamOption

WithRepositoryURLs sets an ordered list of upstream repository URLs. Fetches try them in order and fall through on 404. Replaces any previously configured URLs.

func WithUserAgent added in v1.4.0 

func WithUserAgent(ua string) UpstreamOption

WithUserAgent sets the User-Agent header sent to upstream repositories. Identifying the client as a caching proxy helps avoid rate-limiting and blocklisting heuristics on upstreams such as Maven Central.

type Versioning 

type Versioning struct {
	Latest      string   `xml:"latest,omitempty" json:"latest,omitempty"`
	Release     string   `xml:"release,omitempty" json:"release,omitempty"`
	Versions    Versions `xml:"versions" json:"versions"`
	LastUpdated string   `xml:"lastUpdated,omitempty" json:"last_updated,omitempty"`
}

Versioning contains version information within maven-metadata.xml.

type Versions 

type Versions struct {
	Version []string `xml:"version" json:"version"`
}

Versions is a wrapper for the list of versions in maven-metadata.xml.

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.