nifty_services 0.0.5 → 0.0.6

data/docs/api.md

@@ -0,0 +1,142 @@
+# NiftyServices documentation
+
+---
+
+## Services Public API
+
+Below, a list of most common public accessible methods for any instance of service:
+(Detailed usage and full API list is available below this section)
+
+```ruby
+service.success? # boolean
+service.fail? # boolean
+service.errors # array
+service.response_status # symbol (eg: :ok)
+service.response_status_code # integer (eg: 200)
+```
+
+So, grabbing our `DailyNewsMailSendService` service again, we could do:
+
+```ruby
+service = DailyNewsMailSendService.new(User.new('test', 'test@test.com'))
+service.execute
+
+if service.success? # or unless service.fail?
+  SentEmails.create(user: service.user, type: 'welcome_email')
+else
+  puts 'Error sending email, details below:'
+  puts 'Status: %s' % service.response_status
+  puts 'Status code: %s' % service.response_status_code
+  puts service.errors
+end
+
+# trying to re-execute the service will return `nil`
+service.execute
+```
+
+This is really great and nifty, no? But we already started, there's some really cool stuff when dealing with **Restful** API's actions, before entering this subject let's see how to handle error and success response.
+
+---
+
+## Success & Error Responses
+
+### :white_check_mark: Handling Success :zap:
+
+To mark a service running as successfully, you must call one of this methods (preferencially inside of `execute_action` block):
+
+* `success_response # [200, :ok]`
+* `success_created_response [201, :created]`
+
+The first value in comments above is the value which will be defined to `service.response_status_code` and the last is the value set to `service.response_status`.
+
+---
+
+
+### :red_circle: Handling Error :boom:
+
+By default, all services comes with following error methods:
+(**Hint**: See all available error methods [`here`](lib/nifty_services/configuration.rb#L10-L16))
+
+```ruby
+bad_request_error(message_key) # set response_status_code to 400
+
+not_authorized_error(message_key) # set response_status_code to 401,
+
+forbidden_error(message_key) # set response_status_code to 403,
+
+not_found_error(message_key) # set response_status_code to 404,
+
+unprocessable_entity_error(message_key) # set response_status_code to 422,
+
+internal_server_error(message_key) # set response_status_code to 500,
+
+not_implemented_error(message_key) # set response_status_code to 501
+```
+
+Beside this methods, you can always use **low level** API to generate errors, just call the `error` method, ex:
+
+```ruby
+# API
+error(status, message_key, options = {})
+
+# eg:
+error(409, :conflict_error, reason: 'unkown')
+error!(409, :conflict_error, reason: 'unkown')
+
+# suppose you YML locale file have the configuration:
+# nifty_services:
+#  errors:
+#    conflict_error: 'Conflict! The reason is %{reason}'
+```
+
+#### Custom error response methods
+
+But you can always add new convenience errors methods via API, this way you will have more expressivity and sintax sugar:
+
+```ruby
+## API
+NiftyServices.add_response_error_method(status, status_code)
+
+## eg:
+
+NiftyServices.add_response_error_method(:conflict, 409)
+
+## now you have the methods:
+
+## conflict_error(:conflict_error)
+## conflit_error!(:conflict_error)
+```
+
+---
+
+## Full Public API methods list
+
+You can use any of the methods above with your `services instances`:
+
+```ruby
+service.success? # boolean
+service.fail? # boolean
+
+service.errors # hash
+service.add_error(error) # array
+
+service.response_status # symbol (eg: :ok)
+service.response_status_code # integer (eg: 200)
+
+service.changed_attributes # array
+service.changed? # boolean
+
+service.callback_fired?(callback_name) # boolean
+service.register_callback(name, method, &block) # nil
+service.register_callback_action(&block) # nil
+
+service.option_exists?(option_name) # boolean
+service.option_enabled?(option_name) # boolean
+service.option_disabled?(option_name) # boolean
+```
+
+---
+
+### Next
+
+See [Crud Services](./crud_services.md)

data/docs/callbacks.md

@@ -0,0 +1,67 @@
+# NiftyServices documentation
+
+---
+
+## Callbacks
+
+Here the most common callbacks list you can use to hook actions in run-time:
+(**Hint**: See all existent callbacks definitions in [`extensions/callbacks.rb`](../lib/nifty_services/extensions/callbacks.rb#L7-L22) file)
+
+```
+  - before_initialize
+  - after_initialize
+  - before_execute
+  - after_execute
+  - before_error
+  - after_error
+  - before_success
+  - after_success
+```
+
+
+
+### Creating custom Callbacks
+
+Well, probably you will need to add custom callbacks to your services, in my case I need to save in database an object which tracks information about the environment used to create **ALL RECORDS** in my application, I was able to do it with just a few lines of code, see for yourself:
+
+```ruby
+# Some monkey patch :)
+
+NiftyServices::BaseCreateService.class_eval do
+  ORIGIN_WHITELIST_ATTRIBUTES = [:provider, :locale, :user_agent, :ip]
+
+  def origin_params(params = {})
+    filter_hash(params.fetch(:origin, {}).to_h, ORIGIN_WHITELIST_ATTRIBUTES)
+  end
+
+  def create_origin(originable, params = {})
+    return unless originable.respond_to?(:create_origin)
+    return unless create_origin?
+
+    originable.create_origin(origin_params(params))
+  end
+
+  # for records which we don't need to create origins, just
+  # overwrite this method inside service class turning it off with:
+  # return false
+  def create_origin?
+    Application::Config.create_origin_for_records
+  end
+end
+
+# This register a callback for ALL services who inherit from `NiftyServices::BaseCreateService`
+# In other words: Every and all records created in my application will be tracked
+# I can believe that is easy like this, I need a beer right now!
+NiftyServices::BaseCreateService.register_callback(:after_success, :create_origin_for_record) do
+  create_origin(@record, @options)
+end
+
+```
+
+Now, every record created in my application will have an associated `origin` object, really simple and cool!
+
+---
+
+### Next
+
+See [Configuration](./configuration.md)

data/docs/cli.md

@@ -0,0 +1,13 @@
+# NiftyServices documentation
+
+---
+
+## :question: CLI Generators <a name="cli-generators"></a>
+
+Currently NiftyServices don't have CLI(command line interface) generators, but is in the roadmap, so keep your eyes here!
+
+---
+
+### Next
+
+See [Install on your Ruby Application](../README.md#installation)

data/docs/configuration.md

@@ -0,0 +1,62 @@
+# NiftyServices documentation
+
+---
+
+## :construction: Configuration :construction:
+
+There are only a few things you must want and have to configure for your services work properly, below you can see all needed configuration:
+
+```ruby
+NiftyServices.config do |config|
+  # [optional]
+  # global logger for all services
+  # [Default: Logger.new('/dev/null')]
+  config.logger = Logger.new('log/services_logger.log')
+
+  # [Optional - Default: `'nifty_services'`]
+  # Set a custom I18n lookup namespace for error messages
+  config.i18n_namespace = 'my_app'
+
+  # [Optional - Default: `save`]
+  # Set the method called when saving a record using `BaseCreateService`
+  # The default value is `save`, this will call:`record.save`
+  # Eg: If you want to use `#persist`(`record.persist`), use:
+  config.save_record_method = :persist
+
+  # But you can pass any object that responds to `#call` method, like a Proc:
+  # This way, NiftyServices will call the method sending the record as argument.
+  config.save_record_method = ->(record) {
+    record.save_in_database!
+  }
+
+  # [Optional - Default: `delete`]
+  # Set the method called when deleting a record using BaseDeleteService
+  # The default value is `delete`, this will call:`record.delete`
+  # Eg: If you want to use `#destroy`(`record.destroy`), use:
+  config.delete_record_method = :destroy
+
+  # But you can pass any object that responds to `#call` method, like a Proc:
+  # This way, NiftyServices will call the method sending the record as argument.
+  config.delete_record_method = ->(record) {
+    record.remove
+  }
+
+  # [Optional - Default: `update`]
+  # Set the method called when updating a record using BaseUpdateService
+  # The default value is `update`, this will call:`record.update(attributes)`
+  # Eg: If you want to use `sync`(`record.sync(attributes)`), use:
+  config.update_record_method = :sync
+
+  # But you can pass any object that responds to `#call` method, like a Proc:
+  # This way, NiftyServices will call this block sending the record and attributes as arguments.
+  config.update_record_method = ->(record, attributes) {
+    record.update_attributes(attributes)
+  }
+end
+```
+
+---
+
+### Next
+
+See [Web Frameworks Integration](./webframeworks_integration.md)

data/docs/crud_services.md

@@ -0,0 +1,534 @@
+# NiftyServices documentation
+
+---
+
+## CRUD Services
+
+So, until now we saw how to use `NiftyServices::BaseService` to create generic services to couple specific domain logic for actions,  this is very usefull, but things get a lot better when you're working with **CRUD** actions for your api.
+
+Follow an example of **Create, Update and Delete** CRUD services for `Post` resource:
+
+## :white_check_mark: CRUD: Create
+
+By default, NiftyServices expect that record responds to `new` class method. (eg: `Post.new`).
+
+NiftyServices will expect that record respond to `#save` instance method when trying to save the record after creating it, you can override this behavior using the method `save_record` or using global configuration:
+
+```ruby
+NiftyServices.config do |config|
+  # The default value is `save`, this will call:`record.save`
+  # Eg: If you want to use `#persist`(`record.persist`), use:
+  config.save_record_method = :persist
+
+  # But you can pass any object that responds to `#call` method, like a Proc:
+  # This way, NiftyServices will call the method sending the record as argument.
+  config.save_record_method = ->(record) {
+    record.save_in_database!
+  }
+end
+```
+
+
+```ruby
+class PostCreateService < NiftyServices::BaseCreateService
+
+  attr_reader :user
+
+  # You can freely override initialize method to receive more arguments
+  def initialize(user, options = {})
+    @user = user
+    super(options)
+  end
+
+  # record_type must be a object respond to :build and :save methods
+  # is possible to access this record outside of service using
+  # `service.record` or `service.post`
+  # if you want to create a custom alias name, use:
+  # record_type Post, alias_name: :user_post
+  # This way, you can access the record using
+  # `service.user_post`
+
+  record_type Post
+
+  WHITELIST_ATTRIBUTES = [:title, :content]
+
+  whitelist_attributes WHITELIST_ATTRIBUTES
+
+
+  # use custom scope to create the record
+  # scope returned below must respond_to :build method
+  def build_record_scope
+    @user.posts
+  end
+
+  # this key is used for I18n translations, you don't need to override or implement
+  # NiftyService will try to inflect this using `record_type.to_s.underscore + 's'`
+  # So, if your record type is `Post`, `record_error_key` will be `posts`
+  def record_error_key
+    :posts
+  end
+
+  # This method is strict required by NiftyServices, each service must implement
+  def can_create_record?
+    # Checking user before trying to create a post for this same user
+    unless valid_user?
+      return not_found_error!('users.not_found')
+    end
+
+    return !duplicated?
+  end
+
+  def duplicated?
+    # (here you can do any kind of validation, eg:)
+    # check if user is trying to recreate a recent resource
+    # this will return false if user has already created a post with
+    # this title in the last 30 seconds (usefull to ban bots)
+    @user.posts.exists(title: record_allowed_attributes[:title], created_at: "NOW() - interval(30 seconds)")
+  end
+
+  # This is a custom method of this class, not NiftyService stuff
+  def valid_user?
+    # `valid_object?` signature: `valid_object?(object, expected_class)`
+    valid_object?(@user, User)
+  end
+end
+
+service = PostCreateService.new(User.first, title: 'Teste', content: 'Post example content')
+
+service.execute
+
+service.success? # true
+service.response_status_code # 201
+service.response_status # :created
+```
+
+
+
+#### :earth_americas: I18n setup
+
+You must have the following keys setup up in your locales files:
+
+```yml
+ nifty_services:
+   users:
+     not_found: "Invalid or not found user"
+     ip_temporarily_blocked: "This IP is temporarily blocked from creating records"
+   # note: posts is the key return in `record_error_key` service method
+   posts:
+      cant_create: "Can't create this record"
+```
+
+#### :alien: Invalid user <a name="create-resource-user-invalid"></a>
+
+If you try to create a post for a invalid user, such as:
+
+```ruby
+# PostCreateService.new(user, options)
+service = PostCreateService.new(nil, options)
+service.execute
+
+service.success? # false
+service.response_status # :not_found
+service.response_status_code # 404
+service.errors # ["Invalid or not found user"]
+```
+
+#### :no_entry_sign: Not authorized to create
+
+Or if user is trying to create a duplicate resource:
+
+```ruby
+# PostCreateService.new(user, options)
+service = PostCreateService.new(User.first, options)
+service.execute
+
+service.success? # false
+service.errors # ["User cant create this record"]
+service.response_status # :forbidden_error
+service.response_status_code # 400
+```
+
+#### :boom: Record is invalid
+
+Eg: if any validation in Post model won't pass:
+
+```ruby
+# PostCreateService.new(user, options)
+# Post model as the validation:
+# validates_presence_of :title, :content
+service = PostCreateService.new(User.first, title: nil, content: nil)
+service.execute
+
+service.success? # false
+
+service.errors # => [{ title: 'is empty', content: 'is empty' }]
+
+service.response_status # :unprocessable_entity
+service.response_status_code # 422
+```
+---
+
+## :white_check_mark: CRUD: Update
+
+By default, NiftyServices expect that record responds to `update` class method. (eg: `Post.update(id, data)`)
+
+You can override this behavior using `update_record` method in your service class, or using global configuration:
+
+```ruby
+NiftyServices.config do |config|
+  # Set the method called when updating a record using BaseUpdateService
+  # Eg: If you want to use `sync`(`record.sync(attributes)`), use:
+  config.update_record_method = :sync
+
+  # But you can pass any object that responds to `#call` method, like a Proc:
+  # This way, NiftyServices will call the method sending the record and attributes.
+  config.update_record_method = ->(record, attributes) {
+    record.update_attributes(attributes)
+  }
+end
+```
+
+For validation, NiftyServices expect that record respond to `#valid?` and `#errors` instance methods.
+
+You can override this behavior using `success_updated?` and `update_errors` methods.
+
+
+```ruby
+class PostUpdateService < NiftyServices::BaseUpdateService
+
+  attr_reader :user
+
+  # service.post or service.record
+  record_type Post
+
+  WHITELIST_ATTRIBUTES = [:title, :content]
+
+  whitelist_attributes WHITELIST_ATTRIBUTES
+
+  # You can freely override initialize method to receive more arguments
+  def initialize(record, user, options = {})
+    @user = user
+    super(record, options)
+  end
+
+  # This method is strict required by NiftyServices, each service must implement
+  def can_update_record?
+    unless valid_user?
+     return not_found_error!('users.not_found')
+    end
+
+    return user_has_permission?
+  end
+
+  def user_has_permission?
+    # only system admins and owner can update this record
+    # or you can transfer the logic below to something like:
+    # @record.user_can_update_record?(@user)
+    @user.admin? || @user.id == @record.id
+  end
+
+  # this key is used for I18n translations, you don't need to override or implement
+  def record_error_key
+    :posts
+  end
+
+  # This is a custom method of this class, not NiftyService stuff
+  def valid_user?
+    valid_object?(@user, User)
+  end
+end
+
+# :user_id will be ignored since it's not in whitelisted attributes
+# this can safe yourself from parameter inject attacks, by default
+update_service = PostUpdateService.new(Post.first, User.first, title: 'Changing title', content: 'Updating content', user_id: 2)
+
+update_service.execute
+
+update_service.success? # true
+update_service.response_status # :ok
+update_service.response_status_code # 200
+
+update_service.changed_attributes # [:title, :content]
+update_service.changed? # true
+```
+
+#### :earth_asia: I18n setup
+
+Your locale file must have the following keys:
+
+```yml
+ posts:
+   not_found: "Invalid or not found post"
+   cant_update: "Can't update this record"
+ users:
+   not_found: "Invalid or not found user"
+```
+
+#### :alien: User is invalid <a name="update-resource-user-invalid"></a>
+
+Response when owner user is not valid:
+
+```ruby
+# PostUpdateService.new(post, user, params)
+update_service = PostUpdateService.new(Post.first, nil, title: 'Changing title', content: 'Updating content')
+
+update_service.execute
+
+update_service.success? # false
+update_service.response_status # :not_found_error
+update_service.response_status_code # 404
+
+update_service.errors # ["Invalid or not found user"]
+```
+
+#### :closed_lock_with_key: Resource (Post) don't belongs to user <a name="update-resource-dont-belongs-to-user"></a>
+
+Responses when trying to update to update a resource who don't belongs to owner:
+
+```ruby
+# PostUpdateService.new(post, user, params)
+update_service = PostUpdateService.new(Post.first, User.last, title: 'Changing title', content: 'Updating content')
+
+update_service.execute
+
+update_service.success? # false
+update_service.response_status # :forbidden
+update_service.response_status_code # 400
+
+update_service.changed_attributes # []
+update_service.changed? # false
+update_service.errors # ["User can't update this record"]
+```
+
+#### :santa: Resource don't exists <a name="update-resource-dont-exists"></a>
+
+Response when post don't exists:
+
+```ruby
+# PostUpdateService.new(post, user, params)
+update_service = PostUpdateService.new(nil, User.last, title: 'Changing title', content: 'Updating content')
+
+update_service.execute
+
+update_service.success? # false
+update_service.response_status # :not_found_error
+update_service.response_status_code # 404
+
+update_service.errors # ["Invalid or not found post"]
+```
+
+---
+
+## :white_check_mark: CRUD: Delete
+
+
+By default, NiftyServices expect that record responds to `delete` instance method. (eg: `post.delete`)
+
+You can override this behavior using `delete_record` method in your Service class, or using global configuration:
+
+```ruby
+NiftyServices.config do |config|
+  # The default value is `delete`, this will call:`record.delete`
+   # Eg: If you want to use `#destroy`(`record.destroy`), use:
+  config.delete_record_method = :destroy
+
+  # But you can pass any object that responds to `#call` method, like a Proc:
+  # This way, NiftyServices will call the method sending the record
+  config.delete_record_method = ->(record) {
+    record.remove
+  }
+end
+```
+
+
+```ruby
+class PostDeleteService < NiftyServices::BaseDeleteService
+
+  attr_reader :user
+
+  # record_type object must respond to :delete method
+  # But you can override `delete_method` method to do whatever you want
+  record_type Post
+
+  # You can freely override initialize method to receive more arguments
+  def initialize(record, user, options = {})
+    @user = user
+    super(record, options)
+  end
+
+  # this key is used for I18n translations, you don't need to override or implement
+  def record_error_key
+    :posts
+  end
+
+  # below the code used internally, you can override to
+  # create custom delete, but remembers that this method
+  # must return a boolean value
+  def delete_record
+    @record.delete
+  end
+
+  # This method is strict required by NiftyServices, each service must implement
+  def can_delete_record?
+    # Checking user before trying to create a post for this same user
+    unless valid_user?
+      return not_found_error!('users.not_found')
+    end
+
+    return user_has_permission?
+  end
+
+  def user_has_permission?
+   # only system admins and owner can delete this record
+   # or you can transfer the logic below something like:
+   # @record.user_can_delete_record?(@user)
+   @user.admin? || @user.id == @record.id
+  end
+
+  # This is a custom method of this class, not NiftyService stuff
+  def valid_user?
+    valid_object?(@user, User)
+  end
+end
+```
+
+#### :earth_africa: I18n setup
+
+Your locale file must have the following keys:
+
+```yml
+ posts:
+   not_found: "Invalid or not found post"
+   cant_delete: "Can't delete this record"
+ users:
+   not_found: "Invalid or not found user"
+```
+
+#### :alien: User is invalid <a name="delete-resource-user-invalid"></a>
+
+Response when owner user is not valid:
+
+```ruby
+# PostDeleteService.new(post, user, params)
+delete_service = PostDeleteService.new(Post.first, nil)
+
+delete_service.execute
+
+delete_service.success? # false
+delete_service.response_status # :not_found_error
+delete_service.response_status_code # 404
+
+delete_service.errors # ["Invalid or not found user"]
+```
+
+#### :closed_lock_with_key: Resource don't belongs to user <a name="delete-resource-dont-belongs-to-user"></a>
+
+Responses when trying to delete a resource who don't belongs to owner:
+
+```ruby
+# PostDeleteService.new(post, user, params)
+delete_service = PostDeleteService.new(Post.first, User.last)
+delete_service.execute
+
+delete_service.success? # false
+delete_service.response_status # :forbidden
+delete_service.response_status_code # 400
+delete_service.errors # ["User can't delete this record"]
+```
+
+#### :santa: Resource(Post) don't exists <a name="delete-resource-dont-exists"></a>
+
+Response when post don't exists:
+
+```ruby
+# PostDeleteService.new(post, user, params)
+delete_service = PostDeleteService.new(nil, User.last)
+
+delete_service.execute
+
+delete_service.success? # false
+delete_service.response_status # :not_found_error
+delete_service.response_status_code # 404
+
+delete_service.errors # ["Invalid or not found post"]
+```
+
+---
+
+#### Tip
+
+You can DRY the examples above using `concerns`, if you take a look you will see
+that in `PostUpdateService` and `PostDeleteService` same validation
+methods are repeated, so lets improve this, first thing is create a Ruby plain module:
+
+```ruby
+module PostCrudExtensions
+  # You can freely override initialize method to receive more arguments
+  def initialize(record, user, options = {})
+    @user = user
+    super(record, options)
+  end
+
+  def record_allowed_attributes
+    WHITELIST_ATTRIBUTES
+  end
+
+  def self.whitelist_attributes
+    WHITELIST_ATTRIBUTES
+  end
+
+  def user_has_permission?
+    # only system admins and owner can update this record
+    # or you can transfer the logic below to something like:
+    # @record.user_can_update_record?(@user)
+    @user.admin? || @user.id == @record.id
+  end
+
+  # this key is used for I18n translations, you don't need to override or implement
+  def record_error_key
+    :posts
+  end
+
+  def valid_user?
+    valid_object?(@user, User)
+  end
+end
+```
+
+The second step, is call class method `concern` in Service class, lets use `PostDeleteService`
+
+```ruby
+class PostDeleteService < NiftyServices::BaseDeleteService
+
+  # Include shared CRUD methods to Post's CRUD Services
+  concern PostCrudExtensions
+
+  # record_type object must respond to :delete method
+  # But you can override `delete_method` method to do whatever you want
+
+  # below the code used internally, you can override to
+  # create custom delete, but remembers that this method
+  # must return a boolean value
+  def delete_record
+    @record.delete
+  end
+
+  # This method is strict required by NiftyServices, each service must implement
+  def can_delete_record?
+    # Checking user before trying to create a post for this same user
+    unless valid_user?
+      return not_found_error!('users.not_found')
+    end
+
+    return user_has_permission?
+  end
+end
+```
+
+The code is much more readable and DRY now.
+
+Now, you can share `PostCrudExtensions` will all others Post related CRUD services.
+
+### Next
+
+See [I18n Configuration](./i18n.md)