Allow persistent connections

[nicolas-grekas]

This was proposed in #18 but not implemented.

For Symfony HttpClient, people showed interest in using persistent cURL connections.
Having support in AMPHP would be nice for feature parity.

See symfony/symfony#62751

[kelunik]

@nicolas-grekas Are you sure the underlying implementation is really safe? Reading https://curl.se/libcurl/c/libcurl-share.html:

Since you can use this share from multiple threads, and libcurl has no internal thread synchronization, you must provide mutex callbacks if you are using this multi-threaded. You set lock and unlock functions with curl_share_setopt too.

I don't see any usages of CURLSHOPT_LOCKFUNC in php-src.

Do you know how connections are actually shared in curl?

[nicolas-grekas]

I don't 😬 but I'd suppose this is implemented like other persistent connections: the FPM worker keeps the connection in the memory area that's persisted between requests...
This might cause issues in FrankenPHP IIUC, since this one relies on threads. Unless PHP's thread safety works around the issue?
I don't know...

[nicolas-grekas]

Here is a better answer by GTP5.1 Codex Max:

Here’s what php-src’s curl extension does today regarding shared/persistent handles and thread safety:

• The share API only passes through CURLSHOPT_SHARE / CURLSHOPT_UNSHARE; there is no wiring for CURLSHOPT_LOCKFUNC / CURLSHOPT_UNLOCKFUNC anywhere in the extension (share.c:57-94), and a repo-wide search finds no references to those options.
• “Persistent” share handles were added via curl_share_init_persistent(), which builds a key from allowed lock types (DNS / SSL_SESSION / CONNECT / PSL), de-dupes them, and stores a CURLSH* in a module-global hash for reuse (share.c:139-258). Cookies are explicitly disallowed for persistence.
• The persistent hash table lives in the module globals CURL_G(persistent_curlsh), initialized per module instance (interface.c:188-207). In ZTS builds, module globals are per-thread; in non-ZTS they’re per-process. So: persistent share handles are reused within a single FPM worker process or a single thread, not across threads. That avoids the need for libcurl lock callbacks, but also means no cross-thread reuse (e.g., FrankenPHP would have one cache per worker thread).
• Tests confirm the intent: a second request using the same persistent share reuses the connection (connect_time = 0), while different share option sets do not reuse it (curl_persistent_share_001.phpt:4-36, curl_persistent_share_002.phpt:4-34).

Implication for this issue: php-src’s persistent share feature currently relies on process/thread locality instead of curl’s lock callbacks. It should be safe in FPM (per process) and ZTS (per thread) because handles aren’t shared across threads, but it doesn’t provide cross-thread persistence. If amphp wants thread-pooled reuse, it would need to supply CURLSHOPT_LOCKFUNC / CURLSHOPT_UNLOCKFUNC and manage locking itself; php-src doesn’t set those today.

[kelunik]

Damn, GPT 5.1 still doesn't know amphp doesn't depend on Curl. 😄 Makes sense, though having things cached per worker is probably quite sub-optimal.

The biggest issue with persistent connections is knowing in which state they are. DNS should usually be "shared" locally using a local DNS resolver like systemd-resolved. TLS sessions are currently not really solved, I think. Connections is the really difficult one, because they're stateful. This is even worse in HTTP/2 with stateful HPACK.