served 0.1.10 → 0.1.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 441c7ca5f9f68f1df1cae462d85d60a50b50cdc8
-  data.tar.gz: 74b53138ad506df5fb5ad69f95f8218d7aeb1202
+  metadata.gz: 6caeaa76f12084ca80555e8bf472e9f85ebcae70
+  data.tar.gz: 006b93ac7370979237e29fffe4b49a70938684fe
 SHA512:
-  metadata.gz: 666239cf535c226548af6e029f5c2883da475c4131291167b7ee9482953ef197362fe36489a9f62dd34b17918b42a0f91a1c6bf08434687f845a4e3746d3ce7a
-  data.tar.gz: 472b45163683b788ddd9b023a18cd04daf8fe9897d2d31e41c972000d2fd3b1e1e955bd6ed2914f22d8208a0cfc68db309724e2f7178f59da05e7c6af19d5eb4
+  metadata.gz: 9bc45c23b36761e2c2a24bb7fc295f75a807969455c02347acb74d3664de0eb865716b16da51e401bbe73a50fc1ab60fa6c898ec5e816c800d02092425770697
+  data.tar.gz: 51e0f9ceda390a79ee3da2b1fe071ca376bf3538506d7ce6092e327e51b313200a354521b697c7b8034554c5de04db5a7b01aa33f430006a7e16dccdf52a4abc

data/.travis.yml

@@ -1,4 +1,16 @@
 language: ruby
 rvm:
-  - 2.1.2
+  - 2.1
+  - 2.2.2
+  - 2.3.1
 before_install: gem install bundler -v 1.10.5
+
+gemfile:
+  - gemfiles/3.2.gemfile
+  - gemfiles/4.2.gemfile
+  - gemfiles/5.0.gemfile
+
+matrix:
+  exclude:
+    - gemfile: gemfiles/5.0.gemfile
+      rvm: 2.1

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.1.12
+ * add validation support
+ * add serialization support
+ * allow definition of individual attributes
+ * add resource level `headers` option
+ * `host_config` will be deprecated in 0.2.0
+ * add `Served::Attribute::Base` class
+ 
+## 0.1.11
+ * add resource level `reasource_name` option
+ * add resource level `host` option
+
+## 0.1.10
+* make `timeout` configurable per resource
+
 ## 0.1.8
 
 * fix buggy GET request template expansion defaults

data/README.md

@@ -25,12 +25,12 @@ end
 ```
 
 ## Hosts
-Served models derive their hostname by mapping their parent module to the ```Served::hosts``` configuration hash. For
-example, ```SomeService::SomeResource``` would look up its host configuration at 
-```Served.config.hosts['some_service']```.
+Served models derive their hostname by mapping their parent module to the `Served::hosts` configuration hash. For
+example, `SomeService::SomeResource` would look up its host configuration at 
+`Served.config.hosts['some_service']`.
 
 The host configuration accepts an (Addressable)[https://github.com/sporkmonger/addressable] template mapping
-```resource``` as the resource name (derived from the model name) and ```query``` as the params. For example:
+`resource` as the resource name (derived from the model name) and `query` as the params. For example:
 
 ```
 http://localhost:3000/{resource}{?query*}
@@ -44,22 +44,90 @@ maintained for backwards compatibility, however the extension will likely be rem
 Sets the request timeout in milliseconds.
 
 
-# Usage
+# Defining a Resource
 A service model can be created by declaring a class inheriting from ```Service::Resource::Base```.
 
 ```ruby
 class SomeService::SomeResource < Served::Resource::Base
-
    attribute :name
    attribute :date
-   attribute :phone_number, default: '555-555-5555'
+   attribute :phone_number
+
+end
+```
+
+## Resource Configuration
+The default configuration can be changed for individual resources. The currently available resource configuration
+options are:
+
+* **host** - the service host the request is sent to
+* **headers** - the headers that are sent with the request
+* **timeout** - the timeout for the individual resource
+* **resource_name** - the resource_name of the resource, as applicable to the Addressable template
+
+## Serialization
+
+Attributes can be serialized as Ruby objects when the `serialize:` option is passed to `#attribute`. This can be any
+primitive object (`Fixnum`, `String`, `Symbol`, etc.) or any object whose initializer accepts a single `Hash` or `Array`
+as an argument and responds to `to_json`. This also means that Served resources can be used as nested objects as well, 
+which can allow for strict request validation (as explained in the next section).
+
+When `#save` is called on a resource, non primitive objects will be serialized for transport using their `to_json`
+method, this also means that attributes can be valid `ActiveRecord` objects. Served provides a generic validatable
+non-resource class called `Served::Attribute::Base` that can be used to define deep nested object mapping for 
+complex json data strucutres. 
+
+Example:
+
+```ruby
+class SomeService::SomeThing < Served::Attribute::Base
+  attribute :id
+end
+
+class SomeService::SomeResource < Served::Resource::Base
+  attribute :thing, serialize: SomeService::SometThing
+end
+```
 
+## Validations
+`Served::Resource::Base` includes `AciveModel::Validations` and supports all validation methods with the exception of 
+`Uniquness`. As a shotcut validations can be passed to the `#attribute` method much in the same way as it can be passed 
+to the `#validate` method. 
+
+Example:
+
+```ruby
+class SomeService::SomeResource < Served::Resource::Base
+  attribute :name, presence: true, format: {with: /[a-z]+/}, length: { within: (3..10) }
+  attribute :date
+  
+  validates_each :date do |record, attr, value|
+    # ...
+   end
 end
+
 ```
 
+When a serializer is added to an attribute if that serializer responds to `#valid?` it will be validated along with the
+ rest of the request. These nested validations will bubble up to errors added to the top level  attribute.
+
+
+```ruby
+class SomeService::SomeThing < Served::Attribute::Base
+  attribute :id, presence: true
+end
+
+class SomeService::SomeResource < Served::Resource::Base
+  attribute :thing, presence: true, serialize: SomeService::SometThing
+end
+```
+
+This allows scenarios where a data structure needs to be enforced and to f fail fast when the structure is invalid.
+is particularly useful when developing internal API libraries that communicate between internal services using a uniform data model.
+
 ## Saving a resource
+
 Served follows resourceful standards. When a resource is initially saved a **POST** request will be sent
 to the service. When the resource already exists, a **PUT** request will be sent. Served determines if
 a resource is new or not based on the presence of an id.
 
-

data/gemfiles/3.2.gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+gem 'activesupport', '~> 3.2'
+
+gemspec :path => "../"

data/gemfiles/4.2.gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+gem 'activesupport', '~> 4.2'
+
+gemspec :path => "../"

data/gemfiles/5.0.gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+gem 'activesupport', '~> 5.0'
+
+gemspec :path => "../"

data/lib/served/attribute/base.rb

@@ -0,0 +1,9 @@
+module Served
+  module Attribute
+    class Base
+      include Support::Attributable
+      include Support::Serializable
+      include Support::Validatable
+    end
+  end
+end

data/lib/served/attribute.rb

@@ -0,0 +1 @@
+require_relative 'attribute/base'

data/lib/served/http_client.rb

@@ -5,15 +5,16 @@ module Served
     HEADERS = { 'Content-type' => 'application/json', 'Accept' => 'application/json' }
     DEFAULT_TEMPLATE = '{/resource*}{/id}.json{?query*}'
 
-    def initialize(host, timeout)
+    def initialize(host, timeout, headers={})
       host += DEFAULT_TEMPLATE unless host =~ /{.+}/
       @template = Addressable::Template.new(host)
       @timeout  = timeout
+      @headers = HEADERS.merge(headers || {})
     end
 
     def get(endpoint, id, params={})
       HTTParty.get(@template.expand(id: id, query: params, resource: endpoint).to_s,
-                   headers: HEADERS,
+                   headers: @headers,
                    timeout: @timeout
       )
     end
@@ -21,7 +22,7 @@ module Served
     def put(endpoint, id, body, params={})
       HTTParty.put(@template.expand(id: id, query: params, resource: endpoint).to_s,
         body:    body,
-        headers: HEADERS,
+        headers: @headers,
         timeout: @timeout
       )
     end
@@ -29,7 +30,7 @@ module Served
     def post(endpoint, body, params={})
       HTTParty.post(@template.expand(query: params, resource: endpoint).to_s,
         body:    body,
-        headers: HEADERS,
+        headers: @headers,
         timeout: @timeout
       )
     end

data/lib/served/resource/base.rb

@@ -4,9 +4,21 @@ module Served
     # services based on the namespace. Classes should be namespaced under Services::ServiceName where ServiceName is the
     # name of the service the resource lives on. The resource determines the host of the service based on this
     # this namespace and what is in the configuration.
+    #
+    # Service Resources supports some ActiveModel validations so that a developer can include client side validations
+    # if desired. Validation options can be passed to the #attribute class method using the same options as
+    # ActiveModel#validate
+    #
+    # A resource may also serialize values as specific classes, including nested resources. If serialize is set to a
+    # Served Resource, it will validate the nested resource as well as the top level.
     class Base
+      include Support::Attributable
+      include Support::Validatable
+      include Support::Serializable
+
       # raised when an attribute is passed to a resource that is not declared
-      class InvalidAttributeError < StandardError; end
+      class InvalidAttributeError < StandardError;
+      end
 
       # raised when the connection receives a response from a service that does not constitute a 200
       class ServiceError < StandardError
@@ -19,49 +31,60 @@ module Served
       end
 
       class << self
-        # declare an attribute for the resource
-        #
-        # @example
-        #   class SomeResource
-        #     attribute :attr1
-        #   end
-        def attribute(name, options={})
-          return if attributes.include?(name)
-          attributes[name] = options
-          attr_accessor name
-        end
 
-        # @return [Hash] declared attributes for the resources
-        def attributes
-          @attributes ||= {}
+
+        # Defines the default headers that should be used for the request.
+        #
+        # @param headers [Hash] the headers to send with each requesat
+        # @return headers [Hash] the default headers for the class
+        def headers(h={})
+          @headers = h unless h.empty?
+          @headers
         end
 
         # Looks up a resource on the service by id. For example `SomeResource.find(5)` would call `/some_resources/5`
+        #
+        # @param id [Integer] the id of the resource
+        # @return [Resource::Base] the resource object.
         def find(id)
           instance = new(id: id)
           instance.reload
         end
 
+        # Get or set the resource name for the given resource used for endpoint generation
+        #
+        # @param resource [String] the name of the resource
         # @return [String] the name of the resource. `SomeResource.resource_name` will return `some_resources`
-        def resource_name
-          name.split('::').last.tableize
+        def resource_name(resource=nil)
+          @resource_name = resource if resource
+          @resource_name ||name.split('::').last.tableize
         end
 
+        # @deprecated returns host information
+        def host_config
+          host
+        end
+
+        # Get or set the host for the resource
+        #
+        # @param host [String] the resource host
         # @return [String] or [Hash] the configured host.
         # @see Services::Configuration
-        def host_config
-          Served.config[:hosts][parent.name.underscore.split('/')[-1]]
+        def host(h=nil)
+          @host = h if h
+          @host ||= Served.config[:hosts][parent.name.underscore.split('/')[-1]]
         end
 
+        # Get or set the timeout for the current resource
+        #
         # @return [Integer] allowed timeout in seconds
-        def timeout
-          Served.config.timeout
+        def timeout(sec=nil)
+          @timeout = sec if sec
+          @timeout || Served.config.timeout
         end
 
-        # @return [Served::HTTPClient] The connection instance to the service host. Note this is not an active
-        # connection but a passive one.
         def client
-          @connection ||= Served::HTTPClient.new(host_config, timeout)
+          @connection ||= Served::HTTPClient.new(host_config, timeout, headers)
         end
 
         private
@@ -74,13 +97,7 @@ module Served
             attribute :id
           end
         end
-      end
 
-      # Instantiates a resource with the given attributes.
-      #
-      # @raise [InvalidAttributeError] in the case that an attribute is passed that is not declared
-      def initialize(attributes={})
-        reload_with_attributes(attributes)
       end
 
       # @see Services::Resource::Base::resource_name
@@ -111,18 +128,6 @@ module Served
         self
       end
 
-      # renders the model as json
-      def to_json
-        raise InvalidPresenter, 'Presenter must respond to #to_json' unless presenter.respond_to? :to_json
-        presenter.to_json
-      end
-
-      # override this to return a presenter to be used for serialization, otherwise all attributes will be
-      # serialized
-      def presenter
-        { resource_name.singularize => attributes }
-      end
-
       private
 
       def get(params={})
@@ -144,29 +149,10 @@ module Served
         JSON.parse(response.body)
       end
 
-
-      def reload_with_attributes(attributes)
-        attributes.each do |name, value|
-          set_attribute(name.to_sym, value)
-        end
-        set_attribute_defaults
-      end
-
-      def set_attribute_defaults
-        self.class.attributes.each do |attr, options|
-          next if options[:default].nil? || send(attr)
-          set_attribute(attr, options[:default])
-        end
-      end
-
-      def set_attribute(name, value)
-        raise InvalidAttributeError, "`#{name}' is not a valid attribute" unless self.class.attributes.include?(name)
-        instance_variable_set("@#{name}", value)
-      end
-
       def client
         self.class.client
       end
+
     end
   end
 end

data/lib/served/support/attributable.rb

@@ -0,0 +1,67 @@
+module Served
+  module Support
+    module Attributable
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+
+        # declare an attribute for the resource
+        #
+        # @example
+        #   class SomeResource
+        #     attribute :attr1
+        #   end
+        #
+        # @param name [Symbol] the name of the attribute
+        def attribute(name, options={})
+          return if attributes.include?(name)
+          attributes[name] = options
+          attr_accessor name
+        end
+
+        # declare a set of attributes by name
+        #
+        # @example
+        #   class SomeResource
+        #     attributes :attr1, :attr2
+        #   end
+        #
+        # @param *attributes [Array] a list of attributes for the resource
+        # @return [Hash] declared attributes for the resources
+        def attributes(*args)
+          args.each { |a| attribute a } unless args.empty?
+          @attributes ||= {}
+        end
+
+      end
+
+      def initialize(options={})
+        reload_with_attributes(options)
+      end
+
+      private
+
+      def reload_with_attributes(attributes)
+        attributes.each do |name, value|
+          set_attribute(name.to_sym, value)
+        end
+        set_attribute_defaults
+      end
+
+      def set_attribute_defaults
+        self.class.attributes.each do |attr, options|
+          next if options[:default].nil? || send(attr)
+          set_attribute(attr, options[:default])
+        end
+      end
+
+      def set_attribute(name, value)
+        raise InvalidAttributeError, "`#{name}' is not a valid attribute" unless self.class.attributes.include?(name)
+        instance_variable_set("@#{name}", value)
+      end
+
+    end
+
+
+  end
+end

data/lib/served/support/serializable.rb

@@ -0,0 +1,66 @@
+module Served
+  module Support
+    module Serializable
+      extend ActiveSupport::Concern
+
+      # Specialized class serializers
+      SERIALIZERS = {
+          Fixnum => {call: :to_i},
+          String => {call: :to_s},
+          Symbol => {call: :to_sym},
+          Float => {call: :to_f}
+      }
+
+      included do
+        include Attributable
+        prepend Prepend
+      end
+
+      class InvalidPresenter < StandardError
+      end
+
+      module Prepend
+
+        def set_attribute(name, value)
+          return unless self.class.attributes[name]
+          if serializer = self.class.attributes[name][:serialize]
+            if serializer.is_a? Proc
+              value = serializer.call(value)
+            elsif s = SERIALIZERS[serializer]
+              value = value.send(s[:call]) if s[:call] && value.respond_to?(s[:call])
+              value = s[:converter].call(value) if s[:converter]
+            else
+              value = serializer.new(value)
+            end
+          end
+          super
+        end
+
+
+      end
+
+      module ClassMethods
+
+        private
+
+        def serializer_for_attribute(attr, serializer)
+          attributes[attr][:serializer] = serializer
+        end
+
+      end
+
+      # renders the model as json
+      def to_json
+        raise InvalidPresenter, 'Presenter must respond to #to_json' unless presenter.respond_to? :to_json
+        presenter.to_json
+      end
+
+      # override this to return a presenter to be used for serialization, otherwise all attributes will be
+      # serialized
+      def presenter
+        {resource_name.singularize => attributes}
+      end
+
+    end
+  end
+end

data/lib/served/support/validatable.rb

@@ -0,0 +1,66 @@
+module Served
+  module Support
+    # Resource validation functionality
+    module Validatable
+      extend ActiveSupport::Concern
+
+      # Supported Validation Types
+      SUPPORTED_VALIDATIONS = [
+          :presence,
+          :numericality,
+          :format,
+          :inclusion,
+          :confirmation
+      ]
+
+      included do
+        include ActiveModel::Validations
+        singleton_class.prepend ClassMethods::Prepend
+        prepend Prepend
+      end
+
+      module Prepend
+
+        def save
+          return false unless valid?
+          super
+        end
+
+
+        protected
+
+        def run_validations!
+          super
+          self.class.attributes.each_key do |attribute|
+            attr = send(attribute)
+            errors.add(attribute, :invalid) if attr.respond_to?(:valid?) && !attr.valid?
+          end
+          errors.empty?
+        end
+
+      end
+
+      module ClassMethods
+        module Prepend
+
+          def attribute(name, options={})
+            super
+            set_validations_for_attribute(name, options)
+          end
+
+        end
+
+        private
+
+        # Sets up any validations for the attribute
+        def set_validations_for_attribute(name, options)
+          SUPPORTED_VALIDATIONS.each do |validation|
+            validates name, validation => options[validation] if options[validation]
+          end
+        end
+
+      end
+
+    end
+  end
+end

data/lib/served/support.rb

@@ -0,0 +1,3 @@
+require_relative 'support/attributable'
+require_relative 'support/serializable'
+require_relative 'support/validatable'

data/lib/served/version.rb

@@ -1,3 +1,3 @@
 module Served
-  VERSION = '0.1.10'
+  VERSION = '0.1.12'
 end

data/lib/served.rb

@@ -2,11 +2,14 @@ require 'httparty'
 require 'active_support/configurable'
 require 'active_support/core_ext/string'
 require 'active_support/core_ext/module'
+require 'active_model'
 
 require 'served/engine'
 require 'served/version'
 require 'served/http_client'
+require 'served/support'
 require 'served/resource'
+require 'served/attribute'
 
 module Served
   include ActiveSupport::Configurable

data/served.gemspec

@@ -22,6 +22,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'httparty'
   spec.add_dependency 'activesupport', '>= 3.2'
   spec.add_dependency 'addressable',   '>= 2.4.0'
+  spec.add_dependency 'activemodel', '>= 3.2'
 
   spec.add_development_dependency 'bundler', '~> 1.10'
   spec.add_development_dependency 'rake', '~> 10.0'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: served
 version: !ruby/object:Gem::Version
-  version: 0.1.10
+  version: 0.1.12
 platform: ruby
 authors:
 - Jarod Reid
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-04-18 00:00:00.000000000 Z
+date: 2017-02-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -52,6 +52,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 2.4.0
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.2'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -113,11 +127,20 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- gemfiles/3.2.gemfile
+- gemfiles/4.2.gemfile
+- gemfiles/5.0.gemfile
 - lib/served.rb
+- lib/served/attribute.rb
+- lib/served/attribute/base.rb
 - lib/served/engine.rb
 - lib/served/http_client.rb
 - lib/served/resource.rb
 - lib/served/resource/base.rb
+- lib/served/support.rb
+- lib/served/support/attributable.rb
+- lib/served/support/serializable.rb
+- lib/served/support/validatable.rb
 - lib/served/version.rb
 - served.gemspec
 homepage: http://github.com/fugufish/served
@@ -140,10 +163,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.8
+rubygems_version: 2.6.10
 signing_key: 
 specification_version: 4
 summary: Served provides an easy to use model layer for communicating with disributed
   Rails based Services.
 test_files: []
-has_rdoc: