command_tower 0.4.0 → 0.10.0

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

@@ -1,86 +1,113 @@
 # frozen_string_literal: true
 
 module CommandTower::Jwt
-  class AuthenticateUser < CommandTower::ServiceBase
+  class AuthenticateUser
+    INVALID_TOKEN_MSG = "Unauthorized Access. Invalid Authorization token"
+    STALE_TOKEN_MSG = "Unauthorized Access. Token is no longer valid"
+    EMAIL_VERIFICATION_MSG = "Email must be verified to continue"
+    EMAIL_VERIFICATION_STATUS = 412
+
+    def self.call(token:, bypass_email_validation: false, with_reset: false)
+      new(token:, bypass_email_validation:, with_reset:).call
+    end
 
-    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 initialize(token:, bypass_email_validation: false, with_reset: false)
+      @token = token
+      @bypass_email_validation = !!bypass_email_validation
+      @with_reset = !!with_reset
+    end
 
     def call
-      result = Decode.(token:)
+      decoded = Decode.(token:)
+      return invalid_token if decoded.failure?
 
-      if result.failure?
-        context.fail!(msg: "Unauthorized Access. Invalid Authorization token")
-      end
-      payload = result.payload
+      payload = decoded.payload
 
-      expires_at = validate_generated_at!(generated_at: payload[:generated_at])
+      expires_at = expires_at_for(generated_at: payload[:generated_at])
+      return invalid_token if expires_at.nil?
 
-      user = User.find(payload[:user_id]) rescue nil
+      user = User.find_by(id: payload[:user_id])
       if user.nil?
         log_warn("user_id [#{payload[:user_id]}] was not found. Cannot Continue")
-        context.fail!(msg: "Unauthorized Access. Invalid Authorization token")
+        return invalid_token
       end
 
-      if user.verifier_token == payload[:verifier_token]
-        context.user = user
-      else
-        context.fail!(msg: "Unauthorized Access. Token is no longer valid")
+      unless user.verifier_token == payload[:verifier_token]
+        return AuthenticationOutcome.failure(msg: STALE_TOKEN_MSG)
       end
 
-      email_validation_required!(user:)
+      if email_validation_required?(user:)
+        return AuthenticationOutcome.failure(
+          msg: EMAIL_VERIFICATION_MSG,
+          status: EMAIL_VERIFICATION_STATUS,
+          user:
+        )
+      end
 
+      generated_token = nil
       if with_reset
-        context.generated_token = CommandTower::Jwt::LoginCreate.(user:).token
+        generated_token = LoginCreate.(user:).token
         expires_at = CommandTower.config.jwt.ttl.from_now.to_time
       end
 
-      context.expires_at = expires_at.to_s
+      AuthenticationOutcome.success(user:, expires_at: expires_at.to_s, generated_token:)
     end
 
-    def validate_generated_at!(generated_at:)
+    private
+
+    attr_reader :token, :bypass_email_validation, :with_reset
+
+    def invalid_token
+      AuthenticationOutcome.failure(msg: INVALID_TOKEN_MSG)
+    end
+
+    # Returns nil when the token cannot be trusted to carry a usable expiration.
+    def expires_at_for(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")
+        return nil
       end
 
       expires_time = begin
-        time = Time.at(generated_at)
-        time + CommandTower.config.jwt.ttl
-      rescue
+        Time.at(generated_at) + CommandTower.config.jwt.ttl
+      rescue StandardError
         nil
       end
 
       if expires_time.nil?
         log_warn("generated_at payload cannot be parsed. Cannot continue")
-        context.fail!(msg: "Unauthorized Access. Invalid Authorization token")
+        return nil
       end
 
       if expires_time < Time.now
         log_warn("generated_at is no longer valid. Must request new token")
-        context.fail!(msg: "Unauthorized Access. Invalid Authorization token")
+        return nil
       end
 
       expires_time
     end
 
-    def email_validation_required!(user:)
-      return unless CommandTower.config.login.plain_text.email_verify?
+    def email_validation_required?(user:)
+      return false unless CommandTower.config.login.plain_text.email_verify?
 
       if bypass_email_validation
         log_info("Bypassing email validation without checking if user should be able to continue")
-        return
+        return false
       end
 
-      return if user.email_validated
+      return false if user.email_validated
 
       log_info("User's email is not yet validated.")
-      result = CommandTower::LoginStrategy::PlainText::EmailVerification::Required.(user:)
 
-      if result.required
-        context.fail!(msg: "User's Email must be validated before they can continue")
-      end
+      CommandTower::LoginStrategy::PlainText::EmailVerification::Required.(user:).required?
+    end
+
+    def log_info(msg)
+      Rails.logger.info { "[#{self.class.name}] #{msg}" }
+    end
+
+    def log_warn(msg)
+      Rails.logger.warn { "[#{self.class.name}] #{msg}" }
     end
   end
 end

data/app/services/command_tower/jwt/authentication_outcome.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module CommandTower::Jwt
+  # Narrow value object describing the result of AuthenticateUser only.
+  # This is deliberately not a platform result type — do not reuse it elsewhere.
+  class AuthenticationOutcome
+    attr_reader :user, :expires_at, :generated_token, :status, :msg
+
+    def self.success(user:, expires_at:, generated_token: nil)
+      new(success: true, user:, expires_at:, generated_token:)
+    end
+
+    # `user` is carried on failures so callers can distinguish a known user who
+    # is blocked (e.g. email verification required) from an unidentified caller.
+    def self.failure(msg:, status: nil, user: nil)
+      new(success: false, msg:, status:, user:)
+    end
+
+    def initialize(success:, user: nil, expires_at: nil, generated_token: nil, status: nil, msg: nil)
+      @success = success
+      @user = user
+      @expires_at = expires_at
+      @generated_token = generated_token
+      @status = status
+      @msg = msg
+    end
+
+    def success?
+      @success
+    end
+
+    def failure?
+      !@success
+    end
+  end
+end

data/app/services/command_tower/jwt/decode.rb

@@ -3,19 +3,38 @@
 require "jwt"
 
 module CommandTower::Jwt
-  class Decode < CommandTower::ServiceBase
+  class Decode
+    ALGORITHM = "HS256"
 
-    validate :token, is_a: String, required: true, sensitive: true
+    DecodeOutcome = Data.define(:success, :payload, :headers, :msg) do
+      def self.success(payload:, headers: nil)
+        new(success: true, payload:, headers:, msg: nil)
+      end
 
-    def call
-      data = JWT.decode(token, CommandTower.config.jwt.hmac_secret, true, { algorithm: "HS256" })
+      def self.failure(msg:)
+        new(success: false, payload: nil, headers: nil, msg:)
+      end
 
-      context.payload = data[0].with_indifferent_access
-      context.headers = data[1].with_indifferent_access
+      def success?
+        success
+      end
+
+      def failure?
+        !success
+      end
+    end
+
+    def self.call(token:)
+      data = JWT.decode(token, CommandTower.config.jwt.hmac_secret, true, { algorithm: ALGORITHM })
+
+      DecodeOutcome.success(
+        payload: data[0].with_indifferent_access,
+        headers: data[1].with_indifferent_access
+      )
     rescue JWT::DecodeError => e
-      log_error(e)
+      Rails.logger.warn { "[#{name}] Failed to decode token: #{e.class.name}" }
 
-      context.fail!(msg: "Invalid Token")
+      DecodeOutcome.failure(msg: "Invalid Token")
     end
   end
 end

data/app/services/command_tower/jwt/encode.rb

@@ -3,13 +3,11 @@
 require "jwt"
 
 module CommandTower::Jwt
-  class Encode < CommandTower::ServiceBase
+  class Encode
+    ALGORITHM = "HS256"
 
-    validate :payload, is_a: Hash, required: true
-    validate :header, is_a: Hash, required: false
-
-    def call
-      context.token = JWT.encode(payload, CommandTower.config.jwt.hmac_secret, "HS256", header || {})
+    def self.call(payload:, header: nil)
+      JWT.encode(payload, CommandTower.config.jwt.hmac_secret, ALGORITHM, header || {})
     end
   end
 end

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

@@ -1,21 +1,20 @@
 # frozen_string_literal: true
 
 module CommandTower::Jwt
-  class LoginCreate < CommandTower::ServiceBase
-    on_argument_validation :fail_early
+  class LoginCreate
+    IssuedToken = Data.define(:token)
 
-    validate :user, is_a: User, required: true
-
-    def call
-      context.token = Encode.(payload:).token
+    def self.call(user:)
+      IssuedToken.new(token: Encode.(payload: payload_for(user)))
     end
 
-    def payload
+    def self.payload_for(user)
       {
         generated_at: Time.now.to_i,
         user_id: user.id,
         verifier_token: user.retreive_verifier_token!,
       }
     end
+    private_class_method :payload_for
   end
 end

data/app/services/command_tower/login_strategy/plain_text/email_verification/required.rb

@@ -1,20 +1,22 @@
 # frozen_string_literal: true
 
 module CommandTower::LoginStrategy::PlainText::EmailVerification
-  class Required < CommandTower::ServiceBase
-    validate :user, is_a: User, required: true
-
-    def call
-      context.reqired_after_time = reqired_after_time
-      context.required = Time.now > reqired_after_time
+  # Decides whether an unverified account has passed its grace period and must
+  # verify before it can keep authenticating.
+  class Required
+    Requirement = Data.define(:required, :required_after_time) do
+      def required? = required
     end
 
-    def reqired_after_time
-      user.created_at + email_verify.verify_email_required_within
+    def self.call(user:)
+      required_after_time = user.created_at + email_verify.verify_email_required_within
+
+      Requirement.new(required: Time.now > required_after_time, required_after_time:)
     end
 
-    def email_verify
+    def self.email_verify
       CommandTower.config.login.plain_text.email_verify
     end
+    private_class_method :email_verify
   end
 end

data/app/services/command_tower/messaging/accept/channel_delivery_result.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Accept
+      ChannelDeliveryResult = Data.define(:id, :channel_key, :status) do
+        def self.build(id:, channel_key:, status:)
+          new(id:, channel_key: channel_key.to_s, status: status.to_s).freeze
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/accept/coordinator.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Accept
+      # Domain orchestrator under Produce: validate → idempotency → plan → persist → schedule handoff.
+      # Not an ApplicationWorkflow (nested AW under Produce/host workflows is forbidden).
+      class Coordinator
+        def self.call(**kwargs)
+          new(**kwargs).call
+        end
+
+        def initialize(
+          recipient_id:,
+          notification_type_key:,
+          host_event_identity:,
+          title:,
+          body:,
+          metadata: nil,
+          preference_state: nil,
+          platform_enabled_channels:,
+          message_overrides: nil
+        )
+          @recipient_id = recipient_id
+          @notification_type_key = notification_type_key
+          @host_event_identity = host_event_identity
+          @title = title
+          @body = body
+          @metadata = metadata
+          @preference_state = preference_state
+          @platform_enabled_channels = platform_enabled_channels
+          @message_overrides = message_overrides
+        end
+
+        def call
+          request = {
+            recipient_id: @recipient_id,
+            notification_type_key: @notification_type_key,
+            host_event_identity: @host_event_identity,
+            title: @title,
+            body: @body,
+            metadata: @metadata,
+            preference_state: @preference_state,
+            platform_enabled_channels: @platform_enabled_channels,
+            message_overrides: @message_overrides,
+          }
+
+          OperationLogger.around(request:) do
+            validate_request!
+            fingerprint = RequestNormalizer.fingerprint(
+              title: @title,
+              body: @body,
+              metadata: @metadata,
+              preference_state: @preference_state,
+              platform_enabled_channels: @platform_enabled_channels,
+              message_overrides: @message_overrides,
+            )
+
+            existing = find_by_namespace
+            if existing
+              return resolve_existing(existing, fingerprint)
+            end
+
+            plan = plan!
+            persist_new!(request:, plan:, fingerprint:)
+          end
+        end
+
+        private
+
+        def validate_request!
+          errors = []
+          errors << "recipient_id is required" if blank?(@recipient_id)
+          errors << "notification_type_key is required" if blank?(@notification_type_key)
+          errors << "host_event_identity is required" if blank?(@host_event_identity)
+          errors << "title is required" if blank?(@title)
+          errors << "body is required" if blank?(@body)
+          if @platform_enabled_channels.nil?
+            errors << "platform_enabled_channels is required"
+          end
+          unless @preference_state.nil?
+            errors << "preference_state must not be supplied; CommandTower loads stored preferences"
+          end
+
+          raise ValidationError, errors.join("; ") if errors.any?
+        end
+
+        def blank?(value)
+          value.nil? || (value.respond_to?(:empty?) && value.empty?) ||
+            (value.is_a?(String) && value.strip.empty?)
+        end
+
+        def find_by_namespace
+          Messaging::Communication.find_by_idempotency_namespace(
+            user_id: @recipient_id,
+            notification_type_key: @notification_type_key,
+            host_event_identity: @host_event_identity,
+          )
+        end
+
+        def resolve_existing(communication, fingerprint)
+          if communication.accept_request_fingerprint == fingerprint
+            return Result.from_communication(
+              reload_aggregate(communication.id),
+              idempotent_replay: true,
+            )
+          end
+
+          raise IdempotencyConflictError,
+                "idempotency namespace already accepted with a different request"
+        end
+
+        def plan!
+          Planner.plan(
+            notification_type_key: @notification_type_key,
+            recipient_id: @recipient_id,
+            preference_state: nil,
+            platform_enabled_channels: @platform_enabled_channels,
+            message_overrides: @message_overrides,
+          )
+        rescue Planner::UnknownTypeError => e
+          raise UnknownTypeError, e.message
+        rescue Planner::IllegalOverrideError => e
+          raise IllegalOverrideError, e.message
+        rescue Planner::ImpossibleMandatoryPlanError => e
+          raise ImpossibleMandatoryPlanError, e.message
+        rescue Planner::InvalidEvaluationError => e
+          raise InvalidPreferenceError, e.message
+        rescue Preferences::InvalidPreferenceStateError => e
+          raise InvalidPreferenceError, e.message
+        rescue Preferences::StoreError => e
+          raise PersistenceError, e.message
+        rescue Preferences::UnknownTypeError => e
+          raise UnknownTypeError, e.message
+        end
+
+        def persist_new!(request:, plan:, fingerprint:)
+          communication = Persister.call(request:, plan:, fingerprint:)
+          HandoffScheduler.schedule_after_commit(communication.id)
+          Result.from_communication(communication, idempotent_replay: false)
+        rescue ActiveRecord::RecordNotUnique => error
+          resolve_record_not_unique!(error, fingerprint)
+        rescue ActiveRecord::RecordInvalid => e
+          raise PersistenceError, e.message
+        end
+
+        def resolve_record_not_unique!(error, fingerprint)
+          existing = find_by_namespace
+          if existing
+            return resolve_existing(existing, fingerprint)
+          end
+
+          raise PersistenceError, "persistence uniqueness failure"
+        end
+
+        def reload_aggregate(id)
+          Messaging::Communication.includes(
+            :destination_plan,
+            :inbox_item,
+            :channel_deliveries,
+          ).find(id)
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/accept/error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Accept
+      class Error < CommandTower::Error; end
+    end
+  end
+end

data/app/services/command_tower/messaging/accept/excluded_destination.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Accept
+      ExcludedDestination = Data.define(:destination, :reason_class) do
+        def self.build(destination:, reason_class:)
+          dest =
+            if destination == :inbox || destination.to_s == "inbox"
+              :inbox
+            else
+              destination.to_s
+            end
+
+          new(destination: dest, reason_class: reason_class.to_s).freeze
+        end
+
+        def sort_key
+          destination == :inbox ? "inbox" : destination.to_s
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/accept/handoff_scheduler.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Accept
+      class HandoffScheduler
+        def self.schedule_after_commit(communication_id)
+          new(communication_id).schedule_after_commit
+        end
+
+        def self.enqueue(communication_id)
+          new(communication_id).enqueue
+        end
+
+        def initialize(communication_id)
+          @communication_id = communication_id
+        end
+
+        def schedule_after_commit
+          ActiveRecord.after_all_transactions_commit { enqueue }
+        end
+
+        def enqueue
+          Messaging::HandoffJob.perform_later(@communication_id)
+          communication = Messaging::Communication.find_by(id: @communication_id)
+          if communication
+            Handoff::OperationLogger.scheduled(communication:)
+          end
+        rescue StandardError => error
+          Handoff::OperationLogger.enqueue_failed(
+            communication_id: @communication_id,
+            error:,
+          )
+          # Leave execution_handoff_status as pending — recovery will redrive.
+          nil
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/accept/idempotency_conflict_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Accept
+      class IdempotencyConflictError < Error; end
+    end
+  end
+end

data/app/services/command_tower/messaging/accept/illegal_override_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Accept
+      class IllegalOverrideError < Error; end
+    end
+  end
+end

data/app/services/command_tower/messaging/accept/impossible_mandatory_plan_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Accept
+      class ImpossibleMandatoryPlanError < Error; end
+    end
+  end
+end

data/app/services/command_tower/messaging/accept/invalid_preference_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Accept
+      class InvalidPreferenceError < Error; end
+    end
+  end
+end

data/app/services/command_tower/messaging/accept/invariant_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Accept
+      class InvariantError < Error; end
+    end
+  end
+end