Package · cast

Transport and connection pool

A new connection means DNS, TCP and TLS: tens of milliseconds. Cast tries to open one as rarely as possible, while never giving one connection to two requests at once.

The handle pool

The pool keeps cURL handles. An open connection lives inside a handle: another request to the same host through the same handle goes over the connection that is already open.

text
CurlHandlePool  (one per CastClient and all its with*() copies)
├── idle: [h1, h2, h3]         handles with open connections, at most 16
└── share: DNS + TLS sessions  a shared cache for all handles of the pool

The path of one request:

text
acquire()   take an idle handle; none idle — create a new one
↓
perform the request
↓
release()   reset the options (the connection stays open) and return it to the pool
          • 16 already idle — the handle is closed
          • the request failed — the handle is closed; the next one takes a fresh handle
  • A handle belongs to one request. While it is in use it is not idle, so two requests never write to one connection.
  • The pool does not limit requests. 16 is how many idle handles to keep in reserve, not how many requests run at once. With none idle, a new one is created, without a queue or waiting.
  • Clients are independent. Each new CastClient() has its own pool; copies made with with*() share the original’s pool.

The shared cache: curl_share

Handles of one pool share through curl_share:

  • DNS — an address found by one handle is known to all (cURL’s cache lasts 60 seconds);
  • TLS sessions — a new handle to a known server does a short handshake instead of a full one.

This helps where a connection was not reused: a new handle under peak load, handles after sendAll().

A shared connection cache (CURL_LOCK_DATA_CONNECT) and the PHP 8.5 persistent share are deliberately not used. Their gain is small, and under Swoole with curl-native every coroutine has its own wait loop, so sharing connections between them would cause failures that are hard to track down.

PHP-FPM and Swoole

PHP-FPM Swoole
How long the pool lives while the client lives — usually one application request the whole life of the worker, if the client is a bean
Connection reuse within one application request across all requests of the worker
Concurrent requests Fibers + a shared curl_multi each coroutine takes a handle of its own
Waiting on the network curl_exec or curl_multi_select Swoole’s hooks: the coroutine yields

In Swoole, acquire() and release() contain no waiting points, so a coroutine cannot be switched out in the middle of them. There is no race for a handle and no locks are needed.

sendAll without Swoole: Fibers and curl_multi

text
sendAll([a, b, c])
├─ Fiber a: middleware → retries → transport → handle into curl_multi → suspend
├─ Fiber b: …                                → handle into curl_multi → suspend
├─ Fiber c: …                                → handle into curl_multi → suspend
└─ loop: curl_multi_exec / select → a response is ready → resume its Fiber

Middleware and retry code stays synchronous: $next($request) just returns a response. A pause between retries is also a Fiber suspended on a timer, and the other requests keep going meanwhile. If sendAll() is called from inside another sendAll() (from middleware, say), the nested requests run one after another, but through the same outer loop — nothing blocks.

While a handle is inside curl_multi, its connection is kept in the multi’s cache, which is closed after sendAll(). The handles return to the pool without connections; the next request connects again, but thanks to the share it skips DNS and gets a quick TLS handshake.

The server restarted

  • requests sent while the server is down get a NetworkException (“Could not connect”), and the handle is dropped;
  • as soon as the server is back, the next request goes through: the client does not “remember” anything;
  • a pooled connection that the server closed is checked by cURL before use and silently replaced by a new one; if the server closed it at the moment of sending and no response came, cURL reconnects once by itself;
  • the IP changed (a new container) — for up to a minute the address may come from the DNS cache; to shorten that, use withCurlOptions([CURLOPT_DNS_CACHE_TIMEOUT => 10]);
  • the server did not recognise the TLS session — a full handshake happens, without an error.

To keep a short restart from reaching your code at all, turn on retries: RetryPolicy::exponential(3, 500) — a connection error counts as transient.

HTTP/2

Over TLS, HTTP/2 is used if cURL is built with it and the server offers it (ALPN). Otherwise, and over http://, HTTP/1.1. The response’s version is in getProtocolVersion() and info()->protocol.