rapid_api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 85d057310dcd01fbb26108d9496df7aa2b2bf668
+  data.tar.gz: 52a2e15349493659e8c90f9e36fd9af0732682c1
+SHA512:
+  metadata.gz: 5d6d87ab91566e286945631ff759c7f7ca1cb22877e4f6a1c983a525c1d9bd2e6ceaff5af124c8d27e07bb2f98f53494b211d7be230c610180962a7ba2afe9dd
+  data.tar.gz: 154d0b89aa34045576b14ee5b3bfe1dda5ce7d4ea497dcd9cd0bdd320895501e881872077b8d7d448860a98fb18fac4844d7adc864f4ada421356ee07b444dba

data/README.md

@@ -0,0 +1,120 @@
+# rAPId [![Code Climate](https://codeclimate.com/github/briandavidwetzel/rapid_api/badges/gpa.svg)](https://codeclimate.com/github/briandavidwetzel/rapid_api) [![Build Status](https://travis-ci.org/briandavidwetzel/rapid_api.svg)](https://travis-ci.org/briandavidwetzel/rapid_api) [![Test Coverage](https://codeclimate.com/github/briandavidwetzel/rapid_api/badges/coverage.svg)](https://codeclimate.com/github/briandavidwetzel/rapid_api/coverage)
+
+*NOT PRODUCTION READY*
+
+__A framework for rapid development of Rails APIs__-- *RapidApi* aims to reduce code maintenance and testing costs, while increasing speed of development. Because the ceremony of rendering REST actions is performed for you, you can focus more time on what makes your app unique.
+
+## Installation
+Include in your Gemfile:
+
+```ruby
+gem 'rapid_api', git: 'git://github.com/briandavidwetzel/rapid_api.git'
+```
+
+## Documentation
+### Rapid Actions
+Including `rapid_actions` in your controller will give you conventional RESTful actions: `#index, #show, #create, #update, and #destroy`.
+```ruby
+class BricksController < ApplicationController
+  rapid_actions
+
+  permit_params     :color, :weight, :material
+  filterable_params :color
+end
+```
+#### Permitted Params
+The `permit_params` macro secures member requests using strong params.  Just pass the attributes that you want to be used in creation or update of your model.
+
+#### Filterable Params
+The `filterable_params` macro is similar `permit_params`, except that it applies to the collection instead of the member. RapidApi supports basic filtering on the index action.  A hash of keys and values will be passed to the model adapter secured via strong params.
+
+#### Error Handling
+Error handling is provided automatically for the generated actions. There are currently three potential errors that can be raised and are rendered:
+* __NotFoundError__ (`:not_found`) - obviously, when a member is not found to be shown, updated, or destroyed.
+* __NotProcessableError__ (`:unprocessable_entity`) - this will be rendered when a member has errors added during the create or update process.
+  * *NOTE: For ActiveRecord, this pattern emphasizes using errors.add over raising exceptions.  Also, for AMS, this convention works well with Ember Data's ActiveModelAdapter errors object out of the box.*
+* __StandardError__ (`:internal_server_error`) - Everything else gets caught as an internal server error. The error message is serialized in the json response body.
+
+#### Configuration
+By default, RapidApi will attempt to use ActiveRecord, ActiveModelSerializer and the Rails naming conventions to discover your model and serializer per controller, but you are able to customize the definition. You can pass optional arguments to the `rapid_actions` macro as follows.
+```ruby
+rapid_actions model: YourModel, serializer: YourSerializer, model_adapter: CustomModelAdapter, serializer_adapter: CustomSerializerAdapter
+```
+These settings could also be set globally using the configuration object. For example,
+```ruby
+RapidApi.config.model_adapter      = CustomModelAdapter
+RapidApi.config.serializer_adapter = CustomSerializerAdapter
+```
+You can also override the response codes, if necessary.
+```ruby
+RapidApi.config.response_codes[:created] = :ok
+```
+
+### Scoping
+If you want to scope your controller by a given attribute or attributes, you can use the `scope_by` macro
+```ruby
+class BricksController < ApplicationController
+  rapid_actions
+
+  permit_params     :color, :weight, :material
+  filterable_params :color
+
+  scope_by :user_id do |controller|
+    controller.authenticated.id
+  end
+end
+```
+The scope by block should return the corresponding value for the attribute(s), passed to `scope_by`. In the event that there are multiple scoping attributes, you should return an array of values in the block. The scope will apply to all generated actions.
+
+### Authentication
+*NOTE: The authentication functionality is likely to be moved to another gem by the release of v1*
+
+Some basic API appropriate authentication is available in the form [json web tokens](http://jwt.io). However, you can use RapidApi without taking advantage of this functionality.
+
+#### The Sessions Controller
+```ruby
+class SessionsController < ApplicationController
+  rapid_sessions_controller
+
+  authenticates_with :username, :password do |params|
+    User.where(username: params[:username], password: params[:password]).first
+  end
+
+  responds_with do |authenticated|
+    {
+      token: jwt_encode({ secret: 'foo' }),
+      user: {
+        id:       authenticated.id,
+        username: authenticated.username
+      }
+    }
+  end
+end
+```
+
+`rapid_sessions_controller` will generate an authenticate method, that can be called to initiate a session with your api. The `authenticates_with` macro accepts the parameters that will be used to authenticate, and a block that will do the actual authentication. The block should return the authenticated object. *In the example given, the authenticated User.* Returning nil, well render an `:unauthorized` response. Otherwise, `responds_with` is passed the authenticated object to build the auth token payload for the authentication response.
+
+#### Authenticated Controllers
+```ruby
+class ApplicationController
+  rapid_base_controller
+
+  authenticate do |controller|
+    token = controller.decode_jwt_token!(controller.request.headers.env['Authorization'])
+    user_id = token[0].try :[], 'user_id'
+    if user_id.present?
+      User.find user_id
+    else
+      nil
+    end
+  end
+end
+```
+`rapid_base_controller` can be added to the base class for your api controllers to provide a before_filter that checks authentication. Note if your SessionController is derived from the same base class, then you should add `skip_before_filter :authenticate!` to your SessionsController.  The `authenticate` macro should be passed a block that returns the authenticated object. *In the example, the 'Authorization' token is parsed to return the current user*. If your authenticate block returns nil, then `:unauthorized` will be rendered.
+
+Also note that the `decode_jwt_token!` can raise errors that will result in the rendering of an `:unauthorized` response.
+
+### Extending RapidApi
+If you don't want to use ActiveRecord or ActiveModelSerializer, that is OK. You can create your own adapters.
+
+There are two abstract classes that can be used as base classes for your own implementation: `RapidApi::ModelAdapters::Abstract` and `RapidApi::SerializerAdapters::Abstract`. See the implemented adapters and tests for examples on how to implement an adapter.  Post an issue if you get stuck.

data/lib/rapid_api/action_controller/errors.rb

@@ -0,0 +1,75 @@
+module RapidApi
+  module ActionController
+
+    module Errors
+      extend ActiveSupport::Concern
+
+      NotAuthenticatedError = Class.new StandardError
+      NotFoundError         = Class.new StandardError
+
+      class NotProcessableError < StandardError
+        attr_accessor :errors
+
+        def initialize(errors)
+          @errors = errors
+        end
+
+      end
+
+      included do
+        rescue_from StandardError,         with: :_server_error
+        rescue_from NotAuthenticatedError, with: :_not_authenticated
+        rescue_from NotFoundError,         with: :_not_found
+        rescue_from NotProcessableError,   with: :_not_processable
+      end
+
+      def not_authenticated!
+        raise NotAuthenticatedError
+      end
+
+      def not_found!
+        raise NotFoundError
+      end
+
+      def not_processable!(errors)
+        raise NotProcessableError.new(errors)
+      end
+
+      protected
+
+      def render_error_message(message, status, e)
+        render json: { errors: [message] }, status: response_code_for(status)
+      end
+
+      def response_code_for(status)
+        RapidApi.config.response_codes[status]
+      end
+
+      def log_error(e)
+        puts e.message
+        e.backtrace.map { |m| puts m }
+      end
+
+      def _not_authenticated(e)
+        render_error_message 'Not Authenticated', :unauthorized, e
+      end
+
+      def _not_found(e)
+        render_error_message 'Not Found', :not_found, e
+      end
+
+      def _not_processable(e)
+        render json: { errors: e.errors }, status: response_code_for(:unprocessable_entity)
+      end
+
+      def _server_error(e)
+        render_error_message "Server Error: #{e.message}", :internal_server_error, e
+      end
+
+      module ClassMethods
+
+      end
+    end
+
+  end
+end

data/lib/rapid_api/action_controller/filterable_params.rb

@@ -0,0 +1,29 @@
+module RapidApi
+  module ActionController
+
+    module FilterableParams
+      extend ActiveSupport::Concern
+
+      included do
+
+      end
+
+      def filterable_params
+        params.permit(self.class.permitted_filterable_params)
+      end
+
+      module ClassMethods
+        attr_accessor :permitted_filterable_params
+
+        def permitted_filterable_params
+          @filterable_params ||= []
+        end
+
+        def filterable_params(*params)
+          [*params].each { |p| self.permitted_filterable_params << p }
+        end
+      end
+    end
+
+  end
+end

data/lib/rapid_api/action_controller/macros.rb

@@ -0,0 +1,28 @@
+module RapidApi
+  module ActionController
+    module Macros
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        def rapid_actions(options={})
+          include RapidApi::ActionController::RestActions
+          self.model              = options[:model]              if options[:model]
+          self.serializer         = options[:serializer]         if options[:serializer]
+          self.model_adapter      = options[:model_adapter]      if options[:model_adapter]
+          self.serializer_adapter = options[:serializer_adapter] if options[:serializer_adapter]
+        end
+
+        def rapid_sessions_controller
+          include RapidApi::ActionController::Errors
+          include RapidApi::Auth::Concerns::SessionsController
+        end
+
+        def rapid_base_controller
+          include RapidApi::ActionController::Errors
+          include RapidApi::Auth::Concerns::AuthenticatedController
+        end
+      end
+
+    end
+  end
+end

data/lib/rapid_api/action_controller/permitted_params.rb

@@ -0,0 +1,38 @@
+module RapidApi
+  module ActionController
+
+    module PermittedParams
+      extend ActiveSupport::Concern
+
+      included do
+
+      end
+
+      def permitted_params
+        self.class.permitted_params
+      end
+
+      private
+
+      def _permitted_params_for(key)
+        params.require(key).permit(*permitted_params)
+      end
+
+
+      module ClassMethods
+
+        def permit_params(*params)
+          @permitted_params ||= []
+          @permitted_params += params
+          @permitted_params.uniq!
+        end
+
+        def permitted_params
+          @permitted_params
+        end
+
+      end
+    end
+
+  end
+end

data/lib/rapid_api/action_controller/rest_actions.rb

@@ -0,0 +1,158 @@
+module RapidApi
+  module ActionController
+
+    module RestActions
+      extend ActiveSupport::Concern
+      include PermittedParams
+      include FilterableParams
+      include Errors
+      include Scope
+
+      included do
+        self.serializer_adapter = RapidApi.config.serializer_adapter
+        self.model_adapter      = RapidApi.config.model_adapter
+      end
+
+      def index
+        query_result = _adapted_model.find_all filterable_params, scope
+        render json: _adapted_serializer.serialize_collection(query_result.data), status: response_code_for(:ok)
+      end
+
+      def show
+        query_result = _adapted_model.find params[:id], scope
+        if query_result.found?
+          render json: _adapted_serializer.serialize(query_result.data) , status: response_code_for(:ok)
+        else
+          not_found!
+        end
+      end
+
+      def create
+        query_result = _adapted_model.create _member_params, scope
+        if query_result.has_errors?
+          not_processable! query_result.errors
+        else
+          render json: _adapted_serializer.serialize(query_result.data), status: response_code_for(:created)
+        end
+      end
+
+      def update
+        query_result = _adapted_model.update params[:id], _member_params, scope
+        if query_result.found?
+          if query_result.has_errors?
+            not_processable! query_result.errors
+          else
+            render json: _adapted_serializer.serialize(query_result.data), status: response_code_for(:ok)
+          end
+        else
+          not_found!
+        end
+      end
+
+      def destroy
+        query_result = _adapted_model.destroy params[:id], scope
+        if query_result.has_errors?
+          not_processable! query_result.errors
+        else
+          head :no_content
+        end
+      end
+
+      private
+
+      def _adapted_model
+        self.class.adapted_model
+      end
+
+      def _adapted_serializer
+        self.class.adapted_serializer
+      end
+
+      def _member_params
+        _permitted_params_for(_params_key)
+      end
+
+      def _model
+        self.class.model
+      end
+
+      def _params_key
+        self.class.params_key
+      end
+
+      module ClassMethods
+
+        attr_accessor :model_class_name,
+                      :model,
+                      :model_adapter,
+                      :adapted_model,
+                      :params_key,
+                      :serializer,
+                      :serializer_adapter,
+                      :adapted_serializer
+
+        def model_class_name
+          @model_class_name ||= controller_name.classify.singularize
+        end
+
+        def model
+          @model ||= begin
+                      model_class_name.constantize
+                     rescue NameError
+                     end
+        end
+
+        def model=(model)
+          @model = model
+          _reset_params_key
+          _initialize_model_adapter
+          @model
+        end
+
+        def serializer
+          #TODO: BDW - This convention is too dependent on AMS. This should be
+          # decoupled in some way.
+          @serializer ||=  begin
+                             "#{model_class_name}Serializer".constantize
+                           rescue NameError
+                           end
+        end
+
+        def serializer=(serializer)
+          @serializer = serializer
+          _initalize_serializer_adaper
+          @serializer
+        end
+
+        def params_key
+          @params_key ||= model.to_s.underscore
+        end
+
+        def model_adapter=(adapter)
+          @model_adapter = adapter
+          _initialize_model_adapter
+        end
+
+        def serializer_adapter=(adapter)
+          @serializer_adapter = adapter
+          _initalize_serializer_adaper
+        end
+
+        private
+
+        def _initalize_serializer_adaper
+          self.adapted_serializer = @serializer_adapter.new(serializer, params_key)
+        end
+
+        def _initialize_model_adapter
+          self.adapted_model = @model_adapter.new(model)
+        end
+
+        def _reset_params_key
+          @params_key = model.to_s.underscore
+        end
+      end
+    end
+
+  end
+end

data/lib/rapid_api/action_controller/scope.rb

@@ -0,0 +1,44 @@
+module RapidApi
+  module ActionController
+
+    module Scope
+      extend ActiveSupport::Concern
+
+      attr_accessor :scope
+
+      included do
+        before_filter :define_scope
+      end
+
+      def scope
+        @scope ||= {}
+      end
+
+      protected
+
+      def define_scope
+        return unless self.class.scope_by_proc.present?
+        scope_by = self.class.scope_by_proc.call(self)
+        scope_by_array = [*scope_by]
+        self.class.scope_params.each_with_index do |key, index|
+          scope[key] = scope_by_array[index]
+        end
+      end
+
+
+      module ClassMethods
+        attr_accessor :scope_by_proc, :scope_params
+
+        def scope_params
+          @scope_params ||= []
+        end
+
+        def scope_by(*params, &block)
+          self.scope_by_proc = Proc.new { |p| block.call(p) }
+          [*params].each { |p| self.scope_params << p }
+        end
+      end
+    end
+
+  end
+end

data/lib/rapid_api/action_controller.rb

@@ -0,0 +1,11 @@
+require 'rapid_api/action_controller/permitted_params'
+require 'rapid_api/action_controller/errors'
+require 'rapid_api/action_controller/scope'
+require 'rapid_api/action_controller/filterable_params'
+require 'rapid_api/action_controller/rest_actions'
+require 'rapid_api/action_controller/macros'
+
+module RapidApi
+  module ActionController
+  end
+end

data/lib/rapid_api/auth/concerns/authenticated_controller.rb

@@ -0,0 +1,54 @@
+module RapidApi
+  module Auth
+    module Concerns
+
+      module AuthenticatedController
+        extend ActiveSupport::Concern
+
+        included do
+          before_filter :authenticate!
+
+          attr_accessor :authenticated
+        end
+
+        def authenticate!
+          self.extend JWTHelpers
+          self.extend AuthenticationHelpers
+          self.authenticated = self.class.authenticate_proc.call(self)
+          not_authenticated! if authenticated.nil?
+        end
+
+        protected
+
+        module ClassMethods
+          attr_accessor :authenticate_proc
+
+          def authenticate(&block)
+            self.authenticate_proc = Proc.new { |request| block.call(request) }
+          end
+
+          def inherited(child)
+            child.authenticate_proc = authenticate_proc
+          end
+
+        end
+
+        module AuthenticationHelpers
+
+          def decode_jwt_token!(token)
+            begin
+              jwt_decode(token)
+            rescue JWT::ExpiredSignature
+              not_authenticated!
+            rescue JWT::VerificationError, JWT::DecodeError
+              not_authenticated!
+            end
+          end
+
+        end
+
+      end
+
+    end
+  end
+end

data/lib/rapid_api/auth/concerns/jwt_helpers.rb

@@ -0,0 +1,33 @@
+module RapidApi
+  module Auth
+    module Concerns
+
+      module JWTHelpers
+        extend ActiveSupport::Concern
+
+        included do
+
+        end
+
+        def jwt_encode(payload)
+          Support::JWT.encode(payload)
+        end
+
+        def jwt_decode(token)
+          Support::JWT.decode(token)
+        end
+
+        module ClassMethods
+          def jwt_encode(payload)
+            Support::JWT.encode(payload)
+          end
+
+          def jwt_decode(token)
+            Support::JWT.decode(token)
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/rapid_api/auth/concerns/sessions_controller.rb

@@ -0,0 +1,49 @@
+module RapidApi
+  module Auth
+    module Concerns
+
+      module SessionsController
+        extend ActiveSupport::Concern
+        include JWTHelpers
+
+        included do
+          skip_before_filter :authenticate!
+        end
+
+        def authenticate
+          authenticated = self.class.auth_proc.call(permitted_auth_params)
+          if authenticated.present?
+            render json:   self.class.responds_with_proc.call(authenticated),
+                   status: :ok
+          else
+            render json: { errors: ['Invalid credentials'] }, status: :unauthorized
+          end
+        end
+
+        protected
+
+        def permitted_auth_params
+          params.permit(*self.class.auth_params)
+        end
+
+        module ClassMethods
+          attr_accessor :auth_params, :auth_proc, :responds_with_proc
+
+          def auth_params
+            @auth_params ||= []
+          end
+
+          def authenticates_with(*params, &block)
+            self.auth_proc = Proc.new { |params| block.call(params) }
+            [*params].each { |p| self.auth_params << p }
+          end
+
+          def responds_with(&block)
+            self.responds_with_proc = Proc.new { |authenticated| block.call(authenticated) }
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/rapid_api/auth/concerns.rb

@@ -0,0 +1,11 @@
+require 'rapid_api/auth/concerns/jwt_helpers'
+require 'rapid_api/auth/concerns/authenticated_controller'
+require 'rapid_api/auth/concerns/sessions_controller'
+
+module RapidApi
+  module Auth
+    module Concerns
+
+    end
+  end
+end

data/lib/rapid_api/auth/support/jwt.rb

@@ -0,0 +1,28 @@
+require 'jwt'
+
+module RapidApi
+  module Auth
+    module Support
+
+      class JWT
+
+        def self.encode(payload={}, ttl=3600)
+          if ttl.present?
+            payload[:exp] = Time.current.to_i + ttl
+          end
+          encrypt_key = nil; #TODO: Make this configurable
+          encrypt_alg = 'none'
+
+          ::JWT.encode payload, encrypt_key, encrypt_alg
+        end
+
+        def self.decode(token)
+          decrypt_key = nil;
+          ::JWT.decode token, decrypt_key, false
+        end
+
+      end
+
+    end
+  end
+end