command_tower 0.3.1 → 0.10.0

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

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