Request lifecycle
The path of one send() call, step by step. You do not need to know it, but it explains why
middleware runs once, where the User-Agent comes from, and what exactly is retried.
send()
├─ 1. preparation address, the client's headers, binding to the client
├─ 2. middleware in the order added, once
├─ 3. exchange ┌─ settings = client ⟵ request
│ ├─ attempts (retries, deadline)
│ └─ redirects → attempts again
├─ 4. transport cURL: a handle from the pool, options, receiving the body
└─ 5. response info(), log, throwOnError1. Preparation
- Any PSR-7 request becomes a
CastRequest(CastRequest::from()), so all of its methods are available from here on. - A relative address is appended to the base URL
(the joining rule). No base URL —
RequestException. - The client’s headers are added where the request has no header of the same name.
- The request is bound to the client.
2. Middleware
The chain is built so that the middleware added first runs first. The last link of the chain is the exchange (step 3). Middleware sees the request with the client’s headers already in it and can adjust it.
3. Exchange
Settings. The client’s and the request’s settings are merged, the request’s winning. This
happens here and not in step 1, so middleware can change the request’s settings too — for
example, set withTimeout().
Address check. The scheme must be http or https.
Attempts. For each attempt:
- if a deadline is set — check how much time is left and cap the attempt’s
totalwith it; - from the second attempt on — rewind the body and move the
sinkTo()target back to its starting position; - send through the transport;
- on a network error — retry if the policy allows it, the error is transient and the pause fits into the deadline; otherwise throw;
- on a response with a status from
withStatuses()— retry under the same conditions; when the attempts run out, return the response.
A retry is possible only if the body and the sinkTo() target can be moved back to the start.
Redirects. If the response is a 301, 302, 303, 307 or 308 with a Location and
redirects are on, a new request is built
(the rules) and the attempts run again for
it. The attempt counter is shared by all hops.
4. Transport
CurlTransport performs one attempt:
- takes a handle from the pool;
- sets the options in order of priority: defaults →
withCurlOptions()→ timeouts → reserved options that cannot be overridden; - sets the method the way cURL expects it:
HEADdoes not wait for a body; - builds the headers: cURL sets
Content-Lengthfrom the body,Expect: 100-continueis turned off, the User-Agent gets theWinterCast/… curl/…suffix; - the body: up to 1 MiB from memory, larger or of unknown size streamed, multipart with files as cURL fields that read the files themselves;
- performs the transfer — in a Fiber through the shared
curl_multi, otherwisecurl_exec; - returns the handle to the pool, or drops it after an error.
Response headers. Every status line (100 Continue, a proxy’s answer to CONNECT) starts
the response over, so the result holds only the final response’s headers.
Response body. Once the final response’s headers are in, it is decided where the body goes:
- 2xx with
sinkTo()set — to the target; a file given by path is opened on the first bytes; - otherwise — to memory (
CastStream::temp(): up to 2 MiB in memory, then a temporary file), withmaxResponseSizechecked byContent-Lengthand while receiving.
Errors. The cURL error code becomes a TimeoutException (28), a TooLargeException (the
limit was exceeded) or a NetworkException. A partly written sinkTo() file is removed.
5. Response
info()gets the number of attempts, redirects and the final address;- the client’s logger writes a
debugline; retries went out aswarninglines, a failure aserror; send()withwithThrowOnError()turns a 4xx/5xx into anHttpException;sendRequest()never does.