command_tower 0.4.0 → 0.11.0

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

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Clients
+    class ClientBase
+      class << self
+        # Internal: resolve a provider class under +root+ via Zeitwerk const_get.
+        # Host product entry extends Invocation so +root+ is the host Clients module.
+        # Not the locked product invocation API.
+        def resolve_provider!(name, root: Clients)
+          const_name = ConstResolution.normalize_name(name)
+          path = "#{root.name}::#{const_name}"
+          klass = ConstResolution.const_get!(root, const_name, expected: "provider")
+
+          unless klass.is_a?(Class) && klass < ClientBase
+            raise Errors::DiscoveryError,
+                  "invalid provider inheritance: expected #{path} < #{ClientBase.name}"
+          end
+
+          klass
+        end
+      end
+
+      def initialize(transport: Transport::FaradayAdapter.new(config: Transport::FaradayConfig.from_env))
+        raise Errors::ConfigurationError, "transport is required" if transport.nil?
+
+        @transport = transport
+        @namespace_mutex = Mutex.new
+        @namespaces = {}
+      end
+
+      # Internal: resolve a namespace module under this provider and wrap NamespaceProxy.
+      # Not the locked product invocation API.
+      def resolve_namespace!(name)
+        const_name = ConstResolution.normalize_name(name)
+
+        @namespace_mutex.synchronize do
+          @namespaces[const_name] ||= build_namespace_proxy!(const_name)
+        end
+      end
+
+      # Primary execution contract.
+      # Accepts a normalized Clients::Transport::Request.
+      # Optional +context:+ is internal framework plumbing (typically ScopedClient).
+      def execute(request, context: nil)
+        validate_request!(request)
+
+        prepared = prepare_request(request, context: context)
+        started_at = monotonic_now
+
+        response = call_transport(prepared, started_at)
+        return response if response.is_a?(ClientResult)
+
+        build_result(response, started_at)
+      end
+
+    # Provider-owned authentication check. Default is a no-op so bare/test
+    # providers keep working; ScopedClient delegates opaque scope kwargs.
+    def enforce_authentication!(**)
+      nil
+    end
+
+      # Strip the transport wrapper before resource deserializers run.
+      # Default payload is the raw body — providers own encoding (JSON, XML, …).
+      def decode_response(response)
+        DecodedResponse.new(
+          payload: response.body,
+          provider_metadata: {}
+        )
+      end
+
+      protected
+
+      # Provider host root (and optional path prefix). Required only when the
+      # request URL is relative. Absolute request URLs are preserved as-is.
+      def base_url
+        nil
+      end
+
+      def default_headers
+        {}
+      end
+
+      def apply_authentication(request, context: nil)
+        request
+      end
+
+      def map_provider_error(response)
+        Errors::UpstreamError.new(
+          message: "Upstream request failed with status #{response.status}",
+          details: { status: response.status }
+        )
+      end
+
+      private
+
+      def build_namespace_proxy!(const_name)
+        path = "#{self.class.name}::#{const_name}"
+        mod = ConstResolution.const_get!(self.class, const_name, expected: "namespace")
+
+        unless mod.instance_of?(Module)
+          raise Errors::DiscoveryError,
+                "invalid namespace: expected #{path} to be a Module (Zeitwerk folder)"
+        end
+
+        NamespaceProxy.new(client: self, namespace_module: mod)
+      end
+
+      def validate_request!(request)
+        return if request.is_a?(Transport::Request)
+
+        raise Errors::ConfigurationError,
+              "request must be a #{Transport::Request.name}"
+      end
+
+      def prepare_request(request, context: nil)
+        with_defaults = Transport::Request.build(
+          method: request.method,
+          url: absolutize_url(request.url),
+          headers: default_headers.merge(request.headers),
+          body: request.body,
+          query: request.query,
+          timeout: request.timeout
+        )
+        apply_authentication(with_defaults, context: context)
+      end
+
+      def absolutize_url(url)
+        return url.to_s if Url.absolute?(url)
+
+        Url.join(base_url, url)
+      end
+
+      def call_transport(prepared, started_at)
+        response = @transport.call(prepared)
+        unless response.is_a?(Transport::Response)
+          raise Errors::ConfigurationError,
+                "transport must return a #{Transport::Response.name}"
+        end
+        response
+      rescue Transport::Error => e
+        ClientResult.failure(
+          error: Errors::UpstreamError.new(message: e.message, cause: e),
+          metadata: natural_metadata(status: nil, started_at: started_at, response: nil)
+        )
+      end
+
+      def build_result(response, started_at)
+        metadata = natural_metadata(
+          status: response.status,
+          started_at: started_at,
+          response: response
+        )
+
+        if response.success?
+          ClientResult.success(output: response, metadata: metadata)
+        else
+          ClientResult.failure(
+            error: map_provider_error(response),
+            output: response,
+            metadata: metadata
+          )
+        end
+      end
+
+      def natural_metadata(status:, started_at:, response:)
+        metadata = {}
+        metadata[:status] = status unless status.nil?
+        duration_ms = response&.duration_ms || elapsed_ms(started_at)
+        metadata[:duration_ms] = duration_ms unless duration_ms.nil?
+        metadata
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def elapsed_ms(started_at)
+        ((monotonic_now - started_at) * 1000).round
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Clients
+    class ClientResult
+      attr_reader :output, :error, :metadata, :provider_metadata
+
+      def initialize(success:, output:, error:, metadata:, provider_metadata: {})
+        @success = success
+        @output = output
+        @error = error
+        @metadata = metadata
+        @provider_metadata = provider_metadata
+      end
+
+      def success?
+        @success
+      end
+
+      def failure?
+        !success?
+      end
+
+      def self.success(output:, metadata: {}, provider_metadata: {})
+        new(
+          success: true,
+          output: output,
+          error: nil,
+          metadata: metadata,
+          provider_metadata: provider_metadata
+        )
+      end
+
+      def self.failure(error:, output: nil, metadata: {}, provider_metadata: {})
+        new(
+          success: false,
+          output: output,
+          error: error,
+          metadata: metadata,
+          provider_metadata: provider_metadata
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Clients
+    # Internal constant helpers for provider/namespace/endpoint resolution.
+    # Not a public product API — used by ClientBase / NamespaceProxy and tests.
+    module ConstResolution
+      module_function
+
+      def normalize_name(name)
+        raw = name.to_s.strip
+        if raw.empty?
+          raise Errors::DiscoveryError, "discovery name must be present"
+        end
+
+        raw.camelize
+      end
+
+      def const_get!(parent, name, expected:)
+        const_name = normalize_name(name)
+        path = "#{parent.name}::#{const_name}"
+
+        begin
+          parent.const_get(const_name, false)
+        rescue NameError
+          raise Errors::DiscoveryError,
+                "missing #{expected}: expected #{path}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Clients
+    # Internal handoff from provider decode_response → EndpointBase resource deserializer.
+    # Not a public product wrapper; not placed on ClientResult#output.
+    class DecodedResponse
+      attr_reader :payload, :provider_metadata
+
+      def initialize(payload:, provider_metadata: {})
+        @payload = payload
+        @provider_metadata = provider_metadata
+      end
+    end
+  end
+end

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

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Clients
+    class EndpointBase
+      AUTHENTICATION_MODES = %i[required none].freeze
+
+      class << self
+        attr_reader :declared_http_method, :declared_path, :declared_input_class,
+                    :declared_request_serializer, :declared_response_deserializer,
+                    :declared_authentication
+
+        def http_method(method)
+          @declared_http_method = Transport::Request.validate_method!(method)
+        end
+
+        def path(value = nil, &block)
+          if block && !value.nil?
+            raise Errors::ConfigurationError,
+                  "#{name} path must be a String or a block, not both"
+          end
+
+          @declared_path = block || value
+        end
+
+        def input(klass)
+          unless klass.is_a?(Class)
+            raise Errors::ConfigurationError,
+                  "#{name} input must be a Class (got: #{klass.inspect})"
+          end
+
+          @declared_input_class = klass
+        end
+
+        def request_serializer(serializer)
+          unless serializer.respond_to?(:call)
+            raise Errors::ConfigurationError,
+                  "#{name} request_serializer must respond to call " \
+                  "(got: #{serializer.inspect})"
+          end
+
+          @declared_request_serializer = serializer
+        end
+
+        def response_deserializer(deserializer)
+          unless deserializer.respond_to?(:call)
+            raise Errors::ConfigurationError,
+                  "#{name} response_deserializer must respond to call " \
+                  "(got: #{deserializer.inspect})"
+          end
+
+          @declared_response_deserializer = deserializer
+        end
+
+        # Default when omitted: :required. Public endpoints must opt out with :none.
+        def authentication(mode)
+          normalized = mode.to_sym
+          unless AUTHENTICATION_MODES.include?(normalized)
+            raise Errors::ConfigurationError,
+                  "#{name} authentication must be one of " \
+                  "#{AUTHENTICATION_MODES.join(', ')} (got: #{mode.inspect})"
+          end
+
+          @declared_authentication = normalized
+        end
+
+        def authentication_mode
+          declared_authentication || :required
+        end
+      end
+
+      attr_reader :client
+
+      def initialize(client:)
+        raise Errors::ConfigurationError, "client is required" if client.nil?
+
+        @client = client
+      end
+
+      # Internal orchestration — not the locked product invocation API.
+      # Builds input, serializes, executes, then deserializes a successful response
+      # into a top-level provider contract object or Array of contracts.
+      def call(**attributes)
+        assert_declarations!
+        enforce_authentication_if_required!
+        input = build_input!(attributes)
+        path = resolve_path(input)
+        serialized = serialize_request!(input)
+
+        request = Transport::Request.build(
+          method: self.class.declared_http_method,
+          url: path,
+          query: serialized.query,
+          body: serialized.body,
+          headers: serialized.headers
+        )
+
+        result = client.execute(request)
+        return result if result.failure?
+
+        deserialize_success!(result)
+      end
+
+      private
+
+      def enforce_authentication_if_required!
+        return if self.class.authentication_mode == :none
+
+        client.enforce_authentication!
+      end
+
+      def assert_declarations!
+        missing = []
+        missing << "http_method" if self.class.declared_http_method.nil?
+        missing << "path" if self.class.declared_path.nil?
+        missing << "input" if self.class.declared_input_class.nil?
+        missing << "request_serializer" if self.class.declared_request_serializer.nil?
+        missing << "response_deserializer" if self.class.declared_response_deserializer.nil?
+
+        return if missing.empty?
+
+        raise Errors::ConfigurationError,
+              "#{self.class.name} is missing endpoint declarations: #{missing.join(', ')}"
+      end
+
+      def build_input!(attributes)
+        self.class.declared_input_class.new(**attributes)
+      rescue ArgumentError => e
+        raise Errors::ConfigurationError,
+              "#{self.class.name} failed to build input " \
+              "#{self.class.declared_input_class.name}: #{e.message}",
+              cause: e
+      end
+
+      def resolve_path(input)
+        declared = self.class.declared_path
+        path = if declared.respond_to?(:call)
+                 declared.call(input)
+        else
+                 declared
+        end
+
+        path = path.to_s
+        if path.strip.empty?
+          raise Errors::ConfigurationError,
+                "#{self.class.name} resolved path must be present"
+        end
+
+        path
+      end
+
+      def serialize_request!(input)
+        serializer = self.class.declared_request_serializer
+        unless serializer.respond_to?(:call)
+          raise Errors::ConfigurationError,
+                "#{self.class.name} request_serializer must respond to call"
+        end
+
+        serialized = serializer.call(input)
+        return serialized if serialized.is_a?(SerializedRequest)
+
+        raise Errors::ConfigurationError,
+              "#{self.class.name} request_serializer must return " \
+              "#{SerializedRequest.name} (got: #{serialized.class.name})"
+      end
+
+      def deserialize_success!(result)
+        deserializer = self.class.declared_response_deserializer
+        unless deserializer.respond_to?(:call)
+          raise Errors::ConfigurationError,
+                "#{self.class.name} response_deserializer must respond to call"
+        end
+
+        decoded = nil
+        begin
+          decoded = client.decode_response(result.output)
+          output = deserializer.call(decoded.payload)
+          validate_top_level_output!(output)
+
+          ClientResult.success(
+            output: output,
+            metadata: result.metadata,
+            provider_metadata: decoded.provider_metadata
+          )
+        rescue Errors::DeserializationError, JSON::ParserError, KeyError, TypeError => e
+          ClientResult.failure(
+            error: wrap_deserialization_error(e, deserializer),
+            output: nil,
+            metadata: result.metadata,
+            provider_metadata: decoded&.provider_metadata || {}
+          )
+        end
+      end
+
+      def validate_top_level_output!(output)
+        if output.nil?
+          raise Errors::ConfigurationError,
+                "#{self.class.name} response_deserializer must not return nil"
+        end
+
+        if output.is_a?(Hash)
+          raise Errors::ConfigurationError,
+                "#{self.class.name} response_deserializer must not return a Hash"
+        end
+
+        return unless output.is_a?(Transport::Response)
+
+        raise Errors::ConfigurationError,
+              "#{self.class.name} response_deserializer must not return " \
+              "#{Transport::Response.name}"
+      end
+
+      def wrap_deserialization_error(error, deserializer)
+        if error.is_a?(Errors::DeserializationError) &&
+           error.details.is_a?(Hash) &&
+           error.details[:endpoint].present?
+          return error
+        end
+
+        details = {
+          endpoint: self.class.name,
+          response_deserializer: deserializer_name(deserializer)
+        }
+
+        if error.is_a?(Errors::DeserializationError) && error.details.is_a?(Hash)
+          details = error.details.merge(details)
+        end
+
+        Errors::DeserializationError.new(
+          message: "#{self.class.name} failed to deserialize response " \
+                   "via #{deserializer_name(deserializer)}: #{error.message}",
+          details: details,
+          cause: error.is_a?(Errors::DeserializationError) ? error.cause || error : error
+        )
+      end
+
+      def deserializer_name(deserializer)
+        deserializer.respond_to?(:name) && deserializer.name.present? ? deserializer.name : deserializer.inspect
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Clients
+    # Validation-capable endpoint argument objects.
+    # Construct once in EndpointBase; do not mutate after construction (convention).
+    # Untyped attributes only — typing/validation policy deferred.
+    class EndpointInput
+      include ActiveModel::Model
+      include ActiveModel::Attributes
+
+      def ==(other)
+        other.instance_of?(self.class) && attributes == other.attributes
+      end
+      alias eql? ==
+    end
+  end
+end

data/app/services/command_tower/clients/errors/authentication_error.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Clients
+    module Errors
+      class AuthenticationError < CommandTower::Errors::ApplicationError
+        def initialize(message: nil, details: nil, cause: nil)
+          @message = message
+          super(details: details, cause: cause)
+        end
+
+        def code
+          "authentication_error"
+        end
+
+        def message
+          @message.presence || "Client authentication failed"
+        end
+
+        def log_level
+          :warn
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/clients/errors/configuration_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Clients
+    module Errors
+      class ConfigurationError < StandardError
+      end
+    end
+  end
+end

data/app/services/command_tower/clients/errors/deserialization_error.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Clients
+    module Errors
+      class DeserializationError < CommandTower::Errors::ApplicationError
+        def initialize(message: nil, details: nil, cause: nil)
+          @message = message
+          super(details: details, cause: cause)
+        end
+
+        def code
+          "deserialization_error"
+        end
+
+        def message
+          @message.presence || "Failed to deserialize upstream response"
+        end
+
+        def log_level
+          :warn
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/clients/errors/discovery_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Clients
+    module Errors
+      class DiscoveryError < ConfigurationError
+      end
+    end
+  end
+end

data/app/services/command_tower/clients/errors/upstream_error.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Clients
+    module Errors
+      class UpstreamError < CommandTower::Errors::ApplicationError
+        def initialize(message: nil, details: nil, cause: nil)
+          @message = message
+          super(details: details, cause: cause)
+        end
+
+        def code
+          "upstream_error"
+        end
+
+        def message
+          @message.presence || "Upstream request failed"
+        end
+
+        def log_level
+          :warn
+        end
+      end
+    end
+  end
+end