command_tower 0.4.0 → 0.11.0

data/app/workflows/command_tower/workflows/admin/scope_resolution.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Admin
+      module ScopeResolution
+        module_function
+
+        def resolve(tool_id:, user:, scope_value:)
+          CommandTower::AdminScope::Resolve.call(tool_id:, principal: user, scope_value:)
+        rescue CommandTower::Errors::ForbiddenError => error
+          CommandTower::Workflows::WorkflowResult.failure(errors: [error], http_status: :forbidden)
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/admin/users/error_mapping.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Admin
+      module Users
+        module ErrorMapping
+          module_function
+
+          def http_status_for(error)
+            case error
+            when CommandTower::Errors::ValidationError
+              :unprocessable_entity
+            when CommandTower::Errors::ForbiddenError
+              :forbidden
+            when CommandTower::Errors::NotFoundError
+              :not_found
+            else
+              :internal_server_error
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/admin/users/identity_mutation.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Admin
+      module Users
+        module IdentityMutation
+          module_function
+
+          def resolve_target(id:, principal:, scope_value:)
+            CommandTower::SharedSequences::Admin::Users::ResolveScopedUser.call(
+              id:,
+              principal:,
+              scope_value:
+            )
+          end
+
+          def map_service_failure(result)
+            CommandTower::Workflows::WorkflowResult.failure(
+              errors: result.errors,
+              http_status: CommandTower::Workflows::Admin::Users::ErrorMapping.http_status_for(
+                result.errors.first
+              )
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/admin/users/list_assignable_roles_workflow.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Admin
+      module Users
+        class ListAssignableRolesWorkflow < CommandTower::Workflows::ApplicationWorkflow
+          retry_strategy :none
+
+          def call
+            listed = CommandTower::Services::Admin::Users::ListAssignableRoles.call
+            unless listed.success?
+              return failure(
+                errors: listed.errors,
+                http_status: ErrorMapping.http_status_for(listed.errors.first)
+              )
+            end
+
+            success(
+              payload: CommandTower::Serializers::Admin::Users::AssignableRolesSerializer.serialize(
+                listed.data[:roles]
+              ),
+              http_status: :ok
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/admin/users/list_workflow.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Admin
+      module Users
+        class ListWorkflow < CommandTower::Workflows::ApplicationWorkflow
+          retry_strategy :none
+
+          def call(limit:, offset:, search: nil, user:, scope_value: nil)
+            scope_result = resolve_scope(user:, scope_value:)
+            return scope_result if scope_result.is_a?(CommandTower::Workflows::WorkflowResult)
+
+            listed = CommandTower::Services::Admin::Users::List.call(
+              limit:,
+              offset:,
+              search:,
+              principal: user,
+              scope_context: scope_result
+            )
+            return result_or_failure(listed) unless listed.success?
+
+            payload = listed.data[:users].map do |user|
+              CommandTower::Serializers::Admin::Users::UserSerializer.serialize(user)
+            end
+            meta = CommandTower::Serializers::Admin::Users::PaginationMetaSerializer.serialize(
+              listed.data[:pagination]
+            )
+            success(payload:, meta:, http_status: :ok)
+          end
+
+          private
+
+          def resolve_scope(user:, scope_value:)
+            CommandTower::Workflows::Admin::ScopeResolution.resolve(
+              tool_id: "users",
+              user:,
+              scope_value:
+            )
+          end
+
+          def result_or_failure(result)
+            failure(
+              errors: result.errors,
+              http_status: CommandTower::Workflows::Admin::Users::ErrorMapping.http_status_for(
+                result.errors.first
+              )
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/admin/users/set_email_validated_workflow.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Admin
+      module Users
+        class SetEmailValidatedWorkflow < CommandTower::Workflows::ApplicationWorkflow
+          retry_strategy :none
+
+          def call(id:, user:, email_validated:, scope_value: nil)
+            resolved = IdentityMutation.resolve_target(id:, principal: user, scope_value:)
+            return resolved if resolved.is_a?(CommandTower::Workflows::WorkflowResult)
+
+            target = resolved.user
+            previous = target.email_validated
+
+            transaction do
+              result = CommandTower::Services::Admin::Users::SetEmailValidated.call(
+                user: target,
+                email_validated:
+              )
+              fail_transaction!(IdentityMutation.map_service_failure(result)) unless result.success?
+
+              updated = result.data[:user]
+              if result.data[:changed]
+                audit(
+                  :admin_user_email_validation_changed,
+                  subject: updated,
+                  affected_user: updated,
+                  changes: { email_validated: { from: previous, to: updated.email_validated } },
+                  attribution_mode: :admin_direct
+                )
+              end
+
+              success(
+                payload: CommandTower::Serializers::Admin::Users::UserSerializer.serialize(updated),
+                http_status: :ok
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/admin/users/show_workflow.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Admin
+      module Users
+        class ShowWorkflow < CommandTower::Workflows::ApplicationWorkflow
+          retry_strategy :none
+
+          def call(id:, user:, scope_value: nil)
+            scope_result = resolve_scope(user:, scope_value:)
+            return scope_result if scope_result.is_a?(CommandTower::Workflows::WorkflowResult)
+
+            shown = CommandTower::Services::Admin::Users::Show.call(
+              id:,
+              principal: user,
+              scope_context: scope_result
+            )
+            return result_or_failure(shown) unless shown.success?
+
+            payload = CommandTower::Serializers::Admin::Users::UserSerializer.serialize(
+              shown.data[:user]
+            )
+            success(payload:, http_status: :ok)
+          end
+
+          private
+
+          def resolve_scope(user:, scope_value:)
+            CommandTower::Workflows::Admin::ScopeResolution.resolve(
+              tool_id: "users",
+              user:,
+              scope_value:
+            )
+          end
+
+          def result_or_failure(result)
+            failure(
+              errors: result.errors,
+              http_status: CommandTower::Workflows::Admin::Users::ErrorMapping.http_status_for(
+                result.errors.first
+              )
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/admin/users/update_email_workflow.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Admin
+      module Users
+        class UpdateEmailWorkflow < CommandTower::Workflows::ApplicationWorkflow
+          retry_strategy :none
+
+          def call(id:, user:, email:, scope_value: nil)
+            resolved = IdentityMutation.resolve_target(id:, principal: user, scope_value:)
+            return resolved if resolved.is_a?(CommandTower::Workflows::WorkflowResult)
+
+            target = resolved.user
+
+            transaction do
+              result = CommandTower::Services::Admin::Users::UpdateEmail.call(
+                user: target,
+                email:
+              )
+              fail_transaction!(IdentityMutation.map_service_failure(result)) unless result.success?
+
+              updated = result.data[:user]
+              if result.data[:changed]
+                audit(
+                  :admin_user_email_changed,
+                  subject: updated,
+                  affected_user: updated,
+                  changes: {},
+                  metadata: { email_changed: true },
+                  attribution_mode: :admin_direct
+                )
+              end
+
+              success(
+                payload: CommandTower::Serializers::Admin::Users::UserSerializer.serialize(updated),
+                http_status: :ok
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/admin/users/update_name_workflow.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Admin
+      module Users
+        class UpdateNameWorkflow < CommandTower::Workflows::ApplicationWorkflow
+          retry_strategy :none
+
+          def call(id:, user:, first_name:, last_name:, scope_value: nil)
+            resolved = IdentityMutation.resolve_target(id:, principal: user, scope_value:)
+            return resolved if resolved.is_a?(CommandTower::Workflows::WorkflowResult)
+
+            target = resolved.user
+            previous = { first_name: target.first_name, last_name: target.last_name }
+
+            transaction do
+              result = CommandTower::Services::Admin::Users::UpdateName.call(
+                user: target,
+                first_name:,
+                last_name:
+              )
+              fail_transaction!(IdentityMutation.map_service_failure(result)) unless result.success?
+
+              updated = result.data[:user]
+              if result.data[:changed]
+                audit(
+                  :admin_user_name_changed,
+                  subject: updated,
+                  affected_user: updated,
+                  changes: {
+                    first_name: { from: previous[:first_name], to: updated.first_name },
+                    last_name: { from: previous[:last_name], to: updated.last_name }
+                  },
+                  attribution_mode: :admin_direct
+                )
+              end
+
+              success(
+                payload: CommandTower::Serializers::Admin::Users::UserSerializer.serialize(updated),
+                http_status: :ok
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/admin/users/update_roles_workflow.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Admin
+      module Users
+        class UpdateRolesWorkflow < CommandTower::Workflows::ApplicationWorkflow
+          retry_strategy :none
+
+          def call(id:, user:, roles:, scope_value: nil)
+            resolved = IdentityMutation.resolve_target(id:, principal: user, scope_value:)
+            return resolved if resolved.is_a?(CommandTower::Workflows::WorkflowResult)
+
+            target = resolved.user
+            policy = CommandTower::Services::Admin::Users::RoleAssignmentPolicy.call(
+              actor: user,
+              target:,
+              desired_roles: roles
+            )
+            return IdentityMutation.map_service_failure(policy) unless policy.success?
+
+            transaction do
+              result = CommandTower::Services::Admin::Users::ReplaceUserRoles.call(
+                user: target,
+                desired_roles: policy.data[:desired_roles]
+              )
+              fail_transaction!(IdentityMutation.map_service_failure(result)) unless result.success?
+
+              updated = result.data[:user]
+              if result.data[:changed]
+                Array(result.data[:assigned_roles]).each do |role_name|
+                  audit(
+                    :role_assigned,
+                    subject: updated,
+                    affected_user: updated,
+                    changes: { role: { from: nil, to: role_name.to_s } },
+                    attribution_mode: :admin_direct
+                  )
+                end
+                Array(result.data[:revoked_roles]).each do |role_name|
+                  audit(
+                    :role_revoked,
+                    subject: updated,
+                    affected_user: updated,
+                    changes: { role: { from: role_name.to_s, to: nil } },
+                    attribution_mode: :admin_direct
+                  )
+                end
+              end
+
+              success(
+                payload: CommandTower::Serializers::Admin::Users::UserSerializer.serialize(updated),
+                http_status: :ok
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/admin/users/update_username_workflow.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Admin
+      module Users
+        class UpdateUsernameWorkflow < CommandTower::Workflows::ApplicationWorkflow
+          retry_strategy :none
+
+          def call(id:, user:, username:, scope_value: nil)
+            resolved = IdentityMutation.resolve_target(id:, principal: user, scope_value:)
+            return resolved if resolved.is_a?(CommandTower::Workflows::WorkflowResult)
+
+            target = resolved.user
+            previous_username = target.username
+
+            transaction do
+              result = CommandTower::Services::Admin::Users::UpdateUsername.call(
+                user: target,
+                username:
+              )
+              fail_transaction!(IdentityMutation.map_service_failure(result)) unless result.success?
+
+              updated = result.data[:user]
+              if result.data[:changed]
+                audit(
+                  :admin_user_username_changed,
+                  subject: updated,
+                  affected_user: updated,
+                  changes: { username: { from: previous_username, to: updated.username } },
+                  attribution_mode: :admin_direct
+                )
+              end
+
+              success(
+                payload: CommandTower::Serializers::Admin::Users::UserSerializer.serialize(updated),
+                http_status: :ok
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/admin/workspace/manifest_workflow.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Admin
+      module Workspace
+        class ManifestWorkflow < CommandTower::Workflows::ApplicationWorkflow
+          retry_strategy :none
+
+          def call(user:)
+            result = CommandTower::Services::Admin::Workspace::Manifest.call(user:)
+            unless result.success?
+              return failure(errors: result.errors, http_status: :unprocessable_entity)
+            end
+
+            success(
+              payload: CommandTower::Serializers::Admin::Workspace::ManifestSerializer.serialize(result.data[:tools]),
+              http_status: :ok
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/application_workflow.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    class ApplicationWorkflow
+      include CommandTower::Transactional
+      include CommandTower::Execution::ContextAccess
+      include CommandTower::Logging::LifecycleDeclaration
+      include CommandTower::Impersonation::ActivityDeclaration
+      log_lifecycle!
+
+      TransactionFailure = CommandTower::Transactional::TransactionFailure
+      InvalidTransactionResult = CommandTower::Transactional::InvalidTransactionResult
+
+      ALLOWED_RETRY_STRATEGIES = %i[none delayed_continuation scheduled_cadence].freeze
+
+      protected :transaction, :fail_transaction!
+
+      # Programmer error: deferred result used with a strategy that forbids continuation.
+      class InvalidDeferredResult < StandardError; end
+
+      # Programmer error: delayed continuation requires a job instance to replay.
+      class DelayedContinuationRequiresJob < StandardError; end
+
+      class << self
+        def call(**args)
+          validate_retry_strategy!
+          CommandTower::Events.around_execution(layer: :workflow, subject: name, log_lifecycle: lifecycle_loggable?) do |record|
+            begin
+              record[:result] = new.call(**args)
+            rescue TransactionFailure => e
+              record[:result] = e.result
+            rescue InvalidTransactionResult
+              raise
+            rescue StandardError => e
+              record[:unexpected] = e
+              record[:result] = WorkflowResult.failure(
+                errors: [CommandTower::Errors::InternalError.new(cause: e)],
+                http_status: :internal_server_error
+              )
+            end
+            mark_impersonation_activity!(record[:result])
+          end
+        end
+
+        # Job transport entry. Unexpected exceptions re-raise. Deferred continuation
+        # is scheduled by CommandTower when the strategy is :delayed_continuation.
+        def call_from_job(job: nil, continuation_attempt: 1, **args)
+          validate_retry_strategy!
+          result = invoke_for_job(**args)
+          handle_job_result(
+            result,
+            job: job,
+            continuation_attempt: Integer(continuation_attempt),
+            **args
+          )
+        end
+
+        def retry_strategy(strategy, max_attempts: nil)
+          @retry_strategy = strategy&.to_sym
+          @continuation_max_attempts = max_attempts
+        end
+
+        def declared_retry_strategy
+          @retry_strategy
+        end
+
+        def continuation_max_attempts
+          @continuation_max_attempts
+        end
+
+        def mark_impersonation_activity!(result)
+          return unless impersonation_activity?
+          return unless result.is_a?(CommandTower::Workflows::WorkflowResult) && result.success?
+
+          CommandTower::Current.impersonation_activity_recorded = true
+        end
+        private :mark_impersonation_activity!
+
+        def validate_retry_strategy!
+          raise "#{name} must declare retry_strategy (:none, :delayed_continuation, or :scheduled_cadence)" if @retry_strategy.nil?
+
+          if @retry_strategy == :sidekiq
+            raise "#{name} retry_strategy :sidekiq is not supported; use :delayed_continuation"
+          end
+
+          unless ALLOWED_RETRY_STRATEGIES.include?(@retry_strategy)
+            raise "#{name} retry_strategy #{@retry_strategy.inspect} is invalid " \
+                  "(allowed: :none, :delayed_continuation, :scheduled_cadence)"
+          end
+
+          if @retry_strategy == :delayed_continuation
+            max = @continuation_max_attempts
+            unless max.is_a?(Integer) && max >= 1
+              raise "#{name} retry_strategy :delayed_continuation requires max_attempts: >= 1"
+            end
+          elsif !@continuation_max_attempts.nil?
+            raise "#{name} retry_strategy #{@retry_strategy.inspect} cannot declare max_attempts"
+          end
+        end
+
+        private
+
+        def invoke_for_job(**args)
+          CommandTower::Events.around_execution(layer: :workflow, subject: name, log_lifecycle: lifecycle_loggable?) do |record|
+            begin
+              record[:result] = new.call(**args)
+            rescue TransactionFailure => e
+              record[:result] = e.result
+            rescue StandardError => e
+              record[:unexpected] = e
+              raise
+            end
+          end
+        end
+
+        def handle_job_result(result, job:, continuation_attempt:, **args)
+          if result.deferred?
+            return handle_deferred(result, job: job, continuation_attempt: continuation_attempt, **args)
+          end
+
+          if result.failure? && result.meta[:propagate_to_job]
+            error = Array(result.errors).first
+            raise error if error
+
+            raise StandardError, "#{name} failed for job without errors"
+          end
+
+          result
+        end
+
+        def handle_deferred(result, job:, continuation_attempt:, **args)
+          unless @retry_strategy == :delayed_continuation
+            raise InvalidDeferredResult,
+                  "#{name} returned deferred but retry_strategy is #{@retry_strategy.inspect}"
+          end
+
+          max_attempts = Integer(@continuation_max_attempts)
+          if continuation_attempt >= max_attempts
+            raise CommandTower::Errors::ContinuationExhaustedError.new(
+              details: { attempt: continuation_attempt, max_attempts: max_attempts }
+            )
+          end
+
+          if job.nil?
+            raise DelayedContinuationRequiresJob,
+                  "#{name} deferred continuation requires call_from_job(job:)"
+          end
+
+          wait = [Integer(result.retry_after), 1].max
+          job.class.set(wait: wait.seconds).perform_later(
+            **args.merge(continuation_attempt: continuation_attempt + 1)
+          )
+          result
+        end
+      end
+
+      def call(**)
+        raise NotImplementedError
+      end
+
+      protected
+
+      def success(payload:, http_status: :ok, response_effects: nil, meta: {})
+        WorkflowResult.success(payload:, http_status:, response_effects:, meta:)
+      end
+
+      def failure(errors:, http_status:, response_effects: nil, meta: {})
+        WorkflowResult.failure(errors:, http_status:, response_effects:, meta:)
+      end
+
+      def deferred(reason:, retry_after:, payload: {}, http_status: :accepted, response_effects: nil, meta: {})
+        WorkflowResult.deferred(
+          reason:,
+          retry_after:,
+          payload:,
+          http_status:,
+          response_effects:,
+          meta:
+        )
+      end
+
+      private
+
+      def acceptable_success_result?(result)
+        result.is_a?(WorkflowResult) && result.success?
+      end
+
+      def acceptable_failure_result?(result)
+        result.is_a?(WorkflowResult) && result.failure?
+      end
+
+      def fail_transaction_type_error_message
+        "fail_transaction! requires a failed WorkflowResult"
+      end
+
+      def invalid_success_result_message(result)
+        unless result.is_a?(WorkflowResult)
+          return "transaction block must return a WorkflowResult; got #{result.class}"
+        end
+
+        "transaction block returned a non-success WorkflowResult; " \
+          "use fail_transaction!(failure(...)) for expected failures"
+      end
+    end
+  end
+end