client-api-builder 0.7.0 → 0.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ee8b61c4583f46d39c0d502192fb713f502ece28b7ea98092b73572efc9ffd4
-  data.tar.gz: bc80ea2afb78cdacc5067ebb45005a4bbcc997d13e79e9c6a9cf6b7edc8d5696
+  metadata.gz: aac435317feb174db101e201b00464222bfc2df0f10601ac88e7897c3694be27
+  data.tar.gz: '08ad14efc0bff6c1f6e7fd4864e26c6f41853d72808fdc84b0e4781a0cfd229f'
 SHA512:
-  metadata.gz: 4fd43d2172214d83d6b235096bd17f6289a07243dae96f3911b66c783d11caf1695ee541c2a0d2b547acf305616819c749bb32168ca62b5fa98880b042050925
-  data.tar.gz: e2d29d72f3c076be3b24d0941f317745ce367342cc96157f7c8d2a8592bc2dea0a733da1f4d9d5d40f46e1bf2859a01023ebb57c9ca31be4efca07e18267751e
+  metadata.gz: e28726cc8c9670553371ba62a3c2ea4d30a4edb5db413936b91810ab1b592b2b84e6dd0fd3bcac8ad47fa2fb2c1b5d57a6c0443cace95210b9cf203a5e783d43
+  data.tar.gz: ed7628816de37ff4e8f4a27f67520f277abac439cb6183eca0c98ce5a072a1bd8c0413a3db5bda145d75208b4272c598b89514ad80f6692a6cb300c255330b64

data/CHANGELOG.md

@@ -1,10 +1,59 @@
 # 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)
+
+
+### Bug Fixes
+
+* **router:** detect destroy_ routes as DELETE ([85604c4](https://github.com/dougyouch/client-api-builder/commit/85604c4d974c8483e292e700eb51a2c78e312b54))
+* **router:** url-encode path values ([76d6fb4](https://github.com/dougyouch/client-api-builder/commit/76d6fb4fa246b342e263322d06262cba6760c278))
+
+### Upgrade Notes
+
+* Path values are now percent-encoded by `escape_path`, including `/`. A value like `'a/b'` that previously expanded into two path segments is now sent as one segment (`a%2Fb`). To keep `/` as a separator, override `escape_path` in your client, e.g. `value.to_s.split('/').map { |part| ERB::Util.url_encode(part) }.join('/')`.
+
 ## [0.7.0](https://github.com/dougyouch/client-api-builder/compare/v0.6.1...v0.7.0) (2026-10-03)
 
 
-### Build System
+### ⚠ BREAKING CHANGES
+
+* client-api-builder now requires Ruby 3.2 or newer (previously 3.0). Ruby 3.0 and 3.1 are end-of-life. ([7c951e0](https://github.com/dougyouch/client-api-builder/commit/7c951e0))
+
+### Packaging
+
+* ship only `lib/`, `README.md`, `LICENSE` and `CHANGELOG.md` in the gem instead of every tracked file ([ca141a1](https://github.com/dougyouch/client-api-builder/commit/ca141a1))
+* refresh the gem summary and description ([ca141a1](https://github.com/dougyouch/client-api-builder/commit/ca141a1))
+* add `ClientApiBuilder::VERSION` ([7c951e0](https://github.com/dougyouch/client-api-builder/commit/7c951e0))
 
-* **release:** release 0.7.0 ([fff1354](https://github.com/dougyouch/client-api-builder/commit/fff13543d5d8189e2bb7a84eda7e8ca3181f3469))
+### Build
 
-## Changelog
+* automate versioning, changelog and RubyGems publishing with release-please ([7c951e0](https://github.com/dougyouch/client-api-builder/commit/7c951e0))
+* replace Codecov with a GitHub-hosted coverage badge ([7c951e0](https://github.com/dougyouch/client-api-builder/commit/7c951e0))
+* adopt the dynamic-active-model RuboCop config with rubocop-rspec ([f36ed6f](https://github.com/dougyouch/client-api-builder/commit/f36ed6f))

data/README.md

@@ -1,8 +1,9 @@
 # Client API Builder
 
-[![Gem Version](https://badge.fury.io/rb/client-api-builder.svg)](https://badge.fury.io/rb/client-api-builder)
+[![Gem Version](https://img.shields.io/gem/v/client-api-builder)](https://rubygems.org/gems/client-api-builder)
 [![CI](https://github.com/dougyouch/client-api-builder/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/dougyouch/client-api-builder/actions/workflows/ci.yml)
 [![Coverage](https://raw.githubusercontent.com/dougyouch/client-api-builder/badges/coverage.svg)](https://github.com/dougyouch/client-api-builder/actions/workflows/ci.yml)
+[![Branch Coverage](https://raw.githubusercontent.com/dougyouch/client-api-builder/badges/branches.svg)](https://github.com/dougyouch/client-api-builder/actions/workflows/ci.yml)
 
 A Ruby gem for building robust, secure API clients through declarative configuration. Define your API endpoints and their behavior with minimal boilerplate while benefiting from built-in security features, automatic retries, and comprehensive error handling.
 
@@ -93,25 +94,54 @@ route :method_name, '/path/:param', options
 
 | Option | Description |
 |--------|-------------|
-| `method:` | HTTP method (`:get`, `:post`, `:put`, `:patch`, `:delete`). Auto-detected if omitted. |
+| `method:` | HTTP method. Auto-detected from the route name if omitted. Any of `:get`, `:post`, `:put`, `:patch`, `:delete`, `:head`, `:options`, `:trace`, `:copy`, `:lock`, `:unlock`, `:mkcol`, `:move`, `:propfind`, `:proppatch`. |
 | `query:` | Hash defining query parameters. Use symbols for dynamic values. |
-| `body:` | Hash defining request body. Use symbols for dynamic values. |
-| `expected_response_code:` | Single expected HTTP status code |
+| `body:` | Request body: a Hash or Array (symbols become arguments) or a literal String. |
+| `no_body:` | `true` to send no body, even for POST/PUT/PATCH. |
+| `has_body:` | `true` to add a `body:` argument to any method, e.g. a GET with a body. |
+| `expected_response_code:` | Single expected HTTP status code. Without one, any 2xx response is accepted. |
 | `expected_response_codes:` | Array of expected HTTP status codes |
 | `stream:` | Enable streaming (`:file`, `:io`, `:block`, or `true`) |
 | `return:` | Return type (`:response`, `:body`, or parsed JSON by default) |
 
+POST, PUT and PATCH routes without a `body:` option take the request body as a `body:` argument:
+
+```ruby
+route :create_user, '/users'
+
+client.create_user(body: { name: 'Ann' })
+```
+
+### Per-Request Options
+
+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; 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 },
+  retries: 3,                           # attempts for this call
+  sleep: 0.5,                           # seconds between attempts
+  return: :body                         # :body or :response instead of parsed JSON
+)
+```
+
 ### Automatic HTTP Method Detection
 
-The Router automatically detects HTTP methods based on route names:
+The Router detects the HTTP method from how the route name starts:
 
-| Prefix | HTTP Method |
-|--------|-------------|
-| `get_`, `find_`, `fetch_`, `list_`, `search_` | GET |
-| `post_`, `create_`, `add_`, `insert_` | POST |
-| `put_`, `update_`, `modify_`, `change_` | PUT |
-| `patch_` | PATCH |
-| `delete_`, `remove_`, `destroy_` | DELETE |
+| Name starts with the word | HTTP Method |
+|------------------|-------------|
+| `post`, `create`, `add`, `insert` | POST |
+| `put`, `update`, `modify`, `change` | PUT |
+| `patch` | PATCH |
+| `delete`, `remove`, `destroy` | DELETE |
+| anything else | GET |
+
+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
@@ -132,11 +162,43 @@ end
 
 Parameters can be defined in three ways:
 
-**1. Path Parameters** (using `:param` or `{param}` syntax):
+**1. Path Parameters** (using `:param` syntax):
 
 ```ruby
 route :get_user, '/users/:id'
-route :get_post, '/users/{user_id}/posts/{post_id}'
+# client.get_user(id: 1)
+```
+
+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
+
+route :get_invoices, '/accounts/{account_id}/invoices'
+# client.get_invoices
+```
+
+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`:
+
+```ruby
+# Allow '/' in values, e.g. for nested object keys
+def escape_path(value)
+  value.to_s.split('/').map { |part| ERB::Util.url_encode(part) }.join('/')
+end
 ```
 
 **2. Query Parameters:**
@@ -182,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:
@@ -193,7 +257,7 @@ class MyApiClient
   # Default: JSON (using to_json)
   body_builder :to_json
 
-  # URL-encoded form data (using to_query)
+  # URL-encoded form data (using to_query, requires ActiveSupport)
   body_builder :to_query
 
   # Custom query params builder (no ActiveSupport dependency)
@@ -213,6 +277,8 @@ class MyApiClient
 end
 ```
 
+String bodies are sent as is. Query strings are built the same way with `query_builder`, which accepts `:to_query`, `:query_params`, a method name or a block. It defaults to `:to_query` when ActiveSupport is loaded and to `:query_params` otherwise.
+
 ### Nested Routing (Sections)
 
 Organize complex APIs with nested routes:
@@ -222,12 +288,17 @@ class MyApiClient
   include ClientApiBuilder::Router
 
   base_url 'https://api.example.com'
-  header 'Authorization', :auth_token
+  header 'Authorization', :authorization
 
   attr_accessor :auth_token
 
+  def authorization
+    "Bearer #{auth_token}"
+  end
+
   section :users do
     base_url 'https://api.example.com/v2'  # Override base URL
+    header 'Authorization', :authorization
 
     route :list, '/users'
     route :get, '/users/:id'
@@ -235,6 +306,8 @@ class MyApiClient
   end
 
   section :posts do
+    header 'Authorization', :authorization
+
     route :list, '/posts'
     route :get, '/posts/:id'
   end
@@ -249,6 +322,8 @@ 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 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
 
 Configure connection settings:
@@ -268,6 +343,8 @@ class MyApiClient
 end
 ```
 
+Any `Net::HTTP.start` option can be set this way. Your options are applied over the secure HTTPS defaults, so setting `verify_mode` yourself replaces `VERIFY_PEER`.
+
 ### Retry Configuration
 
 Configure automatic retries for transient failures:
@@ -278,12 +355,14 @@ class MyApiClient
 
   base_url 'https://api.example.com'
 
-  # Retry up to 3 times with 0.5 second delay between attempts
+  # Make up to 3 attempts in total, waiting 0.5 seconds between them
   configure_retries 3, 0.5
 end
 ```
 
-By default, retries are performed only for network-related errors:
+The first argument is the total number of attempts, not extra retries. The default is 1, so requests are not retried unless you configure it. `retries:` and `sleep:` can also be passed per request.
+
+Only these network errors are retried by default:
 - `Net::OpenTimeout`, `Net::ReadTimeout`
 - `Errno::ECONNRESET`, `Errno::ECONNREFUSED`, `Errno::ETIMEDOUT`
 - `SocketError`, `EOFError`
@@ -345,6 +424,10 @@ client.process_stream do |response, chunk|
 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:
@@ -370,11 +453,18 @@ class MyApiClient
     data
   end
 end
+
+# A block passed to the call replaces the route's block
+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
 
-The gem provides detailed error information:
+`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:
 
 ```ruby
 begin
@@ -410,22 +500,22 @@ 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 available, the gem provides instrumentation and logging:
+When ActiveSupport is loaded before your client class includes `ClientApiBuilder::Router`, every request is instrumented as a `client_api_builder.request` event:
 
 ```ruby
-# Set up logging
-ClientApiBuilder.logger = Logger.new(STDOUT)
-
 # Subscribe to request events
 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
@@ -433,9 +523,22 @@ 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
+ClientApiBuilder.logger = Logger.new($stdout)
+```
+
 #### Production Logging
 
-For production environments, it's important to log requests without exposing sensitive credentials that may be present in query parameters. The following example strips query parameters from logged URLs:
+The built-in log subscriber already leaves out query strings, which may hold credentials. To customize the format, subscribe directly:
 
 ```ruby
 ActiveSupport::Notifications.subscribe('client_api_builder.request') do |_, start_time, end_time, _, payload|
@@ -461,11 +564,11 @@ Client API Builder includes several security features enabled by default:
 
 ### SSL/TLS Verification
 
-All HTTPS connections verify SSL certificates by default using `OpenSSL::SSL::VERIFY_PEER`. Default timeouts are also configured to prevent hanging connections.
+HTTPS connections verify SSL certificates using `OpenSSL::SSL::VERIFY_PEER` and default to a 30 second open timeout and 60 second read timeout. Plain HTTP connections use Net::HTTP's own defaults.
 
 ### 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
@@ -478,16 +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 operations validate paths to prevent directory traversal attacks:
+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+`.
@@ -522,12 +636,12 @@ end
 | Method | Description |
 |--------|-------------|
 | `base_url(url)` | Set the base URL for all requests |
-| `header(name, value)` | Add a header to all requests |
+| `header(name, value = nil, &block)` | Add a header to all requests (value, method name symbol, or block) |
 | `body_builder(builder)` | Configure request body serialization |
 | `query_builder(builder)` | Configure query string serialization |
-| `query_param(name, value)` | Add a query parameter to all requests |
+| `query_param(name, value = nil, &block)` | Add a query parameter to all requests (value, method name symbol, or block) |
 | `connection_option(name, value)` | Set Net::HTTP connection options |
-| `configure_retries(max, sleep)` | Configure retry behavior |
+| `configure_retries(max_attempts, sleep = 0.05)` | Configure retry behavior |
 | `route(name, path, options)` | Define an API endpoint |
 | `section(name, options, &block)` | Define nested routes |
 | `namespace(path, &block)` | Add path prefix to routes in block |
@@ -541,11 +655,27 @@ end
 | `total_request_time` | Duration of last request in seconds |
 | `request_attempts` | Number of attempts for last request |
 | `root_router` | Returns the root router (for nested routers) |
+| `base_url` | Base URL used for requests |
+
+### Overridable Hooks
+
+Define these in your client to change default behavior:
+
+| Method | Default |
+|--------|---------|
+| `retry_request?(exception, options)` | `true` for the network errors listed under Retry Configuration |
+| `escape_path(value)` | Percent-encodes path values (`ERB::Util.url_encode`) |
+| `parse_response(response, options)` | Parses the body as JSON, `nil` when empty |
+| `handle_response(response, options, &block)` | Applies `return:`, parsing and the response block |
+| `expected_response_code!(response, codes, options)` | Raises `UnexpectedResponse` for unexpected codes |
+| `get_retry_request_max_retries(options)` | `retries:` option, then `configure_retries`, then 1 |
+| `get_retry_request_sleep_time(exception, options)` | `sleep:` option, then `configure_retries`, then 0.05 |
 
 ## Requirements
 
 - Ruby 3.2+
 - `inheritance-helper` gem (>= 0.2.5)
+- `activesupport` (optional) for `to_query` builders and instrumentation
 
 ## Contributing
 
@@ -554,7 +684,7 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/dougyo
 1. Fork the repository
 2. Create your feature branch (`git checkout -b feature/my-feature`)
 3. Write tests for your changes
-4. Ensure all tests pass (`bundle exec rspec`)
+4. Ensure all tests pass with full line and branch coverage (`CI=true bundle exec rspec`)
 5. Ensure code style compliance (`bundle exec rubocop`)
 6. Commit your changes using [conventional commits](https://www.conventionalcommits.org/) (`git commit -am 'feat(router): add my feature'`); release notes and version bumps are generated from them
 7. Push to the branch (`git push origin feature/my-feature`)

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/nested_router.rb

@@ -17,7 +17,7 @@ module ClientApiBuilder
     end
 
     def self.get_instance_method(var)
-      "\#{root_router.#{var}}"
+      "\#{escape_path(root_router.#{var})}"
     end
 
     def base_url

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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'erb'
 require 'inheritance-helper'
 require 'json'
 
@@ -24,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,
@@ -49,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
@@ -73,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
@@ -169,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)/i
+        when /\A(?:delete|remove|destroy)(?:_|\z)/i
           :delete
         else
           :get
@@ -191,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
@@ -274,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})}"
@@ -292,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
@@ -305,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
@@ -323,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
@@ -351,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"
@@ -379,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)
@@ -412,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
 
@@ -430,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
@@ -441,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)
@@ -469,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)
 
@@ -501,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?('/')
 
@@ -511,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)
@@ -552,8 +591,11 @@ module ClientApiBuilder
       self
     end
 
+    # Percent-encodes everything but RFC 3986 unreserved characters (A-Z a-z 0-9 - . _ ~),
+    # so a value inserted into the path, including any '/', stays one segment.
+    # Override to change how path values are encoded.
     def escape_path(path)
-      path
+      ERB::Util.url_encode(path.to_s)
     end
 
     def instrument_request
@@ -590,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.0'
+  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.0
+  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