client-api-builder 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6561ab09540d28c2d47a6761a538870b81f022f9ec67cf79adff64255a3edea
-  data.tar.gz: b2247387bc5481b0acb55573bcca7c504a5c9500fe3ef81e5b9f14114fb939ac
+  metadata.gz: 7d553ae987e278ac4a41b6185531e02292cc2f3b57cd4af1332552d827ad74b5
+  data.tar.gz: 50cd54be44249bf9a366929c73abe839bab6c2594bf299bc6a0ebb5db4278db3
 SHA512:
-  metadata.gz: 44b79649b72ea649ce6141fb8313e51a659ef3cea1f3737d41ca89fe88e09be14e0f5a0225f4e99fbad59f0ed070698108a8221c282c3c6fde3ecd58c270f4ab
-  data.tar.gz: 583ac9eba3eb265afbb00e738dc4208d79afa810b51a35f3a0a12fca1af9780f14ee51a7c7c885294176f417f73b6b96c47996f16c141ea5cba2ce7646873ffa
+  metadata.gz: 8dfbfc94f744e4d7f91386d550d6d33b98049c872b4324f3dffd9a49e3d42d52ea805d93c2e9cd0c97c556826b6a9aaa2415689d019a49790be14af677adc936
+  data.tar.gz: cd6170e890b619dbac6ec5fe7be55fb9f092fcde346597a201390ee351204a51f8d483a627e26ae3bffae0d50329d63d2e93f81192047b7d56f897c1bc187711

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.1.0](https://github.com/dougyouch/client-api-builder/compare/v1.0.0...v1.1.0) (2026-10-23)
+
+
+### Features
+
+* **transports:** choose how requests are sent per environment ([2193768](https://github.com/dougyouch/client-api-builder/commit/2193768ce8b916ffb9064ccedbd09b87b47def5e))
+
 ## [1.0.0](https://github.com/dougyouch/client-api-builder/compare/v0.11.0...v1.0.0) (2026-10-05)
 
 

data/README.md

@@ -5,6 +5,8 @@
 [![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)
 
+[Changelog](CHANGELOG.md) · [Upgrading to 1.0](UPGRADING.md)
+
 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.
 
 ## Features
@@ -15,6 +17,7 @@ A Ruby gem for building robust, secure API clients through declarative configura
 - **Flexible Request Building** - Support for JSON, query params, and custom body builders
 - **Nested Routing** - Organize complex APIs with hierarchical route structures
 - **Retry Logic** - Configurable automatic retries for transient network failures
+- **Transports** - Choose how requests reach the network per environment at boot, so one client class can open a connection per request in a web server and keep persistent connections in a worker
 - **Connection Pooling** - Opt-in persistent connections shared across threads, with no extra gems
 - **Per-Thread Connections** - Opt-in persistent connections dedicated to each thread, with no pool to size
 - **HTTP/2** - Opt-in HTTP/2 over TLS, multiplexing concurrent requests on one connection per host (with the `http-2` gem)
@@ -336,7 +339,7 @@ section :users, inherit: %i[headers query_params connection_options] do
 end
 ```
 
-Inherited settings are the root client's class-level ones, read on every request (so ones declared after the section, or in a subclass of the client, apply too). The section's own settings override them, and per-request options override both; a per-request `nil` header still drops an inherited one. Retries and body/query builders are always the section's own. Any other options passed to `section` are available to it as `nested_router_options`.
+Inherited settings are the root client's class-level ones, read on every request (so ones declared after the section, or in a subclass of the client, apply too). The section's own settings override them, and per-request options override both; a per-request `nil` header still drops an inherited one. Retries and body/query builders are always the section's own. Any other options passed to `section` are available to it as `nested_router_options`. Get a section's class with `<name>_router` (`MyApiClient.users_router`) rather than its constant name; see [UPGRADING.md](UPGRADING.md#section-class-names-are-no-longer-singularized).
 
 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.
 
@@ -361,9 +364,67 @@ 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`.
 
+### Transports
+
+How requests reach the network is up to a transport, chosen for the environment at boot rather than in the client class. The same `GitHubClient` can open a connection per request inside a web server and keep per-thread connections inside a background worker:
+
+```ruby
+# config/puma.rb, or any web server's boot code: the default, shown for clarity
+ClientApiBuilder.use_transport(ClientApiBuilder::Transports::OneShot.new)
+
+# config/initializers/sidekiq.rb
+Sidekiq.configure_server do |config|
+  ClientApiBuilder.use_transport(ClientApiBuilder::Transports::ThreadLocal.new(ttl: 30))
+  config.on(:shutdown) { ClientApiBuilder.close_transports }
+end
+```
+
+| Transport | Connections | Suits |
+|---|---|---|
+| `Transports::OneShot.new` (default) | A new one per request, closed once the response is read | Web servers, forking process managers, low request rates |
+| `Transports::Pooled.new(max_connections:, ttl:, checkout_timeout:, idle_timeout:)` | Pools shared by every thread, one per scheme, host, port and connection options | Many threads, including short-lived ones ([details](#persistent-connections)) |
+| `Transports::ThreadLocal.new(ttl:, idle_timeout:)` | One per thread and host, reused by that thread's requests | A fixed set of worker threads ([details](#per-thread-connections)) |
+| `Transports::HTTP2.new(fallback: Transports::OneShot.new)` | One HTTP/2 connection per origin, carrying concurrent requests as streams | Many threads waiting on one slow https API ([details](#http2)) |
+
+Register a transport for every client, for one client class (and its subclasses), or for one client instance:
+
+```ruby
+ClientApiBuilder.use_transport(ClientApiBuilder::Transports::ThreadLocal.new)                 # every client
+ClientApiBuilder.use_transport(ClientApiBuilder::Transports::Pooled.new(max_connections: 10), GitHubClient)
+client.transport = ClientApiBuilder::Transports::OneShot.new                                  # this instance only
+
+ClientApiBuilder.close_transports # closes every registered transport's connections, e.g. at shutdown
+```
+
+A request uses the first transport it finds:
+
+1. The one set on the client instance with `transport=`.
+2. The one registered with `use_transport` for the client's class or its nearest ancestor (a module works too, for every class including it).
+3. The one the class itself includes (`ConnectionPools`, `ThreadConnections` or `HTTP2`, below), or its nearest ancestor's.
+4. For a section, its root client's transport.
+5. The process default set with `use_transport(transport)`, else `OneShot`.
+
+So a class can include a sensible default for its API, and the environment still decides: `use_transport` for the class wins whether it runs before or after the class is loaded. Sections use their root client's transport, so they share its connections, unless a transport is set or registered for the section, or it calls `connection_pool` or `connection_per_thread`.
+
+Every transport is fork-safe (after a fork, the child opens its own connections and leaves the parent's alone) and closes a connection whose request raised rather than reusing it.
+
+A transport is any object with `with_connection(uri, connection_options) { |http| ... }`, which yields something answering `request(net_request) { |response| ... }` like a started `Net::HTTP`, and `close`. `connection_options` are the `Net::HTTP.start` options, with the [secure HTTPS defaults](#connection-options) applied.
+
 ### Persistent Connections
 
-By default each request opens and closes its own connection. Include `ClientApiBuilder::ConnectionPools` (after `Router`) to keep connections open and reuse them:
+`Transports::Pooled` keeps connections open and reuses them:
+
+```ruby
+# Optional settings; these are the defaults
+ClientApiBuilder.use_transport(
+  ClientApiBuilder::Transports::Pooled.new(max_connections: 5,  # connections per host
+                                           ttl: 30,             # seconds before a connection is closed and replaced
+                                           checkout_timeout: 5, # seconds to wait for a free connection
+                                           idle_timeout: 2)     # seconds idle before Net::HTTP reconnects (keep_alive_timeout)
+)
+```
+
+Or give a client class its own pools, as its default, by including `ClientApiBuilder::ConnectionPools` (after `Router`):
 
 ```ruby
 class MyApiClient
@@ -372,21 +433,17 @@ class MyApiClient
 
   base_url 'https://api.example.com'
 
-  # Optional; these are the defaults
-  connection_pool max_connections: 5,  # connections per host
-                  ttl: 30,             # seconds before a connection is closed and replaced
-                  checkout_timeout: 5, # seconds to wait for a free connection
-                  idle_timeout: 2      # seconds idle before Net::HTTP reconnects (keep_alive_timeout)
+  connection_pool max_connections: 10, ttl: 60 # optional; takes the same settings
 end
 ```
 
-The pools live on the class, like ActiveRecord's, so every instance shares them: keep one client instance per thread and the threads share the connections. A connection is checked out for one request (or one streamed response) and returned straight after, so `max_connections` can be lower than your thread count. There is one pool per scheme, host, port and connection options.
+Every client using the transport shares its pools: keep one client instance per thread and the threads share the connections. A connection is checked out for one request (or one streamed response) and returned straight after, so `max_connections` can be lower than your thread count. There is one pool per scheme, host, port and connection options.
 
 - Sockets the server has closed, or that sat idle past `idle_timeout`, are reopened automatically.
 - A connection whose request raised is closed rather than reused.
 - When no connection frees up within `checkout_timeout`, the request raises `ClientApiBuilder::ConnectionPools::TimeoutError`.
-- Sections use their root client's pools, getting a separate pool for any other host in their `base_url`. Subclasses share their parent's pools unless they call `connection_pool` themselves.
-- A section can call `connection_pool` in its block to get its own pools and settings. This works whether or not the root client includes `ConnectionPools`:
+- With `ConnectionPools`, sections use their root client's pools, getting a separate pool for any other host in their `base_url`. Subclasses share their parent's pools unless they call `connection_pool` themselves.
+- A section can call `connection_pool` in its block to get its own pools and settings. This works whatever transport the root client uses:
 
   ```ruby
   section :uploads do
@@ -397,25 +454,20 @@ The pools live on the class, like ActiveRecord's, so every instance shares them:
 
   Sections nested inside it still fall back to the root client, as they do for `base_url`.
 - After a fork (Puma, Sidekiq, Resque), the child process opens its own connections.
-- `MyApiClient.close_connections` closes idle connections now and in-use ones when they're returned, including the pools of sections that have their own.
+- `transport.close` (or `MyApiClient.close_connections`, with `ConnectionPools`) closes idle connections now and in-use ones when they're returned. `close_connections` also closes the pools of sections that have their own.
 
 Pooling uses only `Net::HTTP` from the standard library.
 
 ### Per-Thread Connections
 
-When a program runs a fixed set of worker threads, each making its own requests, include `ClientApiBuilder::ThreadConnections` (after `Router`, instead of `ConnectionPools`) to give every thread its own persistent connections:
+When a program runs a fixed set of worker threads, each making its own requests, `Transports::ThreadLocal` gives every thread its own persistent connections:
 
 ```ruby
-class MyApiClient
-  include ClientApiBuilder::Router
-  include ClientApiBuilder::ThreadConnections
-
-  base_url 'https://api.example.com'
-
-  # Optional; these are the defaults
-  connection_per_thread ttl: 30,        # seconds before a connection is closed and replaced
-                        idle_timeout: 2 # seconds idle before Net::HTTP reconnects (keep_alive_timeout)
-end
+# Optional settings; these are the defaults
+ClientApiBuilder.use_transport(
+  ClientApiBuilder::Transports::ThreadLocal.new(ttl: 30,        # seconds before a connection is closed and replaced
+                                                idle_timeout: 2) # seconds idle before Net::HTTP reconnects (keep_alive_timeout)
+)
 
 workers = Array.new(20) do
   Thread.new do
@@ -425,23 +477,35 @@ workers = Array.new(20) do
 end
 ```
 
+To make it a client class's default, include `ClientApiBuilder::ThreadConnections` (after `Router`, instead of `ConnectionPools`) and optionally call `connection_per_thread ttl: 30, idle_timeout: 2` in the class.
+
 A thread opens a connection per host (scheme, port and connection options) on its first request and reuses it for every later one. There's no pool size to keep in step with the thread count, and no thread ever waits for another's connection.
 
 - Sockets the server has closed, or that sat idle past `idle_timeout`, are reopened automatically. A connection whose request raised is closed rather than reused.
 - A request made while the thread's connection is busy (from inside a streaming block, or from another fiber on the thread) opens a connection of its own; the thread keeps one of the two afterwards.
-- Connections of threads that have finished are closed when a thread makes its first request. With short-lived threads, prefer `ConnectionPools`.
-- Sections and subclasses share the class's connections the same way they share pools, and a section can call `connection_per_thread` in its block to get its own.
-- After a fork, the child process opens its own connections. `MyApiClient.close_connections` closes every thread's idle connections now and in-use ones when their request ends.
+- Connections of threads that have finished are closed when a thread makes its first request. With short-lived threads, prefer `Transports::Pooled`.
+- With `ThreadConnections`, sections and subclasses share the class's connections the same way they share pools, and a section can call `connection_per_thread` in its block to get its own.
+- After a fork, the child process opens its own connections. `transport.close` (or `MyApiClient.close_connections`) closes every thread's idle connections now and in-use ones when their request ends.
 
 ### HTTP/2
 
-Include `ClientApiBuilder::HTTP2` (after `Router`, and after `ConnectionPools` or `ThreadConnections` if you use either) to send https requests over HTTP/2. It needs the [`http-2`](https://rubygems.org/gems/http-2) gem, which isn't installed with this one:
+`Transports::HTTP2` sends https requests over HTTP/2. It needs the [`http-2`](https://rubygems.org/gems/http-2) gem, which isn't installed with this one:
 
 ```ruby
 # Gemfile
 gem 'http-2'
 ```
 
+```ruby
+# fallback: is used for http:// URLs and servers that only speak HTTP/1.1 (default: OneShot)
+ClientApiBuilder.use_transport(
+  ClientApiBuilder::Transports::HTTP2.new(fallback: ClientApiBuilder::Transports::Pooled.new),
+  MyApiClient
+)
+```
+
+Or make it a client class's default by including `ClientApiBuilder::HTTP2` (after `Router`, and after `ConnectionPools` or `ThreadConnections` to use them as the fallback):
+
 ```ruby
 class MyApiClient
   include ClientApiBuilder::Router
@@ -452,15 +516,15 @@ class MyApiClient
 end
 ```
 
-Every instance of the class shares one connection per host (and connection options), and concurrent requests from different threads travel over it as separate streams. Responses are ordinary `Net::HTTPResponse` objects with `http_version` `'2.0'`, so `handle_response`, `UnexpectedResponse#response` and streaming routes work unchanged.
+Every client using the transport shares one connection per host (and connection options), and concurrent requests from different threads travel over it as separate streams. Responses are ordinary `Net::HTTPResponse` objects with `http_version` `'2.0'`, so `handle_response`, `UnexpectedResponse#response` and streaming routes work unchanged.
 
-- The protocol is negotiated during the TLS handshake (ALPN). When a server picks HTTP/1.1, that host is remembered and its requests go through `Net::HTTP`, or the pooled or per-thread connections if the class includes `ConnectionPools` or `ThreadConnections`. `http://` URLs always use HTTP/1.1.
+- The protocol is negotiated during the TLS handshake (ALPN). When a server picks HTTP/1.1, that host is remembered and its requests go through the fallback transport. `http://` URLs always use the fallback.
 - The usual connection options apply: `open_timeout`, `read_timeout` (per response header and body chunk), and the SSL options (`verify_mode`, `ca_file`, `cert_store`, `cert`, `key`, ...). Proxies aren't supported.
 - When the server's limit on concurrent streams is reached, a request waits up to `read_timeout` for a stream to free up.
 - Gzip and deflate responses are inflated, as `Net::HTTP` does, unless you set `Accept-Encoding` yourself.
 - A stream the server refused, or never processed before closing the connection (GOAWAY), raises `ClientApiBuilder::HTTP2::StreamRefused`; a dropped connection raises `ClientApiBuilder::HTTP2::ConnectionLost`. Both are retried by `configure_retries`. A stream the server reset raises `ClientApiBuilder::HTTP2::StreamError`.
 - Response data is acknowledged to the server as it arrives, so a streaming consumer slower than the server buffers the difference in memory.
-- Sections use their root client's connections. After a fork, the child opens its own. `MyApiClient.close_connections` closes the HTTP/2 connections (and the pooled or per-thread ones).
+- After a fork, the child opens its own connections. `transport.close` (or `MyApiClient.close_connections`, with `include ClientApiBuilder::HTTP2`) closes the HTTP/2 connections and the fallback's.
 
 **When it's faster.** `script/benchmark_http2.rb` compares a new connection per request, `ConnectionPools` and HTTP/2 against a local TLS server. On one machine (Ruby 4.0.7, http-2 1.2.3):
 
@@ -470,7 +534,7 @@ Every instance of the class shares one connection per host (and connection optio
 | 50 threads, 20ms delay, one pooled connection per thread | 628 req/s | 1,904 req/s | 1,765 req/s |
 | 50 threads, 20ms delay, default pool of 5 | 640 req/s | 208 req/s | 1,706 req/s |
 
-HTTP/2 avoids a TLS handshake per request, like the pools, and isn't limited by a connection count: many threads waiting on a slow API share one connection. Per request, it costs more client CPU than pooled HTTP/1.1 (the protocol layer is pure Ruby), which shows most with large bodies. If you can give each thread its own connection (a pool as large as the thread count, or `ThreadConnections`), HTTP/1.1 is usually as fast or faster.
+HTTP/2 avoids a TLS handshake per request, like the pools, and isn't limited by a connection count: many threads waiting on a slow API share one connection. Per request, it costs more client CPU than pooled HTTP/1.1 (the protocol layer is pure Ruby), which shows most with large bodies. If you can give each thread its own connection (a pool as large as the thread count, or `Transports::ThreadLocal`), HTTP/1.1 is usually as fast or faster.
 
 ### Retry Configuration
 
@@ -756,7 +820,7 @@ Only safe file modes are allowed for streaming to files: `w`, `wb`, `a`, `ab`, `
 
 ## Thread Safety
 
-Client instances are **not thread-safe**. Create a separate client instance per thread. To share connections between those instances, see [Persistent Connections](#persistent-connections).
+Client instances are **not thread-safe**. Create a separate client instance per thread. To share connections between those instances, see [Transports](#transports).
 
 ```ruby
 # Correct: Create a new client for each thread
@@ -817,7 +881,7 @@ Define these in your client to change default behavior:
 | Method | Default |
 |--------|---------|
 | `retry_request?(exception, options)` | `true` for the network errors listed under Retry Configuration |
-| `with_http_connection(uri, connection_options, &block)` | Yields a started `Net::HTTP`: a new connection per request, a pooled one with `ConnectionPools`, or the thread's own with `ThreadConnections` |
+| `with_http_connection(uri, connection_options, &block)` | Yields a started `Net::HTTP` (or an HTTP/2 connection) from the client's [transport](#transports) |
 | `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 |
@@ -828,7 +892,7 @@ Define these in your client to change default behavior:
 ## Requirements
 
 - Ruby 3.3+
-- `inheritance-helper` gem (>= 0.2.5)
+- `inheritance-helper` gem (1.x)
 - `activesupport` (optional) for `to_query` builders and instrumentation
 
 ## Contributing

data/UPGRADING.md

@@ -0,0 +1,139 @@
+# Upgrading
+
+## From 1.0 to 1.1: transports (optional)
+
+1.1 has no breaking changes. Clients that include `ClientApiBuilder::ConnectionPools`, `ThreadConnections` or `HTTP2`
+keep working as before, with the same `connection_pool`, `connection_per_thread` and `close_connections` class methods.
+
+What's new is that how requests reach the network can be chosen per environment at boot, with
+[transports](README.md#transports), instead of only in the client class. Move to them when one client class needs
+different connection handling in different processes, for example a connection per request in a web server and
+persistent connections in a background worker.
+
+Before, the class decided for every process:
+
+```ruby
+class GitHubClient
+  include ClientApiBuilder::Router
+  include ClientApiBuilder::ThreadConnections
+
+  base_url 'https://api.github.com'
+  connection_per_thread ttl: 30
+end
+```
+
+After, the class describes the API and each process picks its transport:
+
+```ruby
+class GitHubClient
+  include ClientApiBuilder::Router
+
+  base_url 'https://api.github.com'
+end
+
+# Sidekiq boot code; the web server keeps the default, a new connection per request
+ClientApiBuilder.use_transport(ClientApiBuilder::Transports::ThreadLocal.new(ttl: 30), GitHubClient)
+at_exit { ClientApiBuilder.close_transports }
+```
+
+You can also keep the `include` as the class's default and override it only where needed: a transport registered for
+the class with `use_transport` wins over the one it includes, whether it's registered before or after the class loads.
+
+| Include style | Transport |
+|---|---|
+| `include ClientApiBuilder::ConnectionPools` + `connection_pool(**settings)` | `Transports::Pooled.new(**settings)` |
+| `include ClientApiBuilder::ThreadConnections` + `connection_per_thread(**settings)` | `Transports::ThreadLocal.new(**settings)` |
+| `include ClientApiBuilder::HTTP2` | `Transports::HTTP2.new` |
+| `include ClientApiBuilder::ConnectionPools` + `include ClientApiBuilder::HTTP2` | `Transports::HTTP2.new(fallback: Transports::Pooled.new)` |
+| `MyClient.close_connections` | `transport.close`, or `ClientApiBuilder.close_transports` for all of them |
+
+One behaviour to know: if your client overrides `with_http_connection`, the override still runs and still takes
+precedence over every transport.
+
+## From 0.11 to 1.0
+
+1.0 has two breaking changes. Most clients need no code changes; check whether these apply to you.
+
+| Change | Who is affected |
+|---|---|
+| [Ruby 3.3 or newer is required](#ruby-33-or-newer-is-required) | Apps on Ruby 3.2 |
+| [Section class names are no longer singularized](#section-class-names-are-no-longer-singularized) | Apps with ActiveSupport loaded (any Rails app) that refer to a section's class by its constant name |
+
+1.0 also requires [inheritance-helper 1.x](https://github.com/dougyouch/inheritance-helper/blob/master/UPGRADING.md).
+If your own code uses inheritance-helper directly, check its upgrade guide too.
+
+### Ruby 3.3 or newer is required
+
+Ruby 3.2 reached end of life in March 2026. On Ruby 3.2, Bundler and RubyGems keep resolving to 0.11.0.
+
+### Section class names are no longer singularized
+
+Each `section` creates a router class and assigns it to a constant on the client class. The name came from
+inheritance-helper, which used `String#classify` when ActiveSupport was loaded, and `classify` singularizes. 1.0
+requires inheritance-helper 1.x, which builds the name the same way everywhere:
+
+| Section | 0.11 with ActiveSupport | 0.11 without ActiveSupport | 1.0 |
+|---|---|---|---|
+| `section :users` | `UserNestedRouter` | `UsersNestedRouter` | `UsersNestedRouter` |
+| `section :news_items` | `NewsItemNestedRouter` | `NewsItemsNestedRouter` | `NewsItemsNestedRouter` |
+| `section :user` | `UserNestedRouter` | `UserNestedRouter` | `UserNestedRouter` |
+
+**What doesn't change:** `client.users`, `MyClient.users_router` and `MyClient.section_routers` return the same
+classes as before. Without ActiveSupport, nothing changes at all.
+
+**What changes:** with ActiveSupport loaded, code that names the constant, such as `MyClient::UserNestedRouter`
+for `section :users`, gets a `NameError` (uninitialized constant).
+
+**Watch for a singular and a plural section in the same client.** On 0.11 with ActiveSupport, `section :user`
+and `section :users` both became `UserNestedRouter`, and whichever was declared last replaced the other (with an
+"already initialized constant" warning). On 1.0 each gets its own class:
+
+```ruby
+class MyClient
+  include ClientApiBuilder::Router
+
+  section(:user)  { route :me, '/me' }
+  section(:users) { route :list_users, '/users' }
+end
+
+MyClient::UserNestedRouter   # 0.11: the :users section (declared last)   1.0: the :user section
+MyClient::UsersNestedRouter  # 0.11: NameError                              1.0: the :users section
+```
+
+Code that used `UserNestedRouter` to mean the `:users` section doesn't fail on 1.0. It gets the `:user` section
+instead, so check for this case.
+
+#### Finding affected code
+
+Search for the generated constants:
+
+```bash
+grep -rnE '[A-Za-z]+NestedRouter\b' app lib spec | grep -v 'ClientApiBuilder::NestedRouter'
+```
+
+#### Fixing it
+
+Use the `<name>_router` class method, which is the same on every version:
+
+```ruby
+# before
+MyClient::UserNestedRouter
+# after
+MyClient.users_router
+```
+
+If you can't change every reference at once, alias the old name to the section's class after it's defined:
+
+```ruby
+class MyClient
+  include ClientApiBuilder::Router
+
+  section(:users) { route :list_users, '/users' }
+
+  # temporary: keeps 0.11's name working until callers use users_router
+  UserNestedRouter = users_router
+end
+```
+
+Don't add an alias that clashes with a section of that name. In the example above with both `:user` and
+`:users`, `UserNestedRouter` already belongs to `:user`.

data/lib/client-api-builder.rb

@@ -20,11 +20,26 @@ module ClientApiBuilder
 
   class << self
     attr_accessor :logger
+
+    # The process-wide Transports::Registry
+    attr_reader :transports
+
+    # Sends requests through transport: for every client, or for client_class and its
+    # subclasses when given. Meant to be called once at boot for the environment.
+    def use_transport(transport, client_class = nil)
+      transports.use(transport, client_class)
+    end
+
+    # Closes the connections of every registered transport, e.g. at shutdown
+    def close_transports
+      transports.close_all
+    end
   end
 
   autoload :ActiveSupportNotifications, 'client_api_builder/active_support_notifications'
   autoload :ActiveSupportLogSubscriber, 'client_api_builder/active_support_log_subscriber'
   autoload :ConnectionPools, 'client_api_builder/connection_pools'
+  autoload :DeclaredTransport, 'client_api_builder/declared_transport'
   autoload :HTTP2, 'client_api_builder/http2'
   autoload :NestedRouter, 'client_api_builder/nested_router'
   autoload :QueryParams, 'client_api_builder/query_params'
@@ -32,8 +47,11 @@ module ClientApiBuilder
   autoload :Router, 'client_api_builder/router'
   autoload :Section, 'client_api_builder/section'
   autoload :ThreadConnections, 'client_api_builder/thread_connections'
+  autoload :Transports, 'client_api_builder/transports'
 
   module NetHTTP
     autoload :Request, 'client_api_builder/net_http_request'
   end
+
+  @transports = Transports::Registry.new
 end

data/lib/client_api_builder/connection_pools.rb

@@ -12,6 +12,8 @@
 #
 # Each thread uses its own client instance; the instances check connections out of the
 # class's pools (one pool per host and connection options) for the length of one request.
+# The pools are a Transports::Pooled declared as the class's transport, so
+# ClientApiBuilder.use_transport can still pick another one for the class at boot.
 module ClientApiBuilder
   module ConnectionPools
     autoload :Connection, 'client_api_builder/connection_pools/connection'
@@ -34,6 +36,7 @@ module ClientApiBuilder
         raise ArgumentError, 'include ClientApiBuilder::ConnectionPools before ClientApiBuilder::HTTP2'
       end
 
+      base.extend ::ClientApiBuilder::DeclaredTransport
       base.extend ClassMethods
       base.connection_pool
     end
@@ -42,7 +45,12 @@ module ClientApiBuilder
       # Configures this class's pools, replacing any it already had. Subclasses share their
       # parent's pools unless they call connection_pool themselves.
       def connection_pool(**settings)
-        redefine_class_method(:connection_pools, PoolSet.new(Settings.new(**settings)))
+        redefine_class_method(:http1_transport, ::ClientApiBuilder::Transports::Pooled.new(**settings))
+        declare_transport
+      end
+
+      def connection_pools
+        http1_transport.pool_set
       end
 
       # Closes idle connections now and in-use ones when they are returned, including the
@@ -52,9 +60,5 @@ module ClientApiBuilder
         section_routers.each_value(&:close_connections)
       end
     end
-
-    def with_http_connection(uri, connection_options, &)
-      self.class.connection_pools.with_connection(uri, connection_options, &)
-    end
   end
 end

data/lib/client_api_builder/declared_transport.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module ClientApiBuilder
+  # Class methods shared by the ConnectionPools, ThreadConnections and HTTP2 mixins. Each
+  # stores its transport on the class with redefine_class_method, so subclasses share it,
+  # and declare_transport registers their combination as the class's declared transport
+  # (see Transports::Registry): the HTTP/2 transport falling back to the HTTP/1.1 one.
+  module DeclaredTransport
+    # The transport for http URLs, and https origins without HTTP/2
+    def http1_transport
+      Transports::OneShot.new
+    end
+
+    # The class's HTTP/2 transport, when it includes HTTP2
+    def http2_transport
+      nil
+    end
+
+    def declare_transport
+      transport = http2_transport ? http2_transport.with_fallback(http1_transport) : http1_transport
+      ClientApiBuilder.transports.declare(transport, self)
+    end
+  end
+end

data/lib/client_api_builder/http2.rb

@@ -15,7 +15,8 @@
 # as streams. TLS negotiates the protocol (ALPN): when the server picks HTTP/1.1, the origin is
 # remembered and its requests go through Net::HTTP (or the pooled or per-thread connections)
 # instead. http URLs always use HTTP/1.1. Responses are Net::HTTPResponse objects with
-# http_version '2.0'.
+# http_version '2.0'. The class's transport becomes a Transports::HTTP2 falling back to its
+# HTTP/1.1 transport; ClientApiBuilder.use_transport can still pick another one at boot.
 module ClientApiBuilder
   module HTTP2
     autoload :Connection, 'client_api_builder/http2/connection'
@@ -43,9 +44,10 @@ module ClientApiBuilder
         raise ArgumentError, 'include ClientApiBuilder::Router before ClientApiBuilder::HTTP2'
       end
 
-      require_http2_gem
+      base.extend ::ClientApiBuilder::DeclaredTransport
       base.extend ClassMethods
-      base.redefine_class_method(:http2_connections, ConnectionSet.new)
+      base.redefine_class_method(:http2_transport, ::ClientApiBuilder::Transports::HTTP2.new)
+      base.declare_transport
     end
 
     def self.require_http2_gem
@@ -55,6 +57,10 @@ module ClientApiBuilder
     end
 
     module ClassMethods
+      def http2_connections
+        http2_transport.connections
+      end
+
       # Closes this class's HTTP/2 connections, and its pooled or per-thread connections when it
       # has them
       def close_connections
@@ -62,10 +68,5 @@ module ClientApiBuilder
         super if defined?(super)
       end
     end
-
-    def with_http_connection(uri, connection_options, &)
-      connection = uri.scheme == 'https' && self.class.http2_connections.connection_for(uri, connection_options)
-      connection ? yield(connection) : super
-    end
   end
 end

data/lib/client_api_builder/nested_router.rb

@@ -87,10 +87,10 @@ module ClientApiBuilder
       root_router.handle_response(response, options, &)
     end
 
-    # Uses the root client's connections unless this section calls connection_pool or
-    # connection_per_thread
-    def with_http_connection(uri, connection_options, &)
-      root_router.with_http_connection(uri, connection_options, &)
+    # Uses the root client's transport unless one is set on this section, registered for its
+    # class, or declared by connection_pool or connection_per_thread
+    def transport
+      @transport || ClientApiBuilder.transports.registered_for(self.class) || root_router.transport
     end
 
     private

data/lib/client_api_builder/net_http_request.rb

@@ -50,10 +50,19 @@ module ClientApiBuilder
         end
       end
 
-      # Yields a started Net::HTTP session for one request. By default each request opens
-      # and closes its own connection; ConnectionPools overrides this to reuse pooled ones.
+      # Sends this client's requests through transport instead of its class's
+      attr_writer :transport
+
+      # The transport set on this client, else the one registered for its class (see
+      # Transports::Registry)
+      def transport
+        @transport || ClientApiBuilder.transports.for_class(self.class)
+      end
+
+      # Yields a started Net::HTTP session (or something answering request like one) for one
+      # request, from the client's transport
       def with_http_connection(uri, connection_options, &)
-        Net::HTTP.start(uri.hostname, uri.port, connection_options, &)
+        transport.with_connection(uri, connection_options, &)
       end
 
       # validate_response, when given, is called with the response before its body is streamed

data/lib/client_api_builder/thread_connections.rb

@@ -12,7 +12,8 @@
 #
 # Each thread opens its own connection per host on its first request and reuses it for its
 # later ones, so there's no pool size to match to the thread count and no waiting for a
-# connection to free up.
+# connection to free up. The connections are a Transports::ThreadLocal declared as the class's
+# transport, so ClientApiBuilder.use_transport can still pick another one for the class at boot.
 module ClientApiBuilder
   module ThreadConnections
     autoload :ConnectionSet, 'client_api_builder/thread_connections/connection_set'
@@ -30,6 +31,7 @@ module ClientApiBuilder
         raise ArgumentError, 'include ClientApiBuilder::ThreadConnections before ClientApiBuilder::HTTP2'
       end
 
+      base.extend ::ClientApiBuilder::DeclaredTransport
       base.extend ClassMethods
       base.connection_per_thread
     end
@@ -38,7 +40,12 @@ module ClientApiBuilder
       # Configures this class's per-thread connections, replacing any it already had.
       # Subclasses share their parent's unless they call connection_per_thread themselves.
       def connection_per_thread(**settings)
-        redefine_class_method(:thread_connections, ConnectionSet.new(Settings.new(**settings)))
+        redefine_class_method(:http1_transport, ::ClientApiBuilder::Transports::ThreadLocal.new(**settings))
+        declare_transport
+      end
+
+      def thread_connections
+        http1_transport.connection_set
       end
 
       # Closes every thread's idle connections now and in-use ones when their request ends,
@@ -48,9 +55,5 @@ module ClientApiBuilder
         section_routers.each_value(&:close_connections)
       end
     end
-
-    def with_http_connection(uri, connection_options, &)
-      self.class.thread_connections.with_connection(uri, connection_options, &)
-    end
   end
 end

data/lib/client_api_builder/transports/http2.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ClientApiBuilder
+  module Transports
+    # HTTP/2 for https, one connection per origin and connection options carrying concurrent
+    # requests as streams (needs the http-2 gem). http URLs, and origins whose server chose
+    # HTTP/1.1 during the TLS handshake, go through the fallback transport.
+    #
+    # connections: shares the HTTP/2 connections of another transport (see with_fallback).
+    class HTTP2
+      attr_reader :fallback, :connections
+
+      def initialize(fallback: OneShot.new, connections: nil)
+        ::ClientApiBuilder::HTTP2.require_http2_gem
+        @fallback = fallback
+        @connections = connections || ::ClientApiBuilder::HTTP2::ConnectionSet.new
+      end
+
+      # A transport over the same HTTP/2 connections with a different fallback
+      def with_fallback(fallback)
+        self.class.new(fallback: fallback, connections: connections)
+      end
+
+      def with_connection(uri, connection_options, &)
+        connection = uri.scheme == 'https' && connections.connection_for(uri, connection_options)
+        connection ? yield(connection) : fallback.with_connection(uri, connection_options, &)
+      end
+
+      # Closes the HTTP/2 connections and the fallback's
+      def close
+        connections.close
+        fallback.close
+      end
+    end
+  end
+end

data/lib/client_api_builder/transports/one_shot.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'net/http'
+
+module ClientApiBuilder
+  module Transports
+    # A new connection for every request, closed once the response is read. Nothing outlives
+    # a request, so it suits web servers and forking process managers. This is the default.
+    class OneShot
+      def with_connection(uri, connection_options, &)
+        Net::HTTP.start(uri.hostname, uri.port, connection_options, &)
+      end
+
+      # Nothing stays open between requests
+      def close; end
+    end
+  end
+end

data/lib/client_api_builder/transports/pooled.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ClientApiBuilder
+  module Transports
+    # Persistent connections shared by every thread, checked out of a pool per scheme, host,
+    # port and connection options for the length of one request. Takes the
+    # ConnectionPools::Settings options (max_connections, ttl, checkout_timeout, idle_timeout).
+    # A connection whose request raised is closed, and after a fork the child opens its own.
+    class Pooled
+      attr_reader :pool_set
+
+      def initialize(**settings)
+        @pool_set = ConnectionPools::PoolSet.new(ConnectionPools::Settings.new(**settings))
+      end
+
+      def settings
+        pool_set.settings
+      end
+
+      def with_connection(uri, connection_options, &)
+        pool_set.with_connection(uri, connection_options, &)
+      end
+
+      # Closes idle connections now and in-use ones when they're returned
+      def close
+        pool_set.close
+      end
+    end
+  end
+end

data/lib/client_api_builder/transports/registry.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module ClientApiBuilder
+  module Transports
+    # Which transport each client class uses. A class (or module) can have two kinds of entry:
+    # one registered with use, normally at boot for the environment, and one declared by its
+    # class body through ConnectionPools, ThreadConnections or HTTP2. A class uses the
+    # registered transport of the nearest class in its ancestry, else the declared one of the
+    # nearest, else the process default (OneShot unless use set another), so the environment's
+    # choice wins whichever loads first.
+    #
+    # Entries are held weakly by class, so anonymous client classes can still be collected.
+    class Registry
+      def initialize(default_factory: -> { OneShot.new })
+        @default_factory = default_factory
+        @mutex = Mutex.new
+        @default = nil
+        @registered = ObjectSpace::WeakKeyMap.new
+        @declared = ObjectSpace::WeakKeyMap.new
+        @transports = ObjectSpace::WeakMap.new
+      end
+
+      # Sends requests through transport: for every client, or for client_class and its
+      # subclasses (and the classes including it, for a module) when given
+      def use(transport, client_class = nil)
+        @mutex.synchronize do
+          client_class ? @registered[client_class] = transport : @default = transport
+          @transports[transport] = true
+        end
+      end
+
+      # The transport a client class's own body chose; use takes precedence over it
+      def declare(transport, client_class)
+        @mutex.synchronize do
+          @declared[client_class] = transport
+          @transports[transport] = true
+        end
+      end
+
+      # The transport registered or declared for the class or its nearest ancestor, or nil
+      def registered_for(client_class)
+        ancestors = client_class.ancestors
+        @mutex.synchronize { nearest(@registered, ancestors) || nearest(@declared, ancestors) }
+      end
+
+      def for_class(client_class)
+        registered_for(client_class) || default
+      end
+
+      def default
+        @mutex.synchronize { @default ||= @default_factory.call }
+      end
+
+      # Closes every transport registered or declared, and the default
+      def close_all
+        transports = @mutex.synchronize { [*@transports.keys, @default].compact.uniq }
+        transports.each(&:close)
+      end
+
+      # Forgets the transports set with use, and the default, closing nothing; declarations
+      # belong to class bodies and stay. Meant for specs.
+      def reset
+        @mutex.synchronize do
+          @registered = ObjectSpace::WeakKeyMap.new
+          @default = nil
+        end
+      end
+
+      private
+
+      def nearest(entries, ancestors)
+        ancestors.each do |ancestor|
+          transport = entries[ancestor]
+          return transport if transport
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/client_api_builder/transports/thread_local.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ClientApiBuilder
+  module Transports
+    # Persistent connections dedicated to each thread: one per scheme, host, port and
+    # connection options, opened on the thread's first request. Takes the
+    # ThreadConnections::Settings options (ttl, idle_timeout). Suits a fixed set of worker
+    # threads; with many short-lived threads, prefer Pooled. A connection whose request
+    # raised is closed, and after a fork the child opens its own.
+    class ThreadLocal
+      attr_reader :connection_set
+
+      def initialize(**settings)
+        @connection_set = ThreadConnections::ConnectionSet.new(ThreadConnections::Settings.new(**settings))
+      end
+
+      def settings
+        connection_set.settings
+      end
+
+      def with_connection(uri, connection_options, &)
+        connection_set.with_connection(uri, connection_options, &)
+      end
+
+      # Closes every thread's idle connections now and in-use ones when their request ends
+      def close
+        connection_set.close
+      end
+    end
+  end
+end

data/lib/client_api_builder/transports.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Purpose: objects that own connections and send requests, chosen per environment at boot
+# rather than baked into a client class:
+#
+#   ClientApiBuilder.use_transport(ClientApiBuilder::Transports::ThreadLocal.new)              # every client
+#   ClientApiBuilder.use_transport(ClientApiBuilder::Transports::Pooled.new, GitHubClient) # one class
+#
+# A transport answers with_connection(uri, connection_options) { |http| ... }, yielding
+# something that responds to request(net_request) { |response| } like a started Net::HTTP,
+# and close, which closes its connections.
+module ClientApiBuilder
+  module Transports
+    autoload :HTTP2, 'client_api_builder/transports/http2'
+    autoload :OneShot, 'client_api_builder/transports/one_shot'
+    autoload :Pooled, 'client_api_builder/transports/pooled'
+    autoload :Registry, 'client_api_builder/transports/registry'
+    autoload :ThreadLocal, 'client_api_builder/transports/thread_local'
+  end
+end

data/lib/client_api_builder/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: client-api-builder
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Doug Youch
@@ -43,6 +43,7 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- UPGRADING.md
 - lib/client-api-builder.rb
 - lib/client_api_builder/active_support_log_subscriber.rb
 - lib/client_api_builder/active_support_notifications.rb
@@ -51,6 +52,7 @@ files:
 - lib/client_api_builder/connection_pools/pool.rb
 - lib/client_api_builder/connection_pools/pool_set.rb
 - lib/client_api_builder/connection_pools/settings.rb
+- lib/client_api_builder/declared_transport.rb
 - lib/client_api_builder/http2.rb
 - lib/client_api_builder/http2/connection.rb
 - lib/client_api_builder/http2/connection_set.rb
@@ -68,6 +70,12 @@ files:
 - lib/client_api_builder/thread_connections.rb
 - lib/client_api_builder/thread_connections/connection_set.rb
 - lib/client_api_builder/thread_connections/settings.rb
+- lib/client_api_builder/transports.rb
+- lib/client_api_builder/transports/http2.rb
+- lib/client_api_builder/transports/one_shot.rb
+- lib/client_api_builder/transports/pooled.rb
+- lib/client_api_builder/transports/registry.rb
+- lib/client_api_builder/transports/thread_local.rb
 - lib/client_api_builder/version.rb
 homepage: https://github.com/dougyouch/client-api-builder
 licenses: