puppet_forge 4.0.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a0e379f885f305dfc82f87bfea6ae668d6467595f0083355cbe95c63e9864019
-  data.tar.gz: 1cf23ce28776267459e01bedfed935750650378542b54e1ec3155efb9b67ba60
+  metadata.gz: 2eed3dead78d19c535ee9a2b372a89e17efcf7b24f01c752bb38096a2ed52e37
+  data.tar.gz: 2036388fc19159a57d425383aa6c89326d222a900f9fd61fbbb529e62d004f28
 SHA512:
-  metadata.gz: b32e4f0758fe84f28339cc8a3f57dad01a21abc26a490e7d1b8ac1a4ecdc6e52b961e4c24f0f4a5b476c4fc1ed849bfb42594314a120f6198c06261036702457
-  data.tar.gz: 044a092e9f8e15f078043281bac236c8694c037a1f71bb34a4d0e392379811e88ac9981afa6d75661cc5483a7a3966af26def433fe2eeb370c9f2d80499fbcba
+  metadata.gz: ca288c45d5329d1656221858c03a1125e0e29eb1e6701b95da90baa2cd6ba254907e15fafbf4f1474b69a43014a3c9f10fbcaed620d3913d4bf221194b3a2cc5
+  data.tar.gz: 8f5a441289712e2cb9ef9c7d34a17cef347b2b09ff0f60fc1430cceae3780229201aecee3b0baa601a3fd343060ed1976fad247e8e54abbbfb7d5a9a37f30fc0

data/.github/workflows/ruby-rspec.yml

@@ -15,13 +15,14 @@ jobs:
     strategy:
       matrix:
         ruby:
+          - '3.2'
           - '3.1'
           - '3.0'
           - '2.7'
           - '2.6'
 
     steps:
-      - uses: actions/checkout@v1
+      - uses: actions/checkout@v3
       - name: Set up Ruby ${{ matrix.ruby }}
         uses: ruby/setup-ruby@v1
         with:

data/CHANGELOG.md

@@ -3,6 +3,17 @@
 Starting with v2.0.0, all notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+## v5.0.0 - 2023-05-07
+
+* Ruby 3.2 support.
+* LRU caching for HTTP response caching.
+* Raise a ModuleNotFound error instead of just nil when a module is not found.
+
+## v4.1.0 - 2023-02-21
+
+* Add upload method functionality.
+* Allows the user to search by an array of endorsements.
+
 ## v4.0.0 - 2022-11-30
 
 * Breaking: The `puppet_forge` gem now requires at least Ruby 2.6.0

data/CODEOWNERS

@@ -1 +1 @@
-* @puppetlabs/forge-team
+* @puppetlabs/forge-team @bastelfreak

data/README.md

@@ -136,7 +136,23 @@ release.verify(Pathname(release_tarball))
 # @raise RuntimeError if it fails to extract the contents of the release tarball
 PuppetForge::Unpacker.unpack(release_tarball, dest_dir, tmp_dir)
 ```
+### Uploading a module release
 
+You can upload new module versions to the forge by following the steps below.
+
+> Note: This API requires authorization. See [Authorization](#authorization) for more information.
+
+```ruby
+release_tarball = 'pkg/puppetlabs-apache-1.6.0.tar.gz'
+
+# Upload a module tarball to the Puppet Forge
+# Returns an instance of V3::Release class and the response from the forge upload 
+# @raise PuppetForge::ReleaseForbidden if a 403 response is recieved from the server
+# @raise PuppetForge::ReleaseBadContent if the module to upload is not valid
+# @raise Faraday::ClientError if any errors encountered in the upload
+# @raise PuppetForge::FileNotFound if the given tarball cannot be found
+release, response = PuppetForge::V3::Release.upload(release_tarball)
+```
 
 ### Paginated Collections
 

data/lib/puppet_forge/error.rb

@@ -28,16 +28,32 @@ Could not install package
     end
   end
 
+
+  class ErrorWithDetail < PuppetForge::Error
+    def self.from_response(response)
+      body = JSON.parse(response[:body])
+
+      message = body['message']
+      if body.key?('errors') && !body['errors']&.empty?
+        message << "\nThe following errors were returned from the server:\n - #{body['errors'].join("\n - ")}"
+      end
+
+      new(message)
+    end
+  end
+
+  class FileNotFound < PuppetForge::Error
+  end
+
   class ModuleNotFound < PuppetForge::Error
   end
 
   class ReleaseNotFound < PuppetForge::Error
   end
 
-  class ReleaseForbidden < PuppetForge::Error
-    def self.from_response(response)
-      body = JSON.parse(response[:body])
-      new(body["message"])
-    end
+  class ReleaseForbidden < PuppetForge::ErrorWithDetail
+  end
+
+  class ReleaseBadContent < PuppetForge::ErrorWithDetail
   end
 end

data/lib/puppet_forge/lru_cache.rb

@@ -0,0 +1,78 @@
+require 'digest'
+
+module PuppetForge
+  # Implements a simple LRU cache. This is used internally by the
+  # {PuppetForge::V3::Base} class to cache API responses.
+  class LruCache
+    # Takes a list of strings (or objects that respond to #to_s) and
+    # returns a SHA256 hash of the strings joined with colons. This is
+    # a convenience method for generating cache keys. Cache keys do not
+    # have to be SHA256 hashes, but they must be unique.
+    def self.new_key(*string_args)
+      Digest::SHA256.hexdigest(string_args.map(&:to_s).join(':'))
+    end
+
+    # @return [Integer] the maximum number of items to cache.
+    attr_reader :max_size
+
+    # @param max_size [Integer] the maximum number of items to cache. This can
+    #   be overridden by setting the PUPPET_FORGE_MAX_CACHE_SIZE environment
+    #   variable.
+    def initialize(max_size = 30)
+      raise ArgumentError, "max_size must be a positive integer" unless max_size.is_a?(Integer) && max_size > 0
+
+      @max_size = ENV['PUPPET_FORGE_MAX_CACHE_SIZE'] ? ENV['PUPPET_FORGE_MAX_CACHE_SIZE'].to_i : max_size
+      @cache = {}
+      @lru = []
+      @semaphore = Mutex.new
+    end
+
+    # Retrieves a value from the cache.
+    # @param key [Object] the key to look up in the cache
+    # @return [Object] the cached value for the given key, or nil if
+    #   the key is not present in the cache.
+    def get(key)
+      if cache.key?(key)
+        semaphore.synchronize do
+          # If the key is present, move it to the front of the LRU
+          # list.
+          lru.delete(key)
+          lru.unshift(key)
+        end
+        cache[key]
+      end
+    end
+
+    # Adds a value to the cache.
+    # @param key [Object] the key to add to the cache
+    # @param value [Object] the value to add to the cache
+    def put(key, value)
+      semaphore.synchronize do
+        if cache.key?(key)
+          # If the key is already present, delete it from the LRU list.
+          lru.delete(key)
+        elsif cache.size >= max_size
+          # If the cache is full, remove the least recently used item.
+          cache.delete(lru.pop)
+        end
+        # Add the key to the front of the LRU list and add the value
+        # to the cache.
+        lru.unshift(key)
+        cache[key] = value
+      end
+    end
+
+    # Clears the cache.
+    def clear
+      semaphore.synchronize do
+        cache.clear
+        lru.clear
+      end
+    end
+
+    private
+
+    # Makes testing easier as these can be accessed directly with #send.
+    attr_reader :cache, :lru, :semaphore
+  end
+end

data/lib/puppet_forge/v3/base.rb

@@ -4,6 +4,7 @@ require 'puppet_forge/error'
 
 require 'puppet_forge/lazy_accessors'
 require 'puppet_forge/lazy_relations'
+require 'puppet_forge/lru_cache'
 
 module PuppetForge
   module V3
@@ -53,8 +54,22 @@ module PuppetForge
           API_VERSION
         end
 
+        # @private
+        def lru_cache
+          @lru_cache ||= PuppetForge::LruCache.new
+        end
+
+        # @private
+        def lru_cache_key(*args)
+          PuppetForge::LruCache.new_key(*args)
+        end
+
         # @private
         def request(resource, item = nil, params = {}, reset_connection = false, conn_opts = {})
+          cache_key = lru_cache_key(resource, item, params)
+          cached = lru_cache.get(cache_key)
+          return cached unless cached.nil?
+
           conn(reset_connection, conn_opts) if reset_connection
           unless conn.url_prefix.to_s =~ /^#{PuppetForge.host}/
             conn.url_prefix = "#{PuppetForge.host}"
@@ -66,7 +81,12 @@ module PuppetForge
             uri_path = "v3/#{resource}/#{item}"
           end
 
-          PuppetForge::V3::Base.conn.get uri_path, params
+          # The API expects a space separated string. This allows the user to invoke it with a more natural feeling array.
+          params['endorsements'] = params['endorsements'].join(' ') if params['endorsements'].is_a? Array
+
+          result = PuppetForge::V3::Base.conn.get uri_path, params
+          lru_cache.put(cache_key, result)
+          result
         end
 
         # @private

data/lib/puppet_forge/v3/module.rb

@@ -11,6 +11,11 @@ module PuppetForge
       lazy :current_release, 'Release'
       lazy_collection :releases, 'Release'
 
+      def self.find(slug)
+        super
+      rescue Faraday::ResourceNotFound
+        raise PuppetForge::ModuleNotFound, "Module #{slug} not found"
+      end
     end
   end
 end

data/lib/puppet_forge/v3/release.rb

@@ -2,6 +2,7 @@ require 'puppet_forge/v3/base'
 require 'puppet_forge/v3/module'
 
 require 'digest'
+require 'base64'
 
 module PuppetForge
   module V3
@@ -38,6 +39,38 @@ module PuppetForge
         end
       end
 
+      # Uploads the tarbarll to the forge
+      #
+      # @param path [Pathname] tarball file path
+      # @return resp
+      def self.upload(path)
+        # We want to make sure that the file exists before trying to upload it
+        raise PuppetForge::FileNotFound, "The file '#{path}' does not exist." unless File.file?(path)
+
+        file = File.open(path, 'rb')
+        encoded_string = Base64.encode64(file.read)
+        data = { file: encoded_string }
+
+        resp = conn.post do |req|
+          req.url '/v3/releases'
+          req.headers['Content-Type'] = 'application/json'
+          req.body = data.to_json
+        end
+
+        [self, resp]
+      rescue Faraday::ClientError => e
+        if e.response
+          case e.response[:status]
+          when 403
+            raise PuppetForge::ReleaseForbidden.from_response(e.response)
+          when 400
+            raise PuppetForge::ReleaseBadContent.from_response(e.response)
+          end
+        end
+
+        raise e
+      end
+
       # Verify that a downloaded module matches the best available checksum in the metadata for this release,
       # validates SHA-256 checksum if available, otherwise validates MD5 checksum
       #

data/lib/puppet_forge/version.rb

@@ -1,3 +1,3 @@
 module PuppetForge
-  VERSION = '4.0.0' # Library version
+  VERSION = '5.0.0' # Library version
 end

data/spec/spec_helper.rb

@@ -12,7 +12,10 @@ require 'puppet_forge'
 
 module StubbingFaraday
 
-  def stub_api_for(klass, base_url = "http://api.example.com")
+  def stub_api_for(klass, base_url = "http://api.example.com", lru_cache: false)
+    unless lru_cache # Disable LRU cache by default
+      allow(klass).to receive(:lru_cache).and_return(instance_double('PuppetForge::LruCache', get: nil, put: nil, clear: nil))
+    end
     allow(klass).to receive(:conn) do
       Faraday.new :url => base_url do |builder|
         builder.response(:json, :content_type => /\bjson$/, :parser_options => { :symbolize_names => true })
@@ -38,7 +41,7 @@ module StubbingFaraday
     [ 404 ].tap do |response|
       local = File.join(PROJECT_ROOT, 'spec', 'fixtures', xplatform_path)
 
-      if File.exists?("#{local}.headers") && File.exists?("#{local}.json")
+      if File.exist?("#{local}.headers") && File.exist?("#{local}.json")
         File.open("#{local}.headers") do |file|
           response[0] = file.readline[/\d{3}/].to_i
           response[1] = headers = {}

data/spec/unit/forge/lru_cache_spec.rb

@@ -0,0 +1,127 @@
+require 'spec_helper'
+
+describe PuppetForge::LruCache do
+  it 'creates a cache key from a list of strings' do
+    expect { subject.class.new_key('foo', 'bar', 'baz') }.not_to raise_error 
+  end
+
+  it 'creates a new instance' do
+    expect { PuppetForge::LruCache.new(1) }.not_to raise_error
+  end
+
+  it 'raises an error if max_size is not a positive integer' do
+    expect { PuppetForge::LruCache.new(-1) }.to raise_error(ArgumentError)
+    expect { PuppetForge::LruCache.new(0) }.to raise_error(ArgumentError)
+    expect { PuppetForge::LruCache.new(1.5) }.to raise_error(ArgumentError)
+  end
+
+  it 'defaults to a max_size of 30' do
+    expect(PuppetForge::LruCache.new.max_size).to eq(30)
+  end
+
+  it 'allows max_size to be set via the max_size parameter' do
+    expect(PuppetForge::LruCache.new(42).max_size).to eq(42)
+  end
+
+  it 'provides a #get method' do
+    expect(PuppetForge::LruCache.new).to respond_to(:get)
+  end
+
+  it 'provides a #put method' do
+    expect(PuppetForge::LruCache.new).to respond_to(:put)
+  end
+
+  it 'provides a #clear method' do
+    expect(PuppetForge::LruCache.new).to respond_to(:clear)
+  end
+
+  context 'with environment variables' do
+    around(:each) do |example|
+      @old_max_size = ENV['PUPPET_FORGE_MAX_CACHE_SIZE']
+      ENV['PUPPET_FORGE_MAX_CACHE_SIZE'] = '42'
+      example.run
+      ENV['PUPPET_FORGE_MAX_CACHE_SIZE'] = @old_max_size
+    end
+
+    it 'uses the value of the PUPPET_FORGE_MAX_CACHE_SIZE environment variable if present' do
+      expect(PuppetForge::LruCache.new.max_size).to eq(42)
+    end
+  end
+
+  context '#get' do
+    it 'returns nil if the key is not present in the cache' do
+      expect(PuppetForge::LruCache.new.get('foo')).to be_nil
+    end
+
+    it 'returns the cached value for the given key' do
+      cache = PuppetForge::LruCache.new
+      cache.put('foo', 'bar')
+      expect(cache.get('foo')).to eq('bar')
+    end
+
+    it 'moves the key to the front of the LRU list' do
+      cache = PuppetForge::LruCache.new
+      cache.put('foo', 'bar')
+      cache.put('baz', 'qux')
+      cache.get('foo')
+      expect(cache.send(:lru)).to eq(['foo', 'baz'])
+    end
+
+    # The below test is non-deterministic but I'm not sure how to unit
+    # test thread-safety.
+    # it 'is thread-safe' do
+    #   cache = PuppetForge::LruCache.new
+    #   cache.put('foo', 'bar')
+    #   cache.put('baz', 'qux')
+    #   threads = []
+    #   threads << Thread.new { 100.times { cache.get('foo') } }
+    #   threads << Thread.new { 100.times { cache.get('baz') } }
+    #   threads.each(&:join)
+    #   expect(cache.send(:lru)).to eq(['baz', 'foo'])
+    # end
+  end
+
+  context '#put' do
+    it 'adds the key to the front of the LRU list' do
+      cache = PuppetForge::LruCache.new
+      cache.put('foo', 'bar')
+      expect(cache.send(:lru)).to eq(['foo'])
+    end
+
+    it 'adds the value to the cache' do
+      cache = PuppetForge::LruCache.new
+      cache.put('foo', 'bar')
+      expect(cache.send(:cache)).to eq({ 'foo' => 'bar' })
+    end
+
+    it 'removes the least recently used item if the cache is full' do
+      cache = PuppetForge::LruCache.new(2)
+      cache.put('foo', 'bar')
+      cache.put('baz', 'qux')
+      cache.put('quux', 'corge')
+      expect(cache.send(:lru)).to eq(['quux', 'baz'])
+    end
+
+    # The below test is non-deterministic but I'm not sure how to unit
+    # test thread-safety.
+    # it 'is thread-safe' do
+    #   cache = PuppetForge::LruCache.new
+    #   threads = []
+    #   threads << Thread.new { 100.times { cache.put('foo', 'bar') } }
+    #   threads << Thread.new { 100.times { cache.put('baz', 'qux') } }
+    #   threads.each(&:join)
+    #   expect(cache.send(:lru)).to eq(['baz', 'foo'])
+    # end
+  end
+
+  context '#clear' do
+    it 'clears the cache' do
+      cache = PuppetForge::LruCache.new
+      cache.put('foo', 'bar')
+      cache.put('baz', 'qux')
+      cache.clear
+      expect(cache.send(:lru).empty?).to be_truthy
+      expect(cache.send(:cache).empty?).to be_truthy
+    end
+  end
+end

data/spec/unit/forge/v3/base_spec.rb

@@ -61,6 +61,7 @@ describe PuppetForge::V3::Base do
   describe 'the host url setting' do
     context 'without a path prefix' do
       before(:each) do
+        PuppetForge::V3::Base.lru_cache.clear # We test the cache later, so clear it now
         @orig_host = PuppetForge.host
         PuppetForge.host = 'https://api.example.com'
 
@@ -83,10 +84,25 @@ describe PuppetForge::V3::Base do
         base = PuppetForge::V3::Base.find 'puppet'
         expect(base.username).to eq('foo')
       end
+
+      it 'caches responses' do
+        stub_api_for(PuppetForge::V3::Base, lru_cache: true) do |stubs|
+          stub_fixture(stubs, :get, '/v3/bases/puppet')
+        end
+        allow(PuppetForge::V3::Base.lru_cache).to receive(:put).and_call_original
+        allow(PuppetForge::V3::Base.lru_cache).to receive(:get).and_call_original
+
+        PuppetForge::V3::Base.find 'puppet'
+        PuppetForge::V3::Base.find 'puppet'
+        PuppetForge::V3::Base.find 'puppet'
+        expect(PuppetForge::V3::Base.lru_cache).to have_received(:put).once
+        expect(PuppetForge::V3::Base.lru_cache).to have_received(:get).exactly(3).times
+      end
     end
 
     context 'with a path prefix' do
       before(:each) do
+        PuppetForge::V3::Base.lru_cache.clear # We test the cache later, so clear it now
         @orig_host = PuppetForge.host
         PuppetForge.host = 'https://api.example.com/uri/prefix'
 
@@ -109,6 +125,20 @@ describe PuppetForge::V3::Base do
         base = PuppetForge::V3::Base.find 'puppet'
         expect(base.username).to eq('bar')
       end
+
+      it 'caches responses' do
+        stub_api_for(PuppetForge::V3::Base, PuppetForge.host, lru_cache: true) do |stubs|
+          stub_fixture(stubs, :get, '/uri/prefix/v3/bases/puppet')
+        end
+        allow(PuppetForge::V3::Base.lru_cache).to receive(:put).and_call_original
+        allow(PuppetForge::V3::Base.lru_cache).to receive(:get).and_call_original
+
+        PuppetForge::V3::Base.find 'puppet'
+        PuppetForge::V3::Base.find 'puppet'
+        PuppetForge::V3::Base.find 'puppet'
+        expect(PuppetForge::V3::Base.lru_cache).to have_received(:put).once
+        expect(PuppetForge::V3::Base.lru_cache).to have_received(:get).exactly(3).times
+      end
     end
   end
 end

data/spec/unit/forge/v3/module_spec.rb

@@ -28,8 +28,8 @@ describe PuppetForge::V3::Module do
       expect(mod_stateless.name).to eq('apache')
     end
 
-    it 'returns nil for non-existent modules' do
-      expect { missing_mod }.to raise_error(Faraday::ResourceNotFound)
+    it 'raises exception for non-existent modules' do
+      expect { missing_mod }.to raise_error(PuppetForge::ModuleNotFound, 'Module absent-apache not found')
     end
   end
 

data/spec/unit/forge/v3/release_spec.rb

@@ -218,5 +218,43 @@ describe PuppetForge::V3::Release do
         expect(release.created_at).to_not be nil
       end
     end
+
+    describe '#upload' do
+      let(:tarball) { "#{PROJECT_ROOT}/spec/tmp/module.tgz" }
+      let(:file_object) { double('file', read: 'file contents') }
+
+      let(:release) { PuppetForge::V3::Release.upload(tarball) }
+      let(:mock_conn) { instance_double('PuppetForge::V3::Connection', url_prefix: PuppetForge.host) }
+
+      context 'when there is no auth token provided' do
+        it 'raises PuppetForge::ReleaseForbidden' do
+          allow(File).to receive(:file?).and_return(true)
+          allow(File).to receive(:open).and_return(file_object)
+          allow(described_class).to receive(:conn).and_return(mock_conn)
+
+          response = { status: 403, body: { 'message' => 'Forbidden' }.to_json }
+          expect(mock_conn).to receive(:post).and_raise(Faraday::ClientError.new('Forbidden', response))
+          expect { release }.to raise_error(PuppetForge::ReleaseForbidden)
+        end
+      end
+
+      context 'when the module is not valid' do
+        it 'raises PuppetForge::ReleaseBadRequest' do
+          allow(File).to receive(:file?).and_return(true)
+          allow(File).to receive(:open).and_return(file_object)
+          allow(described_class).to receive(:conn).and_return(mock_conn)
+
+          response = { status: 400, body: { message: 'Bad Content' }.to_json }
+          expect(mock_conn).to receive(:post).and_raise(Faraday::ClientError.new('400', response))
+          expect { release }.to raise_error(PuppetForge::ReleaseBadContent)
+        end
+      end
+
+      context 'when the tarball does not exist' do
+        it 'raises PuppetForge::FileNotFound' do
+          expect { PuppetForge::V3::Release.upload(tarball) }.to raise_error(PuppetForge::FileNotFound)
+        end
+      end
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: puppet_forge
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 5.0.0
 platform: ruby
 authors:
 - Puppet Labs
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-12-01 00:00:00.000000000 Z
+date: 2023-06-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -187,6 +187,7 @@ files:
 - lib/puppet_forge/error.rb
 - lib/puppet_forge/lazy_accessors.rb
 - lib/puppet_forge/lazy_relations.rb
+- lib/puppet_forge/lru_cache.rb
 - lib/puppet_forge/tar.rb
 - lib/puppet_forge/tar/mini.rb
 - lib/puppet_forge/unpacker.rb
@@ -236,6 +237,7 @@ files:
 - spec/unit/forge/connection_spec.rb
 - spec/unit/forge/lazy_accessors_spec.rb
 - spec/unit/forge/lazy_relations_spec.rb
+- spec/unit/forge/lru_cache_spec.rb
 - spec/unit/forge/tar/mini_spec.rb
 - spec/unit/forge/tar_spec.rb
 - spec/unit/forge/unpacker_spec.rb
@@ -251,7 +253,7 @@ homepage: https://github.com/puppetlabs/forge-ruby
 licenses:
 - Apache-2.0
 metadata: {}
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -267,7 +269,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.1.6
-signing_key:
+signing_key: 
 specification_version: 4
 summary: Access the Puppet Forge API from Ruby for resource information and to download
   releases.
@@ -308,6 +310,7 @@ test_files:
 - spec/unit/forge/connection_spec.rb
 - spec/unit/forge/lazy_accessors_spec.rb
 - spec/unit/forge/lazy_relations_spec.rb
+- spec/unit/forge/lru_cache_spec.rb
 - spec/unit/forge/tar/mini_spec.rb
 - spec/unit/forge/tar_spec.rb
 - spec/unit/forge/unpacker_spec.rb