command_tower 0.4.0 → 0.11.0

data/app/services/command_tower/messaging/execution/revalidate_readiness.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Execution
+      # Execution-time RecipientReadiness revalidation (TOCTOU protection).
+      class RevalidateReadiness
+        def self.call(delivery:, attempt:, communication:)
+          new(delivery:, attempt:, communication:).call
+        end
+
+        def initialize(delivery:, attempt:, communication:)
+          @delivery = delivery
+          @attempt = attempt
+          @communication = communication
+        end
+
+        # Returns ChannelResult on success, or a String error_code on terminal readiness failure.
+        def call
+          platform_enabled_channels = platform_enabled_channels_for(@communication)
+
+          begin
+            result = RecipientReadiness.for_channel(
+              recipient_id: @communication.user_id,
+              channel_key: @delivery.channel_key,
+              platform_enabled_channels:,
+            )
+          rescue RecipientReadiness::RecipientNotFoundError
+            OperationLogger.readiness_failed(
+              channel_delivery: @delivery,
+              delivery_attempt: @attempt,
+              error_code: "recipient_missing",
+              reason_codes: [RecipientReadiness::ReasonCodes::IDENTITY_UNAVAILABLE],
+            )
+            return "recipient_missing"
+          rescue RecipientReadiness::UnknownChannelError
+            OperationLogger.readiness_failed(
+              channel_delivery: @delivery,
+              delivery_attempt: @attempt,
+              error_code: "adapter_unconfigured",
+              reason_codes: [RecipientReadiness::ReasonCodes::PLATFORM_UNCONFIGURED],
+            )
+            return "adapter_unconfigured"
+          end
+
+          OperationLogger.readiness_revalidated(
+            channel_delivery: @delivery,
+            delivery_attempt: @attempt,
+            ready: result.ready,
+          )
+
+          return result if result.ready
+
+          error_code = ReadinessTerminalMapping.error_code_for(result.reason_codes)
+          OperationLogger.readiness_failed(
+            channel_delivery: @delivery,
+            delivery_attempt: @attempt,
+            error_code:,
+            reason_codes: result.reason_codes,
+          )
+          error_code
+        end
+
+        private
+
+        def platform_enabled_channels_for(communication)
+          decision = communication.destination_plan&.decision || {}
+          Array(decision["platform_enabled_channels"]).map(&:to_s)
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/execution/scheduler.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Execution
+      class Scheduler
+        def self.schedule_after_commit(channel_delivery_ids)
+          new(channel_delivery_ids).schedule_after_commit
+        end
+
+        def initialize(channel_delivery_ids)
+          @channel_delivery_ids = Array(channel_delivery_ids).compact.uniq
+        end
+
+        def schedule_after_commit
+          return if @channel_delivery_ids.empty?
+
+          ids = @channel_delivery_ids
+          ActiveRecord.after_all_transactions_commit { enqueue_all(ids) }
+        end
+
+        def enqueue_all(ids = @channel_delivery_ids)
+          ids.each { |id| enqueue(id) }
+        end
+
+        def enqueue(channel_delivery_id)
+          Messaging::ChannelDeliveryExecutionJob.perform_later(channel_delivery_id)
+          delivery = Messaging::ChannelDelivery.find_by(id: channel_delivery_id)
+          OperationLogger.scheduled(channel_delivery: delivery) if delivery
+        rescue StandardError => error
+          OperationLogger.enqueue_failed(channel_delivery_id:, error:)
+          # Leave status as queued — Execution::Recovery will redrive.
+          nil
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/execution/select_adapter.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Execution
+      # Provider adapter selection (fake override → channel configuration → UnconfiguredAdapter).
+      class SelectAdapter
+        def self.call(delivery:, executor: nil)
+          new(delivery:, executor:).call
+        end
+
+        def initialize(delivery:, executor: nil)
+          @delivery = delivery
+          @executor = executor
+        end
+
+        def call
+          @executor || default_adapter
+        end
+
+        private
+
+        def default_adapter
+          # Platform testing override (not provider configuration). Precedence:
+          # injected executor → allow_fake_adapter → provider selection.
+          if CommandTower.config.messaging.allow_fake_adapter
+            return Adapters::FakeAdapter.new
+          end
+
+          case @delivery.channel_key.to_s
+          when "email"
+            return Adapters::Email::Adapter.new if Adapters::Email::Configuration.email_configured?
+          when "sms"
+            return sms_runtime_adapter
+          when "pushover"
+            if Adapters::Pushover::Configuration.pushover_configured?
+              return Adapters::Pushover::Adapter.new
+            end
+          end
+
+          Adapters::UnconfiguredAdapter.new
+        end
+
+        def sms_runtime_adapter
+          case Adapters::Sms::Configuration.new.adapter_name
+          when "twilio"
+            if Adapters::Sms::Configuration.sms_configured?
+              Adapters::Sms::Adapter.new
+            else
+              Adapters::UnconfiguredAdapter.new
+            end
+          when "fake"
+            Adapters::FakeAdapter.new
+          when "log"
+            Adapters::Sms::LogAdapter.new
+          else
+            Adapters::UnconfiguredAdapter.new
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/handoff/advance_communication.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Handoff
+      # Owns the handoff write transaction: planned → queued + execution_handoff_status.
+      class AdvanceCommunication
+        def self.call(communication:)
+          new(communication:).call
+        end
+
+        def initialize(communication:)
+          @communication = communication
+        end
+
+        def call
+          ActiveRecord::Base.transaction do
+            @communication.channel_deliveries.each do |delivery|
+              next unless delivery.status == Messaging::ChannelDelivery::STATUS_PLANNED
+
+              delivery.update!(status: Messaging::ChannelDelivery::STATUS_QUEUED)
+            end
+
+            next_status =
+              if @communication.channel_deliveries.reload.empty?
+                Messaging::Communication::HANDOFF_COMPLETE
+              else
+                Messaging::Communication::HANDOFF_ENQUEUED
+              end
+
+            @communication.update!(execution_handoff_status: next_status)
+          end
+
+          @communication.reload
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/handoff/operation_logger.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Handoff
+      class OperationLogger
+        class << self
+          def scheduled(communication:)
+            info("messaging.accept.handoff.scheduled", communication:)
+          end
+
+          def started(communication:)
+            info("messaging.accept.handoff.started", communication:)
+          end
+
+          def succeeded(communication:)
+            info("messaging.accept.handoff.succeeded", communication:)
+          end
+
+          def failed(communication:, error:)
+            emit(
+              :error,
+              "messaging.accept.handoff.failed",
+              communication:,
+              error_class: error.class.name,
+              error_code: "handoff_execution_failed",
+            )
+          end
+
+          def enqueue_failed(communication_id:, error:)
+            emit(
+              :error,
+              "messaging.accept.handoff.failed",
+              communication_id:,
+              error_class: error.class.name,
+              error_code: "handoff_enqueue_failed",
+            )
+          end
+
+          def recovered(communication:)
+            info("messaging.accept.handoff.recovered", communication:)
+          end
+
+          private
+
+          def info(event, communication:)
+            emit(:info, event, communication:)
+          end
+
+          def emit(level, event, communication: nil, communication_id: nil, **extra)
+            payload = {
+              event:,
+              correlation_id: Contract::Observability::Correlation.resolve,
+              messaging_operation: "accept.handoff",
+            }.merge(extra)
+
+            if communication
+              payload.merge!(
+                communication_id: communication.id,
+                execution_handoff_status: communication.execution_handoff_status,
+                accept_request_fingerprint: communication.accept_request_fingerprint,
+                host_event_identity_digest: Accept::RequestNormalizer.digest_host_event_identity(
+                  communication.host_event_identity,
+                ),
+                channel_delivery_count: communication.channel_deliveries.size,
+                inbox_selected: communication.inbox_item.present? ? 1 : 0,
+              )
+            elsif communication_id
+              payload[:communication_id] = communication_id
+            end
+
+            Contract::Observability::Publisher.public_send(level, payload)
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/handoff/recovery.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Handoff
+      class Recovery
+        GRACE_WINDOW = 1.minute
+
+        def self.call(grace_window: GRACE_WINDOW)
+          new(grace_window:).call
+        end
+
+        def initialize(grace_window: GRACE_WINDOW)
+          @grace_window = grace_window
+        end
+
+        def call
+          Messaging::Communication.needing_handoff_recovery(grace_before: @grace_window.ago).find_each do |communication|
+            Messaging::HandoffJob.perform_later(communication.id)
+            OperationLogger.recovered(communication:)
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/inbox/bulk_result.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Inbox
+      BulkResult = Data.define(:ids, :count, :changed_count) do
+        def self.build(ids:, changed_count:)
+          ids = Array(ids).freeze
+
+          new(
+            ids:,
+            count: ids.size,
+            changed_count: Integer(changed_count),
+          ).freeze
+        end
+      end
+    end
+  end
+end

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

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

data/app/services/command_tower/messaging/inbox/invalid_bulk_items_error.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Inbox
+      # Raised when a bulk request references items the recipient cannot mutate:
+      # unknown ids, another recipient's ids, or ids unavailable for the operation.
+      # Carries the offending ids so callers can report them without parsing the message.
+      class InvalidBulkItemsError < ValidationError
+        attr_reader :invalid_ids
+
+        def initialize(message = "inbox items are unavailable", invalid_ids: [])
+          @invalid_ids = Array(invalid_ids).freeze
+          super(message)
+        end
+      end
+    end
+  end
+end

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

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

data/app/services/command_tower/messaging/inbox/item_result.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Inbox
+      ItemResult = Data.define(
+        :id,
+        :communication_id,
+        :recipient_id,
+        :title,
+        :status,
+        :viewed_at,
+        :archived_at,
+        :deleted_at,
+        :created_at,
+        :updated_at,
+      ) do
+        def self.build(
+          id:,
+          communication_id:,
+          recipient_id:,
+          title:,
+          status:,
+          viewed_at:,
+          archived_at:,
+          deleted_at:,
+          created_at:,
+          updated_at:
+        )
+          new(
+            id:,
+            communication_id:,
+            recipient_id:,
+            title: title.to_s,
+            status: status.to_s,
+            viewed_at:,
+            archived_at:,
+            deleted_at:,
+            created_at:,
+            updated_at:,
+          ).freeze
+        end
+
+        def self.from_record(inbox_item)
+          communication = inbox_item.communication
+          raise InvariantError, "inbox item missing communication" if communication.nil?
+
+          build(
+            id: inbox_item.id,
+            communication_id: inbox_item.communication_id,
+            recipient_id: communication.user_id,
+            title: communication.title,
+            status: inbox_item.lifecycle_label,
+            viewed_at: inbox_item.viewed_at,
+            archived_at: inbox_item.archived_at,
+            deleted_at: inbox_item.deleted_at,
+            created_at: inbox_item.created_at,
+            updated_at: inbox_item.updated_at,
+          )
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/inbox/list_result.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Inbox
+      ListResult = Data.define(:items, :limit, :offset, :total_count) do
+        def self.build(items:, limit:, offset:, total_count:)
+          new(
+            items: Array(items).freeze,
+            limit: Integer(limit),
+            offset: Integer(offset),
+            total_count: Integer(total_count),
+          ).freeze
+        end
+      end
+    end
+  end
+end