api_engine_base 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 237d043d261233c9e45d4b7466dcacbfb4792636246fa2e211e765ee21b75141
-  data.tar.gz: 55d598e1abaf7a12a253fbc9ea8d010c9a11ac9ca5ea293e2a30f6cb42ffc759
+  metadata.gz: d10e7cc64ff7f99aa912731ce7200ebfbff18e90b0cc05b948a8f6034d15e54f
+  data.tar.gz: 07baec4ba6dc487ab145d68e87e489181153550b3e22f1db594d56e1fcc86e3d
 SHA512:
-  metadata.gz: 53180702bea719474e8f9922858da3c1af7b6c44ce3ad1db78bb5c633c039b9b5bb7a524984a637e41dd16499478f896731f033a8c8beece0441eff76ac40fa9
-  data.tar.gz: '03397ea3efb5e7a68554ae600d4eda0d0f467d2990a14dbb4e1bf2ea2cd13a96e82abd679894e2943c51e097eab095c10434116303c1004404626d84d2805c5a'
+  metadata.gz: 93d925277dac2e33eff40c8f3e4669f4ea162051ca6f9ec0d9d66791ed9e937384262fd983a04d4895c7891d1ec763d41f092a3242c4e685f9237f6b8af463ba
+  data.tar.gz: 7e7bd57ff6c8a991fe251c6afb01d4d3a8900a002973dc8c661313fd94ceac1f81e17f7dc80ec96f175bc110f4c0ec74638c75b9eb32b4a871815dff2c20e21f

data/README.md

@@ -1,8 +1,7 @@
 # ApiEngineBase
-Short description and motivation.
+This is an API only base engine to build on top of. This Engine takes care of all Authentication, Token Refresh, and RBAC Roles so that you do not have to! For all applications, you can get right to work on implementing the code directly related to your project rather than dealing with the administrative overhead.
 
-## Usage
-How to use my plugin.
+While this gem is heavily opinionated, everything can be configured to your liking.
 
 ## Installation
 Add this line to your application's Gemfile:
@@ -21,8 +20,40 @@ Or install it yourself as:
 $ gem install api_engine_base
 ```
 
-## Contributing
-Contribution directions go here.
+## Initializing ApiEngineBase
+Please follow all steps in [Initializing ApiEngineBase](docs/initializing.md)
+
+
+## Available Routes
+
+For more info, check out [Controllers ReadMe](docs/controllers.md)
+
+Additionally, You can check out [RSpec Integration Testing](/spec/integration_test)
+
+## Available Models
+
+ApiEngineBase provides several Models at the in the root namespace. Core Models like `User` and `UserSecret` are readily available. Don't forget! You can add additional methods to these classes by opening them back up.
+
+For more info, check out [Models ReadMe](doc/models.md)
+
+## Authentication (JWT BearerToken)
+Authentication ensures that we know which user is requesting the action. When the Engine is unable to authenticate, a `401` status code is returned.
+
+For more info, check out [Authentication ReadMe](docs/authentication.md)
+
+## Authorization (RBAC)
+Authorization is only done after authentication. This is the act of ensuring that the user can perform the action it is requesting. Put differently, I know who you are, but I need to validate you have permissions to complete the action. When the engine is unable to authorize the user, a `403` status code is returned.
+
+For more info, check out [Authentication ReadMe](docs/authorization.md)
+
+## Sensitive Changes
+
+For more info, check out [Sensitive Routes](docs/sensitive_routes.md)
+
+## ServiceBase
+ServiceBase is built on top of Interactor. The ServiceBase is the heart of all logic for ApiEngineBase. It includes Logging and enhanced ArgumentValidation that can directly return back to the API request.
+
+For more info, check out [ServiceBase ReadMe](app/services/api_engine_base/README.md)
 
 ## License
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The engine is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/controllers/api_engine_base/admin_controller.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module ApiEngineBase
+  class AdminController < ::ApiEngineBase::ApplicationController
+    include ApiEngineBase::SchemaHelper
+
+    before_action :authenticate_user!
+    before_action :authorize_user!
+    before_action :user!, only: [:modify, :modify_role]
+
+    # Pagination is needed here
+    def show
+      schemafied_users = User.all.map { ApiEngineBase::Schema::User.convert_user_object(user: _1) }
+      schema = ApiEngineBase::Schema::Admin::Users.new(users: schemafied_users)
+      schema_succesful!(status: 200, schema:)
+    end
+
+    def modify
+      result = ApiEngineBase::UserAttributes::Modify.(user:, admin_user:, **modify_params)
+      if result.success?
+        schema = ApiEngineBase::Schema::User.convert_user_object(user: user.reload)
+        status = 201
+        schema_succesful!(status:, schema:)
+      else
+        if result.invalid_arguments
+          invalid_arguments!(
+            status: 400,
+            message: result.msg,
+            argument_object: result.invalid_argument_hash,
+            schema: ApiEngineBase::Schema::PlainText::LoginRequest
+          )
+        else
+          server_error!(result:)
+        end
+      end
+    end
+
+    def modify_role
+      result = ApiEngineBase::UserAttributes::Roles.(user:, admin_user:, roles: params[:roles] || [])
+      if result.success?
+        schema = ApiEngineBase::Schema::User.convert_user_object(user: user.reload)
+        status = 201
+        schema_succesful!(status:, schema:)
+      else
+        if result.invalid_arguments
+          invalid_arguments!(
+            status: 400,
+            message: result.msg,
+            argument_object: result.invalid_argument_hash,
+            schema: ApiEngineBase::Schema::PlainText::LoginRequest
+          )
+        else
+          server_error!(result:)
+        end
+      end
+    end
+
+    def impersonate
+      # TODO: @matt-taylor
+    end
+
+    private
+
+    def server_error!(result:)
+      status = 500
+      schema = ApiEngineBase::Schema::Error::Base.new(status:, message: result.msg)
+      render(json: schema.to_h, status:)
+    end
+
+    def modify_params
+      {
+        email: params[:email],
+        email_validated: safe_boolean(value: params[:email_validated]),
+        first_name: params[:first_name],
+        last_name: params[:last_name],
+        username: params[:username],
+        verifier_token: safe_boolean(value: params[:verifier_token]),
+      }.compact
+    end
+
+    def admin_user
+      # current_user is defined via authenticate_user! before action
+      current_user
+    end
+
+    def user!
+      _user = User.where(id: params[:user_id]).first
+      if _user
+        @user = _user
+        return true
+      end
+
+      status = 400
+      schema = ApiEngineBase::Schema::Error::Base.new(status:, message: "Invalid user")
+      render(json: schema.to_h, status:)
+      # Must return false so callbacks know to halt propagation
+      false
+    end
+
+    def user
+      @user ||= nil
+    end
+  end
+end

data/app/controllers/api_engine_base/application_controller.rb

@@ -2,12 +2,21 @@
 
 module ApiEngineBase
   class ApplicationController < ActionController::API
-    AUTHORIZATION_HEADER = "AUTHORIZATION"
+    AUTHENTICATION_HEADER = "Authentication"
+    AUTHENTICATION_EXPIRE_HEADER = "X-Authentication-Expire"
+    AUTHENTICATION_WITH_RESET = "X-Authentication-Reset"
+
+    def safe_boolean(value:)
+      return nil unless [true, false, "true", "false", "0", "1", 0, 1].include?(value)
+
+      ActiveModel::Type::Boolean.new.cast(value)
+    end
 
     ###
-    # AUTHORIZATION_HEADER="Bearer: {token value}"
+    # Authenticate user via the passed in header
+    # AUTHENTICATION_HEADER="Bearer: {token value}"
     def authenticate_user!(bypass_email_validation: false)
-      raw_token = request.headers[AUTHORIZATION_HEADER]
+      raw_token = request.headers[AUTHENTICATION_HEADER]
       if raw_token.nil?
         status = 401
         schema = ApiEngineBase::Schema::Error::Base.new(status:, message: "Bearer token missing")
@@ -16,9 +25,14 @@ module ApiEngineBase
       end
 
       token = raw_token.split("Bearer:")[1].strip
-      result = ApiEngineBase::Jwt::AuthenticateUser.(token:, bypass_email_validation:)
+      with_reset = safe_boolean(value: request.headers[AUTHENTICATION_WITH_RESET])
+      result = ApiEngineBase::Jwt::AuthenticateUser.(token:, bypass_email_validation:, with_reset:)
       if result.success?
         @current_user = result.user
+        response.set_header(AUTHENTICATION_EXPIRE_HEADER, result.expires_at)
+        if with_reset
+          response.set_header(AUTHENTICATION_WITH_RESET, result.generated_token)
+        end
         true
       else
         status = 401
@@ -29,19 +43,39 @@ module ApiEngineBase
       end
     end
 
+    ###
+    # Authenticate user via the passed in header without validating email
     def authenticate_user_without_email_verification!
       authenticate_user!(bypass_email_validation: true)
     end
 
-    def current_user
-      @current_user ||= nil
+    ###
+    # After Authenticating user, see if the user needs authorization on the route
+    def authorize_user!
+      if current_user.nil?
+        Rails.logger.error { "Current User is not defined. This means that authenticate_user! was not called" }
+        status = 401
+        schema = ApiEngineBase::Schema::Error::Base.new(status:, message: "Bearer token missing")
+        render(json: schema.to_h, status:)
+        return false
+      end
+      result = ApiEngineBase::Authorize::Validate.(user: current_user, controller: self.class, method: params[:action])
+
+      if result.success?
+        @current_user = result.user
+        true
+      else
+        # Current user is not authorized for the current Controller#action
+        status = 403
+        schema = ApiEngineBase::Schema::Error::Base.new(status:, message: result.msg)
+        render(json: schema.to_h, status:)
+        # Must return false so callbacks know to halt propagation
+        false
+      end
     end
 
-    def add_to_body
-      # {
-      #   token_valid_till:,
-      #   needs_email_verification:,
-      # }
+    def current_user
+      @current_user ||= nil
     end
   end
 end

data/app/controllers/api_engine_base/auth/plain_text_controller.rb

@@ -12,7 +12,7 @@ module ApiEngineBase
         if result.success?
           schema = ApiEngineBase::Schema::PlainText::LoginResponse.new(
             token: result.token,
-            header_name: AUTHORIZATION_HEADER,
+            header_name: AUTHENTICATION_HEADER,
             message: "Successfully logged user in"
           )
           status = 201

data/app/controllers/api_engine_base/inbox/message_blast_controller.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module ApiEngineBase
+  module Inbox
+    class MessageBlastController < ::ApiEngineBase::ApplicationController
+      include ApiEngineBase::SchemaHelper
+
+      before_action :authenticate_user!
+      before_action :authorize_user!
+
+      # GET /inbox/blast
+      def metadata
+        result = ApiEngineBase::InboxService::Blast::Metadata.(id: params[:id].to_i)
+        schema_succesful!(status: 200, schema: result.metadata)
+      end
+
+      # GET /inbox/blast/:id
+      def blast
+        result = ApiEngineBase::InboxService::Blast::Retrieve.(id: params[:id].to_i)
+        if result.success?
+          schema = result.message_blast
+          status = 200
+          schema_succesful!(status:, schema:)
+        else
+          invalid_arguments!(
+            status: 400,
+            message: result.msg,
+            argument_object: result.invalid_argument_hash,
+            schema: ApiEngineBase::Schema::PlainText::LoginRequest,
+          )
+        end
+      end
+
+      # POST /inbox/blast
+      def create
+        upsert
+      end
+
+      # PATCH /inbox/blast/:id
+      def modify
+        upsert(id: params[:id].to_i)
+      end
+
+      # DELETE /inbox/blast/:id
+      def delete
+        result = ApiEngineBase::InboxService::Blast::Delete.(id: params[:id].to_i)
+        if result.success?
+          schema = result.message
+          status = 200
+          render :json, { id: params[:id], msg: "Message Blast message deleted" }
+        else
+          invalid_arguments!(
+            status: 400,
+            message: result.msg,
+            argument_object: result.invalid_argument_hash,
+            schema: ApiEngineBase::Schema::PlainText::LoginRequest,
+          )
+        end
+      end
+
+      private
+
+      def upsert(id: nil)
+        upsert_params = {
+          user: current_user,
+          existing_users: safe_boolean(value: params[:existing_users]),
+          new_users: safe_boolean(value: params[:new_users]),
+          text: params[:text],
+          title: params[:title],
+          id:,
+        }.compact
+        result = ApiEngineBase::InboxService::Blast::Upsert.(**upsert_params)
+
+        if result.success?
+          schema = result.blast
+          status = 200
+          schema_succesful!(status:, schema:)
+        else
+          invalid_arguments!(
+            status: 400,
+            message: result.msg,
+            argument_object: result.invalid_argument_hash,
+            schema: ApiEngineBase::Schema::Inbox::BlastRequest
+          )
+        end
+      end
+    end
+  end
+end

data/app/controllers/api_engine_base/inbox/message_controller.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module ApiEngineBase
+  module Inbox
+    class MessageController < ::ApiEngineBase::ApplicationController
+      include ApiEngineBase::SchemaHelper
+
+      before_action :authenticate_user!
+
+      # GET: /inbox/messages
+      def metadata
+        result = ApiEngineBase::InboxService::Message::Metadata.(user: current_user)
+        if result.success?
+          schema = result.metadata
+          status = 200
+          schema_succesful!(status:, schema:)
+        else
+          invalid_arguments!(
+            status: 400,
+            message: result.msg,
+            argument_object: result.invalid_argument_hash,
+            schema: ApiEngineBase::Schema::PlainText::LoginRequest
+          )
+        end
+      end
+
+      # GET: /inbox/messages/:id
+      def message
+        result = ApiEngineBase::InboxService::Message::Retrieve.(user: current_user, id: params[:id].to_i)
+        if result.success?
+          schema = result.message
+          status = 200
+          schema_succesful!(status:, schema:)
+        else
+          invalid_arguments!(
+            status: 400,
+            message: result.msg,
+            argument_object: result.invalid_argument_hash,
+            schema: ApiEngineBase::Schema::PlainText::LoginRequest
+          )
+        end
+      end
+
+      # POST: /inbox/messages/ack
+      # Body { ids: [<list of ids to ack>] }
+      def ack
+        modify(type: ApiEngineBase::InboxService::Message::Modify::VIEWED)
+      end
+
+      # POST: /inbox/messages/delete
+      # Body { ids: [<list of ids to delete>] }
+      def delete
+        modify(type: ApiEngineBase::InboxService::Message::Modify::DELETE)
+      end
+
+      private
+
+      def modify(type:)
+        result = ApiEngineBase::InboxService::Message::Modify.(
+          user: current_user,
+          ids: params[:ids],
+          type:,
+        )
+        if result.success?
+          schema = result.modified
+          status = 200
+          schema_succesful!(status:, schema:)
+        else
+          invalid_arguments!(
+            status: 400,
+            message: result.msg,
+            argument_object: result.invalid_argument_hash,
+            schema: ApiEngineBase::Schema::PlainText::LoginRequest
+          )
+        end
+      end
+    end
+  end
+end

data/app/controllers/api_engine_base/user_controller.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ApiEngineBase
+  class UserController < ::ApiEngineBase::ApplicationController
+    include ApiEngineBase::SchemaHelper
+
+    before_action :authenticate_user!
+
+    def show
+      schema = ApiEngineBase::Schema::User.convert_user_object(user: current_user)
+      schema_succesful!(status: 200, schema:)
+    end
+
+    def modify
+      result = ApiEngineBase::UserAttributes::Modify.(user: current_user, **modify_params)
+      if result.success?
+        schema = ApiEngineBase::Schema::User.convert_user_object(user: current_user.reload)
+        status = 201
+        schema_succesful!(status:, schema:)
+      else
+        if result.invalid_arguments
+          invalid_arguments!(
+            status: 400,
+            message: result.msg,
+            argument_object: result.invalid_argument_hash,
+            schema: ApiEngineBase::Schema::PlainText::LoginRequest
+          )
+        else
+          status = 500
+          schema = ApiEngineBase::Schema::Error::Base.new(status:, message: result.msg)
+          render(json: schema.to_h, status:)
+        end
+      end
+    end
+
+    private
+
+    def modify_params
+      {
+        email: params[:email],
+        email_validated: safe_boolean(value: params[:email_validated]),
+        first_name: params[:first_name],
+        last_name: params[:last_name],
+        username: params[:username],
+        verifier_token: safe_boolean(value: params[:verifier_token]),
+      }.compact
+    end
+  end
+end

data/app/models/api_engine_base/application_record.rb

@@ -3,5 +3,43 @@
 module ApiEngineBase
   class ApplicationRecord < ActiveRecord::Base
     self.abstract_class = true
+
+    def self.attribute_to_type_mapping
+      @attribute_to_type_mapping ||= begin
+        mapping = ActiveSupport::HashWithIndifferentAccess.new
+        columns_hash.each do |attribute_name, metadata|
+          base = nil
+          ruby_type = nil
+          allowed_types = nil
+          serialized_type = nil
+          case metadata.type
+          when :string, :text
+            base = ruby_type = String
+          when :integer, :bigint
+            base = ruby_type = Integer
+          when :datetime, :time, :date
+            base = String
+            ruby_type = [DateTime, Time]
+          when :float, :decimal
+            base = ruby_type = Float
+          when :boolean
+            base = "Boolean"
+            ruby_type = [TrueClass, FalseClass]
+            allowed_types = [true, false]
+          else
+            # All else fails convert to String and continue
+            base = ruby_type = String
+          end
+
+          attribute_type = attribute_types[attribute_name]
+          if attribute_type.is_a?(ActiveRecord::Type::Serialized)
+            serialized_type = attribute_type.coder.object_class
+          end
+          mapping[attribute_name] = { serialized_type:, base:, ruby_type:, allowed_types: }.compact
+        end
+
+        mapping
+      end
+    end
   end
 end

data/app/models/message.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# == Schema Information
+#
+# Table name: messages
+#
+#  id               :bigint           not null, primary key
+#  pushed           :boolean          default(FALSE)
+#  text             :text(65535)
+#  title            :string(255)
+#  viewed           :boolean          default(FALSE)
+#  created_at       :datetime         not null
+#  updated_at       :datetime         not null
+#  message_blast_id :bigint
+#  user_id          :bigint           not null
+#
+# Indexes
+#
+#  index_messages_on_message_blast_id  (message_blast_id)
+#  index_messages_on_user_id           (user_id)
+#
+# Foreign Keys
+#
+#  fk_rails_...  (message_blast_id => message_blasts.id)
+#  fk_rails_...  (user_id => users.id)
+#
+class Message < ApplicationRecord
+  belongs_to :user
+  belongs_to :message_blast, optional: true
+end

data/app/models/message_blast.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# == Schema Information
+#
+# Table name: message_blasts
+#
+#  id             :bigint           not null, primary key
+#  existing_users :boolean          default(FALSE)
+#  new_users      :boolean          default(FALSE)
+#  text           :text(65535)
+#  title          :string(255)
+#  created_at     :datetime         not null
+#  updated_at     :datetime         not null
+#  user_id        :bigint           not null
+#
+# Indexes
+#
+#  index_message_blasts_on_user_id  (user_id)
+#
+# Foreign Keys
+#
+#  fk_rails_...  (user_id => users.id)
+#
+class MessageBlast < ApplicationRecord
+  has_many :messages
+  belongs_to :user
+end

data/app/models/user.rb

@@ -16,6 +16,7 @@
 #  password_consecutive_fail  :integer          default(0)
 #  password_digest            :string(255)      default(""), not null
 #  recovery_password_digest   :string(255)      default(""), not null
+#  roles                      :string(255)      default([])
 #  successful_login           :integer          default(0)
 #  username                   :string(255)
 #  verifier_token             :string(255)
@@ -35,16 +36,26 @@ class User < ApiEngineBase::ApplicationRecord
   validates :username, uniqueness: true
   validates :email, uniqueness: true
 
+  ###
+  # Serialize the roles column to check for inclusion easily
+  serialize :roles, coder: JSON, type: Array
+
+  has_many :messages
+
   def full_name
     "#{first_name} #{last_name}"
   end
 
-  def retreive_verifier_token!
-    return verifier_token if verifier_token
-
+  def reset_verifier_token!
     value = SecureRandom.alphanumeric(32)
-    update!(verifier_token: value)
+    update!(verifier_token: value, verifier_token_last_reset: Time.now)
 
     value
   end
+
+  def retreive_verifier_token!
+    return verifier_token if verifier_token
+
+    reset_verifier_token!
+  end
 end

data/app/services/api_engine_base/README.md

@@ -0,0 +1,49 @@
+# ApiEngineBase Service
+
+`ApiEngineBase::ServiceBase` an abstraction around the Ruby Gem Interactor. It dds custom functionality to the base Service and is intended to be an inherited Class to create Application logic code. All Services in `ApiEngineBase` utilize this base Service class for convenience and DRYness.
+
+## What does ServiceBase offer
+
+### Logging
+`ServiceBase` offers a convenient way to tag logs. It keeps track of:
+- The start of the the Logic call
+- The time it took to complete the logic
+- The status of the logic
+
+Additionally, it provides some convenience methods for logging
+- `log_debug`
+- `log_info`
+- `log_warn`
+- `log_error`
+
+### Argument Validation
+Argument Validation is the powerhouse behind ServiceBase
+
+Customized argument validation can be created by adding the method `validate!`
+```ruby
+class MyServiceClass < ApiEngineBase::ServiceBase
+
+  def call
+  end
+
+  def validate!
+    # run custom validations before executing call
+  end
+end
+```
+
+Other more complex Argument validation includes:
+- Validating Presence of Argument
+- Validating Type of argument
+- Validating a composition of argument values (At least, At Most, Exactly)
+- Delegate context variable to the class for simplicity
+- Validating Argument length or size is `<` `≤` `==` `>` `≥`
+
+For More information, Check out the [ArgumentValidation ReadMe](argument_validation/README.md)
+
+
+## Basic Examples:
+Check out the examples used in this directory!
+
+
+