api_engine_base 0.1.1 → 0.2.0

data/app/services/api_engine_base/argument_validation/README.md

@@ -0,0 +1,192 @@
+# Argument Validation
+
+Argument validation provides a robust framework to ensure correctness of arguments before executing any application logic code. This was created because when in use with an API, this can help provide reusable messaging directly back to the API when the parameters are incorrect.
+
+## Argument Validation
+Argument Validation provides service object code assurances on what to expect for inputted arguments.
+
+Available arguments:
+- `default`: Default value to set the argument when not provided by user
+- `is_a`: The allowed types of the passed in argument. Will also check if the type is in the ancestral tree
+- `is_one`: Checks a direct comparison if the input is one of these values. Note: while not disallowed, `is_a` and `is_one` should not be used together
+- `length`: (used with operators exclusively) When set to true, the operators will use the length of value rather than the exact value
+- `lt`: When provided, argument must be less than this value
+- `lte`: When provided, argument must be less than or equal to this value
+- `eq`: When provided, argument must be equal to this value
+- `gte`: When provided, argument must be greater than or equal to this value
+- `gt`: When provided, argument must be greater than this value
+- `delegation`: (Default set to true) - Sets the delegation on the object. This allows you to reference the argument name rather than the context.{argument_name}
+- `sensitive`: This marks the argument as sensitive. It will scrub the value of the argument when returning the context to the caller
+- `required`: When set, this marks the argument as required. If not provided, validations are not run. When provided, validations must pass
+
+## Argument Composition
+Argument Compositions are made up of 1 or more Argument Validations. The intention of compositions are to ensure `at_most`, `at_least`, or `exactly` X argument validations are provided by the user.
+
+### Composition: At Most
+At most composition expects at most X arguments to get passed into the instance.
+
+```ruby
+class ServiceExample < ApiEngineBase::ServiceBase
+  at_most 2, :name_of_composition, required: true do
+    validate :email, is_a: String
+    validate :phone, is_a: String
+    validate :username, is_a: String
+  end
+
+  def call; end
+end
+```
+
+```ruby
+rails-app(dev)> ServiceExample.(email: "email", phone: "phone", username: "username")
+=> # Composite Key failure for name_of_composition [name_of_composition]. Expected at most 2 keys assigned. Provided values for the following keys: [:email, :phone, :username]. Available keys [:email, :phone, :username] (ApiEngineBase::ServiceBase::CompositionValidationError)
+```
+
+### Composition: At Least
+At least composition expects at least X arguments to get passed into the instance.
+
+```ruby
+class ServiceExample < ApiEngineBase::ServiceBase
+  at_least 2, :name_of_composition, required: true do
+    validate :email, is_a: String
+    validate :phone, is_a: String
+    validate :username, is_a: String
+  end
+
+  def call; end
+end
+```
+
+```ruby
+rails-app(dev)> ServiceExample.(email: "email")
+=> # Composite Key failure for name_of_composition [name_of_composition]. Expected at least 2 keys assigned. Available keys. Provided values for the following keys: [:email]. Available keys [:email, :phone, :username] (ApiEngineBase::ServiceBase::CompositionValidationError)
+```
+
+**Noteworthy**: `at_least` can take in any integer for its `count`. However, we found that most people just need one. For that reason, the convenience method of `at_least_one` was created. It can be used without the `count` argument in `at_least`
+
+### Composition: Compose Exact
+Compose Exact composition expects exactly X arguments to get passed into the instance. For this composition to be valid, there must be X or more validations.
+
+```ruby
+class ServiceExample < ApiEngineBase::ServiceBase
+  compose_exact 2, :name_of_composition, required: true do
+    validate :email, is_a: String
+    validate :phone, is_a: String
+    validate :username, is_a: String
+  end
+
+  def call; end
+end
+```
+```ruby
+rails-app(dev)> ServiceExample.(email: "email")
+=> # Composite Key failure for name_of_composition [name_of_composition]. Expected [2] of the keys to have a value assigned. But 1 keys were assigned. Provided values for the following keys: [:email]. Available keys [:email, :phone, :username] (ApiEngineBase::ServiceBase::CompositionValidationError)
+```
+
+**Noteworthy**: `compose_exact` can take any `count` value to dynamically provision the exact component. However, we found that we almost only just needed count == 1. We have provided a convenience method of `one_of` without the `count` variable to simplify. There are quite a few examples of this already created
+
+### Custom Compositions
+All compositions are built on top of the same underlying function. This allows you to build additional compositions to add custom logic for validations and what not.
+Check out the [ClassMethods Source Code](class_methods.rb) on what method arguments are required.
+
+
+## Argument validation Failures
+When an argument validation fails (whether that is a single `validate` or a composition), there are 3 options on what to do:
+
+### Raise an error (Default)
+As you can see in the examples above, the default for argument validation failures is to raise the following error
+```ruby
+ApiEngineBase::ServiceBase::CompositionValidationError
+```
+
+The expected behavior is:
+- Downstream code catches the failure and handles it correctly
+- Service Logic code is not executed
+
+This failure mode can get explicitly set via:
+```ruby
+class ServiceExample < ApiEngineBase::ServiceBase
+  on_argument_validation :raise
+
+  one_of :name_of_composition, required: true do
+    validate :email, is_a: String
+    validate :phone, is_a: String
+    validate :username, is_a: String
+  end
+
+  def call; end
+end
+```
+
+### Fail the context Early (Recommended)
+Failing the context early is we recommend to do for your service objects. This mode provides an exceptionally amount of context into **HOW** the validation failed and what needs to get corrected.
+
+
+The expected behavior is:
+- Downstream code checks for `result.failure?` and continues accordingly
+- Service Logic code is not executed
+- Nothing is raised
+
+```ruby
+class ServiceExample < ApiEngineBase::ServiceBase
+  on_argument_validation :fail_early
+
+  one_of :name_of_composition, required: true do
+    validate :email, is_a: String
+    validate :phone, is_a: String
+    validate :username, is_a: String
+  end
+
+  def call; end
+end
+```
+```ruby
+result = ServiceExample.(email: :not_a_string)
+if result.success?
+else
+  if result.invalid_arguments
+    # context.fail! was called by argument validation
+    puts result.invalid_arguments
+    puts result.invalid_argument_hash
+    puts result.invalid_argument_keys
+  else
+    # context.fail! was called by user
+  end
+end
+=> true
+=> {:email=>{:msg=>"Parameter [email] must be of type String. Given Symbol [not_a_string]", :required=>nil, :is_a=>String}}
+=> [:email]
+
+result = ServiceExample.()
+result.invalid_arguments
+=> true
+result.invalid_argument_hash
+=> {:name_of_composition=>{:msg=>"Composite Key failure for name_of_composition [name_of_composition]. Expected [1] of the keys to have a value assigned. But no key was assigned. Provided values for the following keys: []. Available keys [:email, :phone, :username]", :required=>nil, :is_a=>nil}}
+result.invalid_argument_keys
+=> [:name_of_composition]
+
+result = ServiceExample.(email: 7, username: 8)
+result.invalid_arguments
+=> true
+result.invalid_argument_hash
+=> {:email=>{:msg=>"Parameter [email] must be of type String. Given Integer [7]", :required=>nil, :is_a=>String}, :username=>{:msg=>"Parameter [username] must be of type String. Given Integer [8]", :required=>nil, :is_a=>String}, :name_of_composition=>{:msg=>"Composite Key failure for name_of_composition [name_of_composition]. Expected [1] of the keys to have a value assigned. But 2 keys were assigned. Provided values for the following keys: [:email, :username]. Available keys [:email, :phone, :username]", :required=>nil, :is_a=>nil}}
+=> [:email, :username, :name_of_composition]
+```
+
+### Log and Continue (Not Recommended)
+This mode will allow you to log the validation failure and continue. We do not recommend this
+
+
+```ruby
+class ServiceExample < ApiEngineBase::ServiceBase
+  on_argument_validation :log
+
+  one_of :name_of_composition, required: true do
+    validate :email, is_a: String
+    validate :phone, is_a: String
+    validate :username, is_a: String
+  end
+
+  def call; end
+end
+```

data/app/services/api_engine_base/argument_validation/class_methods.rb

@@ -22,8 +22,7 @@ module ApiEngineBase::ArgumentValidation
       raise ApiEngineBase::ServiceBase::CompositionValidationError, "Count must be greater than 0" if count < 1
 
       validation_proc = Proc.new do |input_count, keys|
-
-        language = (input_count > 1) ? "But more than #{count} did" : "But no key had a value"
+        language = (input_count > 0) ? "But #{input_count} keys were assigned" : "But no key was assigned"
         {
           message: "Expected [#{count}] of the keys to have a value assigned. #{language}",
           is_valid: (input_count == count),
@@ -111,7 +110,7 @@ module ApiEngineBase::ArgumentValidation
       end
     end
 
-    def validate(name, default: nil, length: false, matches: nil, is_a: nil, is_one: nil, lt: nil, lte: nil, eq: nil, gt: nil, gte: nil, delegation: true, sensitive: false, required: false)
+    def validate(name, default: nil, length: false, is_a: nil, is_one: nil, lt: nil, lte: nil, eq: nil, gt: nil, gte: nil, delegation: true, sensitive: false, required: false)
       if __existing_names.include?(name)
         raise ApiEngineBase::ServiceBase::NameConflictError, "Duplicate key name found. [#{name}] can only be defined once"
       end

data/app/services/api_engine_base/argument_validation/instance_methods.rb

@@ -50,7 +50,19 @@ module ApiEngineBase::ArgumentValidation
         end
 
         if is_a = metadata[:is_a]
-          if Array(is_a).none? { _1 === value }
+          direct_type = false
+          ancestor_type = false
+
+          # Check if direct type of `is_a` Integer === 5 => true
+          direct_type = Array(is_a).none? { _1 === value }
+
+          # If it is a direct type, we dont need to do any other type of checking
+          if direct_type == true
+            lineage = value.ancestors rescue []
+            # Check inclusion in ancestor list
+            ancestor_type = Array(is_a).none? { lineage.include?(_1) }
+          end
+          if direct_type && ancestor_type
             __failed_argument_validation(msg: "Parameter [#{metadata[:name]}] must be of type #{is_a}. Given #{value.class} [#{value}]", argument: metadata[:name], metadata:)
           end
         end

data/app/services/api_engine_base/authorize/validate.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ApiEngineBase::Authorize
+  class Validate < ApiEngineBase::ServiceBase
+    on_argument_validation :fail_early
+
+    validate :user, is_a: User, required: true
+    validate :controller, is_a: [ActionController::Base, ActionController::API], required: true
+    validate :method, is_a: String, required: true
+
+    def call
+      context.authorization_required = authorization_required?
+      unless context.authorization_required
+        log_info("controller:#{controller}; method:#{method} -- No Authorization required")
+        context.msg = "Authorization not required at this time"
+        return
+      end
+
+      # At this point we know authorization on the route is required
+      # Iterate through the users roles to find a matching role that allows authorization
+      # If at least 1 of the users roles passes validation, we can allow access to the path
+      log_info("User Roles: #{user.roles}")
+      auhorization_result = user_role_objects.any? do |_role_name, role_object|
+        result = role_object.authorized?(controller:, method:, user:)
+        log_info("Role:#{result[:role]};Authorized:[#{result[:authorized]}];Reason:[#{result[:reason]}]")
+        result[:authorized] == true
+      end
+
+      if auhorization_result
+        context.msg = "User is Authorized for action"
+      else
+        context.fail!(msg: "Unauthorized Access. Incorrect User Privileges")
+      end
+    end
+
+    def authorization_required?
+      controller_mapping = ApiEngineBase::Authorization.mapped_controllers[controller]
+      return false if controller_mapping.nil?
+
+      controller_mapping.include?(method.to_sym)
+    end
+
+    def user_role_objects
+      ApiEngineBase::Authorization::Role.roles.select do |role_name, _|
+        user.roles.include?(role_name.to_s)
+      end
+    end
+  end
+end

data/app/services/api_engine_base/inbox_service/blast/delete.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ApiEngineBase
+  module InboxService
+    module Blast
+      class Delete < ApiEngineBase::ServiceBase
+        on_argument_validation :fail_early
+
+        validate :id, is_a: Integer, required: true
+
+        def call
+          message_blast = ::MessageBlast.where(id:).first
+
+          if message_blast.nil?
+            inline_argument_failure!(errors: { id: "MessageBlast ID not found" })
+          end
+
+          message_blast.destroy
+        end
+      end
+    end
+  end
+end

data/app/services/api_engine_base/inbox_service/blast/metadata.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module ApiEngineBase
+  module InboxService
+    module Blast
+      class Metadata  < ApiEngineBase::ServiceBase
+        def call
+          entities = ::MessageBlast.all.select(:id, :title, :existing_users, :new_users).map do |mb|
+            ApiEngineBase::Schema::Inbox::MessageBlastEntity.new(
+              title: mb.title,
+              id: mb.id,
+              existing_users: mb.existing_users,
+              new_users: mb.new_users,
+            )
+          end
+
+
+          context.metadata = ApiEngineBase::Schema::Inbox::MessageBlastMetadata.new(
+            entities: entities,
+            count: entities.length,
+          )
+        end
+      end
+    end
+  end
+end

data/app/services/api_engine_base/inbox_service/blast/new_user_blaster.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module ApiEngineBase
+  module InboxService
+    module Blast
+      class NewUserBlaster  < ApiEngineBase::ServiceBase
+        on_argument_validation :fail_early
+
+        validate :user, is_a: User, required: true
+
+        def call
+          ::MessageBlast.where(new_users: true).each do |message_blast|
+            InboxService::Message::Send.(
+              user:,
+              text: message_blast.text,
+              title: message_blast.title,
+              message_blast:,
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/api_engine_base/inbox_service/blast/retrieve.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ApiEngineBase
+  module InboxService
+    module Blast
+      class Retrieve < ApiEngineBase::ServiceBase
+        on_argument_validation :fail_early
+
+        validate :id, is_a: Integer, required: true
+
+        def call
+          message_blast = ::MessageBlast.where(id:).first
+
+          if message_blast.nil?
+            inline_argument_failure!(errors: { id: "MessageBlast ID not found" })
+          end
+
+          context.message_blast = ApiEngineBase::Schema::Inbox::MessageBlastEntity.new(
+            created_by: ApiEngineBase::Schema::User.convert_user_object(user: message_blast.user),
+            title: message_blast.title,
+            text: message_blast.text,
+            id: message_blast.id,
+            existing_users: message_blast.existing_users,
+            new_users: message_blast.new_users,
+          )
+        end
+      end
+    end
+  end
+end

data/app/services/api_engine_base/inbox_service/blast/upsert.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module ApiEngineBase
+  module InboxService
+    module Blast
+      class Upsert  < ApiEngineBase::ServiceBase
+        on_argument_validation :fail_early
+
+        validate :user, is_a: User, required: true
+        validate :existing_users, is_one: [true, false], required: true
+        validate :new_users, is_one: [true, false], required: true
+        validate :text, is_a: String, required: true
+        validate :title, is_a: String, required: true
+        validate :id, is_a: Integer, required: false
+
+        def call
+          ar = record
+
+          ar.existing_users = existing_users
+          ar.new_users = new_users
+          ar.text = text
+          ar.title = title
+          ar.user = user
+
+          # Probably should wrap this in a transaction block
+          ar.save!
+          blast_messages!(message_blast: ar)
+
+          context.message_blast = ar
+          context.blast = ApiEngineBase::Schema::Inbox::BlastResponse.new(
+            existing_users:,
+            new_users:,
+            text:,
+            title:,
+            id: ar.id,
+            created_by: ApiEngineBase::Schema::User.convert_user_object(user:)
+          )
+        end
+
+        def blast_messages!(message_blast:)
+          # Only blast messages to existing users that are brand new
+          return if @existing_record
+          return unless existing_users
+
+          User.all.each do |u|
+            InboxService::Message::Send.(
+              user: u,
+              text: text,
+              title: title,
+              message_blast: message_blast,
+            )
+          end
+        end
+
+        def record
+          return MessageBlast.new if id.nil?
+
+          record = MessageBlast.where(id:).first
+          inline_argument_failure!(errors: { id: "Message Blast ID does not exist" }) if record.nil?
+
+          @existing_record = true
+          record
+        end
+      end
+    end
+  end
+end

data/app/services/api_engine_base/inbox_service/message/metadata.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module ApiEngineBase
+  module InboxService
+    module Message
+      class Metadata < ApiEngineBase::ServiceBase
+        on_argument_validation :fail_early
+
+        validate :user, is_a: User, required: true
+
+        def call
+          entities = ::Message.where(user:).select(:id, :title, :viewed).map do |message|
+            ApiEngineBase::Schema::Inbox::MessageEntity.new(
+              title:  message.title,
+              id:  message.id,
+              viewed:  message.viewed,
+            )
+          end
+
+          params = {
+            entities: entities.nil? ? nil : entities,
+            count: entities.length,
+          }
+
+          context.metadata = ApiEngineBase::Schema::Inbox::Metadata.new(**params.compact)
+        end
+      end
+    end
+  end
+end
+
+
+
+
+

data/app/services/api_engine_base/inbox_service/message/modify.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module ApiEngineBase
+  module InboxService
+    module Message
+      class Modify < ApiEngineBase::ServiceBase
+        on_argument_validation :fail_early
+
+        IS_ONE = [
+          VIEWED = :viewed,
+          DELETE = :delete,
+        ]
+        validate :user, is_a: User, required: true
+        validate :ids, is_a: Array, required: true
+        validate :type, is_one: IS_ONE, required: true
+
+        def call
+          messages = ::Message.where(user:, id: ids)
+          if messages.empty?
+            inline_argument_failure!(errors: { ids: "No ID's found for user" })
+          end
+
+          case type
+          when VIEWED
+            modified_ids = messages.update(viewed: true).pluck(:id)
+          when DELETE
+            modified_ids = messages.destroy_all.pluck(:id)
+          end
+
+          context.modified = ApiEngineBase::Schema::Inbox::Modified.new(
+            ids: modified_ids,
+            type:,
+            count: modified_ids.length,
+          )
+        end
+      end
+    end
+  end
+end
+
+
+
+
+

data/app/services/api_engine_base/inbox_service/message/retrieve.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ApiEngineBase
+  module InboxService
+    module Message
+      class Retrieve < ApiEngineBase::ServiceBase
+        on_argument_validation :fail_early
+
+        validate :user, is_a: User, required: true
+        validate :id, is_a: Integer, required: true
+
+        def call
+          message = ::Message.where(user:, id:).first
+
+          if message.nil?
+            inline_argument_failure!(errors: { id: "Message ID not found for user" })
+          end
+
+          message.update!(viewed: true)
+
+          context.message = ApiEngineBase::Schema::Inbox::MessageEntity.new(
+            title: message.title,
+            id: message.id,
+            text: message.text,
+            viewed: message.viewed,
+          )
+        end
+      end
+    end
+  end
+end
+
+
+
+
+

data/app/services/api_engine_base/inbox_service/message/send.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ApiEngineBase
+  module InboxService
+    module Message
+      class Send  < ApiEngineBase::ServiceBase
+        validate :user, is_a: User, required: true
+        validate :text, is_a: String, required: true
+        validate :title, is_a: String, required: true
+        validate :message_blast, is_a: ::MessageBlast, required: false
+        validate :pushed, is_one: [true, false], default: false
+
+        def call
+          message = create_message!
+          context.message = message
+        end
+
+        def push_notification!
+          # TODO: Push notifications
+        end
+
+        def create_message!
+          ::Message.create!(
+            user:,
+            text: ,
+            title: ,
+            message_blast:,
+          )
+        end
+      end
+    end
+  end
+end

data/app/services/api_engine_base/jwt/authenticate_user.rb

@@ -5,6 +5,7 @@ module ApiEngineBase::Jwt
 
     validate :token, is_a: String, required: true, sensitive: true
     validate :bypass_email_validation, is_one: [true, false], default: false
+    validate :with_reset, is_one: [true, false], default: false
 
     def call
       result = Decode.(token:)
@@ -14,7 +15,7 @@ module ApiEngineBase::Jwt
       end
       payload = result.payload
 
-      validate_expires_at!(expires_at: payload[:expires_at])
+      expires_at = validate_generated_at!(generated_at: payload[:generated_at])
 
       user = User.find(payload[:user_id]) rescue nil
       if user.nil?
@@ -29,25 +30,39 @@ module ApiEngineBase::Jwt
       end
 
       email_validation_required!(user:)
+
+      if with_reset
+        context.generated_token = ApiEngineBase::Jwt::LoginCreate.(user:).token
+        expires_at = ApiEngineBase.config.jwt.ttl.from_now.to_time
+      end
+
+      context.expires_at = expires_at.to_s
     end
 
-    def validate_expires_at!(expires_at:)
-      if expires_at.nil?
-        log_warn("expires_at payload is missing from the JWT token. Cannot continue")
+    def validate_generated_at!(generated_at:)
+      if generated_at.nil?
+        log_warn("generated_at payload is missing from the JWT token. Cannot continue")
         context.fail!(msg: "Unauthorized Access. Invalid Authorization token")
       end
 
-      expires_time = Time.at(expires_at) rescue nil
+      expires_time = begin
+        time = Time.at(generated_at)
+        time + ApiEngineBase.config.jwt.ttl
+      rescue
+        nil
+      end
 
       if expires_time.nil?
-        log_warn("expires_at payload cannot be parsed. Cannot continue")
+        log_warn("generated_at payload cannot be parsed. Cannot continue")
         context.fail!(msg: "Unauthorized Access. Invalid Authorization token")
       end
 
       if expires_time < Time.now
-        log_warn("expires_at is no longer valid. Must request new token")
+        log_warn("generated_at is no longer valid. Must request new token")
         context.fail!(msg: "Unauthorized Access. Invalid Authorization token")
       end
+
+      expires_time
     end
 
     def email_validation_required!(user:)

data/app/services/api_engine_base/jwt/login_create.rb

@@ -12,7 +12,7 @@ module ApiEngineBase::Jwt
 
     def payload
       {
-        expires_at: ApiEngineBase.config.jwt.ttl.from_now.to_i,
+        generated_at: Time.now.to_i,
         user_id: user.id,
         verifier_token: user.retreive_verifier_token!,
       }