feat: add CurlPersistentShareHandle

This commit introduces a new function, curl_persistent_share_init, that
creates a persistent curl share handle by storing it within a hash table
in the curl module's global variables.

Persisting a curl share handle allows PHP userspace to cache things like
DNS lookups or connections between multiple PHP requests, thus reducing
work for subsequent requests.

The function takes an array of CURL_LOCK_DATA_* constants, which are used
to either construct a new curl share handle with the given options, or
to find an existing one with the same set of options.

CURL_LOCK_DATA_COOKIE is not allowed here, however, as it is considered
unsafe; a developer could accidentally share a user's cookies from an
earlier request when handling a subsequent from a different user.

Author: ericnorris

Zend/Optimizer/zend_func_infos.h

@@ -47,6 +47,7 @@ static const func_info_t func_infos[] = {
 	F1("curl_share_init", MAY_BE_OBJECT),
 	F1("curl_share_strerror", MAY_BE_STRING|MAY_BE_NULL),
 	F1("curl_strerror", MAY_BE_STRING|MAY_BE_NULL),
+	F1("curl_persistent_share_init", MAY_BE_OBJECT),
 	F1("curl_version", MAY_BE_ARRAY|MAY_BE_ARRAY_KEY_STRING|MAY_BE_ARRAY_OF_LONG|MAY_BE_ARRAY_OF_STRING|MAY_BE_ARRAY_OF_ARRAY|MAY_BE_FALSE),
 	F1("date", MAY_BE_STRING),
 	F1("gmdate", MAY_BE_STRING),

ext/curl/curl.stub.php

@@ -3668,6 +3668,14 @@ final class CurlShareHandle
 {
 }
 
+/**
+ * @strict-properties
+ * @not-serializable
+ */
+final class CurlPersistentShareHandle
+{
+}
+
 function curl_close(CurlHandle $handle): void {}
 
 /** @refcount 1 */
@@ -3753,6 +3761,9 @@ function curl_share_strerror(int $error_code): ?string {}
 /** @refcount 1 */
 function curl_strerror(int $error_code): ?string {}
 
+/** @refcount 1 */
+function curl_persistent_share_init(array $share_options): CurlPersistentShareHandle {}
+
 /**
  * @return array<string, int|string|array>|false
  * @refcount 1

ext/curl/curl_arginfo.h

@@ -40,9 +40,20 @@
 #define SAVE_CURL_ERROR(__handle, __err) \
     do { (__handle)->err.no = (int) __err; } while (0)
 
+
+ZEND_BEGIN_MODULE_GLOBALS(curl)
+	HashTable persistent_curlsh;
+ZEND_END_MODULE_GLOBALS(curl)
+
+ZEND_EXTERN_MODULE_GLOBALS(curl)
+
+#define CURL_G(v) ZEND_MODULE_GLOBALS_ACCESSOR(curl, v)
+
 PHP_MINIT_FUNCTION(curl);
 PHP_MSHUTDOWN_FUNCTION(curl);
 PHP_MINFO_FUNCTION(curl);
+PHP_GINIT_FUNCTION(curl);
+PHP_GSHUTDOWN_FUNCTION(curl);
 
 typedef struct {
 	zend_fcall_info_cache fcc;
@@ -125,11 +136,13 @@ typedef struct {
 } php_curlm;
 
 typedef struct _php_curlsh {
-	CURLSH                   *share;
+	CURLSH *share;
+
 	struct {
 		int no;
 	} err;
-	zend_object std;
+
+    zend_object std;
 } php_curlsh;
 
 php_curl *init_curl_handle_into_zval(zval *curl);
@@ -153,6 +166,8 @@ static inline php_curlsh *curl_share_from_obj(zend_object *obj) {
 
 void curl_multi_register_handlers(void);
 void curl_share_register_handlers(void);
+void curl_share_free_persistent_curlsh(zval *data);
+void curl_persistent_share_register_handlers(void);
 void curlfile_register_class(void);
 zend_result curl_cast_object(zend_object *obj, zval *result, int type);
 

ext/curl/curl_private.h

@@ -67,6 +67,8 @@
 
 #include "curl_arginfo.h"
 
+ZEND_DECLARE_MODULE_GLOBALS(curl)
+
 #ifdef PHP_CURL_NEED_OPENSSL_TSL /* {{{ */
 static MUTEX_T *php_curl_openssl_tsl = NULL;
 
@@ -215,18 +217,34 @@ zend_module_entry curl_module_entry = {
 	NULL,
 	PHP_MINFO(curl),
 	PHP_CURL_VERSION,
-	STANDARD_MODULE_PROPERTIES
+	PHP_MODULE_GLOBALS(curl),
+	PHP_GINIT(curl),
+	PHP_GSHUTDOWN(curl),
+	NULL,
+	STANDARD_MODULE_PROPERTIES_EX
 };
 /* }}} */
 
 #ifdef COMPILE_DL_CURL
 ZEND_GET_MODULE (curl)
 #endif
 
+PHP_GINIT_FUNCTION(curl)
+{
+	zend_hash_init(&curl_globals->persistent_curlsh, 0, NULL, curl_share_free_persistent_curlsh, true);
+	GC_MAKE_PERSISTENT_LOCAL(&curl_globals->persistent_curlsh);
+}
+
+PHP_GSHUTDOWN_FUNCTION(curl)
+{
+	zend_hash_destroy(&curl_globals->persistent_curlsh);
+}
+
 /* CurlHandle class */
 
 zend_class_entry *curl_ce;
 zend_class_entry *curl_share_ce;
+zend_class_entry *curl_persistent_share_ce;
 static zend_object_handlers curl_object_handlers;
 
 static zend_object *curl_create_object(zend_class_entry *class_type);
@@ -410,6 +428,10 @@ PHP_MINIT_FUNCTION(curl)
 
 	curl_share_ce = register_class_CurlShareHandle();
 	curl_share_register_handlers();
+
+	curl_persistent_share_ce = register_class_CurlPersistentShareHandle();
+	curl_persistent_share_register_handlers();
+
 	curlfile_register_class();
 
 	return SUCCESS;
@@ -2276,16 +2298,24 @@ static zend_result _php_curl_setopt(php_curl *ch, zend_long option, zval *zvalue
 
 		case CURLOPT_SHARE:
 			{
-				if (Z_TYPE_P(zvalue) == IS_OBJECT && Z_OBJCE_P(zvalue) == curl_share_ce) {
-					php_curlsh *sh = Z_CURL_SHARE_P(zvalue);
-					curl_easy_setopt(ch->cp, CURLOPT_SHARE, sh->share);
+				if (Z_TYPE_P(zvalue) != IS_OBJECT) {
+					break;
+				}
 
-					if (ch->share) {
-						OBJ_RELEASE(&ch->share->std);
-					}
-					GC_ADDREF(&sh->std);
-					ch->share = sh;
+				if (Z_OBJCE_P(zvalue) != curl_share_ce && Z_OBJCE_P(zvalue) != curl_persistent_share_ce) {
+					break;
 				}
+
+				php_curlsh *sh = Z_CURL_SHARE_P(zvalue);
+
+				curl_easy_setopt(ch->cp, CURLOPT_SHARE, sh->share);
+
+				if (ch->share) {
+					OBJ_RELEASE(&ch->share->std);
+				}
+
+				GC_ADDREF(&sh->std);
+				ch->share = sh;
 			}
 			break;
 

ext/curl/interface.c

@@ -37,6 +37,7 @@ extern zend_module_entry curl_module_entry;
 
 PHP_CURL_API extern zend_class_entry *curl_ce;
 PHP_CURL_API extern zend_class_entry *curl_share_ce;
+PHP_CURL_API extern zend_class_entry *curl_persistent_share_ce;
 PHP_CURL_API extern zend_class_entry *curl_multi_ce;
 PHP_CURL_API extern zend_class_entry *curl_CURLFile_class;
 PHP_CURL_API extern zend_class_entry *curl_CURLStringFile_class;

ext/curl/php_curl.h

@@ -21,6 +21,7 @@
 #endif
 
 #include "php.h"
+#include "Zend/zend_exceptions.h"
 
 #include "curl_private.h"
 
@@ -134,6 +135,109 @@ PHP_FUNCTION(curl_share_strerror)
 }
 /* }}} */
 
+/**
+ * Initialize a persistent curl share handle with the given share options, reusing an existing one if found.
+ *
+ * Throws an exception if the share options are invalid.
+ */
+PHP_FUNCTION(curl_persistent_share_init)
+{
+	zval *share_opts = NULL, *entry = NULL;
+	zend_ulong persistent_id = 0;
+
+	php_curlsh *sh;
+
+	CURLSHcode error;
+
+	ZEND_PARSE_PARAMETERS_START(1, 1)
+		Z_PARAM_ARRAY(share_opts)
+	ZEND_PARSE_PARAMETERS_END();
+
+	object_init_ex(return_value, curl_persistent_share_ce);
+	sh = Z_CURL_SHARE_P(return_value);
+
+	ZEND_HASH_FOREACH_VAL(Z_ARRVAL_P(share_opts), entry) {
+		ZVAL_DEREF(entry);
+
+		zend_ulong option = zval_get_long_ex(entry, true);
+
+		if (option == CURL_LOCK_DATA_COOKIE) {
+			zend_throw_exception_ex(
+				NULL,
+				0,
+				"CURL_LOCK_DATA_COOKIE is not allowed with persistent curl share handles"
+			);
+
+			goto error;
+		}
+
+		// Ensure that each additional option results in a unique persistent ID.
+		persistent_id += 1 << option;
+	} ZEND_HASH_FOREACH_END();
+
+	if (persistent_id) {
+		zval *persisted = zend_hash_index_find(&CURL_G(persistent_curlsh), persistent_id);
+
+		if (persisted) {
+			sh->share = Z_PTR_P(persisted);
+
+			return;
+		}
+	}
+
+	// We could not find an existing share handle, so we'll have to create one.
+	sh->share = curl_share_init();
+
+	// Apply $share_options to the handle.
+	ZEND_HASH_FOREACH_VAL(Z_ARRVAL_P(share_opts), entry) {
+		ZVAL_DEREF(entry);
+
+		error = curl_share_setopt(sh->share, CURLSHOPT_SHARE, zval_get_long(entry));
+
+		if (error != CURLSHE_OK) {
+			zend_throw_exception_ex(
+				NULL,
+				0,
+				"Could not construct persistent cURL share handle: %s",
+				curl_share_strerror(error)
+			);
+
+			goto error;
+		}
+	} ZEND_HASH_FOREACH_END();
+
+	zend_hash_index_add_new_ptr(
+		&CURL_G(persistent_curlsh),
+		persistent_id,
+		sh->share
+	);
+
+	return;
+
+ error:
+	if (sh->share) {
+		curl_share_cleanup(sh->share);
+	}
+
+	RETURN_THROWS();
+}
+
+/**
+ * Free a persistent curl share handle from the module global HashTable.
+ *
+ * See PHP_GINIT_FUNCTION in ext/curl/interface.c.
+ */
+void curl_share_free_persistent_curlsh(zval *data)
+{
+	CURLSH *handle = Z_PTR_P(data);
+
+	if (!handle) {
+		return;
+	}
+
+	curl_share_cleanup(handle);
+}
+
 /* CurlShareHandle class */
 
 static zend_object *curl_share_create_object(zend_class_entry *class_type) {
@@ -171,3 +275,23 @@ void curl_share_register_handlers(void) {
 	curl_share_handlers.clone_obj = NULL;
 	curl_share_handlers.compare = zend_objects_not_comparable;
 }
+
+/* CurlPersistentShareHandle class */
+
+static zend_function *curl_persistent_share_get_constructor(zend_object *object) {
+	zend_throw_error(NULL, "Cannot directly construct CurlPersistentShareHandle, use curl_persistent_share_init() instead");
+	return NULL;
+}
+
+static zend_object_handlers curl_persistent_share_handlers;
+
+void curl_persistent_share_register_handlers(void) {
+	curl_persistent_share_ce->create_object = curl_share_create_object;
+	curl_persistent_share_ce->default_object_handlers = &curl_persistent_share_handlers;
+
+	memcpy(&curl_persistent_share_handlers, &std_object_handlers, sizeof(zend_object_handlers));
+	curl_persistent_share_handlers.offset = XtOffsetOf(php_curlsh, std);
+	curl_persistent_share_handlers.get_constructor = curl_persistent_share_get_constructor;
+	curl_persistent_share_handlers.clone_obj = NULL;
+	curl_persistent_share_handlers.compare = zend_objects_not_comparable;
+}