rubygems

Documentation

Overview

Package rubygems provides an HTTP client for the RubyGems.org API.

Overview

This package fetches gem metadata from RubyGems.org (https://rubygems.org), the Ruby community's gem hosting service.

Usage

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

gem, err := client.FetchGem(ctx, "rails", false)
if err != nil {
    log.Fatal(err)
}

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

GemInfo

[FetchGem] returns a GemInfo containing:

• Name, Version: Gem identity
• Dependencies: Runtime dependencies only
• Description: Gem info/summary
• License: License string (may be comma-separated)
• SourceCodeURI, HomepageURI: URLs for enrichment
• Downloads: Total download count
• Authors: Author names

Caching

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

Dependency Filtering

Only runtime dependencies are included. Development dependencies are filtered out. Gem names are normalized to lowercase.

Index

• type Client
  • func NewClient(backend cache.Cache, cacheTTL time.Duration) *Client
  • func (c *Client) FetchGem(ctx context.Context, gem string, refresh bool) (*GemInfo, error)
  • func (c *Client) FetchGemVersion(ctx context.Context, gem, version string, refresh bool) (*GemInfo, error)
  • func (c *Client) ListVersions(ctx context.Context, gem string, refresh bool) ([]string, error)
  • func (c *Client) ListVersionsWithConstraints(ctx context.Context, gem string, refresh bool) (map[string]string, error)
• type Dependency
• type GemInfo

Types

type Client

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

Client provides access to the RubyGems package registry 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 RubyGems 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) FetchGem

func (c *Client) FetchGem(ctx context.Context, gem string, refresh bool) (*GemInfo, error)

FetchGem retrieves metadata for a Ruby gem from RubyGems (latest version).

The gem parameter is normalized to lowercase with whitespace trimmed. Gem 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.

Returns:

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

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

func (*Client) FetchGemVersion

func (c *Client) FetchGemVersion(ctx context.Context, gem, version string, refresh bool) (*GemInfo, error)

FetchGemVersion retrieves metadata for a specific version of a Ruby gem.

The gem parameter is normalized to lowercase. The version must be an exact version string (e.g., "7.1.2").

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

Returns:

• GemInfo populated with metadata on success
• integrations.ErrNotFound if the gem 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, gem string, refresh bool) ([]string, error)

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

func (*Client) ListVersionsWithConstraints

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

ListVersionsWithConstraints returns all versions and their Ruby runtime constraints. Returns a map of version -> required_ruby_version (empty string if not specified).

type Dependency

type Dependency struct {
	Name       string // Gem name
	Constraint string // Version requirement (e.g., "~> 6.0", ">= 1.0, < 2.0")
}

Dependency represents a gem dependency with version requirement.

type GemInfo

type GemInfo struct {
	Name                string       // Gem name, normalized lowercase (e.g., "rails", never empty in valid info)
	Version             string       // Current version (e.g., "7.1.2", never empty in valid info)
	Dependencies        []Dependency // Runtime dependencies with version requirements (nil or empty if none)
	SourceCodeURI       string       // Source code repository URL (may be empty)
	HomepageURI         string       // Homepage URL (may be empty)
	Description         string       // Gem description/info (may be empty)
	License             string       // License(s), comma-separated if multiple (may be empty)
	Downloads           int          // Total download count (0 for new gems)
	Authors             string       // Author name(s) (may be empty)
	RequiredRubyVersion string       // Required Ruby version constraint (e.g., ">= 3.0", may be empty)
}

GemInfo holds metadata for a Ruby gem from RubyGems.

Gem names are normalized to lowercase. Dependencies include only runtime dependencies; development dependencies are excluded.

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