feat: enable persistent CurlShareHandle objects

This commit introduces a new function, curl_share_init_persistent, that
creates a php_curlsh struct that can live beyond a single PHP request.

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

I created a new function instead of reusing the existing curl_share_init
function since it also takes an array of curl_share_setopt options to
set when the persistent handle doesn't yet exist.

It is noteworthy that calling curl_share_setopt on the persistent handle
would affect future requests using the handle; we could consider
preventing this.

It is also noteworthy that changing the persistent share options would
not take effect if the persistent share already existed; changing the
persistent share ID would be sufficient to resolve that.

Author: ericnorris

ext/curl/curl.stub.php

@@ -3665,6 +3665,9 @@ function curl_share_errno(CurlShareHandle $share_handle): int {}
 /** @refcount 1 */
 function curl_share_init(): CurlShareHandle {}
 
+/** @refcount 1 */
+function curl_share_init_persistent(string $persistent_id, array $shares): CurlShareHandle|false {}
+
 function curl_share_setopt(CurlShareHandle $share_handle, int $option, mixed $value): bool {}
 
 /** @refcount 1 */

ext/curl/curl_arginfo.h

@@ -121,10 +121,13 @@ typedef struct {
 } php_curlm;
 
 typedef struct _php_curlsh {
-	CURLSH                   *share;
+	CURLSH	  *share;
+	zend_bool is_persistent;
+
 	struct {
 		int no;
 	} err;
+
 	zend_object std;
 } php_curlsh;
 
@@ -148,7 +151,8 @@ static inline php_curlsh *curl_share_from_obj(zend_object *obj) {
 #define Z_CURL_SHARE_P(zv) curl_share_from_obj(Z_OBJ_P(zv))
 
 void curl_multi_register_handlers(void);
-void curl_share_register_handlers(void);
+void curl_share_register_handlers(int);
+void curl_share_free_obj(zend_object *object);
 void curlfile_register_class(void);
 zend_result curl_cast_object(zend_object *obj, zval *result, int type);
 

ext/curl/curl_private.h

@@ -409,7 +409,7 @@ PHP_MINIT_FUNCTION(curl)
 	curl_multi_register_handlers();
 
 	curl_share_ce = register_class_CurlShareHandle();
-	curl_share_register_handlers();
+	curl_share_register_handlers(module_number);
 	curlfile_register_class();
 
 	return SUCCESS;

ext/curl/interface.c

@@ -28,6 +28,69 @@
 
 #define SAVE_CURLSH_ERROR(__handle, __err) (__handle)->err.no = (int) __err;
 
+static int le_pcurlsh;
+
+/* {{{ Initialize a persistent curl share handle */
+PHP_FUNCTION(curl_share_init_persistent)
+{
+	php_curlsh *sh;
+
+	zend_string *persistent_id  = NULL;
+	zend_string *persistent_key = NULL;
+
+	zend_resource *persisted;
+
+	zval *arr, *entry;
+
+	ZEND_PARSE_PARAMETERS_START(2, 2)
+		Z_PARAM_STR_EX(persistent_id, 1, 0)
+		Z_PARAM_ARRAY(arr)
+	ZEND_PARSE_PARAMETERS_END();
+
+	persistent_key = strpprintf(0, "curl_share_init_persistent:id=%s", ZSTR_VAL(persistent_id));
+
+	object_init_ex(return_value, curl_share_ce);
+
+	sh = Z_CURL_SHARE_P(return_value);
+
+	if ((persisted = zend_hash_find_ptr(&EG(persistent_list), persistent_key)) != NULL) {
+		if (persisted->type == le_pcurlsh) {
+			sh->share         = persisted->ptr;
+			sh->is_persistent = 1;
+
+			goto cleanup;
+		}
+	}
+
+	sh->share = curl_share_init();
+
+	ZEND_HASH_FOREACH_VAL(Z_ARRVAL_P(arr), entry) {
+		ZVAL_DEREF(entry);
+
+		CURLSHcode error = curl_share_setopt(sh->share, CURLSHOPT_SHARE, zval_get_long(entry));
+
+		if (error != CURLSHE_OK) {
+			php_error_docref(NULL, E_WARNING, "could not construct persistent curl share: %s", curl_share_strerror(error));
+			goto error;
+		}
+	} ZEND_HASH_FOREACH_END();
+
+	zend_register_persistent_resource(ZSTR_VAL(persistent_key), ZSTR_LEN(persistent_key), sh->share, le_pcurlsh);
+
+	sh->is_persistent = 1;
+
+ cleanup:
+	zend_string_release(persistent_key);
+	return;
+
+ error:
+	zend_string_release(persistent_key);
+	curl_share_free_obj(Z_OBJ_P(return_value));
+
+	RETURN_FALSE;
+}
+/* }}} */
+
 /* {{{ Initialize a share curl handle */
 PHP_FUNCTION(curl_share_init)
 {
@@ -42,6 +105,14 @@ PHP_FUNCTION(curl_share_init)
 }
 /* }}} */
 
+ZEND_RSRC_DTOR_FUNC(php_pcurlsh_dtor)
+{
+	if (res->ptr) {
+		curl_share_cleanup(res->ptr);
+		res->ptr = NULL;
+	}
+}
+
 /* {{{ Close a set of cURL handles */
 PHP_FUNCTION(curl_share_close)
 {
@@ -79,7 +150,7 @@ static bool _php_curl_share_setopt(php_curlsh *sh, zend_long option, zval *zvalu
 PHP_FUNCTION(curl_share_setopt)
 {
 	zval       *z_sh, *zvalue;
-	zend_long        options;
+	zend_long  options;
 	php_curlsh *sh;
 
 	ZEND_PARSE_PARAMETERS_START(3,3)
@@ -101,8 +172,8 @@ PHP_FUNCTION(curl_share_setopt)
 /* {{{ Return an integer containing the last share curl error number */
 PHP_FUNCTION(curl_share_errno)
 {
-	zval        *z_sh;
-	php_curlsh  *sh;
+	zval       *z_sh;
+	php_curlsh *sh;
 
 	ZEND_PARSE_PARAMETERS_START(1,1)
 		Z_PARAM_OBJECT_OF_CLASS(z_sh, curl_share_ce)
@@ -154,13 +225,16 @@ void curl_share_free_obj(zend_object *object)
 {
 	php_curlsh *sh = curl_share_from_obj(object);
 
-	curl_share_cleanup(sh->share);
+	if (!sh->is_persistent) {
+		curl_share_cleanup(sh->share);
+	}
+
 	zend_object_std_dtor(&sh->std);
 }
 
 static zend_object_handlers curl_share_handlers;
 
-void curl_share_register_handlers(void) {
+void curl_share_register_handlers(int module_number) {
 	curl_share_ce->create_object = curl_share_create_object;
 	curl_share_ce->default_object_handlers = &curl_share_handlers;
 
@@ -170,4 +244,6 @@ void curl_share_register_handlers(void) {
 	curl_share_handlers.get_constructor = curl_share_get_constructor;
 	curl_share_handlers.clone_obj = NULL;
 	curl_share_handlers.compare = zend_objects_not_comparable;
+
+	le_pcurlsh = zend_register_list_destructors_ex(NULL, php_pcurlsh_dtor, "Curl persistent shared handle", module_number);
 }