ext/curl: add socket callback options bridging to ext/sockets

Expose libcurl's CURLOPT_SOCKOPTFUNCTION, CURLOPT_OPENSOCKETFUNCTION and
CURLOPT_CLOSESOCKETFUNCTION, letting userland hook into socket creation,
configuration and teardown. These are useful for application security, in
particular SSRF protection (validating the resolved address before connecting)
and low-level socket hardening.

Following the existing curl_write_header / curl_prereqfunction bridge model, the
callbacks exchange ext/sockets Socket objects so they are fully usable in pure
PHP (socket_create/socket_bind, socket_set_option, socket_close):

  - sockopt:     fn(CurlHandle $ch, Socket $socket, int $purpose): int
                 returns CURL_SOCKOPT_OK / _ERROR / _ALREADY_CONNECTED
  - opensocket:  fn(CurlHandle $ch, int $purpose, array $address): Socket|false
                 $address = [family, socktype, protocol, ip, port];
                 returning false aborts the connection (CURL_SOCKET_BAD)
  - closesocket: fn(CurlHandle $ch, Socket $socket): void

The dependency on ext/sockets is optional both at build and at runtime
(ZEND_MOD_OPTIONAL): the rest of ext/curl keeps working when sockets is not
loaded, and the three socket-callback options simply throw a clear Error when
invoked in that configuration. The Socket class entry is resolved lazily by
name at MINIT rather than referenced as a link-time symbol, so curl never
carries a hard symbol dependency on ext/sockets.

Notable details:
  - Descriptors owned by libcurl are detached (bsd_socket = -1) before the
    temporary Socket object is released, to avoid a double close. Socket
    objects are created without calling socket_import_file_descriptor(), which
    on Windows emits a spurious WSAEINVAL warning on a not-yet-connected
    socket during the SOCKOPT phase.
  - Pooled connections still alive at curl_easy_cleanup() would otherwise
    invoke the userland CURLOPT_CLOSESOCKETFUNCTION callback during handle
    destruction. Calling into PHP from there is unsafe (an exception thrown
    from the callback would surface outside any try/catch). Setting the
    option back to NULL on the easy handle is not enough — libcurl caches the
    function pointer per connection. The close FCC is torn down before
    curl_easy_cleanup() so the trampoline falls through to its native-close
    fallback when libcurl invokes it.
  - The same teardown is applied to every easy handle attached to a
    CurlMultiHandle before curl_multi_cleanup() so the close callback never
    fires from within the multi's destructor either.
  - Stream-backed Sockets and already-closed Sockets returned from
    CURLOPT_OPENSOCKETFUNCTION are refused with a TypeError: a stream-backed
    Socket bypasses our bsd_socket detach (socket_free_obj() delegates close
    to the backing php_stream), and an already-closed Socket would bury the
    real cause under a generic CURLE_COULDNT_CONNECT.
  - When the sockopt callback throws, the abort path returns
    CURL_SOCKOPT_ERROR (matching opensocket / ssh_hostkey) so libcurl does
    not connect with a half-configured socket.
  - Setting an option to null restores libcurl's native default.

New constants (only defined when ext/curl is built with sockets headers
available, i.e. HAVE_SOCKETS): CURLOPT_SOCKOPTFUNCTION,
CURLOPT_OPENSOCKETFUNCTION, CURLOPT_CLOSESOCKETFUNCTION, CURL_SOCKOPT_OK,
CURL_SOCKOPT_ERROR, CURL_SOCKOPT_ALREADY_CONNECTED, CURLSOCKTYPE_IPCXN,
CURLSOCKTYPE_ACCEPT.

Author: xavierleune

NEWS

@@ -512,6 +512,10 @@ PHP                                                                        NEWS
 
 - Curl:
   . Add support for CURLINFO_SIZE_DELIVERED (libcurl >= 8.20.0). (Ayesh)
+  . Added CURLOPT_SOCKOPTFUNCTION, CURLOPT_OPENSOCKETFUNCTION and
+    CURLOPT_CLOSESOCKETFUNCTION options, bridging libcurl's socket callbacks to
+    ext/sockets Socket objects (requires the sockets extension).
+    (Xavier Leune)
 
 - Date:
   . Update timelib to 2022.16. (Derick)

UPGRADING

@@ -331,6 +331,16 @@ PHP 8.6 UPGRADE NOTES
     failing with CURLE_SEND_FAIL_REWIND. The callback receives the CurlHandle,
     offset and origin, and must return one of CURL_SEEKFUNC_OK,
     CURL_SEEKFUNC_FAIL or CURL_SEEKFUNC_CANTSEEK.
+  . Added the CURLOPT_SOCKOPTFUNCTION, CURLOPT_OPENSOCKETFUNCTION and
+    CURLOPT_CLOSESOCKETFUNCTION options, which let userland hook into libcurl's
+    socket creation, configuration and teardown. The callbacks exchange
+    ext/sockets Socket objects, e.g. to validate the resolved address before
+    connecting (SSRF protection) or to set low-level socket options. Setting
+    one of these three options requires the sockets extension to be loaded
+    (otherwise an Error is thrown); the rest of ext/curl keeps working without
+    it. The new CURL_SOCKOPT_OK, CURL_SOCKOPT_ERROR,
+    CURL_SOCKOPT_ALREADY_CONNECTED, CURLSOCKTYPE_IPCXN and CURLSOCKTYPE_ACCEPT
+    constants are defined alongside them.
 
 - Date:
   . Added a new Time\Duration class.

ext/curl/config.m4

@@ -75,6 +75,13 @@ if test "$PHP_CURL" != "no"; then
   PHP_NEW_EXTENSION([curl],
     [interface.c multi.c share.c curl_file.c],
     [$ext_shared])
+  dnl The CURLOPT_SOCKOPT/OPENSOCKET/CLOSESOCKETFUNCTION callbacks bridge to
+  dnl ext/sockets Socket objects (guarded by HAVE_SOCKETS). The dependency is
+  dnl optional both at build and at runtime: without sockets the rest of curl
+  dnl keeps working, and the three socket-callback options throw a clear error
+  dnl when invoked. The hint below only enforces MINIT order when sockets is
+  dnl built in alongside curl.
+  PHP_ADD_EXTENSION_DEP(curl, sockets, true)
   PHP_INSTALL_HEADERS([ext/curl], [php_curl.h])
   PHP_SUBST([CURL_SHARED_LIBADD])
 fi

ext/curl/config.w32

@@ -25,6 +25,12 @@ if (PHP_CURL != "no") {
 			WARNING("zstd in curl not enabled; library not found");
 		}
 		EXTENSION("curl", "interface.c multi.c share.c curl_file.c");
+		// The socket callbacks (CURLOPT_SOCKOPT/OPENSOCKET/CLOSESOCKETFUNCTION)
+		// bridge to ext/sockets Socket objects, guarded by HAVE_SOCKETS. Optional
+		// at build and at runtime: without sockets the rest of curl keeps working
+		// and only those three options throw a clear error when invoked. The hint
+		// below ensures MINIT order when both extensions are built together.
+		ADD_EXTENSION_DEP('curl', 'sockets', true);
 		AC_DEFINE('HAVE_CURL', 1, "Define to 1 if the PHP extension 'curl' is available.");
 		ADD_FLAG("CFLAGS_CURL", "/D PHP_CURL_EXPORTS=1");
 		if (curl_location.match(/libcurl_a\.lib$/)) {

ext/curl/curl.stub.php

@@ -2352,6 +2352,63 @@
  */
 const CURL_FNMATCHFUNC_NOMATCH = UNKNOWN;
 
+#ifdef HAVE_SOCKETS
+/**
+ * Used with CURLOPT_SOCKOPTFUNCTION, which receives a Socket wrapping the
+ * descriptor libcurl just created and must return one of the CURL_SOCKOPT_*
+ * constants below.
+ * @var int
+ * @cvalue CURLOPT_SOCKOPTFUNCTION
+ */
+const CURLOPT_SOCKOPTFUNCTION = UNKNOWN;
+/**
+ * Used with CURLOPT_OPENSOCKETFUNCTION, which receives the resolved address and
+ * must return a Socket to use for the connection, or false to abort it.
+ * @var int
+ * @cvalue CURLOPT_OPENSOCKETFUNCTION
+ */
+const CURLOPT_OPENSOCKETFUNCTION = UNKNOWN;
+/**
+ * Used with CURLOPT_CLOSESOCKETFUNCTION, which is notified when libcurl is done
+ * with a socket created by the open-socket callback.
+ * @var int
+ * @cvalue CURLOPT_CLOSESOCKETFUNCTION
+ */
+const CURLOPT_CLOSESOCKETFUNCTION = UNKNOWN;
+/**
+ * Return value for the CURLOPT_SOCKOPTFUNCTION callback: proceed normally.
+ * @var int
+ * @cvalue CURL_SOCKOPT_OK
+ */
+const CURL_SOCKOPT_OK = UNKNOWN;
+/**
+ * Return value for the CURLOPT_SOCKOPTFUNCTION callback: abort the connection.
+ * @var int
+ * @cvalue CURL_SOCKOPT_ERROR
+ */
+const CURL_SOCKOPT_ERROR = UNKNOWN;
+/**
+ * Return value for the CURLOPT_SOCKOPTFUNCTION callback: the socket is already
+ * connected, so libcurl should skip its own connect step.
+ * @var int
+ * @cvalue CURL_SOCKOPT_ALREADY_CONNECTED
+ */
+const CURL_SOCKOPT_ALREADY_CONNECTED = UNKNOWN;
+/**
+ * Purpose passed to the socket callbacks: a socket for a regular IP connection.
+ * @var int
+ * @cvalue CURLSOCKTYPE_IPCXN
+ */
+const CURLSOCKTYPE_IPCXN = UNKNOWN;
+/**
+ * Purpose passed to the socket callbacks: a socket created from accept() (e.g.
+ * active FTP).
+ * @var int
+ * @cvalue CURLSOCKTYPE_ACCEPT
+ */
+const CURLSOCKTYPE_ACCEPT = UNKNOWN;
+#endif
+
 /* Available since 7.21.2 */
 /**
  * @var int

ext/curl/curl_arginfo.h

@@ -85,6 +85,11 @@ typedef struct {
 #if LIBCURL_VERSION_NUM >= 0x075400 /* Available since 7.84.0 */
 	zend_fcall_info_cache sshhostkey;
 #endif
+#ifdef HAVE_SOCKETS
+	zend_fcall_info_cache sockopt;
+	zend_fcall_info_cache opensocket;
+	zend_fcall_info_cache closesocket;
+#endif
 } php_curl_handlers;
 
 struct _php_curl_error  {