ext/curl: Add CURLOPT_PREREQFUNCTION

Ayesh · Ayesh · commit 545e929cbada · 2024-03-11T22:26:18.000+07:00
Curl >= 7.80.0 supports declaring a function for `CURLOPT_PREREQFUNCTION` option that gets called after Curl establishes a connection (including the TLS handshake for HTTPS connections), but before the actual request is made. The callable must return either `CURL_PREREQFUNC_OK` or `CURL_PREREQFUNC_ABORT` to allow or abort the request. This adds support for it to PHP with required ifdef. - libc: https://curl.se/libcurl/c/CURLOPT_PREREQFUNCTION.html
diff --git a/UPGRADING b/UPGRADING
@@ -171,6 +171,12 @@ PHP 8.4 UPGRADE NOTES
   . curl_version() returns an additional feature_list value, which is an
     associative array of all known Curl features, and whether they are
     supported (true) or not (false).
+  . Added CURLOPT_PREREQFUNCTION option which accepts a callable that gets
+    called after a connection is established (including TLS handshake), but
+    before the request is made. The function is called with the CurlHandle
+    object, primary IP, local IP, primary port, and the local port, and it
+    must return CURL_PREREQFUNC_OK or CURL_PREREQFUNC_ABORT to allow or abort
+    the request.
 
 - Date:
   . Added static methods
@@ -513,6 +519,11 @@ PHP 8.4 UPGRADE NOTES
 - Core:
   . PHP_OUTPUT_HANDLER_PROCESSED.
 
+- Curl:
+  . CURLOPT_PREREQFUNCTION.
+  . CURL_PREREQFUNC_OK.
+  . CURL_PREREQFUNC_ABORT.
+
 - Intl:
   . The IntlDateFormatter class exposes now the new PATTERN constant
     reflecting udat api's UDAT_PATTERN.
diff --git a/ext/curl/curl.stub.php b/ext/curl/curl.stub.php
@@ -3485,6 +3485,21 @@
  * @cvalue CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256
  */
 const CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 = UNKNOWN;
+/**
+ * @var int
+ * @cvalue CURLOPT_PREREQFUNCTION
+ */
+const CURLOPT_PREREQFUNCTION = UNKNOWN;
+/**
+ * @var int
+ * @cvalue CURL_PREREQFUNC_OK
+ */
+const CURL_PREREQFUNC_OK = UNKNOWN;
+/**
+ * @var int
+ * @cvalue CURL_PREREQFUNC_ABORT
+ */
+const CURL_PREREQFUNC_ABORT = UNKNOWN;
 #endif
 
 #if LIBCURL_VERSION_NUM >= 0x075100 /* Available since 7.81.0 */
diff --git a/ext/curl/curl_arginfo.h b/ext/curl/curl_arginfo.h
diff --git a/ext/curl/curl_private.h b/ext/curl/curl_private.h
@@ -74,6 +74,9 @@ typedef struct {
 	zval               std_err;
 	php_curl_callback *progress;
 	php_curl_callback  *xferinfo;
+#if LIBCURL_VERSION_NUM >= 0x075000 /* 7.80.0 */
+	php_curl_callback  *prereq;
+#endif
 	php_curl_callback  *fnmatch;
 #if LIBCURL_VERSION_NUM >= 0x075400 /* Available since 7.84.0 */
 	php_curl_callback  *sshhostkey;
diff --git a/ext/curl/interface.c b/ext/curl/interface.c
@@ -496,6 +496,12 @@ static HashTable *curl_get_gc(zend_object *object, zval **table, int *n)
 		zend_get_gc_buffer_add_zval(gc_buffer, &curl->handlers.xferinfo->func_name);
 	}
 
+#if LIBCURL_VERSION_NUM >= 0x075000 /* Available since 7.80.0 */
+	if (curl->handlers.prereq) {
+		zend_get_gc_buffer_add_zval(gc_buffer, &curl->handlers.prereq->func_name);
+	}
+#endif
+
 	if (curl->handlers.fnmatch) {
 		zend_get_gc_buffer_add_zval(gc_buffer, &curl->handlers.fnmatch->func_name);
 	}
@@ -939,6 +945,64 @@ static size_t curl_write_header(char *data, size_t size, size_t nmemb, void *ctx
 }
 /* }}} */
 
+#if LIBCURL_VERSION_NUM >= 0x075000 /* Available since 7.80.0 */
+static int curl_prereqfunction(void *clientp, char *conn_primary_ip, char *conn_local_ip, int conn_primary_port, int conn_local_port)
+{
+	php_curl *ch = (php_curl *)clientp;
+	php_curl_callback *t = ch->handlers.prereq;
+
+	int rval = CURL_PREREQFUNC_ABORT; /* Disallow the request by default. */
+
+#if PHP_CURL_DEBUG
+	fprintf(stderr, "curl_prereqfunction() called\n");
+	fprintf(stderr, "clientp = %x, conn_primary_ip = %s, conn_local_ip = %s, conn_primary_port = %d, conn_local_port = %d\n", clientp, conn_primary_ip, conn_local_ip, c, onn_primary_port, conn_local_port);
+#endif
+
+	zval argv[5];
+	zval retval;
+
+	zend_fcall_info fci;
+
+	GC_ADDREF(&ch->std);
+	ZVAL_OBJ(&argv[0], &ch->std);
+	ZVAL_STRING(&argv[1], conn_primary_ip);
+	ZVAL_STRING(&argv[2], conn_local_ip);
+	ZVAL_LONG(&argv[3], conn_primary_port);
+	ZVAL_LONG(&argv[4], conn_local_port);
+
+	fci.size = sizeof(fci);
+	ZVAL_COPY_VALUE(&fci.function_name, &t->func_name);
+	fci.object = NULL;
+	fci.retval = &retval;
+	fci.param_count = 5;
+	fci.params = argv;
+	fci.named_params = NULL;
+
+	ch->in_callback = 1;
+	zend_call_function(&fci, &t->fci_cache);
+	ch->in_callback = 0;
+	if (!Z_ISUNDEF(retval)) {
+		_php_curl_verify_handlers(ch, true);
+		if (Z_TYPE(retval) == IS_LONG) {
+			zend_long retval_long = Z_LVAL(retval);
+			if (retval_long == CURL_PREREQFUNC_OK || retval_long == CURL_PREREQFUNC_ABORT) {
+				rval = retval_long;
+			} else {
+				zend_throw_error(NULL, "The CURLOPT_PREREQFUNCTION callback must return either CURL_PREREQFUNC_OK or CURL_PREREQFUNC_ABORT");
+			}
+		} else {
+			zend_throw_error(NULL, "The CURLOPT_PREREQFUNCTION callback must return either CURL_PREREQFUNC_OK or CURL_PREREQFUNC_ABORT");
+		}
+	}
+	zval_ptr_dtor(&argv[0]);
+	zval_ptr_dtor(&argv[1]);
+	zval_ptr_dtor(&argv[2]);
+
+	return rval;
+}
+
+#endif
+
 static int curl_debug(CURL *cp, curl_infotype type, char *buf, size_t buf_len, void *ctx) /* {{{ */
 {
 	php_curl *ch = (php_curl *)ctx;
@@ -1120,6 +1184,9 @@ void init_curl_handle(php_curl *ch)
 	ch->handlers.progress = NULL;
 	ch->handlers.xferinfo = NULL;
 	ch->handlers.fnmatch = NULL;
+#if LIBCURL_VERSION_NUM >= 0x075000 /* Available since 7.80.0 */
+	ch->handlers.prereq = NULL;
+#endif
 #if LIBCURL_VERSION_NUM >= 0x075400 /* Available since 7.84.0 */
 	ch->handlers.sshhostkey = NULL;
 #endif
@@ -1296,6 +1363,9 @@ void _php_setup_easy_copy_handlers(php_curl *ch, php_curl *source)
 	_php_copy_callback(ch, &ch->handlers.progress, source->handlers.progress, CURLOPT_PROGRESSDATA);
 	_php_copy_callback(ch, &ch->handlers.xferinfo, source->handlers.xferinfo, CURLOPT_XFERINFODATA);
 	_php_copy_callback(ch, &ch->handlers.fnmatch, source->handlers.fnmatch, CURLOPT_FNMATCH_DATA);
+#if LIBCURL_VERSION_NUM >= 0x075000 /* Available since 7.80.0 */
+	_php_copy_callback(ch, &ch->handlers.prereq, source->handlers.prereq, CURLOPT_PREREQFUNCTION);
+#endif
 #if LIBCURL_VERSION_NUM >= 0x075400 /* Available since 7.84.0 */
 	_php_copy_callback(ch, &ch->handlers.sshhostkey, source->handlers.sshhostkey, CURLOPT_SSH_HOSTKEYDATA);
 #endif
@@ -2206,6 +2276,20 @@ static zend_result _php_curl_setopt(php_curl *ch, zend_long option, zval *zvalue
 			ZVAL_COPY(&ch->handlers.xferinfo->func_name, zvalue);
 			break;
 
+#if LIBCURL_VERSION_NUM >= 0x075000 /* Available since 7.80.0 */
+		case CURLOPT_PREREQFUNCTION:
+			curl_easy_setopt(ch->cp, CURLOPT_PREREQFUNCTION,	curl_prereqfunction);
+			curl_easy_setopt(ch->cp, CURLOPT_PREREQDATA, ch);
+			if (ch->handlers.prereq == NULL) {
+				ch->handlers.prereq = ecalloc(1, sizeof(php_curl_callback));
+			} else if (!Z_ISUNDEF(ch->handlers.prereq->func_name)) {
+				zval_ptr_dtor(&ch->handlers.prereq->func_name);
+				ch->handlers.prereq->fci_cache = empty_fcall_info_cache;
+			}
+			ZVAL_COPY(&ch->handlers.prereq->func_name, zvalue);
+			break;
+#endif
+
 		/* Curl off_t options */
 		case CURLOPT_MAX_RECV_SPEED_LARGE:
 		case CURLOPT_MAX_SEND_SPEED_LARGE:
@@ -2849,6 +2933,9 @@ static void curl_free_obj(zend_object *object)
 #if LIBCURL_VERSION_NUM >= 0x075400 /* Available since 7.84.0 */
 	_php_curl_free_callback(ch->handlers.sshhostkey);
 #endif
+#if LIBCURL_VERSION_NUM >= 0x075000 /* Available since 7.80.0 */
+	_php_curl_free_callback(ch->handlers.prereq);
+#endif
 
 	zval_ptr_dtor(&ch->postfields);
 	zval_ptr_dtor(&ch->private_data);
@@ -2923,6 +3010,14 @@ static void _php_curl_reset_handlers(php_curl *ch)
 		ch->handlers.xferinfo = NULL;
 	}
 
+#if LIBCURL_VERSION_NUM >= 0x075000 /* Available since 7.80.0 */
+	if (ch->handlers.prereq) {
+		zval_ptr_dtor(&ch->handlers.prereq->func_name);
+		efree(ch->handlers.prereq);
+		ch->handlers.prereq = NULL;
+	}
+#endif
+
 	if (ch->handlers.fnmatch) {
 		zval_ptr_dtor(&ch->handlers.fnmatch->func_name);
 		efree(ch->handlers.fnmatch);
diff --git a/ext/curl/tests/curl_setopt_CURLOPT_PREREQFUNCTION.phpt b/ext/curl/tests/curl_setopt_CURLOPT_PREREQFUNCTION.phpt
@@ -0,0 +1,61 @@
+--TEST--
+Curl option CURLOPT_PREREQFUNCTION
+--EXTENSIONS--
+curl
+--SKIPIF--
+<?php
+$curl_version = curl_version();
+if ($curl_version['version_number'] < 0x075000) die("skip: test works only with curl >= 7.80.0");
+?>
+--FILE--
+<?php
+include 'server.inc';
+
+$host = curl_cli_server_start();
+$port = (int) (explode(':', $host))[1];
+
+$ch = curl_init();
+curl_setopt($ch, CURLOPT_URL, $host);
+curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
+//curl_setopt($ch, CURLOPT_IPRESOLVE, CURL_IPRESOLVE_V4);
+
+var_dump(CURLOPT_PREREQFUNCTION);
+var_dump(CURL_PREREQFUNC_OK);
+var_dump(CURL_PREREQFUNC_ABORT);
+
+curl_setopt($ch, CURLOPT_PREREQFUNCTION, function() use ($port) {
+	var_dump('callback');
+	var_dump(func_num_args());
+	$args = func_get_args();
+	var_dump(get_class($args[0]));
+	var_dump(filter_var($args[1], FILTER_VALIDATE_IP) !== false);
+	var_dump(filter_var($args[2], FILTER_VALIDATE_IP) !== false);
+	var_dump($port === $args[3]);
+	var_dump(is_int($args[4]));
+
+	return CURL_PREREQFUNC_ABORT;
+});
+
+$result = curl_exec($ch);
+
+var_dump($result);
+var_dump(curl_error($ch));
+var_dump(curl_errno($ch));
+
+var_dump('finished');
+?>
+--EXPECT--
+int(20312)
+int(0)
+int(1)
+string(8) "callback"
+int(5)
+string(10) "CurlHandle"
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(false)
+string(41) "operation aborted by pre-request callback"
+int(42)
+string(8) "finished"
