xero-kiwi 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e52bfcc3939a00a86a7bc26b931aa6e7553b2479fb3b2b36c3215daccad754de
-  data.tar.gz: 0c13e42901c11b857c0476dea1c898a46a12404de66231df0b82cb9c899d9a71
+  metadata.gz: 5aeae0acf1024528b094ffc690323179bd336c9817bef6a897258b5304f66844
+  data.tar.gz: 2ab0071a933a39e93a10ef7ed7658b354e2043cc753441c65491443fff5e22a2
 SHA512:
-  metadata.gz: 1d9b16a8564e87c0935dfd301ec480fa856c7374f70ca939eef877d4e108f8e54a9ef38a1454451d848de1d6c697addb561f3bf81e3405414dbb0567c9ff77d2
-  data.tar.gz: 169f97330de612d1c940bbd0ee0d671c5d5ae7cc4284f5cc42af9b5d59cd37c2e5a68a81113d7e56a66c6e03a5a649bac779783d9b055db143f04684cd6d954c
+  metadata.gz: 4b4c8cdd72c20abdd5d377edbb125b53466d6ebb907a8f2949fec962d20d432226c39e21d23c3053f39bdf7f935678ff2a10cc0240db8f32eb07f5d8d7133ff5
+  data.tar.gz: 7b19c8922f563d1a51b599f6379a92d289a19c43b5580282a0cd348561cb1f8f0786e245e0490fbe3ad5cf31c462f49e37cf37cc9996f91c003e0721d80c6e55

data/CHANGELOG.md

@@ -1,5 +1,36 @@
 ## [Unreleased]
 
+## [0.12.0] - 2026-10-19
+
+### Breaking
+
+- **Timeouts and failed connections now raise `XeroKiwi::ConnectionError`.** They used to escape as `Faraday::TimeoutError`, `Faraday::ConnectionFailed` or `Faraday::SSLError`. None of these is a `XeroKiwi::Error`, so `rescue XeroKiwi::Error` missed them. All three are now wrapped in `XeroKiwi::ConnectionError < XeroKiwi::Error`, with the original as `cause`. The client's retry middleware still sees and retries Faraday's own errors; the wrap only happens once it gives up.
+
+  Upgrading: a `rescue` of any of those three Faraday errors around a kiwi call no longer matches. Rescue `XeroKiwi::ConnectionError`, and read `e.cause` if you need to tell them apart.
+
+  `XeroKiwi::OAuth::IDToken.verify` without `jwks:` is unchanged: it still raises `IDTokenError` for any failure to fetch the JWKS.
+
+### Changed
+
+- **Every HTTP call now has a timeout.** There were none, so each call used Net::HTTP's defaults of 60 seconds to connect, 60 to read and 60 to write. A consumer runs the code exchange and the ID token check inside a web request, and retries the exchange 3 times, so a slow identity.xero.com held a server thread for minutes. The defaults are now:
+
+  | Host | Used by | Connect | Read | Write |
+  |------|---------|---------|------|-------|
+  | identity.xero.com | `OAuth`, `TokenRefresher`, `IDToken.verify` | 5s | 10s | 10s |
+  | api.xero.com | `Client` | 5s | 60s | 10s |
+
+  The API read stays at 60 seconds because a page of 1,000 invoices can be slow. The client retries a timeout up to 4 times, so one hung API request can still take more than 5 minutes to fail. Lower `timeout:` and `retry_options: { max: ... }` together where that matters.
+
+  `IDToken.verify` without `jwks:` also stops Net::HTTP retrying a timed-out JWKS fetch, which doubled its wait.
+
+### Added
+
+- **`open_timeout:`, `timeout:` and `write_timeout:`**, in seconds, on `XeroKiwi::OAuth.new`, `XeroKiwi::TokenRefresher.new`, `XeroKiwi::OAuth::IDToken.verify` and `XeroKiwi::Client.new`. `timeout:` is the read timeout, under the name Faraday gives it. The refresh and revoke calls a `Client` makes use the identity defaults, not the client's own values.
+
+### Documentation
+
+- The errors doc said everything kiwi raises is a `XeroKiwi::Error`. One Faraday error still escapes: `Faraday::ParsingError`, when a response says it is JSON but does not parse. The doc now says so.
+
 ## [0.11.0] - 2026-10-08
 
 ### Added

data/docs/client.md

@@ -44,6 +44,9 @@ you. See [Tokens](tokens.md) for the full refresh story.
 | `throttle:` | Limiter | No | `XeroKiwi.default_throttle`, else none | Proactive per-tenant rate limiting. See [Throttling](throttling.md). |
 | `page_size:` | `Integer` | No | `nil` (Xero's own default of 100) | Default `pageSize` for every list call. Per-call `page_size:` overrides it. See [Querying](querying.md). |
 | `retain_raw:` | `Boolean` | No | `false` | Keep Xero's untouched response hash on each resource, readable via `#raw`. See below. |
+| `open_timeout:` | `Numeric` | No | `5` | Seconds to wait for a connection to api.xero.com. See [Timeouts](#timeouts). |
+| `timeout:` | `Numeric` | No | `60` | Seconds to wait for each read of the response. Longer than the identity default, because a page of 1,000 invoices can be slow. |
+| `write_timeout:` | `Numeric` | No | `10` | Seconds to wait for each write of the request. |
 
 ### `retain_raw:` and `#raw`
 
@@ -371,6 +374,35 @@ client = XeroKiwi::Client.new(
 See [retries and rate limits](retries-and-rate-limits.md) for the full
 configuration reference and which keys you can override.
 
+## Timeouts
+
+A request that hits `open_timeout:`, `timeout:` or `write_timeout:` is
+retried like any other transport failure. Once the retries are exhausted, the
+client raises `XeroKiwi::ConnectionError`, with the last
+`Faraday::TimeoutError` or `Faraday::ConnectionFailed` as its `cause`. A
+failed TLS handshake is not retried: it raises `XeroKiwi::ConnectionError` at
+once, with `Faraday::SSLError` as its `cause`.
+
+```ruby
+client = XeroKiwi::Client.new(
+  access_token: "...",
+  open_timeout: 2,
+  timeout:      30
+)
+```
+
+**Retries multiply the wait.** With the default `max: 4`, one hung request
+can wait for 5 reads of 60 seconds, plus the backoff between them: more than
+5 minutes. Where that matters, such as inside a web request, lower `timeout:`
+and `retry_options: { max: ... }` together.
+
+`timeout:` applies to each read from the socket, not to the whole request, so
+a response that keeps arriving slowly can take longer in total.
+
+**Refresh and revoke use the identity timeouts.** Those calls go to
+identity.xero.com, so the client's own values do not apply to them. See
+[Tokens](tokens.md#timeouts).
+
 ## Thread safety
 
 A single client can safely be shared across threads. The internals are

data/docs/errors.md

@@ -16,6 +16,7 @@ StandardError
    │  ├─ XeroKiwi::ClientError           (other 4xx)
    │  ├─ XeroKiwi::ServerError           (5xx)
    │  └─ XeroKiwi::RateLimitError        (429, with retry_after + problem)
+   ├─ XeroKiwi::ConnectionError          (timeout or failed connection)
    ├─ XeroKiwi::OAuth::StateMismatchError  (CSRF check failed)
    └─ XeroKiwi::OAuth::IDTokenError        (ID token JWT verification failed)
 ```
@@ -23,12 +24,16 @@ StandardError
 A few things worth noticing about the shape:
 
 - **Everything Xero Kiwi raises** descends from `XeroKiwi::Error`. If you only want
-  one rescue clause for "the Xero integration broke," catch this.
+  one rescue clause for "the Xero integration broke," catch this. The one
+  exception is a response that says it is JSON but does not parse, which
+  raises Faraday's own `Faraday::ParsingError`.
 - **HTTP responses** descend from `XeroKiwi::APIError`, which carries `status`
   and `body` attributes you can inspect.
 - **OAuth-specific errors** for state mismatch and ID token verification
   descend from `XeroKiwi::Error` directly (not `APIError`) because they don't
   come from an HTTP response — they're local validation failures.
+- **`XeroKiwi::ConnectionError`** descends from `XeroKiwi::Error` directly
+  too. No response arrived, so there is no status or body to carry.
 - **`XeroKiwi::TokenRefreshError`** and **`XeroKiwi::OAuth::CodeExchangeError`** are
   both `AuthenticationError` subclasses, because the practical recovery is
   the same as for any 401: the user needs to re-authorise.
@@ -136,6 +141,30 @@ Extra attributes beyond `APIError`:
 Sidekiq job can re-enqueue itself with that delay rather than hammering
 Xero.
 
+### `XeroKiwi::ConnectionError`
+
+Raised when a request hits its `open_timeout:`, `timeout:` or
+`write_timeout:`, or when the connection fails (refused, reset, the host
+does not resolve, or the TLS handshake fails). `XeroKiwi::Client` raises it
+only after its retries are exhausted, except for a TLS failure, which it
+does not retry. Identity calls (code exchange, client credentials, refresh,
+revoke and the JWKS fetch) are not retried.
+
+The original `Faraday::TimeoutError`, `Faraday::ConnectionFailed` or
+`Faraday::SSLError` is the error's `cause`:
+
+```ruby
+rescue XeroKiwi::ConnectionError => e
+  e.cause # => #<Faraday::TimeoutError: Net::ReadTimeout ...>
+```
+
+`XeroKiwi::OAuth::IDToken.verify` without `jwks:` is the one exception: it
+raises `XeroKiwi::OAuth::IDTokenError` for any failure to fetch the JWKS,
+timeouts included.
+
+See [Client — Timeouts](client.md#timeouts) and [OAuth — Timeouts](oauth.md#timeouts)
+for the limits and their defaults.
+
 ### `XeroKiwi::OAuth::StateMismatchError`
 
 Raised by `XeroKiwi::OAuth.verify_state!` when the `state` parameter Xero
@@ -156,7 +185,9 @@ the ID token JWT can't be verified. Causes:
 - Wrong audience.
 - Token expired.
 - Nonce mismatch (when nonce verification was requested).
-- Network failure fetching JWKS.
+- Network failure fetching JWKS, through `IDToken.verify` without `jwks:`.
+  Through `oauth.verify_id_token`, a network failure raises
+  `XeroKiwi::ConnectionError` instead.
 
 The error message has a brief description of which check failed (e.g.
 `"ID token verification failed: Signature verification failed"`,
@@ -223,10 +254,12 @@ rescue XeroKiwi::OAuth::CodeExchangeError
   redirect_to root_path, alert: "Could not complete Xero authorisation"
 rescue XeroKiwi::OAuth::IDTokenError
   redirect_to root_path, alert: "Could not verify Xero identity"
+rescue XeroKiwi::ConnectionError
+  redirect_to root_path, alert: "Xero did not respond. Please try again."
 end
 ```
 
-Three separate rescue clauses give you three different user-facing
+Four separate rescue clauses give you four different user-facing
 messages, which is usually what you want for an OAuth callback — different
 failures imply different user actions.
 

data/docs/oauth.md

@@ -40,6 +40,9 @@ oauth = XeroKiwi::OAuth.new(
 | `client_secret:` | `String` | Yes | — | Your Xero app's client secret |
 | `redirect_uri:` | `String` | Conditional | `nil` | Required for `authorization_url` and `exchange_code`. **Optional** if you only use this instance for `revoke_token` or `verify_id_token`. |
 | `adapter:` | Faraday adapter | No | `Faraday.default_adapter` | The HTTP adapter for token-endpoint and JWKS calls |
+| `open_timeout:` | `Numeric` | No | `5` | Seconds to wait for a connection to identity.xero.com. See [Timeouts](#timeouts). |
+| `timeout:` | `Numeric` | No | `10` | Seconds to wait for each read of the response. |
+| `write_timeout:` | `Numeric` | No | `10` | Seconds to wait for each write of the request. |
 
 ### Why `redirect_uri:` is optional
 
@@ -58,6 +61,32 @@ fake redirect URL. Pass `redirect_uri: nil` (or just omit it). If you then
 *do* call `authorization_url` or `exchange_code`, you'll get a clear
 `ArgumentError` at call time rather than a confusing 400 from Xero.
 
+### Timeouts
+
+Every call the instance makes — `exchange_code`, `client_credentials_token`,
+`revoke_token` and the JWKS fetch behind `verify_id_token` — gives up after
+these limits and raises `XeroKiwi::ConnectionError`. Faraday's
+`Faraday::TimeoutError` or `Faraday::ConnectionFailed` is its `cause`.
+
+Without them, each call would use Net::HTTP's defaults of 60 seconds to
+connect, 60 to read and 60 to write. The code exchange and the ID token check
+usually run inside a web request, so a slow identity.xero.com would hold that
+request, and its server thread, for a minute or more.
+
+```ruby
+oauth = XeroKiwi::OAuth.new(
+  client_id:     ENV.fetch("XERO_CLIENT_ID"),
+  client_secret: ENV.fetch("XERO_CLIENT_SECRET"),
+  redirect_uri:  "https://app.example.com/xero/callback",
+  open_timeout:  2,
+  timeout:       5
+)
+```
+
+Identity calls are not retried, so the limits are close to the whole wait.
+`timeout:` applies to each read from the socket, so a response that keeps
+arriving slowly can take longer in total.
+
 ## Step 1: building the authorisation URL
 
 ```ruby
@@ -263,7 +292,7 @@ id_token, and scope. See [Tokens](tokens.md) for the full reference.
 | Wrong `redirect_uri` (must match the one used at authorise time) | `XeroKiwi::OAuth::CodeExchangeError` |
 | PKCE verifier mismatch | `XeroKiwi::OAuth::CodeExchangeError` |
 | Wrong client credentials | `XeroKiwi::OAuth::CodeExchangeError` |
-| Network error | bubbles up as a `Faraday::ConnectionFailed` |
+| Timeout, or no connection to Xero | `XeroKiwi::ConnectionError`, with Faraday's error as its `cause` |
 
 `XeroKiwi::OAuth::CodeExchangeError` inherits from `XeroKiwi::AuthenticationError`,
 so you can catch the broader class if you don't care about the distinction.
@@ -312,6 +341,15 @@ The standalone class method **fetches JWKS fresh on every call** via
 `Net::HTTP`. Fine for one-off use, wasteful in a hot loop. If you find
 yourself calling it repeatedly, switch to the OAuth instance method.
 
+It takes the same `open_timeout:`, `timeout:` and `write_timeout:` options
+as `OAuth.new`, with the same defaults. Unlike the instance method, it raises
+`XeroKiwi::OAuth::IDTokenError` when the fetch times out, as it does for any
+other failure to fetch the JWKS.
+
+```ruby
+XeroKiwi::OAuth::IDToken.verify(id_token, client_id: "...", timeout: 5)
+```
+
 You can also inject your own JWKS provider:
 
 ```ruby
@@ -443,6 +481,7 @@ auto-refresh paths stay out of the way.
 |-------|-----------|
 | Wrong `client_id` / `client_secret` | `XeroKiwi::OAuth::ClientCredentialsError` |
 | Scope the app isn't authorised for | `XeroKiwi::OAuth::ClientCredentialsError` |
+| Timeout, or no connection to Xero | `XeroKiwi::ConnectionError`, with Faraday's error as its `cause` |
 
 `ClientCredentialsError` subclasses `XeroKiwi::AuthenticationError`, so an
 existing `rescue XeroKiwi::AuthenticationError` still catches it. There is

data/docs/retries-and-rate-limits.md

@@ -175,10 +175,12 @@ code, catch `XeroKiwi::ServerError` and handle it explicitly.
 |----------|-----------------|
 | All retries returned 429 | `XeroKiwi::RateLimitError` (with `retry_after` and `problem` attributes) |
 | All retries returned 502/503/504 | `XeroKiwi::ServerError` |
-| All retries failed at the transport level | The underlying `Faraday::ConnectionFailed` / `Faraday::TimeoutError` |
+| All retries failed at the transport level | `XeroKiwi::ConnectionError`, with the last `Faraday::ConnectionFailed` / `Faraday::TimeoutError` as its `cause` |
 
 The retried request count includes the original attempt, so `max: 4` means
-**up to 5 total HTTP requests** before giving up.
+**up to 5 total HTTP requests** before giving up. Each of them can wait the
+full read timeout, so a hung endpoint takes up to 5 times as long to fail.
+See [Client — Timeouts](client.md#timeouts).
 
 ## Customising the retry policy
 

data/docs/tokens.md

@@ -145,6 +145,34 @@ else
 end
 ```
 
+### Timeouts
+
+A refresh goes to identity.xero.com, not api.xero.com, so it uses the
+identity timeouts: 5 seconds to connect, 10 to read and 10 to write. The
+client's own `timeout:` does not apply to it. When identity.xero.com does not
+answer in time, the refresh raises `XeroKiwi::ConnectionError` rather than
+holding the thread for Net::HTTP's default of 60 seconds.
+
+`XeroKiwi::TokenRefresher` takes the same options as `XeroKiwi::OAuth.new`
+if you use it directly:
+
+```ruby
+refresher = XeroKiwi::TokenRefresher.new(
+  client_id:     ENV.fetch("XERO_CLIENT_ID"),
+  client_secret: ENV.fetch("XERO_CLIENT_SECRET"),
+  open_timeout:  2,
+  timeout:       5
+)
+
+refresher.refresh(refresh_token: stored_refresh_token)
+```
+
+| Option | Default | Purpose |
+|--------|---------|---------|
+| `open_timeout:` | `5` | Seconds to wait for a connection. |
+| `timeout:` | `10` | Seconds to wait for each read of the response. |
+| `write_timeout:` | `10` | Seconds to wait for each write of the request. |
+
 ## The `on_token_refresh` callback
 
 This is the most important integration point in the gem. Every time the
@@ -275,7 +303,9 @@ This:
    current refresh token.
 2. Returns `true` on success.
 3. Raises `XeroKiwi::TokenRefreshError` if the client has no refresh capability,
-   or `XeroKiwi::AuthenticationError` if Xero rejects the revoke.
+   `XeroKiwi::AuthenticationError` if Xero rejects the revoke, or
+   `XeroKiwi::ConnectionError` if identity.xero.com does not answer within the
+   [identity timeouts](#timeouts).
 
 After revocation, **treat the client as dead.** Subsequent API calls will
 401, and reactive refresh will fail because the refresh token is gone too.

data/lib/xero_kiwi/client.rb

@@ -52,6 +52,10 @@ module XeroKiwi
       ]
     }.freeze
 
+    DEFAULT_OPEN_TIMEOUT  = 5
+    DEFAULT_READ_TIMEOUT  = 60
+    DEFAULT_WRITE_TIMEOUT = 10
+
     attr_reader :token
 
     def initialize(
@@ -66,7 +70,10 @@ module XeroKiwi
       retry_options: {},
       throttle: nil,
       page_size: nil,
-      retain_raw: false
+      retain_raw: false,
+      open_timeout: DEFAULT_OPEN_TIMEOUT,
+      timeout: DEFAULT_READ_TIMEOUT,
+      write_timeout: DEFAULT_WRITE_TIMEOUT
     )
       @token            = Token.new(access_token: access_token, refresh_token: refresh_token, expires_at: expires_at)
       @client_id        = client_id
@@ -75,6 +82,7 @@ module XeroKiwi
       @adapter          = adapter
       @user_agent       = user_agent
       @retry_options    = DEFAULT_RETRY_OPTIONS.merge(retry_options)
+      @timeouts         = { open_timeout: open_timeout, timeout: timeout, write_timeout: write_timeout }
       @throttle         = throttle || XeroKiwi.default_throttle || Throttle::NullLimiter.new
       @page_size        = page_size
       @retain_raw       = retain_raw
@@ -882,8 +890,9 @@ module XeroKiwi
     # Middleware order matters. Outbound runs top-to-bottom; inbound runs in
     # reverse. We want:
     #
-    #   1. ResponseHandler (outermost) — converts the FINAL response status into
-    #      a XeroKiwi exception, *after* retries have been exhausted.
+    #   1. ResponseHandler (outermost) — converts the FINAL response status, or
+    #      the final transport failure, into a XeroKiwi exception, *after*
+    #      retries have been exhausted.
     #   2. Retry — retries on 429/503 (respecting Retry-After) and on transport
     #      exceptions.
     #   3. RateLimitCapture — records Xero's quota headers. Below Retry so
@@ -899,7 +908,7 @@ module XeroKiwi
     # gets retried by Faraday before we ever raise RateLimitError, and the
     # exception only fires once we've truly given up.
     def build_http
-      Faraday.new(url: BASE_URL) do |f|
+      Faraday.new(url: BASE_URL, request: @timeouts) do |f|
         f.use ResponseHandler
         f.request :retry, @retry_options
         f.use RateLimitCapture, @rate_limits
@@ -985,10 +994,17 @@ module XeroKiwi
       end
     end
 
-    # Faraday middleware that maps non-2xx responses onto our exception
-    # hierarchy. Lives outside the retry middleware so it only fires on the
-    # final response.
+    # Faraday middleware that maps non-2xx responses and transport failures
+    # onto our exception hierarchy. Lives outside the retry middleware so it
+    # only fires on the final response, and so the retry middleware still
+    # sees Faraday's own errors.
     class ResponseHandler < Faraday::Middleware
+      def call(env)
+        super
+      rescue Faraday::TimeoutError, Faraday::ConnectionFailed, Faraday::SSLError => e
+        raise ConnectionError, "Request to #{env.url.host} failed: #{e.message}"
+      end
+
       def on_complete(env)
         # 304 Not Modified is a valid response to a conditional GET
         # (If-Modified-Since). Let it through so the list helper can

data/lib/xero_kiwi/errors.rb

@@ -16,6 +16,7 @@ module XeroKiwi
   class AuthenticationError < APIError; end
   class ClientError < APIError; end
   class ServerError < APIError; end
+  class ConnectionError < Error; end
 
   # Raised when refreshing the OAuth2 token fails — typically because the
   # refresh token has expired (60 days) or has already been rotated. Callers

data/lib/xero_kiwi/identity.rb

@@ -17,15 +17,26 @@ module XeroKiwi
     JWKS_PATH        = "/.well-known/openid-configuration/jwks"
     JWKS_URL         = "#{URL}#{JWKS_PATH}".freeze
 
+    DEFAULT_OPEN_TIMEOUT  = 5
+    DEFAULT_READ_TIMEOUT  = 10
+    DEFAULT_WRITE_TIMEOUT = 10
+
     module_function
 
     # Builds a Faraday connection configured for the Xero identity host:
-    # JSON response parsing and our exception mapping. No retry middleware
-    # — token endpoints aren't subject to the same rate limits as the API,
-    # and retrying a failed token call usually masks a real configuration
-    # problem instead of fixing a transient one.
-    def build_http(adapter: nil)
-      Faraday.new(url: URL) do |f|
+    # timeouts, JSON response parsing and our exception mapping. No retry
+    # middleware — token endpoints aren't subject to the same rate limits as
+    # the API, and retrying a failed token call usually masks a real
+    # configuration problem instead of fixing a transient one.
+    def build_http(
+      adapter: nil,
+      open_timeout: DEFAULT_OPEN_TIMEOUT,
+      timeout: DEFAULT_READ_TIMEOUT,
+      write_timeout: DEFAULT_WRITE_TIMEOUT
+    )
+      request = { open_timeout: open_timeout, timeout: timeout, write_timeout: write_timeout }
+
+      Faraday.new(url: URL, request: request) do |f|
         f.use Client::ResponseHandler
         f.response :json, content_type: /\bjson/
         f.adapter(adapter || Faraday.default_adapter)

data/lib/xero_kiwi/oauth/id_token.rb

@@ -34,20 +34,29 @@ module XeroKiwi
 
       attr_reader :claims
 
-      def self.verify(id_token, client_id:, nonce: nil, jwks: nil)
+      def self.verify(
+        id_token,
+        client_id:,
+        nonce: nil,
+        jwks: nil,
+        open_timeout: Identity::DEFAULT_OPEN_TIMEOUT,
+        timeout: Identity::DEFAULT_READ_TIMEOUT,
+        write_timeout: Identity::DEFAULT_WRITE_TIMEOUT
+      )
         raise ArgumentError, "id_token is required"  if id_token.nil?  || id_token.empty?
         raise ArgumentError, "client_id is required" if client_id.nil? || client_id.empty?
 
-        decoded = decode(id_token, client_id, jwks)
-        claims  = decoded.first
+        timeouts = { open_timeout: open_timeout, timeout: timeout, write_timeout: write_timeout }
+        decoded  = decode(id_token, client_id: client_id, jwks: jwks, timeouts: timeouts)
+        claims   = decoded.first
         verify_nonce!(claims, nonce) if nonce
         new(claims)
       rescue JWT::DecodeError => e
         raise IDTokenError, "ID token verification failed: #{e.message}"
       end
 
-      def self.decode(id_token, client_id, jwks)
-        jwks_proc = jwks || method(:fetch_jwks_directly)
+      def self.decode(id_token, client_id:, jwks:, timeouts:)
+        jwks_proc = jwks || -> { fetch_jwks_directly(**timeouts) }
         JWT.decode(
           id_token,
           nil,
@@ -66,8 +75,18 @@ module XeroKiwi
       # injected. Net::HTTP keeps this dependency-free at the call site;
       # OAuth#verify_id_token uses an instance-cached Faraday fetcher
       # instead.
-      def self.fetch_jwks_directly
-        body = Net::HTTP.get(URI(Identity::JWKS_URL))
+      def self.fetch_jwks_directly(open_timeout:, timeout:, write_timeout:)
+        uri     = URI(Identity::JWKS_URL)
+        options = {
+          use_ssl:       uri.scheme == "https",
+          open_timeout:  open_timeout,
+          read_timeout:  timeout,
+          write_timeout: write_timeout,
+          # Net::HTTP retries a timed-out GET once, which doubles the wait.
+          max_retries:   0
+        }
+
+        body = Net::HTTP.start(uri.host, uri.port, **options) { |http| http.get(uri.request_uri).body }
         JSON.parse(body).fetch("keys")
       rescue StandardError => e
         raise IDTokenError, "failed to fetch JWKS: #{e.message}"

data/lib/xero_kiwi/oauth.rb

@@ -101,11 +101,20 @@ module XeroKiwi
     # (`authorization_url` and `exchange_code`) but not for `revoke_token`
     # or `verify_id_token`. It's optional at construction time so callers
     # who only need the latter operations don't have to invent a fake URL.
-    def initialize(client_id:, client_secret:, redirect_uri: nil, adapter: nil)
+    def initialize(
+      client_id:,
+      client_secret:,
+      redirect_uri: nil,
+      adapter: nil,
+      open_timeout: Identity::DEFAULT_OPEN_TIMEOUT,
+      timeout: Identity::DEFAULT_READ_TIMEOUT,
+      write_timeout: Identity::DEFAULT_WRITE_TIMEOUT
+    )
       @client_id       = client_id
       @client_secret   = client_secret
       @redirect_uri    = redirect_uri
       @adapter         = adapter
+      @timeouts        = { open_timeout: open_timeout, timeout: timeout, write_timeout: write_timeout }
       @jwks_mutex      = Mutex.new
       @jwks_cache      = nil
       @jwks_fetched_at = nil
@@ -281,7 +290,7 @@ module XeroKiwi
     end
 
     def http
-      @_http ||= Identity.build_http(adapter: @adapter)
+      @_http ||= Identity.build_http(adapter: @adapter, **@timeouts)
     end
   end
 end

data/lib/xero_kiwi/token_refresher.rb

@@ -13,10 +13,18 @@ module XeroKiwi
   #
   # See: https://developer.xero.com/documentation/guides/oauth2/auth-flow#refreshing-access-and-refresh-tokens
   class TokenRefresher
-    def initialize(client_id:, client_secret:, adapter: nil)
+    def initialize(
+      client_id:,
+      client_secret:,
+      adapter: nil,
+      open_timeout: Identity::DEFAULT_OPEN_TIMEOUT,
+      timeout: Identity::DEFAULT_READ_TIMEOUT,
+      write_timeout: Identity::DEFAULT_WRITE_TIMEOUT
+    )
       @client_id     = client_id
       @client_secret = client_secret
       @adapter       = adapter
+      @timeouts      = { open_timeout: open_timeout, timeout: timeout, write_timeout: write_timeout }
     end
 
     # Performs the refresh round-trip and returns a fresh XeroKiwi::Token. Raises
@@ -47,7 +55,7 @@ module XeroKiwi
     end
 
     def http
-      @_http ||= Identity.build_http(adapter: @adapter)
+      @_http ||= Identity.build_http(adapter: @adapter, **@timeouts)
     end
   end
 end

data/lib/xero_kiwi/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module XeroKiwi
-  VERSION = "0.11.0"
+  VERSION = "0.12.0"
 end

data/llms-full.txt

@@ -413,6 +413,9 @@ you. See [Tokens](tokens.md) for the full refresh story.
 | `throttle:` | Limiter | No | `XeroKiwi.default_throttle`, else none | Proactive per-tenant rate limiting. See [Throttling](throttling.md). |
 | `page_size:` | `Integer` | No | `nil` (Xero's own default of 100) | Default `pageSize` for every list call. Per-call `page_size:` overrides it. See [Querying](querying.md). |
 | `retain_raw:` | `Boolean` | No | `false` | Keep Xero's untouched response hash on each resource, readable via `#raw`. See below. |
+| `open_timeout:` | `Numeric` | No | `5` | Seconds to wait for a connection to api.xero.com. See [Timeouts](#timeouts). |
+| `timeout:` | `Numeric` | No | `60` | Seconds to wait for each read of the response. Longer than the identity default, because a page of 1,000 invoices can be slow. |
+| `write_timeout:` | `Numeric` | No | `10` | Seconds to wait for each write of the request. |
 
 ### `retain_raw:` and `#raw`
 
@@ -740,6 +743,35 @@ client = XeroKiwi::Client.new(
 See [retries and rate limits](retries-and-rate-limits.md) for the full
 configuration reference and which keys you can override.
 
+## Timeouts
+
+A request that hits `open_timeout:`, `timeout:` or `write_timeout:` is
+retried like any other transport failure. Once the retries are exhausted, the
+client raises `XeroKiwi::ConnectionError`, with the last
+`Faraday::TimeoutError` or `Faraday::ConnectionFailed` as its `cause`. A
+failed TLS handshake is not retried: it raises `XeroKiwi::ConnectionError` at
+once, with `Faraday::SSLError` as its `cause`.
+
+```ruby
+client = XeroKiwi::Client.new(
+  access_token: "...",
+  open_timeout: 2,
+  timeout:      30
+)
+```
+
+**Retries multiply the wait.** With the default `max: 4`, one hung request
+can wait for 5 reads of 60 seconds, plus the backoff between them: more than
+5 minutes. Where that matters, such as inside a web request, lower `timeout:`
+and `retry_options: { max: ... }` together.
+
+`timeout:` applies to each read from the socket, not to the whole request, so
+a response that keeps arriving slowly can take longer in total.
+
+**Refresh and revoke use the identity timeouts.** Those calls go to
+identity.xero.com, so the client's own values do not apply to them. See
+[Tokens](tokens.md#timeouts).
+
 ## Thread safety
 
 A single client can safely be shared across threads. The internals are
@@ -821,6 +853,9 @@ oauth = XeroKiwi::OAuth.new(
 | `client_secret:` | `String` | Yes | — | Your Xero app's client secret |
 | `redirect_uri:` | `String` | Conditional | `nil` | Required for `authorization_url` and `exchange_code`. **Optional** if you only use this instance for `revoke_token` or `verify_id_token`. |
 | `adapter:` | Faraday adapter | No | `Faraday.default_adapter` | The HTTP adapter for token-endpoint and JWKS calls |
+| `open_timeout:` | `Numeric` | No | `5` | Seconds to wait for a connection to identity.xero.com. See [Timeouts](#timeouts). |
+| `timeout:` | `Numeric` | No | `10` | Seconds to wait for each read of the response. |
+| `write_timeout:` | `Numeric` | No | `10` | Seconds to wait for each write of the request. |
 
 ### Why `redirect_uri:` is optional
 
@@ -839,6 +874,32 @@ fake redirect URL. Pass `redirect_uri: nil` (or just omit it). If you then
 *do* call `authorization_url` or `exchange_code`, you'll get a clear
 `ArgumentError` at call time rather than a confusing 400 from Xero.
 
+### Timeouts
+
+Every call the instance makes — `exchange_code`, `client_credentials_token`,
+`revoke_token` and the JWKS fetch behind `verify_id_token` — gives up after
+these limits and raises `XeroKiwi::ConnectionError`. Faraday's
+`Faraday::TimeoutError` or `Faraday::ConnectionFailed` is its `cause`.
+
+Without them, each call would use Net::HTTP's defaults of 60 seconds to
+connect, 60 to read and 60 to write. The code exchange and the ID token check
+usually run inside a web request, so a slow identity.xero.com would hold that
+request, and its server thread, for a minute or more.
+
+```ruby
+oauth = XeroKiwi::OAuth.new(
+  client_id:     ENV.fetch("XERO_CLIENT_ID"),
+  client_secret: ENV.fetch("XERO_CLIENT_SECRET"),
+  redirect_uri:  "https://app.example.com/xero/callback",
+  open_timeout:  2,
+  timeout:       5
+)
+```
+
+Identity calls are not retried, so the limits are close to the whole wait.
+`timeout:` applies to each read from the socket, so a response that keeps
+arriving slowly can take longer in total.
+
 ## Step 1: building the authorisation URL
 
 ```ruby
@@ -1044,7 +1105,7 @@ id_token, and scope. See [Tokens](tokens.md) for the full reference.
 | Wrong `redirect_uri` (must match the one used at authorise time) | `XeroKiwi::OAuth::CodeExchangeError` |
 | PKCE verifier mismatch | `XeroKiwi::OAuth::CodeExchangeError` |
 | Wrong client credentials | `XeroKiwi::OAuth::CodeExchangeError` |
-| Network error | bubbles up as a `Faraday::ConnectionFailed` |
+| Timeout, or no connection to Xero | `XeroKiwi::ConnectionError`, with Faraday's error as its `cause` |
 
 `XeroKiwi::OAuth::CodeExchangeError` inherits from `XeroKiwi::AuthenticationError`,
 so you can catch the broader class if you don't care about the distinction.
@@ -1093,6 +1154,15 @@ The standalone class method **fetches JWKS fresh on every call** via
 `Net::HTTP`. Fine for one-off use, wasteful in a hot loop. If you find
 yourself calling it repeatedly, switch to the OAuth instance method.
 
+It takes the same `open_timeout:`, `timeout:` and `write_timeout:` options
+as `OAuth.new`, with the same defaults. Unlike the instance method, it raises
+`XeroKiwi::OAuth::IDTokenError` when the fetch times out, as it does for any
+other failure to fetch the JWKS.
+
+```ruby
+XeroKiwi::OAuth::IDToken.verify(id_token, client_id: "...", timeout: 5)
+```
+
 You can also inject your own JWKS provider:
 
 ```ruby
@@ -1224,6 +1294,7 @@ auto-refresh paths stay out of the way.
 |-------|-----------|
 | Wrong `client_id` / `client_secret` | `XeroKiwi::OAuth::ClientCredentialsError` |
 | Scope the app isn't authorised for | `XeroKiwi::OAuth::ClientCredentialsError` |
+| Timeout, or no connection to Xero | `XeroKiwi::ConnectionError`, with Faraday's error as its `cause` |
 
 `ClientCredentialsError` subclasses `XeroKiwi::AuthenticationError`, so an
 existing `rescue XeroKiwi::AuthenticationError` still catches it. There is
@@ -1538,6 +1609,34 @@ else
 end
 ```
 
+### Timeouts
+
+A refresh goes to identity.xero.com, not api.xero.com, so it uses the
+identity timeouts: 5 seconds to connect, 10 to read and 10 to write. The
+client's own `timeout:` does not apply to it. When identity.xero.com does not
+answer in time, the refresh raises `XeroKiwi::ConnectionError` rather than
+holding the thread for Net::HTTP's default of 60 seconds.
+
+`XeroKiwi::TokenRefresher` takes the same options as `XeroKiwi::OAuth.new`
+if you use it directly:
+
+```ruby
+refresher = XeroKiwi::TokenRefresher.new(
+  client_id:     ENV.fetch("XERO_CLIENT_ID"),
+  client_secret: ENV.fetch("XERO_CLIENT_SECRET"),
+  open_timeout:  2,
+  timeout:       5
+)
+
+refresher.refresh(refresh_token: stored_refresh_token)
+```
+
+| Option | Default | Purpose |
+|--------|---------|---------|
+| `open_timeout:` | `5` | Seconds to wait for a connection. |
+| `timeout:` | `10` | Seconds to wait for each read of the response. |
+| `write_timeout:` | `10` | Seconds to wait for each write of the request. |
+
 ## The `on_token_refresh` callback
 
 This is the most important integration point in the gem. Every time the
@@ -1668,7 +1767,9 @@ This:
    current refresh token.
 2. Returns `true` on success.
 3. Raises `XeroKiwi::TokenRefreshError` if the client has no refresh capability,
-   or `XeroKiwi::AuthenticationError` if Xero rejects the revoke.
+   `XeroKiwi::AuthenticationError` if Xero rejects the revoke, or
+   `XeroKiwi::ConnectionError` if identity.xero.com does not answer within the
+   [identity timeouts](#timeouts).
 
 After revocation, **treat the client as dead.** Subsequent API calls will
 401, and reactive refresh will fail because the refresh token is gone too.
@@ -3909,6 +4010,7 @@ StandardError
    │  ├─ XeroKiwi::ClientError           (other 4xx)
    │  ├─ XeroKiwi::ServerError           (5xx)
    │  └─ XeroKiwi::RateLimitError        (429, with retry_after + problem)
+   ├─ XeroKiwi::ConnectionError          (timeout or failed connection)
    ├─ XeroKiwi::OAuth::StateMismatchError  (CSRF check failed)
    └─ XeroKiwi::OAuth::IDTokenError        (ID token JWT verification failed)
 ```
@@ -3916,12 +4018,16 @@ StandardError
 A few things worth noticing about the shape:
 
 - **Everything Xero Kiwi raises** descends from `XeroKiwi::Error`. If you only want
-  one rescue clause for "the Xero integration broke," catch this.
+  one rescue clause for "the Xero integration broke," catch this. The one
+  exception is a response that says it is JSON but does not parse, which
+  raises Faraday's own `Faraday::ParsingError`.
 - **HTTP responses** descend from `XeroKiwi::APIError`, which carries `status`
   and `body` attributes you can inspect.
 - **OAuth-specific errors** for state mismatch and ID token verification
   descend from `XeroKiwi::Error` directly (not `APIError`) because they don't
   come from an HTTP response — they're local validation failures.
+- **`XeroKiwi::ConnectionError`** descends from `XeroKiwi::Error` directly
+  too. No response arrived, so there is no status or body to carry.
 - **`XeroKiwi::TokenRefreshError`** and **`XeroKiwi::OAuth::CodeExchangeError`** are
   both `AuthenticationError` subclasses, because the practical recovery is
   the same as for any 401: the user needs to re-authorise.
@@ -4029,6 +4135,30 @@ Extra attributes beyond `APIError`:
 Sidekiq job can re-enqueue itself with that delay rather than hammering
 Xero.
 
+### `XeroKiwi::ConnectionError`
+
+Raised when a request hits its `open_timeout:`, `timeout:` or
+`write_timeout:`, or when the connection fails (refused, reset, the host
+does not resolve, or the TLS handshake fails). `XeroKiwi::Client` raises it
+only after its retries are exhausted, except for a TLS failure, which it
+does not retry. Identity calls (code exchange, client credentials, refresh,
+revoke and the JWKS fetch) are not retried.
+
+The original `Faraday::TimeoutError`, `Faraday::ConnectionFailed` or
+`Faraday::SSLError` is the error's `cause`:
+
+```ruby
+rescue XeroKiwi::ConnectionError => e
+  e.cause # => #<Faraday::TimeoutError: Net::ReadTimeout ...>
+```
+
+`XeroKiwi::OAuth::IDToken.verify` without `jwks:` is the one exception: it
+raises `XeroKiwi::OAuth::IDTokenError` for any failure to fetch the JWKS,
+timeouts included.
+
+See [Client — Timeouts](client.md#timeouts) and [OAuth — Timeouts](oauth.md#timeouts)
+for the limits and their defaults.
+
 ### `XeroKiwi::OAuth::StateMismatchError`
 
 Raised by `XeroKiwi::OAuth.verify_state!` when the `state` parameter Xero
@@ -4049,7 +4179,9 @@ the ID token JWT can't be verified. Causes:
 - Wrong audience.
 - Token expired.
 - Nonce mismatch (when nonce verification was requested).
-- Network failure fetching JWKS.
+- Network failure fetching JWKS, through `IDToken.verify` without `jwks:`.
+  Through `oauth.verify_id_token`, a network failure raises
+  `XeroKiwi::ConnectionError` instead.
 
 The error message has a brief description of which check failed (e.g.
 `"ID token verification failed: Signature verification failed"`,
@@ -4116,10 +4248,12 @@ rescue XeroKiwi::OAuth::CodeExchangeError
   redirect_to root_path, alert: "Could not complete Xero authorisation"
 rescue XeroKiwi::OAuth::IDTokenError
   redirect_to root_path, alert: "Could not verify Xero identity"
+rescue XeroKiwi::ConnectionError
+  redirect_to root_path, alert: "Xero did not respond. Please try again."
 end
 ```
 
-Three separate rescue clauses give you three different user-facing
+Four separate rescue clauses give you four different user-facing
 messages, which is usually what you want for an OAuth callback — different
 failures imply different user actions.
 
@@ -4345,10 +4479,12 @@ code, catch `XeroKiwi::ServerError` and handle it explicitly.
 |----------|-----------------|
 | All retries returned 429 | `XeroKiwi::RateLimitError` (with `retry_after` and `problem` attributes) |
 | All retries returned 502/503/504 | `XeroKiwi::ServerError` |
-| All retries failed at the transport level | The underlying `Faraday::ConnectionFailed` / `Faraday::TimeoutError` |
+| All retries failed at the transport level | `XeroKiwi::ConnectionError`, with the last `Faraday::ConnectionFailed` / `Faraday::TimeoutError` as its `cause` |
 
 The retried request count includes the original attempt, so `max: 4` means
-**up to 5 total HTTP requests** before giving up.
+**up to 5 total HTTP requests** before giving up. Each of them can wait the
+full read timeout, so a hung endpoint takes up to 5 times as long to fail.
+See [Client — Timeouts](client.md#timeouts).
 
 ## Customising the retry policy
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: xero-kiwi
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Douglas Greyling