command_tower 0.4.0 → 0.11.0

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Clients
+    # Product invocation boundary mixin.
+    # Host: `module Clients; extend CommandTower::Clients::Invocation; end`
+    # then `Clients.mariana_tek(user:)` / `Clients.mariana_tek(access_token:)`.
+    # Provider resolution uses the extending module as the provider root (+self+).
+    module Invocation
+      def method_missing(name, *args, **scope, &block)
+        return super if block || args.any?
+
+        ScopedClient.new(provider: provider_for!(name), **scope)
+      rescue Errors::DiscoveryError
+        super
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        ClientBase.resolve_provider!(name, root: self)
+        true
+      rescue Errors::DiscoveryError
+        super
+      end
+
+      def provider_for!(name)
+        const_name = ConstResolution.normalize_name(name)
+
+        providers_mutex.synchronize do
+          providers[const_name] ||= ClientBase.resolve_provider!(name, root: self).new
+        end
+      end
+
+      # Test helper — clears memoized providers (and their transport pools).
+      def reset_providers!
+        providers_mutex.synchronize do
+          providers.clear
+        end
+      end
+
+      # Test helper — seed a provider instance under a normalized name.
+      def seed_provider!(name, provider)
+        const_name = ConstResolution.normalize_name(name)
+        providers_mutex.synchronize do
+          providers[const_name] = provider
+        end
+      end
+
+      private
+
+      def providers_mutex
+        @providers_mutex ||= Mutex.new
+      end
+
+      def providers
+        @providers ||= {}
+      end
+    end
+
+    extend Invocation
+  end
+end

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Clients
+    # Lightweight handle for a Zeitwerk namespace module under a provider.
+    # Internal resolution primitive — not the locked product invocation API.
+    class NamespaceProxy
+      attr_reader :client, :namespace_module
+
+      def initialize(client:, namespace_module:)
+        raise Errors::ConfigurationError, "client is required" if client.nil?
+        raise Errors::ConfigurationError, "namespace_module is required" if namespace_module.nil?
+
+        @client = client
+        @namespace_module = namespace_module
+        @endpoint_mutex = Mutex.new
+        @endpoints = {}
+        @endpoint_classes = {}
+      end
+
+      # Resolve and memoize an EndpointBase instance bound to this proxy's client.
+      # Prefer #build_endpoint for ScopedClient so user-bound instances are not shared.
+      def resolve_endpoint!(name)
+        const_name = ConstResolution.normalize_name(name)
+
+        @endpoint_mutex.synchronize do
+          @endpoints[const_name] ||= build_endpoint_instance!(
+            resolve_endpoint_class_locked!(const_name),
+            client: client
+          )
+        end
+      end
+
+      # Memoize endpoint class resolution only; always return a fresh instance.
+      def build_endpoint(name, client:)
+        klass = resolve_endpoint_class!(name)
+        build_endpoint_instance!(klass, client: client)
+      end
+
+      def resolve_endpoint_class!(name)
+        const_name = ConstResolution.normalize_name(name)
+
+        @endpoint_mutex.synchronize do
+          resolve_endpoint_class_locked!(const_name)
+        end
+      end
+
+      private
+
+      def resolve_endpoint_class_locked!(const_name)
+        @endpoint_classes[const_name] ||= fetch_endpoint_class!(const_name)
+      end
+
+      def fetch_endpoint_class!(const_name)
+        path = "#{namespace_module.name}::#{const_name}"
+        klass = ConstResolution.const_get!(
+          namespace_module,
+          const_name,
+          expected: "endpoint"
+        )
+
+        unless klass.is_a?(Class) && klass < EndpointBase
+          raise Errors::DiscoveryError,
+                  "invalid endpoint inheritance: expected #{path} < #{EndpointBase.name}"
+        end
+
+        klass
+      end
+
+      def build_endpoint_instance!(klass, client:)
+        klass.new(client: client)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Clients
+    # Request-scoped handle around a memoized provider. Holds opaque scope kwargs
+    # (e.g. user:, access_token:) without interpreting provider credentials.
+    class ScopedClient
+      attr_reader :provider, :scope
+
+      def initialize(provider:, **scope)
+        raise Errors::ConfigurationError, "provider is required" if provider.nil?
+
+        @provider = provider
+        @scope = scope.freeze
+        @namespace_mutex = Mutex.new
+        @namespaces = {}
+      end
+
+      def user
+        scope[:user]
+      end
+
+      def [](key)
+        scope[key]
+      end
+
+      def enforce_authentication!
+        provider.enforce_authentication!(**scope)
+      end
+
+      def execute(request)
+        provider.execute(request, context: self)
+      end
+
+      def decode_response(response)
+        provider.decode_response(response)
+      end
+
+      def method_missing(name, *args, **kwargs, &block)
+        return super if block || args.any? || !kwargs.empty?
+
+        NamespaceHandle.new(
+          scoped_client: self,
+          namespace_proxy: resolve_namespace_proxy!(name)
+        )
+      rescue Errors::DiscoveryError
+        super
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        resolve_namespace_proxy!(name)
+        true
+      rescue Errors::DiscoveryError
+        super
+      end
+
+      # Fresh endpoint instances bound to this scoped client (not memoized).
+      class NamespaceHandle
+        def initialize(scoped_client:, namespace_proxy:)
+          @scoped_client = scoped_client
+          @namespace_proxy = namespace_proxy
+        end
+
+        def method_missing(name, *args, **attributes, &block)
+          raise ArgumentError, "endpoint invocation does not take a block" if block
+          raise ArgumentError, "endpoint invocation does not take positional args" if args.any?
+
+          endpoint = @namespace_proxy.build_endpoint(name, client: @scoped_client)
+          endpoint.call(**attributes)
+        end
+
+        def respond_to_missing?(_name, _include_private = false)
+          true
+        end
+      end
+
+      private
+
+      def resolve_namespace_proxy!(name)
+        const_name = ConstResolution.normalize_name(name)
+
+        @namespace_mutex.synchronize do
+          @namespaces[const_name] ||= provider.resolve_namespace!(name)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Clients
+    # Pure serializer output for endpoint request assembly.
+    # Not a Hash — keeps the client framework on typed value objects.
+    SerializedRequest = Data.define(:query, :body, :headers) do
+      def self.build(query: {}, body: nil, headers: {})
+        new(
+          query: query.to_h,
+          body: body,
+          headers: headers.to_h
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Clients
+    module Transport
+      # Expected outbound transport failures (timeout, connection refused, etc.).
+      # ClientBase maps these to failed ClientResult values — they are not framework defects.
+      class Error < StandardError
+        attr_reader :cause
+
+        def initialize(message = nil, cause: nil)
+          @cause = cause
+          super(message)
+        end
+      end
+    end
+  end
+end

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