amfetamine 0.1.5

data/.gitignore

@@ -0,0 +1,8 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+Guardfile
+.yardoc
+doc/
+coverage/

data/.rvmrc

@@ -0,0 +1 @@
+rvm use ruby-1.9.3-p0

data/Gemfile

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

data/README.md

@@ -0,0 +1,196 @@
+Amfetamine, A REST object abstractavaganza
+====================================
+
+> Makes your API calls f-f-f-ast!
+
+Amfetamine adds an ActiveModel like interface to your REST services with support for any HTTParty client and caching using memcached.
+
+Features
+--------
+
+It is still in beta and under heavy development. Some features:
+
+* Mapping of REST services to objects.
+* HTTP configuration agnostic; it works with any configuration of HTTParty. It should work with any object that has a similar syntax.
+* Reasonably effective object caching with memcached.
+* It has a lot of methods that you expect from ActiveModel objects. Find, all, save, create, new, destroy, update_attributes, update.
+* It supports all validation methods ActiveModel provides, thanks to ActiveModel -red.
+* You can fully configure your memcached client, it uses Dalli.
+* Although the client has been tested and build with JSON, it should support XML as well.
+* It supports single nested resources for now.
+* It supports conditions in the all method (find method asap), just provice a :conditions hash like you're used to.
+* Supports global HTTP and Memcached client as well as per object overriding.
+* If a request passes validation on client side and not on service side, the client properly sets error messages from the service.
+* Provides testing helpers
+* Amfetamine supports some basic callbacks: before_save, after_save, around_save and before_create. More coming as needed.
+
+Setup
+=====
+
+### 1)
+Add it to your gemfile (not released yet):
+
+```ruby
+gem 'amfetamine'
+```
+
+### 2)
+Create an initializer amfetamine_initializer.rb:
+
+```ruby
+Amfetamine::Config.configure do |config|
+  config.memcached_instance = [HOST:PORT, OPTION1,OPTION2] || HOST:PORT
+  config.rest_client = REST_CLIENT
+
+  # Optional
+  config.resource_suffix = '.json' # The suffix to the path
+  config.base_uri = 'http://bla.bla/bla/' # If you either need a path or domain infront of your URI, you can do it here. Its advised to use httparty for this.
+end
+```
+
+### 3)
+Configure your object:
+
+```ruby
+class Banana < Amfetamine::Base
+  # You need to setup an attribute for each attribute your object has, apart from id (thats _mandatory_)
+  amfetamine_attributes :name, :shape, :color, :created_at, :updated_at
+
+  # OPTIONAL: Per object configuration
+  amfetamine_configure memcached_instance: 'localhost:11211',
+                 rest_client: BananaRestclient
+
+end
+```
+
+
+### 4)
+Lastly, because I think its more semantic, you need to configure both your service and client to include the root element in JSON. However, Amfetamine will work fine without this.
+
+```ruby
+# config/initializers/wrap_parameters.rb
+ActiveSupport.on_load(:action_controller) do
+  wrap_parameters :format => [:json]
+end
+```
+
+Usage
+=====
+
+### Relationships
+
+```ruby
+has_many_resources PLURAL_OBJECT_NAME_SYMBOLS
+belongs_to_resource SINGULAR_OBJECT_NAME_SYMBOL
+
+parent.children.all # => Returns all nested resources, you can enumarate it with each, include? and several other helpers are available
+parent.children.all(:conditions => SOMETHING) # Works as expected
+parent.children << child # Sets a child to a parent, child still needs to be saved. This will append it to the current all array and set the parent_id, accessing #all will overwrite that array.
+parent.children.find(ID) # => Returns the nested child with ID
+children.parent # => returns a Amfetamine::Relationship with only the parent
+```
+
+### Querying
+
+```ruby
+Object.all # => returns all objects, request: /objects
+Object.all(conditions: {:other_parent_id => 2} ) # => request: objects?other_parent_id=2
+Object.find(ID) # => returns object with ID, request: objects/ID
+```
+
+### Modifying data
+
+```ruby
+object.save
+object.destroy
+object.update_attributes(HASH)
+Object.create(HASH)
+```
+
+Cache Invalidation
+=================
+
+Objects are cached by request with the body as value. Request status codes are also cached. Every time an object is created, destroyed or updated, the plural cache is also invalidated.
+
+You can invalidate an object's cache any time by calling `clean_cache!` on an object. You can flush the whole cache by calling flush on either a class or Amfetamine::Cache.
+
+Testing
+=======
+
+Amfetamine provides a testing helper to easilly stub out responses from external services, so you can better control what response you get.
+
+```ruby
+# Rspec:
+before do
+  AmfetamineObject.stub_responses! do |r|
+    # Setting the code / path is optional. If amfetamine picks the wrong path, this will give you some weird errors.
+    r.post(path: '/bananas/', code: 201) { some_object }
+    r.get { some_object } # this sets to the default for gets on the rest_client this object uses
+  end
+end
+```
+
+Also, if you're using a cache, you should flush the cache before each test to avoid confusion.
+
+Building Custom Methods
+=======================
+
+Its important to note that caching might not work as expected when building custom methods. For now, please refer to the code.
+
+Testing
+=======
+
+Amfetamine provides several testing helpers to make testing easier. I didn't think it would be wise to allow external connections, but I didn't want you to have to stub out all methods either.
+
+```ruby
+Object.prevent_external_connections! # Raises an error if any external connections are made on this object
+
+# You can provide a block as well, after the block the rest_client is set back to the default:
+Object.prevent_external_connections! do |rest_client|
+  rest_client.should_receive('get').with('/objects').and_return(objects.to_json)
+  Object.all
+end
+
+# You can also use a dsl to predefine responses up front on a per object basis. You can use rspec 'let' objects in the response as well.
+Object.stub_external_responses! do |r|
+  r.get {object}
+end
+
+r.all # => object, also will yield an error, expects an array
+r.find(1) # => object
+
+# You can go wilder with this as well so you can allow multiple requests. You can also use this dsl on the rest_client in #prevent_external_connections!
+Object.stub_external_responses! do |r|
+  r.get(path: '/objects') { [object] } # Returns [object].to_json
+  r.get(path: "/objects/#{object.id}", code: 404) {} # Returns a resource not found
+end
+```
+
+TODO
+
+Future Features
+===============
+
+* Smarter caching
+* Better support for custom methods
+* Support for Reddis
+* Automatic determining of attributes and validations
+* Supporting any amount of nested relationships
+* Supporting interobject relationship (database versus service)
+* More callbacks
+* Better typecasting, it doesn't always work.
+
+Licence
+=======
+
+TBD
+
+Contributing
+============
+
+Please do a pull request and test your code!
+
+Contributors
+============
+
+* Timon Vonk

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+
+task :default => [:bundle_dependencies, :rspec]
+
+task :bundle_dependencies do
+  sh "bundle"
+end
+
+task :rspec do
+  sh "rspec spec"
+end

data/amfetamine.gemspec

@@ -0,0 +1,40 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "amfetamine/version"
+
+Gem::Specification.new do |s|
+  s.name        = "amfetamine"
+  s.version     = Amfetamine::VERSION
+  s.authors     = ["Timon Vonk"]
+  s.email       = ["timon@exvo.com"]
+  s.homepage    = "http://www.github.com/exvo/amfetamine"
+  s.summary     = %q{Wraps REST to objects}
+  s.description = %q{Wraps REST to objects, provides caching and makes your app go Bzzz!}
+
+  s.rubyforge_project = "amfetamine"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  # Development dependencies
+  s.add_development_dependency "rspec"
+  s.add_development_dependency "guard"
+  s.add_development_dependency "guard-rspec"
+  #s.add_development_dependency "growl_notify"
+  #s.add_development_dependency "rb-fsevent"
+  s.add_development_dependency "growl"
+  s.add_development_dependency "httparty"
+  s.add_development_dependency "fakeweb"
+  s.add_development_dependency "simplecov"
+  s.add_development_dependency "simplecov-rcov"
+
+
+  # Runtime dependencies
+  s.add_runtime_dependency "dalli"
+  s.add_runtime_dependency "activesupport" # For helper methods
+  s.add_runtime_dependency "activemodel" # For validations and AM like behaviour
+  s.add_runtime_dependency "json"
+  s.add_runtime_dependency "rake"
+end

data/lib/amfetamine.rb

@@ -0,0 +1,19 @@
+require "amfetamine/version"
+require "amfetamine/helpers/test_helpers" # Testing helper methods
+require "amfetamine/exceptions"
+require "amfetamine/logger"
+require 'amfetamine/relationship'
+require "amfetamine/relationships"
+require "amfetamine/caching_adapter" # Adapter that wraps memcache methods
+require "amfetamine/cache" # Common caching methods
+require "amfetamine/rest_helpers" # Methods for determining REST paths
+require "amfetamine/query_methods" # Methods for interfacing with the classs
+require "amfetamine/base" # Basics
+require "amfetamine/config" # Configuration class
+
+module Amfetamine
+
+  def self.logger
+    Amfetamine::Logger.instance
+  end
+end

data/lib/amfetamine/base.rb

@@ -0,0 +1,189 @@
+require 'active_model'
+
+module Amfetamine
+  class Base
+    # Activemodel
+    extend ActiveModel::Naming
+    extend ActiveModel::Callbacks
+    include ActiveModel::Validations
+    include ActiveModel::Serialization
+    include ActiveModel::Serializers::JSON
+
+    #Callbacks
+    define_model_callbacks :create, :save
+
+
+    # amfetamine
+    include Amfetamine::RestHelpers
+    include Amfetamine::QueryMethods
+    include Amfetamine::Relationships
+
+    # Testing
+    include Amfetamine::TestHelpers
+
+
+    attr_reader :attributes
+
+    def id=(val)
+      @attributes['id'] = val
+    end
+
+    def id
+      @attributes['id']
+    end
+
+    private :'id='
+
+
+
+    def self.amfetamine_attributes(*attrs)
+      attrs.each do |attr|
+        define_method("#{attr}=") do |arg|
+          @attributes[attr.to_s] = arg
+        end
+
+        define_method("#{attr}") do
+          @attributes[attr.to_s]
+        end
+      end
+    end
+
+    def self.amfetamine_configure(hash)
+      hash.each do |k,v|
+        self.send("#{k.to_s}=", v)
+      end
+    end
+
+    # Builds an object from JSON, later on will need more (maybe object id? Or should that go in find?)
+    # It parses the hash, builds the objects and sets new to false
+    def self.build_object(args)
+      # Cache corruption guard
+      args = normalize_cache_data(args)
+
+      obj = self.new(args)
+      obj.tap { |obj| obj.instance_variable_set('@notsaved',false) } # because I don't want a global writer
+    end
+
+    def update_attributes_from_response(args)
+      # We need to check this. If an api provides new data after an update, it will be set :-)
+      # Some apis return "nil" or something like that, so we need to double check its a hash
+
+      # TODO: Remove if statement because validation has been added
+      if args && args.is_a?(Hash) && args.has_key?(self.class_name)
+        args = args[self.class_name]
+        args.each { |k,v| self.send("#{k}=", v); self.attributes[k.to_sym] = v  }
+      end
+    end
+
+    # Allows you to override the global caching server
+    def self.memcached_instance=(value, options={})
+      if value.is_a?(Array)
+        @cache_server = Amfetamine::Cache.new(value.shift, value.first) # First element is the server, second must be the options
+      else
+        @cache_server = Amfetamine::Cache.new(value, options)
+      end
+    end
+
+    # Base method for creating objects
+    def initialize(args={})
+      super
+      @attributes = {}
+      args.each { |k,v| self.send("#{k}=", v) }
+      @notsaved = true
+      self
+    end
+
+    def is_attribute?(attr)
+      @attributes.keys.include?(attr.to_sym)
+    end
+
+    def persisted?
+      !new?
+    end
+
+    def to_model
+      self
+    end
+
+    def to_json(*gen)
+      options = {}
+      options.merge!(:root => self.class.model_name.element)
+      super(self.as_json(options))
+    end
+
+    def to_key
+      persisted? ? [id] : nil
+    end
+
+    def to_param
+      persisted? ? id.to_s : nil
+    end
+
+    # Checks if object is cached
+    # TODO this is not very efficient, but dalli doesn't provide a polling function :(
+    def cached?
+      keys = belongs_to_relationships.collect { |r| r.singular_path } << self.singular_path
+      keys.any? { |k| cache.get(k) }
+    end
+
+    # Checks if object is cachable
+    # TODO implement
+    def self.cacheable?
+      true
+    end
+
+    def cacheable?
+      self.class.cacheable?
+    end
+
+    # Checks to see if an object is valid or not
+    def valid?
+      errors.clear
+      run_validations!
+    end
+
+    # We need to redefine this so it doesn't check on object_id
+    def ==(other)
+      return false unless self.id == other.id # Some APIs dont ALWAYS return an ID
+
+      self.attributes.all? do |k,v|
+        self.attributes[k] == other.attributes[k]
+      end
+    end
+
+    def errors
+      @errors ||= ActiveModel::Errors.new(self)
+    end
+
+
+
+    def class_name
+      self.class.class_name
+    end
+
+    def self.class_name
+      self.name.downcase
+    end
+
+    protected
+    def self.cache
+      @cache_server || Amfetamine::Cache
+    end
+
+    def cache
+      self.class.cache
+    end
+
+    # TODO: Refactor > cache, only cache should know if data is valid.
+    def self.normalize_cache_data(args)
+      # Validation predicates
+      raise InvalidCacheData, "Empty data" if args.nil?
+      raise InvalidCacheData, "Invalid data: #{args.to_s}" if !args.is_a?(Hash)
+      args.stringify_keys!
+      args = args[class_name] || args
+      # TODO remove [:id], stringify_keys! _should_ nail this.
+      raise InvalidCacheData, "No object or ID #{args}"  unless args.present? && (args["id"] || args[:id])
+      args
+    end
+  end
+end