command_tower 0.4.0 → 0.10.0

data/app/services/command_tower/clients/transport/faraday_adapter.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "json"
+require "faraday"
+require "faraday/net_http_persistent"
+require "connection_pool"
+
+module CommandTower
+  module Clients
+    module Transport
+      class FaradayAdapter
+        attr_reader :config, :pool
+
+        def initialize(config: FaradayConfig.defaults, connection: nil, **overrides)
+          @config = resolve_config(config, overrides)
+          @pool = build_pool(connection)
+        end
+
+        def call(request)
+          unless request.is_a?(Request)
+            raise Errors::ConfigurationError,
+                  "request must be a #{Request.name}"
+          end
+
+          started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          url = merge_url_and_query(request.url, request.query)
+          body, headers = encode_body(request.body, request.headers)
+          timeout = request.timeout || config.timeout
+
+          response = with_connection do |connection|
+            connection.run_request(request.method, url, body, headers) do |req|
+              req.options.timeout = timeout
+              req.options.open_timeout = config.open_timeout
+            end
+          end
+
+          Response.build(
+            status: response.status,
+            headers: response.headers.to_h,
+            body: response.body,
+            duration_ms: elapsed_ms(started_at)
+          )
+        rescue Faraday::TimeoutError => e
+          raise Error.new(e.message.presence || "request timed out", cause: e)
+        rescue Faraday::ConnectionFailed => e
+          raise Error.new(e.message.presence || "connection failed", cause: e)
+        rescue ConnectionPool::TimeoutError => e
+          raise Error.new(e.message.presence || "connection pool timeout", cause: e)
+        end
+
+        private
+
+        def resolve_config(config, overrides)
+          base = config || FaradayConfig.defaults
+          return base if overrides.empty?
+
+          FaradayConfig.new(
+            pool_size: overrides.fetch(:pool_size, base.pool_size),
+            idle_timeout: overrides.fetch(:idle_timeout, base.idle_timeout),
+            open_timeout: overrides.fetch(:open_timeout, base.open_timeout),
+            timeout: overrides.fetch(:timeout, base.timeout)
+          )
+        end
+
+        def build_pool(connection)
+          if connection
+            ConnectionPool.new(size: 1, timeout: config.open_timeout) { connection }
+          else
+            ConnectionPool.new(size: config.pool_size, timeout: config.open_timeout) do
+              build_persistent_connection(config)
+            end
+          end
+        end
+
+        def with_connection(&block)
+          pool.with(&block)
+        end
+
+        def build_persistent_connection(config)
+          Faraday.new do |faraday|
+            # One socket-management context per pooled Faraday::Connection;
+            # concurrency across threads is provided by ConnectionPool.
+            faraday.adapter :net_http_persistent, pool_size: 1 do |http|
+              http.idle_timeout = config.idle_timeout
+            end
+          end
+        end
+
+        def merge_url_and_query(url, query)
+          uri = URI.parse(url)
+          existing = URI.decode_www_form(uri.query.to_s)
+          extra = normalize_query(query).flat_map do |key, value|
+            Array(value).map { |item| [ key.to_s, item.to_s ] }
+          end
+          combined = existing + extra
+          uri.query = combined.empty? ? nil : URI.encode_www_form(combined)
+          uri.to_s
+        end
+
+        def normalize_query(query)
+          query.to_h
+        end
+
+        def encode_body(body, headers)
+          normalized_headers = headers.to_h.transform_keys(&:to_s)
+
+          case body
+          when Hash, Array
+            encoded = JSON.generate(body)
+            unless content_type_present?(normalized_headers)
+              normalized_headers = normalized_headers.merge("Content-Type" => "application/json")
+            end
+            [ encoded, normalized_headers ]
+          else
+            [ body, normalized_headers ]
+          end
+        end
+
+        def content_type_present?(headers)
+          headers.keys.any? { |key| key.downcase == "content-type" }
+        end
+
+        def elapsed_ms(started_at)
+          ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/clients/transport/faraday_config.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Clients
+    module Transport
+      FaradayConfig = Data.define(:pool_size, :idle_timeout, :open_timeout, :timeout) do
+        DEFAULT_POOL_SIZE = 5
+        DEFAULT_IDLE_TIMEOUT = 30
+        DEFAULT_OPEN_TIMEOUT = 5
+        DEFAULT_TIMEOUT = 30
+
+        # pool_size — ConnectionPool size (concurrent Faraday::Connection checkouts)
+        # idle_timeout — net_http_persistent idle timeout per pooled connection
+        # open_timeout — Faraday open timeout and ConnectionPool checkout timeout
+        # timeout — default per-request Faraday timeout
+
+        def self.defaults
+          new(
+            pool_size: DEFAULT_POOL_SIZE,
+            idle_timeout: DEFAULT_IDLE_TIMEOUT,
+            open_timeout: DEFAULT_OPEN_TIMEOUT,
+            timeout: DEFAULT_TIMEOUT
+          )
+        end
+
+        def self.from_env
+          new(
+            pool_size: integer_env("CLIENTS_HTTP_POOL_SIZE", DEFAULT_POOL_SIZE),
+            idle_timeout: integer_env("CLIENTS_HTTP_IDLE_TIMEOUT", DEFAULT_IDLE_TIMEOUT),
+            open_timeout: integer_env("CLIENTS_HTTP_OPEN_TIMEOUT", DEFAULT_OPEN_TIMEOUT),
+            timeout: integer_env("CLIENTS_HTTP_TIMEOUT", DEFAULT_TIMEOUT)
+          )
+        end
+
+        def self.integer_env(key, default)
+          value = ENV[key]
+          return default if value.nil? || value.strip.empty?
+
+          Integer(value)
+        end
+        private_class_method :integer_env
+      end
+    end
+  end
+end

data/app/services/command_tower/clients/transport/request.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Clients
+    module Transport
+      Request = Data.define(:method, :url, :headers, :body, :query, :timeout) do
+        SUPPORTED_METHODS = %i[get post put patch delete].freeze
+
+        def self.build(method:, url:, headers: {}, body: nil, query: {}, timeout: nil)
+          new(
+            method: normalize_and_validate_method(method),
+            url: url.to_s,
+            headers: normalize_headers(headers),
+            body: body,
+            query: normalize_query(query),
+            timeout: timeout
+          )
+        end
+
+        def self.validate_method!(method)
+          normalize_and_validate_method(method)
+        end
+
+        def self.normalize_and_validate_method(method)
+          normalized = method.to_s.downcase.to_sym
+          return normalized if SUPPORTED_METHODS.include?(normalized)
+
+          raise Errors::ConfigurationError,
+                "unsupported HTTP method: #{method.inspect} " \
+                "(supported: #{SUPPORTED_METHODS.join(', ')})"
+        end
+        private_class_method :normalize_and_validate_method
+
+        def self.normalize_headers(headers)
+          headers.to_h.transform_keys(&:to_s)
+        end
+        private_class_method :normalize_headers
+
+        def self.normalize_query(query)
+          query.to_h.transform_keys(&:to_s)
+        end
+        private_class_method :normalize_query
+
+        def merge_headers(extra)
+          with(headers: headers.merge(self.class.send(:normalize_headers, extra)))
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/clients/transport/response.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Clients
+    module Transport
+      Response = Data.define(:status, :headers, :body, :duration_ms) do
+        def self.build(status:, headers: {}, body: nil, duration_ms: nil)
+          new(
+            status: Integer(status),
+            headers: headers.to_h.transform_keys(&:to_s),
+            body: body,
+            duration_ms: duration_ms
+          )
+        end
+
+        def success?
+          status >= 200 && status < 300
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/clients/url.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module CommandTower
+  module Clients
+    # URI-aware URL helpers for ClientBase absolutization.
+    # Joins provider base_url with relative endpoint paths without URI.join
+    # replacing intentional base path prefixes (e.g. /api/v1).
+    module Url
+      module_function
+
+      def absolute?(url)
+        uri = URI.parse(url.to_s)
+        uri.absolute? && uri.host.present?
+      rescue URI::InvalidURIError
+        false
+      end
+
+      def join(base_url, relative_path)
+        base = base_url.to_s.strip
+        if base.empty?
+          raise Errors::ConfigurationError, "base_url is required to resolve a relative request URL"
+        end
+
+        uri = URI.parse(base)
+        unless uri.absolute? && uri.host.present?
+          raise Errors::ConfigurationError,
+                "base_url must be an absolute URL with a host (got: #{base_url.inspect})"
+        end
+
+        suffix = relative_path.to_s.delete_prefix("/")
+        prefix = uri.path.to_s
+        prefix = "" if prefix == "/"
+        prefix = prefix.delete_suffix("/")
+
+        combined = if prefix.empty?
+                     "/#{suffix}"
+        else
+                     "#{prefix}/#{suffix}"
+        end
+        combined = "/" if combined.empty?
+
+        result = uri.dup
+        result.path = combined
+        result.query = nil
+        result.fragment = nil
+        result.to_s
+      rescue URI::InvalidURIError => e
+        raise Errors::ConfigurationError,
+              "invalid base_url: #{base_url.inspect}",
+              cause: e
+      end
+    end
+  end
+end

data/app/services/command_tower/identity/phone/normalizer.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "phonelib"
+
+module CommandTower
+  module Identity
+    module Phone
+      # Canonical E.164 normalize/reject entry point for Identity phone numbers.
+      class Normalizer
+        DEFAULT_COUNTRY = "US"
+
+        BLANK_MESSAGE = "is required"
+        INVALID_MESSAGE = "is invalid"
+
+        Normalized = Data.define(:normalized, :message) do
+          def success? = message.nil?
+
+          def failure? = !success?
+        end
+
+        def self.call(phone_number:)
+          raw = phone_number.to_s.strip
+          return failure(BLANK_MESSAGE) if raw.blank?
+
+          parsed = Phonelib.parse(raw, DEFAULT_COUNTRY)
+          return failure(INVALID_MESSAGE) unless parsed.valid?
+
+          e164 = parsed.e164.to_s
+          return failure(INVALID_MESSAGE) if e164.blank?
+
+          Normalized.new(normalized: e164, message: nil)
+        end
+
+        def self.failure(message)
+          Normalized.new(normalized: nil, message:)
+        end
+        private_class_method :failure
+      end
+    end
+  end
+end

data/app/services/command_tower/identity/phone_verification/sms_configuration.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Identity
+    module PhoneVerification
+      # Readiness detector for Identity phone-verification OTP SMS delivery.
+      # Distinct from Messaging notification SMS Configuration — same Twilio ENV
+      # names may be shared, but adapters and sender resolution differ.
+      class SmsConfiguration
+        def self.sms_ready?
+          new.sms_ready?
+        end
+
+        def sms_ready?
+          return false unless phone_verification.enable
+
+          case adapter_name
+          when "twilio"
+            twilio_credentials_present?
+          when "fake", "log"
+            # Intentional non-provider transports for test/development only.
+            !Rails.env.production?
+          else
+            false
+          end
+        end
+
+        def adapter_name
+          phone_verification.sms_adapter.to_s
+        end
+
+        private
+
+        def phone_verification
+          CommandTower.config.identity.phone_verification
+        end
+
+        def twilio_credentials_present?
+          account_sid.present? && auth_token.present? && from_number.present?
+        end
+
+        def account_sid
+          CredentialResolution.resolve(:twilio).account_sid
+        end
+
+        def auth_token
+          CredentialResolution.resolve(:twilio).auth_token
+        end
+
+        def from_number
+          phone_verification.sms_from.to_s.strip.presence ||
+            ENV["TWILIO_FROM"].to_s.strip.presence ||
+            ENV["TWILIO_FROM_NUMBER"].to_s.strip.presence
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/identity/phone_verification/sms_transport/adapters/fake_adapter.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Identity
+    module PhoneVerification
+      module SmsTransport
+        module Adapters
+          # In-memory / no-network adapter for tests and local default.
+          class FakeAdapter
+            class << self
+              attr_accessor :deliveries, :fail_with
+
+              def reset!
+                self.deliveries = []
+                self.fail_with = nil
+              end
+            end
+
+            self.reset!
+
+            def deliver(to:, body:)
+              if self.class.fail_with
+                code, message = self.class.fail_with
+                return SmsTransport::Result.new(success?: false, error_code: code, error_message: message)
+              end
+
+              self.class.deliveries << { to: to, body: body }
+              SmsTransport::Result.new(success?: true, error_code: nil, error_message: nil)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/identity/phone_verification/sms_transport/adapters/log_adapter.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Identity
+    module PhoneVerification
+      module SmsTransport
+        module Adapters
+          # Logs masked destination only — never OTP body in production logs.
+          class LogAdapter
+            def deliver(to:, body:)
+              Rails.logger.info(
+                {
+                  event: "phone_verification_sms_log_adapter",
+                  to_masked: mask_phone(to),
+                  body_length: body.to_s.length
+                }.to_json
+              )
+              SmsTransport::Result.new(success?: true, error_code: nil, error_message: nil)
+            end
+
+            private
+
+            def mask_phone(value)
+              digits = value.to_s.gsub(/\D/, "")
+              return "[redacted]" if digits.length < 4
+
+              "#{"*" * (digits.length - 4)}#{digits[-4,]}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/identity/phone_verification/sms_transport/adapters/twilio_adapter.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module CommandTower
+  module Identity
+    module PhoneVerification
+      module SmsTransport
+        module Adapters
+          # Smallest Twilio REST adapter. Requires Twilio credentials via
+          # CredentialResolution and identity.phone_verification.sms_from (or TWILIO_FROM).
+          class TwilioAdapter
+            def deliver(to:, body:)
+              twilio = CredentialResolution.resolve(:twilio)
+              account_sid = twilio.account_sid
+              auth_token = twilio.auth_token
+              from = CommandTower.config.identity.phone_verification.sms_from.presence ||
+                ENV["TWILIO_FROM"].to_s.presence ||
+                ENV["TWILIO_FROM_NUMBER"].to_s.presence
+
+              if account_sid.blank? || auth_token.blank? || from.blank?
+                return SmsTransport::Result.new(
+                  success?: false,
+                  error_code: :configuration_unavailable,
+                  error_message: "SMS provider is not configured"
+                )
+              end
+
+              uri = URI("https://api.twilio.com/2010-04-01/Accounts/#{account_sid}/Messages.json")
+              request = Net::HTTP::Post.new(uri)
+              request.basic_auth(account_sid, auth_token)
+              request.set_form_data("To" => to, "From" => from, "Body" => body)
+
+              response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
+                http.request(request)
+              end
+
+              if response.is_a?(Net::HTTPSuccess)
+                SmsTransport::Result.new(success?: true, error_code: nil, error_message: nil)
+              else
+                SmsTransport::Result.new(
+                  success?: false,
+                  error_code: :provider_unavailable,
+                  error_message: "SMS provider rejected the request"
+                )
+              end
+            rescue StandardError
+              SmsTransport::Result.new(
+                success?: false,
+                error_code: :provider_unavailable,
+                error_message: "SMS provider unavailable"
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/identity/phone_verification/sms_transport.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Identity
+    module PhoneVerification
+      # Vendor-agnostic SMS delivery for phone OTP. Identity depends on this interface only.
+      module SmsTransport
+        Result = Struct.new(:success?, :error_code, :error_message, keyword_init: true)
+
+        class << self
+          attr_writer :adapter
+
+          def adapter
+            @adapter ||= build_adapter
+          end
+
+          def reset_adapter!
+            @adapter = nil
+          end
+
+          def deliver(to:, body:)
+            adapter.deliver(to: to, body: body)
+          end
+
+          private
+
+          def build_adapter
+            name = CommandTower.config.identity.phone_verification.sms_adapter.to_s
+            case name
+            when "twilio"
+              Adapters::TwilioAdapter.new
+            when "log"
+              Adapters::LogAdapter.new
+            else
+              Adapters::FakeAdapter.new
+            end
+          end
+        end
+      end
+    end
+  end
+end