Class: Purl::Lookup

Inherits:
Object
  • Object
show all
Defined in:
lib/purl/lookup.rb

Overview

Provides lookup functionality for packages using the ecosyste.ms API

Constant Summary collapse

ECOSYSTE_MS_API_BASE = 
"https://packages.ecosyste.ms/api/v1"

Instance Method Summary collapse

Constructor Details

#initialize(user_agent: nil, timeout: 10) ⇒ Lookup

Initialize a new Lookup instance

Parameters:

  • user_agent (String) (defaults to: nil) —

    User agent string for API requests

  • timeout (Integer) (defaults to: 10) —

    Request timeout in seconds



17
18
19
20
 
# File 'lib/purl/lookup.rb', line 17

def initialize(user_agent: nil, timeout: 10)
  @user_agent = user_agent || "purl-ruby/#{Purl::VERSION}"
  @timeout = timeout
end

Instance Method Details

#package_info(purl) ⇒ Hash?

Look up package information for a given PURL

Examples:

lookup = Purl::Lookup.new
info = lookup.package_info("pkg:cargo/[email protected]")
puts info[:package][:name]  # => "rand"
puts info[:version][:published_at] if info[:version]  # => "2025-07-20T17:47:01.870Z"

Parameters:

  • purl (String, PackageURL) —

    PURL string or PackageURL object

Returns:

  • (Hash, nil) —

    Package information hash or nil if not found

Raises:

  • (LookupError) —

    if the lookup fails due to network or API errors



33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
 
# File 'lib/purl/lookup.rb', line 33

def package_info(purl)
  purl_obj = purl.is_a?(PackageURL) ? purl : PackageURL.parse(purl.to_s)
  
  # Try package lookup first
  uri = URI("#{ECOSYSTE_MS_API_BASE}/packages/lookup")
  uri.query = URI.encode_www_form({ purl: purl_obj.to_s })
  
  response_data = make_request(uri)
  
  if response_data.is_a?(Array) && response_data.length > 0
    package_data = response_data[0]
    
    result = {
      purl: purl_obj.to_s,
      package: extract_package_info(package_data)
    }
    
    # If PURL has a version and we have a versions_url, fetch version-specific details
    if purl_obj.version && package_data["versions_url"]
      version_info = fetch_version_info(package_data["versions_url"], purl_obj.version)
      result[:version] = version_info if version_info
    end
    
    return result
  end
  
  # If no package found, try repository lookup
  repo_uri = URI("https://repos.ecosyste.ms/api/v1/repositories/lookup")
  repo_uri.query = URI.encode_www_form({ purl: purl_obj.to_s })
  
  repo_data = make_request(repo_uri)
  
  if repo_data
    result = {
      purl: purl_obj.to_s,
      repository: extract_repository_info(repo_data)
    }
    
    return result
  end
  
  nil
end

#version_info(purl) ⇒ Hash?

Look up version information for a specific version of a package

Examples:

lookup = Purl::Lookup.new
version_info = lookup.version_info("pkg:cargo/[email protected]")
puts version_info[:published_at]  # => "2025-07-20T17:47:01.870Z"

Parameters:

  • purl (String, PackageURL) —

    PURL string or PackageURL object (must include version)

Returns:

  • (Hash, nil) —

    Version information hash or nil if not found

Raises:

  • (LookupError) —

    if the lookup fails due to network or API errors

  • (ArgumentError) —

    if the PURL doesn’t include a version



88
89
90
91
92
93
94
95
96
97
98
 
# File 'lib/purl/lookup.rb', line 88

def version_info(purl)
  purl_obj = purl.is_a?(PackageURL) ? purl : PackageURL.parse(purl.to_s)
  
  raise ArgumentError, "PURL must include a version" unless purl_obj.version
  
  # First get the package info to get the versions_url
  package_result = package_info(purl_obj.versionless)
  return nil unless package_result && package_result[:package][:versions_url]
  
  fetch_version_info(package_result[:package][:versions_url], purl_obj.version)
end