remotely 0.0.4

data/lib/remotely/ext/url.rb

@@ -0,0 +1,29 @@
+class URL
+  include Comparable
+
+  def initialize(*args)
+    @url = "/" + args.flatten.compact.join("/")
+    @url.gsub! %r[/{2,}], "/"
+    @url.gsub! %r[/$], ""
+  end
+
+  def +(other)
+    URL.new(to_s, other.to_s)
+  end
+
+  def -(other)
+    URL.new(to_s.gsub(other.to_s, ""))
+  end
+
+  def <=>(other)
+    @url <=> other.to_s
+  end
+
+  def to_s
+    @url
+  end
+end
+
+def URL(*args)
+  URL.new(*args)
+end

data/lib/remotely/http_methods.rb

@@ -0,0 +1,205 @@
+module Remotely
+  module HTTPMethods
+    # HTTP status codes that are represent successful requests
+    SUCCESS_STATUSES = (200..299)
+
+    # @return [Symbol] the name of the app the model is fetched from
+    attr_accessor :app
+
+    # @return [String] the relative uri to the model's type of resource
+    attr_accessor :uri
+
+    # Set or get the app for this model belongs to. If name is passed,
+    # it's a setter, otherwise, a getter.
+    #
+    # @overload app()
+    #   Gets the current `app` value.
+    #
+    # @overload app(name)
+    #   Sets the value of `app`.
+    #   @param [Symbol] name Name corresponding to an app defined via Remotely.app.
+    #
+    # @return [Symbol] New app symbol or current value.
+    #
+    def app(name=nil)
+      if @app.nil? && name.nil? && Remotely.apps.size == 1
+        name = Remotely.apps.first.first
+      end
+
+      (name and @app = name) or @app
+    end
+
+    # Set or get the base uri for this model. If name is passed,
+    # it's a setter, otherwise, a getter.
+    #
+    # @overload uri()
+    #   Gets the current `uri` value.
+    #
+    # @overload uri(path)
+    #   Sets the value of `uri`.
+    #   @param [Symbol] path Relative path to this type of resource.
+    #
+    # @return [String] New uri or current value.
+    #
+    def uri(path=nil)
+      (path and @uri = path) or @uri
+    end
+
+    # The connection to the remote API.
+    #
+    # @return [Faraday::Connection] Connection to the remote API.
+    #
+    def remotely_connection
+      address = Remotely.apps[app][:base]
+      address = "http://#{address}" unless address =~ /^http/
+
+      @connection ||= Faraday::Connection.new(address) do |b|
+        b.request  :url_encoded
+        b.adapter  :net_http
+      end
+
+      @connection.basic_auth(*Remotely.basic_auth) if Remotely.basic_auth
+      @connection
+    end
+
+    # GET request.
+    #
+    # @param [String] uri Relative path of request.
+    # @param [Hash] params Query string, in key-value Hash form.
+    #
+    # @return [Remotely::Collection, Remotely::Model, Hash] If the result
+    #   is an array, Collection, if it's a hash, Model, otherwise it's the
+    #   parsed response body.
+    #
+    def get(uri, options={})
+      uri      = expand(uri)
+      klass    = options.delete(:class)
+      parent   = options.delete(:parent)
+
+      before_request(uri, :get, options)
+
+      response = remotely_connection.get { |req| req.url(uri, options) }
+      parse_response(raise_if_html(response), klass, parent)
+    end
+
+    # POST request.
+    #
+    # Used mainly to create new resources. Remotely assumes that the
+    # remote API will return the newly created object, in JSON form,
+    # with the `id` assigned to it.
+    #
+    # @param [String] uri Relative path of request.
+    # @param [Hash] params Request payload. Gets JSON-encoded.
+    #
+    # @return [Remotely::Collection, Remotely::Model, Hash] If the result
+    #   is an array, Collection, if it's a hash, Model, otherwise it's the
+    #   parsed response body.
+    #
+    def post(uri, options={})
+      uri    = expand(uri)
+      klass  = options.delete(:class)
+      parent = options.delete(:parent)
+      body   = options.delete(:body) || Yajl::Encoder.encode(options)
+
+      before_request(uri, :post, body)
+      raise_if_html(remotely_connection.post(uri, body))
+    end
+
+    # PUT request.
+    #
+    # @param [String] uri Relative path of request.
+    # @param [Hash] params Request payload. Gets JSON-encoded.
+    #
+    # @return [Boolean] Was the request successful? (Resulted in a
+    #   200-299 response code)
+    #
+    def put(uri, options={})
+      uri  = expand(uri)
+      body = options.delete(:body) || Yajl::Encoder.encode(options)
+
+      before_request(uri, :put, body)
+      raise_if_html(remotely_connection.put(uri, body))
+    end
+
+    # DELETE request.
+    #
+    # @param [String] uri Relative path of request.
+    #
+    # @return [Boolean] Was the resource deleted? (Resulted in a
+    #   200-299 response code)
+    #
+    def http_delete(uri)
+      uri = expand(uri)
+      before_request(uri, :delete)
+      response = raise_if_html(remotely_connection.delete(uri))
+      SUCCESS_STATUSES.include?(response.status)
+    end
+
+    # Expand a URI to include any path specified in the the main app
+    # configuration. When creating a Faraday object with a path that
+    # includes a uri, eg: "localhost:1234/api", Faraday drops the path,
+    # making it "localhost:1234". We need to add the "/api" back in
+    # before our relative uri.
+    #
+    # @example
+    #   Remotely.configure { app :thingapp, "http://example.com/api" }
+    #   Model.expand("/members") # => "/api/members"
+    #
+    def expand(uri)
+      baseuri = Remotely.apps[app][:uri]
+      uri =~ /^#{baseuri}/ ? uri : URL(baseuri, uri)
+    end
+
+    # Gets called before a request. Override to add logging, etc.
+    def before_request(uri, http_verb = :get, options = {})
+      if ENV['REMOTELY_DEBUG']
+        puts "-> #{http_verb.to_s.upcase} #{uri}" 
+        puts "   #{options.inspect}"
+      end
+    end
+
+    def raise_if_html(response)
+      if response.body =~ %r(<html>)
+        raise Remotely::NonJsonResponseError.new(response.body)
+      end
+      response
+    end
+
+    # Parses the response depending on what was returned. The following
+    # table described what gets return in what situations.
+    #
+    # ------------+------------------+--------------
+    # Status Code | Return Body Type | Return Value
+    # ------------+------------------+--------------
+    #   >= 400    |       N/A        |    false
+    # ------------+------------------+--------------
+    #   200-299   |      Array       |  Collection
+    # ------------+------------------+--------------
+    #   200-299   |      Hash        |     Model
+    # ------------+------------------+--------------
+    #   200-299   |      Other       | Parsed JSON
+    # ------------+------------------+--------------
+    #
+    # @param [Faraday::Response] response Response object
+    #
+    # @return [Remotely::Collection, Remotely::Model, Other] If the result
+    #   is an array, Collection, if it's a hash, Model, otherwise it's the
+    #   parsed response body.
+    #
+    def parse_response(response, klass=nil, parent=nil)
+      return false if response.status >= 400
+
+      body  = Yajl::Parser.parse(response.body) rescue nil
+      klass = (klass || self)
+
+      case body
+      when Array
+        Collection.new(parent, klass, body.map { |o| klass.new(o) })
+      when Hash
+        klass.new(body)
+      else
+        body
+      end
+    end
+  end
+end

data/lib/remotely/model.rb

@@ -0,0 +1,317 @@
+module Remotely
+  class Model
+    extend  Forwardable
+    extend  ActiveModel::Naming
+    include ActiveModel::Conversion
+    include Associations
+
+    class << self
+      include Remotely::HTTPMethods
+
+      # Array of attributes to be sent when saving
+      attr_reader :savable_attributes
+
+      # Mark an attribute as safe to save. The `save` method
+      # will only send these attributes when called.
+      #
+      # @param [Symbols] *attrs List of attributes to make savable.
+      #
+      # @example Mark `name` and `age` as savable
+      #   attr_savable :name, :age
+      #
+      def attr_savable(*attrs)
+        @savable_attributes ||= []
+        @savable_attributes += attrs
+        @savable_attributes.uniq!
+      end
+
+      # Fetch all entries.
+      #
+      # @return [Remotely::Collection] collection of entries
+      #
+      def all
+        get uri
+      end
+
+      # Retreive a single object. Combines `uri` and `id` to determine
+      # the URI to use.
+      #
+      # @param [Fixnum] id The `id` of the resource.
+      #
+      # @example Find the User with id=1
+      #   User.find(1)
+      #
+      # @return [Remotely::Model] Single model object.
+      #
+      def find(id)
+        get URL(uri, id)
+      end
+
+      # Fetch the first record matching +attrs+ or initialize a new instance
+      # with those attributes.
+      #
+      # @param [Hash] attrs Attributes to search by, and subsequently instantiate
+      #   with, if not found.
+      #
+      # @return [Remotely::Model] Fetched or initialized model object
+      #
+      def find_or_initialize(attrs={})
+        where(attrs).first or new(attrs)
+      end
+
+      # Fetch the first record matching +attrs+ or initialize and save a new
+      # instance with those attributes.
+      #
+      # @param [Hash] attrs Attributes to search by, and subsequently instantiate
+      #   and save with, if not found.
+      #
+      # @return [Remotely::Model] Fetched or initialized model object
+      #
+      def find_or_create(attrs={})
+        where(attrs).first or create(attrs)
+      end
+
+      # Search the remote API for a resource matching conditions specified
+      # in `params`. Sends `params` as a url-encoded query string. It
+      # assumes the search endpoint is at "/resource_plural/search".
+      #
+      # @param [Hash] params Key-value pairs of attributes and values to search by.
+      #
+      # @example Search for a person by name and title
+      #   User.where(:name => "Finn", :title => "The Human")
+      #
+      # @return [Remotely::Collection] Array-like collection of model objects.
+      #
+      def where(params={})
+        get URL(uri, "search"), params
+      end
+
+      # Creates a new resource.
+      #
+      # @param [Hash] params Attributes to create the new resource with.
+      #
+      # @return [Remotely::Model, Boolean] If the creation succeeds, a new
+      #   model object is returned, otherwise false.
+      #
+      def create(params={})
+        new(params).save
+      end
+
+      alias :create! :create
+
+      # Update every entry with values from +params+.
+      #
+      # @param [Hash] params Key-Value pairs of attributes to update
+      # @return [Boolean] If the update succeeded
+      #
+      def update_all(params={})
+        put uri, params
+      end
+
+      alias :update_all! :update_all
+
+      # Destroy an individual resource.
+      #
+      # @param [Fixnum] id id of the resource to destroy.
+      #
+      # @return [Boolean] If the destruction succeeded.
+      #
+      def destroy(id)
+        http_delete URL(uri, id)
+      end
+
+      alias :destroy! :destroy
+
+      # Remotely models don't support single table inheritence
+      # so the base class is always itself.
+      #
+      def base_class
+        self
+      end
+
+    private
+
+      # Search by one or more attribute and their values.
+      #
+      # @param [String, Symbol] name The attribute name
+      # @param [String, Symbol] value Value to search by
+      #
+      # @see .where
+      #
+      def find_by(name, *args)
+        where(Hash[name.split("_and_").zip(args)]).first
+      end
+
+      def method_missing(name, *args, &block)
+        return find_by($1, *args) if name.to_s =~ /^find_by_(.*)!?$/
+        super
+      end
+    end
+
+    def_delegators :"self.class", :uri, :get, :post, :put, :parse_response
+
+    # @return [Hash] Key-value of attributes and values.
+    attr_accessor :attributes
+
+    def initialize(attributes={})
+      set_errors(attributes.delete('errors')) if attributes['errors']
+      self.attributes = attributes.symbolize_keys
+      associate!
+    end
+
+    # Update a single attribute.
+    #
+    # @param [Symbol, String] name Attribute name
+    # @param [Mixed] value New value for the attribute
+    # @param [Boolean] should_save Should it save after updating
+    #   the attributes. Default: true
+    # @return [Boolean, Mixed] Boolean if the it tried to save, the
+    #   new value otherwise.
+    #
+    def update_attribute(name, value)
+      self.attributes[name.to_sym] = value
+      save
+    end
+
+    # Update multiple attributes.
+    #
+    # @param [Hash] attrs Hash of attributes/values to update with.
+    # @return [Boolean] Did the save succeed.
+    #
+    def update_attributes(attrs={})
+      @attribute_cache = self.attributes.dup
+      self.attributes.merge!(attrs.symbolize_keys)
+
+      if save && self.errors.empty?
+        true
+      else
+        self.attributes = @attribute_cache
+        false
+      end
+    end
+
+    # Persist this object to the remote API.
+    #
+    # If the request returns a status code of 201 or 200 
+    # (for creating new records and updating existing ones,
+    # respectively) it is considered a successful save and returns 
+    # the object. Any other status will result in a return value 
+    # of false. In addition, the `obj.errors` collection will be 
+    # populated with any errors returns from the remote API.
+    #
+    # For `save` to handle errors correctly, the remote API should
+    # return a response body which matches a JSONified ActiveRecord
+    # errors object. ie:
+    #
+    #   {"errors":{"attribute":["message", "message"]}}
+    #
+    # @return [Boolean, Model] 
+    #   Remote API returns 200/201 status:   the new/updated model object
+    #   Remote API returns any other status: false
+    #
+    def save
+      method = new_record? ? :post      : :put
+      status = new_record? ? 201        : 200
+      attrs  = new_record? ? attributes : attributes.slice(*savable_attributes)
+      url    = new_record? ? uri        : URL(uri, id)
+
+      resp = public_send(method, url, attrs)
+      body = Yajl::Parser.parse(resp.body)
+
+      if resp.status == status && !body.nil?
+        self.attributes.merge!(body.symbolize_keys)
+      else
+        set_errors(body.delete("errors")) unless body.nil?
+      end
+
+      self
+    end
+
+    def savable_attributes
+      (self.class.savable_attributes || attributes.keys) << :id
+    end
+
+    # Sets multiple errors with a hash
+    def set_errors(hash)
+      (hash || {}).each do |attribute, messages|
+        Array(messages).each {|m| errors.add(attribute, m) }
+      end
+    end
+
+    # Track errors with ActiveModel::Errors
+    def errors
+      @errors ||= ActiveModel::Errors.new(self)
+    end
+
+    # Destroy this object with the might of 60 jotun!
+    #
+    def destroy
+      self.class.destroy(id)
+    end
+
+    # Re-fetch the resource from the remote API.
+    #
+    def reload
+      self.attributes = get(URL(uri, id)).attributes
+      self
+    end
+
+    def id
+      self.attributes[:id]
+    end
+
+    # Assumes that if the object doesn't have an `id`, it's new.
+    #
+    def new_record?
+      self.attributes[:id].nil?
+    end
+
+    def persisted?
+      !new_record?
+    end
+
+    def respond_to?(name)
+      self.attributes and self.attributes.include?(name) or super
+    end
+
+    def to_json
+      Yajl::Encoder.encode(self.attributes)
+    end
+
+  private
+
+    def metaclass
+      (class << self; self; end)
+    end
+
+    # Finds all attributes that match `*_id`, and creates a method for it,
+    # that will fetch that record. It uses the `*` part of the attribute
+    # to determine the model class and calls `find` on it with the value
+    # if the attribute.
+    #
+    def associate!
+      self.attributes.select { |k,v| k =~ /_id$/ }.each do |key, id|
+        name = key.to_s.gsub("_id", "")
+        metaclass.send(:define_method, name) { |reload=false| fetch(name, id, reload) }
+      end
+    end
+
+    def fetch(name, id, reload)
+      klass = name.to_s.classify.constantize
+      set_association(name, klass.find(id)) if reload || association_undefined?(name)
+      get_association(name)
+    end
+
+    def method_missing(name, *args, &block)
+      if self.attributes.include?(name)
+        self.attributes[name]
+      elsif name =~ /(.*)=$/ && self.attributes.include?($1.to_sym)
+        self.attributes[$1.to_sym] = args.first
+      elsif name =~ /(.*)\?$/ && self.attributes.include?($1.to_sym)
+        !!self.attributes[$1.to_sym]
+      else
+        super
+      end
+    end
+  end
+end