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) 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) 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.