knuverse-knufactor 0.0.1

data/lib/knuverse/knufactor/api_exception.rb

@@ -0,0 +1,7 @@
+module KnuVerse
+  module Knufactor
+    # Generic Exception definition
+    class APIException < StandardError
+    end
+  end
+end

data/lib/knuverse/knufactor/exceptions/api_client_not_configured.rb

@@ -0,0 +1,9 @@
+module KnuVerse
+  module Knufactor
+    module Exceptions
+      # The client must be configured before it can be used
+      class APIClientNotConfigured < APIException
+      end
+    end
+  end
+end

data/lib/knuverse/knufactor/exceptions/immutable_modification.rb

@@ -0,0 +1,9 @@
+module KnuVerse
+  module Knufactor
+    module Exceptions
+      # Provided when an attempt is made to modify an immutable resource
+      class ImmutableModification < APIException
+      end
+    end
+  end
+end

data/lib/knuverse/knufactor/exceptions/invalid_arguments.rb

@@ -0,0 +1,9 @@
+module KnuVerse
+  module Knufactor
+    module Exceptions
+      # Missing, incorrect argument(s) were passed
+      class InvalidArguments < APIException
+      end
+    end
+  end
+end

data/lib/knuverse/knufactor/exceptions/invalid_options.rb

@@ -0,0 +1,9 @@
+module KnuVerse
+  module Knufactor
+    module Exceptions
+      # Missing, incorrect, or extra options were passed
+      class InvalidOptions < APIException
+      end
+    end
+  end
+end

data/lib/knuverse/knufactor/exceptions/invalid_property.rb

@@ -0,0 +1,9 @@
+module KnuVerse
+  module Knufactor
+    module Exceptions
+      # Provided when property definitions use inappropriate names
+      class InvalidProperty < APIException
+      end
+    end
+  end
+end

data/lib/knuverse/knufactor/exceptions/invalid_where_query.rb

@@ -0,0 +1,9 @@
+module KnuVerse
+  module Knufactor
+    module Exceptions
+      # Provided when a query is constructed but is invalid
+      class InvalidWhereQuery < APIException
+      end
+    end
+  end
+end

data/lib/knuverse/knufactor/exceptions/missing_path.rb

@@ -0,0 +1,9 @@
+module KnuVerse
+  module Knufactor
+    module Exceptions
+      # Provided when a method is called on an incomplete resource definition
+      class MissingPath < APIException
+      end
+    end
+  end
+end

data/lib/knuverse/knufactor/exceptions/new_instance_with_id.rb

@@ -0,0 +1,9 @@
+module KnuVerse
+  module Knufactor
+    module Exceptions
+      # ID can not be manually specified on resources
+      class NewInstanceWithID < APIException
+      end
+    end
+  end
+end

data/lib/knuverse/knufactor/helpers/api_client.rb

@@ -0,0 +1,36 @@
+module KnuVerse
+  module Knufactor
+    module Helpers
+      # Simple helper methods for the API Client
+      module APIClient
+        # Substitute characters with their JSON-supported versions
+        # @return [String]
+        def json_escape(s)
+          json_escape = {
+            '&' => '\u0026',
+            '>' => '\u003e',
+            '<' => '\u003c',
+            '%' => '\u0025',
+            "\u2028" => '\u2028',
+            "\u2029" => '\u2029'
+          }
+          json_escape_regex = /[\u2028\u2029&><%]/u
+
+          s.to_s.gsub(json_escape_regex, json_escape)
+        end
+
+        # Provides access to the "raw" underlying rest-client
+        # @return [RestClient::Resource]
+        def raw
+          connection
+        end
+
+        # The API Client version (uses Semantic Versioning)
+        # @return [String]
+        def version
+          VERSION
+        end
+      end
+    end
+  end
+end

data/lib/knuverse/knufactor/helpers/resource.rb

@@ -0,0 +1,112 @@
+module KnuVerse
+  module Knufactor
+    module Helpers
+      # Simple helper methods for Resources
+      module Resource
+        def datetime_from_params(params, actual_key)
+          DateTime.new(
+            params["#{actual_key}(1i)"].to_i,
+            params["#{actual_key}(2i)"].to_i,
+            params["#{actual_key}(3i)"].to_i,
+            params["#{actual_key}(4i)"].to_i,
+            params["#{actual_key}(5i)"].to_i
+          )
+        end
+
+        def fresh?
+          !tainted?
+        end
+
+        def id_property
+          self.class.properties.select { |_, opts| opts[:id_property] }.keys.first
+        end
+
+        def id
+          @entity[id_property.to_s]
+        end
+
+        def immutable?
+          self.class.immutable?
+        end
+
+        # ActiveRecord ActiveModel::Name compatibility method
+        def model_name
+          self.class
+        end
+
+        def new?
+          !@entity.key?(id_property.to_s)
+        end
+
+        def paths
+          self.class.paths
+        end
+
+        def path_for(kind)
+          self.class.path_for(kind)
+        end
+
+        # ActiveRecord ActiveModel::Model compatibility method
+        def persisted?
+          !new?
+        end
+
+        def properties
+          self.class.properties
+        end
+
+        def tainted?
+          @tainted ? true : false
+        end
+
+        # ActiveRecord ActiveModel::Conversion compatibility method
+        def to_key
+          new? ? [] : [id]
+        end
+
+        # ActiveRecord ActiveModel::Conversion compatibility method
+        def to_model
+          self
+        end
+
+        # ActiveRecord ActiveModel::Conversion compatibility method
+        def to_param
+          new? ? nil : id.to_s
+        end
+
+        # ActiveRecord ActiveModel compatibility method
+        def update(params)
+          new_params = {}
+          # need to convert multi-part datetime params
+          params.each do |key, value|
+            if key =~ /([^(]+)\(1i/
+              actual_key = key.match(/([^(]+)\(/)[1]
+              new_params[actual_key] = datetime_from_params(params, actual_key)
+            else
+              new_params[key] = value
+            end
+          end
+
+          new_params.each do |key, value|
+            setter_key = "#{key}=".to_sym
+            raise Exceptions::InvalidProperty unless respond_to?(setter_key)
+            send(setter_key, value)
+          end
+          save
+        end
+
+        def <=>(other)
+          if id < other.id
+            -1
+          elsif id > other.id
+            1
+          elsif id == other.id
+            0
+          else
+            raise Exceptions::InvalidArguments
+          end
+        end
+      end
+    end
+  end
+end

data/lib/knuverse/knufactor/helpers/resource_class.rb

@@ -0,0 +1,49 @@
+module KnuVerse
+  module Knufactor
+    module Helpers
+      # Simple helper class methods for Resource
+      module ResourceClass
+        # Produce a more human-readable representation of {#i18n_key}
+        # @note ActiveRecord ActiveModel::Name compatibility method
+        # @return [String]
+        def human
+          i18n_key.humanize
+        end
+
+        # Check if a resource class is immutable
+        def immutable?
+          @immutable ||= false
+        end
+
+        # A mock internationalization key based on the class name
+        # @note ActiveRecord ActiveModel::Name compatibility method
+        # @return [String]
+        def i18n_key
+          name.split('::').last.to_underscore
+        end
+
+        alias singular_route_key i18n_key
+
+        # A symbolized version of {#i18n_key}
+        # @note ActiveRecord ActiveModel::Name compatibility method
+        # @return [Symbol]
+        def param_key
+          i18n_key.to_sym
+        end
+
+        # All the properties defined for this Resource class
+        # @return [Hash{Symbol => Hash}]
+        def properties
+          @properties ||= {}
+        end
+
+        # A route key for building URLs
+        # @note ActiveRecord ActiveModel::Name compatibility method
+        # @return [String]
+        def route_key
+          i18n_key.en.plural
+        end
+      end
+    end
+  end
+end

data/lib/knuverse/knufactor/resource.rb

@@ -0,0 +1,207 @@
+module KnuVerse
+  module Knufactor
+    # A generic API resource
+    # TODO: Thread safety
+    class Resource
+      attr_accessor :client
+      attr_reader :errors
+
+      include Comparable
+      include Validations::Resource
+      include Helpers::Resource
+      extend Helpers::ResourceClass
+
+      # Can this type of resource be changed client-side?
+      def self.immutable(status)
+        unless status.is_a?(TrueClass) || status.is_a?(FalseClass)
+          raise Exceptions::InvalidArguments
+        end
+        @immutable = status
+      end
+
+      # Define a property for a model
+      # @!macro [attach] property
+      #   The $1 property
+      # @todo add more validations on options and names
+      def self.property(name, options = {})
+        @properties ||= {}
+
+        invalid_prop_names = [
+          :>, :<, :'=', :class, :def,
+          :%, :'!', :/, :'.', :'?', :*, :'{}',
+          :'[]'
+        ]
+
+        raise(Exceptions::InvalidProperty) if invalid_prop_names.include?(name.to_sym)
+        @properties[name.to_sym] = options
+      end
+
+      # Set the URI path for a resource method
+      def self.path(kind, uri)
+        paths[kind.to_sym] = uri
+      end
+
+      # Create or set a class-level location to store URI paths for methods
+      # @return [Hash{Symbol => String}]
+      def self.paths
+        @paths ||= {}
+      end
+
+      def self.path_for(kind)
+        guess = kind.to_sym == :all ? route_key : "#{route_key}/#{kind}"
+        paths[kind.to_sym] || guess
+      end
+
+      def self.gen_getter_method(name, opts)
+        method_name = opts[:type] == :boolean ? "#{name}?" : name
+        define_method(method_name.to_sym) do
+          name_as_string = name.to_s
+          reload if @lazy && !@entity.key?(name_as_string)
+
+          case opts[:type]
+          when :time
+            if @entity[name_as_string] && !@entity[name_as_string].to_s.empty?
+              Time.parse(@entity[name_as_string].to_s).utc
+            end
+          else
+            @entity[name_as_string]
+          end
+        end
+      end
+
+      def self.gen_setter_method(name, opts)
+        define_method("#{name}=".to_sym) do |value|
+          raise Exceptions::ImmutableModification if immutable?
+          # TODO: allow specifying a list of allowed values and validating against it
+          @entity[name.to_s] = opts[:type] == :time ? Time.parse(value.to_s).utc : value
+          @tainted = true
+          @modified_properties << name.to_sym
+        end
+      end
+
+      def self.gen_property_methods
+        properties.each do |prop, opts|
+          # Getter methods
+          next if opts[:id_property]
+          gen_getter_method(prop, opts) unless opts[:write_only]
+
+          # Setter methods (don't make one for obviously read-only properties)
+          gen_setter_method(prop, opts) unless opts[:read_only]
+        end
+      end
+
+      def self.all(options = {})
+        # TODO: Add validations for options
+
+        # TODO: add validation checks for the required pieces
+        raise Exceptions::MissingPath unless path_for(:all)
+
+        api_client = options[:api_client] || APIClient.instance
+
+        root = name.split('::').last.en.plural.to_underscore
+        # TODO: do something with lazy requests...
+
+        ResourceCollection.new(
+          api_client.get(path_for(:all))[root].collect do |record|
+            new(
+              entity: record,
+              lazy: (options[:lazy] ? true : false),
+              tainted: false,
+              api_client: api_client
+            )
+          end,
+          type: self,
+          api_client: api_client
+        )
+      end
+
+      def self.get(id, options = {})
+        # TODO: Add validations for options
+        raise Exceptions::MissingPath unless path_for(:all)
+
+        api_client = options[:api_client] || APIClient.instance
+
+        new(
+          entity: api_client.get("#{path_for(:all)}/#{id}"),
+          lazy: false,
+          tainted: false,
+          api_client: api_client
+        )
+      end
+
+      def self.where(attribute, value, options = {})
+        # TODO: validate incoming options
+        options[:comparison] ||= value.is_a?(Regexp) ? :match : '=='
+        api_client = options[:api_client] || APIClient.instance
+        all(lazy: (options[:lazy] ? true : false), api_client: api_client).where(
+          attribute, value, comparison: options[:comparison]
+        )
+      end
+
+      def initialize(options = {})
+        # TODO: better options validations
+        raise Exceptions::InvalidOptions unless options.is_a?(Hash)
+
+        @entity = options[:entity] || {}
+
+        # Allows lazy-loading if we're told this is a lazy instance
+        #  This means only the minimal attributes were fetched.
+        #  This shouldn't be set by end-users.
+        @lazy = options.key?(:lazy) ? options[:lazy] : false
+        # This allows local, user-created instances to be differentiated from fetched
+        # instances from the backend API. This shouldn't be set by end-users.
+        @tainted = options.key?(:tainted) ? options[:tainted] : true
+        # This is the API Client used to get data for this resource
+        @api_client = options[:api_client] || APIClient.instance
+        @errors = {}
+        # A place to store which properties have been modified
+        @modified_properties = []
+
+        validate_mutability
+        validate_id
+
+        self.class.class_eval { gen_property_methods }
+      end
+
+      def destroy
+        raise Exceptions::ImmutableModification if immutable?
+        unless new?
+          @api_client.delete("#{path_for(:all)}/#{id}")
+          @lazy = false
+          @tainted = true
+          @entity.delete('id')
+        end
+        true
+      end
+
+      def reload
+        if new?
+          # Can't reload a new resource
+          false
+        else
+          @entity  = @api_client.get("#{path_for(:all)}/#{id}")
+          @lazy    = false
+          @tainted = false
+          true
+        end
+      end
+
+      def save
+        saveable_data = @entity.select do |prop, value|
+          pr = prop.to_sym
+          go = properties.key?(pr) && !properties[pr][:read_only] && !value.nil?
+          @modified_properties.uniq.include?(pr) if go
+        end
+
+        if new?
+          @entity  = @api_client.post(path_for(:all).to_s, saveable_data)
+          @lazy    = true
+        else
+          @api_client.put("#{path_for(:all)}/#{id}", saveable_data)
+        end
+        @tainted = false
+        true
+      end
+    end
+  end
+end