goproxy

Documentation

Overview

Package goproxy provides an HTTP client for the Go Module Proxy.

Overview

This package fetches module metadata from the Go Module Proxy (https://proxy.golang.org), the default proxy for Go modules.

Usage

client, err := goproxy.NewClient(24 * time.Hour)
if err != nil {
    log.Fatal(err)
}

mod, err := client.FetchModule(ctx, "github.com/spf13/cobra", false)
if err != nil {
    log.Fatal(err)
}

fmt.Println(mod.Path, mod.Version)
fmt.Println("Dependencies:", mod.Dependencies)

ModuleInfo

[FetchModule] returns a ModuleInfo containing:

• Path: Module path (e.g., "github.com/spf13/cobra")
• Version: Latest version from @latest endpoint
• Dependencies: Direct dependencies from go.mod

Caching

Responses are cached to reduce load on the proxy. The cache TTL is set when creating the client. Pass refresh=true to bypass the cache.

Dependency Filtering

Only direct dependencies are included. Indirect dependencies (marked with "// indirect" comment) are filtered out.

Two-Phase Fetch

The client performs two requests:

1. @latest endpoint to get the latest version
2. .mod endpoint to fetch and parse go.mod for dependencies

Some modules don't have a go.mod file (pre-modules or minimal modules). In this case, dependencies will be empty.

Path Escaping

Module paths with uppercase letters are escaped per the Go module proxy protocol (uppercase becomes !lowercase).

Index

• type Client
  • func NewClient(backend cache.Cache, cacheTTL time.Duration) *Client
  • func (c *Client) FetchLicense(ctx context.Context, mod string, refresh bool) string
  • func (c *Client) FetchModule(ctx context.Context, mod string, refresh bool) (*ModuleInfo, error)
  • func (c *Client) FetchModuleVersion(ctx context.Context, mod, version string, refresh bool) (*ModuleInfo, error)
  • func (c *Client) ListVersions(ctx context.Context, mod string, refresh bool) ([]string, error)
• type Dependency
• type ModuleInfo

Types

type Client

type Client struct {
	*integrations.Client
	// contains filtered or unexported fields
}

Client provides access to the Go module proxy API. It handles HTTP requests with caching and automatic retries.

All methods are safe for concurrent use by multiple goroutines.

func NewClient

func NewClient(backend cache.Cache, cacheTTL time.Duration) *Client

NewClient creates a Go module proxy client with the given cache backend.

Parameters:

• backend: Cache backend for HTTP response caching (use storage.NullBackend{} for no caching)
• cacheTTL: How long responses are cached (typical: 1-24 hours)

The returned Client is safe for concurrent use.

func (*Client) FetchLicense

func (c *Client) FetchLicense(ctx context.Context, mod string, refresh bool) string

FetchLicense retrieves the license identifier for a module from pkg.go.dev. This is intentionally separated from FetchModule/FetchModuleVersion so that the expensive HTML scrape only runs during the post-resolution enrichment phase, not during PubGrub solving where many versions are evaluated.

Results are cached at the module level (not per-version) since the license is the same for all versions of a module.

func (*Client) FetchModule

func (c *Client) FetchModule(ctx context.Context, mod string, refresh bool) (*ModuleInfo, error)

FetchModule retrieves metadata for a Go module from the module proxy (latest version).

The mod parameter should be a full module path (e.g., "github.com/user/repo"). Module paths with uppercase letters are escaped per the Go module proxy protocol. Module path cannot be empty; an empty string will result in an API error.

If refresh is true, the cache is bypassed and a fresh API call is made. If refresh is false, cached data is returned if available and not expired.

This method performs two API calls:

1. @latest endpoint to get the latest version
2. .mod endpoint to fetch and parse go.mod for dependencies

go.mod fetch failures are silently ignored; Dependencies will be nil/empty if it fails. This is normal for pre-module packages or minimal modules without dependencies.

Returns:

• ModuleInfo populated with metadata on success
• integrations.ErrNotFound if the module doesn't exist
• integrations.ErrNetwork for HTTP failures (timeout, 5xx, etc.)
• Other errors for JSON decoding failures

The returned ModuleInfo pointer is never nil if err is nil. This method is safe for concurrent use.

func (*Client) FetchModuleVersion

func (c *Client) FetchModuleVersion(ctx context.Context, mod, version string, refresh bool) (*ModuleInfo, error)

FetchModuleVersion retrieves metadata for a specific version of a Go module.

The mod parameter should be a full module path. The version must be an exact version string (e.g., "v1.8.0").

If refresh is true, the cache is bypassed and a fresh API call is made.

Returns:

• ModuleInfo populated with metadata on success
• integrations.ErrNotFound if the module or version doesn't exist
• integrations.ErrNetwork for HTTP failures (timeout, 5xx, etc.)

This method is safe for concurrent use.

func (*Client) ListVersions

func (c *Client) ListVersions(ctx context.Context, mod string, refresh bool) ([]string, error)

ListVersions returns all available versions for a module, sorted from oldest to newest.

type Dependency

type Dependency struct {
	Name       string // Module path
	Constraint string // Version requirement from go.mod (e.g., "v1.2.3")
}

Dependency represents a Go module dependency with version requirement.

type ModuleInfo

type ModuleInfo struct {
	Path                 string       // Module path (e.g., "github.com/spf13/cobra", never empty in valid info)
	Version              string       // Latest version from @latest endpoint (e.g., "v1.8.0", never empty in valid info)
	Dependencies         []Dependency // Direct dependencies with versions (nil or empty if none or no go.mod)
	IndirectDependencies []Dependency // Indirect dependencies (marked with "// indirect" in go.mod)
	GoVersion            string       // Go version from go.mod (e.g., "1.21", may be empty for old modules)
	License              string       // License identifier if detectable (may be empty)
	Repository           string       // Canonical source repository URL if discoverable (may be empty)
}

ModuleInfo holds metadata for a Go module from the Go module proxy.

Dependencies include only direct dependencies; indirect dependencies are stored separately in IndirectDependencies. Some modules (pre-modules or minimal modules) may not have a go.mod file; Dependencies will be nil/empty.

For Go 1.17+ modules, the IndirectDependencies list represents the pruned module graph (only modules actually needed to build). For older modules, indirect deps may be incomplete.

Zero values: All string fields are empty, Dependencies is nil. This struct is safe for concurrent reads after construction.