client-api-builder 0.5.6 → 0.6.0

data/lib/client_api_builder/router.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 require 'inheritance-helper'
 require 'json'
 
@@ -14,11 +15,25 @@ module ClientApiBuilder
     end
 
     module ClassMethods
-      REQUIRED_BODY_HTTP_METHODS = [
-        :post,
-        :put,
-        :patch
-      ]
+      REQUIRED_BODY_HTTP_METHODS = %i[
+        post
+        put
+        patch
+      ].freeze
+
+      # Allowed URL schemes for base_url to prevent SSRF attacks
+      ALLOWED_URL_SCHEMES = %w[http https].freeze
+
+      # Deep duplicates a hash to prevent shared mutable state
+      def deep_dup_hash(hash)
+        hash.transform_values do |value|
+          case value
+          when Hash then deep_dup_hash(value)
+          when Array then value.map { |v| v.is_a?(Hash) ? deep_dup_hash(v) : v }
+          else value
+          end
+        end
+      end
 
       def default_options
         {
@@ -36,7 +51,7 @@ module ClientApiBuilder
 
       # tracks the proc used to handle responses
       def add_response_proc(method_name, proc)
-        response_procs = default_options[:response_procs].dup
+        response_procs = deep_dup_hash(default_options[:response_procs])
         response_procs[method_name] = proc
         add_value_to_class_method(:default_options, response_procs: response_procs)
       end
@@ -47,12 +62,24 @@ module ClientApiBuilder
       end
 
       # set/get base url
+      # Validates URL scheme to prevent SSRF attacks
       def base_url(url = nil)
         return default_options[:base_url] unless url
 
+        validate_base_url!(url)
         add_value_to_class_method(:default_options, base_url: url)
       end
 
+      # Validates that base_url uses an allowed scheme
+      def validate_base_url!(url)
+        uri = URI.parse(url.to_s)
+        return if ALLOWED_URL_SCHEMES.include?(uri.scheme&.downcase)
+
+        raise ArgumentError, "Invalid base_url scheme: #{uri.scheme.inspect}. Allowed: #{ALLOWED_URL_SCHEMES.join(', ')}"
+      rescue URI::InvalidURIError => e
+        raise ArgumentError, "Invalid base_url: #{e.message}"
+      end
+
       # set the builder to :to_json, :to_query, :query_params or specify a proc to handle building the request body payload
       # or get the body builder
       def body_builder(builder = nil, &block)
@@ -71,14 +98,14 @@ module ClientApiBuilder
 
       # add a request header
       def header(name, value = nil, &block)
-        headers = default_options[:headers].dup
+        headers = deep_dup_hash(default_options[:headers])
         headers[name] = value || block
         add_value_to_class_method(:default_options, headers: headers)
       end
 
       # set a connection_option, specific to Net::HTTP
       def connection_option(name, value)
-        connection_options = default_options[:connection_options].dup
+        connection_options = deep_dup_hash(default_options[:connection_options])
         connection_options[name] = value
         add_value_to_class_method(:default_options, connection_options: connection_options)
       end
@@ -93,7 +120,7 @@ module ClientApiBuilder
 
       # add a query param to all requests
       def query_param(name, value = nil, &block)
-        query_params = default_options[:query_params].dup
+        query_params = deep_dup_hash(default_options[:query_params])
         query_params[name] = value || block
         add_value_to_class_method(:default_options, query_params: query_params)
       end
@@ -175,7 +202,10 @@ module ClientApiBuilder
           when Array
             arguments += get_array_arguments(v)
           when String
-            hsh[k] = "__||#{$1}||__" if v =~ /\{([a-z0-9_]+)\}/i
+            # Use match with block form to avoid thread-unsafe $1 global variable
+            if (match = v.match(/\{([a-z0-9_]+)\}/i))
+              hsh[k] = "__||#{match[1]}||__"
+            end
           end
         end
         arguments
@@ -193,7 +223,10 @@ module ClientApiBuilder
           when Array
             arguments += get_array_arguments(v)
           when String
-            list[idx] = "__||#{$1}||__" if v =~ /\{([a-z0-9_]+)\}/i
+            # Use match with block form to avoid thread-unsafe $1 global variable
+            if (match = v.match(/\{([a-z0-9_]+)\}/i))
+              list[idx] = "__||#{match[1]}||__"
+            end
           end
         end
         arguments
@@ -212,140 +245,165 @@ module ClientApiBuilder
       end
 
       def get_instance_method(var)
-         "#\{escape_path(#{var})\}"
+        "#\{escape_path(#{var})}"
       end
 
-      @@namespaces = []
+      # Thread-local storage key for namespaces to ensure thread safety
+      NAMESPACE_THREAD_KEY = :client_api_builder_namespaces
+
       def namespaces
-        @@namespaces
+        Thread.current[NAMESPACE_THREAD_KEY] ||= []
       end
 
       # a namespace is a top level path to apply to all routes within the namespace block
       def namespace(name)
         namespaces << name
         yield
+      ensure
+        # Always pop the namespace, even if an exception occurs during yield
         namespaces.pop
       end
 
-      def generate_route_code(method_name, path, options = {})
-        http_method = options[:method] || auto_detect_http_method(method_name)
-
+      def process_route_path(path)
         path = namespaces.join + path
 
-        # instance method
-        path.gsub!(/\{([a-z0-9_]+)\}/i) do |_|
-          get_instance_method($1)
+        # instance method - use block parameter to avoid thread-unsafe $1
+        path = path.gsub(/\{([a-z0-9_]+)\}/i) do |_match|
+          get_instance_method(Regexp.last_match(1))
         end
 
         path_arguments = []
-        path.gsub!(/:([a-z0-9_]+)/i) do |_|
-          path_arguments << $1
-          "#\{escape_path(#{$1})\}"
+        path = path.gsub(/:([a-z0-9_]+)/i) do |_match|
+          param_name = Regexp.last_match(1)
+          path_arguments << param_name
+          "#\{escape_path(#{param_name})}"
         end
 
-        has_body_param = options[:body].nil? && requires_body?(http_method, options)
+        [path, path_arguments]
+      end
 
-        query =
-          if options[:query]
-            query_arguments = get_arguments(options[:query])
-            str = options[:query].inspect
-            str.gsub!(/"__\|\|(.+?)\|\|__"/) { $1 }
-            str
-          else
-            query_arguments = []
-            'nil'
-          end
+      def build_query_code(options)
+        if options[:query]
+          query_arguments = get_arguments(options[:query])
+          str = options[:query].inspect
+          str = str.gsub(/"__\|\|(.+?)\|\|__"/) { Regexp.last_match(1) }
+          [str, query_arguments.map(&:to_s)]
+        else
+          ['nil', []]
+        end
+      end
 
-        body =
-          if options[:body]
-            has_body_param = false
-            body_arguments = get_arguments(options[:body])
-            str = options[:body].inspect
-            str.gsub!(/"__\|\|(.+?)\|\|__"/) { $1 }
-            str
-          else
-            body_arguments = []
-            has_body_param ? 'body' : 'nil'
-          end
+      def build_body_code(options, has_body_param)
+        if options[:body]
+          body_arguments = get_arguments(options[:body])
+          str = options[:body].inspect
+          str = str.gsub(/"__\|\|(.+?)\|\|__"/) { Regexp.last_match(1) }
+          [str, body_arguments.map(&:to_s), false]
+        else
+          [has_body_param ? 'body' : 'nil', [], has_body_param]
+        end
+      end
 
-        query_arguments.map!(&:to_s)
-        body_arguments.map!(&:to_s)
-        named_arguments = path_arguments + query_arguments + body_arguments
-        named_arguments.uniq!
+      def extract_expected_response_codes(options)
+        codes = options[:expected_response_codes] || (options[:expected_response_code] ? [options[:expected_response_code]] : [])
+        codes.map(&:to_s)
+      end
 
-        expected_response_codes =
-          if options[:expected_response_codes]
-            options[:expected_response_codes]
-          elsif options[:expected_response_code]
-            [options[:expected_response_code]]
-          else
-            []
-          end
-        expected_response_codes.map!(&:to_s)
-
-        stream_param =
-          case options[:stream]
-          when true,
-               :file
-            :file
-          when :io
-            :io
-          end
+      def determine_stream_param(options)
+        case options[:stream]
+        when true, :file then :file
+        when :io then :io
+        end
+      end
+
+      def build_method_args(named_arguments, has_body_param, stream_param)
+        args = named_arguments.map { |arg_name| "#{arg_name}:" }
+        args += ['body:'] if has_body_param
+        args += ["#{stream_param}:"] if stream_param
+        args + ['**__options__', '&block']
+      end
+
+      def generate_request_call_code(options, stream_param)
+        code = "  @request_options[:#{stream_param}] = #{stream_param}\n" if stream_param
+        code ||= ''
+
+        code + case options[:stream]
+               when true, :file then "  @response = stream_to_file(**@request_options)\n"
+               when :io then "  @response = stream_to_io(**@request_options)\n"
+               when :block then "  @response = stream(**@request_options, &block)\n"
+               else "  @response = request(**@request_options)\n"
+               end
+      end
 
-        method_args = named_arguments.map { |arg_name| "#{arg_name}:" }
-        method_args += ['body:'] if has_body_param
-        method_args += ["#{stream_param}:"] if stream_param
-        method_args += ['**__options__', '&block']
+      def generate_response_handling_code(options)
+        if options[:stream] || options[:return] == :response
+          "    @response\n"
+        elsif options[:return] == :body
+          "    @response.body\n"
+        else
+          "    handle_response(@response, __options__, &block)\n"
+        end
+      end
+
+      def generate_route_code(method_name, path, options = {})
+        # Validate method_name to prevent code injection
+        raise ArgumentError, "Invalid method name: #{method_name.inspect}" unless method_name.to_s.match?(/\A[a-z_][a-z0-9_]*\z/i)
 
-        code = "def #{method_name}_raw_response(" + method_args.join(', ') + ")\n"
-        code += "  __path__ = \"#{path}\"\n"
-        code += "  __query__ = #{query}\n"
-        code += "  __body__ = #{body}\n"
+        http_method = options[:method] || auto_detect_http_method(method_name)
+        path, path_arguments = process_route_path(path)
+        has_body_param = options[:body].nil? && requires_body?(http_method, options)
+
+        query, query_arguments = build_query_code(options)
+        body, body_arguments, has_body_param = build_body_code(options, has_body_param)
+
+        named_arguments = (path_arguments + query_arguments + body_arguments).uniq
+        expected_response_codes = extract_expected_response_codes(options)
+        stream_param = determine_stream_param(options)
+        method_args = build_method_args(named_arguments, has_body_param, stream_param)
+
+        route_context = {
+          method_name: method_name, method_args: method_args, path: path,
+          query: query, body: body, http_method: http_method,
+          options: options, stream_param: stream_param,
+          expected_response_codes: expected_response_codes
+        }
+
+        generate_raw_response_method(route_context) + generate_wrapper_method(route_context)
+      end
+
+      def generate_raw_response_method(ctx)
+        code = "def #{ctx[:method_name]}_raw_response(#{ctx[:method_args].join(', ')})\n"
+        code += "  __path__ = \"#{ctx[:path]}\"\n"
+        code += "  __query__ = #{ctx[:query]}\n"
+        code += "  __body__ = #{ctx[:body]}\n"
         code += "  __uri__ = build_uri(__path__, __query__, __options__)\n"
         code += "  __body__ = build_body(__body__, __options__)\n"
         code += "  __headers__ = build_headers(__options__)\n"
         code += "  __connection_options__ = build_connection_options(__options__)\n"
-        code += "  @request_options = {method: #{http_method.inspect}, uri: __uri__, body: __body__, headers: __headers__, connection_options: __connection_options__}\n"
-        code += "  @request_options[:#{stream_param}] = #{stream_param}\n" if stream_param
+        code += "  @request_options = {method: #{ctx[:http_method].inspect}, uri: __uri__, body: __body__, " \
+                "headers: __headers__, connection_options: __connection_options__}\n"
+        code += generate_request_call_code(ctx[:options], ctx[:stream_param])
+        code + "end\n\n"
+      end
 
-        case options[:stream]
-        when true,
-             :file
-          code += "  @response = stream_to_file(**@request_options)\n"
-        when :io
-          code += "  @response = stream_to_io(**@request_options)\n"
-        when :block
-          code += "  @response = stream(**@request_options, &block)\n"
-        else
-          code += "  @response = request(**@request_options)\n"
-        end
-        code += "end\n"
-        code += "\n"
+      def generate_wrapper_method(ctx)
+        raw_call_args = ctx[:method_args].map { |a| a =~ /:$/ ? "#{a} #{a.sub(':', '')}" : a }.join(', ')
 
-        code += "def #{method_name}(" + method_args.join(', ') + ")\n"
+        code = "def #{ctx[:method_name]}(#{ctx[:method_args].join(', ')})\n"
         code += "  request_wrapper(__options__) do\n"
-        code += "    block ||= self.class.get_response_proc(#{method_name.inspect})\n"
-        code += "    __expected_response_codes__ = #{expected_response_codes.inspect}\n"
-        code += "    #{method_name}_raw_response(" + method_args.map { |a| a =~ /:$/ ? "#{a} #{a.sub(':', '')}" : a }.join(', ') + ")\n"
+        code += "    block ||= self.class.get_response_proc(#{ctx[:method_name].inspect})\n"
+        code += "    __expected_response_codes__ = #{ctx[:expected_response_codes].inspect}\n"
+        code += "    #{ctx[:method_name]}_raw_response(#{raw_call_args})\n"
         code += "    expected_response_code!(@response, __expected_response_codes__, __options__)\n"
-
-        if options[:stream] || options[:return] == :response
-          code += "    @response\n"
-        elsif options[:return] == :body
-          code += "    @response.body\n"
-        else
-          code += "    handle_response(@response, __options__, &block)\n"
-        end
-
+        code += generate_response_handling_code(ctx[:options])
         code += "  end\n"
-        code += "end\n"
-        code
+        code + "end\n"
       end
 
       def route(method_name, path, options = {}, &block)
         add_response_proc(method_name, block) if block
 
-        self.class_eval generate_route_code(method_name, path, options), __FILE__, __LINE__
+        class_eval generate_route_code(method_name, path, options), __FILE__, __LINE__
       end
     end
 
@@ -368,7 +426,7 @@ module ClientApiBuilder
       end
 
       self.class.default_headers.each(&add_header_proc)
-      options[:headers] && options[:headers].each(&add_header_proc)
+      options[:headers]&.each(&add_header_proc)
 
       headers
     end
@@ -396,8 +454,8 @@ module ClientApiBuilder
       end
 
       self.class.default_query_params.each(&add_query_param_proc)
-      query && query.each(&add_query_param_proc)
-      options[:query] && options[:query].each(&add_query_param_proc)
+      query&.each(&add_query_param_proc)
+      options[:query]&.each(&add_query_param_proc)
 
       query_params.empty? ? nil : self.class.build_query(self, query_params)
     end
@@ -412,20 +470,34 @@ module ClientApiBuilder
     end
 
     def build_uri(path, query, options)
-      uri = URI(base_url + path)
+      # Properly join base_url and path to handle missing/extra slashes
+      base = base_url.to_s
+      base = base.chomp('/') if base.end_with?('/')
+      path = path.to_s
+      path = "/#{path}" unless path.start_with?('/')
+
+      uri = URI(base + path)
       uri.query = build_query(query, options)
       uri
     end
 
-    def expected_response_code!(response, expected_response_codes, options)
-      return if expected_response_codes.empty? && response.kind_of?(Net::HTTPSuccess)
+    def expected_response_code!(response, expected_response_codes, _options)
+      return if expected_response_codes.empty? && response.is_a?(Net::HTTPSuccess)
       return if expected_response_codes.include?(response.code)
 
       raise(::ClientApiBuilder::UnexpectedResponse.new("unexpected response code #{response.code}", response))
     end
 
-    def parse_response(response, options)
-      response.body && JSON.parse(response.body)
+    def parse_response(response, _options)
+      body = response.body
+      return nil if body.nil? || body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError => e
+      raise ::ClientApiBuilder::UnexpectedResponse.new(
+        "Invalid JSON in response: #{e.message}",
+        response
+      )
     end
 
     def handle_response(response, options, &block)
@@ -467,16 +539,18 @@ module ClientApiBuilder
       begin
         @request_attempts += 1
         yield
-      rescue Exception => e
+      rescue StandardError => e
+        # Use StandardError instead of Exception to allow SystemExit, Interrupt, etc. to propagate
         log_request_exception(e)
         raise(e) if @request_attempts >= max_attempts || !retry_request?(e, options)
+
         sleep_time = get_retry_request_sleep_time(e, options)
-        sleep(sleep_time) if sleep_time && sleep_time > 0
+        sleep(sleep_time) if sleep_time&.positive?
         retry
       end
     end
 
-    def get_retry_request_sleep_time(e, options)
+    def get_retry_request_sleep_time(_e, options)
       options[:sleep] || self.class.default_options[:sleep] || 0.05
     end
 
@@ -484,28 +558,39 @@ module ClientApiBuilder
       options[:retries] || self.class.default_options[:max_retries] || 1
     end
 
-    def request_wrapper(options)
+    def request_wrapper(options, &block)
       retry_request(options) do
-        instrument_request do
-          yield
-        end
+        instrument_request(&block)
       end
     end
 
-    def retry_request?(exception, options)
-      true
+    # Determines whether to retry on a given exception.
+    # Override this method to customize retry behavior.
+    # By default, only retries on network-related errors, not application errors.
+    def retry_request?(exception, _options)
+      case exception
+      when Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNRESET,
+           Errno::ECONNREFUSED, Errno::ETIMEDOUT, SocketError, EOFError
+        true
+      else
+        false
+      end
     end
 
     def log_request_exception(exception)
-      ::ClientApiBuilder.logger && ::ClientApiBuilder.logger.error(exception)
+      ::ClientApiBuilder.logger&.error(exception)
     end
 
     def request_log_message
+      return '' unless request_options
+
       method = request_options[:method].to_s.upcase
       uri = request_options[:uri]
+      return "#{method} [no URI]" unless uri
+
       response_code = response ? response.code : 'UNKNOWN'
+      duration = total_request_time ? (total_request_time * 1000).to_i : 0
 
-      duration = (total_request_time * 1000).to_i
       "#{method} #{uri.scheme}://#{uri.host}#{uri.path}[#{response_code}] took #{duration}ms"
     end
   end

data/lib/client_api_builder/section.rb

@@ -8,26 +8,26 @@ module ClientApiBuilder
     end
 
     module ClassMethods
-      def section(name, nested_router_options={}, &block)
+      def section(name, nested_router_options = {}, &)
         kls = InheritanceHelper::ClassBuilder::Utils.create_class(
           self,
           name,
           ::ClientApiBuilder::NestedRouter,
           nil,
           'NestedRouter',
-          &block
+          &
         )
 
-        code = <<CODE
-def self.#{name}_router
-  #{kls.name}
-end
+        code = <<~CODE
+          def self.#{name}_router
+            #{kls.name}
+          end
 
-def #{name}
-  @#{name} ||= self.class.#{name}_router.new(self.root_router, #{nested_router_options.inspect})
-end
-CODE
-        self.class_eval code, __FILE__, __LINE__
+          def #{name}
+            @#{name} ||= self.class.#{name}_router.new(self.root_router, #{nested_router_options.inspect})
+          end
+        CODE
+        class_eval code, __FILE__, __LINE__
       end
     end
   end

data/script/console

@@ -8,7 +8,7 @@ autoload :BasicAuthExampleClient, 'basic_auth_example_client'
 autoload :IMDBDatesetsClient, 'imdb_datasets_client'
 autoload :LoremIpsumClient, 'lorem_ipsum_client'
 require 'logger'
-LOG = Logger.new(STDOUT)
+LOG = Logger.new($stdout)
 ClientApiBuilder.logger = LOG
 ClientApiBuilder::ActiveSupportLogSubscriber.new(LOG).subscribe!
 require 'irb'

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: client-api-builder
 version: !ruby/object:Gem::Version
-  version: 0.5.6
+  version: 0.6.0
 platform: ruby
 authors:
 - Doug Youch
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-05-05 00:00:00.000000000 Z
+date: 2026-01-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: inheritance-helper
@@ -24,17 +23,25 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.2.5
-description: Create API clients through configuration with complete transparency
+description: |
+  A Ruby gem for building API clients through declarative configuration. Features include
+  automatic HTTP method detection, nested routing, streaming support, configurable retries,
+  and security features like SSL verification, SSRF protection, and path traversal prevention.
+  Define your API endpoints with a clean DSL and get comprehensive error handling, debugging
+  capabilities, and optional ActiveSupport integration for logging and instrumentation.
 email: dougyouch@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - ".cursor.json"
+- ".github/workflows/ci.yml"
 - ".gitignore"
+- ".rubocop.yml"
 - ".ruby-gemset"
 - ".ruby-version"
 - ARCHITECTURE.md
+- CLAUDE.md
 - Gemfile
 - Gemfile.lock
 - LICENSE
@@ -55,8 +62,12 @@ files:
 homepage: https://github.com/dougyouch/client-api-builder
 licenses:
 - MIT
-metadata: {}
-post_install_message:
+metadata:
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/dougyouch/client-api-builder
+  source_code_uri: https://github.com/dougyouch/client-api-builder
+  changelog_uri: https://github.com/dougyouch/client-api-builder/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/dougyouch/client-api-builder/issues
 rdoc_options: []
 require_paths:
 - lib
@@ -64,15 +75,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.3
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
-summary: Utility for creating API clients through configuration
+summary: Build robust, secure API clients through declarative configuration
 test_files: []