aptible-resource 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 953b5ea9c2b350a3b37e7bc3b1125fd1962e7628
+  data.tar.gz: 01317c3f36bd2061be1a95e95b1995f1c0d096d9
+SHA512:
+  metadata.gz: 7015d0822a8d50f48248610da1f89a894e5228bbd8a5618b84a202ccb96170b9af8f866b343bd94c27ea22b9841b63f8ff07078d40343746794869ba9ba7ab68
+  data.tar.gz: cf190060c67bb26f41340340de34ec0620c6887e793e14633e49386ae1a7cb7978249dbf2656f79b03076de1519510a6db58359ade13fa1ce929f7c7be0f2aef

data/.gitignore

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

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/.rubocop.yml

@@ -0,0 +1,22 @@
+Documentation:
+  Enabled: false
+
+Encoding:
+  Enabled: false
+
+DoubleNegation:
+  Enabled: false
+
+AllCops:
+  Include:
+    - !ruby/regexp /\.rb$/
+    - !ruby/regexp /\.rake$/
+    - !ruby/regexp /\.gemspec$/
+    - !ruby/regexp /Rakefile$/
+  Exclude:
+    # Exclude line length check from autogenerated files
+    - !ruby/regexp /\/db\/schema\.rb$/
+    - !ruby/regexp /node_modules\//
+    - !ruby/regexp /tmp\//
+    - !ruby/regexp /vendor\//
+    - !ruby/regexp /hyper_resource/

data/.travis.yml

@@ -0,0 +1,3 @@
+rvm:
+  - 2.0.0
+  - jruby

data/Gemfile

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

data/LICENSE.md

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Aptible, Inc.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,52 @@
+# ![](https://raw.github.com/aptible/straptible/master/lib/straptible/rails/templates/public.api/icon-60px.png) Aptible::Resource
+
+[![Gem Version](https://badge.fury.io/rb/aptible-resource.png)](https://rubygems.org/gems/aptible-resource)
+[![Build Status](https://travis-ci.org/aptible/aptible-resource.png?branch=master)](https://travis-ci.org/aptible/aptible-resource)
+[![Dependency Status](https://gemnasium.com/aptible/aptible-resource.png)](https://gemnasium.com/aptible/aptible-resource)
+
+Foundation classes for Aptible resource server gems.
+
+## Usage
+
+To build a new resource server gem on top of `aptible-resource`, create a top-level class for your resource server. For example:
+
+```ruby
+module Example
+  module Api
+    class Resource < Aptible::Resource::Base
+      def namespace
+        'Example::Api'
+      end
+
+      def root_url
+        'https://api.example.com'
+      end
+    end
+  end
+end
+```
+
+Then add the gem to your gemspec:
+
+```ruby
+spec.add_dependency 'aptible-resource'
+```
+
+## Development
+
+This gem depends on a vendored version of [HyperResource](https://github.com/gamache/hyperresource), which can be updated from a local checkout of HyperResource as follows:
+
+    cp -rp /path/to/hyperresource/lib/hyper_resource* lib/
+
+## Contributing
+
+1. Fork the project.
+1. Commit your changes, with specs.
+1. Ensure that your code passes specs (`rake spec`) and meets Aptible's Ruby style guide (`rake rubocop`).
+1. Create a new pull request on GitHub.
+
+## Copyright and License
+
+MIT License, see [LICENSE](LICENSE.md) for details.
+
+Copyright (c) 2014 [Aptible](https://www.aptible.com), Frank Macreery, and contributors.

data/Rakefile

@@ -0,0 +1,4 @@
+require 'bundler/gem_tasks'
+
+require 'aptible/tasks'
+Aptible::Tasks.load_tasks

data/aptible-resource.gemspec

@@ -0,0 +1,35 @@
+# encoding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'English'
+require 'aptible/resource/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'aptible-resource'
+  spec.version       = Aptible::Resource::VERSION
+  spec.authors       = ['Frank Macreery']
+  spec.email         = ['frank@macreery.com']
+  spec.description   = %q(Foundation classes for Aptible resource server gems)
+  spec.summary       = %q(Foundation classes for Aptible resource server gems)
+  spec.homepage      = 'https://github.com/aptible/aptible-resource'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files`.split($RS)
+  spec.test_files    = spec.files.grep(/^spec\//)
+  spec.require_paths = ['lib']
+
+  # HyperResource dependencies
+  spec.add_dependency 'uri_template', '>= 0.5.2'
+  spec.add_dependency 'faraday',      '>= 0.8.6'
+  spec.add_dependency 'json'
+
+  spec.add_dependency 'fridge'
+  spec.add_dependency 'activesupport'
+
+  spec.add_development_dependency 'bundler', '~> 1.6'
+  spec.add_development_dependency 'aptible-tasks'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec', '~> 2.0'
+  spec.add_development_dependency 'pry'
+end

data/lib/aptible/resource.rb

@@ -0,0 +1,7 @@
+require 'aptible/resource/version'
+require 'aptible/resource/base'
+
+module Aptible
+  module Resource
+  end
+end

data/lib/aptible/resource/adapter.rb

@@ -0,0 +1,19 @@
+module Aptible
+  module Resource
+    class Adapter < HyperResource::Adapter::HAL_JSON
+      class << self
+        def get_data_type_from_object(object)
+          return nil unless object
+
+          if (type = object['_type'])
+            if type.respond_to?(:camelize)
+              type.camelize
+            else
+              type[0].upcase + type[1..-1]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aptible/resource/base.rb

@@ -0,0 +1,70 @@
+require 'fridge'
+
+# Require vendored HyperResource
+$LOAD_PATH.unshift File.expand_path('../..', __FILE__)
+require 'hyper_resource'
+
+require 'aptible/resource/adapter'
+require 'aptible/resource/model'
+
+module Aptible
+  module Resource
+    class Base < HyperResource
+      include Model
+
+      attr_accessor :token
+
+      def self.get_data_type_from_response(response)
+        return nil unless response && response.body
+        adapter.get_data_type_from_object(adapter.deserialize(response.body))
+      end
+
+      def self.adapter
+        Aptible::Resource::Adapter
+      end
+
+      def initialize(options = {})
+        if options.is_a?(Hash)
+          self.token = options[:token]
+
+          options[:root] ||= root_url
+          options[:namespace] ||= namespace
+          options[:headers] ||= { 'Content-Type' => 'application/json' }
+          options[:headers].merge!(
+            'Authorization' => "Bearer #{bearer_token}"
+          ) if options[:token]
+        end
+
+        super(options)
+      end
+
+      def adapter
+        self.class.adapter
+      end
+
+      def namespace
+        fail 'Resource server namespace must be defined by subclass'
+      end
+
+      def root_url
+        fail 'Resource server root URL must be defined by subclass'
+      end
+
+      def find_by_url(url_or_href)
+        resource = dup
+        resource.href = url_or_href.gsub(/^#{root}/, '')
+        resource.get
+      end
+
+      def bearer_token
+        case token
+        when Aptible::Resource::Base then token.access_token
+        when Fridge::AccessToken then token.to_s
+        when String then token
+        end
+      end
+    end
+  end
+end
+
+require 'aptible/resource/token'

data/lib/aptible/resource/model.rb

@@ -0,0 +1,115 @@
+require 'active_support/inflector'
+
+module Aptible
+  module Resource
+    module Model
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      module ClassMethods
+        def collection_href
+          "/#{basename}"
+        end
+
+        def basename
+          name.split('::').last.downcase.pluralize
+        end
+
+        def all(options = {})
+          resource = find_by_url(collection_href, options)
+          return [] unless resource
+          resource.send(basename).entries
+        end
+
+        def find(id, options = {})
+          find_by_url("#{collection_href}/#{id}", options)
+        end
+
+        def find_by_url(url, options = {})
+          # REVIEW: Should exception be raised if return type mismatch?
+          new(options).find_by_url(url)
+        rescue HyperResource::ClientError => e
+          if e.response.status == 404
+            return nil
+          else
+            raise e
+          end
+        end
+
+        def create(params)
+          token = params.delete(:token)
+          resource = new(token: token)
+          resource.send(basename).create(normalize_params(params))
+        end
+
+        # rubocop:disable PredicateName
+        def has_many(relation)
+          define_has_many_getter(relation)
+          define_has_many_setter(relation)
+        end
+        # rubocop:enable PredicateName
+
+        def belongs_to(relation)
+          define_method relation do
+            get unless loaded
+            if (memoized = instance_variable_get("@#{relation}"))
+              memoized
+            elsif links[relation]
+              instance_variable_set("@#{relation}", links[relation].get)
+            end
+          end
+        end
+
+        # rubocop:disable PredicateName
+        def has_one(relation)
+          # Better than class << self + alias_method?
+          belongs_to(relation)
+        end
+        # rubocop:enable PredicateName
+
+        def define_has_many_getter(relation)
+          define_method relation do
+            get unless loaded
+            if (memoized = instance_variable_get("@#{relation}"))
+              memoized
+            elsif links[relation]
+              instance_variable_set("@#{relation}", links[relation].entries)
+            end
+          end
+        end
+
+        def define_has_many_setter(relation)
+          define_method "create_#{relation.to_s.singularize}" do |params = {}|
+            get unless loaded
+            links[relation].create(self.class.normalize_params(params))
+          end
+        end
+
+        def normalize_params(params = {})
+          params_array = params.map do |key, value|
+            value.is_a?(HyperResource) ? [key, value.href] : [key, value]
+          end
+          Hash[params_array]
+        end
+      end
+
+      def delete
+        # HyperResource/Faraday choke on empty response bodies
+        super
+      rescue HyperResource::ResponseError
+        nil
+      end
+      alias_method :destroy, :delete
+
+      def update(params)
+        super(self.class.normalize_params(params))
+      end
+
+      # NOTE: The following does not update the object in-place
+      def reload
+        self.class.find_by_url(href, headers: headers)
+      end
+    end
+  end
+end

data/lib/aptible/resource/token.rb

@@ -0,0 +1,10 @@
+require 'aptible/resource/base'
+
+# Skeleton class for token implementations to inherit from
+module Aptible
+  module Resource
+    class Token < Base
+      attr_accessor :access_token
+    end
+  end
+end

data/lib/aptible/resource/version.rb

@@ -0,0 +1,5 @@
+module Aptible
+  module Resource
+    VERSION = '0.1.0'
+  end
+end

data/lib/hyper_resource.rb

@@ -0,0 +1,302 @@
+require 'hyper_resource/attributes'
+require 'hyper_resource/exceptions'
+require 'hyper_resource/link'
+require 'hyper_resource/links'
+require 'hyper_resource/objects'
+require 'hyper_resource/response'
+require 'hyper_resource/version'
+
+require 'hyper_resource/adapter'
+require 'hyper_resource/adapter/hal_json'
+
+require 'hyper_resource/modules/http'
+require 'hyper_resource/modules/internal_attributes'
+
+require 'rubygems' if RUBY_VERSION[0..2] == '1.8'
+
+require 'pp'
+
+## HyperResource is the main resource base class.  Normally it will be used
+## through subclassing, though it may also be used directly.
+
+class HyperResource
+
+  include HyperResource::Modules::HTTP
+  include HyperResource::Modules::InternalAttributes
+  include Enumerable
+
+private
+
+  DEFAULT_HEADERS = { 'Accept' => 'application/json' }
+
+public
+
+  ## Create a new HyperResource, given a hash of options.  These options
+  ## include:
+  ##
+  ## [root]  The root URL of the resource.
+  ##
+  ## [auth]  Authentication information.  Currently only +{basic:
+  ##         ['key', 'secret']}+ is supported.
+  ##
+  ## [namespace] Class or class name, into which resources should be
+  ##             instantiated.
+  ##
+  ## [headers] Headers to send along with requests for this resource (as
+  ##           well as its eventual child resources, if any).
+  ##
+  ## [faraday_options] Configuration passed to +Faraday::Connection.initialize+,
+  ##                   such as +{request: {timeout: 30}}+.
+  ##
+  def initialize(opts={})
+    return init_from_resource(opts) if opts.kind_of?(HyperResource)
+
+    self.root       = opts[:root] || self.class.root
+    self.href       = opts[:href] || ''
+    self.auth       = (self.class.auth || {}).merge(opts[:auth] || {})
+    self.namespace  = opts[:namespace] || self.class.namespace
+    self.headers    = DEFAULT_HEADERS.merge(self.class.headers || {}).
+                                      merge(opts[:headers]     || {})
+    self.faraday_options = opts[:faraday_options] ||
+                               self.class.faraday_options || {}
+
+    ## There's a little acrobatics in getting Attributes, Links, and Objects
+    ## into the correct subclass.
+    if self.class != HyperResource
+      if self.class::Attributes == HyperResource::Attributes
+        Object.module_eval(
+          "class #{self.class}::Attributes < HyperResource::Attributes; end"
+        )
+      end
+      if self.class::Links == HyperResource::Links
+        Object.module_eval(
+          "class #{self.class}::Links < HyperResource::Links; end"
+        )
+      end
+      if self.class::Objects == HyperResource::Objects
+        Object.module_eval(
+          "class #{self.class}::Objects < HyperResource::Objects; end"
+        )
+      end
+    end
+
+    self.attributes = self.class::Attributes.new(self)
+    self.links      = self.class::Links.new(self)
+    self.objects    = self.class::Objects.new(self)
+
+    self.loaded     = false
+
+    self.adapter    = opts[:adapter] || self.class.adapter ||
+                      HyperResource::Adapter::HAL_JSON
+  end
+
+
+  ## Returns true if one or more of this object's attributes has been
+  ## reassigned.
+  def changed?(*args)
+    attributes.changed?(*args)
+  end
+
+
+  #### Filters
+
+  ## +incoming_body_filter+ filters a hash of attribute keys and values
+  ## on their way from a response body to a HyperResource.  Override this
+  ## in a subclass of HyperResource to implement filters on incoming data.
+  def incoming_body_filter(attr_hash)
+    attr_hash
+  end
+
+  ## +outgoing_body_filter+ filters a hash of attribute keys and values
+  ## on their way from a HyperResource to a request body.  Override this
+  ## in a subclass of HyperResource to implement filters on outgoing data.
+  def outgoing_body_filter(attr_hash)
+    attr_hash
+  end
+
+  ## +outgoing_uri_filter+ filters a hash of attribute keys and values
+  ## on their way from a HyperResource to a URL.  Override this
+  ## in a subclass of HyperResource to implement filters on outgoing URI
+  ## parameters.
+  def outgoing_uri_filter(attr_hash)
+    attr_hash
+  end
+
+
+  #### Enumerable support
+
+  ## Returns the *i*th object in the first collection of objects embedded
+  ## in this resource.  Returns nil on failure.
+  def [](i)
+    get unless loaded
+    self.objects.first[1][i] rescue nil
+  end
+
+  ## Iterates over the objects in the first collection of embedded objects
+  ## in this resource.
+  def each(&block)
+    get unless loaded
+    self.objects.first[1].each(&block) rescue nil
+  end
+
+  #### Magic
+
+  ## method_missing will load this resource if not yet loaded, then
+  ## attempt to delegate to +attributes+, then +objects+, then +links+.
+  ## Override with care.
+  def method_missing(method, *args)
+    self.get unless self.loaded
+
+    method = method.to_s
+    if method[-1,1] == '='
+      return attributes[method[0..-2]] = args.first if attributes[method[0..-2]]
+    else
+      return attributes[method] if attributes && attributes.has_key?(method)
+      return objects[method] if objects && objects[method]
+      if links && links[method]
+        if args.count > 0
+          return links[method].where(*args)
+        else
+          return links[method]
+        end
+      end
+    end
+
+    raise NoMethodError, "undefined method `#{method}' for #{self.inspect}"
+  end
+
+
+  def inspect # @private
+    "#<#{self.class}:0x#{"%x" % self.object_id} @root=#{self.root.inspect} "+
+    "@href=#{self.href.inspect} @loaded=#{self.loaded} "+
+    "@namespace=#{self.namespace.inspect} ...>"
+  end
+
+  ## +response_body+, +response_object+, and +deserialized_response+
+  ##  are deprecated in favor of +body+.  (Sorry. Naming things is hard.)
+  def response_body # @private
+    _hr_deprecate('HyperResource#response_body is deprecated. '+
+                  'Please use HyperResource#body instead.')
+    body
+  end
+  def response_object # @private
+    _hr_deprecate('HyperResource#response_object is deprecated. '+
+                  'Please use HyperResource#body instead.')
+    body
+  end
+  def deserialized_response # @private
+    _hr_deprecate('HyperResource#deserialized_response is deprecated. '+
+                  'Please use HyperResource#body instead.')
+    body
+  end
+
+
+
+  ## Return a new HyperResource based on this object and a given href.
+  def _hr_new_from_link(href) # @private
+    self.class.new(:root            => self.root,
+                   :auth            => self.auth,
+                   :headers         => self.headers,
+                   :namespace       => self.namespace,
+                   :faraday_options => self.faraday_options,
+                   :href            => href)
+  end
+
+
+  ## Returns the class into which the given response should be cast.
+  ## If the object is not loaded yet, or if +namespace+ is
+  ## not set, returns +self+.
+  ##
+  ## Otherwise, +response_class+ uses +get_data_type_from_response+ to
+  ## determine subclass name, glues it to the given namespace, and
+  ## creates the class if it's not there yet. E.g., given a namespace of
+  ## +FooAPI+ and a response content-type of
+  ## "application/vnd.foocorp.fooapi.v1+json;type=User", this should
+  ## return +FooAPI::User+ (even if +FooAPI::User+ hadn't existed yet).
+  def self.response_class(response, namespace)
+    if self.to_s == 'HyperResource'
+      return self unless namespace
+    end
+
+    namespace ||= self.to_s
+
+    type_name = self.get_data_type_from_response(response)
+    return self unless type_name
+
+    namespaced_class(type_name, namespace)
+  end
+
+  def self.namespaced_class(type_name, namespace)
+    class_name = "#{namespace}::#{type_name}"
+    class_name.gsub!(/[^_0-9A-Za-z:]/, '')  ## sanitize class_name
+
+    ## Return data type class if it exists
+    klass = eval(class_name) rescue :sorry_dude
+    return klass if klass.is_a?(Class)
+
+    ## Data type class didn't exist -- create namespace (if necessary),
+    ## then the data type class
+    if namespace != ''
+      nsc = eval(namespace) rescue :bzzzzzt
+      unless nsc.is_a?(Class)
+        Object.module_eval "class #{namespace} < #{self}; end"
+      end
+    end
+    Object.module_eval "class #{class_name} < #{namespace}; end"
+    eval(class_name)
+  end
+
+  def _hr_response_class # @private
+    self.namespace ||= self.class.to_s unless self.class.to_s=='HyperResource'
+    self.class.response_class(self.response, self.namespace)
+  end
+
+
+  ## Inspects the given Faraday::Response, and returns a string describing
+  ## this resource's data type.
+  ##
+  ## By default, this method looks for a +type=...+ modifier in the
+  ## response's +Content-type+ and returns that value, capitalized.
+  ##
+  ## Override this method in a subclass to alter HyperResource's behavior.
+  def self.get_data_type_from_response(response)
+    return nil unless response
+    return nil unless content_type = response['content-type']
+    return nil unless m=content_type.match(/;\s* type=([0-9A-Za-z:]+)/x)
+    m[1][0,1].upcase + m[1][1..-1]
+  end
+
+  ## Uses +HyperResource.get_response_data_type+ to determine the proper
+  ## data type for this object.  Override to change behavior (though you
+  ## probably just want to override the class method).
+  def get_data_type_from_response
+    self.class.get_data_type_from_response(self.response)
+  end
+
+private
+
+  ## Return this object, "cast" into its proper response class.
+  def to_response_class
+    response_class = self._hr_response_class
+    return self if self.class == response_class
+    response_class.new(self)
+  end
+
+  ## Use the given resource's data to initialize this one.
+  def init_from_resource(resource)
+    (self.class._hr_attributes - [:attributes, :links, :objects]).each do |attr|
+      self.send("#{attr}=".to_sym, resource.send(attr))
+    end
+    self.adapter.apply(self.body, self)
+  end
+
+
+  ## Show a deprecation message.
+  def self._hr_deprecate(message) # @private
+    STDERR.puts "#{message} (called from #{caller[2]})"
+  end
+
+  def _hr_deprecate(*args) # @private
+    self.class._hr_deprecate(*args)
+  end
+end