acfs 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7b8b60ec789ab339c208b7b78b4bcdf38fb18467
-  data.tar.gz: cd3c88aec232d7b8e0716b2f10b53eea5741c47d
+  metadata.gz: 36f33bb4ccf82d17ac10c0c1a142476817229231
+  data.tar.gz: a881457d71f8437c9f81466e928eb4e7cb57df90
 SHA512:
-  metadata.gz: ef3105d463581ec7712d3112fcd68fd89f2a82c4389519ba299c4383d2b47454857a5ffc6613bb366367bff8a376bb6b7754b5baaf6ee24cc695ea03166813cd
-  data.tar.gz: 5e6afdf759f89a7f2d69fa8f5950fc6d99ec2b05648f33302306fc67f022154b79f7d3071b2f2d10880dc187c1aa2fba5c28dff61cf77cca3ee8ef18b86667a4
+  metadata.gz: fcb651f2c3c488d05fdebcd2a63ac2c6612a5d19188519456a1d690cccfe6fdc7786aeeddef7ae6dd30170aa9cc11a4b342037d2102ed4eb67d1b983950e8922
+  data.tar.gz: eed4cc6c2c6dd9071c40c22fc5786541e7c5e615e708affe2d772e5d7a6e2c9005cb2d97e664bef9acad7cf222fa16904282797a7da1b27c4255a586c65f1aeb

data/README.md

@@ -10,10 +10,10 @@ TODO: Write a gem description
 
 Add this line to your application's Gemfile:
 
-    gem 'acfs', '0.3.0'
+    gem 'acfs', '0.6.0'
 
-**Note:** Acfs is under development. API may change at any time. No semantic versioning will be applied until version
-`1.0`. Version `1.0` does not mean a complete feature set but a first stable code base.
+**Note:** Acfs is under development. I'll try to avoid changes to the public
+API but internal APIs may change quite often.
 
 And then execute:
 
@@ -25,71 +25,113 @@ Or install it yourself as:
 
 ## Usage
 
-### Attributes
+First you need to define your service(s):
 
 ```ruby
-class MyModel
-  include Acfs::Model
-
-  attribute :name, :string
-  attribute :age, :integer, default: 15
+class UserService < Acfs::Service
+  self.base_url = 'http://users.myapp.org'
 end
-
-MyModel.attributes # => { "name" => "", "age" => 15 }
-
-mo = MyModel.new name: 'Johnny', age: 12
-mo.name # => "Johnny"
-mo.age = '13'
-mo.age # => 13
-mo.attributes # => { "name" => "Johnny", "age" => 13 }
 ```
 
-### Service, Model & Collection
+This specifies where the `UserService` can be reached. You can now create some
+models representing resources serviced by the `UserService`.
 
 ```ruby
-class MyService < Acfs::Service
-  self.base_url = 'http://acc.srv'
-end
-
 class User
   include Acfs::Model
-  service MyService
+  service UserService # Associate `User` model with `UserService`.
+
+  # Define model attributes and types
+  # Types are needed to parse and generate request and response payload.
+
+  attribute :id, :uuid # Types can be classes or symbols.
+                       # Symbols will be used to load a class from `Acfs::Model::Attributes` namespace.
+                       # Eg. `:uuid` will load class `Acfs::Model::Attributes::Uuid`.
+
+  attribute :name, :string, default: 'Anonymous'
+  attribute :age, ::Acfs::Model::Attributes::Integer # Or use :integer
 
-  attribute :id, :integer
 end
+```
 
+The service and model classes can be shipped as a gem or git submodule to be
+included by the frontend application(s).
+
+You can use the model there:
+
+```ruby
 @user = User.find 14
 
 @user.loaded? #=> false
 
 Acfs.run # This will run all queued request as parallel as possible.
          # For @user the following URL will be requested:
-         # `http://acc.srv/users/14`
+         # `http://users.myapp.org/users/14`
 
 @model.name # => "..."
 
 @users = User.all
 @users.loaded? #=> false
 
-Acfs.run # Will request `http://acc.srv/users`
+Acfs.run # Will request `http://users.myapp.org/users`
 
 @users #=> [<User>, ...]
 ```
 
+If you need multiple resources or dependent resources first define a "plan"
+how they can be loaded:
+
+```ruby
+@user = User.find(5) do |user|
+  # Block will be executed right after user with id 5 is loaded
+
+  # You can load additional resources also from other services
+  # Eg. fetch comments from `CommentSerivce`. The line below will
+  # load comments from `http://comments.myapp.org/comments?user=5`
+  @comments = Comment.where user: user.id
+
+  # You can load multiple resources in parallel if you have multiple
+  # ids.
+  @friends  = User.find 1, 4, 10 do |friends|
+    # This block will be executed when all friends are loaded.
+    # [ ... ]
+  end
+end
+
+Acfs.run # This call will fire all request as parallel as possible.
+         # The sequence above would look similar to:
+         #
+         # Start                Fin
+         #   |===================|       `Acfs.run`
+         #   |====|                      /users/5
+         #   |    |==============|       /comments?user=5
+         #   |    |======|               /users/1
+         #   |    |=======|              /users/4
+         #   |    |======|               /users/10
+
+# Now we can access all resources:
+
+@user.name       # => "John
+@comments.size   # => 25
+@friends[0].name # => "Miraculix"
+
 ## TODO
 
-* Develop Library
+* Create/Update operations
+* High level features
+** Pagination? Filtering? (If service API provides such features.)
+** Messaging Queue support for services and models
 * Documentation
 
 ## Contributing
 
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Add specs for your feature
-4. Implement your feature
-5. Commit your changes (`git commit -am 'Add some feature'`)
-6. Push to the branch (`git push origin my-new-feature`)
-7. Create new Pull Request
+3a. Add specs for your feature
+3b. Implement your feature
+3c. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
 
 ## License
 

data/acfs.gemspec

@@ -30,4 +30,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rspec'
   spec.add_development_dependency 'guard-rspec'
   spec.add_development_dependency 'coveralls'
+  spec.add_development_dependency 'msgpack'
 end

data/lib/acfs.rb

@@ -17,6 +17,7 @@ module Acfs
     autoload :Base
     autoload :Print
     autoload :JsonDecoder
+    autoload :MessagePackDecoder, 'acfs/middleware/msgpack_decoder'
   end
 
   module Adapter
@@ -33,9 +34,9 @@ module Acfs
     end
 
     def queue(req, &block)
-      request = middleware.call Request.new(req)
+      request = Request.new req
       request.on_complete &block if block_given?
-      adapter.queue request
+      middleware.call request
     end
 
     def adapter
@@ -43,7 +44,9 @@ module Acfs
     end
 
     def middleware
-      @middleware ||= lambda { |request| request }
+      @middleware ||= proc do |request|
+        adapter.queue request
+      end
     end
 
     def use(klass, options = {})
@@ -54,5 +57,11 @@ module Acfs
       @middlewares << klass
       @middleware = klass.new(middleware, options)
     end
+
+    def clear
+      @middleware  = nil
+      @middlewares = nil
+    end
   end
 end
+

data/lib/acfs/middleware/base.rb

@@ -13,7 +13,7 @@ module Acfs
       end
 
       def call(request)
-        request.on_complete { |res| response(res) } if respond_to? :response
+        request.on_complete { |res, nxt| response(res, nxt) } if respond_to? :response
         app.call(request)
       end
     end

data/lib/acfs/middleware/json_decoder.rb

@@ -7,8 +7,9 @@ module Acfs
     #
     class JsonDecoder < Base
 
-      def response(response)
+      def response(response, nxt)
         response.data = ::MultiJson.load(response.body) if response.json?
+        nxt.call response
       end
     end
   end

data/lib/acfs/middleware/msgpack_decoder.rb

@@ -0,0 +1,26 @@
+require 'msgpack'
+require 'action_dispatch'
+
+module Acfs
+  module Middleware
+
+    # Register msgpack mime type
+    ::Mime::Type.register 'application/x-msgpack', :msgpack
+
+    # A middleware to decode Message Pack responses.
+    #
+    class MessagePackDecoder < Base
+
+      CONTENT_TYPES = %w(application/x-msgpack)
+
+      def response(response, nxt)
+        response.data = ::MessagePack.load(response.body) if message_pack?(response)
+        nxt.call response
+      end
+
+      def message_pack?(response)
+        CONTENT_TYPES.include? response.content_type
+      end
+    end
+  end
+end

data/lib/acfs/model/query_methods.rb

@@ -21,25 +21,15 @@ module Acfs::Model
       # Try to load a resource by given id.
       #
       # Example
-      #   User.find(5) # Will query `http://base.url/users/5`
+      #   User.find(5)       # Will query `http://base.url/users/5`
+      #   User.find(1, 2, 5) # Will return collection and will query
+      #                      # `http://base.url/users/1`, `http://base.url/users/2`
+      #                      # and `http://base.url/users/5` parallel
       #
-      def find(id, options = {}, &block)
-        model = self.new
-
-        request = case id
-                    when Hash
-                      Acfs::Request.new url, params: id
-                    else
-                      Acfs::Request.new url(id.to_s)
-                  end
+      def find(*attrs, &block)
+        opts  = attrs.extract_options!
 
-        service.queue(request) do |response|
-          model.attributes = response.data
-          model.loaded!
-          block.call model unless block.nil?
-        end
-
-        model
+        attrs.size > 1 ? find_multiple(attrs, opts, &block) : find_single(attrs[0], opts, &block)
       end
 
       # Try to load all resources.
@@ -61,6 +51,35 @@ module Acfs::Model
         collection
       end
       alias :where :all
+
+      private
+      def find_single(id, opts, &block)
+        model = self.new
+
+        request = Acfs::Request.new url(id.to_s)
+        service.queue(request) do |response|
+          model.attributes = response.data
+          model.loaded!
+          block.call model unless block.nil?
+        end
+
+        model
+      end
+
+      def find_multiple(ids, opts, &block)
+        ::Acfs::Collection.new.tap do |collection|
+          counter = 0
+          ids.each do |id|
+            find_single id, opts do |resource|
+              collection << resource
+              if (counter += 1) == ids.size
+                collection.loaded!
+                block.call collection unless block.nil?
+              end
+            end
+          end
+        end
+      end
     end
   end
 end

data/lib/acfs/request.rb

@@ -2,6 +2,9 @@ require 'acfs/request/callbacks'
 
 module Acfs
 
+  # Encapsulate all data required to make up a request to the
+  # underlaying http library.
+  #
   class Request
     attr_accessor :body, :format
     attr_reader :url, :headers, :params, :data

data/lib/acfs/request/callbacks.rb

@@ -21,7 +21,7 @@ module Acfs
       # @return [ Acfs::Request ] The request itself.
       #
       def on_complete(&block)
-        callbacks << block if block_given?
+        callbacks.insert 0, block if block_given?
         self
       end
 
@@ -38,9 +38,14 @@ module Acfs
       # @return [ Acfs::Request ] The request itself.
       #
       def complete!(response)
-        callbacks.each { |cb| cb.call response }
+        call_callback response, 0
         self
       end
+
+      private
+      def call_callback(res, index)
+        callbacks[index].call res, proc { |res| call_callback res, index + 1 } if index < callbacks.size
+      end
     end
   end
 end

data/lib/acfs/response/formats.rb

@@ -6,15 +6,15 @@ module Acfs
     # Quick accessors for format handling.
     module Formats
 
-      def mime_type
-        @mime_type ||= begin
+      def content_type
+        @content_type ||= begin
           content_type = headers['Content-Type'].split(/;\s*\w+="?\w+"?/).first
           Mime::Type.parse(content_type).first
         end
       end
 
       def json?
-        mime_type == Mime::JSON
+        content_type == Mime::JSON
       end
     end
   end

data/lib/acfs/version.rb

@@ -1,8 +1,8 @@
 module Acfs
   module VERSION
     MAJOR = 0
-    MINOR = 5
-    PATCH = 1
+    MINOR = 6
+    PATCH = 0
     STAGE = nil
 
     STRING = [MAJOR, MINOR, PATCH, STAGE].reject(&:nil?).join('.')

data/spec/acfs/middleware/msgpack_decoder_spec.rb

@@ -0,0 +1,45 @@
+require 'spec_helper'
+
+describe Acfs::Middleware::MessagePackDecoder do
+  let(:data)     { [{id: 1, name: "Anon"},{id: 2, name:"John", friends: [ 1 ]}] }
+  let(:body)     { data.to_param }
+  let(:headers)  { {} }
+  let(:request)  { Acfs::Request.new "fubar" }
+  let(:response) { Acfs::Response.new request, 200, headers, body }
+  let(:decoder)  { Acfs::Middleware::MessagePackDecoder.new lambda { |req| req } }
+
+  before do
+    decoder.call request
+  end
+
+  context 'with Message Pack response' do
+    let(:headers) { { 'Content-Type' => 'application/x-msgpack' } }
+    let(:body)    { MessagePack.dump data }
+
+    it 'should decode body data' do
+      request.complete! response
+
+      expect(response.data).to be == data.map(&:stringify_keys)
+    end
+  end
+
+  context 'with invalid response' do
+    let(:headers) { { 'Content-Type' => 'application/x-msgpack' } }
+    let(:body)    { MessagePack.dump(data)[4..-4] }
+
+    it 'should raise an error' do
+      expect { request.complete! response }.to raise_error(MessagePack::MalformedFormatError)
+    end
+  end
+
+  context 'without Message Pack response' do
+    let(:headers) { { 'Content-Type' => 'application/text' } }
+    let(:body)    { data.to_json }
+
+    it 'should not decode non-MessagePack encoded responses' do
+      request.complete! response
+
+      expect(response.data).to be_nil
+    end
+  end
+end

data/spec/acfs/request/callbacks_spec.rb

@@ -17,7 +17,7 @@ describe Acfs::Request::Callbacks do
       request.on_complete &callback
 
       expect(request.callbacks).to have(2).item
-      expect(request.callbacks[1]).to be == callback
+      expect(request.callbacks[0]).to be == callback
     end
   end
 
@@ -25,10 +25,22 @@ describe Acfs::Request::Callbacks do
     let(:response) { Acfs::Response.new(request) }
 
     it 'should trigger registered callbacks with given response' do
-      callback.should_receive(:call).with(response)
+      callback.should_receive(:call).with(response, kind_of(Proc))
 
       request.on_complete &callback
       request.complete! response
     end
+
+    it 'should trigger multiple callback in reverted insertion order' do
+      check = []
+
+      request.on_complete { |res, nxt| check << 1; nxt.call res }
+      request.on_complete { |res, nxt| check << 2; nxt.call res }
+      request.on_complete { |res, nxt| check << 3; nxt.call res }
+
+      request.complete! response
+
+      expect(check).to be == [3, 2, 1]
+    end
   end
 end

data/spec/acfs/response/formats_spec.rb

@@ -11,9 +11,9 @@ describe Acfs::Response::Formats do
   context 'with JSON mimetype' do
     let(:mime_type) { 'application/json' }
 
-    describe '#mime_type' do
+    describe '#content_type' do
       it 'should return Mime::JSON' do
-        expect(response.mime_type).to be == Mime::JSON
+        expect(response.content_type).to be == Mime::JSON
       end
     end
 
@@ -26,9 +26,9 @@ describe Acfs::Response::Formats do
     context 'with charset option' do
       let(:mime_type) { 'application/json; charset=utf8' }
 
-      describe '#mime_type' do
+      describe '#content_type' do
         it 'should return Mime::JSON' do
-          expect(response.mime_type).to be == Mime::JSON
+          expect(response.content_type).to be == Mime::JSON
         end
       end
 

data/spec/acfs_spec.rb

@@ -3,11 +3,15 @@ require 'spec_helper'
 describe "Acfs" do
 
   before do
+    Acfs.clear
     Acfs.use Acfs::Middleware::JsonDecoder
+    Acfs.use Acfs::Middleware::MessagePackDecoder
 
     headers = { 'Content-Type' => 'application/json' }
     stub_request(:get, "http://users.example.org/users").to_return(:body => '[{"id":1,"name":"Anon","age":12},{"id":2,"name":"John","age":26}]', headers: headers)
     stub_request(:get, "http://users.example.org/users/2").to_return(:body => '{"id":2,"name":"John","age":26}', headers: headers)
+    stub_request(:get, "http://users.example.org/users/3").to_return(:body => '{"id":2,"name":"Miraculix","age":122}', headers: headers)
+    stub_request(:get, "http://users.example.org/users/100").to_return(:body => '{"id":2,"name":"Jimmy","age":45}', headers: headers)
     stub_request(:get, "http://users.example.org/users/2/friends").to_return(:body => '[{"id":1,"name":"Anon","age":12}]', headers: headers)
     stub_request(:get, "http://comments.example.org/comments?user=2").to_return(:body => '[{"id":1,"text":"Comment #1"},{"id":2,"text":"Comment #2"}]', headers: headers)
   end
@@ -24,6 +28,34 @@ describe "Acfs" do
     expect(@user.age).to be == 26
   end
 
+  it 'should load multiple single resources' do
+    @users = MyUser.find(2, 3, 100) do |users|
+      # This block should be called only after *all* resources are loaded.
+      @john = users[0]
+      @mirx = users[1]
+      @jimy = users[2]
+    end
+
+    expect(@users).to_not be_loaded
+
+    Acfs.run
+
+    expect(@users).to be_loaded
+    expect(@users).to have(3).items
+
+    expect(@users[0].name).to be == 'John'
+    expect(@users[0].age).to be == 26
+    expect(@users[0]).to be == @john
+
+    expect(@users[1].name).to be == 'Miraculix'
+    expect(@users[1].age).to be == 122
+    expect(@users[1]).to be == @mirx
+
+    expect(@users[2].name).to be == 'Jimmy'
+    expect(@users[2].age).to be == 45
+    expect(@users[2]).to be == @jimy
+  end
+
   it 'should load multiple resources' do
     @users = MyUser.all
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: acfs
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Jan Graichen
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-10 00:00:00.000000000 Z
+date: 2013-04-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -164,6 +164,20 @@ dependencies:
     - - '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: msgpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: API Client For Services
 email:
 - jg@altimos.de
@@ -188,6 +202,7 @@ files:
 - lib/acfs/collection.rb
 - lib/acfs/middleware/base.rb
 - lib/acfs/middleware/json_decoder.rb
+- lib/acfs/middleware/msgpack_decoder.rb
 - lib/acfs/middleware/print.rb
 - lib/acfs/model.rb
 - lib/acfs/model/attributes.rb
@@ -207,6 +222,7 @@ files:
 - lib/acfs/service.rb
 - lib/acfs/version.rb
 - spec/acfs/middleware/json_decoder_spec.rb
+- spec/acfs/middleware/msgpack_decoder_spec.rb
 - spec/acfs/request/callbacks_spec.rb
 - spec/acfs/request_spec.rb
 - spec/acfs/response/formats_spec.rb
@@ -243,6 +259,7 @@ specification_version: 4
 summary: An abstract API base client for service oriented application.
 test_files:
 - spec/acfs/middleware/json_decoder_spec.rb
+- spec/acfs/middleware/msgpack_decoder_spec.rb
 - spec/acfs/request/callbacks_spec.rb
 - spec/acfs/request_spec.rb
 - spec/acfs/response/formats_spec.rb