services 3.1.1 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: aa36865886b193fa90e404a25e97a77f02b8db14
-  data.tar.gz: 98215ed1fe3f3c11426c8946d6e5fed0cf9f5c61
+  metadata.gz: 74080ca61d88a944b2f35bfe0f81cd00815c96cc
+  data.tar.gz: 4be4bae8d75734489654038732c34d922e28b1bc
 SHA512:
-  metadata.gz: 23145a46e65887c619eb18c4be711bbecbf0016de66c0c89c791f4aacf4d6eb7bd2f71cc975ae180700912d93a5a1deaa2edc3427e323541d743bc95292e39ef
-  data.tar.gz: 9e3cbf5c22d2ea747bc91b08b443e8f8c7856da671104cb2bc80d998a8bc8ce6741ac3edf6c46a96912dcc08599343772810026d344c429b902d76bbdd3c88b1
+  metadata.gz: a0332a0d2e3be17d07698ee992d85fce822d77744a06051cf8fe1015f6325805aeeb175e21d1d7845d77bfe054c8fa590a54eeed64afba7a20a98d168450bd90
+  data.tar.gz: 4c4d2fce4a8df600e1457d8ef70c45f1f62d267e0aa43670bd9e9e962ec2ff8c402fe0bd651176e14babe295f9fa99ad209ebf122bcb11f423df3384a4ddaa24

data/README.md

@@ -5,48 +5,52 @@
 [![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 collection of modules and base classes that let you implement a nifty service layer in your Rails app.
+Services is a small collection of modules and base classes that let you implement a nifty service layer in 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.
 
-**The biggest benefit you get with 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 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.**
 
 ## Usage
 
-For disambiguation, we let's write Services with a uppercase "S" when we mean this gem, and services with a lowercase "s" when we mean, well, the plural of service.
+For disambiguation: when I write "Services" with a uppercase "S", I mean this gem, whereas with "services" I mean, well, the plural of service.
 
 ### Requirements
 
-#### Rails
+### Ruby
 
-to be described...
+Ruby >= 2.0
 
-#### Redis
+#### Rails
 
-to be described...
+Rails >= 3.2
 
-#### Sidekiq
+#### Redis
 
-To process services in the background, Services uses [Sidekiq](https://github.com/mperham/sidekiq). Sidekiq is not 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.
+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.
 
 #### Postgres
 
 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!
 
+#### 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.
+
 ### Basic principles
 
-Services is based on a couple of basic principles of what a service should be and do in your app:
+Services is based on a couple of basic principles around what a service should be and do in your app:
 
 A service...
 
-* ...does one thing well (Unix philosophy)
-* ...can be run synchronously (in the foreground) or asynchronously (in the background)
-* ...can be unique, meaning only one instance of it should be run at a time
-* ...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 one or multiple objects or one or multiple object IDs
+* 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
+* 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
 
 Apart from these basic principles, you can implement the actual logic in a service any way you want.
 
@@ -54,20 +58,20 @@ Apart from these basic principles, you can implement the actual logic in a servi
 
 Follow these conventions when using Services in your Rails app:
 
-* services inherit from `Services::Base` (or `Services::Query`)
-* services are located in `app/services/`
-* services are namespaced with the model they operate on and their names are verbs, 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::CleanOldUsers`, `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.
+* Let your services inherit from `Services::Base` (or `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.)
+* 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.
 
-### Configure
+### Configuration
 
-You can set some configuration options in an initializer:
+You can/should configure Services in an initializer:
 
 ```ruby
 # config/initializers/services.rb
 Services.configure do |config|
-  config.logger = Services::Logger::Redis.new(REDIS) # or Services::Logger::File.new(Rails.root.join('log'))
-  config.redis  = REDIS
+  config.logger = Services::Logger::Redis.new(Redis.new) # or Services::Logger::File.new(Rails.root.join('log'))
+  config.redis  = Redis.new
 end
 ```
 
@@ -104,7 +108,7 @@ end
 This service can be called in several ways:
 
 ```ruby
-# Execute synchronously/immediately
+# 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 1                           # with a user ID
@@ -117,7 +121,7 @@ Services::Users::Delete.perform_async [1, 2, 3]          # with multiple user ID
 
 As you can see, you cannot use objects when calling a service asynchronously since the arguments are serialized to Redis.
 
-As you can see, 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 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.
 
 It's good practice to always return the objects a service has been operating on at the end of the service.
 
@@ -149,9 +153,9 @@ 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.
 
-`Services::Query` inherits from `Services::Base` and 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.
+`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.
 
-Check out [the source of `Services::Query`](lib/services/base_finder.rb) to understand what it does in more detail.
+Check out [the source of `Services::Query`](lib/services/query.rb) to understand what it does in more detail.
 
 ### Helpers
 
@@ -160,7 +164,6 @@ Your services inherit from `Services::Base` which makes several helper methods a
 * `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.
-* `controller` creates a `ActionController::Base` instance with an empty request. You can use it to call `render_to_string` to render a view from your service for example.
 
 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.
 
@@ -168,10 +171,13 @@ Your services also automatically get a custom `Error` class, so you can `raise E
 
 You can choose between logging to Redis or to a file.
 
-
 #### Redis
 
+to be described...
+
+#### File
 
+to be described...
 
 ### Exception wrapping
 
@@ -185,10 +191,6 @@ to be described...
 
 to be described...
 
-## Requirements
-
-Ruby >= 2.0
-
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -213,4 +215,4 @@ Or install it yourself as:
 
 ## Testing
 
-You need Redis to run tests, check out the Guardfile!
+You need Redis to run tests, check out the [Guardfile](Guardfile) which loads it automatically when you start Guard!

data/lib/services.rb

@@ -6,7 +6,6 @@ module Services
   BackgroundProcessorNotFound = Class.new(StandardError)
 
   with_configuration do
-    has :host, classes: String
     has :logger
     has :redis
   end

data/lib/services/base.rb

@@ -66,16 +66,5 @@ module Services
         end.first
       end
     end
-
-    def controller
-      @controller ||= begin
-        raise 'Please configure host.' if Services.configuration.host.nil?
-        request = ActionDispatch::TestRequest.new
-        request.host = Services.configuration.host
-        ActionController::Base.new.tap do |controller|
-          controller.instance_variable_set('@_request', request)
-        end
-      end
-    end
   end
 end

data/lib/services/version.rb

@@ -1,3 +1,3 @@
 module Services
-  VERSION = '3.1.1'
+  VERSION = '4.0.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: services
 version: !ruby/object:Gem::Version
-  version: 3.1.1
+  version: 4.0.0
 platform: ruby
 authors:
 - Manuel Meurer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-22 00:00:00.000000000 Z
+date: 2015-02-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake