Apply the shared request options

Timeout, bounded retry on transient failures, an attributable user agent, and optionally a throttle and headers.

Usage

req_defaults(
  req,
  timeout = 20,
  max_tries = 3,
  headers = NULL,
  throttle = NULL,
  user_agent = default_user_agent()
)

Arguments

req

An httr2 request.

timeout

Seconds before the request is abandoned.

max_tries

Total attempts, including the first.

headers

A named list of headers. All of them are marked sensitive.

throttle

An optional list with capacity, fill_time_s, and realm. httr2 token buckets are per process, so a realm keyed on the host gives one honest bucket per host. Defaults to the request's own host.

user_agent

The User-Agent string. See user_agent().

Value

The request, with the options applied.

Details

req_error() is disarmed here on purpose. httr2 would otherwise raise on a non-2xx, and this package normalizes every outcome into an envelope instead, so perform() needs the response object rather than a condition.

Headers are attached with .redact set to their names, so a token never prints in an inspected request, a log line, or an error message. Header auth also keeps the secret out of the URL, where it would end up in access logs.

Examples

req_defaults(httr2::request("https://example.org"), timeout = 5)
#> <httr2_request>
#> GET https://example.org
#> Body: empty
#> Options:
#> * timeout_ms    : 5000
#> * connecttimeout: 0
#> * useragent     : "biohttp/0.1.1"
#> Policies:
#> * retry_max_tries        : 3
#> * retry_on_failure       : FALSE
#> * retry_is_transient     : <function>
#> * retry_failure_threshold: Inf
#> * retry_failure_timeout  : 30
#> * retry_realm            : "example.org"
#> * error_is_error         : <function>

# A key-gated source. The token is redacted from anything printable.
req_defaults(
  httr2::request("https://example.org"),
  headers = list(Authorization = "Bearer secret-token")
)
#> <httr2_request>
#> GET https://example.org
#> Headers:
#> * Authorization: <REDACTED>
#> Body: empty
#> Options:
#> * timeout_ms    : 20000
#> * connecttimeout: 0
#> * useragent     : "biohttp/0.1.1"
#> Policies:
#> * retry_max_tries        : 3
#> * retry_on_failure       : FALSE
#> * retry_is_transient     : <function>
#> * retry_failure_threshold: Inf
#> * retry_failure_timeout  : 30
#> * retry_realm            : "example.org"
#> * error_is_error         : <function>