endpoint-flux 1.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0274fa91a530211dfb8293bd9663d74c67e57eab95c593b2a21187333f6f563a
+  data.tar.gz: 2ca3e41032810c54268440850141b22dff6c8ac868c134bfb85ddbd523b5474a
+SHA512:
+  metadata.gz: dc4fe82a415890d4b207dfba40193c4e600b78f96f6bf49b0146203ec3f8e9b01d2682316ae0a037f859df77c2cc11c3026ce37b5399506bbcb126f1ba4762e6
+  data.tar.gz: ba45e125f2a8508e5fc62a216af336dcc4f84bcc8afeeb57cdca4c2cce8115b9fc448614d16d16c485056a85908184c75b1add80928895d31e1b789a1df60338

data/.gitignore

@@ -0,0 +1,36 @@
+# Ignore bundler config.
+/.bundle
+
+# Ignore all logfiles and tempfiles.
+/log/*
+/tmp/*
+!/log/.keep
+!/tmp/.keep
+
+.docker-sync
+
+.rspec
+.ruby-*
+
+.DS_Store
+.idea
+.dev_secrets
+.env
+.env.test
+.vimrc
+
+# vim ignores
+# swap
+[._]*.s[a-v][a-z]
+[._]*.sw[a-p]
+[._]s[a-v][a-z]
+[._]sw[a-p]
+# session
+Session.vim
+# temporary
+.netrwhist
+*~
+# auto-generated tag files
+tags
+
+.byebug_history

data/CONTRIBUTING.md

@@ -0,0 +1,18 @@
+## Contributing
+
+While not required to contribute, we recommend [RBENV](https://github.com/rbenv/rbenv) to manage your rubies.
+
+1. Read the [Contributor Code of Conduct](https://www.contributor-covenant.org/version/1/0/0/code-of-conduct.html)
+2. [Fork it](https://help.github.com/articles/about-forks/)
+3. Clone the project `git clone git@github.com:[YOUR GITHUB USERNAME]/endpoint-flux.git`
+4. `cd endpoint-flux`
+5. Create your feature branch `git checkout -b my-new-feature`
+6. Write tests for your changes (feature/bug)
+7. Write your (feature/bugfix)
+8. Install the dependencies `bundle install`
+9. Run the tests `bundle exec rspec`
+10. Commit your changes `git commit -am 'Added some feature'`
+11. Push to the branch `git push origin my-new-feature`
+12. Create new [Pull Request](https://help.github.com/articles/creating-a-pull-request/)
+
+If we've missed something please open an [issue](https://github.com/resolving/endpoint-flux/issues/new)

data/Gemfile

@@ -0,0 +1,6 @@
+ruby '2.5.1'
+#ruby-gemset=endpoint-flux
+
+source 'https://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,37 @@
+PATH
+  remote: .
+  specs:
+    endpoint-flux (1.1.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    byebug (9.0.6)
+    diff-lcs (1.3)
+    rspec (3.5.0)
+      rspec-core (~> 3.5.0)
+      rspec-expectations (~> 3.5.0)
+      rspec-mocks (~> 3.5.0)
+    rspec-core (3.5.4)
+      rspec-support (~> 3.5.0)
+    rspec-expectations (3.5.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.5.0)
+    rspec-mocks (3.5.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.5.0)
+    rspec-support (3.5.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  byebug
+  endpoint-flux!
+  rspec
+
+RUBY VERSION
+   ruby 2.5.1p57
+
+BUNDLED WITH
+   1.16.4

data/README.md

@@ -0,0 +1,607 @@
+# EndpointFlux
+A simple way to organise API endpoints
+
+[![Gem Version](https://badge.fury.io/rb/endpoint-flux.svg)](http://badge.fury.io/rb/endpoint-flux)
+
+
+## Index
+- [Projects code organisation](#projects-code-organisation)
+- [Usage](#usage)
+  - [Installation](#installation)
+  - [Configuration](#configuration)  
+  - [Endpoints](#endpoints)  
+  - [Routing](#routing)
+  - [Controllers](#controllers)  
+  - [Middlewares](#middlewares)
+      - [Authenticator](#authenticator)
+      - [Authorizator](#authorizator)      
+      - [Policy](#policy)
+      - [Validator](#validator)
+      - [Decorator](#decorator)
+  - [Decorators](#decorators)
+  - [Validations](#validations)  
+  - [Services](#services)
+  - [Exceptions](#exceptions)
+  - [Response helpers](#response-helpers)  
+- [Contributing](CONTRIBUTING.md)
+  - [Maintainers](https://github.com/resolving/endpoint-flux/graphs/contributors)
+- [License](#license)
+
+
+## Projects code organisation
+
+EndpointFlux offers you a new file and logic organisation in Ruby applications.
+
+```
+app
+├── controllers
+│   ├── users_controller.rb
+├── endpoint_flux
+│   ├── decorators
+│   │   ├── users
+│   │   │   ├── project.rb
+│   │   ├── user.rb
+│   │   ├── ...
+│   ├── endpoints
+│   │   ├── users
+│   │       ├── create.rb
+│   │       ├── update.rb
+│   │       ├── ...
+│   ├── middlewares
+│   │   ├── authenticator
+│   │   │   ├── default.rb
+│   │   ├── authorizator
+│   │   │   ├── default.rb
+│   │   ├── decorator
+│   │   │   ├── paginate.rb
+│   │   │   ├── representable.rb
+│   │   │   ├── ...
+│   │   ├── policy
+│   │   │   ├── comment.rb
+│   │   │   ├── ...
+│   │   ├── validator
+│   │       ├── inline.rb
+│   ├── services
+│   │   ├── auth.rb
+│   │   ├── ...
+│   ├── validations
+│   │   ├── predicates
+│   │   │   ├── base.rb
+│   │   │   ├── date.rb
+│   │   │   ├── ...
+│   │   ├── base.rb
+│   │   ├── error.rb
+│   │   ├── user.rb
+```
+
+
+## Usage
+
+### Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'endpoint-flux'
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install endpoint-flux
+```
+
+
+### Configuration
+
+You can initialize the EndpointFlux before using and can specify a bunch of params as you need. Locate it in 
+`config/initializers/endpoint_flux.rb`.
+
+With the `EndpointFlux.config.middlewares_namespaces` directive you can specify the location of middleware. 
+```ruby
+EndpointFlux.config.middlewares_namespaces << 'middlewares'
+```
+
+To specify the default middleware that will be used for each response, if nothing specified in Endpoint class, use 
+`EndpointFlux.config.default_middlewares` directive. For example:
+```ruby
+EndpointFlux.config.default_middlewares :validator, :inline
+```
+Where `:validator` is a middleware and `:inline` is a class that defined in 
+`app/endpoint_flux/middlewares/validator/inline.rb`. More details [here](#validator).
+
+With `EndpointFlux.config.rescue_from` you can specify how to handle the custom exceptions that would be raised in 
+Application. For example: 
+ ```ruby
+not_found_errors = [ActiveRecord::RecordNotFound]
+EndpointFlux.config.rescue_from(not_found_errors) do |_, attrs, _|
+  attrs[1].body = EndpointFlux::Exceptions::NotFound.new.to_hash
+  attrs
+end
+ ```
+
+Also you can specify interceptor that would be called before processing each response
+```ruby
+EndpointFlux.config.interceptor do |attrs|
+  Rails.root.join('maintenance.txt').exist? &&
+    raise(EndpointFlux::Exceptions::ServiceUnavailable)
+
+  attrs
+end 
+```
+
+And if you need you can define your own methods like this:
+```ruby
+EndpointFlux::Endpoint.class_eval do
+  define_method(:raise_validation_error) do |errors|
+    raise EndpointFlux::Exceptions::Validation, errors
+  end
+end
+```
+
+Config example:
+```ruby
+# config/initializers/endpoint_flux.rb
+require 'endpoint_flux'
+
+EndpointFlux.config.middlewares_namespaces << 'middlewares'
+
+EndpointFlux.config.default_middlewares :authenticator, :default
+EndpointFlux.config.default_middlewares :authorizator, :default
+EndpointFlux.config.default_middlewares :validator, :inline
+EndpointFlux.config.default_middlewares :policy,    :skip
+EndpointFlux.config.default_middlewares :decorator, :skip
+
+not_found_errors = [ActiveRecord::RecordNotFound]
+EndpointFlux.config.rescue_from(not_found_errors) do |_, attrs, _|
+  attrs[1].body = EndpointFlux::Exceptions::NotFound.new.to_hash
+  attrs
+end
+
+EndpointFlux.config.interceptor do |attrs|
+  Rails.root.join('maintenance.txt').exist? &&
+    raise(EndpointFlux::Exceptions::ServiceUnavailable)
+
+  attrs
+end
+
+EndpointFlux::Endpoint.class_eval do
+  define_method(:raise_validation_error) do |errors|
+    raise EndpointFlux::Exceptions::Validation, errors
+  end
+end
+```
+
+### Routing
+
+EndpointFlux has Rails helper - 
+[`present`](https://github.com/resolving/endpoint-flux/blob/master/lib/endpoint_flux/rails/concerns/endpoint_controller.rb), 
+which integrates with Rails controllers. So, you can use the default Rails routing system to define routes.
+
+```ruby
+Rails.application.routes.draw do
+  resources :users
+end
+```
+
+```ruby
+class UsersController < ApplicationController
+  def index
+    present 'users/index' # it dispatches to Endpoints::Users::Index endpoint class.
+  end  
+end
+```
+
+Or if you're using it in not Rails application, you can implement the middleware for providing
+such data to Endpoints namespace, for example:
+
+```ruby
+class BaseHandler
+  def process(msg, options, namespace)
+    params   = JSON.parse(msg)
+    action   = options[:headers]['action']
+    endpoint = endpoint_for("#{namespace}/#{action}")
+
+    _, response = endpoint.perform(request_object(params))
+
+    response.body
+  end
+  
+  private
+
+  def endpoint_for(namespace)
+    if ::EndpointFlux.config.endpoints_namespace
+      ::EndpointFlux.config.endpoints_namespace + '/' + namespace
+    else
+      namespace
+    end.camelize.constantize
+  end
+
+  def request_object(params)
+    ::EndpointFlux::Request.new(headers: {}, params: params.to_h.deep_symbolize_keys!)
+  end
+end
+```
+
+
+### Controllers
+
+Controllers are simple endpoints for HTTP. They don't have any business logic and just dispatch to an endpoint class.
+
+```ruby
+class UsersController < ApplicationController
+  def index
+    present 'users/index' # it dispatches to Endpoints::Users::Index endpoint class.
+  end  
+end
+```
+Finally `present` method renders `response.body` in JSON format (`render json: response.body`).  
+ 
+
+### Endpoints
+
+Endpoints encapsulate business logic and it's a central part of applications architecture. It can be used in any Ruby 
+application like Rails, Sinatra and etc. 
+It's a simple coordinator between all layers needed to get the job done. Endpoint needs for defining and implementing 
+steps for the processing data for response. It uses middlewares for data processing that receives the arguments from 
+the caller and returns the array `[request, response]` with `response` that contains `body` and `headers` for API.
+
+```ruby
+# app/endpoint_flux/endpoints/users/comments/index.rb
+module Endpoints
+  module Users
+    module Comments
+      module Index
+        include EndpointFlux::Endpoint
+
+        policy :user
+        policy :comments
+
+        validator :inline do
+          required(:user_id).value(:number?)
+        end
+
+        process do |request, response|
+          response.body[:comments] = request.scope
+
+          [request, response]
+        end
+
+        decorator :add_status, 200        
+        decorator :representable, decorator: :comment, collection?: true, wrapped_in: :comments
+      end
+    end
+  end
+end
+```
+
+
+
+### Middlewares
+
+EndpointFlux has 6 types of predefined middlewares. They will be called in the strong defined order - `authenticator, 
+authorizator, validator, policy, process, decorator`. Where `process` should be defined inside the endpoint class for 
+the request processing.
+
+Also you can add your own middleware class to this flow or change the order. It's possible in two ways: 
+
+* Inside the custom endpoint class, for example:  
+```ruby
+# app/endpoint_flux/endpoints/users/index.rb
+
+module Endpoints
+  module Users
+    module Index
+      include EndpointFlux::Endpoint
+      # define new flow with `new_middleware` only for this endpoint
+      flow %i[authenticator authorizator validator policy process new_middleware decorator]
+      
+      authorizator :skip
+      #...
+      process do |request, response|
+      # ... some actions
+        [request, response]
+      end
+      
+      # define the middleware
+      new_middleware :default 
+      
+      decorator :add_status, 200
+    end
+  end
+end      
+```
+
+* Globally in EndpointFlux config section that will affect all endpoints, for example:
+```ruby
+# config/initializers/endpoint_flux.rb
+# ...
+# define default value for new middleware
+EndpointFlux.config.default_middlewares :new_middleware, :default 
+# Global change the middlewares order flow by adding a new one `new_middleware`
+EndpointFlux.config.flow(%i[authenticator authorizator validator policy process new_middleware decorator]) 
+```
+
+Middleware class definition should contains `self.perform(*args)` method and returns the `[request, response]` as a result
+```ruby
+# app/endpoint_flux/middlewares/new_middleware/default.rb
+module Middlewares
+  module NewMiddleware
+    module Default
+      def self.perform(request, response, _)
+        # ... some actions
+        [request, response]
+      end
+    end
+  end
+end
+```
+
+We have implemented the default middlewares that could be used to skip it without any changes to data. It's located 
+[here](https://github.com/resolving/endpoint-flux/tree/master/lib/endpoint_flux/middlewares)
+ 
+
+#### Authenticator
+
+Here you can implement your authenticate system. For example you can user the [JWT gem](https://github.com/jwt/ruby-jwt)
+Locate it in `app/endpoint_flux/middlewares/authenticator` folder.
+Also you can skip this middleware in Endpoint class by `authenticator :skip` directive
+
+
+#### Authorizator
+
+Here you can implement your authorization system and check the user permissions according to the user role.
+Locate it in `app/endpoint_flux/middlewares/authorizator` folder.
+Also you can skip this middleware in the Endpoint class by `authorizator :skip` directive
+
+
+
+#### Policy
+
+Here you implement different policy scopes and use them inside the Endpoint class. And also you can chain it to each other by
+calling in special order. Locate it in `app/endpoint_flux/middlewares/policy` folder.
+
+For example: 
+* User policy 
+```ruby
+# app/endpoint_flux/middlewares/policy/user.rb
+module Middlewares
+  module Policy
+    module User
+      def self.perform(request, response, _)
+        request.scope = ::User.find(request.params[:user_id])
+
+        [request, response]
+      end
+    end
+  end
+end
+```
+
+* Comments policy 
+```ruby
+# app/endpoint_flux/middlewares/policy/comments.rb
+module Middlewares
+  module Policy
+    module Comments
+      def self.perform(request, response, _)
+        raise 'scope must be set' unless request.scope
+        raise 'scope must be User' unless request.scope.class.name == 'User'
+
+        request.scope = ::Comment.where(user_id: request.scope.id)
+
+        [request, response]
+      end
+    end
+  end
+end
+```
+
+And usage inside the Endpoint class:
+```ruby
+# app/endpoint_flux/endpoints/users/comments/index.rb
+module Endpoints
+  module Users
+    module Comments
+      module Index
+        include EndpointFlux::Endpoint
+
+        policy :user  # get user scope
+        policy :comments # get users comments scope
+
+        validator :inline do
+          required(:user_id).value(:number?)
+        end
+
+        process do |request, response|
+          response.body[:comments] = request.scope
+
+          [request, response]
+        end
+
+        decorator :add_status, 200        
+        decorator :representable, decorator: :comment, collection?: true, wrapped_in: :comments
+      end
+    end
+  end
+end
+```
+
+
+#### Validator
+
+Here you can implement validation system for request params using the [Dry validation gem](http://dry-rb.org/gems/dry-validation)
+or another libraries. Locate it in `app/endpoint_flux/middlewares/validator` folder.
+Also you can skip this middleware in the Endpoint class by `validator :empty` directive
+
+```ruby
+# app/endpoint_flux/middlewares/validator/inline.rb
+module Middlewares
+  module Validator
+    module Inline
+      def self.perform(request, response, _options, &block)
+        validation = ::Services::Validation(&block).call(request.params)
+        unless validation.success?
+          raise ::EndpointFlux::Exceptions::Validation, validation.messages
+        end
+        request.params = validation.result
+
+        [request, response]
+      end
+    end
+  end
+end
+```
+
+Just declare the schema block inside the endpoint to provide it to middleware 
+```ruby
+# app/endpoint_flux/endpoints/users/create.rb
+module Endpoints
+  module Users
+    module Create      
+      include EndpointFlux::Endpoint
+
+      authenticator :skip
+      authorizator :skip
+      
+      validator :inline do
+        required(:user).schema do
+          required(:email).value(:str?, :email?)
+          required(:password).value(:str?, :password?)
+        end        
+      end
+
+      process do |request, response|
+        # some actions ... like calling checking for user uniqueness, Mailer Sidekiq workers, token generation and etc.
+  
+        response.body[:user] = ::User.create(request.params[:user])
+        
+        # ...
+
+        [request, response]
+      end
+
+      decorator :add_status, 200        
+      decorator :representable, decorator: :user      
+    end
+  end
+end
+```
+
+
+#### Decorator
+
+Here you can implement a decorator system for representing the response.
+Locate it in `app/endpoint_flux/middlewares/decorator` folder. You can call it inside the endpoint class by using 
+directive like this `decorator :representable, decorator: :user`, where `:representable` it's your decorators class name 
+and `decorator: :user` it's a custom params as you wish (in this situation specialising to use User decorator for 
+representing data).  
+For example 
+
+```ruby
+# app/endpoint_flux/middlewares/decorator/representable.rb
+module Middlewares
+  module Decorator
+    module Representable
+      def self.perform(request, response, options)
+        resource_name = options[:decorator]
+        resource      = response.body[resource_name]
+
+        response.body[resource_name] = ::Services::Decorator.call(resource, options) if resource
+
+        [request, response]
+      end
+    end
+  end
+end      
+```
+
+You can add a custom status to the response body by using directive `decorator :add_status, {status_number}`, 
+for example `decorator :add_status, 200`.
+Also you can skip this middleware in the Endpoint class by `decorator :skip` directive
+
+
+
+### Decorators
+
+Endpoint can use representers from `app/endpoint_flux/decorators` to serialize and parse JSON and XML documents for APIs.
+For example you can use 
+[Representable gem](http://trailblazer.to/gems/representable), it maps representation documents from and to Ruby objects
+and includes JSON, XML and YAML support, plain properties and compositions.
+You can define the decorator schema class in `app/endpoint_flux/decorators` folder and specify it inside of the 
+endpoint class by providing as params for `decorator` directive, 
+for example  `decorator :representable, decorator: :user`
+
+```ruby
+# app/endpoint_flux/decorators/user.rb
+module Decorators
+  class User < Representable::Decorator
+    include Representable::JSON
+
+    property :id
+    property :name
+    property :email    
+    property :role, exec_context: :decorator   
+    
+    property :updated_at
+    property :created_at
+
+    def role
+      represented.role.name
+    end
+  end
+end    
+```
+
+
+### Validations
+
+In `app/endpoint_flux/validations` you can locate a custom validation classes and use them with Validator middleware.
+
+
+### Services
+
+You can move some business logic from endpoints to service object and locate it here `app/endpoint_flux/services`.
+
+
+### Exceptions
+
+You can use EndpointFlux predefined Exceptions for you business logic, for example 
+`raise ::EndpointFlux::Exceptions::Validation`.
+They defined in 
+[lib/endpoint_flux/exceptions](https://github.com/resolving/endpoint-flux/tree/master/lib/endpoint_flux/exceptions)
+
+The list of exceptions:
+* `Forbidden`
+* `NotFound`
+* `ServiceUnavailable`
+* `Unauthorized`
+* `Validation`
+
+
+### Response helpers
+
+If needs you can use the response helpers to check the response body status such as `success?`, `invalid?` or 
+you can define your own helpers in that way. You can use it with an instance of the `EndpointFlux::Response` class.
+They defined in 
+[lib/endpoint_flux/response.rb](https://github.com/resolving/endpoint-flux/blob/master/lib/endpoint_flux/response.rb)
+
+The list of helpers:
+* `success?`
+* `invalid?`
+* `forbidden?`
+* `unauthorized?`
+* `not_found?`
+
+
+## [Contributing](CONTRIBUTING.md)
+
+### [Maintainers](https://github.com/resolving/endpoint-flux/graphs/contributors)
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).