acfs 0.16.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0f5f03951ec6374b76946211e390bfc2c0ff6f1f
-  data.tar.gz: af8cf339ce2bc9e4a5542a55bb1b8d1e8b63793b
+  metadata.gz: 879fbc544d14669fd0db86a7705c1ff10e997a56
+  data.tar.gz: 6424e9a7fcc978e739e80a0ee009fa141ce2ad25
 SHA512:
-  metadata.gz: 66728dbe0550a7d8585d1d47b615c60534417d176125ddca78b572e11e13f6611b4ec16877db10096c4752f9d24f1323ea01da8bfc5f0b97fd9bcd83e530a85f
-  data.tar.gz: 55f211e28b344c2c5245161d76c12826cd6c89d36132a7838fdfa1402ac5e1dde1618851e3a1e9d6c1c40b5b17ff6bbdef5c6101b464d1cd7196a46d66418a3c
+  metadata.gz: 697f3c7d31e1aa7081eb0e471e1065dcb2a9ec0be7e57b0f9f130cea0c40bb96dba91bbbb9faaf30eaec0aac29de99ee5b27df8b278696d7d43a9c8d1d4e2826
+  data.tar.gz: da505f1e0fcf03d21f594d81f32527dbe0b991dea6b310a400c0d5182cd573a9f3bfabeb3fddd5438a69dee344ef0dcbd540bc8994ee61cadf92e04a3238f436

data/.gitignore

@@ -4,7 +4,8 @@
 .bundle
 .config
 .yardoc
-Gemfile.lock
+doc
+Gemfile*.lock
 InstalledFiles
 _yardoc
 coverage

data/.travis.yml

@@ -1,4 +1,5 @@
 language: ruby
+bundler_args: --without development
 rvm:
   - 2.0.0
   - 1.9.3
@@ -6,5 +7,9 @@ rvm:
   - rbx-19mode
 
 gemfile:
+  - gemfiles/Gemfile.rails-3-1
   - gemfiles/Gemfile.rails-3-2
   - gemfiles/Gemfile.rails-4-0
+
+services:
+  - rabbitmq

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.17.0
+
+* Basic messaging
+* Extensible YARD documentation
+
 ## 0.16.0
 
 * Add YAML configuration

data/Gemfile

@@ -1,19 +1,27 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in acfs.gemspec
-gemroot = File.dirname File.absolute_path __FILE__
-gemspec path: gemroot
-
 # Development gems
 #
 gem 'webmock', '~> 1.7'
 gem 'rake'
 gem 'rspec'
-gem 'guard-rspec'
 gem 'coveralls'
+gem 'json', '~> 1.7.7'
 
+# Doc
+group :development do
+  gem 'yard', '~> 0.8.6'
+  gem 'listen'
+  gem 'guard-yard'
+  gem 'guard-rspec'
+  gem 'redcarpet', platform: :ruby
+end
 
 # Platform specific development dependencies
 #
 gem 'msgpack', platform: :ruby
 gem 'msgpack-jruby', require: 'msgpack', platform: :jruby
+
+# Specify your gem's dependencies in acfs.gemspec
+gemroot = File.dirname File.absolute_path __FILE__
+gemspec path: gemroot

data/Guardfile

@@ -3,22 +3,12 @@
 
 guard 'rspec' do
   watch(%r{^spec/.+_spec\.rb$})
-  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
-  watch('spec/spec_helper.rb')  { "spec" }
+  watch(%r{^lib/(.+)\.rb$})          { |m| "spec/#{m[1]}_spec.rb" }
 
-  # Rails example
-  watch(%r{^app/(.+)\.rb$})                           { |m| "spec/#{m[1]}_spec.rb" }
-  watch(%r{^app/(.*)(\.erb|\.haml)$})                 { |m| "spec/#{m[1]}#{m[2]}_spec.rb" }
-  watch(%r{^app/controllers/(.+)_(controller)\.rb$})  { |m| ["spec/routing/#{m[1]}_routing_spec.rb", "spec/#{m[2]}s/#{m[1]}_#{m[2]}_spec.rb", "spec/acceptance/#{m[1]}_spec.rb"] }
-  watch(%r{^spec/support/(.+)\.rb$})                  { "spec" }
-  watch('config/routes.rb')                           { "spec/routing" }
-  watch('app/controllers/application_controller.rb')  { "spec/controllers" }
-
-  # Capybara features specs
-  watch(%r{^app/views/(.+)/.*\.(erb|haml)$})          { |m| "spec/features/#{m[1]}_spec.rb" }
-
-  # Turnip features and steps
-  watch(%r{^spec/acceptance/(.+)\.feature$})
-  watch(%r{^spec/acceptance/steps/(.+)_steps\.rb$})   { |m| Dir[File.join("**/#{m[1]}.feature")][0] || 'spec/acceptance' }
+  watch('spec/spec_helper.rb')       { 'spec' }
+  watch(%r{^spec/support/(.+)\.rb$}) { 'spec' }
 end
 
+guard 'yard' do
+  watch(%r{lib/.+\.rb})
+end

data/README.md

@@ -1,6 +1,11 @@
 # Acfs - *API client for services*
 
-[![Gem Version](https://badge.fury.io/rb/acfs.png)](http://badge.fury.io/rb/acfs) [![Build Status](https://travis-ci.org/jgraichen/acfs.png?branch=master)](https://travis-ci.org/jgraichen/acfs) [![Coverage Status](https://coveralls.io/repos/jgraichen/acfs/badge.png?branch=master)](https://coveralls.io/r/jgraichen/acfs) [![Code Climate](https://codeclimate.com/github/jgraichen/acfs.png)](https://codeclimate.com/github/jgraichen/acfs) [![Dependency Status](https://gemnasium.com/jgraichen/acfs.png)](https://gemnasium.com/jgraichen/acfs)
+[![Gem Version](https://badge.fury.io/rb/acfs.png)](http://badge.fury.io/rb/acfs)
+[![Build Status](https://travis-ci.org/jgraichen/acfs.png?branch=master)](https://travis-ci.org/jgraichen/acfs)
+[![Coverage Status](https://coveralls.io/repos/jgraichen/acfs/badge.png?branch=master)](https://coveralls.io/r/jgraichen/acfs)
+[![Code Climate](https://codeclimate.com/github/jgraichen/acfs.png)](https://codeclimate.com/github/jgraichen/acfs)
+[![Dependency Status](https://gemnasium.com/jgraichen/acfs.png)](https://gemnasium.com/jgraichen/acfs)
+[![RubyDoc Documentation](https://raw.github.com/jgraichen/acfs/master/rubydoc.png)](http://rubydoc.info/github/jgraichen/acfs/master/frames)
 
 Acfs is a library to develop API client libraries for single services within a larger service oriented application.
 
@@ -16,11 +21,11 @@ Add this line to your application's Gemfile:
 
 And then execute:
 
-    $ bundle
+    > bundle
 
 Or install it yourself as:
 
-    $ gem install acfs
+    > gem install acfs
 
 ## Usage
 
@@ -185,6 +190,38 @@ it 'should find user number one' do
 end
 ```
 
+## Messaging (Experimental)
+
+Acfs 0.17.0 includes experimental messaging support using RabbitMQ. You can create receivers for messages as well as send custom messages. Messages can be high level structures (like hashes) and will be packed into MessagePack.
+
+Create your custom receivers e.g. in `app/receivers`:
+
+```ruby
+# app/receivers/my_receiver.rb
+
+class MyReceiver
+  include Acfs::Messaging::Receiver
+  route "my.#"       # Specify routing key for receiving messages
+
+  def receive(delivery_info, metadata, payload)
+    puts payload.inspect
+    # more foo...
+  end
+end
+```
+
+Make sure the receivers get loaded by placing an initializer in you app that require all receivers. You need to do this manually but it will be automated in some future release.
+
+You can now send messages by calling the `publish` method directly:
+
+```ruby
+Acfs::Messaging::Client.instance.publish "my.message", { message: "Hi!" }
+```
+
+This will invoke `#receive` on an instance of your receiver class.
+
+Be aware that messaging is still experimental and *will* change in future releases.
+
 ## Roadmap
 
 * Update
@@ -201,6 +238,9 @@ end
           Modified Headers, conflict detection, ...
     * Pagination? Filtering? (If service API provides such features.)
     * Messaging Queue support for services and models
+        * Allow triggering messages on resource events (CRUD)
+        * Abstract messages into objects
+        * Middleware stack for messages?
 * Documentation
 
 ## Contributing

data/Rakefile

@@ -2,5 +2,15 @@ require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
-
 task :default => :spec
+
+begin
+  require 'yard'
+  require 'yard/rake/yardoc_task'
+
+  YARD::Rake::YardocTask.new do |t|
+    t.files = %w(lib/**/*.rb)
+    t.options = %w(--output-dir doc/)
+  end
+rescue LoadError
+end

data/acfs.gemspec

@@ -4,25 +4,26 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'acfs/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "acfs"
+  spec.name          = 'acfs'
   spec.version       = Acfs::VERSION
   spec.authors       = ['Jan Graichen']
   spec.email         = %w(jg@altimos.de)
   spec.description   = %q{API Client For Services}
   spec.summary       = %q{An abstract API base client for service oriented application.}
-  spec.homepage      = ""
-  spec.license       = "MIT"
+  spec.homepage      = 'https://github.com/jgraichen/acfs'
+  spec.license       = 'MIT'
 
   spec.files         = `git ls-files`.split($/)
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = %w(lib)
 
-  spec.add_runtime_dependency 'activesupport'
-  spec.add_runtime_dependency 'activemodel'
-  spec.add_runtime_dependency 'actionpack'
+  spec.add_runtime_dependency 'activesupport', '>= 3.1'
+  spec.add_runtime_dependency 'activemodel', '>= 3.1'
+  spec.add_runtime_dependency 'actionpack', '>= 3.1'
   spec.add_runtime_dependency 'multi_json'
   spec.add_runtime_dependency 'typhoeus'
+  spec.add_runtime_dependency 'bunny', '~> 0.9.0.pre12'
   spec.add_runtime_dependency 'rack'
 
   spec.add_development_dependency 'bundler', '~> 1.3'

data/gemfiles/Gemfile.rails-3-0

@@ -0,0 +1,8 @@
+source 'https://rubygems.org'
+
+# Load root Gemfile
+self.instance_eval Bundler.read_file 'Gemfile'
+
+gem 'activesupport', '~> 3.0.0'
+gem 'activemodel', '~> 3.0.0'
+gem 'actionpack', '~> 3.0.0'

data/gemfiles/Gemfile.rails-3-1

@@ -0,0 +1,8 @@
+source 'https://rubygems.org'
+
+# Load root Gemfile
+self.instance_eval Bundler.read_file 'Gemfile'
+
+gem 'activesupport', '~> 3.1.0'
+gem 'activemodel', '~> 3.1.0'
+gem 'actionpack', '~> 3.1.0'

data/lib/acfs.rb

@@ -22,6 +22,13 @@ module Acfs
   autoload :Runner
   autoload :Configuration
 
+  module Messaging
+    extend ActiveSupport::Autoload
+
+    autoload :Client
+    autoload :Receiver
+  end
+
   module Middleware
     extend ActiveSupport::Autoload
 

data/lib/acfs/configuration.rb

@@ -3,15 +3,27 @@ require 'yaml'
 
 module Acfs
 
-  #
+  # Acfs configuration is used to locate services and get their base URLs.
   #
   class Configuration
     attr_reader :locations
 
+    # @api private
     def initialize
       @locations = {}
     end
 
+    # @api public
+    #
+    # Configure using given block. If block accepts zero arguments
+    # bock will be evaluated in context of the configuration instance
+    # otherwise the configuration instance will be given as first arguments.
+    #
+    # @yield [configuration] Give configuration as arguments or evaluate block
+    #   in context of configuration object.
+    # @yieldparam configuration [Configuration] Configuration object.
+    # @return [undefined]
+    #
     def configure(&block)
       if block.arity > 0
         block.call self
@@ -20,6 +32,21 @@ module Acfs
       end
     end
 
+    # @api public
+    #
+    # @overload locate(service, uri)
+    #   Configures URL where a service can be reached.
+    #
+    #   @param [Symbol] service Service identity key for service that is reachable under given URL.
+    #   @param [String] uri URL where service is reachable. Will be passed to {URI.parse}.
+    #   @return [undefined]
+    #
+    # @overload locate(service)
+    #   Return configured base URL for given service identity key.
+    #
+    #   @param [Symbol] service Service identity key to lookup.
+    #   @return [URI, NilClass] Configured base URL or nil.
+    #
     def locate(service, uri = nil)
       service = service.to_s.underscore.to_sym
       if uri.nil?
@@ -29,6 +56,13 @@ module Acfs
       end
     end
 
+    # @api public
+    #
+    # Load configuration from given YAML file.
+    #
+    # @param [String] filename Path to YAML configuration file.
+    # @return [undefined]
+    #
     def load(filename)
       config = YAML::load File.read filename
       env    = ENV['RACK_ENV'] || ENV['RAILS_ENV'] || 'development'
@@ -41,6 +75,10 @@ module Acfs
       end
     end
 
+    # @api private
+    #
+    # Load services from configuration YAML.
+    #
     def load_services(services)
       services.each do |service, data|
         if (val = data).is_a?(String) || (val = data['locate'])
@@ -51,10 +89,23 @@ module Acfs
 
     class << self
 
+      # @api private
+      #
+      # Return current configuration object.
+      #
+      # @return [Configuration]
+      #
       def current
         @configuration ||= new
       end
 
+      # @api private
+      #
+      # Swap configuration object with given new one. Must be a {Configuration} object.
+      #
+      # @param [Configuration] configuration
+      # @return [undefined]
+      #
       def set(configuration)
         @configuration = configuration if configuration.is_a? Configuration
       end

data/lib/acfs/global.rb

@@ -4,16 +4,30 @@ module Acfs
   #
   module Global
 
+    # @api private
+    # @return [Runner]
+    #
     def runner
       @runner ||= Runner.new Adapter::Typhoeus.new
     end
 
+    # @api public
+    #
     # Run all queued operations.
     #
+    # @return [undefined]
+    #
     def run
       runner.start
     end
 
+    # @api public
+    #
+    # Configure acfs using given block.
+    #
+    # @return [undefined]
+    # @see Configuration#configure
+    #
     def configure(&block)
       Configuration.current.configure &block
     end

data/lib/acfs/messaging/client.rb

@@ -0,0 +1,39 @@
+require 'bunny'
+
+module Acfs::Messaging
+
+  # @macro experimental
+  #
+  class Client
+
+    def initialize
+      @bunny ||= Bunny.new.tap do |bunny|
+        bunny.start
+      end
+    end
+
+    def channel
+      @channel ||= @bunny.create_channel
+    end
+
+    def exchange
+      @exchange ||= @channel.topic 'acfs-0.17.0-2', auto_delete: true
+    end
+
+    def publish(routing_key, message)
+      exchange.publish MessagePack.pack(message), routing_key: routing_key
+    end
+
+    class << self
+
+      def instance
+        @instance ||= new
+      end
+
+      def register(receiver)
+        @receivers ||= []
+        @receivers << receiver.instance.tap { |r| r.init instance }
+      end
+    end
+  end
+end

data/lib/acfs/messaging/message.rb

@@ -0,0 +1,7 @@
+module Acfs::Messaging
+
+  #
+  class Message
+
+  end
+end