Package · cast

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.

text
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, throwOnError

1. 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:

  1. if a deadline is set — check how much time is left and cap the attempt’s total with it;
  2. from the second attempt on — rewind the body and move the sinkTo() target back to its starting position;
  3. send through the transport;
  4. on a network error — retry if the policy allows it, the error is transient and the pause fits into the deadline; otherwise throw;
  5. 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:

  1. takes a handle from the pool;
  2. sets the options in order of priority: defaults → withCurlOptions() → timeouts → reserved options that cannot be overridden;
  3. sets the method the way cURL expects it: HEAD does not wait for a body;
  4. builds the headers: cURL sets Content-Length from the body, Expect: 100-continue is turned off, the User-Agent gets the WinterCast/… curl/… suffix;
  5. 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;
  6. performs the transfer — in a Fiber through the shared curl_multi, otherwise curl_exec;
  7. 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), with maxResponseSize checked by Content-Length and 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 debug line; retries went out as warning lines, a failure as error;
  • send() with withThrowOnError() turns a 4xx/5xx into an HttpException; sendRequest() never does.