puppet_forge 1.0.0

data/.gitignore

@@ -0,0 +1,22 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in puppet_forge.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,13 @@
+Copyright (c) 2014 Puppet Labs, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.md

@@ -0,0 +1,172 @@
+#Puppet Forge
+
+Access and manipulate the [Puppet Forge API](https://forgeapi.puppetlabs.com)
+from Ruby.
+
+##Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'puppet_forge'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install puppet_forge
+
+##Requirements
+
+* Ruby >= 1.9.3
+
+##Dependencies
+
+* [Her](http://her-rb.org) ~> 0.6
+* [Typhoeus](https://github.com/typhoeus/typhoeus) ~> 0.6 (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
+applications.
+
+##Usage
+
+First, make sure you have imported the Puppet Forge gem into your application:
+
+``` ruby
+require 'puppet_forge'
+```
+
+Next, supply a user-agent string to identify requests sent by your application
+to the Puppet Forge API:
+
+``` ruby
+PuppetForge.user_agent = "MyApp/1.0.0"
+```
+
+Now you can make use of the resource models defined by the gem:
+
+* [PuppetForge::V3::User][user_ref]
+* [PuppetForge::V3::Module][module_ref]
+* [PuppetForge::V3::Release][release_ref]
+
+For convenience, these classes are also aliased as:
+
+* [PuppetForge::User][user_ref]
+* [PuppetForge::Module][module_ref]
+* [PuppetForge::Release][release_ref]
+
+[user_ref]: https://github.com/puppetlabs/forge-ruby/wiki/Resource-Reference#puppetforgeuser
+[module_ref]: https://github.com/puppetlabs/forge-ruby/wiki/Resource-Reference#puppetforgemodule
+[release_ref]: https://github.com/puppetlabs/forge-ruby/wiki/Resource-Reference#puppetforgerelease
+
+__The aliases will always point to the most modern API implementations for each
+model.__ You may also use the fully qualified class names
+(e.g. PuppetForge::V3::User) to ensure your code is forward compatible.
+
+See the [Basic Interface](#basic-interface) section below for how to perform
+common tasks with these models.
+
+Please note that PuppetForge models are identified by unique slugs rather
+than numerical identifiers.
+
+The slug format, properties, associations, and methods available on each
+resource model are documented on the [Resource Reference][resource_ref] page.
+
+[resource_ref]: https://github.com/puppetlabs/forge-ruby/wiki/Resource-Reference
+
+###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.
+
+Currently, only unauthenticated read-only actions are supported.
+
+``` ruby
+# Find a Resource by Slug
+PuppetForge::User.find('puppetlabs') # => #<Forge::V3::User(/v3/users/puppetlabs)>
+
+# Find All Resources
+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').first # => #<Forge::V3::Module(/v3/modules/puppetlabs-apache)>
+```
+
+###Paginated Collections
+
+The Forge API only returns paginated collections as of v3.
+
+``` ruby
+PuppetForge::Module.all.total # => 1728
+PuppetForge::Module.all.length # => 20
+```
+
+Movement through the collection can be simulated using the `limit` and `offset`
+parameters, but it's generally preferable to leverage the pagination links
+provided by the API. For convenience, pagination links are exposed by the
+library.
+
+``` ruby
+PuppetForge::Module.all.offset # => 0
+PuppetForge::Module.all.next_url # => "/v3/modules?limit=20&offset=20"
+PuppetForge::Module.all.next.offset # => 20
+```
+
+An enumerator exists for iterating over the entire (unpaginated) collection.
+Keep in mind that this will result in multiple calls to the Forge API.
+
+``` ruby
+PuppetForge::Module.where(query: 'php').total # => 37
+PuppetForge::Module.where(query: 'php').unpaginated # => #<Enumerator>
+PuppetForge::Module.where(query: 'php').unpaginated.to_a.length # => 37
+```
+
+###Associations & Lazy Attributes
+
+Associated models are accessible in the API by property name.
+
+``` ruby
+PuppetForge::Module.find('puppetlabs-apache').owner # => #<Forge::V3::User(/v3/users/puppetlabs)>
+```
+
+Properties of associated models are then loaded lazily.
+
+``` ruby
+user = PuppetForge::Module.find('puppetlabs-apache').owner
+
+# This does not trigger a request
+user.username # => "puppetlabs"
+
+# This *does* trigger a request
+user.created_at # => "2010-05-19 05:46:26 -0700"
+```
+
+##Caveats
+
+This library currently does no response caching of its own, instead opting to
+re-issue every request each time. This will be changed in a later release.
+
+##Reporting Issues
+
+Please report problems, issues, and feature requests on the public
+[Puppet Labs issue tracker][issues] under the FORGE project. You will need
+to create a free account to add new tickets.
+
+[issues]: https://tickets.puppetlabs.com/browse/FORGE
+
+##Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/forge-ruby/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+##Contributors
+
+* Pieter van de Bruggen, Puppet Labs
+* Jesse Scott, Puppet Labs

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/lib/her/lazy_accessors.rb

@@ -0,0 +1,140 @@
+# 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
+
+  # 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
+  # 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.
+  module LazyAccessors
+
+    # Callback for module inclusion.
+    #
+    # On each lazy class we'll store a reference to a Module, which will act as
+    # the container for the attribute methods.
+    #
+    # @param base [Class] the Class this module was included into
+    # @return [void]
+    def self.included(base)
+      base.singleton_class.class_eval do
+        attr_accessor :_accessor_container
+      end
+    end
+
+    # Override the default {Her::Model}#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('=')
+      end
+      "#<#{self.class}(#{request_path}) #{attrs.join(' ')}>"
+    end
+
+    # Override the default {Her::Model}#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
+    # - the caller is looking up a piece of remote data
+    # - the method doesn't actually exist
+    #
+    # To solve the remote case, we begin by ensuring our attribute list is
+    # up-to-date with a call to {#fetch}, create a new {AccessorContainer} if
+    # necessary, and add any missing accessors to the container. We can then
+    # dispatch the method call to the newly created accessor.
+    #
+    # The local case is almost identical, except that we can skip updating the
+    # model's attributes.
+    #
+    # If, after our work, we haven't seen the requested method name, we can
+    # surmise that it doesn't actually exist, and pass the call along to
+    # upstream handlers.
+    def method_missing(name, *args, &blk)
+      fetch unless has_attribute?(name.to_s[/\w+/])
+
+      klass = self.class
+      mod = (klass._accessor_container ||= AccessorContainer.new(klass))
+      mod.add_attributes(attributes.keys)
+
+      if (meth = mod.instance_method(name) rescue nil)
+        return meth.bind(self).call(*args)
+      else
+        return super(name, *args, &blk)
+      end
+    end
+
+    # Updates model data from the API. This method will short-circuit if this
+    # model has already been fetched from the remote server, to avoid duplicate
+    # requests.
+    #
+    # @return [self]
+    def fetch
+      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
+      end
+
+      return self
+    end
+
+
+    # A Module subclass for attribute accessors.
+    class AccessorContainer < Module
+
+      # Creating a new instance of this class will automatically include itself
+      # into the provided class.
+      #
+      # @param base [Class] the class this container belongs to
+      def initialize(base)
+        base.send(:include, self)
+      end
+
+      # Adds attribute accessors, predicates, and mutators for the named keys.
+      # Since these methods will also be instantly available on all instances
+      # of the parent class, each of these methods will also conservatively
+      # {LazyAccessors#fetch} any missing data.
+      #
+      # @param keys [Array<#to_s>] the list of attributes to create
+      # @return [void]
+      def add_attributes(keys)
+        keys.each do |key|
+          next if methods.include?(name = :"#{key}")
+
+          define_method(name) do
+            fetch unless has_attribute?(name)
+            attribute(name)
+          end
+
+          define_method(:"#{name}?") do
+            fetch unless has_attribute?(name)
+            has_attribute?(name)
+          end
+
+          define_method(:"#{name}=") do |value|
+            fetch unless has_attribute?(name)
+            attributes[name] = value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/her/lazy_relations.rb

@@ -0,0 +1,86 @@
+module Her
+
+  # This module provides convenience accessors for related resources. Related
+  # classes will include {LazyAccessors}, allowing them to transparently fetch
+  # fetch more complete representations from the API.
+  #
+  # @see LazyAccessors
+  module LazyRelations
+
+    # Mask mistaken `include` calls by transparently extending this class.
+    # @private
+    def self.included(base)
+      base.extend(self)
+      base.after_initialize { @_lazy = {} }
+    end
+
+    # @!macro [attach] lazy
+    #   @!method $1
+    #     Returns a lazily-loaded $1 proxy. To eagerly load this $1, call
+    #     #fetch.
+    #     @return a proxy for the related $1
+    #
+    # Declares a new lazily loaded property.
+    #
+    # This is particularly useful since our data hashes tend to contain at
+    # least a partial representation of the related object. This mechanism
+    # provides a proxy object which will avoid making HTTP requests until
+    # it is asked for a property it does not contain, at which point it
+    # will fetch the related object from the API and look up the property
+    # from there.
+    #
+    # @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
+
+      define_method(name) do
+        @_lazy[name] ||= begin
+          klass ||= parent.const_get(class_name)
+          klass.send(:include, Her::LazyAccessors)
+          fetch unless has_attribute?(name)
+          value = attribute(name)
+          klass.new(value) if value
+        end
+      end
+    end
+
+    # @!macro [attach] lazy_collection
+    #   @!method $1
+    #     Returns a lazily-loaded proxy for a collection of $1. To eagerly
+    #     load any one of these $1, call #fetch.
+    #     @return [Array<$2>] a proxy for the related collection of $1
+    #
+    # Declares a new lazily loaded collection.
+    #
+    # This behaves like {#lazy}, with the exception that the underlying
+    # attribute is an array of property hashes, representing several
+    # distinct models. In this case, we return an array of proxy objects,
+    # one for each property hash.
+    #
+    # It's also worth pointing out that this is not a paginated collection.
+    # Since the array of property hashes we're wrapping is itself
+    # unpaginated and complete (if shallow), wrapping it in a paginated
+    # collection doesn't provide any semantic value.
+    #
+    # @see LazyRelations
+    # @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
+
+      define_method(name) do
+        @_lazy[name] ||= begin
+          klass ||= parent.const_get(class_name)
+          klass.send(:include, Her::LazyAccessors)
+          fetch unless has_attribute?(name)
+          (attribute(name) || []).map { |x| klass.new(x) }
+        end
+      end
+    end
+  end
+end

data/lib/puppet_forge.rb

@@ -0,0 +1,19 @@
+require 'bundler/setup'
+require 'backports/1.9.1/enumerator/new' if RUBY_VERSION == '1.8.7'
+
+require 'puppet_forge/version'
+
+module PuppetForge
+  class << self
+    attr_accessor :user_agent
+    attr_accessor :host
+  end
+
+  self.host = 'https://forgeapi.puppetlabs.com'
+
+  require 'puppet_forge/v3'
+
+  const_set :User, PuppetForge::V3::User
+  const_set :Module, PuppetForge::V3::Module
+  const_set :Release, PuppetForge::V3::Release
+end