remotable 0.1.1 → 0.1.2

data/.gitignore

@@ -2,3 +2,5 @@
 .bundle
 Gemfile.lock
 pkg/*
+coverage
+

data/.simplecov

@@ -0,0 +1,3 @@
+SimpleCov.start do
+end
+

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Bob Lail
+
+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.mdown

@@ -0,0 +1,103 @@
+# Remotable
+
+Remotable associates an ActiveRecord model with a remote resource (like an ActiveResource model) and keeps the two synchronized.
+
+- When a local record is loaded, Remotable ensures that it is up-to-date.
+- When a local record is requested (by an ActiveRecord `find_by_` method) but not found, Remotable fetches the remote resource and creates a local copy.
+- When a local record is created, updated, or destroyed, Remotable ensures that the corresponding remote resource is created, updated, or destroyed.
+
+## Using Remotable
+
+### Installation
+
+Just add the following to your Gemfile:
+
+    gem "remotable"
+
+### Getting Started
+
+**1.** Remotable requires that your local model have an `expires_at` column.
+
+    class AddExpiresAtToTenants < ActiveRecord::Migration
+      def self.up
+        add_column :tenants, :expires_at, :timestamp, :null => false
+      end
+    end
+
+**2.** Your local model has to be associated with a remote model: (Let's say `RemoteTenant` is the name of an ActiveResource model.)
+
+    class Tenant < ActiveRecord::Base
+      remote_model RemoteTenant
+    end
+
+
+### Configuration
+
+Specify the attributes of the local model that you want to keep in sync with the remote model. You can also specify mappings by using the hash rocket. The line `:customer_name => :name` tells Remotable to keep `RemoteTenant#customer_name` in sync with `Tenant#name`.
+
+    class Tenant < ActiveRecord::Base
+      remote_model RemoteTenant
+      attr_remote :slug,
+                  :customer_name => :name,
+                  :id => :remote_id
+    end
+
+By default Remotable assumes that the local model and remote model are joined with the connection you would express in SQL this way: `local_model INNER JOIN remote_model ON local_model.id=remote_model.id`. But it is generally impractical to join on `local_model.id`.
+
+If you specify `attr_remote :id => :remote_id`, then the join will be on `local_model.remote_id=remote_model.id`, but you can also use a different attribute as the join key:
+
+    class Tenant < ActiveRecord::Base
+      remote_model RemoteTenant
+      attr_remote :slug,
+                  :customer_name => :name,
+                  :id => :remote_id
+      remote_key  :slug
+    end
+
+Now, the join could be expressed this way: `local_model.slug=remote_model.slug`.
+
+### Finders
+
+For all of the local attributes that you've remoted (`slug`, `name`, and `remote_id` in the example above), the remoted model will respond to custom finders (e.g. `find_by_slug`, `find_by_name`, and `find_by_remote_id`). These finders will _first_ look in the local database for the requested record and, if it isn't found, look for the resource remotely. If a finder finds the resource remotely, it creates a local copy and returns that.
+
+Without any further configuration, Remotable will assume the route to for the customer finder from the attribute. For example,
+
+    find_by_id(...)            # Looks in api_path/tenants/:id
+    find_by_slug(...)          # Looks in api_path/tenants/by_slug/:slug
+    find_by_customer_name(...) # Looks in api_path/tenants/by_customer_name/:customer_name
+
+You can specify a custom path with the `find_by` method or you can always write an appropriate `find_by_whatever` method on your remote resource.
+
+    class Tenant < ActiveRecord::Base
+      remote_model RemoteTenant
+      attr_remote :slug,
+                  :customer_name => :name,
+                  :id => :remote_id
+      find_by :name, :path => "by_nombre/:name"
+    end
+
+When you use `find_by`, give the name of the _local_ attribute not the remote one (if they differ). Also, the name of the symbolic part of the path should match the local attribute name as well.
+
+### Expiration
+
+Whenever a remoted record is instantiated, Remotable checks the value of its `expires_at` attribute. If the date is in the past, Remotable pulls changes from the remote resource. Whenever a record is saved, `expires_at` is set to a time in the future&mdash;by default, 1 day. You can change how frequently a record expires by setting `expires_after` to a duration:
+
+    class Tenant < ActiveRecord::Base
+      remote_model RemoteTenant
+      expires_after 1.hour
+    end
+
+### Adapters
+
+Remotable checks class you hand to `remote_model` to see what it inherits from. Remotable checks this to use the correct adapter with the remote model. Currently, the only adapter included in Remotable is for ActiveResource::Base.
+
+## Development
+
+### To Do
+
+ - Add additional adapters
+ - Write a generator
+
+### License
+
+Remotable is available under the terms of the MIT license.

data/lib/remotable.rb

@@ -1,4 +1,5 @@
 require "remotable/version"
+require "remotable/nosync"
 
 
 # Remotable keeps a locally-stored ActiveRecord
@@ -28,6 +29,7 @@ require "remotable/version"
 #
 #
 module Remotable
+  extend Nosync
   
   
   

data/lib/remotable/active_record_extender.rb

@@ -5,6 +5,11 @@ require "active_support/concern"
 module Remotable
   module ActiveRecordExtender
     extend ActiveSupport::Concern
+    include Nosync
+    
+    def nosync?
+      self.class.nosync? || super
+    end
     
     
     
@@ -28,6 +33,11 @@ module Remotable
     
     
     module ClassMethods
+      include Nosync
+      
+      def nosync?
+        Remotable.nosync? || super
+      end
       
       def remote_key(*args)
         if args.any?
@@ -51,13 +61,16 @@ module Remotable
       
       def attr_remote(*attrs)
         map = attrs.extract_options!
-        map = attrs.map_to_self(map)
+        map = attrs.map_to_self.merge(map)
         @remote_attribute_map = map
+        
+        @remote_attribute_routes = {}
+        fetch_with(*local_attribute_names)
       end
       
-      def fetch_with(*args)
-        keys_and_routes = extract_keys_and_routes(*args)
-        @remote_attribute_routes.merge!(keys_and_routes)
+      def fetch_with(*local_keys)
+        remote_keys_and_routes = extract_remote_keys_and_routes(*local_keys)
+        @remote_attribute_routes.merge!(remote_keys_and_routes)
       end
       alias :find_by :fetch_with
       
@@ -93,7 +106,11 @@ module Remotable
       
       def default_route_for(local_key, remote_key=nil)
         remote_key ||= remote_attribute_name(local_key)
-        "by_#{remote_key}/:#{local_key}.json"
+        if remote_key.to_s == primary_key
+          ":#{local_key}"
+        else
+          "by_#{remote_key}/:#{local_key}"
+        end
       end
       
       
@@ -102,8 +119,10 @@ module Remotable
       # so you can use the remoted record in associations.
       def instantiate(*args)
         record = super
-        record.pull_remote_data! if record.expired?
-        record = nil if record.destroyed?
+        if record.expired? && !Remotable.nosync?
+          record.pull_remote_data!
+          record = nil if record.destroyed?
+        end
         record
       end
       
@@ -112,7 +131,7 @@ module Remotable
       def method_missing(method_sym, *args, &block)
         method_name = method_sym.to_s
         
-        if method_name =~ /find_by_(.*)(!?)/
+        if method_name =~ /find_by_([^!]*)(!?)/
           local_attr, bang, value = $1.to_sym, !$2.blank?, args.first
           remote_attr = remote_attribute_name(local_attr)
           
@@ -120,11 +139,8 @@ module Remotable
                      # primary key if we're evaluating a finder
           
           if remote_attribute_routes.key?(remote_attr)
-            local_resource = where(local_attr => value).first
-            unless local_resource
-              remote_resource = remote_model.find_by(remote_attr, value)
-              local_resource = new_from_remote(remote_resource) if remote_resource
-            end
+            local_resource = where(local_attr => value).first ||
+                             fetch_by(remote_attr, value)
             
             raise ActiveRecord::RecordNotFound if local_resource.nil? && bang
             return local_resource
@@ -136,6 +152,22 @@ module Remotable
       
       
       
+      def expire_all!
+        update_all(["expires_at=?", 1.day.ago])
+      end
+      
+      
+      
+      # Looks the resource up remotely, by the given attribute
+      # If the resource is found, wraps it in a new local resource
+      # and returns that.
+      def fetch_by(remote_attr, value)
+        remote_resource = remote_model.find_by(remote_attr, value)
+        remote_resource && new_from_remote(remote_resource)
+      end
+      
+      
+      
     private
       
       
@@ -156,7 +188,7 @@ module Remotable
       end
       
       
-      def extract_keys_and_routes(*local_keys)
+      def extract_remote_keys_and_routes(*local_keys)
         keys_and_routes = local_keys.extract_options!
         {}.tap do |hash|
           local_keys.each {|local_key| hash[remote_attribute_name(local_key)] = nil}
@@ -220,28 +252,6 @@ module Remotable
     
     
     
-    def nosync!
-      @nosync = true
-    end
-    
-    def nosync
-      value = @nosync
-      @nosync = true
-      yield
-    ensure
-      @nosync = value
-    end
-    
-    def nosync=(val)
-      @nosync = (val == true)
-    end
-    
-    def nosync?
-      @nosync == true
-    end
-    
-    
-    
   private
     
     def fetch_remote_resource

data/lib/remotable/adapters/active_resource.rb

@@ -1,4 +1,5 @@
 require "remotable/active_resource_fixes"
+require "remotable/core_ext/uri"
 require "active_support/concern"
 
 
@@ -19,11 +20,7 @@ module Remotable
         
         
         def find_by!(key, value)
-          if key == :id
-            find(value)
-          else
-            find(:one, :from => path_for(key, value))
-          end
+          find(:one, :from => path_for(key, value))
         end
         
         def find_by(key, value)
@@ -39,9 +36,9 @@ module Remotable
           route = route_for(local_key)
           path = route.gsub(/:#{local_key}/, value.to_s)
           if relative_path?(path)
-            path
+            URI.join_url_segments(prefix, collection_name, "#{path}.#{format.extension}")
           else
-            join_url_segments(prefix, collection_name, path)
+            path
           end
         end
         
@@ -52,11 +49,7 @@ module Remotable
         
         
         def relative_path?(path)
-          path.start_with?("/") || path["://"]
-        end
-        
-        def join_url_segments(*segments)
-          segments.flatten.join("/").gsub(/\/+/, "/")
+          !(path.start_with?("/") || path["://"])
         end
         
         

data/lib/remotable/core_ext/uri.rb

@@ -0,0 +1,22 @@
+require "uri"
+
+
+module Remotable
+  module CoreExt
+    module URI
+      
+      
+      def join_url_segments(*segments)
+        segments = segments.dup.flatten.map(&:to_s)
+        first_segment = segments.shift.gsub(/\/$/, "")
+        segments.map! { |seg| seg.gsub(/(^\/)|(\/$)/, "") }
+        [first_segment, *segments].join("/")
+      end
+      
+      
+    end
+  end
+end
+
+
+::URI.extend(Remotable::CoreExt::URI)

data/lib/remotable/nosync.rb

@@ -0,0 +1,28 @@
+
+module Remotable
+  module Nosync
+    
+    
+    def nosync!
+      self.nosync = true
+    end
+    
+    def nosync
+      value = @nosync
+      nosync!
+      yield
+    ensure
+      self.nosync = value
+    end
+    
+    def nosync=(val)
+      @nosync = (val == true)
+    end
+    
+    def nosync?
+      @nosync == true
+    end
+    
+    
+  end
+end

data/lib/remotable/version.rb

@@ -1,3 +1,3 @@
 module Remotable
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

data/remotable.gemspec

@@ -22,6 +22,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency "factory_girl"
   s.add_development_dependency "sqlite3"
   s.add_development_dependency "active_resource_simulator"
+  s.add_development_dependency "simplecov"
   
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")

data/test/nosync_test.rb

@@ -0,0 +1,30 @@
+require "test_helper"
+require "remotable"
+require "support/active_resource"
+
+
+class NoSyncTest < ActiveSupport::TestCase
+  
+  
+  
+  test "nosync? should be false by default" do
+    assert_equal false, Tenant.new.nosync?
+  end
+  
+  test "nosync? should be true if remotable is turned off globally" do
+    Remotable.nosync do
+      assert_equal true, Tenant.new.nosync?
+      assert_equal true, RemoteWithoutKey.new.nosync?
+    end
+  end
+  
+  test "nosync? should be true if remotable is turned off for the model" do
+    Tenant.nosync do
+      assert_equal true, Tenant.new.nosync?
+      assert_equal false, RemoteWithoutKey.new.nosync?
+    end
+  end
+  
+  
+  
+end

data/test/remotable_test.rb

@@ -45,6 +45,43 @@ class RemotableTest < ActiveSupport::TestCase
     end
   end
   
+  test "should be able to find resources with the bang method" do
+    new_tenant_slug = "not_found2"
+    
+    assert_equal 0, Tenant.where(:slug => new_tenant_slug).count,
+      "There's not supposed to be a Tenant with the slug #{new_tenant_slug}."
+    
+    assert_difference "Tenant.count", +1 do
+      RemoteTenant.run_simulation do |s|
+        s.show(nil, {
+          :id => 46,
+          :slug => new_tenant_slug,
+          :church_name => "Not Found"
+        }, :path => "/api/accounts/by_slug/#{new_tenant_slug}.json")
+        
+        new_tenant = Tenant.find_by_slug!(new_tenant_slug)
+        assert_not_nil new_tenant, "A remote tenant was not found with the slug #{new_tenant_slug.inspect}"
+      end
+    end
+  end
+  
+  test "if a resource is neither local nor remote, raise an exception with the bang method" do
+    new_tenant_slug = "not_found3"
+    
+    assert_equal 0, Tenant.where(:slug => new_tenant_slug).count,
+      "There's not supposed to be a Tenant with the slug #{new_tenant_slug}."
+    
+    RemoteTenant.run_simulation do |s|
+      s.show(nil, nil, :status => 404, :path => "/api/accounts/by_slug/#{new_tenant_slug}.json")
+      
+      assert_raises ActiveRecord::RecordNotFound do
+        Tenant.find_by_slug!(new_tenant_slug)
+      end
+    end
+  end
+  
+  
+  
   test "should be able to find resources by different attributes and specify a path" do
     new_tenant_name = "JohnnyG"
     

data/test/support/active_resource.rb

@@ -14,8 +14,7 @@ end
 class Tenant < ActiveRecord::Base
   remote_model RemoteTenant
   attr_remote :slug, :church_name => :name, :id => :remote_id
-  find_by :slug
-  find_by :name => "by_nombre/:name.json"
+  find_by :name => "by_nombre/:name"
 end
 
 

data/test/test_helper.rb

@@ -1,4 +1,5 @@
 require 'rubygems'
+require 'simplecov'
 require 'rails'
 require 'rails/test_help'
 require 'active_support/core_ext'

metadata

@@ -2,7 +2,7 @@
 name: remotable
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors: 
 - Robert Lail
@@ -10,12 +10,11 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-08-26 00:00:00 -05:00
+date: 2011-09-19 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: activeresource
-  prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -23,10 +22,10 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: "0"
   type: :runtime
+  prerelease: false
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
   name: activerecord
-  prerelease: false
   requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -34,10 +33,10 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: "0"
   type: :runtime
+  prerelease: false
   version_requirements: *id002
 - !ruby/object:Gem::Dependency 
   name: activesupport
-  prerelease: false
   requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -45,10 +44,10 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: "0"
   type: :runtime
+  prerelease: false
   version_requirements: *id003
 - !ruby/object:Gem::Dependency 
   name: rails
-  prerelease: false
   requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -56,10 +55,10 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: "0"
   type: :development
+  prerelease: false
   version_requirements: *id004
 - !ruby/object:Gem::Dependency 
   name: turn
-  prerelease: false
   requirement: &id005 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -67,10 +66,10 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: "0"
   type: :development
+  prerelease: false
   version_requirements: *id005
 - !ruby/object:Gem::Dependency 
   name: factory_girl
-  prerelease: false
   requirement: &id006 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -78,10 +77,10 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: "0"
   type: :development
+  prerelease: false
   version_requirements: *id006
 - !ruby/object:Gem::Dependency 
   name: sqlite3
-  prerelease: false
   requirement: &id007 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -89,10 +88,10 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: "0"
   type: :development
+  prerelease: false
   version_requirements: *id007
 - !ruby/object:Gem::Dependency 
   name: active_resource_simulator
-  prerelease: false
   requirement: &id008 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -100,7 +99,19 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: "0"
   type: :development
+  prerelease: false
   version_requirements: *id008
+- !ruby/object:Gem::Dependency 
+  name: simplecov
+  requirement: &id009 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  prerelease: false
+  version_requirements: *id009
 description: Remotable keeps a locally-stored ActiveRecord synchronized with a remote resource.
 email: 
 - robert.lail@cph.org
@@ -112,7 +123,10 @@ extra_rdoc_files: []
 
 files: 
 - .gitignore
+- .simplecov
 - Gemfile
+- MIT-LICENSE
+- README.mdown
 - Rakefile
 - lib/remotable.rb
 - lib/remotable/active_record_extender.rb
@@ -120,9 +134,12 @@ files:
 - lib/remotable/adapters/active_resource.rb
 - lib/remotable/core_ext.rb
 - lib/remotable/core_ext/enumerable.rb
+- lib/remotable/core_ext/uri.rb
+- lib/remotable/nosync.rb
 - lib/remotable/version.rb
 - remotable.gemspec
 - test/factories/tenants.rb
+- test/nosync_test.rb
 - test/remotable_test.rb
 - test/support/active_resource.rb
 - test/support/schema.rb
@@ -141,12 +158,18 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: -3964453781744969533
+      segments: 
+      - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: -3964453781744969533
+      segments: 
+      - 0
       version: "0"
 requirements: []
 
@@ -157,6 +180,7 @@ specification_version: 3
 summary: Binds an ActiveRecord model to a remote resource and keeps the two synchronized
 test_files: 
 - test/factories/tenants.rb
+- test/nosync_test.rb
 - test/remotable_test.rb
 - test/support/active_resource.rb
 - test/support/schema.rb