Add OAuth2 HTTP request timeouts

[RobertIndie]

Motivation

OAuth2 issuer discovery and token requests previously used libcurl without application-level connection or total request deadlines. An unavailable or stalled issuer could therefore delay client startup and recovery for several minutes.

Modifications

Add a distinct CurlWrapper connection timeout and configurable OAuth2 connect_timeout_seconds and request_timeout_seconds parameters, defaulting to 10 and 30 seconds. Validate both parameters as positive integers, apply them to discovery, token acquisition, and refresh for both OAuth2 flows, document the public configuration, and add black-box regression coverage.

Verifying this change

Built the modified production and AuthPluginTest objects with -Werror. Ran three new timeout and validation tests plus four existing OAuth TLS tests; all 7 passed. The complete pulsar-tests target remains blocked by the pre-existing DagWatchSession incompatibility with the installed Boost.Asio API.

Usage

Configure the OAuth2 HTTP timeouts through the authentication parameters:

pulsar::ParamMap params;
params["issuer_url"] = "https://auth.example.com";
params["private_key"] = "file:///path/to/oauth-credentials.json";
params["audience"] = "https://pulsar.example.com";
params["connect_timeout_seconds"] = "5";
params["request_timeout_seconds"] = "15";

pulsar::ClientConfiguration config;
config.setAuth(pulsar::AuthOauth2::create(params));

pulsar::Client client("pulsar+ssl://broker.example.com:6651", config);

The parameters can also be supplied as JSON:

const std::string authParams = R"({
  "issuer_url": "https://auth.example.com",
  "private_key": "file:///path/to/oauth-credentials.json",
  "audience": "https://pulsar.example.com",
  "connect_timeout_seconds": "5",
  "request_timeout_seconds": "15"
})";

pulsar::ClientConfiguration config;
config.setAuth(pulsar::AuthOauth2::create(authParams));

pulsar::Client client("pulsar+ssl://broker.example.com:6651", config);

• connect_timeout_seconds controls the OAuth HTTP connection timeout and defaults to 10 seconds.
• request_timeout_seconds controls the total OAuth HTTP request timeout and defaults to 30 seconds.
• Both values must be positive integers.
• The timeouts apply to issuer discovery, initial token acquisition, and token refresh.

Python client users can pass the same JSON parameters:

import json
import pulsar

auth = pulsar.AuthenticationOauth2(json.dumps({
    "issuer_url": "https://auth.example.com",
    "private_key": "file:///path/to/oauth-credentials.json",
    "audience": "https://pulsar.example.com",
    "connect_timeout_seconds": "5",
    "request_timeout_seconds": "15",
}))

client = pulsar.Client(
    "pulsar+ssl://broker.example.com:6651",
    authentication=auth,
)

Documentation

• doc-required
  (Your PR needs to update docs and you will update later)

• doc-not-needed
  (Please explain why)

• doc
  (Your PR contains doc changes)

• doc-complete
  (Docs have been already added)

[Copilot]

Pull request overview

Adds configurable OAuth2 HTTP connection and total-request timeouts to prevent issuer discovery / token requests from stalling client startup and token refresh.

Changes:

• Introduces connect_timeout_seconds and request_timeout_seconds OAuth2 parameters (defaults 10s/30s) with positive-integer validation.
• Extends CurlWrapper::Options with a connection timeout and applies it via CURLOPT_CONNECTTIMEOUT.
• Adds black-box tests covering issuer discovery timeout, token request timeout, and parameter validation; updates public header docs.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/AuthPluginTest.cc	Adds mock-server delay support and new OAuth2 timeout/validation regression tests.
oauth2-http-timeout-analysis.md	Adds an in-repo analysis/design write-up for the OAuth2 timeout change.
lib/CurlWrapper.h	Adds connectTimeoutInSeconds and applies CURLOPT_CONNECTTIMEOUT.
lib/auth/AuthOauth2.h	Introduces Oauth2HttpTimeouts and stores it in OAuth2 flows.
lib/auth/AuthOauth2.cc	Parses/validates timeout params and applies them to issuer discovery + token requests (incl. timeout logging).
include/pulsar/Authentication.h	Documents new OAuth2 timeout parameters in the public API header.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.