command_tower 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4f9f21fbcb6005b0181cb027daaf67f3df5a2a905cbe199b0b8e7bf1f252e72
-  data.tar.gz: d1e6e49ef8ff63818e0c80bb39352087fc6a448a70b264b8789e9851b93d3687
+  metadata.gz: 634d9c131508812e791849829e9cfe172b41c2508d25d3eefbad69a61ecb4228
+  data.tar.gz: c2c38369dd2c60e1656e0f607bda06518d32590baba669c05c1072e6cf6ac97b
 SHA512:
-  metadata.gz: 2b9751dcdb8d2ed1f970408e296fe2640a8af1bccf8eb5e834745779cb6f201984f29ca1a8a9e10240e477b6ec12bf4a25703cb5a77e1a577633658184e3897e
-  data.tar.gz: 323c22c584f970e4ff187c6eaba3a66302248242f505eb9470687d704b77bc554fdf0eaa074d1087f8014e0ee9b046786b1512befbf7b3db74263ee8db95fe00
+  metadata.gz: 12c681eeaeefcb8ed919cbb2b0eaf77849c74eccec569d99ead80e1cafecd0b69c106ed12c8902b2e294f1886cd8b148a1ab798a46695e059bd6f92eaa9d2ff0
+  data.tar.gz: a28884515dc4d80c789e62a1b0971c8fadbb2dcdd3d5ad3c3df6d2b6740bbea5c2c378418b604b171eb42e2ba7c4adc8a89087e6ffc53981b8ee7771e7f8495a

data/README.md

@@ -34,7 +34,7 @@ Additionally, You can check out [RSpec Integration Testing](/spec/integration_te
 
 CommandTower 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)
+For more info, check out [Models ReadMe](docs/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.
@@ -55,5 +55,8 @@ ServiceBase is built on top of Interactor. The ServiceBase is the heart of all l
 
 For more info, check out [ServiceBase ReadMe](app/services/command_tower/README.md)
 
+## Pagination
+Pagination is available on routes when explicitly set. There are a subset of routes available as part of this engine. Pagination is available to be used in downstream services as well. For more info, check out [Pagination ReadMe](docs/pagination.md)
+
 ## License
 The engine is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/controllers/command_tower/admin_controller.rb

@@ -3,18 +3,23 @@
 module CommandTower
   class AdminController < ::CommandTower::ApplicationController
     include CommandTower::SchemaHelper
+    include CommandTower::PaginationHelper
 
     before_action :authenticate_user!
     before_action :authorize_user!
     before_action :user!, only: [:modify, :modify_role]
 
-    # Pagination is needed here
+    # GET: /admin
+    # Pagination Available
     def show
-      schemafied_users = User.all.map { CommandTower::Schema::User.convert_user_object(user: _1) }
-      schema = CommandTower::Schema::Admin::Users.new(users: schemafied_users)
+      schema = CommandTower::AdminService::Users.(
+        user: admin_user,
+        pagination: pagination_values,
+      ).schema
       schema_succesful!(status: 200, schema:)
     end
 
+    # POST: /modify
     def modify
       result = CommandTower::UserAttributes::Modify.(user:, admin_user:, **modify_params)
       if result.success?
@@ -35,6 +40,7 @@ module CommandTower
       end
     end
 
+    # POST: /modify/role
     def modify_role
       result = CommandTower::UserAttributes::Roles.(user:, admin_user:, roles: params[:roles] || [])
       if result.success?

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

@@ -13,6 +13,7 @@ module CommandTower
           schema = CommandTower::Schema::PlainText::LoginResponse.new(
             token: result.token,
             header_name: AUTHENTICATION_HEADER,
+            user: CommandTower::Schema::User.convert_user_object(user: result.user),
             message: "Successfully logged user in"
           )
           status = 201

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

@@ -4,12 +4,14 @@ module CommandTower
   module Inbox
     class MessageController < ::CommandTower::ApplicationController
       include CommandTower::SchemaHelper
+      include CommandTower::PaginationHelper
 
       before_action :authenticate_user!
 
       # GET: /inbox/messages
+      # Pagination Available
       def metadata
-        result = CommandTower::InboxService::Message::Metadata.(user: current_user)
+        result = CommandTower::InboxService::Message::Metadata.(user: current_user, pagination: pagination_values)
         if result.success?
           schema = result.metadata
           status = 200

data/app/helpers/command_tower/pagination_helper.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module PaginationHelper
+    def pagination_values
+      (pagination_from_body || pagination_from_query || {}).compact
+    end
+
+    def pagination_from_body
+      pagination = params[:pagination]
+      return nil unless pagination.is_a?(ActionController::Parameters) || pagination.is_a?(Hash)
+
+      {
+        page: pagination_safe_integer_convert(pagination[:page]),
+        limit: pagination_safe_integer_convert(pagination[:limit]),
+        cursor: pagination_safe_integer_convert(pagination[:cursor]),
+      }
+    end
+
+    def pagination_from_query
+      return nil unless safe_boolean(value: params[:pagination]) == true
+
+      {
+        page: pagination_safe_integer_convert(params[:page]),
+        limit: pagination_safe_integer_convert(params[:limit]),
+        cursor: pagination_safe_integer_convert(params[:cursor]),
+      }
+    end
+
+    def pagination_safe_integer_convert(value, type = Integer)
+      return if value.presence.nil?
+
+      if value.to_i.to_s == value
+        value.to_i
+      else
+        nil
+      end
+    end
+  end
+end

data/app/services/command_tower/admin_service/users.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module AdminService
+    class Users < CommandTower::ServiceBase
+      include CommandTower::PaginationServiceHelper
+
+      on_argument_validation :fail_early
+
+      # to be used for auditing later maybe?
+      validate :user, is_a: User, required: true
+
+      def call
+        schemafied_users = query.map { CommandTower::Schema::User.convert_user_object(user: _1) }
+        context.schema = CommandTower::Schema::Admin::Users.new(
+          users: schemafied_users,
+          count: schemafied_users.count,
+          pagination: pagination_schema,
+        )
+      end
+
+      def default_query
+        ::User.all.select(*CommandTower.config.user.default_attributes)
+      end
+    end
+  end
+end

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

@@ -4,25 +4,31 @@ module CommandTower
   module InboxService
     module Message
       class Metadata < CommandTower::ServiceBase
+        include CommandTower::PaginationServiceHelper
+
         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|
+          entities = query.map do |message|
             CommandTower::Schema::Inbox::MessageEntity.new(
-              title:  message.title,
-              id:  message.id,
-              viewed:  message.viewed,
+              id: message.id,
+              title: message.title,
+              viewed: message.viewed,
             )
           end
 
           params = {
-            entities: entities.nil? ? nil : entities,
             count: entities.length,
-          }
+            entities: entities.nil? ? nil : entities,
+            pagination: pagination_schema,
+          }.compact
+          context.metadata = CommandTower::Schema::Inbox::Metadata.new(**params)
+        end
 
-          context.metadata = CommandTower::Schema::Inbox::Metadata.new(**params.compact)
+        def default_query
+          ::Message.where(user:).select(:id, :title, :viewed)
         end
       end
     end

data/app/services/command_tower/pagination_service_helper.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module PaginationServiceHelper
+    def query
+      return default_query if pagination_params.empty?
+
+      context.pagination_used = true
+
+      default_query.offset(pagination_params[:offset]).limit(pagination_params[:limit])
+    end
+
+    def default_query
+      raise NoMethodError, "Method must be defined on base class"
+    end
+
+    def pagination_schema
+      return nil unless context.pagination_used
+
+      base_params = {
+        limit: pagination_params[:limit],
+        cursor: pagination_params[:offset],
+      }
+      query = base_params.to_query
+      current = CommandTower::Schema::Page.new(query:, **base_params)
+
+      base_params[:cursor] += pagination_params[:limit]
+      query = base_params.to_query
+      next_page = CommandTower::Schema::Page.new(query:, **base_params)
+
+      count_available = default_query.size
+      total_pages = count_available / pagination_params[:limit]
+      # when offset is zero, it returns 0...Min page is 1
+      base_current_page = (pagination_params[:offset].to_f / pagination_params[:limit].to_f)
+      if pagination_params[:offset] % pagination_params[:limit] == 0
+        current_page = (base_current_page + 1).to_i
+      else
+        current_page = base_current_page.ceil
+      end
+      # current_page = [, 1].max
+      # Ensure we cannot go negative when no elements are returned
+      remaining_pages = [total_pages - current_page, 0].max
+
+      CommandTower::Schema::Pagination.new(
+        count_available:,
+        total_pages:,
+        current_page:,
+        remaining_pages:,
+        current:,
+        next: next_page,
+      )
+    end
+
+    def pagination_params
+      return {} if context.pagination.presence.nil?
+
+      __params = { limit: pagination_limit }
+      if pagination_cursor
+        # When cursor is provided, we take cursor and limit as injections
+        __params[:offset] = pagination_cursor
+      else
+        # When cursor is not provided, use default of page and limit
+        __params[:offset] = pagination_page * pagination_limit
+      end
+
+      __params.compact
+    end
+
+    def pagination_cursor
+      return if context.pagination[:cursor].nil?
+
+      # Cursor must be greater than or equal to 0
+      [context.pagination[:cursor].to_i, 0].max
+    end
+
+    def pagination_page
+      # Page must be greater than or equal to 0
+      # Incoming page is 1 indexed -- must convert to 0 indexed to work properly
+      [(context.pagination[:page] || 1).to_i, 1].max - 1
+    end
+
+    def pagination_limit
+      return CommandTower.config.pagination.limit if context.pagination[:limit].nil?
+
+      [context.pagination[:limit].to_i, 1].max
+    end
+  end
+end

data/lib/command_tower/configuration/config.rb

@@ -2,16 +2,17 @@
 
 require "singleton"
 require "class_composer"
+require "command_tower/configuration/admin/config"
+require "command_tower/configuration/application/config"
+require "command_tower/configuration/authorization/config"
 require "command_tower/configuration/base"
 require "command_tower/configuration/email/config"
 require "command_tower/configuration/jwt/config"
 require "command_tower/configuration/login/config"
 require "command_tower/configuration/otp/config"
-require "command_tower/configuration/username/config"
-require "command_tower/configuration/application/config"
-require "command_tower/configuration/admin/config"
-require "command_tower/configuration/authorization/config"
+require "command_tower/configuration/pagination/config"
 require "command_tower/configuration/user/config"
+require "command_tower/configuration/username/config"
 
 module CommandTower
   module Configuration
@@ -66,6 +67,11 @@ module CommandTower
         allowed: Configuration::Admin::Config,
         default: Configuration::Admin::Config.new
 
+      add_composer :pagination,
+        desc: "Pagination configuration for the app",
+        allowed: Configuration::Pagination::Config,
+        default: Configuration::Pagination::Config.new
+
       # To be Deleted
       add_composer :otp,
         desc: "One Time Password generation is used for ease in quickly validating a users actions. This is good for short term validation requirements as opposed to UserSecrets",

data/lib/command_tower/configuration/pagination/config.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Configuration
+    module Pagination
+      class Config < ::CommandTower::Configuration::Base
+        include ClassComposer::Generator
+
+        add_composer :limit,
+          desc: "Default Limit for pagination return when not present on service or query/body. Negative values are treated like no limit",
+          allowed: Integer,
+          default: 10
+      end
+    end
+  end
+end

data/lib/command_tower/schema/admin/users.rb

@@ -1,14 +1,15 @@
 # frozen_string_literal: true
 
 require "command_tower/schema/user"
-require "command_tower/schema/page"
+require "command_tower/schema/pagination"
 
 module CommandTower
   module Schema
     module Admin
       class Users < JsonSchematize::Generator
         add_field name: :users, array_of_types: true, type: CommandTower::Schema::User
-        add_field name: :pagination, type: CommandTower::Schema::Page, required: false
+        add_field name: :count, type: Integer, required: false
+        add_field name: :pagination, type: CommandTower::Schema::Pagination, required: false
       end
     end
   end

data/lib/command_tower/schema/inbox/message_blast_metadata.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "command_tower/schema/inbox/message_blast_entity"
-require "command_tower/schema/page"
+require "command_tower/schema/pagination"
 
 module CommandTower
   module Schema
@@ -9,7 +9,7 @@ module CommandTower
       class MessageBlastMetadata < JsonSchematize::Generator
         add_field name: :entities, array_of_types: true, type: CommandTower::Schema::Inbox::MessageBlastEntity, required: false
         add_field name: :count, type: Integer
-        add_field name: :pagination, type: CommandTower::Schema::Page, required: false
+        add_field name: :pagination, type: CommandTower::Schema::Pagination, required: false
       end
     end
   end

data/lib/command_tower/schema/inbox/metadata.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "command_tower/schema/inbox/message_entity"
-require "command_tower/schema/page"
+require "command_tower/schema/pagination"
 
 module CommandTower
   module Schema
@@ -11,7 +11,7 @@ module CommandTower
 
         add_field name: :entities, array_of_types: true, type: CommandTower::Schema::Inbox::MessageEntity, required: false
         add_field name: :count, type: Integer
-        add_field name: :pagination, type: CommandTower::Schema::Page, required: false
+        add_field name: :pagination, type: CommandTower::Schema::Pagination, required: false
       end
     end
   end

data/lib/command_tower/schema/page.rb

@@ -3,12 +3,9 @@
 module CommandTower
   module Schema
     class Page < JsonSchematize::Generator
-      schema_default option: :dig_type, value: :string
-
-      add_field name: :count, type: Integer
       add_field name: :cursor, type: Integer
       add_field name: :limit, type: Integer
-      add_field name: :next, type: String
+      add_field name: :query, type: String
     end
   end
 end

data/lib/command_tower/schema/pagination.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "command_tower/schema/page"
+
+module CommandTower
+  module Schema
+    class Pagination < JsonSchematize::Generator
+      add_field name: :current, type: Page
+      add_field name: :next, type: Page, required: false
+      add_field name: :count_available, type: Integer, required: false
+      add_field name: :current_page, type: Integer, required: false
+      add_field name: :remaining_pages, type: Integer, required: false
+      add_field name: :total_pages, type: Integer, required: false
+    end
+  end
+end

data/lib/command_tower/schema/plain_text/login_response.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "command_tower/schema/user"
+
 module CommandTower
   module Schema
     module PlainText
@@ -7,6 +9,7 @@ module CommandTower
         add_field name: :token, type: String
         add_field name: :header_name, type: String
         add_field name: :message, type: String
+        add_field name: :user, type: CommandTower::Schema::User
       end
     end
   end

data/lib/command_tower/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CommandTower
-  VERSION = "0.3.1"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: command_tower
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - matt-taylor
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-03-02 00:00:00.000000000 Z
+date: 2025-05-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rotp
@@ -133,6 +133,7 @@ files:
 - app/controllers/command_tower/user_controller.rb
 - app/controllers/command_tower/username_controller.rb
 - app/helpers/command_tower/application_helper.rb
+- app/helpers/command_tower/pagination_helper.rb
 - app/helpers/command_tower/schema_helper.rb
 - app/jobs/command_tower/application_job.rb
 - app/mailers/command_tower/application_mailer.rb
@@ -143,6 +144,7 @@ files:
 - app/models/user.rb
 - app/models/user_secret.rb
 - app/services/command_tower/README.md
+- app/services/command_tower/admin_service/users.rb
 - app/services/command_tower/argument_validation.rb
 - app/services/command_tower/argument_validation/README.md
 - app/services/command_tower/argument_validation/class_methods.rb
@@ -168,6 +170,7 @@ files:
 - app/services/command_tower/login_strategy/plain_text/email_verification/send.rb
 - app/services/command_tower/login_strategy/plain_text/email_verification/verify.rb
 - app/services/command_tower/login_strategy/plain_text/login.rb
+- app/services/command_tower/pagination_service_helper.rb
 - app/services/command_tower/secrets.rb
 - app/services/command_tower/secrets/cleanse.rb
 - app/services/command_tower/secrets/generate.rb
@@ -200,6 +203,7 @@ files:
 - lib/command_tower/configuration/login/strategy/plain_text/email_verify.rb
 - lib/command_tower/configuration/login/strategy/plain_text/lockable.rb
 - lib/command_tower/configuration/otp/config.rb
+- lib/command_tower/configuration/pagination/config.rb
 - lib/command_tower/configuration/user/config.rb
 - lib/command_tower/configuration/username/check.rb
 - lib/command_tower/configuration/username/config.rb
@@ -218,6 +222,7 @@ files:
 - lib/command_tower/schema/inbox/metadata.rb
 - lib/command_tower/schema/inbox/modified.rb
 - lib/command_tower/schema/page.rb
+- lib/command_tower/schema/pagination.rb
 - lib/command_tower/schema/plain_text/create_user_request.rb
 - lib/command_tower/schema/plain_text/create_user_response.rb
 - lib/command_tower/schema/plain_text/email_verify_request.rb
@@ -229,8 +234,8 @@ files:
 - lib/command_tower/schema/user.rb
 - lib/command_tower/spec_helper.rb
 - lib/command_tower/version.rb
-- lib/generators/api_engine_base/configure/USAGE
-- lib/generators/api_engine_base/configure/configure_generator.rb
+- lib/generators/command_tower/configure/USAGE
+- lib/generators/command_tower/configure/configure_generator.rb
 - lib/tasks/auto_annotate_models.rake
 homepage: https://github.com/matt-taylor/command_tower
 licenses: