services 4.1.0 → 4.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8f7714cb0e9390aa539649cc30b178705ef47aa6
-  data.tar.gz: 8821244fee82df7be557f4bbc4591e7d084c2c56
+  metadata.gz: cd7dc93d539be1dfb493ae76fa3517df9f91c50e
+  data.tar.gz: 6c5c5c79fb229e7c1ab98d68ede41939b800e8d2
 SHA512:
-  metadata.gz: ecbfa1b8fe169b98f68fcab6ea905b75a70e51c54872a39bbcc3a6e0b6c838caf18f093df743c0a1a84d61b9de209516205ab0a61114674ccc707ffafe5edd43
-  data.tar.gz: 6b81875b67297940f7fbae262b9a6532dca7aa2497e346940f3e8033bf67d325f9952725e273521fae06ce613a5768d40dca1b1194b0290177315b9f42118cb3
+  metadata.gz: 470ab654cddf1cc75439e0301090865ec6269f31acd76e42d0e614ecbf003373330954d3f1b03376eb3eda59815bf6513cfab1cc7dc79deab9f002e4b4c32ea9
+  data.tar.gz: 4ff35e833918ff1c6269388242bcbdaa4d57f9eaa38f25a1c34450766ceaaf82f12180e964fd39636bd490d917d5461d5ed07eb694a7ceaff76f3ca432ffc31f

data/.travis.yml

@@ -3,5 +3,9 @@ rvm:
   - 2.0
   - 2.1
   - 2.2
+  - 2.3.0
 services:
   - redis-server
+before_install:
+  - gem update --system
+  - gem update bundler

data/Guardfile

@@ -15,7 +15,7 @@ module ::Guard
     REDIS_CLI        = SPEC_SUPPORT_DIR.join('redis-cli')
     REDIS_PIDFILE    = SPEC_SUPPORT_DIR.join('redis.pid')
     REDIS_LOGFILE    = SPEC_SUPPORT_DIR.join('log', 'redis.log')
-    REDIS_PORT       = 6479
+    REDIS_PORT       = 6379
 
     def self.options_to_string(options)
       options.map { |k, v| "-#{'-' if k.length > 1}#{k} #{v}" }.join(' ')

data/README.md

@@ -5,17 +5,17 @@
 [![Dependency Status](https://gemnasium.com/krautcomputing/services.png)](https://gemnasium.com/krautcomputing/services)
 [![Code Climate](https://codeclimate.com/github/krautcomputing/services.png)](https://codeclimate.com/github/krautcomputing/services)
 
-Services is a small collection of modules and base classes that let you implement a nifty service layer in your Rails app.
+Services is a collection of modules and base classes that let you simply add a service layer to your Rails app.
 
 ## Motivation
 
-A lot has been written about service layers in Rails apps. There are of course advantages and disadvantages, but after using Services since 2013 in several Rails apps, I must say that in my opinion the advantages far outweigh the disadvantages.
+A lot has been written about service layers (service objects, SOA, etc.) for Rails. There are of course advantages and disadvantages, but after using Services since 2013 in several Rails apps, I must say that in my opinion the advantages far outweigh the disadvantages.
 
-**The biggest benefit you get when using a service layer is that it gets much easier to reason about your application, find a bug, or implement new features, when all your business logic is in services, not scattered in models, controllers, helpers etc.**
+**The biggest benefit you get when using a service layer, in my opinion, is that it gets so much easier to reason about your application, find a bug, or implement new features, when all your business logic is in services, not scattered in models, controllers, helpers etc.**
 
 ## Usage
 
-For disambiguation: when I write "Services" with a uppercase "S", I mean this gem, whereas with "services" I mean, well, the plural of service.
+For disambiguation: in this README, when you read "Services" with a uppercase "S", this gem is meant, whereas with "services", well, the plural of service is meant.
 
 ### Requirements
 
@@ -23,17 +23,17 @@ For disambiguation: when I write "Services" with a uppercase "S", I mean this ge
 
 #### Rails >= 3.2
 
-#### Redis
+#### Redis >= 2.8
 
-Redis is used at several points, e.g. to store information about the currently running services, so you can make sure a certain service is not executed more than once simultaneously.
+Redis is used at several points, e.g. to store information about the currently running services, so you can enforce uniqueness for specific services, i.e. make sure no more than one instance of such a service is executed simultaneously.
 
-#### Postgres
+#### Postgres (optional)
 
-The SQL that `Services::Query` (discussed further down) generates is optimized for Postgres. It might work with other databases but it's not guaranteed. If you're not using Postgres, don't use `Services::Query` or, even better, submit a [pull request](https://github.com/krautcomputing/services/issues) that fixes it to work with your database!
+The SQL that `Services::Query` (discussed further down) generates is optimized for Postgres. It might work with other databases but it's not guaranteed. If you're not using Postgres, you can still use all other parts of Services, just don't use `Services::Query` or, even better, submit a [pull request](https://github.com/krautcomputing/services/issues) that fixes it to work with your database!
 
 #### Sidekiq (optional)
 
-To process services in the background, Services uses [Sidekiq](https://github.com/mperham/sidekiq). Sidekiq is not absolutely required to use Services though. If it's not present when Services is loaded, a service will raise an exception when you try to enqueue it for background processing. If you use Sidekiq, make sure to load the Services gem after the Sidekiq gem.
+To process services in the background, Services uses [Sidekiq](https://github.com/mperham/sidekiq). If you don't need background processing, you can still use Services without Sidekiq. When you then try to enqueue a service for background processing, an exception will be raised. If you use Sidekiq, make sure to load the Services gem after the Sidekiq gem.
 
 ### Basic principles
 
@@ -41,22 +41,23 @@ Services is based on a couple of basic principles around what a service should b
 
 A service...
 
-* does one thing and does it well (Unix philosophy)
-* can be run synchronously (in the foreground) or asynchronously (in the background)
-* can be configured as "unique", meaning only one instance of it should be run at any time
+* does only one thing and does it well (Unix philosophy)
+* can be run synchronously (i.e. blocking/in the foreground) or asynchronously (i.e. non-blocking/in the background)
+* can be configured as "unique", meaning only one instance of it should be run at any time (including or ignoring parameters)
 * logs all the things (start time, end time, duration, caller, exceptions etc.)
-* has its own exception class(es) that all exceptions that it may raise inherit from
-* can be called with objects or IDs as parameters
+* has its own exception class(es) which all exceptions that might be raised inherit from
+* does not care whether certain parameters are objects or object IDs
 
-Apart from these basic principles, you can implement the actual logic in a service any way you want.
+Apart from these basic principles, you are free to implement the actual logic in a service any way you want.
 
 ### Conventions
 
-Follow these conventions when using Services in your Rails app:
+Follow these conventions when using Services in your Rails app, and you'll be fine:
 
-* Let your services inherit from `Services::Base` (or `Services::Query`)
+* Let your services inherit from `Services::Base`
+* Let your query objects inherit from `Services::Query`
 * Put your services in `app/services/`
-* Namespace your services with the model they operate on and give them verb names, e.g. `app/services/users/delete.rb` defines `Services::Users::Delete`. If a service operates on multiple models or no models at all, don't namespace them (`Services::DoStuff`) or namespace them by logical groups unrelated to models (`Services::Maintenance::CleanOldStuff`, `Services::Maintenance::SendDailySummary`, etc.)
+* Namespace your services with the model they operate on and give them "verb names", e.g. `app/services/users/delete.rb` defines `Services::Users::Delete`. If a service operates on multiple models or no models at all, don't namespace them (`Services::DoStuff`) or namespace them by logical groups unrelated to models (`Services::Maintenance::CleanOldStuff`, `Services::Maintenance::SendDailySummary`, etc.)
 * Some services call other services. Try to not combine multiple calls to other services and business logic in one service. Instead, some services should contain only business logic and other services only a bunch of service calls but no (or little) business logic. This keeps your services nice and modular.
 
 ### Configuration
@@ -66,8 +67,9 @@ You can/should configure Services in an initializer:
 ```ruby
 # config/initializers/services.rb
 Services.configure do |config|
-  config.logger = Services::Logger::Redis.new(Redis.new) # or Services::Logger::File.new(Rails.root.join('log'))
-  config.redis  = Redis.new
+  config.logger = Services::Logger::Redis.new(Redis.new)    # see Logging
+  config.redis  = Redis.new                                 # optional, if Redis.current is defined. Otherwise it is recommended to use
+                                                            # a [connection pool](https://github.com/mperham/connection_pool).
 end
 ```
 
@@ -80,9 +82,15 @@ By default, Rails expects `app/services/users/delete.rb` to define `Users::Delet
 config.autoload_paths += [config.root.join('app')]
 ```
 
-### Examples
+This looks as if it might break things, but I've never had any problems with it.
+
+### Services::Base
+
+`Services::Base` is the base class you should use for all your services. It gives you a couply of helper methods and defines a custom exception class for you.
 
-The following service takes one or more users or user IDs as an argument.
+Read [the source](lib/services/base.rb) to understand what it does in more detail.
+
+The following example service takes one or more users or user IDs as an argument and deletes the users:
 
 ```ruby
 module Services
@@ -91,6 +99,9 @@ module Services
       def call(ids_or_objects)
         users = find_objects(ids_or_objects)
         users.each do |user|
+          if user.posts.any?
+            raise Error, "User #{user.id} has one or more posts, refusing to delete."
+          end
           user.destroy
           Mailer.user_deleted(user).deliver
         end
@@ -105,37 +116,44 @@ This service can be called in several ways:
 
 ```ruby
 # Execute synchronously/in the foreground
+
 Services::Users::Delete.call User.find(1)                # with a user object
-Services::Users::Delete.call User.where(id: [1, 2, 3])   # with multiple user objects
+Services::Users::Delete.call User.where(id: [1, 2, 3])   # with a ActiveRecord::Relation returning user objects
+Services::Users::Delete.call [user1, user2, user3]       # with an array of user objects
 Services::Users::Delete.call 1                           # with a user ID
-Services::Users::Delete.call [1, 2, 3]                   # with multiple user IDs
+Services::Users::Delete.call [1, 2, 3]                   # with an array of user IDs
 
 # Execute asynchronously/in the background
+
 Services::Users::Delete.perform_async 1                  # with a user ID
 Services::Users::Delete.perform_async [1, 2, 3]          # with multiple user IDs
 ```
 
-As you can see, you cannot use objects when calling a service asynchronously since the arguments are serialized to Redis.
+As you can see, you cannot use objects or a ActiveRecord::Relation as parameters when calling a service asynchronously since the arguments are serialized to Redis. This might change once Services works with [ActiveJob](https://github.com/rails/rails/tree/master/activejob) and [GlobalID](https://github.com/rails/globalid/).
 
-The helper `find_objects` is used to make sure you are dealing with an array of users from that point on, no matter whether `ids_or_objects` is a single user ID or user, or an array of user IDs or users.
+The helper `find_objects` is used to allow the `ids_or_objects` parameter to be a object, object ID, array or ActiveRecord::Relation, and make sure you we dealing with an array of objects from that point on.
 
 It's good practice to always return the objects a service has been operating on at the end of the service.
 
-Another example, this time using `Services::Query`:
+### Services::Query
+
+`Services::Query` on the other hand should be the base class for all query objects.
+
+Here is an example that is used to find users:
 
 ```ruby
 module Services
   module Users
     class Find < Services::Query
+      convert_condition_objects_to_ids :post
+
       private def process(scope, conditions)
         conditions.each do |k, v|
           case k
           when :email, :name
             scope = scope.where(k => v)
-          when :product_id
-            scope = scope.joins(:products).where("#{Product.table_name}.id" => v)
-          when :product_category_id
-            scope = scope.joins(:product_categories).where("#{ProductCategory.table_name}.id" => v)
+          when :post_id
+            scope = scope.joins(:posts).where("#{Post.table_name}.id" => v)
           else
             raise ArgumentError, "Unexpected condition: #{k}"
           end
@@ -147,25 +165,49 @@ module Services
 end
 ```
 
-Since you will create services to find objects for pretty much every model you have and they all look very similar, i.e. process the find conditions and return a `ActiveRecord::Relation`, you can let those services inherit from `Services::Query` to remove some of the boilerplate.
+A query object that inherits from `Services::Query` always receives two parameters: an array of IDs and a hash of conditions. It always returns an array, even if none or only one object is found.
 
-`Services::Query` takes an array of IDs and a hash of conditions as parameters. It then extracts some special conditions (:order, :limit, :page, :per_page) that are handled separately and passes a `ActiveRecord::Relation` and the remaining conditions to the `process` method that the inheriting class must define. This method should handle all the conditions, extend the scope and return it.
+When you write your query objects, the only method you have to write is `process` (preferably make it private). This method does the actual querying for all non-standard parameters (more about standard vs. non-standard parameters below).
+
+This is how `Services::Users::Find` can be called:
+
+```ruby
+Services::Users::Find.call []                             # find all users, neither filtered by IDs nor by conditions
+Services::Users::Find.call [1, 2, 3]                      # find users with ID 1, 2 or 3
+Services::Users::Find.call 1                              # find users with ID 1 (careful: returns an array containing this one user, if found, otherwise an empty array)
+Services::Users::Find.call [], email: 'foo@bar.com'       # find users with this email address
+Services::Users::Find.call [1, 2], post: Post.find(1)     # find users with ID 1 or 2 and having the post with ID 1
+Services::Users::Find.call [1, 2], post: [Post.find(1)]   # same as above
+Services::Users::Find.call [1, 2], post: 1                # same as above
+```
 
 Check out [the source of `Services::Query`](lib/services/query.rb) to understand what it does in more detail.
 
+#### Standard vs. non-standard parameters
+
+to be described...
+
+#### convert_condition_objects_to_ids
+
+As with service objects, you want to be able to pass objects or IDs as conditions to query objects as well, and be sure that they behave the same way. This is what `convert_condition_objects_to_ids :post` does in the previous example: it tells the service object to convert the `post` condition, if present, to `post_id`.
+
+For example, at some point in your app you have an array of posts and need to find the users that created these posts. `Services::Users::Find.call([], post: posts)` will find them for you. If you have a post ID on the other hand, simply use `Services::Users::Find.call([], post: post_id)`, or if you have a single post, use `Services::Users::Find.call([], post: post)`. Each of these calls will return an array of users, as you would expect.
+
+`Services::Query` takes an array of IDs and a hash of conditions as parameters. It then extracts some special conditions (:order, :limit, :page, :per_page) that are handled separately and passes a `ActiveRecord::Relation` and the remaining conditions to the `process` method that the inheriting class must define. This method should handle all the conditions, extend the scope and return it.
+
 ### Helpers
 
-Your services inherit from `Services::Base` which makes several helper methods available:
+Your services inherit from `Services::Base` which makes several helper methods available to them:
 
 * `Rails.application.routes.url_helpers` is included so you use all Rails URL helpers.
 * `find_objects` and `find_object` let you automatically find object or a single object from an array of objects or object IDs, or a single object or object ID. The only difference is that `find_object` returns a single object whereas `find_objects` always returns an array.
 * `object_class` tries to figure out the class the service operates on. If you follow the service naming conventions and you have a service `Services::Products::Find`, `object_class` will return `Product`. Don't call it if you have a service like `Services::DoStuff` or it will raise an exception.
 
-Your services also automatically get a custom `Error` class, so you can `raise Error, 'Uh-oh, something has gone wrong!'` and a `Services::MyService::Error` will be raised.
+Your services also automatically get a custom `Error` class, so you can `raise Error, 'Uh-oh, something has gone wrong!'` in `Services::MyService` and a `Services::MyService::Error` will be raised.
 
 ### Logging
 
-You can choose between logging to Redis or to a file.
+You can choose between logging to Redis or to a file, or turn logging off. By default logging is turned off.
 
 #### Redis
 

data/lib/services.rb

@@ -6,11 +6,16 @@ module Services
   include GemConfig::Base
 
   BackgroundProcessorNotFound = Class.new(StandardError)
+  RedisNotFound               = Class.new(StandardError)
 
   with_configuration do
     has :logger, default: Services::Logger::Null.new
     has :redis
   end
+
+  def self.redis
+    @redis ||= self.configuration.redis || (defined?(Redis.current) && Redis.current) or fail RedisNotFound, 'Redis not configured.'
+  end
 end
 
 require_relative 'services/version'

data/lib/services/modules/uniqueness_checker.rb

@@ -27,7 +27,7 @@ module Services
         @_uniqueness_args = args.empty? ? @_service_args : args
         new_uniqueness_key = uniqueness_key(@_uniqueness_args)
         raise "A uniqueness key with args #{@_uniqueness_args.inspect} already exists." if @_uniqueness_keys && @_uniqueness_keys.include?(new_uniqueness_key)
-        if @_similar_service_id = Services.configuration.redis.get(new_uniqueness_key)
+        if @_similar_service_id = Services.redis.get(new_uniqueness_key)
           if on_error.to_sym == :ignore
             return false
           else
@@ -37,7 +37,7 @@ module Services
         else
           @_uniqueness_keys ||= []
           @_uniqueness_keys << new_uniqueness_key
-          Services.configuration.redis.setex new_uniqueness_key, ONE_DAY, @id
+          Services.redis.setex new_uniqueness_key, ONE_DAY, @id
           true
         end
       end
@@ -62,8 +62,8 @@ module Services
           raise "Unexpected on_error: #{@_on_error}"
         end
       ensure
-        Services.configuration.redis.del @_uniqueness_keys unless Array(@_uniqueness_keys).empty?
-        Services.configuration.redis.del error_count_key
+        Services.redis.del @_uniqueness_keys unless Array(@_uniqueness_keys).empty?
+        Services.redis.del error_count_key
       end
 
       private
@@ -99,11 +99,11 @@ module Services
       end
 
       def error_count
-        (Services.configuration.redis.get(error_count_key) || 0).to_i
+        (Services.redis.get(error_count_key) || 0).to_i
       end
 
       def increase_error_count
-        Services.configuration.redis.setex error_count_key, retry_delay + ONE_DAY, error_count + 1
+        Services.redis.setex error_count_key, retry_delay + ONE_DAY, error_count + 1
       end
 
       def uniqueness_key(args)

data/lib/services/version.rb

@@ -1,3 +1,3 @@
 module Services
-  VERSION = '4.1.0'
+  VERSION = '4.1.1'
 end

data/spec/services/base_spec.rb

@@ -45,7 +45,7 @@ describe Services::Base do
     context 'when passing in something else than a single object or ID' do
       it 'raises an error' do
         [%w(foo bar), nil, Object.new].each do |object|
-          expect { Services::Models::FindObjectTest.call(object) }.to raise_error
+          expect { Services::Models::FindObjectTest.call(object) }.to raise_error(Services::Models::FindObjectTest::Error)
         end
       end
     end
@@ -91,7 +91,7 @@ describe Services::Base do
     context 'when passing in something else than a single object or ID' do
       it 'raises an error' do
         [%w(foo bar), nil, Object.new].each do |object|
-          expect { Services::Models::FindIdTest.call(object) }.to raise_error
+          expect { Services::Models::FindIdTest.call(object) }.to raise_error(Services::Models::FindIdTest::Error)
         end
       end
     end

data/spec/services/logger/redis_spec.rb

@@ -2,7 +2,7 @@ require 'spec_helper'
 
 describe Services::Logger::Redis do
   let(:key)    { 'custom_log_key' }
-  let(:redis)  { Redis.new }
+  let(:redis)  { Redis.new(url: REDIS_URL) }
   let(:logger) { described_class.new(redis, key) }
   let(:logs) {
     [

data/spec/services/modules/uniqueness_checker_spec.rb

@@ -77,7 +77,7 @@ shared_examples 'checking the uniqueness properly' do
 
     # Check that all Redis keys are deleted
     key_pattern = "#{described_class::KEY_PREFIX}*"
-    expect(Services.configuration.redis.keys(key_pattern)).to be_empty
+    expect(Services.redis.keys(key_pattern)).to be_empty
   end
 end
 

data/spec/spec_helper.rb

@@ -17,22 +17,20 @@ SIDEKIQ_PIDFILE        = SUPPORT_DIR.join('sidekiq.pid')
 WAIT                   = 0.5
 START_TIMEOUT          = 5
 SIDEKIQ_TIMEOUT        = 20
-REDIS_PORT             = 6479
+REDIS_URL              = 'redis://localhost:6379/0'
 
 %w(shared helpers test_services).each do |file|
   require SUPPORT_DIR.join(file)
 end
 
-Services.configure do |config|
-  config.redis = Redis.new
-end
+Redis.current = Redis.new(url: REDIS_URL)
 
 Sidekiq.configure_client do |config|
-  config.redis = { redis: "redis://localhost:#{REDIS_PORT}/0", namespace: 'sidekiq', size: 1 }
+  config.redis = { url: REDIS_URL, namespace: 'sidekiq', size: 1 }
 end
 
 Sidekiq.configure_server do |config|
-  config.redis = { redis: "redis://localhost:#{REDIS_PORT}/0", namespace: 'sidekiq' }
+  config.redis = { url: REDIS_URL, namespace: 'sidekiq' }
 end
 
 RSpec.configure do |config|

data/spec/support/activerecord_models_and_services.rb

@@ -27,7 +27,9 @@ module Services
     class FindRaiseConditions < Services::Query
       convert_condition_objects_to_ids :comment
 
-      private def process(scope, conditions)
+      private
+
+      def process(scope, conditions)
         raise conditions.to_json
       end
     end
@@ -39,7 +41,9 @@ module Services
     class Find < Services::Query
       convert_condition_objects_to_ids :comment
 
-      private def process(scope, conditions)
+      private
+
+      def process(scope, conditions)
         conditions.each do |k, v|
           case k
           when :title, :body
@@ -61,7 +65,9 @@ module Services
     class Find < Services::Query
       convert_condition_objects_to_ids :post
 
-      private def process(scope, conditions)
+      private
+
+      def process(scope, conditions)
         conditions.each do |k, v|
           case k
           when :body, :post_id

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: services
 version: !ruby/object:Gem::Version
-  version: 4.1.0
+  version: 4.1.1
 platform: ruby
 authors:
 - Manuel Meurer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-05-05 00:00:00.000000000 Z
+date: 2016-02-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -214,7 +214,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: A nifty service layer for your Rails app