Debian Codegraph @

vendor/guzzlehttp/guzzle/src/Handler/CurlMultiHandler.php

raw
1 <?php
2
3 namespace GuzzleHttp\Handler;
4
5 use Closure;
6 use GuzzleHttp\Promise as P;
7 use GuzzleHttp\Promise\Promise;
8 use GuzzleHttp\Promise\PromiseInterface;
9 use GuzzleHttp\TransportSharing;
10 use GuzzleHttp\Utils;
11 use Psr\Http\Message\RequestInterface;
12
13 /**
14 * Returns an asynchronous response using curl_multi_* functions.
15 *
16 * When using the CurlMultiHandler, custom curl options can be specified as an
17 * associative array of curl option constants mapping to values in the
18 * **curl** key of the provided request options.
19 *
20 * @final
21 */
22 class CurlMultiHandler
23 {
24 /**
25 * @var CurlFactoryInterface
26 */
27 private $factory;
28
29 /**
30 * @var CurlShareHandleState|null
31 */
32 private $shareHandleState;
33
34 /**
35 * @var int
36 */
37 private $selectTimeout;
38
39 /**
40 * @var int Will be higher than 0 when `curl_multi_exec` is still running.
41 */
42 private $active = 0;
43
44 /**
45 * @var array Request entry handles, indexed by handle id in `addRequest`.
46 *
47 * @see CurlMultiHandler::addRequest
48 */
49 private $handles = [];
50
51 /**
52 * @var array<int, float> An array of delay times, indexed by handle id in `addRequest`.
53 *
54 * @see CurlMultiHandler::addRequest
55 */
56 private $delays = [];
57
58 /**
59 * @var array<mixed> An associative array of CURLMOPT_* options and corresponding values for curl_multi_setopt()
60 */
61 private $options = [];
62
63 /** @var resource|\CurlMultiHandle */
64 private $_mh;
65
66 /**
67 * @var bool
68 */
69 private $executingMulti = false;
70
71 /**
72 * @var array<int, EasyHandle>
73 */
74 private $deferredCancels = [];
75
76 /**
77 * @var string|null Owner signature of the proxy tunnels the multi handle's
78 * connection cache may hold
79 */
80 private $proxyTunnelOwner;
81
82 /** @var array<string, int> Count of attached transfers per proxy tunnel signature. */
83 private $activeProxyTunnelSignatures = [];
84
85 /** @var array<int, string> Maps an attached handle id to its proxy tunnel signature. */
86 private $activeProxyTunnelHandles = [];
87
88 /**
89 * @var bool Guards against multi-handle recreation re-entrancy from
90 * processMessages (a retried transfer re-invokes the handler)
91 */
92 private $processingMessages = false;
93
94 /**
95 * This handler accepts the following options:
96 *
97 * - handle_factory: An optional factory used to create curl handles
98 * - transport_sharing: Optional transport sharing mode.
99 * - select_timeout: Optional timeout (in seconds) to block before timing
100 * out while selecting curl handles. Defaults to 1 second.
101 * - options: An associative array of CURLMOPT_* options and
102 * corresponding values for curl_multi_setopt()
103 */
104 public function __construct(array $options = [])
105 {
106 CurlShareHandleState::assertNoRequiredSharingCustomFactoryConflict($options, 'CurlMultiHandler');
107 $transportSharing = $options['transport_sharing'] ?? null;
108 $sharingMode = CurlShareHandleState::normalizeMode($transportSharing, 'transport_sharing');
109
110 if (\array_key_exists('handle_factory', $options) && $options['handle_factory'] !== null) {
111 $this->shareHandleState = null;
112 $this->factory = $options['handle_factory'];
113 } else {
114 $this->shareHandleState = $sharingMode !== TransportSharing::NONE
115 ? CurlShareHandleState::fromOption($transportSharing)
116 : null;
117
118 $this->factory = $this->shareHandleState !== null
119 ? new CurlFactory(50, $this->shareHandleState->mode, $this->shareHandleState->handle)
120 : new CurlFactory(50);
121 }
122
123 if (isset($options['select_timeout'])) {
124 $this->selectTimeout = $options['select_timeout'];
125 } elseif ($selectTimeout = Utils::getenv('GUZZLE_CURL_SELECT_TIMEOUT')) {
126 \trigger_deprecation('guzzlehttp/guzzle', '7.2', 'The GUZZLE_CURL_SELECT_TIMEOUT environment variable is deprecated; use the "select_timeout" option instead.');
127 $this->selectTimeout = (int) $selectTimeout;
128 } else {
129 $this->selectTimeout = 1;
130 }
131
132 $this->options = $options['options'] ?? [];
133
134 // unsetting the property forces the first access to go through
135 // __get().
136 unset($this->_mh);
137 }
138
139 /**
140 * @param string $name
141 *
142 * @return resource|\CurlMultiHandle
143 *
144 * @throws \BadMethodCallException when another field as `_mh` will be gotten
145 * @throws \RuntimeException when curl can not initialize a multi handle
146 */
147 public function __get($name)
148 {
149 if ($name !== '_mh') {
150 throw new \BadMethodCallException("Can not get other property as '_mh'.");
151 }
152
153 $multiHandle = \curl_multi_init();
154
155 if (false === $multiHandle) {
156 throw new \RuntimeException('Can not initialize curl multi handle.');
157 }
158
159 $this->_mh = $multiHandle;
160
161 foreach ($this->options as $option => $value) {
162 // A warning is raised in case of a wrong option.
163 curl_multi_setopt($this->_mh, $option, $value);
164 }
165
166 return $this->_mh;
167 }
168
169 public function __destruct()
170 {
171 if (isset($this->_mh)) {
172 try {
173 \curl_multi_close($this->_mh);
174 } catch (\Throwable $e) {
175 // Destructors must not throw.
176 } finally {
177 unset($this->_mh);
178 }
179 }
180 }
181
182 public function __invoke(RequestInterface $request, array $options): PromiseInterface
183 {
184 $easy = $this->factory->create($request, $options);
185 $this->applyProxyTunnelOwnership($easy);
186 $id = (int) $easy->handle;
187
188 $promise = new Promise(
189 [$this, 'execute'],
190 function () use ($id) {
191 return $this->cancel($id);
192 }
193 );
194
195 $this->addRequest(['easy' => $easy, 'deferred' => $promise]);
196
197 return $promise;
198 }
199
200 /**
201 * Isolates the connection cache when the request's proxy tunnel section
202 * differs from the one the multi handle's cache may already hold.
203 */
204 private function applyProxyTunnelOwnership(EasyHandle $easy): void
205 {
206 $signature = $easy->proxyTunnelSignature;
207 if ($signature === null || $signature === $this->proxyTunnelOwner) {
208 return;
209 }
210
211 if ($this->proxyTunnelOwner === null) {
212 // No in-domain transfer has ever run on this multi handle: latch
213 // the owner without destroying pooled direct connections.
214 $this->proxyTunnelOwner = $signature;
215
216 return;
217 }
218
219 if (
220 $this->handles === []
221 && !$this->executingMulti
222 && !$this->processingMessages
223 && $this->deferredCancels === []
224 ) {
225 // Idle: hand the connection cache over by recreating the multi
226 // handle (unsetting re-arms the lazy __get initializer, which
227 // re-applies the CURLMOPT_* options).
228 if (isset($this->_mh)) {
229 \curl_multi_close($this->_mh);
230 unset($this->_mh);
231 }
232 $this->proxyTunnelOwner = $signature;
233
234 return;
235 }
236
237 // Busy: isolate this transfer from the owner's pooled tunnels.
238 $this->isolateProxyTunnelTransfer($easy);
239 }
240
241 private function addCurlHandle(EasyHandle $easy): void
242 {
243 $this->isolateFromForeignActiveProxyTunnel($easy);
244 \curl_multi_add_handle($this->_mh, $easy->handle);
245 $this->markProxyTunnelActive($easy);
246 }
247
248 /**
249 * @param resource|\CurlHandle $handle
250 */
251 private function removeCompletedHandleFromMulti(int $id, $handle): void
252 {
253 \curl_multi_remove_handle($this->_mh, $handle);
254 $this->unmarkProxyTunnelActiveById($id);
255 }
256
257 private function isolateFromForeignActiveProxyTunnel(EasyHandle $easy): void
258 {
259 $signature = $easy->proxyTunnelSignature;
260
261 if ($signature === null || $this->activeProxyTunnelSignatures === []) {
262 return;
263 }
264
265 if (\count($this->activeProxyTunnelSignatures) === 1 && isset($this->activeProxyTunnelSignatures[$signature])) {
266 return;
267 }
268
269 $this->isolateProxyTunnelTransfer($easy);
270 }
271
272 private function isolateProxyTunnelTransfer(EasyHandle $easy): void
273 {
274 // Unqualified curl_setopt so the test bootstrap shadow records it.
275 curl_setopt($easy->handle, \CURLOPT_FRESH_CONNECT, true);
276 curl_setopt($easy->handle, \CURLOPT_FORBID_REUSE, true);
277 }
278
279 private function markProxyTunnelActive(EasyHandle $easy): void
280 {
281 $signature = $easy->proxyTunnelSignature;
282 if ($signature === null) {
283 return;
284 }
285
286 $id = (int) $easy->handle;
287 if (isset($this->activeProxyTunnelHandles[$id])) {
288 if ($this->activeProxyTunnelHandles[$id] === $signature) {
289 return;
290 }
291
292 $this->unmarkProxyTunnelActiveById($id);
293 }
294
295 $this->activeProxyTunnelHandles[$id] = $signature;
296 $this->activeProxyTunnelSignatures[$signature] = ($this->activeProxyTunnelSignatures[$signature] ?? 0) + 1;
297 }
298
299 private function unmarkProxyTunnelActive(EasyHandle $easy): void
300 {
301 $this->unmarkProxyTunnelActiveById((int) $easy->handle);
302 }
303
304 private function unmarkProxyTunnelActiveById(int $id): void
305 {
306 if (!isset($this->activeProxyTunnelHandles[$id])) {
307 return;
308 }
309
310 $signature = $this->activeProxyTunnelHandles[$id];
311 unset($this->activeProxyTunnelHandles[$id]);
312
313 if (!isset($this->activeProxyTunnelSignatures[$signature])) {
314 return;
315 }
316
317 --$this->activeProxyTunnelSignatures[$signature];
318
319 if ($this->activeProxyTunnelSignatures[$signature] <= 0) {
320 unset($this->activeProxyTunnelSignatures[$signature]);
321 }
322 }
323
324 /**
325 * Ticks the curl event loop.
326 */
327 public function tick(): void
328 {
329 // Add any delayed handles if needed.
330 if ($this->delays) {
331 $currentTime = Utils::currentTime();
332 foreach ($this->delays as $id => $delay) {
333 if ($currentTime >= $delay) {
334 unset($this->delays[$id]);
335 $this->addCurlHandle($this->handles[$id]['easy']);
336 }
337 }
338 }
339
340 // Run curl_multi_exec in the queue to enable other async tasks to run
341 P\Utils::queue()->add(Closure::fromCallable([$this, 'tickInQueue']));
342
343 // Step through the task queue which may add additional requests.
344 P\Utils::queue()->run();
345
346 if ($this->active && \curl_multi_select($this->_mh, $this->selectTimeout) === -1) {
347 // Perform a usleep if a select returns -1.
348 // See: https://bugs.php.net/bug.php?id=61141
349 \usleep(250);
350 }
351
352 do {
353 $this->executingMulti = true;
354
355 try {
356 $exec = \curl_multi_exec($this->_mh, $this->active);
357 } finally {
358 $this->executingMulti = false;
359 $this->cleanupDeferredCancels();
360 }
361
362 // Prevent busy looping for slow HTTP requests.
363 if ($exec === \CURLM_CALL_MULTI_PERFORM) {
364 \curl_multi_select($this->_mh, $this->selectTimeout);
365 }
366 } while ($exec === \CURLM_CALL_MULTI_PERFORM);
367
368 $this->processMessages();
369 }
370
371 /**
372 * Runs \curl_multi_exec() inside the event loop, to prevent busy looping
373 */
374 private function tickInQueue(): void
375 {
376 $this->executingMulti = true;
377
378 try {
379 $exec = \curl_multi_exec($this->_mh, $this->active);
380 } finally {
381 $this->executingMulti = false;
382 $this->cleanupDeferredCancels();
383 }
384
385 if ($exec === \CURLM_CALL_MULTI_PERFORM) {
386 \curl_multi_select($this->_mh, 0);
387 P\Utils::queue()->add(Closure::fromCallable([$this, 'tickInQueue']));
388 }
389 }
390
391 /**
392 * Runs until all outstanding connections have completed.
393 */
394 public function execute(): void
395 {
396 $queue = P\Utils::queue();
397
398 while ($this->handles || !$queue->isEmpty()) {
399 // If there are no transfers, then sleep for the next delay
400 if (!$this->active && $this->delays) {
401 \usleep($this->timeToNext());
402 }
403 $this->tick();
404 }
405 }
406
407 private function addRequest(array $entry): void
408 {
409 $easy = $entry['easy'];
410 $id = (int) $easy->handle;
411 $this->handles[$id] = $entry;
412 if (empty($easy->options['delay'])) {
413 $this->addCurlHandle($easy);
414 } else {
415 $this->delays[$id] = Utils::currentTime() + ($easy->options['delay'] / 1000);
416 }
417 }
418
419 /**
420 * Cancels a handle from sending and removes references to it.
421 *
422 * @param int $id Handle ID to cancel and remove.
423 *
424 * @return bool True on success, false on failure.
425 */
426 private function cancel($id): bool
427 {
428 if (!is_int($id)) {
429 \trigger_deprecation('guzzlehttp/guzzle', '7.4', 'Not passing an int to %s::%s() is deprecated and will cause an error in 8.0.', __CLASS__, __FUNCTION__);
430 }
431
432 // Cannot cancel if it has been processed.
433 if (!isset($this->handles[$id])) {
434 return false;
435 }
436
437 $easy = $this->handles[$id]['easy'];
438 unset($this->delays[$id], $this->handles[$id]);
439
440 if ($this->executingMulti) {
441 $this->deferredCancels[$id] = $easy;
442
443 return true;
444 }
445
446 $this->cleanupCancelledHandle($easy);
447
448 return true;
449 }
450
451 private function cleanupDeferredCancels(): void
452 {
453 if ($this->deferredCancels === []) {
454 return;
455 }
456
457 $entries = $this->deferredCancels;
458 $this->deferredCancels = [];
459
460 foreach ($entries as $easy) {
461 $this->cleanupCancelledHandle($easy);
462 }
463 }
464
465 private function cleanupCancelledHandle(EasyHandle $easy): void
466 {
467 $handle = $easy->handle;
468 \curl_multi_remove_handle($this->_mh, $handle);
469 $this->unmarkProxyTunnelActive($easy);
470
471 if (PHP_VERSION_ID < 80000) {
472 \curl_close($handle);
473 }
474 }
475
476 private function processMessages(): void
477 {
478 // CurlFactory::finish can retry a transfer by re-invoking this handler
479 // from inside this loop; the guard keeps that re-entry from recreating
480 // the multi handle mid-iteration (see applyProxyTunnelOwnership).
481 $this->processingMessages = true;
482
483 try {
484 while ($done = \curl_multi_info_read($this->_mh)) {
485 if ($done['msg'] !== \CURLMSG_DONE) {
486 // if it's not done, then it would be premature to remove the handle. ref https://github.com/guzzle/guzzle/pull/2892#issuecomment-945150216
487 continue;
488 }
489 if (!isset($done['handle'])) {
490 // Work around a PHP issue where cancelled transfers may omit the handle.
491 // Remove this once we no longer support PHP versions before the fix in
492 // https://github.com/php/php-src/pull/16302.
493 continue;
494 }
495 $id = (int) $done['handle'];
496 $this->removeCompletedHandleFromMulti($id, $done['handle']);
497
498 if (!isset($this->handles[$id])) {
499 // Probably was cancelled.
500 continue;
501 }
502
503 $entry = $this->handles[$id];
504 unset($this->handles[$id], $this->delays[$id]);
505 $entry['easy']->errno = $done['result'];
506
507 try {
508 $result = CurlFactory::finish($this, $entry['easy'], $this->factory);
509 } catch (\Throwable $e) {
510 $entry['deferred']->reject($e);
511
512 continue;
513 }
514
515 $entry['deferred']->resolve($result);
516 }
517 } finally {
518 $this->processingMessages = false;
519 }
520 }
521
522 private function timeToNext(): int
523 {
524 $currentTime = Utils::currentTime();
525 $nextTime = \PHP_INT_MAX;
526 foreach ($this->delays as $time) {
527 if ($time < $nextTime) {
528 $nextTime = $time;
529 }
530 }
531
532 return ((int) \max(0, $nextTime - $currentTime)) * 1000000;
533 }
534 }