1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
|
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/client.R
\name{cepis_client}
\alias{cepis_client}
\title{Build a client for the cep.is API}
\usage{
cepis_client(
base_url = DEFAULT_BASE_URL,
timeout = 10,
max_attempts = 3L,
backoff_base = 0.5,
backoff_max = 8,
total_timeout = NULL,
user_agent = NULL
)
}
\arguments{
\item{base_url}{Where the API lives. Point it at a local instance (the API
repo brings one up on \verb{http://localhost:8080} with \verb{just up}) or at a
test server. It is the only parameter that usually changes between
environments. Trailing slashes are stripped, so it cannot produce
doubled separators that some proxies normalise and others 404.}
\item{timeout}{Seconds allowed for \strong{one attempt}, connection and
transfer together. It is not a cap on the whole call, since a call may
make several attempts; that cap is \code{total_timeout}.}
\item{max_attempts}{How many attempts in total, counting the first. \code{1}
disables retrying. The default of \code{3} covers the common case (one
transient failure) without turning a real outage into a long wait.}
\item{backoff_base}{Base of the exponential wait, in seconds. The actual
wait is drawn from \verb{[0, base * 2^(n - 1)]} — \emph{full jitter}. The
randomness is not decoration: without it, N clients that fail together
come back together and reproduce the spike that took the service down.}
\item{backoff_max}{Cap on each individual wait, in seconds. It applies to
a server-sent \code{Retry-After} too, or a \code{Retry-After: 3600} from a
misconfigured proxy would park the session for an hour.}
\item{total_timeout}{Cap on the whole call, attempts and waits included.
\code{NULL} leaves \code{max_attempts} as the only bound. Set it in code serving a
web request: without it the worst case is \code{max_attempts * timeout} plus
the sum of the backoffs.}
\item{user_agent}{Overrides the \code{User-Agent}. The default identifies the
package and its version, which is what lets the server diagnose an old
client misbehaving.}
}
\value{
An object of class \code{cepis_client}, to pass as the \code{client}
argument of \code{\link[=cep_lookup]{cep_lookup()}}, \code{\link[=cep_lookup_many]{cep_lookup_many()}} and \code{\link[=cep_health]{cep_health()}}.
}
\description{
Holds the configuration and nothing else: no connection, no state between
calls. Build one and reuse it, or skip it entirely — \code{\link[=cep_lookup]{cep_lookup()}},
\code{\link[=cep_lookup_many]{cep_lookup_many()}} and \code{\link[=cep_health]{cep_health()}} fall back to a shared default
client built with these defaults.
}
\examples{
client <- cepis_client(base_url = "http://localhost:8080", timeout = 5)
client$max_attempts
}
|