puppet_forge 1.0.6 → 2.0.0

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Change Log
+
+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/).i
+
+## v2.0.0 - 2015-08-13
+
+### Added
+
+* PuppetForge::V3::Release can now verify the md5, unpack, and install a release tarball.
+* PuppetForge::Middleware::SymbolifyJson to change Faraday response hash keys into symbols.
+* PuppetForge::V3::Metadata to represent a release's metadata as an object.
+* PuppetForge::Connection to provide Faraday connections.
+
+### Changed
+
+* Failed API requests, such as those for a module that doesn't exist, throw a Faraday::ResourceNotFound error.
+* API requests are sent through Faraday directly rather than through Her.
+* PuppetForge::V3::Base#where and PuppetForge::V3::Base#all now send an API request immediately and return a paginated collection.
+
+### Removed
+
+* Depency on Her (also removes dependency on ActiveSupport).

data/MAINTAINERS

@@ -0,0 +1,13 @@
+If you'd like to make a change to this library, you should contact at least one
+of the maintainers listed below. They will be able to discuss the change with
+you and decide the next best step. The maintainers will also be notified of pull
+requests as described in the README. This maintainers file should be kept up to
+date with the current maintainers of the project.
+
+If you need to contact the maintainers of this project you should email
+info@puppetlabs.com.
+
+Alex Dreyer, Puppet Labs
+Anderson Mills, Puppet Labs
+Jesse Scott, Puppet Labs
+

data/README.md

@@ -23,8 +23,8 @@ Or install it yourself as:
 
 ##Dependencies
 
-* [Her](http://her-rb.org) ~> 0.6
-* [Typhoeus](https://github.com/typhoeus/typhoeus) ~> 0.6 (optional)
+* [Faraday]() ~> 0.9.0
+* [Typhoeus](https://github.com/typhoeus/typhoeus) ~> 0.7.0 (optional)
 
 Typhoeus will be used as the HTTP adapter if it is available, otherwise
 Net::HTTP will be used. We recommend using Typhoeus for production-level
@@ -78,12 +78,13 @@ resource model are documented on the [Resource Reference][resource_ref] page.
 
 ###Basic Interface
 
-Each of the models uses [Her](http://her-rb.org) (an ActiveRecord-like REST
-library) to map over the Forge API endpoints. Most simple ActiveRecord-style
-interactions function as intended.
+Each of the models uses ActiveRecord-like REST functionality to map over the Forge API endpoints.
+Most simple ActiveRecord-style interactions function as intended.
 
 Currently, only unauthenticated read-only actions are supported.
 
+The methods find, where, and all immediately make one API request.
+
 ``` ruby
 # Find a Resource by Slug
 PuppetForge::User.find('puppetlabs') # => #<Forge::V3::User(/v3/users/puppetlabs)>
@@ -92,10 +93,50 @@ PuppetForge::User.find('puppetlabs') # => #<Forge::V3::User(/v3/users/puppetlabs
 PuppetForge::Module.all # See "Paginated Collections" below for important info about enumerating resource sets.
 
 # Find Resources with Conditions
-PuppetForge::Module.where(query: 'apache').all # See "Paginated Collections" below for important info about enumerating resource sets.
+PuppetForge::Module.where(query: 'apache') # See "Paginated Collections" below for important info about enumerating resource sets.
 PuppetForge::Module.where(query: 'apache').first # => #<Forge::V3::Module(/v3/modules/puppetlabs-apache)>
 ```
 
+For compatibility with older versions of the puppet_forge gem, the following two methods are functionally equivalent.
+
+``` ruby
+PuppetForge::Module.where(query: 'apache')
+PuppetForge::Module.where(query: 'apache').all # This method is deprecated and not recommended
+```
+
+####Errors
+
+All API Requests (whether via find, where, or all) will raise a Faraday::ResourceNotFound error if the request fails.
+
+
+###Installing a Release
+
+A release tarball can be downloaded and installed by following the steps below.
+
+``` ruby
+release_slug = "puppetlabs-apache-1.6.0"
+release_tarball = release_slug + ".tar.gz"
+dest_dir = "/path/to/install/directory"
+tmp_dir = "/path/to/tmpdir"
+
+# Fetch Release information from API
+# @raise Faraday::ResourceNotFound error if the given release does not exist
+release = PuppetForge::Release.find release_slug
+
+# Download the Release tarball
+# @raise PuppetForge::ReleaseNotFound error if the given release does not exist
+release.download(Pathname(release_tarball))
+
+# Verify the MD5
+# @raise PuppetForge::V3::Release::ChecksumMismatch error if the file's md5 does not match the API information
+release.verify(Pathname(release_tarball))
+
+# Unpack the files to a given directory
+# @raise RuntimeError if it fails to extract the contents of the release tarball
+PuppetForge::Unpacker.unpack(release_tarball, dest_dir, tmp_dir)
+```
+
+
 ###Paginated Collections
 
 The Forge API only returns paginated collections as of v3.
@@ -170,3 +211,4 @@ to create a free account to add new tickets.
 
 * Pieter van de Bruggen, Puppet Labs
 * Jesse Scott, Puppet Labs
+* Austin Blatt, Puppet Labs

data/lib/puppet_forge.rb

@@ -8,8 +8,12 @@ module PuppetForge
 
   self.host = 'https://forgeapi.puppetlabs.com'
 
+  require 'puppet_forge/tar'
+  require 'puppet_forge/unpacker'
   require 'puppet_forge/v3'
 
+  const_set :Metadata, PuppetForge::V3::Metadata
+
   const_set :User, PuppetForge::V3::User
   const_set :Module, PuppetForge::V3::Module
   const_set :Release, PuppetForge::V3::Release

data/lib/puppet_forge/connection.rb

@@ -0,0 +1,81 @@
+require 'puppet_forge/connection/connection_failure'
+
+require 'faraday'
+require 'faraday_middleware'
+require 'puppet_forge/middleware/symbolify_json'
+
+module PuppetForge
+  # Provide a common mixin for adding a HTTP connection to classes.
+  #
+  # This module provides a common method for creating HTTP connections as well
+  # as reusing a single connection object between multiple classes. Including
+  # classes can invoke #conn to get a reasonably configured HTTP connection.
+  # Connection objects can be passed with the #conn= method.
+  #
+  # @example
+  #   class HTTPThing
+  #     include PuppetForge::Connection
+  #   end
+  #   thing = HTTPThing.new
+  #   thing.conn = thing.make_connection('https://non-standard-forge.site')
+  #
+  # @api private
+  module Connection
+
+    attr_writer :conn
+
+    USER_AGENT = "#{PuppetForge.user_agent} PuppetForge.gem/#{PuppetForge::VERSION} Faraday/#{Faraday::VERSION} Ruby/#{RUBY_VERSION}-p#{RUBY_PATCHLEVEL} (#{RUBY_PLATFORM})".strip
+
+    def self.authorization=(token)
+      @authorization = token
+    end
+
+    def self.authorization
+      @authorization
+    end
+
+    # @return [Faraday::Connection] An existing Faraday connection if one was
+    #   already set, otherwise a new Faraday connection.
+    def conn
+      @conn ||= default_connection
+    end
+
+    def default_connection
+
+      begin
+        # Use Typhoeus if available.
+        Gem::Specification.find_by_name('typhoeus', '~> 0.6')
+        require 'typhoeus/adapters/faraday'
+        adapter = :typhoeus
+      rescue Gem::LoadError
+        adapter = Faraday.default_adapter
+      end
+
+      make_connection(PuppetForge.host, [adapter])
+    end
+    module_function :default_connection
+
+    # Generate a new Faraday connection for the given URL.
+    #
+    # @param url [String] the base URL for this connection
+    # @return [Faraday::Connection]
+    def make_connection(url, adapter_args = nil, opts = {})
+      adapter_args ||= [Faraday.default_adapter]
+      options = { :headers => { :user_agent => USER_AGENT } }.merge(opts)
+
+      if token = PuppetForge::Connection.authorization
+        options[:headers][:authorization] = token
+      end
+
+      Faraday.new(url, options) do |builder|
+        builder.use PuppetForge::Middleware::SymbolifyJson
+        builder.response(:json, :content_type => /\bjson$/)
+        builder.response(:raise_error)
+        builder.use(:connection_failure)
+
+        builder.adapter(*adapter_args)
+      end
+    end
+    module_function :make_connection
+  end
+end

data/lib/puppet_forge/connection/connection_failure.rb

@@ -0,0 +1,26 @@
+require 'faraday'
+
+module PuppetForge
+  module Connection
+    # Wrap Faraday connection failures to include the host and optional proxy
+    # in use for the failed connection.
+    class ConnectionFailure < Faraday::Middleware
+      def call(env)
+        @app.call(env)
+      rescue Faraday::ConnectionFailed => e
+        baseurl = env[:url].dup
+        baseurl.path = ''
+        errmsg = "Unable to connect to #{baseurl.to_s}"
+        if proxy = env[:request][:proxy]
+          errmsg << " (using proxy #{proxy.uri.to_s})"
+        end
+        errmsg << ": #{e.message}"
+        m = Faraday::ConnectionFailed.new(errmsg)
+        m.set_backtrace(e.backtrace)
+        raise m
+      end
+    end
+  end
+end
+
+Faraday::Middleware.register_middleware(:connection_failure => lambda { PuppetForge::Connection::ConnectionFailure })

data/lib/puppet_forge/error.rb

@@ -0,0 +1,34 @@
+module PuppetForge
+  class Error < RuntimeError
+    attr_accessor :original
+    def initialize(message, original=nil)
+      super(message)
+      @original = original
+    end
+  end
+
+  class ExecutionFailure < PuppetForge::Error
+  end
+
+  class InvalidPathInPackageError < PuppetForge::Error
+    def initialize(options)
+      @entry_path = options[:entry_path]
+      @directory  = options[:directory]
+      super "Attempt to install file into #{@entry_path.inspect} under #{@directory.inspect}"
+    end
+
+    def multiline
+      <<-MSG.strip
+Could not install package
+  Package attempted to install file into
+  #{@entry_path.inspect} under #{@directory.inspect}.
+      MSG
+    end
+  end
+
+  class ModuleNotFound < PuppetForge::Error
+  end
+
+  class ReleaseNotFound < PuppetForge::Error
+  end
+end

data/lib/{her → puppet_forge}/lazy_accessors.rb

@@ -1,18 +1,12 @@
-# Her is an ORM for RESTful APIs, instead of databases.
-# @see http://her-rb.org/
-module Her
-
-  # ActiveRecord-like interface for RESTful models.
-  # @see http://her-rb.org/#usage/activerecord-like-methods
-  module Model; end
+module PuppetForge
 
   # When dealing with a remote service, it's reasonably common to receive only
   # a partial representation of the underlying object, with additional data
-  # available upon request. {Her}, by default, provides a convenient interface
+  # available upon request. PuppetForge, by default, provides a convenient interface
   # for accessing whatever local data is available, but lacks good support for
   # fleshing out partial representations. In order to build a seamless
   # interface for both local and remote attriibutes, this module replaces the
-  # default behavior of {Her::Model}s with an "updatable" interface.
+  # default behavior with an "updatable" interface.
   module LazyAccessors
 
     # Callback for module inclusion.
@@ -28,19 +22,25 @@ module Her
       end
     end
 
-    # Override the default {Her::Model}#inspect behavior.
+    # Provide class name for object
+    #
+    def class_name
+      self.class.name.split("::").last.downcase
+    end
+
+    # Override the default #inspect behavior.
     #
     # The original behavior actually invokes each attribute accessor, which can
     # be somewhat problematic when the accessors have been overridden. This
     # implementation simply reports the contents of the attributes hash.
     def inspect
       attrs = attributes.map do |x, y|
-        [ x, attribute_for_inspect(y) ].join('=')
+        [ x, y ].join('=')
       end
-      "#<#{self.class}(#{request_path}) #{attrs.join(' ')}>"
+      "#<#{self.class}(#{uri}) #{attrs.join(' ')}>"
     end
 
-    # Override the default {Her::Model}#method_misssing behavior.
+    # Override the default #method_misssing behavior.
     #
     # When we receive a {#method_missing} call, one of three things is true:
     # - the caller is looking up a piece of local data without an accessor
@@ -81,22 +81,15 @@ module Her
       return self if @_fetch
 
       klass = self.class
-      params = { :_method => klass.method_for(:find), :_path => self.request_path }
 
-      klass.request(params) do |data, response|
-        if @_fetch = response.success?
-          parsed = klass.parse(data[:data])
-          parsed.merge!(:_metadata => data[:metadata], :_errors => data[:errors])
-
-          self.send(:initialize, parsed)
-          self.run_callbacks(:find)
-        end
+      response = klass.request("#{self.class_name}s/#{self.slug}")
+      if @_fetch = response.success?
+        self.send(:initialize, response.body)
       end
 
       return self
     end
 
-
     # A Module subclass for attribute accessors.
     class AccessorContainer < Module
 
@@ -117,19 +110,19 @@ module Her
       # @return [void]
       def add_attributes(keys)
         keys.each do |key|
-          next if methods.include?(name = :"#{key}")
+          next if methods.include?(name = key)
 
-          define_method(name) do
+          define_method("#{name}") do
             fetch unless has_attribute?(name)
             attribute(name)
           end
 
-          define_method(:"#{name}?") do
+          define_method("#{name}?") do
             fetch unless has_attribute?(name)
             has_attribute?(name)
           end
 
-          define_method(:"#{name}=") do |value|
+          define_method("#{name}=") do |value|
             fetch unless has_attribute?(name)
             attributes[name] = value
           end

data/lib/{her → puppet_forge}/lazy_relations.rb

@@ -1,4 +1,4 @@
-module Her
+module PuppetForge
 
   # This module provides convenience accessors for related resources. Related
   # classes will include {LazyAccessors}, allowing them to transparently fetch
@@ -11,9 +11,24 @@ module Her
     # @private
     def self.included(base)
       base.extend(self)
-      base.after_initialize { @_lazy = {} }
     end
 
+    def parent
+      if self.is_a? Class
+        class_name = self.name
+      else
+        class_name = self.class.name
+      end
+
+      # Get the name of the version module
+      version = class_name.split("::")[-2]
+
+      if version.nil?
+        raise RuntimeError, "Unable to determine the parent PuppetForge version module"
+      end
+
+      PuppetForge.const_get(version)
+    end
     # @!macro [attach] lazy
     #   @!method $1
     #     Returns a lazily-loaded $1 proxy. To eagerly load this $1, call
@@ -32,16 +47,19 @@ module Her
     # @param name [Symbol] the name of the lazy attribute
     # @param class_name [#to_s] the lazy relation's class name
     def lazy(name, class_name = name)
-      parent = self.parent
       klass = (class_name.is_a?(Class) ? class_name : nil)
-      class_name = "#{class_name}".singularize.classify
+      class_name = "#{class_name}"
 
       define_method(name) do
+        @_lazy ||= {}
+
         @_lazy[name] ||= begin
+
           klass ||= parent.const_get(class_name)
-          klass.send(:include, Her::LazyAccessors)
+
+          klass.send(:include, PuppetForge::LazyAccessors)
           fetch unless has_attribute?(name)
-          value = attribute(name)
+          value = attributes[name]
           klass.new(value) if value
         end
       end
@@ -69,14 +87,15 @@ module Her
     # @param name [Symbol] the name of the lazy collection attribute
     # @param class_name [#to_s] the lazy relation's class name
     def lazy_collection(name, class_name = name)
-      parent = self.parent
       klass = (class_name.is_a?(Class) ? class_name : nil)
-      class_name = "#{class_name}".singularize.classify
+      class_name = "#{class_name}"
 
       define_method(name) do
+        @_lazy ||= {}
+
         @_lazy[name] ||= begin
           klass ||= parent.const_get(class_name)
-          klass.send(:include, Her::LazyAccessors)
+          klass.send(:include, PuppetForge::LazyAccessors)
           fetch unless has_attribute?(name)
           (attribute(name) || []).map { |x| klass.new(x) }
         end