rfc:curl_share_persistence

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
rfc:curl_share_persistence [2024/10/09 20:03] – first draft enorrisrfc:curl_share_persistence [2025/01/02 15:08] (current) – add link to curl_share_persistence_improvement RFC enorris
Line 1: Line 1:
 ====== PHP RFC: Add persistent curl share handles ====== ====== PHP RFC: Add persistent curl share handles ======
-  * Version: 1.0+  * Version: 1.3
   * Date: 2024-10-09   * Date: 2024-10-09
   * Author: Eric Norris, erictnorris@gmail.com   * Author: Eric Norris, erictnorris@gmail.com
-  * Status: Under Discussion+  * Status: Accepted
   * First Published at: http://wiki.php.net/rfc/curl_share_persistence   * First Published at: http://wiki.php.net/rfc/curl_share_persistence
 +  * Superseded by: http://wiki.php.net/rfc/curl_share_persistence_improvement
  
 ===== Introduction ===== ===== Introduction =====
Line 18: Line 19:
 ===== Proposal ===== ===== Proposal =====
  
-This RFC proposes to add a new function, ''curl_share_init_persistent($id, $share_options)'', that will construct a persistent curl share handle.+This RFC proposes to enable users to create persistent curl share handles, by modifying the signature of ''curl_share_init'' to accept a persistent ID: ''curl_share_init(?array $share_options, ?string $persistent_id)''.
  
-When called, the function will first check the global memory within the SAPI worker for an existing curl share handle. If found, the function will return immediately.+When called with a persistent ID, the function will first check the global memory within the SAPI worker for an existing curl share handle. If found, the function will return immediately.
  
 If a curl share handle does not already exist, the function will construct a new one, apply the given share options, store it in global memory, and return it. If a curl share handle does not already exist, the function will construct a new one, apply the given share options, store it in global memory, and return it.
  
-==== Why not add persistence to curl_share_init? ====+==== Safety ====
  
 +Since curl share handles are stateful, developers must consider whether a given ''CURL_LOCK_DATA_*'' constant is safe to use in a persistent context.
  
-I had originally attempted to add a single new optional ''$persistent_id'' parameter to ''curl_share_init'', and then to call ''curl_share_setopt'' on the handle to set share options separately. Unfortunately I ran into https://github.com/curl/curl/pull/14696, where it seems that curl was re-initializing some of the share options in a way that broke functionality. +  * ''CURL_LOCK_DATA_CONNECT'' and ''CURL_LOCK_DATA_SSL_SESSION'' is safe to use; curl will not reuse connections between ''CurlHandle'' objects unless the connection settings (e.g. TLS client certificates) match. 
- +  * ''CURL_LOCK_DATA_COOKIE'' is **not** safe to use when making downstream requests on behalf of users; developers must take care to ensure that authentication cookies, etc. are not shared between separate users. 
-This issue meant that I needed to set the share options only once in userland, which is difficult or impossible to do. I decided to introduce a new function where the PHP extension could safely know if it needed to apply the share options or not. +  * ''CURL_LOCK_DATA_DNS'' is safe to use. 
- +  * ''CURL_LOCK_DATA_PSL'' is safe to use.
-At the time of writing the RFC I have come up with a new alternative: we could change the signature of ''curl_share_init'' to ''curl_share_init(array|null $share_options, string|null $persistent_id)''. I don't have a strong opinion on either.+
  
 ===== Backward Incompatible Changes ===== ===== Backward Incompatible Changes =====
Line 39: Line 40:
 ===== Proposed PHP Version(s) ===== ===== Proposed PHP Version(s) =====
  
-Next PHP ''8.x'' release.+Next PHP minor release.
  
 ===== RFC Impact ===== ===== RFC Impact =====
Line 49: Line 50:
 ==== To Existing Extensions ==== ==== To Existing Extensions ====
  
-''ext/curl'' will have a new function.+''curl_share_init'' in ''ext/curl'' will have a new signature.
  
 ==== To Opcache ==== ==== To Opcache ====
Line 62: Line 63:
  
 None. None.
- 
-===== Open Issues ===== 
- 
-==== Persistence Implementation ==== 
- 
-My first attempt at a pull request used the ''EG(persistent_list)'' global variable, which uses "internal" (i.e. not directly exposed to userland) resources. I received feedback from **@cmb69** that this was deprecated, but https://wiki.php.net/rfc/resource_to_object_conversion does not directly address internal resources. These are currently still used in places like PDO and streams, even when they return objects to userland. 
- 
-Fortunately I was able to come up with an alternative implementation using ''ZEND_BEGIN_MODULE_GLOBALS'' instead, but it's unclear whether this is a better approach. I don't have a strong opinion on which method of persistence I use, only that I'm able to implement persistence at all. 
- 
-==== curl_share_close Behavior ==== 
- 
-From **@kocsismate**: 
- 
-<blockquote>I'm wondering if it would make sense to explicitly close persistent shares with curl_share_close? It's a no-op for regular shares, but it may be useful for persistent ones?</blockquote> 
  
 ===== Future Scope ===== ===== Future Scope =====
  
-  * As noted in the Open Issues, we may want to put together an RFC in the future for a new persistence API that avoids internal resources.+  * We may want to put together an RFC in the future for a new internal API for persistence.
  
-===== Proposed Voting Choices =====+===== Voting Choices =====
  
-This vote would require a ⅔ majority:+Voting started on 2024-10-24 and will end on 2024-11-08 00:00 UTC.
  
-^ Add curl share persistence in the next PHP 8.x ^ +This vote requires a ⅔ majority:
-|                                                |+
  
-This vote would require a simple majority: +<doodle title="Add curl_share_init(?array $share_options, ?string $persistent_id) in the next PHP minor release" auth="enorris" voteType="single" closed="true" closeon="2024-11-08T00:00:00Z"> 
- +   * Yes 
-^ Method signature ^^ +   * No 
-| curl_share_init_persistent(string $id, array $share_options) | curl_share_init(?array $share_options, ?string $persistent_id) |+</doodle>
  
 ===== Patches and Tests ===== ===== Patches and Tests =====
  
-  * Patch implementing ''curl_share_init_persistent'': https://github.com/php/php-src/pull/15603+  * https://github.com/php/php-src/pull/15603
  
 ===== Implementation ===== ===== Implementation =====
Line 103: Line 89:
  
   * https://wiki.php.net/rfc/resource_to_object_conversion   * https://wiki.php.net/rfc/resource_to_object_conversion
 +  * https://github.com/curl/curl/pull/1917 - curl pull request demonstrating their position on connection reuse with TLS settings
 ===== Rejected Features ===== ===== Rejected Features =====
  
rfc/curl_share_persistence.1728504212.txt.gz · Last modified: 2024/10/09 20:03 by enorris

Page Tools