remotely 0.0.4

data/.autotest

@@ -0,0 +1 @@
+require 'autotest/growl'

data/.gitignore

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

data/Gemfile

@@ -0,0 +1,2 @@
+source :rubygems
+gemspec

data/README.md

@@ -0,0 +1,70 @@
+# Remotely
+
+Remotely lets you specify associations for your models that should
+be fetched from a remote API instead of the database.
+
+## App Setup
+
+Apps are where Remotely goes to find association resources. You can define as many as you want, but if you define only one, you can omit the `:app` option from your associations.
+
+    Remotely.app :legsapp, "http://omgsomanylegs.com/api/v1"
+
+## Defining Associations
+
+`has_many_remote` takes two options, `:app` and `:path`. `:app` tells Remotely which registered app to fetch it from. `:path` tells it the URI to the object (everything after the app).
+
+**One app & association name matches URI**
+
+    class Millepied < ActiveRecord::Base
+      has_many_remote :legs # => "/legs"
+    end
+
+**One app & custom path**
+
+    class Millepied < ActiveRecord::Base
+      has_many_remote :legs, :path => "/store/legs"
+    end
+
+**One app & custom path with `id` substitution**
+
+    class Millepied < ActiveRecord::Base
+      has_many_remote :legs, :path => "/millepieds/:id/legs"
+    end
+
+**Multiple apps (all secondary conditions from above apply)**
+
+    class Millepied < ActiveRecord::Base
+      has_many_remote :legs, :app => :legsapp, ...
+    end
+
+### id Substitution
+
+A path can include "`:id`" anywhere in it, which is replaced by the instance's `id`. This is useful when the resource on the API end is namespaced. For example:
+
+    class Millepied < ActiveRecord::Base
+      has_many_remote :legs, :path => "/millepieds/:id/legs"
+    end
+
+    m = Millepied.new
+    m.id   # => 1
+    m.legs # => Requests "/millepieds/1/legs"
+
+## Fetched Objects
+
+Remote associations are Remotely::Model objects. Whatever data the API returns, becomes the attributes of the Model.
+
+    m = Millepied.new
+    m.legs[0]         # => #<Remotely::Model:0x0000f351c8 @attributes={:length=>"1mm"}>
+    m.legs[0].length  # => "1mm"
+
+### Fetched Object Associations
+
+If a fetched object includes an attribute matching "\*_id", Remotely tries to find the model it is for and retrieve it.
+
+    leg = m.legs.first
+    leg.user_id # => 2
+    leg.user    # => User.find(2)
+
+## Contributing
+
+Fork, branch and pull-request. Bump versions in their own commit.

data/Rakefile

@@ -0,0 +1,6 @@
+#!/usr/bin/env rake
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+task :default => :spec

data/lib/remotely.rb

@@ -0,0 +1,91 @@
+require "forwardable"
+require "faraday"
+require "active_support/inflector"
+require "active_support/concern"
+require "active_support/core_ext/hash"
+require "active_model"
+require "remotely/ext/url"
+
+module Remotely
+  autoload :Collection,   "remotely/collection"
+  autoload :Associations, "remotely/associations"
+  autoload :Model,        "remotely/model"
+  autoload :HTTPMethods,  "remotely/http_methods"
+
+  class RemotelyError < StandardError
+    def message; self.class::MESSAGE; end
+  end
+
+  class URLHostError < RemotelyError
+    MESSAGE = "URL object missing host"
+  end
+
+  class RemoteAppError < RemotelyError
+    MESSAGE = "No app specified for association with more than one app registered."
+  end
+
+  class HasManyForeignKeyError < RemotelyError
+    MESSAGE = "has_many associations can use the :foreign_key option."
+  end
+
+  class NonJsonResponseError < RemotelyError
+    MESSAGE = "Received an HTML response. Expected JSON."
+    attr_reader :body
+
+    def initialize(body)
+      @body = body
+    end
+  end
+
+  class << self
+    # @return [Hash] Hash of registered apps (key: name, value: URL)
+    def apps
+      @apps ||= {}
+    end
+
+    # Configure applications to be used by models. Accepts a block
+    # which specifies multiple apps via the `app` method.
+    #
+    # @param [Proc] block Configuration block.
+    #
+    # @example Registers an app named :fun with a URL of "http://fun.com/api/"
+    #   Remotely.configure do
+    #     app :fun, "http://fun.com/api/"
+    #   end
+    #
+    def configure(&block)
+      instance_eval(&block)
+    end
+
+    # Register an application with Remotely.
+    #
+    # @param [Symbol] name Placeholder name for the application.
+    # @param [String] url URL to the application's API.
+    #
+    def app(name, url)
+      url  = URI.parse(url)
+      apps[name] = { base: "#{url.scheme || "http"}://#{url.host}:#{url.port}", uri: url.path }
+    end
+
+    # Set the Basic Auth user and password to use when making
+    # requests.
+    #
+    # @param [String] user BasicAuth user
+    # @param [String] password BasicAuth password
+    #
+    def basic_auth(user=nil, password=nil)
+      user and password and @basic_auth = [user, password] or @basic_auth
+    end
+
+    # Clear all registered apps
+    #
+    def reset!
+      @apps = {}
+      @basic_auth = nil
+    end
+  end
+end
+
+module ActiveRecord
+  class Base; include Remotely::Associations end
+end

data/lib/remotely/associations.rb

@@ -0,0 +1,241 @@
+module Remotely
+  module Associations
+    # A set class methods for defining associations that are retreived from
+    # a remote API. They're available to all classes which inherit from
+    # ActiveRecord::Base orRemotely::Model.
+    #
+    #  class Show < ActiveRecord::Base
+    #    has_many_remote   :members
+    #    has_one_remote    :set
+    #    belongs_to_remote :station
+    #  end
+    #
+    # = Warning
+    #
+    # Just like with ActiveRecord, associations will overwrite any instance method
+    # with the same name as the association. So don't do that.
+    #
+    # = Cardinality and Defining Associations
+    #
+    # Remotely can be used to specify one-to-one and one-to-many associations.
+    # Many-to-many is not supported.
+    #
+    # Unlike ActiveRecord, remote associations are only defined on the client side.
+    # +has_many+ relations have no accompanying +belongs_to+.
+    #
+    # == One-to-many
+    #
+    # Use +has_many_remote+ to define a one-to-many relationship where the model
+    # you are defining it in is the parent.
+    #
+    # === URI Assumptions
+    #
+    # Remotely assumes all +has_many_remote+ associations can be found at:
+    #
+    #  /model_name(plural)/id/association_name(plural)
+    #
+    # ==== Example
+    #
+    #  class User < ActiveRecord::Base
+    #    has_many_remote :friends
+    #  end
+    #
+    #  user = User.new(:id => 1)
+    #  user.friends # => /users/1/friends
+    #
+    #
+    # == One-to-one
+    #
+    # Use +has_one_remote+ to define a one-to-one relationship.
+    #
+    # === URI Assumptions
+    #
+    # Remotely assumes all +has_one_remote+ associations can be found at:
+    #
+    #  /model_name(plural)/id/association_name(singular)
+    #
+    # ==== Example
+    #
+    #  class Car < ActiveRecord::Base
+    #    has_one_remote :engine
+    #  end
+    #
+    #  car = Car.new(:id => 1)
+    #  car.engine # => /cars/1/engine
+    #
+    #
+    # == Many-to-one
+    #
+    # Use +belongs_to_remote+ to define a many-to-one relationship. That is, if the
+    # model you're defining this on has a foreign key to the remote model.
+    #
+    # === URI Assumptions
+    #
+    # Remotely assumes all +belongs_to_remote+ associations can be found at:
+    #
+    #  /association_name(plural)/{association_name}_id
+    #
+    # ==== Example
+    #
+    #  class Car < ActiveRecord::Base
+    #    belongs_to_remote :brand
+    #  end
+    #
+    #  car = Car.new(:brand_id => 2)
+    #  car.brand # => /brands/2
+    #
+    # == Options
+    #
+    # === +:path+
+    # The full URI that should be used to fetch this resource.
+    # (supported by all methods)
+    #
+    # === +:foreign_key+
+    # The attribute that should be used, instead of +id+ when generating URIs.
+    # (supported by +belongs_to_remote+ only)
+    #
+    # == Path Variables
+    #
+    # The +path+ option will replace any symbol(ish) looking string with the
+    # value of that attribute, of the model.
+    #
+    #  class User < ActiveRecord::Base
+    #    belongs_to_remote :family, :path => "/families/:family_key"
+    #  end
+    #
+    #  user = User.new(:family_key => "noble")
+    #  user.family # => /families/noble
+    #
+    module ClassMethods
+      # Remote associations defined and their options.
+      attr_accessor :remote_associations
+
+      # Specifies a one-to-many relationship.
+      #
+      # @param [Symbol] name Name of the relationship
+      # @param [Hash] options Association configuration options.
+      # @option options [String] :path Path to the remote resource
+      #
+      def has_many_remote(name, options={})
+        define_association_method(:has_many, name, options)
+      end
+
+      # Specifies a one-to-one relationship.
+      #
+      # @param [Symbol] name Name of the relationship
+      # @param [Hash] options Association configuration options.
+      # @option options [String] :path Path to the remote resource
+      #
+      def has_one_remote(name, options={})
+        define_association_method(:has_one, name, options)
+      end
+
+      # Specifies a many-to-one relationship.
+      #
+      # @param [Symbol] name Name of the relationship
+      # @param [Hash] options Association configuration options.
+      # @option options [String] :path Path to the remote resource
+      # @option options [Symbol, String] :foreign_key Attribute to be used
+      #   in place of +id+ when constructing URIs.
+      #
+      def belongs_to_remote(name, options={})
+        define_association_method(:belongs_to, name, options)
+      end
+
+    private
+
+      def define_association_method(type, name, options)
+        self.remote_associations     ||= {}
+        self.remote_associations[name] = options.merge(type: type)
+        define_method(name)        { |reload=false| call_association(reload, name) }
+        define_method(:"#{name}=") { |o| set_association(name, o) }
+      end
+
+      def inherited(base)
+        base.remote_associations = self.remote_associations
+        base.extend(ClassMethods)
+        base.extend(Remotely::HTTPMethods)
+        super
+      end
+    end
+
+    def remote_associations
+      self.class.remote_associations ||= {}
+    end
+
+    def path_to(name, type)
+      opts = remote_associations[name]
+      raise HasManyForeignKeyError if opts[:foreign_key] && [:has_many, :has_one].include?(type)
+
+      base = self.class.base_class.model_name.element.pluralize
+      fkey = opts[:foreign_key] || :"#{name}_id"
+      path = opts[:path]
+      path = self.instance_exec(&path) if path.is_a?(Proc)
+
+      # :path option takes precedence
+      return interpolate URL(path) if path
+
+      singular_path = name.to_s.singularize
+      plural_path   = name.to_s.pluralize
+
+      case type
+      when :has_many
+        interpolate URL(base, self.id, plural_path)
+      when :has_one
+        interpolate URL(base, self.id, singular_path)
+      when :belongs_to
+        interpolate URL(plural_path, public_send(fkey))
+      end
+    end
+
+    def self.included(base) #:nodoc:
+      base.extend(ClassMethods)
+    end
+
+  private
+  
+    def can_fetch_remotely_association?(name)
+      opts = remote_associations[name]
+
+      if opts[:path]
+        opts[:path].scan(/:([^\/]*)/).map { |m| public_send(m.first.to_sym) }.all?
+      else
+        case opts[:type]
+        when :belongs_to
+          !public_send(opts[:foreign_key] || "#{name}_id").nil?
+        when :has_many, :has_one
+          !self.id.nil?
+        end
+      end
+    end
+
+    def call_association(reload, name)
+      return unless can_fetch_remotely_association?(name)
+      fetch_association(name) if reload || association_undefined?(name)
+      get_association(name)
+    end
+
+    def fetch_association(name)
+      type     = remote_associations[name][:type]
+      klass    = name.to_s.classify.constantize
+      response = self.class.get(path_to(name, type), :class => klass, :parent => self)
+      set_association(name, response)
+    end
+
+    def get_association(name)
+      instance_variable_get("@#{name}")
+    end
+
+    def set_association(name, value)
+      instance_variable_set("@#{name}", value)
+    end
+
+    def association_undefined?(name)
+      !instance_variable_defined?("@#{name}")
+    end
+
+    def interpolate(content)
+      content.to_s.gsub(/:\w+/) { |m| public_send(m.tr(":", "")) }
+    end
+  end
+end

data/lib/remotely/collection.rb

@@ -0,0 +1,75 @@
+module Remotely
+  class Collection < Array
+    def initialize(parent, klass, *args, &block)
+      @parent = parent
+      @klass  = klass
+      super(*args, &block)
+    end
+
+    # Returns the first Model object with +id+.
+    #
+    # @param [Fixnum] id id of the record
+    # @return [Remotely::Model] Model object with that id
+    #
+    def find(id)
+      select { |e| e.id.to_i == id.to_i }.first
+    end
+
+    # Returns a new Collection object consisting of all the
+    # Model objects matching `attrs`.
+    #
+    # @param [Hash] attrs Search criteria in key-value form
+    # @return [Remotely::Collection] New collection of elements matching
+    #
+    def where(attrs={}, &block)
+      block = lambda { |e| attrs.all? { |k,v| e.send(k) == v }} unless block_given?
+      Collection.new(@parent, @klass, select(&block))
+    end
+
+    # Mimic an ActiveRecord::Relation, but just return self since
+    # that's already an array.
+    #
+    # @return [Remotely::Collection] self
+    #
+    def all
+      self
+    end
+
+    # Order the result set by a specific attribute.
+    #
+    # @example Sort by +name+
+    #   Thing.where(:type => "awesome").order(:name)
+    #
+    # @result [Remotely::Collection] A new, ordered, Collection.
+    #
+    def order(attribute)
+      Collection.new(@parent, @klass, sort_by(&attribute))
+    end
+
+    # Instantiate a new model object, pre-build with a foreign key
+    # attribute set to it's parent, and add it to itself.
+    #
+    # NOTE: Does not persist the new object. You must call +save+ on the
+    # new object to persist it. To instantiate and persist in one operation
+    # @see #create.
+    #
+    # @param [Hash] attrs Attributes to instantiate the new object with.
+    # @return [Remotely::Model] New model object
+    #
+    def build(attrs={})
+      attribute  = "#{@parent.class.model_name.element.to_sym}_id".to_sym
+      value      = @parent.id
+      attrs.merge!(attribute => value)
+
+      @klass.new(attrs).tap { |m| self << m }
+    end
+
+    # Same as #build, but saves the new model object as well.
+    #
+    # @see #build
+    #
+    def create(attrs={})
+      build(attrs).tap { |m| m.save }
+    end
+  end
+end