puppet_forge 1.0.6 → 2.0.0

data/lib/puppet_forge/v3/base/paginated_collection.rb

@@ -2,22 +2,31 @@ module PuppetForge
   module V3
     class Base
 
-      # A subclass of Her::Collection that enables navigation of the Forge API's
-      # paginated datasets.
-      class PaginatedCollection < Her::Collection
+      # Enables navigation of the Forge API's paginated datasets.
+      class PaginatedCollection < Array
+
+        # Default pagination limit for API request
+        LIMIT = 20
 
-        # In addition to the standard Her::Collection arguments, this
-        # constructor requires a reference to the paginated class. This enables
-        # the collection to load related pages.
-        #
         # @api private
-        # @param klass [Her::Model] the class to page over
+        # @param klass [PuppetForge::V3::Base] the class to page over
         # @param data [Array] the current data page
         # @param metadata [Hash<(:limit, :total, :offset)>] page metadata
         # @param errors [Object] errors for the page request
-        def initialize(klass, data, metadata, errors)
-          super(data, metadata, errors)
+        def initialize(klass, data = [], metadata = {:total => 0, :offset => 0, :limit => LIMIT}, errors = nil)
+          super()
+          @metadata = metadata
+          @errors = errors
           @klass = klass
+
+          data.each do |item|
+            self << @klass.new(item)
+          end
+        end
+
+        # For backwards compatibility, all returns the current object.
+        def all
+          self
         end
 
         # An enumerator that iterates over the entire collection, independent
@@ -26,7 +35,7 @@ module PuppetForge
         #
         # @return [Enumerator] an iterator for the entire collection
         def unpaginated
-          page = @klass.get_collection(metadata[:first])
+          page = @klass.get_collection(@metadata[:first])
           Enumerator.new do |emitter|
             loop do
               page.each { |x| emitter << x }
@@ -42,7 +51,7 @@ module PuppetForge
         # @!method offset
         #   @return [Integer] the offset for the current page
         [ :total, :limit, :offset ].each do |info|
-          define_method(info) { metadata[info] }
+          define_method(info) { @metadata[info] }
         end
 
         [ :next, :previous ].each do |link|
@@ -53,7 +62,7 @@ module PuppetForge
           #   Returns the previous page if a previous page exists.
           #   @return [PaginatedCollection, nil] the previous page
           define_method(link) do
-            return unless path = metadata[link]
+            return unless path = @metadata[link]
             @klass.get_collection(path)
           end
 
@@ -64,7 +73,7 @@ module PuppetForge
           #   Returns the url of the previous page if a previous page exists.
           #   @return [String, nil] the previous page's url
           define_method("#{link}_url") do
-            metadata[link]
+            @metadata[link]
           end
         end
       end

data/lib/puppet_forge/v3/metadata.rb

@@ -0,0 +1,197 @@
+require 'uri'
+require 'json'
+require 'set'
+require 'semantic_puppet/version'
+
+module PuppetForge
+  module V3
+    # This class provides a data structure representing a module's metadata.
+    # @api private
+    class Metadata
+
+      attr_accessor :module_name
+
+      DEFAULTS = {
+        'name'         => nil,
+        'version'      => nil,
+        'author'       => nil,
+        'summary'      => nil,
+        'license'      => 'Apache-2.0',
+        'source'       => '',
+        'project_page' => nil,
+        'issues_url'   => nil,
+        'dependencies' => Set.new.freeze,
+      }
+
+      def initialize
+        @data = DEFAULTS.dup
+        @data['dependencies'] = @data['dependencies'].dup
+      end
+
+      # Returns a filesystem-friendly version of this module name.
+      def dashed_name
+        PuppetForge::V3.normalize_name(@data['name']) if @data['name']
+      end
+
+      # Returns a string that uniquely represents this version of this module.
+      def release_name
+        return nil unless @data['name'] && @data['version']
+        [ dashed_name, @data['version'] ].join('-')
+      end
+
+      alias :name :module_name
+      alias :full_module_name :dashed_name
+
+      # Merges the current set of metadata with another metadata hash.  This
+      # method also handles the validation of module names and versions, in an
+      # effort to be proactive about module publishing constraints.
+      def update(data, with_dependencies = true)
+        process_name(data) if data['name']
+        process_version(data) if data['version']
+        process_source(data) if data['source']
+        merge_dependencies(data) if with_dependencies && data['dependencies']
+
+        @data.merge!(data)
+        return self
+      end
+
+      # Validates the name and version_requirement for a dependency, then creates
+      # the Dependency and adds it.
+      # Returns the Dependency that was added.
+      def add_dependency(name, version_requirement=nil, repository=nil)
+        validate_name(name)
+        validate_version_range(version_requirement) if version_requirement
+
+        if dup = @data['dependencies'].find { |d| d.full_module_name == name && d.version_requirement != version_requirement }
+          raise ArgumentError, "Dependency conflict for #{full_module_name}: Dependency #{name} was given conflicting version requirements #{version_requirement} and #{dup.version_requirement}. Verify that there are no duplicates in the metadata.json or the Modulefile."
+        end
+
+        dep = Dependency.new(name, version_requirement, repository)
+        @data['dependencies'].add(dep)
+
+        dep
+      end
+
+      # Provides an accessor for the now defunct 'description' property.  This
+      # addresses a regression in Puppet 3.6.x where previously valid templates
+      # refering to the 'description' property were broken.
+      # @deprecated
+      def description
+        @data['description']
+      end
+
+      def dependencies
+        @data['dependencies'].to_a
+      end
+
+      # Returns a hash of the module's metadata.  Used by Puppet's automated
+      # serialization routines.
+      #
+      # @see Puppet::Network::FormatSupport#to_data_hash
+      def to_hash
+        @data
+      end
+      alias :to_data_hash :to_hash
+
+      def to_json
+        data = @data.dup.merge('dependencies' => dependencies)
+
+        contents = data.keys.map do |k|
+          value = (JSON.pretty_generate(data[k]) rescue data[k].to_json)
+          "#{k.to_json}: #{value}"
+        end
+
+        "{\n" + contents.join(",\n").gsub(/^/, '  ') + "\n}\n"
+      end
+
+      # Expose any metadata keys as callable reader methods.
+      def method_missing(name, *args)
+        return @data[name.to_s] if @data.key? name.to_s
+        super
+      end
+
+      private
+
+      # Do basic validation and parsing of the name parameter.
+      def process_name(data)
+        validate_name(data['name'])
+        author, @module_name = data['name'].split(/[-\/]/, 2)
+
+        data['author'] ||= author if @data['author'] == DEFAULTS['author']
+      end
+
+      # Do basic validation on the version parameter.
+      def process_version(data)
+        validate_version(data['version'])
+      end
+
+      # Do basic parsing of the source parameter.  If the source is hosted on
+      # GitHub, we can predict sensible defaults for both project_page and
+      # issues_url.
+      def process_source(data)
+        if data['source'] =~ %r[://]
+          source_uri = URI.parse(data['source'])
+        else
+          source_uri = URI.parse("http://#{data['source']}")
+        end
+
+        if source_uri.host =~ /^(www\.)?github\.com$/
+          source_uri.scheme = 'https'
+          source_uri.path.sub!(/\.git$/, '')
+          data['project_page'] ||= @data['project_page'] || source_uri.to_s
+          data['issues_url'] ||= @data['issues_url'] || source_uri.to_s.sub(/\/*$/, '') + '/issues'
+        end
+
+      rescue URI::Error
+        return
+      end
+
+      # Validates and parses the dependencies.
+      def merge_dependencies(data)
+        data['dependencies'].each do |dep|
+          add_dependency(dep['name'], dep['version_requirement'], dep['repository'])
+        end
+
+        # Clear dependencies so @data dependencies are not overwritten
+        data.delete 'dependencies'
+      end
+
+      # Validates that the given module name is both namespaced and well-formed.
+      def validate_name(name)
+        return if name =~ /\A[a-z0-9]+[-\/][a-z][a-z0-9_]*\Z/i
+
+        namespace, modname = name.split(/[-\/]/, 2)
+        modname = :namespace_missing if namespace == ''
+
+        err = case modname
+        when nil, '', :namespace_missing
+          "the field must be a namespaced module name"
+        when /[^a-z0-9_]/i
+          "the module name contains non-alphanumeric (or underscore) characters"
+        when /^[^a-z]/i
+          "the module name must begin with a letter"
+        else
+          "the namespace contains non-alphanumeric characters"
+        end
+
+        raise ArgumentError, "Invalid 'name' field in metadata.json: #{err}"
+      end
+
+      # Validates that the version string can be parsed by SemanticPuppet.
+      def validate_version(version)
+        return if SemanticPuppet::Version.valid?(version)
+
+        err = "version string cannot be parsed as a valid Semantic Version"
+        raise ArgumentError, "Invalid 'version' field in metadata.json: #{err}"
+      end
+
+      # Validates that the version range can be parsed by SemanticPuppet.
+      def validate_version_range(version_range)
+        SemanticPuppet::VersionRange.parse(version_range)
+      rescue ArgumentError => e
+        raise ArgumentError, "Invalid 'version_range' field in metadata.json: #{e}"
+      end
+    end
+  end
+end
+

data/lib/puppet_forge/v3/module.rb

@@ -9,7 +9,8 @@ module PuppetForge
     class Module < Base
       lazy :owner, 'User'
       lazy :current_release, 'Release'
-      lazy_collection :releases
+      lazy_collection :releases, 'Release'
+
     end
   end
 end

data/lib/puppet_forge/v3/release.rb

@@ -6,8 +6,8 @@ module PuppetForge
 
     # Models a specific release version of a Puppet Module on the Forge.
     class Release < Base
-      lazy :module
-      
+      lazy :module, 'Module'
+
       # Returns a fully qualified URL for downloading this release from the Forge.
       #
       # @return [String] fully qualified download URL for release
@@ -21,15 +21,40 @@ module PuppetForge
 
       # Downloads the Release tarball to the specified file path.
       #
-      # @todo Stream the tarball data to disk.
-      # @param file [String] the file to create
+      # @param path [Pathname]
       # @return [void]
-      def download(file)
-        self.class.get_raw(download_url)[:response].on_complete do |env|
-          File.open(file, 'wb') { |file| file.write(env[:body]) }
+      def download(path)
+        resp = self.class.conn.get(file_url)
+        path.open('wb') { |fh| fh.write(resp.body) }
+      rescue Faraday::ResourceNotFound => e
+        raise PuppetForge::ReleaseNotFound, "The module release #{slug} does not exist on #{conn.url_prefix}.", e.backtrace
+      end
+
+      # Verify that a downloaded module matches the checksum in the metadata for this release.
+      #
+      # @param path [Pathname]
+      # @return [void]
+      def verify(path)
+        expected_md5 = file_md5
+        file_md5     = Digest::MD5.file(path).hexdigest
+        if expected_md5 != file_md5
+          raise ChecksumMismatch.new("Expected #{path} checksum to be #{expected_md5}, got #{file_md5}")
         end
-        nil
       end
+
+      private
+
+      def file_url
+        "/v3/files/#{slug}.tar.gz"
+      end
+
+      def resource_url
+        "/v3/releases/#{slug}"
+      end
+
+      class ChecksumMismatch < StandardError
+      end
+
     end
   end
 end

data/lib/puppet_forge/v3/user.rb

@@ -7,6 +7,8 @@ module PuppetForge
     # Models a Forge user's account.
     class User < Base
 
+      include PuppetForge::LazyAccessors
+
       # Returns a collection of Modules owned by the user.
       #
       # @note Because there is no related module data in the record, we can't

data/lib/puppet_forge/version.rb

@@ -1,3 +1,3 @@
 module PuppetForge
-  VERSION = '1.0.6' # Library version
+  VERSION = '2.0.0' # Library version
 end

data/puppet_forge.gemspec

@@ -8,7 +8,8 @@ Gem::Specification.new do |spec|
   spec.version       = PuppetForge::VERSION
   spec.authors       = ["Puppet Labs"]
   spec.email         = ["forge-team+api@puppetlabs.com"]
-  spec.summary       = "Access and manipulate the Puppet Forge API from Ruby."
+  spec.summary       = "Access the Puppet Forge API from Ruby for resource information and to download releases."
+  spec.description   = %q{Tools that can be used to access Forge API information on Modules, Users, and Releases. As well as download, unpack, and install Releases to a directory.}
   spec.homepage      = "https://github.com/puppetlabs/forge-ruby"
   spec.license       = "Apache-2.0"
 
@@ -19,8 +20,10 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = '>= 1.9.3'
 
-  spec.add_runtime_dependency "activesupport", "~> 4.2"
-  spec.add_runtime_dependency "her", "~> 0.6.8"
+  spec.add_runtime_dependency "faraday", "~> 0.9.0"
+  spec.add_runtime_dependency "faraday_middleware", "~> 0.9.0"
+  spec.add_dependency 'semantic_puppet', '~> 0.1.0'
+  spec.add_dependency 'minitar'
 
   spec.add_development_dependency "bundler", "~> 1.6"
   spec.add_development_dependency "rake"

data/spec/fixtures/v3/modules/puppetlabs-apache.json

@@ -1,16 +1,19 @@
 {
   "uri": "/v3/modules/puppetlabs-apache",
+  "slug": "puppetlabs-apache",
   "name": "apache",
   "downloads": 81387,
   "created_at": "2010-05-20 22:43:19 -0700",
   "updated_at": "2014-01-06 14:42:07 -0800",
   "owner": {
     "uri": "/v3/users/puppetlabs",
+    "slug": "puppetlabs",
     "username": "puppetlabs",
     "gravatar_id": "fdd009b7c1ec96e088b389f773e87aec"
   },
   "current_release": {
     "uri": "/v3/releases/puppetlabs-apache-0.10.0",
+    "slug": "puppetlabs-apache-0.10.0",
     "module": {
       "uri": "/v3/modules/puppetlabs-apache",
       "name": "apache",
@@ -318,73 +321,90 @@
   "releases": [
     {
       "uri": "/v3/releases/puppetlabs-apache-0.10.0",
+      "slug": "puppetlabs-apache-0.10.0",
       "version": "0.10.0"
     },
     {
       "uri": "/v3/releases/puppetlabs-apache-0.9.0",
+      "slug": "puppetlabs-apache-0.9.0",
       "version": "0.9.0"
     },
     {
       "uri": "/v3/releases/puppetlabs-apache-0.8.1",
+      "slug": "puppetlabs-apache-0.8.1",
       "version": "0.8.1"
     },
     {
       "uri": "/v3/releases/puppetlabs-apache-0.8.0",
+      "slug": "puppetlabs-apache-0.8.0",
       "version": "0.8.0"
     },
     {
       "uri": "/v3/releases/puppetlabs-apache-0.7.0",
+      "slug": "puppetlabs-apache-0.7.0",
       "version": "0.7.0"
     },
     {
       "uri": "/v3/releases/puppetlabs-apache-0.6.0",
+      "slug": "puppetlabs-apache-0.6.0",
       "version": "0.6.0"
     },
     {
       "uri": "/v3/releases/puppetlabs-apache-0.5.0-rc1",
+      "slug": "puppetlabs-apache-0.5.0-rc1",
       "version": "0.5.0-rc1"
     },
     {
       "uri": "/v3/releases/puppetlabs-apache-0.4.0",
+      "slug": "puppetlabs-apache-0.4.0",
       "version": "0.4.0"
     },
     {
       "uri": "/v3/releases/puppetlabs-apache-0.3.0",
+      "slug": "puppetlabs-apache-0.3.0",
       "version": "0.3.0"
     },
     {
       "uri": "/v3/releases/puppetlabs-apache-0.2.2",
+      "slug": "puppetlabs-apache-0.2.2",
       "version": "0.2.2"
     },
     {
       "uri": "/v3/releases/puppetlabs-apache-0.2.1",
+      "slug": "puppetlabs-apache-0.2.1",
       "version": "0.2.1"
     },
     {
       "uri": "/v3/releases/puppetlabs-apache-0.2.0",
+      "slug": "puppetlabs-apache-0.2.0",
       "version": "0.2.0"
     },
     {
       "uri": "/v3/releases/puppetlabs-apache-0.1.1",
+      "slug": "puppetlabs-apache-0.1.1",
       "version": "0.1.1"
     },
     {
       "uri": "/v3/releases/puppetlabs-apache-0.0.4",
+      "slug": "puppetlabs-apache-0.0.4",
       "version": "0.0.4"
     },
     {
       "uri": "/v3/releases/puppetlabs-apache-0.0.3",
+      "slug": "puppetlabs-apache-0.0.3",
       "version": "0.0.3"
     },
     {
       "uri": "/v3/releases/puppetlabs-apache-0.0.2",
+      "slug": "puppetlabs-apache-0.0.2",
       "version": "0.0.2"
     },
     {
       "uri": "/v3/releases/puppetlabs-apache-0.0.1",
+      "slug": "puppetlabs-apache-0.0.1",
       "version": "0.0.1"
     }
   ],
   "homepage_url": "https://github.com/puppetlabs/puppetlabs-apache",
   "issues_url": "https://tickets.puppetlabs.com"
-}
+}