crates

Documentation

Overview

Package crates provides an HTTP client for the crates.io API.

Overview

This package fetches crate metadata from crates.io (https://crates.io), the Rust community's package registry.

Usage

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

crate, err := client.FetchCrate(ctx, "serde", false)
if err != nil {
    log.Fatal(err)
}

fmt.Println(crate.Name, crate.Version)
fmt.Println("Dependencies:", crate.Dependencies)

CrateInfo

[FetchCrate] returns a CrateInfo containing:

• Name, Version: Crate identity (max_version from API)
• Dependencies: Normal (non-optional, non-dev) dependencies
• Description: Crate description
• License: SPDX license identifier
• Repository, HomePage: URLs for enrichment
• Downloads: Total download count

Caching

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

Dependency Filtering

Only "normal" dependencies are included. Development dependencies, build dependencies, and optional dependencies are filtered out.

User-Agent

The client includes a User-Agent header as requested by crates.io policy.

Index

• type Client
  • func NewClient(backend cache.Cache, cacheTTL time.Duration) *Client
  • func (c *Client) FetchCrate(ctx context.Context, crate string, refresh bool) (*CrateInfo, error)
  • func (c *Client) FetchCrateVersion(ctx context.Context, crate, version string, refresh bool) (*CrateInfo, error)
  • func (c *Client) FetchCrateVersionFromIndex(ctx context.Context, crate, version string, refresh bool) (*CrateInfo, error)
  • func (c *Client) ListVersions(ctx context.Context, crate string, refresh bool) ([]string, error)
  • func (c *Client) ListVersionsWithConstraints(ctx context.Context, crate string, refresh bool) (map[string]string, error)
• type CrateInfo
• type Dependency

Types

type Client

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

Client provides access to the crates.io package registry API. It handles HTTP requests with caching and automatic retries.

All methods are safe for concurrent use by multiple goroutines.

Note: crates.io requires a User-Agent header; this client sets one automatically.

func NewClient

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

NewClient creates a crates.io 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 client includes a User-Agent header as required by crates.io API policy. The returned Client is safe for concurrent use.

func (*Client) FetchCrate

func (c *Client) FetchCrate(ctx context.Context, crate string, refresh bool) (*CrateInfo, error)

FetchCrate retrieves metadata for a Rust crate from crates.io (latest version).

The crate parameter is case-sensitive and must match the published crate name exactly. Crate name 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.

Dependency fetching failures are silently ignored; Dependencies will be empty/nil if the secondary API call fails. This is not considered an error.

Returns:

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

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

func (*Client) FetchCrateVersion

func (c *Client) FetchCrateVersion(ctx context.Context, crate, version string, refresh bool) (*CrateInfo, error)

FetchCrateVersion retrieves metadata for a specific version of a Rust crate.

The crate parameter is case-sensitive. The version must be an exact version string (e.g., "1.0.193").

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

Returns:

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

This method is safe for concurrent use.

func (*Client) FetchCrateVersionFromIndex

func (c *Client) FetchCrateVersionFromIndex(ctx context.Context, crate, version string, refresh bool) (*CrateInfo, error)

FetchCrateVersionFromIndex returns package info using only the sparse index. This is much faster than FetchCrateVersion because it avoids the REST API call for metadata (description, license, downloads, etc.). Use this during dependency resolution where only deps and MSRV are needed.

func (*Client) ListVersions

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

ListVersions returns all non-yanked versions for a crate, sorted semantically from oldest to newest.

func (*Client) ListVersionsWithConstraints

func (c *Client) ListVersionsWithConstraints(ctx context.Context, crate string, refresh bool) (map[string]string, error)

ListVersionsWithConstraints returns all versions and their rust_version (MSRV). Returns a map of version -> rust_version (empty string if not specified).

type CrateInfo

type CrateInfo struct {
	Name         string       // Crate name (e.g., "serde", never empty in valid info)
	Version      string       // Latest version (e.g., "1.0.193", never empty in valid info)
	Dependencies []Dependency // Normal dependencies with version requirements (nil or empty if none)
	Repository   string       // Repository URL (may be empty)
	HomePage     string       // Homepage URL (may be empty)
	Description  string       // Crate description (may be empty)
	License      string       // License identifier(s) (may be empty or "MIT OR Apache-2.0")
	Downloads    int          // Total download count across all versions (0 for new crates)
	MSRV         string       // Minimum Supported Rust Version (e.g., "1.70.0", may be empty)
}

CrateInfo holds metadata for a Rust crate from crates.io.

The Version field contains the max_version (latest stable or highest version). Dependencies include only "normal" (non-dev, non-optional) dependencies.

Zero values: All string fields are empty, Dependencies is nil, Downloads is 0. A Downloads value of 0 is valid for newly published crates. This struct is safe for concurrent reads after construction.

type Dependency

type Dependency struct {
	Name       string // Crate name
	Constraint string // Version requirement (e.g., "^1.0", ">=0.5,<1.0"), empty for no constraint
}

Dependency represents a crate dependency with version requirement.