command_tower 0.4.0 → 0.10.0

data/app/services/command_tower/messaging/endpoints.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    # Safe owner-facing Endpoint Platform façade.
+    # Decrypt-at-use lives on Endpoints::SecretReader (internal).
+    module Endpoints
+      module_function
+
+      def create(owner_user_id:, channel_key:, address: nil, credentials: nil)
+        Create.call(owner_user_id:, channel_key:, address:, credentials:)
+      end
+
+      def replace(owner_user_id:, channel_key: nil, endpoint_id: nil, address: nil, credentials: nil)
+        Replace.call(owner_user_id:, channel_key:, endpoint_id:, address:, credentials:)
+      end
+
+      def revoke(owner_user_id:, endpoint_id:)
+        Revoke.call(owner_user_id:, endpoint_id:)
+      end
+
+      def list(owner_user_id:, channel_key: nil)
+        Query.list(owner_user_id:, channel_key:)
+      end
+
+      def show(owner_user_id:, endpoint_id:)
+        Query.show(owner_user_id:, endpoint_id:)
+      end
+
+      def mark_invalid(owner_user_id:, endpoint_id:)
+        MarkInvalid.call(owner_user_id:, endpoint_id:)
+      end
+
+      def begin_verification(owner_user_id:, endpoint_id:)
+        BeginVerification.call(owner_user_id:, endpoint_id:)
+      end
+
+      def mark_verified(owner_user_id:, endpoint_id:)
+        MarkVerified.call(owner_user_id:, endpoint_id:)
+      end
+
+      def mark_verification_failed(owner_user_id:, endpoint_id:)
+        MarkVerificationFailed.call(owner_user_id:, endpoint_id:)
+      end
+
+      def reset_verification(owner_user_id:, endpoint_id:)
+        ResetVerification.call(owner_user_id:, endpoint_id:)
+      end
+
+      def verify_pushover!(owner_user_id:, endpoint_id:)
+        Pushover::Verify.call(owner_user_id:, endpoint_id:)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Execution
+      AdapterRequest = Data.define(
+        :channel_delivery_id,
+        :communication_id,
+        :channel_key,
+        :attempt_id,
+        :rendered,
+      ) do
+        def self.build(channel_delivery_id:, communication_id:, channel_key:, attempt_id:, rendered:)
+          raise InvalidAdapterContractError, "arbitrary hashes are not accepted" if [channel_delivery_id, communication_id, channel_key, attempt_id].any? { |v| v.is_a?(Hash) }
+          raise InvalidAdapterContractError, "channel_delivery_id is required" if blank?(channel_delivery_id)
+          raise InvalidAdapterContractError, "communication_id is required" if blank?(communication_id)
+          raise InvalidAdapterContractError, "attempt_id is required" if blank?(attempt_id)
+          raise InvalidAdapterContractError, "channel_key is required" if blank?(channel_key)
+          raise InvalidAdapterContractError, "channel_key must be a String" unless channel_key.is_a?(String)
+          raise InvalidAdapterContractError, "rendered is required" if rendered.nil?
+          unless rendered.is_a?(Rendering::RenderedPayload) ||
+              rendered.is_a?(Rendering::RenderedSmsPayload) ||
+              rendered.is_a?(Rendering::RenderedPushoverPayload)
+            raise InvalidAdapterContractError,
+                  "rendered must be a RenderedPayload, RenderedSmsPayload, or RenderedPushoverPayload"
+          end
+          raise InvalidAdapterContractError, "rendered must be frozen" unless rendered.frozen?
+
+          new(
+            channel_delivery_id:,
+            communication_id:,
+            channel_key:,
+            attempt_id:,
+            rendered:,
+          ).freeze
+        end
+
+        def self.blank?(value)
+          value.nil? || (value.respond_to?(:empty?) && value.empty?)
+        end
+        private_class_method :blank?
+      end
+    end
+  end
+end

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Execution
+      AdapterResult = Data.define(
+        :outcome,
+        :normalized_provider_status,
+        :provider_message_id,
+        :error_code,
+      ) do
+        OUTCOMES = %i[success retryable_failure terminal_failure].freeze
+
+        def self.build(
+          outcome:,
+          normalized_provider_status: nil,
+          provider_message_id: nil,
+          error_code: nil
+        )
+          raise InvalidAdapterContractError, "arbitrary hashes are not accepted as outcome" if outcome.is_a?(Hash)
+          raise InvalidAdapterContractError, "raw exception objects are not accepted" if exception_like?(outcome) ||
+            exception_like?(normalized_provider_status) ||
+            exception_like?(provider_message_id) ||
+            exception_like?(error_code)
+          raise InvalidAdapterContractError, "raw exception messages are not accepted" if looks_like_exception_message?(error_code)
+
+          normalized_outcome = normalize_outcome!(outcome)
+          validate_optional_string!(normalized_provider_status, "normalized_provider_status")
+          validate_optional_string!(provider_message_id, "provider_message_id")
+          validate_optional_string!(error_code, "error_code")
+
+          new(
+            outcome: normalized_outcome,
+            normalized_provider_status:,
+            provider_message_id:,
+            error_code:,
+          ).freeze
+        end
+
+        def self.normalize_outcome!(outcome)
+          value = outcome.is_a?(String) ? outcome.to_sym : outcome
+          unless OUTCOMES.include?(value)
+            raise InvalidAdapterContractError, "unsupported outcome: #{outcome.inspect}"
+          end
+
+          value
+        end
+        private_class_method :normalize_outcome!
+
+        def self.validate_optional_string!(value, field_name)
+          return if value.nil?
+          raise InvalidAdapterContractError, "#{field_name} must be a String" unless value.is_a?(String)
+        end
+        private_class_method :validate_optional_string!
+
+        def self.exception_like?(value)
+          value.is_a?(Exception)
+        end
+        private_class_method :exception_like?
+
+        def self.looks_like_exception_message?(value)
+          # Reject multi-line or stack-trace-like payloads masquerading as error_code.
+          value.is_a?(String) && (value.include?("\n") || value.match?(/\.rb:\d+:in/))
+        end
+        private_class_method :looks_like_exception_message?
+
+        def success?
+          outcome == :success
+        end
+
+        def retryable_failure?
+          outcome == :retryable_failure
+        end
+
+        def terminal_failure?
+          outcome == :terminal_failure
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/execution/adapters/email/adapter.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "net/smtp"
+require "socket"
+require "timeout"
+
+module CommandTower
+  module Messaging
+    module Execution
+      module Adapters
+        module Email
+          class Adapter
+            RETRYABLE_ERRORS = [
+              Timeout::Error,
+              Net::OpenTimeout,
+              Net::ReadTimeout,
+              Errno::ECONNREFUSED,
+              Errno::ECONNRESET,
+              Errno::EHOSTUNREACH,
+              Errno::ENETUNREACH,
+              SocketError,
+            ].freeze
+
+            TERMINAL_SMTP_ERRORS = [
+              Net::SMTPAuthenticationError,
+              Net::SMTPFatalError,
+              Net::SMTPSyntaxError,
+            ].freeze
+
+            def call(request:)
+              raise ArgumentError, "request must be an AdapterRequest" unless request.is_a?(AdapterRequest)
+
+              begin
+                message = Messaging::ChannelMailer.deliver_rendered(rendered: request.rendered).deliver
+                AdapterResult.build(
+                  outcome: :success,
+                  normalized_provider_status: "accepted",
+                  provider_message_id: extract_message_id(message),
+                )
+              rescue ArgumentError
+                AdapterResult.build(
+                  outcome: :terminal_failure,
+                  error_code: "invalid_recipient",
+                )
+              rescue *TERMINAL_SMTP_ERRORS
+                AdapterResult.build(
+                  outcome: :terminal_failure,
+                  error_code: "smtp_rejected",
+                )
+              rescue *RETRYABLE_ERRORS
+                AdapterResult.build(
+                  outcome: :retryable_failure,
+                  error_code: "smtp_transient",
+                )
+              rescue StandardError
+                AdapterResult.build(
+                  outcome: :retryable_failure,
+                  error_code: "smtp_transient",
+                )
+              end
+            end
+
+            private
+
+            def extract_message_id(message)
+              return nil unless message.respond_to?(:message_id)
+
+              id = message.message_id
+              return nil if id.nil? || id.to_s.strip.empty?
+
+              id.to_s
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/execution/adapters/email/configuration.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Execution
+      module Adapters
+        module Email
+          class Configuration
+            SUPPORTED_DELIVERY_METHODS = %i[test smtp].freeze
+            SMTP_STRING_KEYS = %i[address user_name password authentication].freeze
+
+            def self.email_configured?
+              new.email_configured?
+            end
+
+            def email_configured?
+              method = CommandTower.config.email.delivery_method
+              method = method.to_sym if method.respond_to?(:to_sym)
+
+              case method
+              when :test
+                true
+              when :smtp
+                smtp_contract_complete?
+              else
+                false
+              end
+            end
+
+            private
+
+            def smtp_contract_complete?
+              settings = Rails.configuration.action_mailer.smtp_settings
+              return false unless settings.is_a?(Hash)
+
+              SMTP_STRING_KEYS.each do |key|
+                value = settings[key] || settings[key.to_s]
+                return false if value.nil? || value.to_s.strip.empty?
+              end
+
+              port = settings[:port] || settings["port"]
+              return false unless port.is_a?(Integer)
+
+              tls = settings[:enable_starttls_auto]
+              tls = settings["enable_starttls_auto"] if tls.nil?
+              return false unless tls == true || tls == false
+
+              true
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Execution
+      module Adapters
+        class FakeAdapter
+          attr_reader :last_request
+
+          def initialize(outcome: :success, normalized_provider_status: nil, provider_message_id: nil, error_code: nil)
+            @outcome = outcome
+            @normalized_provider_status = normalized_provider_status
+            @provider_message_id = provider_message_id
+            @error_code = error_code
+            @last_request = nil
+          end
+
+          def call(request:)
+            raise ArgumentError, "request must be an AdapterRequest" unless request.is_a?(AdapterRequest)
+
+            @last_request = request
+
+            AdapterResult.build(
+              outcome: @outcome,
+              normalized_provider_status: @normalized_provider_status,
+              provider_message_id: @provider_message_id || "fake-#{request.attempt_id}",
+              error_code: @error_code,
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/execution/adapters/pushover/adapter.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Execution
+      module Adapters
+        module Pushover
+          # Execution adapter: decrypts credentials for the readiness-resolved
+          # endpoint and sends via Messaging::Pushover::Transport.
+          class Adapter
+            CREDENTIAL_REJECTION_CODES = %i[
+              invalid_user
+              invalid_token
+              invalid_credentials
+            ].freeze
+
+            def initialize(configuration: nil, transport: nil, secret_reader: nil)
+              @configuration = configuration || Configuration.new
+              @transport = transport || Messaging::Pushover::Transport
+              @secret_reader = secret_reader || Endpoints::SecretReader
+            end
+
+            def call(request:)
+              raise ArgumentError, "request must be an AdapterRequest" unless request.is_a?(AdapterRequest)
+
+              rendered = request.rendered
+              unless rendered.is_a?(Rendering::RenderedPushoverPayload)
+                return AdapterResult.build(outcome: :terminal_failure, error_code: "render_failed")
+              end
+
+              unless @configuration.pushover_configured?
+                return AdapterResult.build(outcome: :terminal_failure, error_code: "adapter_unconfigured")
+              end
+
+              endpoint_id = Integer(rendered.recipient_address, exception: false)
+              if endpoint_id.nil? || endpoint_id <= 0
+                return AdapterResult.build(outcome: :terminal_failure, error_code: "invalid_recipient")
+              end
+
+              delivery = Messaging::ChannelDelivery.includes(:communication).find_by(id: request.channel_delivery_id)
+              owner_user_id = delivery&.communication&.user_id
+              if owner_user_id.nil?
+                return AdapterResult.build(outcome: :terminal_failure, error_code: "recipient_missing")
+              end
+
+              credentials = read_credentials(owner_user_id:, endpoint_id:)
+              return credentials if credentials.is_a?(AdapterResult)
+
+              result = @transport.send_message!(
+                user_key: credentials.fetch(:user_key),
+                application_token: credentials.fetch(:application_token),
+                title: rendered.title,
+                message: rendered.message,
+              )
+              map_result(result, owner_user_id:, endpoint_id:)
+            rescue StandardError
+              AdapterResult.build(outcome: :retryable_failure, error_code: "pushover_transient")
+            end
+
+            private
+
+            def read_credentials(owner_user_id:, endpoint_id:)
+              @secret_reader.read_pushover_credentials!(owner_user_id:, endpoint_id:)
+            rescue Endpoints::NotFoundError, Endpoints::ValidationError
+              AdapterResult.build(outcome: :terminal_failure, error_code: "recipient_missing")
+            end
+
+            def map_result(result, owner_user_id:, endpoint_id:)
+              unless result.is_a?(Messaging::Pushover::Result)
+                return AdapterResult.build(outcome: :retryable_failure, error_code: "pushover_transient")
+              end
+
+              if result.success?
+                return AdapterResult.build(
+                  outcome: :success,
+                  normalized_provider_status: "accepted",
+                  provider_message_id: result.provider_request_id,
+                )
+              end
+
+              code = result.error_code.to_sym
+              if CREDENTIAL_REJECTION_CODES.include?(code)
+                mark_invalid_best_effort!(owner_user_id:, endpoint_id:)
+                return AdapterResult.build(outcome: :terminal_failure, error_code: "pushover_rejected")
+              end
+
+              case code
+              when :adapter_disabled
+                AdapterResult.build(outcome: :terminal_failure, error_code: "adapter_unconfigured")
+              when :timeout, :provider_unavailable, :rate_limited
+                AdapterResult.build(outcome: :retryable_failure, error_code: "pushover_transient")
+              else
+                AdapterResult.build(outcome: :retryable_failure, error_code: "pushover_transient")
+              end
+            end
+
+            def mark_invalid_best_effort!(owner_user_id:, endpoint_id:)
+              Endpoints.mark_invalid(owner_user_id:, endpoint_id:)
+            rescue StandardError
+              nil
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/execution/adapters/pushover/configuration.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Execution
+      module Adapters
+        module Pushover
+          # Platform readiness detector for Pushover delivery.
+          # User-owned credentials (no host app token). Ready when transport adapter
+          # is fake, log, or http — disabled never counts as platform_configured.
+          class Configuration
+            CONFIGURED_ADAPTERS = %w[fake log http].freeze
+
+            def self.pushover_configured?
+              new.pushover_configured?
+            end
+
+            def pushover_configured?
+              CONFIGURED_ADAPTERS.include?(adapter_name)
+            end
+
+            def adapter_name
+              CommandTower.config.messaging.pushover.adapter.to_s
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "socket"
+require "timeout"
+
+module CommandTower
+  module Messaging
+    module Execution
+      module Adapters
+        module Sms
+          class Adapter
+            E164 = /\A\+[1-9]\d{1,14}\z/
+
+            RETRYABLE_HTTP_STATUSES = [408, 429, 500, 502, 503, 504].freeze
+            AUTH_HTTP_STATUSES = [401, 403].freeze
+
+            def initialize(http_client: nil, configuration: nil)
+              @http_client = http_client
+              @configuration = configuration || Configuration.new
+            end
+
+            def call(request:)
+              raise ArgumentError, "request must be an AdapterRequest" unless request.is_a?(AdapterRequest)
+              rendered = request.rendered
+              unless rendered.is_a?(Rendering::RenderedSmsPayload)
+                return AdapterResult.build(outcome: :terminal_failure, error_code: "render_failed")
+              end
+
+              unless @configuration.sms_configured?
+                return AdapterResult.build(outcome: :terminal_failure, error_code: "adapter_unconfigured")
+              end
+
+              to = rendered.recipient_address.to_s
+              unless to.match?(E164)
+                return AdapterResult.build(outcome: :terminal_failure, error_code: "invalid_recipient")
+              end
+
+              begin
+                response = client.create_message(
+                  to:,
+                  body: rendered.body,
+                  from: @configuration.use_messaging_service? ? nil : @configuration.from_number,
+                  messaging_service_sid: @configuration.use_messaging_service? ? @configuration.messaging_service_sid : nil,
+                )
+                map_response(response)
+              rescue Timeout::Error, Net::OpenTimeout, Net::ReadTimeout
+                AdapterResult.build(outcome: :retryable_failure, error_code: "twilio_transient")
+              rescue Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH, Errno::ENETUNREACH, SocketError
+                AdapterResult.build(outcome: :retryable_failure, error_code: "twilio_transient")
+              rescue StandardError
+                AdapterResult.build(outcome: :retryable_failure, error_code: "twilio_transient")
+              end
+            end
+
+            private
+
+            def client
+              @http_client || TwilioHttpClient.new(
+                account_sid: @configuration.account_sid,
+                auth_token: @configuration.auth_token,
+              )
+            end
+
+            def map_response(response)
+              if response[:ok]
+                return AdapterResult.build(
+                  outcome: :success,
+                  normalized_provider_status: response[:provider_status] || "queued",
+                  provider_message_id: response[:sid],
+                )
+              end
+
+              status = response[:status_code].to_i
+              if AUTH_HTTP_STATUSES.include?(status)
+                return AdapterResult.build(outcome: :terminal_failure, error_code: "twilio_auth_failed")
+              end
+
+              if RETRYABLE_HTTP_STATUSES.include?(status)
+                return AdapterResult.build(outcome: :retryable_failure, error_code: "twilio_transient")
+              end
+
+              AdapterResult.build(outcome: :terminal_failure, error_code: "twilio_rejected")
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Execution
+      module Adapters
+        module Sms
+          # Platform readiness detector for notification SMS.
+          # Ready only when adapter is twilio and credentials + sender are complete.
+          # disabled / fake / log never count as platform_configured.
+          class Configuration
+            def self.sms_configured?
+              new.sms_configured?
+            end
+
+            def sms_configured?
+              return false unless adapter_name == "twilio"
+
+              account_sid.present? && auth_token.present? && sender_identity_present?
+            end
+
+            def adapter_name
+              CommandTower.config.messaging.sms.adapter.to_s
+            end
+
+            def account_sid
+              CredentialResolution.resolve(:twilio).account_sid
+            end
+
+            def auth_token
+              CredentialResolution.resolve(:twilio).auth_token
+            end
+
+            # Prefer Messaging Service SID when both sender mechanisms are set.
+            def messaging_service_sid
+              CommandTower.config.messaging.sms.messaging_service_sid.to_s.strip.presence
+            end
+
+            def from_number
+              configured = CommandTower.config.messaging.sms.from_number.to_s.strip.presence
+              configured ||
+                ENV["TWILIO_FROM"].to_s.strip.presence ||
+                ENV["TWILIO_FROM_NUMBER"].to_s.strip.presence
+            end
+
+            def sender_identity_present?
+              messaging_service_sid.present? || from_number.present?
+            end
+
+            def use_messaging_service?
+              messaging_service_sid.present?
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Execution
+      module Adapters
+        module Sms
+          # Dev-only log adapter. Does not mark platform_configured.
+          class LogAdapter
+            def call(request:)
+              raise ArgumentError, "request must be an AdapterRequest" unless request.is_a?(AdapterRequest)
+
+              Rails.logger.info(
+                {
+                  component: "command_tower.messaging",
+                  event: "messaging.sms.log_adapter",
+                  channel_delivery_id: request.channel_delivery_id,
+                  attempt_id: request.attempt_id,
+                  channel_key: request.channel_key,
+                }.to_json,
+              )
+
+              AdapterResult.build(
+                outcome: :success,
+                normalized_provider_status: "logged",
+                provider_message_id: "log-#{request.attempt_id}",
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end