client-api-builder 0.7.1 → 0.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00351abdc1f660fefd19687f75b696db8a1b9b16390ff6427706a8f5db64ee74
-  data.tar.gz: 34dac63d4090971accab88566f4c217ccdb5a1d21ba000281ad5e2ea68bd74cb
+  metadata.gz: aac435317feb174db101e201b00464222bfc2df0f10601ac88e7897c3694be27
+  data.tar.gz: '08ad14efc0bff6c1f6e7fd4864e26c6f41853d72808fdc84b0e4781a0cfd229f'
 SHA512:
-  metadata.gz: b34e2623702b08c9ac8156e8f0fe9da060636823492ec49bc34832e4e5bff09bb8ab4b3244cbba38bc49ec1a01a80ae30a484c8ec85fb8ae7a032131156278f5
-  data.tar.gz: 4e164e2afd778cd2a6c2adb171c0ee6afec71eef925de9b61fe9b8c1b1d94a5faf2bd8fa624f6f691c4b7268d550e2e58dc82ef0c9b40470fe687026a5cef90f
+  metadata.gz: e28726cc8c9670553371ba62a3c2ea4d30a4edb5db413936b91810ab1b592b2b84e6dd0fd3bcac8ad47fa2fb2c1b5d57a6c0443cace95210b9cf203a5e783d43
+  data.tar.gz: ed7628816de37ff4e8f4a27f67520f277abac439cb6183eca0c98ce5a072a1bd8c0413a3db5bda145d75208b4272c598b89514ad80f6692a6cb300c255330b64

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## [0.7.2](https://github.com/dougyouch/client-api-builder/compare/v0.7.1...v0.7.2) (2026-10-03)
+
+
+### Bug Fixes
+
+* **notifications:** report request exceptions to subscribers ([5c29e71](https://github.com/dougyouch/client-api-builder/commit/5c29e71b2ed23016fa68fce3b3aeda3cebdd1e21))
+* **router:** check the base URL used for each request ([e9ea9c8](https://github.com/dougyouch/client-api-builder/commit/e9ea9c808569adf251247a849d6d5727cd3d2772))
+* **router:** clear the previous response before each attempt ([861ae3e](https://github.com/dougyouch/client-api-builder/commit/861ae3e9fd73b45cbb7be33de09b3cf19ffae028))
+* **router:** clear the response block when a route is redefined without one ([cca46c3](https://github.com/dougyouch/client-api-builder/commit/cca46c3e87176d37e953de1ec159b4cb3fd5f4a0))
+* **router:** fill in every placeholder in query and body strings ([beb2d89](https://github.com/dougyouch/client-api-builder/commit/beb2d890f20423b792733919e4fded51fe47c5ee))
+* **router:** only resolve symbols and procs for class-level headers and query params ([bfa29f1](https://github.com/dougyouch/client-api-builder/commit/bfa29f18d28e32eff4268b3dd3343162289140d1))
+* **router:** reject route values that can't be compiled into the generated method ([2a5cdad](https://github.com/dougyouch/client-api-builder/commit/2a5cdad5c338ee8f05b0a3b3739c937f1fa48375))
+* **router:** require a whole verb when detecting the HTTP method ([0bfa860](https://github.com/dougyouch/client-api-builder/commit/0bfa8601a454e8ecf27a496dd894a7a8c67a2351))
+* **router:** stop route from modifying the caller's query and body ([faaee75](https://github.com/dougyouch/client-api-builder/commit/faaee756c81d258516422405ee3ac63fe9227771))
+* **router:** treat a colon after a word as literal path text ([5dae4b0](https://github.com/dougyouch/client-api-builder/commit/5dae4b0bb3e0b850775f62541024d3e441cf87a1))
+* **section:** define section methods with closures instead of generated source ([d9e23a6](https://github.com/dougyouch/client-api-builder/commit/d9e23a6c8bb010ed5a76993fd0ec6014cd0acb18))
+* **stream:** check the response status before streaming the body ([eeb9e3b](https://github.com/dougyouch/client-api-builder/commit/eeb9e3b3895f4571bff147e5f75695e4f7324868))
+* **stream:** reject only parent path segments in file names ([09c355d](https://github.com/dougyouch/client-api-builder/commit/09c355dc3c68dd06e07c8c9dfe003d7daf1153f6))
+
+### Upgrade Notes
+
+* Per-request `headers:` and `query:` values and route arguments are now sent as given. A Symbol there (e.g. `query: { order: :desc }`) is sent as the value `desc` instead of calling a method of that name. Symbols and blocks given to the class-level `header` and `query_param` are still resolved on the client.
+* HTTP method detection now needs the whole verb: route names where the verb runs into the next word (`posts`, `addresses`, `deleted_users`, `updates_feed`, `changelog`) now default to GET instead of POST, PUT or DELETE. Add `method:` to such routes to keep the old method.
+* Redefining a route without a block, in the same class or a subclass, no longer keeps the previous or inherited response block. Pass the block again to keep it.
+* A `:name` directly after a letter, digit, `_` or `}` is now literal path text, so `/v1/items:batchGet` works; a mid-word parameter such as `/items:id` no longer becomes an argument.
+* Route `query:`/`body:` values must be strings, numbers, booleans, `nil`, hashes or arrays. `Range`, `Regexp`, `BigDecimal`, `Complex`, `Time` and other objects now raise an `ArgumentError` naming the route when the class loads; write them as a string or use a `'{method}'` placeholder.
+
 ## [0.7.1](https://github.com/dougyouch/client-api-builder/compare/v0.7.0...v0.7.1) (2026-10-03)
 
 

data/README.md

@@ -119,7 +119,7 @@ Every generated method also accepts options that apply to that call only:
 ```ruby
 client.get_user(
   id: 1,
-  headers: { 'X-Trace-Id' => 'abc' },   # merged over the class headers
+  headers: { 'X-Trace-Id' => 'abc' },   # merged over the class headers; nil removes one
   query: { expand: 'teams' },           # merged over the route's query params
   body: { name: 'Ann' },                # replaces the route's body
   connection_options: { read_timeout: 5 },
@@ -133,7 +133,7 @@ client.get_user(
 
 The Router detects the HTTP method from how the route name starts:
 
-| Name starts with | HTTP Method |
+| Name starts with the word | HTTP Method |
 |------------------|-------------|
 | `post`, `create`, `add`, `insert` | POST |
 | `put`, `update`, `modify`, `change` | PUT |
@@ -141,7 +141,7 @@ The Router detects the HTTP method from how the route name starts:
 | `delete`, `remove`, `destroy` | DELETE |
 | anything else | GET |
 
-The match is on the start of the name only, so `address_lookup` is a POST. Pass `method:` when the name doesn't say it.
+The verb must be the whole name or be followed by `_`: `create_user` and `delete` are detected, while names such as `posts`, `addresses`, `deleted_users` or `updates_feed` are GET. Pass `method:` when the name doesn't say it.
 
 ```ruby
 class MyApiClient
@@ -169,7 +169,9 @@ route :get_user, '/users/:id'
 # client.get_user(id: 1)
 ```
 
-`{name}` is filled from the client's own `name` method rather than an argument, which suits values like account IDs that are set once:
+A colon directly after a letter, digit, `_` or `}` is literal text, so paths like `/v1/items:batchGet`, `/v1/{name}:cancel` or `/slots/12:30` need no escaping. Parameter names start with a letter or `_`.
+
+`{name}` is filled from the client's own `name` method rather than an argument, which suits values like account IDs that are set once. If the route also has an argument called `name`, the argument is used instead (in sections, path values always come from the root client's method):
 
 ```ruby
 attr_accessor :account_id
@@ -178,7 +180,17 @@ route :get_invoices, '/accounts/{account_id}/invoices'
 # client.get_invoices
 ```
 
-The same `'{name}'` form works as a value inside `query:` and `body:`.
+The same `{name}` form works inside `query:` and `body:` strings. A string that is exactly `'{name}'` passes the value through unchanged, so numbers, arrays and hashes keep their type. Placeholders within text are filled in as strings, and every one is used:
+
+```ruby
+route :search_issues, '/issues', query: { q: 'author:{username} state:{state}' }
+route :create_report, '/reports', body: { title: 'Report for {username}', limit: '{page_size}' }
+# q=author:octocat state:open    {"title":"Report for octocat","limit":50}
+```
+
+`query:` and `body:` are compiled into the generated method when the class loads, so their fixed values must be strings, numbers, booleans, `nil`, hashes or arrays. Other objects (`Time`, `Date`, `BigDecimal`, `Range`, ...) raise an `ArgumentError` naming the route; pass them as an argument or a `'{method}'` placeholder, or write them as a string.
+
+Any `{identifier}` in these strings is a placeholder; other text, including quotes and `#{...}`, is sent literally. Top-level String bodies (`body: '...'`) are always sent as is.
 
 Path values, from arguments and `{name}` alike, are percent-encoded so each stays a single segment: `get_file(name: 'a/b c')` requests `/files/a%2Fb%20c`. Only RFC 3986 unreserved characters (`A-Z a-z 0-9 - . _ ~`) are left as is. To change this, override `escape_path`:
 
@@ -232,6 +244,8 @@ class MyApiClient
 end
 ```
 
+A symbol or block given to `header` or `query_param` is evaluated on the client for every request. Values passed when calling a route, including per-request `headers:` and `query:`, are always sent as given, so `client.list_items(sort: :asc)` sends `sort=asc`. Header values are sent as strings; setting one to `nil` for a request leaves it out.
+
 ### Request Body Formats
 
 Configure how request bodies are serialized:
@@ -308,7 +322,7 @@ user = client.users.get(id: 123)
 posts = client.posts.list
 ```
 
-A section is its own router class. It uses the parent's `base_url` unless it sets one, but headers, query params, connection options, retries and builders are not inherited, so declare the ones it needs inside the section. Symbol and block values, `{name}` path values, and response blocks are evaluated on the root client, so they can use its methods and state.
+A section is its own router class. It uses the parent's `base_url` unless it sets one, but headers, query params, connection options, retries and builders are not inherited, so declare the ones it needs inside the section. Symbol and block values given to `header` and `query_param`, `{name}` path values, and response blocks are evaluated on the root client, so they can use its methods and state.
 
 ### Connection Options
 
@@ -412,6 +426,8 @@ end
 
 Streaming routes return the `Net::HTTPResponse`. Files are written in `wb` mode by default; pass `connection_options: { file_mode: 'ab' }` to append.
 
+The status is checked against the route's expected response codes before any of the body is streamed. An error response raises `UnexpectedResponse` with the error body in `e.response.body`, and nothing is written to the file, IO or block; an existing file is left untouched.
+
 ### Response Handling
 
 Customize how responses are processed:
@@ -444,6 +460,8 @@ client.get_user(id: 1) { |data| data['name'] }
 
 Blocks run on the client, so they can call its methods and set its state. Empty response bodies return `nil`.
 
+Redefining a route, in the same class or a subclass, replaces the whole definition including its block; without a block it goes back to the default handling. Pass the block again to keep it.
+
 ### Error Handling
 
 `ClientApiBuilder::UnexpectedResponse` is raised when the status code isn't expected (any non-2xx by default, or anything outside `expected_response_code(s)`) and when a response body isn't valid JSON. It carries the response:
@@ -482,6 +500,8 @@ puts client.total_request_time   # Time in seconds
 puts client.request_attempts     # Number of attempts (including retries)
 ```
 
+These describe the latest attempt. If it failed, `response` is `nil` when no response arrived, and `request_options` is `nil` when the request couldn't be built.
+
 ### ActiveSupport Integration
 
 When ActiveSupport is loaded before your client class includes `ClientApiBuilder::Router`, every request is instrumented as a `client_api_builder.request` event:
@@ -492,9 +512,10 @@ ActiveSupport::Notifications.subscribe('client_api_builder.request') do |*args|
   event = ActiveSupport::Notifications::Event.new(*args)
   client = event.payload[:client]
 
-  puts "#{client.request_options[:method]} #{client.request_options[:uri]}"
+  puts "#{client.request_options&.dig(:method)} #{client.request_options&.dig(:uri)}"
   puts "Status: #{client.response&.code}"
   puts "Duration: #{event.duration.round(2)}ms"
+  puts "Failed: #{event.payload[:exception_object].inspect}" if event.payload[:exception]
 end
 
 # Or use the built-in log subscriber
@@ -502,6 +523,13 @@ subscriber = ClientApiBuilder::ActiveSupportLogSubscriber.new(Rails.logger)
 subscriber.subscribe!
 ```
 
+An event fires for every attempt, including failed ones. When an attempt raises, the payload also holds `:exception` (`[class name, message]`) and `:exception_object`, following the usual ActiveSupport convention, and `request_options` or `response` may be `nil`. The built-in subscriber logs lines like:
+
+```
+GET https://api.example.com/users/123[200] took 45ms
+GET https://api.example.com/users/123[UNKNOWN] took 5003ms (Net::ReadTimeout: Net::ReadTimeout)
+```
+
 Separately, `ClientApiBuilder.logger` receives every exception raised during a request attempt, including ones that are retried:
 
 ```ruby
@@ -540,7 +568,7 @@ HTTPS connections verify SSL certificates using `OpenSSL::SSL::VERIFY_PEER` and
 
 ### SSRF Protection
 
-Base URLs are validated to only allow `http` and `https` schemes, preventing Server-Side Request Forgery attacks:
+Base URLs must use the `http` or `https` scheme and include a host, preventing Server-Side Request Forgery attacks:
 
 ```ruby
 class MyApiClient
@@ -553,20 +581,27 @@ class MyApiClient
 end
 ```
 
+The URL actually used is checked again on every request, so a `base_url` method defined on the client (for example, a per-tenant URL) gets the same check. A client with no base URL at all raises `ArgumentError: no base_url configured for MyApiClient` instead of failing inside Net::HTTP.
+
 ### Path Value Encoding
 
 Values inserted into a route's path are percent-encoded, so input such as `../admin` or `a/b?x=1` can't add path segments or a query string to the request.
 
 ### Path Traversal Protection
 
-File streaming rejects any path containing `..` or a null byte:
+File streaming rejects a path with a `..` segment or a null byte, so a file name built from untrusted input can't climb out of the directory you put it in:
 
 ```ruby
-# These will raise ArgumentError
-client.download_file(id: 1, file: '/tmp/../etc/passwd')
+# These raise ArgumentError
+client.download_file(id: 1, file: "/downloads/#{'../etc/passwd'}")
 client.download_file(id: 1, file: "/tmp/file\0.txt")
+
+# Names that only contain dots are fine
+client.download_file(id: 1, file: '/downloads/report..v2.csv')
 ```
 
+Absolute paths and symlinks are not restricted, since only your code knows where files may go. If untrusted input can supply the whole path, validate it before passing it as `file:`.
+
 ### Safe File Modes
 
 Only safe file modes are allowed for streaming to files: `w`, `wb`, `a`, `ab`, `w+`, `wb+`, `a+`, `ab+`.

data/lib/client-api-builder.rb

@@ -22,6 +22,7 @@ module ClientApiBuilder
   autoload :ActiveSupportLogSubscriber, 'client_api_builder/active_support_log_subscriber'
   autoload :NestedRouter, 'client_api_builder/nested_router'
   autoload :QueryParams, 'client_api_builder/query_params'
+  autoload :RouteValueValidator, 'client_api_builder/route_value_validator'
   autoload :Router, 'client_api_builder/router'
   autoload :Section, 'client_api_builder/section'
 

data/lib/client_api_builder/active_support_log_subscriber.rb

@@ -17,14 +17,27 @@ module ClientApiBuilder
       end
     end
 
+    # request_options is nil when the request failed before it was built,
+    # and response is nil when no response was received.
+    # Failed requests end with the exception, e.g. "(Net::OpenTimeout: execution expired)".
     def generate_log_message(event)
       client = event.payload[:client]
-      method = client.request_options[:method].to_s.upcase
-      uri = client.request_options[:uri]
-      response = client.response
-      response_code = response ? response.code : 'UNKNOWN'
+      request_options = client.request_options
+      response_code = client.response ? client.response.code : 'UNKNOWN'
 
-      "#{method} #{uri.scheme}://#{uri.host}#{uri.path}[#{response_code}] took #{event.duration.to_i}ms"
+      message = "#{request_description(request_options)}[#{response_code}] took #{event.duration.to_i}ms"
+      exception = event.payload[:exception]
+      exception ? "#{message} (#{exception.join(': ')})" : message
+    end
+
+    private
+
+    def request_description(request_options)
+      return '[request not built]' unless request_options
+
+      method = request_options[:method].to_s.upcase
+      uri = request_options[:uri]
+      uri ? "#{method} #{uri.scheme}://#{uri.host}#{uri.path}" : "#{method} [no URI]"
     end
   end
 end

data/lib/client_api_builder/active_support_notifications.rb

@@ -5,21 +5,11 @@ require 'active_support'
 # Purpose is to change the instrument_request to use ActiveSupport::Notifications.instrument
 module ClientApiBuilder
   module ActiveSupportNotifications
-    def instrument_request
+    # When the request raises, ActiveSupport adds :exception and :exception_object to the
+    # event payload, notifies subscribers, and re-raises the original exception.
+    def instrument_request(&)
       start_time = Time.now
-      error = nil
-      result = nil
-      ActiveSupport::Notifications.instrument('client_api_builder.request', client: self) do
-        result = yield
-      rescue StandardError => e
-        # Use StandardError instead of Exception to allow SystemExit, Interrupt, etc. to propagate
-        error = e
-      end
-
-      # Re-raise with original backtrace preserved
-      raise(error, error.message, error.backtrace) if error
-
-      result
+      ActiveSupport::Notifications.instrument('client_api_builder.request', client: self, &)
     ensure
       @total_request_time = Time.now - start_time
     end

data/lib/client_api_builder/net_http_request.rb

@@ -50,46 +50,78 @@ module ClientApiBuilder
         end
       end
 
-      def stream(method:, uri:, body:, headers:, connection_options:)
+      # validate_response, when given, is called with the response before its body is streamed
+      # and raises to reject it. A rejected body is read into response.body instead of being
+      # streamed, so the error can still show it.
+      def stream(method:, uri:, body:, headers:, connection_options:, validate_response: nil)
         request(method: method, uri: uri, body: body, headers: headers,
                 connection_options: connection_options) do |response|
+          validate_streamed_response(response, validate_response) if validate_response
           response.read_body do |chunk|
             yield response, chunk
           end
         end
       end
 
-      def stream_to_io(method:, uri:, body:, headers:, connection_options:, io:)
+      def stream_to_io(method:, uri:, body:, headers:, connection_options:, io:, validate_response: nil)
         stream(method: method, uri: uri, body: body, headers: headers,
-               connection_options: connection_options) do |_, chunk|
+               connection_options: connection_options, validate_response: validate_response) do |_, chunk|
           io.write chunk
         end
       end
 
-      def stream_to_file(method:, uri:, body:, headers:, connection_options:, file:)
+      # The file is opened only once the response has passed validate_response, so a rejected
+      # response never creates, truncates or appends to it.
+      def stream_to_file(method:, uri:, body:, headers:, connection_options:, file:, validate_response: nil)
         # Use dup to avoid mutating the original hash
         opts = connection_options.dup
-        mode = opts.delete(:file_mode)
-
-        # Validate file mode - use whitelist approach
-        mode = if mode.nil?
-                 'wb'
-               elsif ALLOWED_FILE_MODES.include?(mode.to_s)
-                 mode.to_s
-               else
-                 raise ArgumentError,
-                       "Invalid file mode: #{mode.inspect}. Allowed modes: #{ALLOWED_FILE_MODES.join(', ')}"
-               end
-
-        # Validate file path - expand to absolute path and check for path traversal
-        expanded_path = File.expand_path(file)
-        if file.to_s.include?('..') || expanded_path.include?("\0")
-          raise ArgumentError, 'Invalid file path: potential path traversal detected'
-        end
+        mode = stream_file_mode(opts.delete(:file_mode))
+        path = stream_file_path(file)
 
-        File.open(expanded_path, mode) do |io|
-          stream_to_io(method: method, uri: uri, body: body, headers: headers, connection_options: opts, io: io)
+        io = nil
+        open_file = lambda do |response|
+          validate_response&.call(response)
+          io = File.open(path, mode) # rubocop:disable Style/FileOpen -- closed in ensure
+        end
+        stream(method: method, uri: uri, body: body, headers: headers,
+               connection_options: opts, validate_response: open_file) do |_, chunk|
+          io.write chunk
         end
+      ensure
+        io&.close
+      end
+
+      private
+
+      def validate_streamed_response(response, validate_response)
+        validate_response.call(response)
+      rescue StandardError
+        response.read_body
+        raise
+      end
+
+      # Validate file mode - use whitelist approach
+      def stream_file_mode(mode)
+        return 'wb' if mode.nil?
+        return mode.to_s if ALLOWED_FILE_MODES.include?(mode.to_s)
+
+        raise ArgumentError, "Invalid file mode: #{mode.inspect}. Allowed modes: #{ALLOWED_FILE_MODES.join(', ')}"
+      end
+
+      # Rejects null bytes and any '..' path segment, so a name built from untrusted input
+      # can't climb out of the directory the caller put it in. Names merely containing '..'
+      # (report..v2.csv) are fine. Absolute paths are allowed: the caller decides where files go.
+      def stream_file_path(file)
+        path = file.to_s
+        raise ArgumentError, 'Invalid file path: contains a null byte' if path.include?("\0")
+        raise ArgumentError, 'Invalid file path: potential path traversal detected' if parent_segment?(path)
+
+        File.expand_path(path)
+      end
+
+      # Splits on both separators so the rule is the same on every platform
+      def parent_segment?(path)
+        path.split(%r{[/\\]}).include?('..')
       end
     end
   end

data/lib/client_api_builder/route_value_validator.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module ClientApiBuilder
+  # A route's query: and body: values are compiled into the source of the generated method,
+  # so only values that value_to_code can write back as equal Ruby literals are allowed.
+  # Anything computed per request belongs in a symbol argument or a '{method}' placeholder.
+  module RouteValueValidator
+    LITERAL_CLASSES = [String, Integer, TrueClass, FalseClass, NilClass].freeze
+    ARGUMENT_NAME = /\A[a-z_][a-z0-9_]*\z/i
+
+    module_function
+
+    # Raises ArgumentError naming the route for the first value that can't be compiled
+    def validate!(route_name, location, value)
+      case value
+      when Hash
+        value.each do |key, item|
+          validate_key!(route_name, location, key)
+          validate!(route_name, location, item)
+        end
+      when Array
+        value.each { |item| validate!(route_name, location, item) }
+      when Symbol
+        validate_argument_name!(route_name, location, value)
+      else
+        raise ArgumentError, unsupported_value_message(route_name, location, value) unless literal?(value)
+      end
+    end
+
+    def validate_key!(route_name, location, key)
+      return if key.is_a?(Symbol) || literal?(key)
+
+      raise ArgumentError, unsupported_value_message(route_name, location, key)
+    end
+
+    # Symbol values become keyword arguments of the generated method
+    def validate_argument_name!(route_name, location, name)
+      return if name.to_s.match?(ARGUMENT_NAME)
+
+      raise ArgumentError,
+            "route #{route_name.inspect}: #{location} argument #{name.inspect} is not a valid argument name"
+    end
+
+    def literal?(value)
+      LITERAL_CLASSES.any? { |klass| value.is_a?(klass) } || (value.is_a?(Float) && value.finite?)
+    end
+
+    def unsupported_value_message(route_name, location, value)
+      "route #{route_name.inspect}: #{location} value #{value.inspect} (#{value.class}) can't be written into " \
+        "the generated method; use a String, number, boolean, nil, Hash or Array, or a '{method}' placeholder " \
+        'to compute it per request'
+    end
+  end
+end

data/lib/client_api_builder/router.rb

@@ -25,17 +25,31 @@ module ClientApiBuilder
       # 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
+      # Ruby source that value_to_code inserts verbatim into a generated route method
+      CodeSnippet = Data.define(:code)
+
+      # '{name}' in a query/body string: a route argument with that name, or else the client's method
+      PLACEHOLDER = /\{([a-z0-9_]+)\}/i
+      WHOLE_PLACEHOLDER = /\A\{([a-z0-9_]+)\}\z/i
+
+      # ':name' in a route path is an argument unless the colon follows a letter, digit, '_' or '}',
+      # so items:batchGet, {name}:cancel and 12:30 stay literal
+      PATH_PARAMETER = /(?<![a-z0-9_}]):([a-z_][a-z0-9_]*)/i
+
+      # Deep duplicates hashes and arrays (at any depth) to prevent shared mutable state.
+      # Other values are returned as is.
+      def deep_dup(value)
+        case value
+        when Hash then value.transform_values { |v| deep_dup(v) }
+        when Array then value.map { |v| deep_dup(v) }
+        else value
         end
       end
 
+      def deep_dup_hash(hash)
+        deep_dup(hash)
+      end
+
       def default_options
         {
           base_url: nil,
@@ -50,7 +64,7 @@ module ClientApiBuilder
         }.freeze
       end
 
-      # tracks the proc used to handle responses
+      # tracks the proc used to handle responses; nil clears it
       def add_response_proc(method_name, proc)
         response_procs = deep_dup_hash(default_options[:response_procs])
         response_procs[method_name] = proc
@@ -74,10 +88,11 @@ module ClientApiBuilder
       # 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)
-
-        allowed = ALLOWED_URL_SCHEMES.join(', ')
-        raise ArgumentError, "Invalid base_url scheme: #{uri.scheme.inspect}. Allowed: #{allowed}"
+        unless ALLOWED_URL_SCHEMES.include?(uri.scheme&.downcase)
+          allowed = ALLOWED_URL_SCHEMES.join(', ')
+          raise ArgumentError, "Invalid base_url scheme: #{uri.scheme.inspect}. Allowed: #{allowed}"
+        end
+        raise ArgumentError, "Invalid base_url: #{url.to_s.inspect} has no host" if uri.host.to_s.empty?
       rescue URI::InvalidURIError => e
         raise ArgumentError, "Invalid base_url: #{e.message}"
       end
@@ -170,15 +185,17 @@ module ClientApiBuilder
         end
       end
 
+      # The verb must be the whole name or be followed by '_', so create_user is a POST
+      # but names such as posts or deleted_users stay GET.
       def auto_detect_http_method(method_name)
         case method_name.to_s
-        when /^(?:post|create|add|insert)/i
+        when /\A(?:post|create|add|insert)(?:_|\z)/i
           :post
-        when /^(?:put|update|modify|change)/i
+        when /\A(?:put|update|modify|change)(?:_|\z)/i
           :put
-        when /^(?:patch)/i
+        when /\Apatch(?:_|\z)/i
           :patch
-        when /^(?:delete|remove|destroy)/i
+        when /\A(?:delete|remove|destroy)(?:_|\z)/i
           :delete
         else
           :get
@@ -192,48 +209,56 @@ module ClientApiBuilder
         REQUIRED_BODY_HTTP_METHODS.include?(http_method)
       end
 
+      # Replaces argument symbols and '{name}' strings in a query/body hash, in place, with
+      # CodeSnippets; returns the argument names found
       def get_hash_arguments(hsh)
         arguments = []
-        hsh.each do |k, v|
-          case v
-          when Symbol
-            hsh[k] = "__||#{v}||__"
-            arguments << v
-          when Hash
-            arguments += get_hash_arguments(v)
-          when Array
-            arguments += get_array_arguments(v)
-          when String
-            # 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
+        hsh.each { |key, value| hsh[key] = argument_code(value, arguments) }
         arguments
       end
 
+      # Same as get_hash_arguments, for an array
       def get_array_arguments(list)
         arguments = []
-        list.each_with_index do |v, idx|
-          case v
-          when Symbol
-            list[idx] = "__||#{v}||__"
-            arguments << v
-          when Hash
-            arguments += get_hash_arguments(v)
-          when Array
-            arguments += get_array_arguments(v)
-          when String
-            # 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
+        list.each_with_index { |value, idx| list[idx] = argument_code(value, arguments) }
         arguments
       end
 
+      def argument_code(value, arguments)
+        case value
+        when Symbol
+          arguments << value
+          CodeSnippet.new(value.to_s)
+        when Hash
+          arguments.concat(get_hash_arguments(value))
+          value
+        when Array
+          arguments.concat(get_array_arguments(value))
+          value
+        when String
+          string_template_code(value)
+        else
+          value
+        end
+      end
+
+      # A string that is exactly '{name}' passes the value through unchanged (keeping its type);
+      # placeholders within text are interpolated into the string. Strings without placeholders
+      # are returned as is.
+      def string_template_code(str)
+        return str unless str.match?(PLACEHOLDER)
+
+        whole = str.match(WHOLE_PLACEHOLDER)
+        return CodeSnippet.new(whole[1]) if whole
+
+        parts = str.split(/(\{[a-z0-9_]+\})/i).map do |part|
+          placeholder = part.match(WHOLE_PLACEHOLDER)
+          # inspect escapes quotes, backslashes and '#{' so the text stays literal
+          placeholder ? "\#{#{placeholder[1]}}" : part.inspect[1..-2]
+        end
+        CodeSnippet.new("\"#{parts.join}\"")
+      end
+
       # returns a list of arguments to add to the route method
       def get_arguments(value)
         case value
@@ -275,7 +300,7 @@ module ClientApiBuilder
         end
 
         path_arguments = []
-        path = path.gsub(/:([a-z0-9_]+)/i) do |_match|
+        path = path.gsub(PATH_PARAMETER) do |_match|
           param_name = Regexp.last_match(1)
           path_arguments << param_name
           "#\{escape_path(#{param_name})}"
@@ -293,7 +318,7 @@ module ClientApiBuilder
 
           pairs = value.map do |k, v|
             key_code = case k
-                       when Symbol then "#{k}: "
+                       when Symbol then k.match?(RouteValueValidator::ARGUMENT_NAME) ? "#{k}: " : "#{k.inspect} => "
                        when String then "#{k.inspect} => "
                        else "#{value_to_code(k)} => "
                        end
@@ -306,17 +331,19 @@ module ClientApiBuilder
           'nil'
         when TrueClass, FalseClass
           value.to_s
+        when CodeSnippet
+          value.code
         else
           value.inspect
         end
       end
 
+      # get_arguments rewrites values in place, so work on a copy of the caller's query/body
       def build_query_code(options)
         if options[:query]
-          query_arguments = get_arguments(options[:query])
-          str = value_to_code(options[:query])
-          str = str.gsub(/"__\|\|(.+?)\|\|__"/) { Regexp.last_match(1) }
-          [str, query_arguments.map(&:to_s)]
+          query = deep_dup(options[:query])
+          query_arguments = get_arguments(query)
+          [value_to_code(query), query_arguments.map(&:to_s)]
         else
           ['nil', []]
         end
@@ -324,10 +351,9 @@ module ClientApiBuilder
 
       def build_body_code(options, has_body_param)
         if options[:body]
-          body_arguments = get_arguments(options[:body])
-          str = value_to_code(options[:body])
-          str = str.gsub(/"__\|\|(.+?)\|\|__"/) { Regexp.last_match(1) }
-          [str, body_arguments.map(&:to_s), false]
+          body = deep_dup(options[:body])
+          body_arguments = get_arguments(body)
+          [value_to_code(body), body_arguments.map(&:to_s), false]
         else
           [has_body_param ? 'body' : 'nil', [], has_body_param]
         end
@@ -352,18 +378,26 @@ module ClientApiBuilder
         args + ['**__options__', '&block']
       end
 
-      def generate_request_call_code(options, stream_param)
+      def generate_request_call_code(options, stream_param, expected_response_codes)
         code = "  @request_options[:#{stream_param}] = #{stream_param}\n" if stream_param
         code ||= ''
+        validator = stream_validator_code(expected_response_codes)
 
         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"
+               when true, :file then "  @response = stream_to_file(**@request_options, #{validator})\n"
+               when :io then "  @response = stream_to_io(**@request_options, #{validator})\n"
+               when :block then "  @response = stream(**@request_options, #{validator}, &block)\n"
                else "  @response = request(**@request_options)\n"
                end
       end
 
+      # Streaming routes check the status before the body is streamed, using the same
+      # expected_response_code! as other routes, so error bodies never reach the file, IO or block
+      def stream_validator_code(expected_response_codes)
+        'validate_response: ->(response) { ' \
+          "expected_response_code!(response, #{expected_response_codes.inspect}, __options__) }"
+      end
+
       def generate_response_handling_code(options)
         if options[:stream] || options[:return] == :response
           "    @response\n"
@@ -380,6 +414,9 @@ module ClientApiBuilder
           raise ArgumentError, "Invalid method name: #{method_name.inspect}"
         end
 
+        RouteValueValidator.validate!(method_name, :query, options[:query])
+        RouteValueValidator.validate!(method_name, :body, options[:body])
+
         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)
@@ -413,7 +450,7 @@ module ClientApiBuilder
         code += "  __connection_options__ = build_connection_options(__options__)\n"
         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 += generate_request_call_code(ctx[:options], ctx[:stream_param], ctx[:expected_response_codes])
         "#{code}end\n\n"
       end
 
@@ -431,8 +468,10 @@ module ClientApiBuilder
         "#{code}end\n"
       end
 
+      # A route definition is complete: redefining a route without a block also clears the
+      # previous block, including one inherited from a parent class
       def route(method_name, path, options = {}, &block)
-        add_response_proc(method_name, block) if block
+        add_response_proc(method_name, block)
 
         class_eval generate_route_code(method_name, path, options), __FILE__, __LINE__
       end
@@ -442,24 +481,12 @@ module ClientApiBuilder
       self.class.base_url
     end
 
+    # Class-level headers may be method names or blocks; per-request headers are used as given.
+    # Values are converted to strings, as Net::HTTP requires; nil values are left out of the request.
     def build_headers(options)
-      headers = {}
-
-      add_header_proc = proc do |name, value|
-        headers[name] =
-          if value.is_a?(Proc)
-            root_router.instance_eval(&value)
-          elsif value.is_a?(Symbol)
-            root_router.send(value)
-          else
-            value
-          end
-      end
-
-      self.class.default_headers.each(&add_header_proc)
-      options[:headers]&.each(&add_header_proc)
-
-      headers
+      headers = self.class.default_headers.transform_values { |value| resolve_config_value(value) }
+      headers.merge!(options[:headers]) if options[:headers]
+      headers.transform_values { |value| value&.to_s }
     end
 
     def build_connection_options(options)
@@ -470,27 +497,26 @@ module ClientApiBuilder
       end
     end
 
+    # Class-level query params may be method names or blocks; values from route arguments
+    # and per-request options are sent as given.
     def build_query(query, options)
-      query_params = {}
-
-      add_query_param_proc = proc do |name, value|
-        query_params[name] =
-          if value.is_a?(Proc)
-            root_router.instance_eval(&value)
-          elsif value.is_a?(Symbol)
-            root_router.send(value)
-          else
-            value
-          end
-      end
-
-      self.class.default_query_params.each(&add_query_param_proc)
-      query&.each(&add_query_param_proc)
-      options[:query]&.each(&add_query_param_proc)
+      query_params = self.class.default_query_params.transform_values { |value| resolve_config_value(value) }
+      query_params.merge!(query) if query
+      query_params.merge!(options[:query]) if options[:query]
 
       query_params.empty? ? nil : self.class.build_query(self, query_params)
     end
 
+    # Resolves a class-level header or query_param value: a Symbol calls that method and a
+    # Proc is evaluated, both on the root router; anything else is used as is.
+    def resolve_config_value(value)
+      case value
+      when Proc then root_router.instance_eval(&value)
+      when Symbol then root_router.send(value)
+      else value
+      end
+    end
+
     def build_body(body, options)
       body = options[:body] if options.key?(:body)
 
@@ -502,8 +528,7 @@ module ClientApiBuilder
 
     def build_uri(path, query, options)
       # Properly join base_url and path to handle missing/extra slashes
-      base = base_url.to_s
-      base = base.chomp('/') if base.end_with?('/')
+      base = validated_base_url.chomp('/')
       path = path.to_s
       path = "/#{path}" unless path.start_with?('/')
 
@@ -512,6 +537,19 @@ module ClientApiBuilder
       uri
     end
 
+    # The base URL used for this request, checked every time so a base_url method defined on
+    # the client gets the same scheme and host check as the class-level base_url
+    def validated_base_url
+      url = base_url.to_s
+      if url.empty?
+        raise ArgumentError, "no base_url configured for #{self.class.name || self.class.inspect}; set one with " \
+                             "base_url 'https://api.example.com' or define a base_url method"
+      end
+
+      self.class.validate_base_url!(url)
+      url
+    end
+
     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)
@@ -594,6 +632,9 @@ module ClientApiBuilder
 
     def request_wrapper(options, &block)
       retry_request(options) do
+        # Clear the previous attempt's state so a failed attempt never reports an earlier response
+        @request_options = nil
+        @response = nil
         instrument_request(&block)
       end
     end

data/lib/client_api_builder/section.rb

@@ -8,7 +8,13 @@ module ClientApiBuilder
     end
 
     module ClassMethods
+      SECTION_NAME = /\A[a-z_][a-z0-9_]*\z/i
+
+      # Defines <name>_router (the section's NestedRouter class) and <name> (its router for a
+      # client instance) with closures, so anonymous client classes and any option values work.
       def section(name, nested_router_options = {}, &)
+        raise ArgumentError, "Invalid section name: #{name.inspect}" unless name.to_s.match?(SECTION_NAME)
+
         kls = InheritanceHelper::ClassBuilder::Utils.create_class(
           self,
           name,
@@ -18,16 +24,22 @@ module ClientApiBuilder
           &
         )
 
-        code = <<~CODE
-          def self.#{name}_router
-            #{kls.name}
-          end
+        define_singleton_method(:"#{name}_router") { kls }
+        define_section_accessor(name, nested_router_options)
+      end
+
+      private
+
+      # Memoized per client instance; each instance gets its own copy of the options
+      def define_section_accessor(name, nested_router_options)
+        router_method = :"#{name}_router"
+        ivar = :"@#{name}"
 
-          def #{name}
-            @#{name} ||= self.class.#{name}_router.new(self.root_router, #{nested_router_options.inspect})
-          end
-        CODE
-        class_eval code, __FILE__, __LINE__
+        define_method(name) do
+          instance_variable_get(ivar) ||
+            instance_variable_set(ivar, self.class.public_send(router_method)
+                                              .new(root_router, nested_router_options.dup))
+        end
       end
     end
   end

data/lib/client_api_builder/version.rb

@@ -2,5 +2,5 @@
 
 module ClientApiBuilder
   # Gem version, bumped by release-please
-  VERSION = '0.7.1'
+  VERSION = '0.7.2'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: client-api-builder
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.7.2
 platform: ruby
 authors:
 - Doug Youch
@@ -43,6 +43,7 @@ files:
 - lib/client_api_builder/nested_router.rb
 - lib/client_api_builder/net_http_request.rb
 - lib/client_api_builder/query_params.rb
+- lib/client_api_builder/route_value_validator.rb
 - lib/client_api_builder/router.rb
 - lib/client_api_builder/section.rb
 - lib/client_api_builder/version.rb