command_tower 0.3.1 → 0.10.0

data/app/services/command_tower/messaging/execution/adapters/sms/twilio_http_client.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module CommandTower
+  module Messaging
+    module Execution
+      module Adapters
+        module Sms
+          # Narrowly scoped Twilio Messages HTTP client for Messaging notification SMS.
+          # Not shared with Identity OTP transport.
+          class TwilioHttpClient
+            API_BASE = "https://api.twilio.com/2010-04-01"
+
+            def initialize(account_sid:, auth_token:)
+              @account_sid = account_sid
+              @auth_token = auth_token
+            end
+
+            # Returns a hash: { ok:, status_code:, body:, sid:, provider_status:, error_code: }
+            def create_message(to:, body:, from: nil, messaging_service_sid: nil)
+              uri = URI("#{API_BASE}/Accounts/#{@account_sid}/Messages.json")
+              request = Net::HTTP::Post.new(uri)
+              request.basic_auth(@account_sid, @auth_token)
+
+              form = { "To" => to, "Body" => body }
+              if messaging_service_sid.present?
+                form["MessagingServiceSid"] = messaging_service_sid
+              else
+                form["From"] = from
+              end
+              request.set_form_data(form)
+
+              response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, open_timeout: 10, read_timeout: 15) do |http|
+                http.request(request)
+              end
+
+              parse_response(response)
+            end
+
+            private
+
+            def parse_response(response)
+              parsed = parse_json(response.body)
+              sid = parsed.is_a?(Hash) ? (parsed["sid"] || parsed[:sid]).to_s.presence : nil
+              provider_status = parsed.is_a?(Hash) ? (parsed["status"] || parsed[:status]).to_s.presence : nil
+              provider_error = parsed.is_a?(Hash) ? (parsed["code"] || parsed[:code] || parsed["error_code"]).to_s.presence : nil
+
+              {
+                ok: response.is_a?(Net::HTTPSuccess),
+                status_code: response.code.to_i,
+                sid:,
+                provider_status:,
+                provider_error_code: provider_error,
+              }
+            end
+
+            def parse_json(body)
+              JSON.parse(body.to_s)
+            rescue JSON::ParserError
+              nil
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/execution/adapters/unconfigured_adapter.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Execution
+      module Adapters
+        class UnconfiguredAdapter
+          def call(request:)
+            raise ArgumentError, "request must be an AdapterRequest" unless request.is_a?(AdapterRequest)
+
+            AdapterResult.build(
+              outcome: :terminal_failure,
+              error_code: "adapter_unconfigured",
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Execution
+      # DeliveryAttempt + ChannelDelivery ledger writes for start and finalize paths.
+      class AttemptLedger
+        def self.start(delivery:)
+          new.start(delivery:)
+        end
+
+        def self.finalize_from_adapter(delivery:, attempt:, result:)
+          new.finalize_from_adapter(delivery:, attempt:, result:)
+        end
+
+        def self.finalize_terminal(delivery:, attempt:, error_code:)
+          new.finalize_terminal(delivery:, attempt:, error_code:)
+        end
+
+        def self.finalize_unexpected(delivery:, attempt:, error: nil, error_class: nil)
+          new.finalize_unexpected(delivery:, attempt:, error:, error_class:)
+        end
+
+        def start(delivery:)
+          now = Time.current
+          attempt = Messaging::DeliveryAttempt.create!(
+            channel_delivery: delivery,
+            status: Messaging::DeliveryAttempt::STATUS_STARTED,
+            started_at: now,
+          )
+          OperationLogger.attempt_started(channel_delivery: delivery, delivery_attempt: attempt)
+          attempt
+        rescue StandardError => error
+          mark_failed_retryable_best_effort!(delivery)
+          failed = load_delivery(delivery.id)
+          OperationLogger.attempt_create_failed(channel_delivery: failed, error:) if failed
+          nil
+        end
+
+        def finalize_terminal(delivery:, attempt:, error_code:)
+          finalize_from_adapter(
+            delivery:,
+            attempt:,
+            result: AdapterResult.build(outcome: :terminal_failure, error_code:),
+          )
+        end
+
+        def finalize_from_adapter(delivery:, attempt:, result:)
+          now = Time.current
+          ActiveRecord::Base.transaction do
+            case result.outcome
+            when :success
+              attempt.update!(
+                status: Messaging::DeliveryAttempt::STATUS_SUCCEEDED,
+                finished_at: now,
+                normalized_provider_status: result.normalized_provider_status,
+                provider_message_id: result.provider_message_id,
+                error_code: nil,
+                error_class: nil,
+              )
+              delivery.update!(status: Messaging::ChannelDelivery::STATUS_ACCEPTED_BY_PROVIDER)
+            when :retryable_failure
+              attempt.update!(
+                status: Messaging::DeliveryAttempt::STATUS_FAILED_RETRYABLE,
+                finished_at: now,
+                normalized_provider_status: result.normalized_provider_status,
+                provider_message_id: result.provider_message_id,
+                error_code: result.error_code,
+                error_class: nil,
+              )
+              delivery.update!(status: Messaging::ChannelDelivery::STATUS_FAILED_RETRYABLE)
+            when :terminal_failure
+              attempt.update!(
+                status: Messaging::DeliveryAttempt::STATUS_FAILED_TERMINAL,
+                finished_at: now,
+                normalized_provider_status: result.normalized_provider_status,
+                provider_message_id: result.provider_message_id,
+                error_code: result.error_code,
+                error_class: nil,
+              )
+              delivery.update!(status: Messaging::ChannelDelivery::STATUS_FAILED_TERMINAL)
+            else
+              raise InvalidAdapterContractError, "unsupported outcome: #{result.outcome.inspect}"
+            end
+          end
+
+          delivery.reload
+          attempt.reload
+          if result.success?
+            OperationLogger.attempt_succeeded(channel_delivery: delivery, delivery_attempt: attempt)
+            OperationLogger.succeeded(channel_delivery: delivery)
+          else
+            OperationLogger.attempt_failed(channel_delivery: delivery, delivery_attempt: attempt)
+            OperationLogger.failed(
+              channel_delivery: delivery,
+              error_code: result.error_code || result.outcome.to_s,
+              error_class: nil,
+            )
+          end
+
+          delivery
+        end
+
+        def finalize_unexpected(delivery:, attempt:, error: nil, error_class: nil)
+          now = Time.current
+          resolved_class = error_class || error&.class&.name || "UnknownError"
+
+          ActiveRecord::Base.transaction do
+            attempt.update!(
+              status: Messaging::DeliveryAttempt::STATUS_FAILED_RETRYABLE,
+              finished_at: now,
+              error_code: "internal_adapter_error",
+              error_class: resolved_class,
+              normalized_provider_status: nil,
+              provider_message_id: nil,
+            )
+            delivery.update!(status: Messaging::ChannelDelivery::STATUS_FAILED_RETRYABLE)
+          end
+
+          delivery.reload
+          attempt.reload
+          OperationLogger.attempt_failed(channel_delivery: delivery, delivery_attempt: attempt)
+          OperationLogger.failed(
+            channel_delivery: delivery,
+            error_code: "internal_adapter_error",
+            error_class: resolved_class,
+          )
+        rescue StandardError
+          mark_failed_retryable_best_effort!(delivery)
+        end
+
+        private
+
+        def load_delivery(id)
+          Messaging::ChannelDelivery.find_by(id:)
+        end
+
+        def mark_failed_retryable_best_effort!(delivery)
+          delivery.update(status: Messaging::ChannelDelivery::STATUS_FAILED_RETRYABLE)
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Execution
+      # Optimistic CAS: queued → executing. Returns true only when this worker wins.
+      class Claim
+        def self.call(delivery:)
+          new(delivery:).call
+        end
+
+        def initialize(delivery:)
+          @delivery = delivery
+        end
+
+        def call
+          now = Time.current
+          updated = Messaging::ChannelDelivery.where(
+            id: @delivery.id,
+            status: Messaging::ChannelDelivery::STATUS_QUEUED,
+          ).update_all(
+            [
+              "status = ?, execution_claimed_at = ?, execution_attempt_count = execution_attempt_count + 1, updated_at = ?",
+              Messaging::ChannelDelivery::STATUS_EXECUTING,
+              now,
+              now,
+            ],
+          )
+
+          updated == 1
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Execution
+      class InvalidAdapterContractError < ArgumentError; end
+    end
+  end
+end

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

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Execution
+      class OperationLogger
+        class << self
+          def scheduled(channel_delivery:)
+            info("messaging.execution.scheduled", channel_delivery:)
+          end
+
+          def claimed(channel_delivery:)
+            info("messaging.execution.claimed", channel_delivery:)
+          end
+
+          def started(channel_delivery:)
+            info("messaging.execution.started", channel_delivery:)
+          end
+
+          def succeeded(channel_delivery:)
+            info("messaging.execution.succeeded", channel_delivery:)
+          end
+
+          def failed(channel_delivery:, error: nil, error_code: "failed_retryable", error_class: nil)
+            emit(
+              :error,
+              "messaging.execution.failed",
+              channel_delivery:,
+              error_class: error_class || error&.class&.name,
+              error_code:,
+            )
+          end
+
+          def enqueue_failed(channel_delivery_id:, error:)
+            emit(
+              :error,
+              "messaging.execution.failed",
+              channel_delivery_id:,
+              error_class: error.class.name,
+              error_code: "execution_enqueue_failed",
+            )
+          end
+
+          def recovered(channel_delivery:)
+            info("messaging.execution.recovered", channel_delivery:)
+          end
+
+          def attempt_started(channel_delivery:, delivery_attempt:)
+            emit_attempt("messaging.execution.attempt.started", channel_delivery:, delivery_attempt:)
+          end
+
+          def attempt_succeeded(channel_delivery:, delivery_attempt:)
+            emit_attempt("messaging.execution.attempt.succeeded", channel_delivery:, delivery_attempt:)
+          end
+
+          def attempt_failed(channel_delivery:, delivery_attempt:)
+            emit_attempt(
+              "messaging.execution.attempt.failed",
+              channel_delivery:,
+              delivery_attempt:,
+              level: :error,
+            )
+          end
+
+          def attempt_create_failed(channel_delivery:, error:)
+            emit(
+              :error,
+              "messaging.execution.attempt_create_failed",
+              channel_delivery:,
+              error_class: error.class.name,
+              error_code: "attempt_create_failed",
+            )
+          end
+
+          def render_started(channel_delivery:, delivery_attempt:)
+            emit_render(
+              :info,
+              "messaging.execution.render.started",
+              channel_delivery:,
+              delivery_attempt:,
+            )
+          end
+
+          def render_succeeded(channel_delivery:, delivery_attempt:)
+            emit_render(
+              :info,
+              "messaging.execution.render.succeeded",
+              channel_delivery:,
+              delivery_attempt:,
+            )
+          end
+
+          def render_failed(channel_delivery:, delivery_attempt:, error_code:, error_class: nil)
+            emit_render(
+              :error,
+              "messaging.execution.render.failed",
+              channel_delivery:,
+              delivery_attempt:,
+              error_code:,
+              error_class:,
+            )
+          end
+
+          def adapter_started(channel_delivery:, delivery_attempt:)
+            emit_adapter(
+              :info,
+              "messaging.execution.adapter.started",
+              channel_delivery:,
+              delivery_attempt:,
+            )
+          end
+
+          def adapter_accepted(channel_delivery:, delivery_attempt:)
+            emit_adapter(
+              :info,
+              "messaging.execution.adapter.accepted",
+              channel_delivery:,
+              delivery_attempt:,
+            )
+          end
+
+          def adapter_retryable(channel_delivery:, delivery_attempt:, error_code:)
+            emit_adapter(
+              :error,
+              "messaging.execution.adapter.retryable",
+              channel_delivery:,
+              delivery_attempt:,
+              error_code:,
+            )
+          end
+
+          def adapter_terminal(channel_delivery:, delivery_attempt:, error_code:)
+            emit_adapter(
+              :error,
+              "messaging.execution.adapter.terminal",
+              channel_delivery:,
+              delivery_attempt:,
+              error_code:,
+            )
+          end
+
+          def readiness_revalidated(channel_delivery:, delivery_attempt:, ready:)
+            emit(
+              :info,
+              "messaging.execution.readiness.revalidated",
+              channel_delivery:,
+              delivery_attempt_id: delivery_attempt.id,
+              ready: ready ? 1 : 0,
+            )
+          end
+
+          def readiness_failed(
+            channel_delivery:,
+            delivery_attempt:,
+            error_code:,
+            reason_codes: []
+          )
+            emit(
+              :error,
+              "messaging.execution.readiness.failed",
+              channel_delivery:,
+              delivery_attempt_id: delivery_attempt.id,
+              error_code:,
+              reason_codes: Array(reason_codes).map(&:to_s),
+            )
+          end
+
+          private
+
+          def emit_render(level, event, channel_delivery:, delivery_attempt:, error_code: nil, error_class: nil)
+            emit(
+              level,
+              event,
+              channel_delivery:,
+              delivery_attempt_id: delivery_attempt.id,
+              error_code:,
+              error_class:,
+            )
+          end
+
+          def emit_adapter(level, event, channel_delivery:, delivery_attempt:, error_code: nil)
+            emit(
+              level,
+              event,
+              channel_delivery:,
+              delivery_attempt_id: delivery_attempt.id,
+              error_code:,
+            )
+          end
+
+          def info(event, channel_delivery:)
+            emit(:info, event, channel_delivery:)
+          end
+
+          def emit_attempt(event, channel_delivery:, delivery_attempt:, level: :info)
+            emit(
+              level,
+              event,
+              channel_delivery:,
+              delivery_attempt_id: delivery_attempt.id,
+              attempt_status: delivery_attempt.status,
+              error_code: delivery_attempt.error_code,
+              error_class: delivery_attempt.error_class,
+              provider_message_id: delivery_attempt.provider_message_id,
+            )
+          end
+
+          def emit(level, event, channel_delivery: nil, channel_delivery_id: nil, **extra)
+            payload = {
+              event:,
+              correlation_id: Contract::Observability::Correlation.resolve,
+              messaging_operation: "execution",
+            }.merge(extra)
+
+            if channel_delivery
+              communication = channel_delivery.communication
+              payload.merge!(
+                channel_delivery_id: channel_delivery.id,
+                communication_id: channel_delivery.communication_id,
+                channel_key: channel_delivery.channel_key,
+                execution_status: channel_delivery.status,
+                execution_attempt_count: channel_delivery.execution_attempt_count,
+                host_event_identity_digest: Accept::RequestNormalizer.digest_host_event_identity(
+                  communication&.host_event_identity,
+                ),
+              )
+            elsif channel_delivery_id
+              payload[:channel_delivery_id] = channel_delivery_id
+            end
+
+            Contract::Observability::StructuredLogger.public_send(level, payload)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Execution
+      module ReadinessTerminalMapping
+        module_function
+
+        def error_code_for(reason_codes)
+          codes = Array(reason_codes).map(&:to_s)
+          return "recipient_missing" if codes.empty?
+
+          case codes.first
+          when RecipientReadiness::ReasonCodes::PLATFORM_DISABLED
+            "platform_disabled"
+          when RecipientReadiness::ReasonCodes::PLATFORM_UNCONFIGURED
+            "adapter_unconfigured"
+          when RecipientReadiness::ReasonCodes::IDENTITY_UNVERIFIED
+            "recipient_unverified"
+          when RecipientReadiness::ReasonCodes::IDENTITY_MISSING,
+               RecipientReadiness::ReasonCodes::IDENTITY_UNAVAILABLE
+            "recipient_missing"
+          when RecipientReadiness::ReasonCodes::ENDPOINT_INVALID
+            "invalid_recipient"
+          when RecipientReadiness::ReasonCodes::ENDPOINT_MISSING,
+               RecipientReadiness::ReasonCodes::ENDPOINT_INACTIVE,
+               RecipientReadiness::ReasonCodes::ENDPOINT_UNVERIFIED,
+               RecipientReadiness::ReasonCodes::CREDENTIALS_MISSING
+            "recipient_missing"
+          else
+            "recipient_missing"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Execution
+      class Recovery
+        def self.call(
+          grace_window: Messaging::DeliveryRetryPolicy::GRACE_WINDOW,
+          max_attempts: Messaging::DeliveryRetryPolicy::MAX_ATTEMPTS
+        )
+          new(grace_window:, max_attempts:).call
+        end
+
+        def initialize(
+          grace_window: Messaging::DeliveryRetryPolicy::GRACE_WINDOW,
+          max_attempts: Messaging::DeliveryRetryPolicy::MAX_ATTEMPTS
+        )
+          @grace_window = grace_window
+          @max_attempts = max_attempts
+        end
+
+        def call
+          recover_queued!
+          recover_failed!
+          recover_stale_executing!
+        end
+
+        private
+
+        def grace_before
+          @grace_window.ago
+        end
+
+        def recover_queued!
+          Messaging::ChannelDelivery
+            .queued_for_execution
+            .where(Messaging::ChannelDelivery.arel_table[:updated_at].lt(grace_before))
+            .find_each { |delivery| redrive!(delivery) }
+        end
+
+        def recover_failed!
+          Messaging::ChannelDelivery
+            .failed_retryable
+            .where(Messaging::ChannelDelivery.arel_table[:updated_at].lt(grace_before))
+            .where(Messaging::ChannelDelivery.arel_table[:execution_attempt_count].lt(@max_attempts))
+            .find_each do |delivery|
+              reset_to_queued!(delivery)
+              redrive!(delivery.reload)
+            end
+        end
+
+        def recover_stale_executing!
+          Messaging::ChannelDelivery
+            .executing
+            .where(Messaging::ChannelDelivery.arel_table[:execution_claimed_at].lt(grace_before))
+            .find_each do |delivery|
+              next if delivery.execution_attempt_count >= @max_attempts
+
+              reset_to_queued!(delivery)
+              redrive!(delivery.reload)
+            end
+        end
+
+        def reset_to_queued!(delivery)
+          delivery.update!(
+            status: Messaging::ChannelDelivery::STATUS_QUEUED,
+            execution_claimed_at: nil,
+          )
+        end
+
+        def redrive!(delivery)
+          Messaging::ChannelDeliveryExecutionJob.perform_later(delivery.id)
+          OperationLogger.recovered(channel_delivery: delivery)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Execution
+      # Transport address only — eligibility / endpoint selection is owned by RecipientReadiness.
+      class ResolveRecipientAddress
+        E164 = /\A\+[1-9]\d{1,14}\z/
+
+        def self.call(communication:, channel_key:, readiness_result: nil)
+          new(communication:, channel_key:, readiness_result:).call
+        end
+
+        def initialize(communication:, channel_key:, readiness_result: nil)
+          @communication = communication
+          @channel_key = channel_key
+          @readiness_result = readiness_result
+        end
+
+        def call
+          case @channel_key.to_s
+          when "sms"
+            phone = @communication&.user&.phone_number.to_s.strip
+            if blank_recipient?(phone)
+              { address: nil, error_code: "recipient_missing" }
+            elsif !phone.match?(E164)
+              { address: nil, error_code: "invalid_recipient" }
+            else
+              { address: phone, error_code: nil }
+            end
+          when "email"
+            address = @communication&.user&.email
+            if blank_recipient?(address)
+              { address: nil, error_code: "recipient_missing" }
+            else
+              { address:, error_code: nil }
+            end
+          when "pushover"
+            endpoint_id = @readiness_result&.resolved_endpoint_id
+            if endpoint_id.nil?
+              { address: nil, error_code: "recipient_missing" }
+            else
+              { address: endpoint_id.to_s, error_code: nil }
+            end
+          else
+            { address: nil, error_code: "adapter_unconfigured" }
+          end
+        end
+
+        private
+
+        def blank_recipient?(recipient_address)
+          recipient_address.nil? || recipient_address.to_s.strip.empty?
+        end
+      end
+    end
+  end
+end