docs: document idle connection behavior for socket callbacks by jayvenn21 · Pull Request #20521 · curl/curl

jayvenn21 · 2026-02-04T21:08:23Z

This PR documents observed behavior around idle connections and socket callbacks that is not currently described in the documentation.

Specifically:

When CURLOPT_CLOSESOCKETFUNCTION is copied and when it is invoked
How idle connections interact with CURLMOPT_SOCKETFUNCTION
Why read/error events may still occur on sockets that have been removed from polling

This behavior is relevant for applications managing large numbers of sockets and custom polling loops (e.g. kqueue/epoll-based integrations).

No functional changes are introduced.

Addresses #20377

rakshasa · 2026-02-05T13:13:26Z

+socket. This can surface as zero-length reads or spurious data when
+the connection is later closed or reused. Applications using
+CURLMOPT_SOCKETFUNCTION(3) should handle such events without assuming
+the socket is still actively used by libcurl.


This is slightly inverted.

While idle connections are not supposed to receive data (according to http specs), they can receive zero length messages indicating connection closed by server. (non-zero length messages when using https, that decrypt to zero-length message)

However CURL_POLL_REMOVE has told us not to listen for read events.

We can't send CURL_CSELECT_ERR to libcurl in those cases because idle connections don't get handled in curl_multi_socket_action.

So we can't cheat by listening to read events for idle connections for three reasons:

There a way to get libcurl to close an fd in idle connection pool.

We can't peek at the message to check if it is zero-length. (http)

We can't decrypt the message to determine it is zero-length. (https)

Also point out that if a socket is NOT in read nor write, and is closed by the kernel for some reason, that fd can be reused and cause conflicts with libcurl's internally managed list of fds.

Thanks for the clarification that makes sense.

You're right: the wording is slightly inverted. The intent was not to suggest that applications should listen for read events on idle connections, but rather to document why they may still surface and why libcurl cannot safely act on them once CURL_POLL_REMOVE has been issued.

I’ll update the text to emphasize:

That idle connections are not expected to receive application data

That zero-length reads (or encrypted data decrypting to zero-length) can still occur on close

That libcurl cannot inspect, decrypt, or act on such events for idle connections

And that fd reuse after kernel close is the underlying risk applications need to account for

I’ll push a small doc fix shortly.

jayvenn21 · 2026-02-05T13:42:38Z

Looks like the Alpine musl + c-ares DNS flake (test 2103).
Could someone rerun the Alpine job?

testclutch · 2026-02-05T13:48:24Z

Analysis of PR #20521 at 6b1fd514:

Test 2103 failed, which has NOT been flaky recently, so there could be a real issue in this PR. Note that this test has failed in 12 different CI jobs (the link just goes to one of them).

Generated by Testclutch

jayvenn21 · 2026-02-05T13:50:55Z

@testclutch Thanks for the heads-up.
This PR is documentation-only and does not touch resolver, socket, or test code.
Given that test 2103 is failing consistently across multiple Alpine/musl + c-ares jobs, this looks like an environment/test expectation issue rather than a change introduced here.
Happy to help investigate if you think it’s related, otherwise I assume this needs a CI rerun or maintainer-side follow-up.

jayvenn21 · 2026-02-07T22:43:36Z

I’ve updated the documentation to align more closely with the intended contract and wording expectations.

Changes in this revision:
• Removed references to “observed behavior” and reframed the text to describe how libcurl behaves from the API/user perspective.
• Clarified that socketp may be NULL after CURL_POLL_REMOVE, and that pointers previously assigned via curl_multi_assign() are forgotten at that point.
• Tightened language to avoid speculation about kernel behavior or fd reuse, focusing instead on what applications can and cannot rely on when sockets are no longer monitored.
• Simplified wording to be explicit about state transitions (active → idle) without implying unsupported usage.

Please let me know if this better matches the documentation style you’re aiming for, or if further tightening is needed.

jayvenn21 · 2026-02-07T23:43:44Z

Thanks for the detailed review as that helped clarify the scope here.

I’ve updated the PR to:
• Remove CURL_POLL_REMOVE and socket-function-related discussion from the close socket callback man page
• Limit the documentation to the defined behavior and guarantees of CURLOPT_CLOSESOCKETFUNCTION
• Apply the suggested wording changes directly

Any remaining questions about idle connection observability probably belong in the socket function docs or a separate design discussion, so I’ve kept this PR narrowly scoped.

clayjohn · 2026-02-10T04:50:56Z

Hi @bagder I hate to be the bearer of bad news. But Jayvenn21 is using some sort of continuous AI agent to interact on Github. I highly doubt there is a human reading any of the extensive review comments that you have left :( More likely your comments are being fed directly into an AI chatbot which is generating and pushing further patches.

Since you have left such extensive reviews, maybe the final result is fine, but I would hate to see you waste further time trying to give nice and helpful feedback to an AI chat bot who will not learn from this interaction and will never become a future contributor.

We just banned this user from the Godot repo after they replied to our admonition for submitting non-functional AI-generated code with an AI-generated (non)apology. Example here: godotengine/godot#116056

jayvenn21 · 2026-02-10T04:55:41Z

Hi @clayjohn fyi and just to clarify, I’m actively reading and responding to review feedback myself. I do use tooling to help reason and personally go through unfamiliar code paths, but all changes are reviewed, understood, and implemented by me. If not, then I wouldn't personally take my time out and read through the comments and iterate over them. Happy to clarify or adjust anything if there are concerns.

bagder

Some ideas to improve this

bagder · 2026-06-16T13:08:23Z

+CURL_POLL_REMOVE, the application must stop monitoring that socket on
+libcurl's behalf. libcurl does not track idle connections. The pointer
+previously assigned to the socket with curl_multi_assign(3) is forgotten by
+libcurl.


This note seems to be better placed in the curl_multi_assign(3) man page!

bagder · 2026-06-16T13:11:37Z

+
+When using the multi interface, the close socket callback is invoked when
+libcurl closes a socket it owns. The callback and CURLOPT_CLOSESOCKETDATA(3)
+are copied from the *first* easy handle that creates the connection;


Suggested change

are copied from the *first* easy handle that creates the connection;

are copied from the *first* easy handle that creates the socket used for a connection;

bagder · 2026-06-16T13:12:36Z

+are copied from the *first* easy handle that creates the connection;
+changing this option on a subsequent easy handle that reuses the same
+connection has no effect for that connection. The callback is stored with
+the connection because the connection may outlive the easy handle that


Suggested change

the connection because the connection may outlive the easy handle that

the connection because the connection and its associated socket may outlive the easy handle that

bagder · 2026-06-16T13:12:58Z

+changing this option on a subsequent easy handle that reuses the same
+connection has no effect for that connection. The callback is stored with
+the connection because the connection may outlive the easy handle that
+created it, so that libcurl can still invoke it when the connection is


Suggested change

created it, so that libcurl can still invoke it when the connection is

created it, so that libcurl can still invoke it when the socket is

bagder · 2026-06-16T13:14:16Z

 inherited by a new connection and that connection may live longer
 than the transfer itself in the multi/share handle's connection cache.

+# NOTES ON IDLE CONNECTIONS


This note seems to be about reused connections, not idle ones.

Suggested change

# NOTES ON IDLE CONNECTIONS

# NOTES ON CONNECTION REUSE

Document observed behavior around idle connections and socket callbacks: - When CURLOPT_CLOSESOCKETFUNCTION is copied and when it is invoked - How idle connections interact with CURLMOPT_SOCKETFUNCTION - Why read/error events may still occur on sockets removed from polling No functional changes.

Co-authored-by: Daniel Stenberg <daniel@haxx.se>

Remove socket function and polling details from the close socket callback man page and clarify only the documented lifecycle guarantees.

jayvenn21 · 2026-06-19T15:50:45Z

Thanks for the update and feedback and I updated the docs with the suggested changes.

I renamed the close socket note to connection reuse and adjusted the wording around the first easy handle/socket lifetime. also, I've rebased on current master; the curl_multi_assign(3) note is covered there now, so this PR no longer changes that file.

rakshasa · 2026-08-02T10:36:01Z

https://github.com/rakshasa/libtorrent/blob/master/src/net/curl_socket.cc#L377-L450

The above code was necessary to reliably detect libcurl sockets that circumvent the CURLOPT_OPENSOCKETFUNCTION callback. (macos/bsd/linux)

jayvenn21 · 2026-08-02T18:05:21Z

thanks i've taken a look and updated based on both of the above comments.

I removed the extra CURL_POLL_REMOVE sentence from the socket callback page since it was just restating the existing contract. Also, I've reworded the close socket callback note, so that the generic behavior is not described as multi-only.

bagder · 2026-08-20T22:13:13Z

Thanks!

github-actions Bot added the documentation label Feb 4, 2026

jayvenn21 mentioned this pull request Feb 4, 2026

Current API insufficient to deal with idle connection close/errors on kqueue #20377

Closed

jayvenn21 force-pushed the docs-idle-connection-socket-callbacks branch from 188f3d6 to b1b3718 Compare February 4, 2026 21:23

rakshasa reviewed Feb 5, 2026

View reviewed changes

jayvenn21 force-pushed the docs-idle-connection-socket-callbacks branch 2 times, most recently from bd79658 to 6b1fd51 Compare February 5, 2026 13:30

bagder reviewed Feb 7, 2026

View reviewed changes

TheBaronVladimirHarkonnen reviewed Feb 8, 2026

View reviewed changes

Comment thread docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md Outdated

bagder reviewed Feb 9, 2026

View reviewed changes

jayvenn21 force-pushed the docs-idle-connection-socket-callbacks branch from 8a5a1cd to c2c8195 Compare February 9, 2026 15:35

bagder reviewed Feb 9, 2026

View reviewed changes

Comment thread docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md Outdated

bagder reviewed Feb 10, 2026

View reviewed changes

Comment thread docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md Outdated

bagder reviewed Jun 16, 2026

View reviewed changes

github-actions Bot added the libcurl API label Jun 19, 2026

jayvenn21 and others added 7 commits June 19, 2026 11:39

docs: fix man page formatting for idle connection behavior

45bc09e

docs: fix spelling in CURLOPT_CLOSESOCKETFUNCTION

03bbd8b

docs: clarify idle connection polling behavior per review

1b1ad3a

docs: fix pyspelling by marking technical terms

7d65e27

docs: reframe idle connection notes as API guarantees per review

9426e14

Update docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md

db82a8f

Co-authored-by: Daniel Stenberg <daniel@haxx.se>

jayvenn21 and others added 6 commits June 19, 2026 11:39

Update docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md

386e35c

Co-authored-by: Daniel Stenberg <daniel@haxx.se>

docs: limit close socket callback documentation to defined behavior

3730a98

Remove socket function and polling details from the close socket callback man page and clarify only the documented lifecycle guarantees.

docs: narrow CURLOPT_CLOSESOCKETFUNCTION to defined guarantees

ba041b0

docs: remove redundant socketp sentence per review

8158f62

docs: add reason callback is stored with connection per review

21e2e54

docs: address socket callback review feedback

9c58ed9

jayvenn21 force-pushed the docs-idle-connection-socket-callbacks branch from 9713813 to 9c58ed9 Compare June 19, 2026 15:45

bagder reviewed Jul 27, 2026

View reviewed changes

Comment thread docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md Outdated

Comment thread docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md Outdated

docs: address socket callback review comments

64e9f1f

bagder closed this in 3bc9364 Aug 20, 2026

	are copied from the first easy handle that creates the connection;
	are copied from the first easy handle that creates the socket used for a connection;

	the connection because the connection may outlive the easy handle that
	the connection because the connection and its associated socket may outlive the easy handle that

	created it, so that libcurl can still invoke it when the connection is
	created it, so that libcurl can still invoke it when the socket is

Uh oh!

Uh oh!

Conversation

jayvenn21 commented Feb 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rakshasa Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jayvenn21 Feb 5, 2026

Choose a reason for hiding this comment

Uh oh!

jayvenn21 commented Feb 5, 2026

Uh oh!

testclutch commented Feb 5, 2026

Generated by Testclutch

Uh oh!

jayvenn21 commented Feb 5, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jayvenn21 commented Feb 7, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jayvenn21 commented Feb 7, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

clayjohn commented Feb 10, 2026

Uh oh!

jayvenn21 commented Feb 10, 2026

Uh oh!

Uh oh!

bagder left a comment

Choose a reason for hiding this comment

Uh oh!

bagder Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

bagder Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

bagder Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

bagder Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

bagder Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

jayvenn21 commented Jun 19, 2026

Uh oh!

Uh oh!

Uh oh!

rakshasa commented Aug 2, 2026

Uh oh!

jayvenn21 commented Aug 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bagder commented Aug 20, 2026

Uh oh!

jayvenn21 commented Feb 4, 2026 •

edited

Loading

rakshasa Feb 5, 2026 •

edited

Loading

jayvenn21 commented Aug 2, 2026 •

edited

Loading