arkenstone-open 3.0.1

data/lib/arkenstone/associations.rb

@@ -0,0 +1,389 @@
+# frozen_string_literal: true
+
+require 'active_support/inflector'
+
+# TODO: consider splitting the bigger associations (has_many) into separate files
+module Arkenstone
+  module Associations
+    class << self
+      def included(base)
+        base.send :include, Arkenstone::Associations::Resources
+        base.send :include, Arkenstone::Associations::InstanceMethods
+        base.extend Arkenstone::Associations::ClassMethods
+      end
+    end
+
+    module ClassMethods
+      # All association data is stored in a hash (@arkenstone_data) on the instance of the class. Each entry in the hash is keyed off the association name. The value of the hash key is a basic array. This can be wrapped up and extended if (when) more functionality is needed.
+      # `setup_arkenstone_data` creates the following *instance* methods on the class:
+      #
+      # `arkenstone_data` - the hash for the association data. Only use this if you're absolutely 100% sure that you don't need to get up to date data.
+      #
+      # `wipe_arkenstone_cache` - clears the cache for the association provided
+      def setup_arkenstone_data
+        define_method('arkenstone_data') do
+          @arkenstone_data = {} if @arkenstone_data.nil?
+          @arkenstone_data
+        end
+
+        define_method('wipe_arkenstone_cache') do |model_name|
+          arkenstone_data[model_name] = nil
+        end
+      end
+
+      # Creates a One to Many association with the supplied `child_model_name`. Example:
+      #
+      #     class Flea
+      #     end
+      #
+      #     class Llama
+      #       has_many :fleas
+      #
+      #     end
+      #
+      # Once `has_many` has evaluated, the structure of `Llama` will look like this:
+      #
+      #     class Llama
+      #       url 'http://example.com/llamas'
+      #
+      #       def cached_fleas
+      #         #snip
+      #       end
+      #
+      #       def fleas
+      #         #snip
+      #       end
+      #
+      #       def flea_ids
+      #         [...] # all the ids of the fleas
+      #       end
+      #
+      #       def add_flea(new_flea)
+      #         #snip
+      #       end
+      #
+      #       def remove_flea(flea_to_remove)
+      #         #snip
+      #       end
+      #     end
+      #
+      # You can override the url of the association by passing in model_name: 'something'. This will change the URL it fetches from to use the `model_name` instead:
+      #
+      #    has_many :fleas, model_name: 'bugs'
+      #
+      # Will fetch `fleas` from `http://example.com/llamas/:id/bugs.
+      def has_many(child_model_name, options = {})
+        setup_arkenstone_data
+        child_url_fragment = options[:model_name] || child_model_name
+        child_class_name = options[:class_name] || child_model_name
+
+        # The method for accessing the cached data is `cached_[name]`. If the cache is empty it creates a request to repopulate it from the server.
+        cached_child_name = "cached_#{child_model_name}"
+        add_association_method cached_child_name do
+          cache = arkenstone_data
+          if cache[child_model_name].nil?
+            child_instances = fetch_children child_class_name, child_url_fragment
+            attach_nested_has_many_resource_methods(child_instances, child_model_name, child_class_name)
+            cache[child_model_name] = child_instances
+          end
+          cache[child_model_name]
+        end
+
+        # The uncached version is the name supplied to has_many. It wipes the cache for the association and refetches it.
+        add_association_method child_model_name do
+          wipe_arkenstone_cache child_model_name
+          send cached_child_name
+        end
+
+        # Creates an array of the ids of the child models for quick access.
+        singular = child_model_name.to_s.singularize
+        add_association_method "#{singular}_ids" do
+          (send cached_child_name).map(&:id)
+        end
+
+        # Add a model to the association with add_[child_model_name]. It performs two network calls, one to add it, then another to refetch the association.
+        add_child_method_name = "add_#{singular}"
+        add_association_method add_child_method_name do |new_child|
+          add_child child_model_name, new_child.id
+          wipe_arkenstone_cache child_model_name
+          send cached_child_name
+        end
+
+        # Remove a model from the association with remove_[child_model_name]. It performs two network calls, one to add it, then another to refetch the association.
+        remove_child_method_name = "remove_#{singular}"
+        add_association_method remove_child_method_name do |child_to_remove|
+          remove_child child_model_name, child_to_remove.id
+          wipe_arkenstone_cache child_model_name
+          send cached_child_name
+        end
+      end
+
+      # Similar to `has_many` but for a One to One association. Example:
+      #
+      #     class Hat
+      #     end
+      #
+      #     class Llama
+      #       has_one :hat
+      #     end
+      #
+      # Once `has_one` has evaluated, the structure of `Llama` will look like this:
+      #
+      #     class Llama
+      #       def cached_hat
+      #         #snip
+      #       end
+      #
+      #       def hat
+      #         #snip
+      #       end
+      #
+      #       def hat=(new_value)
+      #         #snip
+      #       end
+      #     end
+      #
+      # If nil is passed into the setter method (`hat=` in the above example), the association is removed.
+      def has_one(child_model_name, options = {})
+        setup_arkenstone_data
+        child_url_fragment = options[:model_name] || child_model_name
+
+        # The method for accessing the cached single resource is `cached_[name]`. If the value is nil it creates a request to pull the value from the server.
+        cached_child_name = "cached_#{child_model_name}"
+        add_association_method cached_child_name do
+          cache = arkenstone_data
+          cache[child_model_name] = fetch_child child_model_name, child_url_fragment if cache[child_model_name].nil?
+          cache[child_model_name]
+        end
+
+        # The uncached version is retrieved by wiping the cache for the association, and then re-getting it.
+        add_association_method child_model_name do
+          arkenstone_data[child_model_name] = nil
+          send cached_child_name
+        end
+
+        # A single association is updated or removed with a setter method.
+        setter_method_name = "#{child_model_name}="
+        add_association_method setter_method_name do |new_value|
+          if new_value.nil?
+            old_model = send child_model_name
+            remove_child child_model_name, old_model.id
+            wipe_arkenstone_cache child_model_name
+          else
+            add_child child_model_name, new_value.id
+            wipe_arkenstone_cache child_model_name
+            send cached_child_name
+          end
+        end
+      end
+
+      # The opposite of a has_X relationship. Allows you to go back up the association tree. Example:
+      #
+      #     class Hat
+      #       belongs_to :llama
+      #     end
+      #
+      #     class Llama
+      #     end
+      #
+      # Once `belongs_to` has been evaluated, the structure of `Hat` will look like this:
+      #
+      #     class Hat
+      #       def llama
+      #         #snip
+      #       end
+      #     end
+      def belongs_to(parent_model_name)
+        setup_arkenstone_data
+
+        parent_model_field = "#{parent_model_name}_id"
+
+        self.arkenstone_attributes = [] unless arkenstone_attributes
+        arkenstone_attributes << parent_model_field.to_sym
+        class_eval("attr_accessor :#{parent_model_field}", __FILE__, __LINE__)
+
+        # The method for accessing the cached data is `cached_[name]`. If the cache is empty it creates a request to repopulate it from the server.
+        cached_parent_model_name = "cached_#{parent_model_name}"
+        add_association_method cached_parent_model_name do
+          cache = arkenstone_data
+          cache[parent_model_name] = fetch_parent parent_model_name if cache[parent_model_name].nil?
+          cache[parent_model_name]
+        end
+
+        # The uncached version is the name supplied to belongs_to. It wipes the cache for the association and refetches it.
+        add_association_method parent_model_name.to_s do
+          arkenstone_data[parent_model_name] = nil
+          send cached_parent_model_name
+        end
+
+        define_method("#{parent_model_name}=") do |parent_instance|
+          send "#{parent_model_field}=".to_sym, parent_instance.id
+        end
+      end
+
+      ### Support for `has_and_belongs_to_many` relationship
+      def has_and_belongs_to_many(model_klass_name)
+        # Gather the namespace
+        namespace             = to_s.split(/::/)
+        model_klass_name      = model_klass_name.to_s.singularize.underscore.to_sym
+        current_klass_name    = namespace.pop.underscore.to_sym
+
+        # Build join class needs
+        join_klass_name       = [model_klass_name, current_klass_name].sort.join('_')
+        join_klass_classified = join_klass_name.classify.to_sym
+        join_klass_pluralized = join_klass_name.pluralize
+        namespace             = Kernel.const_get(namespace.join('::'))
+
+        # Create the join class if it doesn't exist already
+        unless namespace.constants.include?(join_klass_classified)
+          join_klass = namespace.const_set(join_klass_classified, Class.new)
+          join_klass.instance_eval { include Arkenstone::Document }
+
+          # The join class should belong to both foreign sides of the relationship
+          join_klass.send :belongs_to, model_klass_name
+          join_klass.send :belongs_to, current_klass_name
+        end
+
+        # This class should belong to the join table
+        send(:has_many, join_klass_pluralized.to_sym) unless respond_to?(join_klass_pluralized.to_sym)
+
+        # These are helper variables for the cached and uncached join `:through` instances
+        model_klass_pluralized = model_klass_name.to_s.pluralize
+        cached_instances_field = "cached_#{model_klass_pluralized}"
+
+        send :attr_accessor, cached_instances_field.to_sym
+
+        # Creates a `self.join_through_instances` helper method
+        #
+        # This actually pulls instances of the join model and then maps on the
+        # complimenting foreign key to gather all the foreign join instances
+        #
+        define_method model_klass_pluralized.to_s do
+          current_klass_instance   = self # The instance calling this method
+          current_klass_pluralized = current_klass_name.to_s.pluralize
+
+          # Check for cached joined instances
+          cached_instances = current_klass_instance.send cached_instances_field
+          return cached_instances if cached_instances
+
+          # Get from joined instances
+          model_klass_instances = send("cached_#{join_klass_pluralized}".to_sym).map(&:"#{model_klass_pluralized}")
+
+          # Redefine `<<` so that you can something like `beer.tags << new_tag`
+          model_klass_instances.define_singleton_method :<< do |element|
+            # Use built in `push` for `Array.new`
+            push element
+
+            # Cache the result
+            current_klass_instance.send "#{cached_instances_field}=", self
+
+            # Add the current class instance in the other side of the join
+            # The equivelant of doing `beer.tags << tag` then `tag.beers << beer`
+            #
+            # Grab the current_klass_instances from element
+            element_current_klass_instances = element.send(current_klass_pluralized)
+
+            # Push the current_klass_instance to what element currently has
+            element_current_klass_instances.push(current_klass_instance)
+
+            # Save the new stack of current_klass_instances with element
+            element.send "#{current_klass_pluralized}=", element_current_klass_instances
+
+            # Return the new array
+            self
+          end
+          model_klass_instances
+        end
+
+        # This creates a setter helper to set all joined instances on the
+        # opposite side of the foreign join
+        #
+        define_method "#{model_klass_pluralized}=" do |elements|
+          current_klass_instance = self
+          current_klass_instance.send "#{cached_instances_field}=", elements
+        end
+      end
+
+      # Adds a method to a class unless that method is already defined.
+      def add_association_method(method_name, &method_definition)
+        define_method method_name, method_definition unless method_defined? method_name
+      end
+    end
+
+    module InstanceMethods
+      ### Fetches a `has_many` based resource
+      def fetch_children(child_model_name, child_url_fragment)
+        fetch_nested_resource child_model_name, child_url_fragment do |klass, response_body|
+          klass.parse_all response_body
+        end
+      end
+
+      ### Fetches a single `has_one` based resource
+      def fetch_child(child_model_name, child_url_fragment)
+        fetch_nested_resource child_model_name, child_url_fragment do |klass, response_body|
+          return nil if response_body.nil? || response_body.empty?
+
+          klass.build JSON.parse(response_body)
+        end
+      end
+
+      ### Fetches a single `belongs_to` parent resource.
+      def fetch_parent(parent_model_name)
+        klass_name = parent_model_name.to_s.classify
+        klass_name = prefix_with_class_module klass_name
+        klass      = Kernel.const_get klass_name
+        parent_model_field = "#{parent_model_name}_id"
+        klass.send(:find, send(parent_model_field))
+      end
+
+      ### Calls the POST url for creating a nested_resource
+      def add_child(child_model_name, child_id)
+        url = build_nested_url child_model_name
+        body = { id: child_id }.to_json
+        self.class.send_request url, :post, body
+      end
+
+      ### Calls the DELETE route for a nested resource
+      def remove_child(child_model_name, child_id)
+        url = build_nested_url child_model_name, child_id
+        self.class.send_request url, :delete
+      end
+
+      private
+
+      ### Creates the network request for fetching a child resource. Hands parsing the response off to a callback.
+      def fetch_nested_resource(nested_resource_name, nested_resource_fragment = nested_resource_name, &parser)
+        url = build_nested_url nested_resource_fragment
+        response = self.class.send_request url, :get
+        return [] unless Arkenstone::Network.response_is_success response
+
+        klass_name = nested_resource_name.to_s.classify
+        klass_name = prefix_with_class_module klass_name
+        klass = Kernel.const_get klass_name
+        parser[klass, response.body]
+      end
+
+      # If the class is in a module, preserve the module namespace.
+      # Example:
+      #
+      #     # for the class Zoo::Llama
+      #     prefix_with_class_module('Hat') # 'Zoo::Hat'
+      def prefix_with_class_module(klass)
+        mod = self.class.name.deconstantize
+        klass = "#{mod}::#{klass}" unless mod.empty?
+        klass
+      end
+
+      # Builds a RESTful nested URL based on the instance URL.
+      # Example:
+      #
+      #     build_nested_url('fleas') # http://example.com/llamas/100/fleas
+      #     build_nested_url('fleas', 25) # http://example.com/llamas/100/fleas/25
+      def build_nested_url(child_name, child_id = nil)
+        url = "#{instance_url}/#{child_name}"
+        url += "/#{child_id}" unless child_id.nil?
+        url
+      end
+    end
+  end
+end

data/lib/arkenstone/document.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Arkenstone
+  # == Document
+  #
+  # A `Document` is the main entry point for Arkenstone. A `Document` is a model that is retrieved and/or stored on a RESTful service. For example, if you have a web service that has a URL structure like:
+  #
+  #     http://example.com/users
+  #
+  # You can create a `User` model, include `Document` and it will automatically create methods to fetch and save data from that URL.
+  #
+  #     class User
+  #       include Arkenstone::Document
+  #
+  #       url 'http://example.com/users'
+  #
+  #       attributes :first_name, :last_name, :email
+  #     end
+  #
+  # Attributes create properties on instances that match up with the data returned by the `url`. Properties on the web service are ignored if they are not present within the `attributes` list.
+  module Document
+    class << self
+      def included(base)
+        base.send :include, Arkenstone::Helpers
+        base.send :include, Arkenstone::Associations
+        base.send :include, Arkenstone::Document::InstanceMethods
+        base.send :include, Arkenstone::Network
+        base.extend Arkenstone::Document::ClassMethods
+      end
+    end
+
+    module InstanceMethods
+      ### The convention is for all Documents to have an id.
+      attr_accessor :id, :arkenstone_attributes, :arkenstone_server_errors
+
+      ### Easy access to all of the attributes defined for this Document.
+      def attributes
+        new_hash = {}
+        self.class.arkenstone_attributes.each do |key|
+          new_hash[key.to_sym] = send(key.to_s)
+        end
+        new_hash
+      end
+
+      ### Set attributes for a Document. If a key in the `options` hash is not present in the attributes list, it is ignored.
+      def attributes=(options)
+        options.each do |key, value|
+          setter = "#{key}="
+          send(setter.to_sym, value) if respond_to? setter
+        end
+        attributes
+      end
+
+      ### Returns true if this is a new object that has not been saved yet.
+      def new_record?
+        id.nil?
+      end
+
+      ### Serializes the attributes to json.
+      def to_json(options = {})
+        attributes.to_json(options)
+      end
+
+      ### If this is a new Document, create it with a POST request, otherwise update it with a PUT. Returns whether the server response was successful or not.
+      def save
+        self.class.check_for_url
+        timestamp if respond_to?(:timestampable)
+        response             = new_record? ? post_document_data : put_document_data
+        self.attributes      = JSON.parse(response.body)
+        Arkenstone::Network.response_is_success response
+      end
+
+      ### Reloading the document fetches the document again by it's id
+      def reload
+        reloaded_self = self.class.find(id)
+        self.attributes = reloaded_self.attributes
+        self
+      end
+
+      alias save! save
+
+      ### Update a single attribute. Performs validation (by calling `update_attributes`).
+      def update_attribute(key, value)
+        hash = { key.to_sym => value }
+        update_attributes hash
+      end
+
+      ### Update multiple attributes at once. Performs validation (if that is setup for this document).
+      def update_attributes(new_attributes)
+        attributes.merge! new_attributes
+        save
+      end
+
+      ### Checks if there is a `valid?` method.
+      def has_validation_method?
+        self.class.method_defined? :valid?
+      end
+
+      # Retrieves a RESTful URL for an instance, in this case by tacking an id onto the end of the `arkenstone_url`.
+      # Example:
+      #
+      #     # arkenstone_url
+      #     http://example.com/users
+      #
+      #     # instance_url
+      #     http://example.com/users/100
+      def instance_url
+        "#{full_url(self.class.arkenstone_url)}#{id}"
+      end
+
+      ### The full RESTful URL for a Document.
+      def class_url
+        full_url(self.class.arkenstone_url)
+      end
+
+      ### Save via POST.
+      def post_document_data
+        http_response class_url, :post
+      end
+
+      ### Save via PUT.
+      def put_document_data
+        http_response instance_url, :put
+      end
+
+      ### Sends a DELETE request to the `instance_url`.
+      def destroy
+        resp = http_response instance_url, :delete
+        Arkenstone::Network.response_is_success resp
+      end
+
+      ### Sends a network request with the `attributes` as the body.
+      def http_response(url, method = :post)
+        response = self.class.send_request url, method, saveable_attributes
+        self.arkenstone_server_errors = JSON.parse(response.body) if response.code == '500'
+        response
+      end
+
+      ### Runs any encoding hooks on the attributes if present.
+      def saveable_attributes
+        return attributes unless Arkenstone::Hook.has_hooks? self.class
+
+        attrs = {}
+        Arkenstone::Hook.all_hooks_for_class(self.class).each do |hook|
+          new_attrs = hook.encode_attributes(attributes)
+          attrs.merge! new_attrs unless new_attrs.nil?
+        end
+        attrs.empty? ? attributes : attrs
+      end
+
+      ### Creates a deep dupe of the document with the id set to nil
+      def dup
+        duped = super
+        duped.id = nil
+        duped
+      end
+    end
+
+    module ClassMethods
+      attr_accessor :arkenstone_url, :arkenstone_attributes, :arkenstone_hooks, :arkenstone_inherit_hooks
+
+      ### Sets the root url used for generating RESTful requests.
+      def url(new_url)
+        self.arkenstone_url = new_url
+      end
+
+      # == Hooks
+      #
+      # Hooks are used to allow you to call arbitrary code at various points in the object lifecycle. For example, if you need to massage some property names before they are sent off to the `url`, you can do that with a hook. A hook should extend `Arkenstone::Hook` and then override the method you want to hook into. There are three types of hooks:
+      # 1. `before_request` - Called before the request is sent to the web service. Passes in the request environment (an `Arkenstone::Environment`) as a parameter.
+      # 2. `after_complete` - Called after the request has been *successfully* completed. Passes in a Net::HTTPResponse as a parameter.
+      # 3. `on_error` - Called if the response returned an error. Passes in a Net::HTTPResponse as a parameter.
+      #
+      # Example:
+      #
+      #     class ErrorLogger < Arkenstone::Hook
+      #       def on_error(response)
+      #         # log the error here
+      #       end
+      #     end
+      #
+      #     class User
+      #       include Arkenstone::Document
+      #
+      #       url 'http://example.com/users'
+      #       add_hook ErrorLogger.new
+      #     end
+      def add_hook(hook)
+        self.arkenstone_hooks = [] if arkenstone_hooks.nil?
+        arkenstone_hooks << hook
+      end
+
+      # Hooks are applied **only** to the class they are added to. This can cause a problem if you have a base class and want to use the same hooks for subclasses. If you want to use the same hooks as a parent class, use `inherit_hooks`. This will tell Arkenstone to walk up the inheritance chain and call all of the hooks it can find.
+      # Example:
+      #
+      #     class ErrorLogger < Arkenstone::Hook
+      #       def on_error(response)
+      #         # log the error here
+      #       end
+      #     end
+      #
+      #     class BaseModel
+      #       include Arkenstone::Document
+      #
+      #       add_hook ErrorLogger.new
+      #       add_hook SomeOtherHook.new
+      #     end
+      #
+      #     class User < BaseModel
+      #       url 'http://example.com/users'
+      #
+      #       inherit_hooks
+      #     end
+      #
+      # This will use the hooks defined for `BaseModel` and any defined for `User` too.
+      def inherit_hooks(val: true)
+        self.arkenstone_inherit_hooks = val
+      end
+
+      ### Sets the attributes for an Arkenstone Document. These become `attr_accessors` on instances.
+      def attributes(*options)
+        self.arkenstone_attributes = options
+        options.each do |option|
+          send(:attr_accessor, option)
+        end
+        arkenstone_attributes
+      end
+
+      ### You can use Arkenstone without defining a `url`, but you won't be able to save a model without one. This raises an error if the url is not defined.
+      def check_for_url
+        raise NoUrlError.new, NoUrlError.default_message if arkenstone_url.nil?
+      end
+
+      ### Constructs a new instance with the provided attributes.
+      def build(options)
+        document = new
+        document.attributes = Hash(options).select do |key, _value|
+          document.respond_to? :"#{key}="
+        end
+        document
+      end
+
+      ### Builds a list of objects with attributes set from a JSON string or an array.
+      def parse_all(to_parse)
+        return [] if to_parse.nil? || to_parse.empty?
+
+        tree = if to_parse.is_a? String
+                 JSON.parse to_parse
+               else
+                 to_parse
+               end
+        tree = ensure_parseable_is_array tree
+        documents = tree.map { |document| build document }
+        Arkenstone::QueryList.new documents
+      end
+
+      def ensure_parseable_is_array(to_parse)
+        to_parse = [to_parse] if to_parse.is_a? Hash
+        to_parse
+      end
+
+      ### Creates and saves a single instance with the attribute values provided.
+      def create(options)
+        document = build(options)
+        document.save
+        document
+      end
+
+      ### Performs a GET request to the instance url with the supplied id. Builds an instance with the response.
+      def find(id)
+        check_for_url
+        url      = full_url(arkenstone_url) + id.to_s
+        response = send_request url, :get
+        return nil unless Arkenstone::Network.response_is_success response
+
+        build JSON.parse(response.body)
+      end
+
+      ### Calls the `arkenstone_url` expecting to receive a json array of properties to deserialize into a list of objects.
+      def all
+        check_for_url
+        response = send_request arkenstone_url, :get
+        parse_all response.body
+      end
+    end
+  end
+end

data/lib/arkenstone/enumerable/query_list.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Arkenstone
+  # QueryList extends Array to provide more customized options for Arkenstone documents.
+  class QueryList < Array
+    ### If an array is provided, concatenate it onto the instance so that it becomes one long array. Otherwise, push it on.
+    def initialize(initial_value)
+      if initial_value.instance_of?(Array)
+        concat initial_value
+      else
+        push initial_value
+      end
+    end
+
+    # Assumes that every element is an Arkenstone::Document
+    def to_json(options = nil)
+      map(&:attributes).to_json(options)
+    end
+  end
+end