From ab2b91d2e3a545f210e66cc7d6b065711ba8d1d9 Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:40:44 +0000 Subject: [PATCH 1/4] Run Guzzle CI on the Swoole nightly images Use the nightly image for each existing PHP job so the fork exercises current Swoole master. The fixed RC2 images remain available for release-specific verification. --- .github/workflows/ci.yml | 4 ++-- .github/workflows/static.yml | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e474586d4..6b88e9dc8 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -16,7 +16,7 @@ jobs: name: Build lowest version runs-on: ubuntu-24.04 container: - image: ghcr.io/hypervel/components-ci:php8.4-swoole6.3.0-rc1 + image: ghcr.io/hypervel/components-ci:php8.4-swoole-nightly steps: - name: Set up Node @@ -41,7 +41,7 @@ jobs: name: Build runs-on: ubuntu-24.04 container: - image: ghcr.io/hypervel/components-ci:php${{ matrix.php }}-swoole6.3.0-rc1 + image: ghcr.io/hypervel/components-ci:php${{ matrix.php }}-swoole-nightly strategy: fail-fast: false max-parallel: 10 diff --git a/.github/workflows/static.yml b/.github/workflows/static.yml index be2234387..d6ebd0e6f 100644 --- a/.github/workflows/static.yml +++ b/.github/workflows/static.yml @@ -16,7 +16,7 @@ jobs: name: PHPStan runs-on: ubuntu-24.04 container: - image: ghcr.io/hypervel/components-ci:php8.4-swoole6.3.0-rc1 + image: ghcr.io/hypervel/components-ci:php8.4-swoole-nightly steps: - name: Checkout code @@ -35,7 +35,7 @@ jobs: name: PHP-CS-Fixer runs-on: ubuntu-24.04 container: - image: ghcr.io/hypervel/components-ci:php8.4-swoole6.3.0-rc1 + image: ghcr.io/hypervel/components-ci:php8.4-swoole-nightly steps: - name: Checkout code @@ -54,7 +54,7 @@ jobs: name: Composer Normalize runs-on: ubuntu-24.04 container: - image: ghcr.io/hypervel/components-ci:php8.4-swoole6.3.0-rc1 + image: ghcr.io/hypervel/components-ci:php8.4-swoole-nightly steps: - name: Checkout code From 3a7ad941113a6d40601f7248817f43fab95df6bc Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Thu, 19 Nov 2026 00:00:14 +0000 Subject: [PATCH 2/4] Require Swoole 6.3.0 RC2 The fork accepted any Swoole version. It runs inside Hypervel components, so it should require the same Swoole version as the components release it supports; otherwise Composer can install it next to a Swoole build that components rejects. Components is moving to 6.3.0 RC2, and the coroutine cancellation handling in the next commit is written and tested against that release. Set ext-swoole to ^6.3.0RC2 and add a rule to AGENTS.md that keeps the constraint matched to the components version the branch supports. --- AGENTS.md | 2 ++ composer.json | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 4117b77b5..c0caf0143 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -126,6 +126,8 @@ sections of the README and `UPGRADING.md` describe the fork; the rest of runtime requirements are defined in `composer.json`. Preserve upstream's source style and formatting, including attribute placement and parameter commas; avoid unrelated syntax modernization. +- Match this fork's `require.ext-swoole` constraint to the one in the root + `composer.json` of the `hypervel/components` version this branch supports. - Regenerate `phpstan-baseline.neon` with `make static-phpstan-update-baseline` whenever an upstream merge conflicts in it. Investigate new errors before accepting baseline changes. diff --git a/composer.json b/composer.json index 463da7616..586248fe9 100644 --- a/composer.json +++ b/composer.json @@ -53,7 +53,7 @@ "require": { "php": "^8.4", "ext-json": "*", - "ext-swoole": "*", + "ext-swoole": "^6.3.0RC2", "guzzlehttp/psr7": "^3.4", "hypervel/guzzle-promises": "^3.1", "psr/http-client": "^1.0", From 0982f22d604cdf66afe12429c339870e61409305 Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Thu, 19 Nov 2026 00:00:47 +0000 Subject: [PATCH 3/4] Report coroutine cancellation instead of transfer errors Canceling a Swoole coroutine while it waits on a Guzzle request interrupts the wait, but the handlers reported it as an ordinary transfer failure: cURL error 42, a stream open or read error, or a RequestException wrapping the cancellation. Callers and retry middleware treated a canceled request like a network error and could retry it. When Swoole threw the CanceledException out of curl_exec(), CurlHandler also skipped finishing the transfer, so the easy handle and its connection stayed open until garbage collection. The handlers now report Swoole's CanceledException: - CurlHandler releases the handle and reports on_stats. If curl_exec() itself throws the cancellation, it is rethrown from the handler call as before, so promise-based middleware such as retries never sees it. A non-throwing cancel is recognized from error 42 when no callback aborted the transfer, and rejects with the cancellation. Aborts from a CURLOPT_PREREQFUNCTION passed through the curl option are now recorded so they keep their cURL error. A custom handle_factory keeps error 42, because its callbacks can abort with the same error. - CurlMultiHandler's select wait and its fallback sleep throw when cancellation interrupts them. tick() and execute() leave the other transfers running. A waited promise whose wait fails removes its own transfer instead of leaving it running unobserved. - StreamHandler recognizes an interrupted open and an interrupted read of the stock response stream. A stream notification callback can reset the coroutine's cancellation state before the open returns, so the state is captured before the callback runs. - Clock::sleep, used for request delays and deadline waits, throws when interrupted. - A cancellation thrown into on_headers, progress or on_trailers, a request body read, or a sink write is reported as is. The stock PSR-7 streams wrap a cancellation thrown during their I/O in a RuntimeException, so only those streams' immediate cause is unwrapped. An application exception or custom stream failure that carries a cancellation keeps its own meaning. A failed wait counts as canceled only when the coroutine is canceled and Swoole's last error is the cancellation code from that wait, so a cancel flag left over from an earlier, handled cancellation is not mistaken for a new one. The handler guide, exception guidelines, README and UPGRADING describe the behavior and the Swoole 6.3.0 RC2 requirement. The tests cancel real transfers inside coroutines, and a small stream wrapper raises the cancellation inside a read or write without depending on timing. --- README.md | 5 +- UPGRADING.md | 14 +- docs/contributing/exception-guidelines.md | 12 + docs/handlers.md | 32 +++ phpstan-baseline.neon | 2 +- src/Handler/CancelableTransportStream.php | 60 +++++ src/Handler/Clock.php | 12 + src/Handler/CoroutineCancellation.php | 66 ++++++ src/Handler/CurlFactory.php | 92 +++++++- src/Handler/CurlHandler.php | 29 ++- src/Handler/CurlMultiHandler.php | 38 +++- src/Handler/DeadlineSourceStream.php | 2 +- src/Handler/EasyHandle.php | 6 + src/Handler/RequestFraming.php | 18 +- src/Handler/StreamCancellation.php | 53 +++++ src/Handler/StreamHandler.php | 57 ++++- tests/CancelingStreamWrapper.php | 78 +++++++ tests/Handler/ClockTest.php | 31 +++ tests/Handler/CurlFactoryTest.php | 9 +- tests/Handler/CurlHandlerTest.php | 256 ++++++++++++++++++++++ tests/Handler/CurlMultiHandlerTest.php | 109 ++++++--- tests/Handler/RunsInCoroutines.php | 58 +++++ tests/Handler/StreamHandlerTest.php | 195 +++++++++++++++- 23 files changed, 1164 insertions(+), 70 deletions(-) create mode 100644 src/Handler/CancelableTransportStream.php create mode 100644 src/Handler/CoroutineCancellation.php create mode 100644 src/Handler/StreamCancellation.php create mode 100644 tests/CancelingStreamWrapper.php create mode 100644 tests/Handler/RunsInCoroutines.php diff --git a/README.md b/README.md index f4c5dff68..1bbe216f1 100644 --- a/README.md +++ b/README.md @@ -38,6 +38,9 @@ Guzzle client, including clients that SDKs create. This fork adds: send requests through it, tick, run or close it, or wait on or cancel its transfers: those calls throw a `LogicException` without changing the handler. See [Coroutine Ownership](docs/handlers.md#coroutine-ownership). +- **Coroutine cancellation.** Canceling a coroutine interrupts the request it is + waiting on and reports Swoole's `CanceledException` instead of a transfer + error. See [Coroutine Cancellation](docs/handlers.md#coroutine-cancellation). - **Transfer tracking.** When the promise task queue implements `ScopedTaskQueueInterface` from [`hypervel/guzzle-promises`](https://github.com/hypervel/guzzle-promises), the @@ -74,7 +77,7 @@ composer require hypervel/guzzle ## Version Guidance -This fork requires PHP 8.4 or newer and the Swoole extension. +This fork requires PHP 8.4 or newer and Swoole 6.3.0 RC2 or a later 6.x release. [composer.json](composer.json) lists the exact requirements. Each fork version is the upstream release it is based on plus a fork release number. For example, `8.2.0.1` is the first fork release based on upstream `8.2.0`. diff --git a/UPGRADING.md b/UPGRADING.md index 3b3e07d9e..d3b312cac 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -13,9 +13,9 @@ fork. #### PHP Version and Dependencies -This fork requires PHP 8.4 or newer and the Swoole extension. It requires -`hypervel/guzzle-promises`, Hypervel's fork of `guzzlehttp/promises`, in place -of `guzzlehttp/promises`; also read its +This fork requires PHP 8.4 or newer and Swoole 6.3.0 RC2 or a later 6.x release. +It requires `hypervel/guzzle-promises`, Hypervel's fork of +`guzzlehttp/promises`, in place of `guzzlehttp/promises`; also read its [upgrade guide](https://github.com/hypervel/guzzle-promises/blob/3.1/UPGRADING.md). #### Multi Handler Ownership @@ -33,6 +33,14 @@ its coroutine ends, unless the task queue implements `GuzzleHttp\Promise\ScopedTaskQueueInterface`, which cancels them. See [Coroutine Handlers](docs/handlers.md#coroutine-handlers). +#### Coroutine Cancellation + +A request interrupted by canceling its coroutine reports +`Swoole\Coroutine\CanceledException` instead of a Guzzle transfer exception, +such as cURL error 42. It is not a `GuzzleException`, so handle it separately +where a canceled request needs handling. See +[Coroutine Cancellation](docs/handlers.md#coroutine-cancellation). + #### Task Queues Promise callbacks settle promises in the coroutine that drains the task queue, diff --git a/docs/contributing/exception-guidelines.md b/docs/contributing/exception-guidelines.md index a81455021..8d8e64cde 100644 --- a/docs/contributing/exception-guidelines.md +++ b/docs/contributing/exception-guidelines.md @@ -72,6 +72,18 @@ no-response interface, so among PSR-18's request-bound interfaces only `RequestExceptionInterface` remains once Guzzle holds a response. This is a deliberate classification, not a claim that the request message was malformed. +## Coroutine cancellation + +When canceling the current Swoole coroutine interrupts a wait the handler owns, +or throws into a callback or into a read or write of a stock PSR-7 stream, the +handler reports the `Swoole\Coroutine\CanceledException` itself, never a Guzzle +exception wrapping it. A cancellation is not a transfer failure, and wrapping it +would let retry logic resend a request its caller abandoned. Keep catch blocks +that wrap other failures from catching it. Unwrap only a stock stream's failure, +and only to its immediate cancellation cause: an application exception that +carries a cancellation, or a failure from any other stream, keeps its own +meaning. + ## `GuzzleHttp\Exception\InvalidArgumentException` `final class InvalidArgumentException extends \InvalidArgumentException implements GuzzleException` diff --git a/docs/handlers.md b/docs/handlers.md index b327ffc68..b0f1f03da 100644 --- a/docs/handlers.md +++ b/docs/handlers.md @@ -284,6 +284,38 @@ one coroutine at a time. Capped clients keep one multi handler so the limits apply across all their requests. Requests with `stream` enabled use `StreamHandler`, which rejects them when connection caps are configured. +### Coroutine Cancellation + +Canceling a Swoole coroutine interrupts the request it is waiting on. The +built-in handlers then report the `Swoole\Coroutine\CanceledException` instead +of a transfer error, whether or not `Swoole\Coroutine::cancel()` was asked to +throw. This includes a cancellation thrown into a callback such as `on_headers`, +`progress` or `on_trailers`, into a read of the request body or into a write to +the `sink`. An application exception that carries a cancellation keeps its own +meaning, as does a failure from a custom stream implementation. An interrupted +request delay throws the cancellation. + +- `CurlHandler` releases the transfer and reports the cancellation to + `on_stats`. If `curl_exec()` itself throws the cancellation, it leaves the + handler call, so promise-based middleware such as retries never handles it. + Any other cancellation rejects the promise. Reading a request body smaller + than 1 MB happens before the transfer starts, so a cancellation there is + thrown. When the coroutine is canceled without an exception, a transfer + created by a custom `handle_factory` keeps its cURL error, because the + factory's callbacks can abort a transfer with the error Swoole reports for + that cancellation. +- `CurlMultiHandler` throws it from `tick()` and `execute()` and leaves the + pending transfers running. Waiting on a promise instead rejects the promise + with it and removes the promise's transfer; other transfers stay pending. A + transfer whose callback, body read or sink write is canceled rejects with the + cancellation after reporting it to `on_stats`. Like `CurlHandler`, it throws + when reading a request body smaller than 1 MB is interrupted. +- `StreamHandler` reports it to `on_stats` and rejects with it. Reading a + streamed body throws it. + +The cancellation does not implement `Psr\Http\Client\ClientExceptionInterface`, +so it also escapes PSR-18 `sendRequest()` unwrapped. + ## Transport Sharing By default, Guzzle does not ask handlers to share low-level transport state. diff --git a/phpstan-baseline.neon b/phpstan-baseline.neon index 127d82eee..81862305f 100644 --- a/phpstan-baseline.neon +++ b/phpstan-baseline.neon @@ -171,7 +171,7 @@ parameters: - message: '#^Parameter \#1 \$multi_handle of function curl_multi_select expects CurlMultiHandle, CurlMultiHandle\|resource given\.$#' identifier: argument.type - count: 3 + count: 2 path: src/Handler/CurlMultiHandler.php - diff --git a/src/Handler/CancelableTransportStream.php b/src/Handler/CancelableTransportStream.php new file mode 100644 index 000000000..b7e0dcb98 --- /dev/null +++ b/src/Handler/CancelableTransportStream.php @@ -0,0 +1,60 @@ +stream = $stream; + $this->cancellation = $cancellation; + } + + public function __clone() + { + // Detaching a clone must not detach this body's transport. + $this->stream = clone $this->stream; + } + + public function read(int $length): string + { + $this->cancellation->begin(); + + try { + return $this->stream->read($length); + } catch (\RuntimeException $e) { + $cancellation = CoroutineCancellation::fromStreamFailure($e, true); + if ($cancellation !== null) { + throw $cancellation; + } + + if ($e->getPrevious() === null && !$e instanceof TimeoutException && $this->cancellation->interrupted()) { + throw new CanceledException('Reading the response body was canceled.', 0, $e); + } + + throw $e; + } + } +} diff --git a/src/Handler/Clock.php b/src/Handler/Clock.php index 20f284bfe..db6e696f7 100644 --- a/src/Handler/Clock.php +++ b/src/Handler/Clock.php @@ -4,6 +4,8 @@ namespace GuzzleHttp\Handler; +use Swoole\Coroutine\CanceledException; + /** * @internal */ @@ -21,11 +23,21 @@ public static function now(): float return \hrtime(true) / 1e9; } + /** + * @throws CanceledException when canceling the current coroutine + * interrupts the sleep + */ public static function sleep(int $microseconds): void { while ($microseconds > 0) { $slice = \min($microseconds, 0xFFFFFFFF); + \swoole_clear_error(); \usleep($slice); + + if (CoroutineCancellation::interrupted(\SWOOLE_ERROR_CO_CANCELED)) { + throw new CanceledException('The coroutine was canceled while sleeping.'); + } + $microseconds -= $slice; } } diff --git a/src/Handler/CoroutineCancellation.php b/src/Handler/CoroutineCancellation.php new file mode 100644 index 000000000..fa6de8cdb --- /dev/null +++ b/src/Handler/CoroutineCancellation.php @@ -0,0 +1,66 @@ + 0 + && \Swoole\Coroutine::isCanceled() + && \swoole_last_error() === $error; + } + + /** + * Returns whether a stream is the stock PSR-7 stream, which reports a + * cancellation thrown during its I/O as the cause of its own failure. + */ + public static function isStockStream(StreamInterface $stream): bool + { + $class = \get_class($stream); + + return $class === Psr7\Stream::class || $class === Psr7\LazyOpenStream::class; + } + + /** + * Returns the cancellation a stream operation failed with: the failure + * itself, or, for a stock stream, the cancellation it reports as the cause. + * Another stream's failure keeps its own meaning, because the application + * may have wrapped a cancellation that belongs to something else. + */ + public static function fromStreamFailure(\Throwable $failure, bool $stockStream): ?CanceledException + { + if ($failure instanceof CanceledException) { + return $failure; + } + + $previous = $failure->getPrevious(); + + return $stockStream && $failure instanceof \RuntimeException && $previous instanceof CanceledException + ? $previous + : null; + } +} diff --git a/src/Handler/CurlFactory.php b/src/Handler/CurlFactory.php index 2a8d01aab..67dd631fe 100644 --- a/src/Handler/CurlFactory.php +++ b/src/Handler/CurlFactory.php @@ -31,6 +31,7 @@ use Psr\Http\Message\StreamFactoryInterface; use Psr\Http\Message\StreamInterface; use Psr\Http\Message\UriInterface; +use Swoole\Coroutine\CanceledException; /** * Creates curl resources from a request @@ -318,6 +319,21 @@ public function create( // Add handler options from the request configuration options if (isset($options['curl'])) { $conf = \array_replace($conf, $options['curl']); + + // A pre-request abort reports the same error as Swoole's coroutine + // cancellation, so record it to tell the two apart. + $prerequest = \defined('CURLOPT_PREREQFUNCTION') ? (int) \constant('CURLOPT_PREREQFUNCTION') : null; + if ($prerequest !== null && isset($conf[$prerequest]) && \is_callable($conf[$prerequest])) { + $callback = $conf[$prerequest]; + $conf[$prerequest] = static function (...$arguments) use ($easy, $callback) { + $result = $callback(...$arguments); + if ($result !== \constant('CURL_PREREQFUNC_OK')) { + $easy->prerequestAborted = true; + } + + return $result; + }; + } } self::normalizeStringableProxyCredentialOptions($conf); @@ -1042,6 +1058,18 @@ public static function finish( EasyHandle $easy, CurlFactoryInterface $factory ): PromiseInterface { + // A callback's failure stops the transfer, so at most one is recorded. + $callbackFailure = $easy->onHeadersException + ?? $easy->progressException + ?? $easy->bodyReadException + ?? $easy->sinkWriteException; + if ($callbackFailure instanceof CanceledException) { + self::finishCanceled($easy, $factory, $callbackFailure); + + /** @var PromiseInterface */ + return P\Create::rejectionFor($callbackFailure); + } + /** @var (callable(TransferStats): mixed)|null $onStats */ $onStats = $easy->options['on_stats'] ?? null; $stats = $onStats !== null ? self::createStats($easy) : null; @@ -1094,7 +1122,7 @@ public static function finish( try { $onTrailers(self::headersFromTrailerLines($easy->trailers), $response, $easy->request); } catch (\Throwable $e) { - $reason = new ResponseException( + $reason = $e instanceof CanceledException ? $e : new ResponseException( 'An error was encountered during the on_trailers event', $easy->request, $response, @@ -1102,8 +1130,8 @@ public static function finish( ); if ($onStats !== null && $stats !== null) { - // Report the ResponseException rather than errno 0 to match - // the response finalization stats above. + // Report the failure rather than errno 0 to match the + // response finalization stats above. $onStats(new TransferStats( $easy->request, $response, @@ -1126,9 +1154,52 @@ public static function finish( return P\Create::promiseFor($response); } + /** + * Returns whether Swoole's hooked curl_exec() abandoned the transfer + * because the calling coroutine was canceled. + * + * Swoole reports the cancellation as CURLE_ABORTED_BY_CALLBACK. Every + * callback this factory installs that can abort a transfer records why, + * so an abort without a recorded reason can only be the cancellation. + * + * @internal + */ + public static function wasCanceled(EasyHandle $easy): bool + { + return $easy->errno === \CURLE_ABORTED_BY_CALLBACK + && !$easy->progressAborted + && !$easy->prerequestAborted + && $easy->progressException === null + && !self::hasLocalFailure($easy); + } + + /** + * Releases a transfer abandoned for a canceled coroutine and reports its + * statistics with the cancellation. + * + * @internal + */ + public static function finishCanceled( + #[\SensitiveParameter] + EasyHandle $easy, + CurlFactoryInterface $factory, + CanceledException $cancellation + ): void { + /** @var (callable(TransferStats): mixed)|null $onStats */ + $onStats = $easy->options['on_stats'] ?? null; + $stats = $onStats !== null ? self::createStats($easy, $cancellation) : null; + + $factory->release($easy); + + if ($onStats !== null && $stats !== null) { + $onStats($stats); + } + } + private static function createStats( #[\SensitiveParameter] - EasyHandle $easy + EasyHandle $easy, + ?CanceledException $cancellation = null ): TransferStats { $curlStats = \curl_getinfo($easy->handle); $curlStats['appconnect_time'] = \curl_getinfo($easy->handle, \CURLINFO_APPCONNECT_TIME); @@ -1140,7 +1211,7 @@ private static function createStats( ]; } - $handlerErrorData = $easy->responseHeaderException ?? $easy->responseBodySizeException ?? $easy->errno; + $handlerErrorData = $cancellation ?? $easy->responseHeaderException ?? $easy->responseBodySizeException ?? $easy->errno; return new TransferStats( $easy->request, @@ -2367,13 +2438,14 @@ private function applyBody( * @return int|string */ $remaining = $contentLength; + $stockBody = CoroutineCancellation::isStockStream($body); $conf[\CURLOPT_READFUNCTION] = static function ( #[\SensitiveParameter] $ch, #[\SensitiveParameter] $fd, int $length - ) use ($easy, $body, &$remaining) { + ) use ($easy, $body, $stockBody, &$remaining) { if ($remaining === 0) { return ''; } @@ -2387,7 +2459,7 @@ private function applyBody( return self::CURL_READFUNC_ABORT; } catch (\Throwable $e) { - $easy->bodyReadException = $e; + $easy->bodyReadException = CoroutineCancellation::fromStreamFailure($e, $stockBody) ?? $e; return self::CURL_READFUNC_ABORT; } @@ -2643,7 +2715,9 @@ private function applyHandlerOptions( $sink = new LazyOpenStream($sink, 'w+'); } $easy->sink = $sink; - $conf[\CURLOPT_WRITEFUNCTION] = static function ($ch, string $write) use ($easy, $sink): int { + // A caller's resource sink is decorated, but writes to a stock stream. + $stockSink = ($hasSink && \is_resource($options['sink'])) || CoroutineCancellation::isStockStream($sink); + $conf[\CURLOPT_WRITEFUNCTION] = static function ($ch, string $write) use ($easy, $sink, $stockSink): int { $length = \strlen($write); try { @@ -2665,7 +2739,7 @@ private function applyHandlerOptions( return 0; } catch (\Throwable $e) { - $easy->sinkWriteException = $e; + $easy->sinkWriteException = CoroutineCancellation::fromStreamFailure($e, $stockSink) ?? $e; return 0; } diff --git a/src/Handler/CurlHandler.php b/src/Handler/CurlHandler.php index f22e87515..43bca293c 100644 --- a/src/Handler/CurlHandler.php +++ b/src/Handler/CurlHandler.php @@ -6,11 +6,13 @@ use GuzzleHttp\Exception\InvalidArgumentException; use GuzzleHttp\NonSerializableTrait; +use GuzzleHttp\Promise as P; use GuzzleHttp\Promise\PromiseInterface; use GuzzleHttp\Psr7\DiagnosticValue; use GuzzleHttp\TransportSharing; use Psr\Http\Message\RequestInterface; use Psr\Http\Message\ResponseInterface; +use Swoole\Coroutine\CanceledException; /** * HTTP handler that uses cURL easy handles as a transport layer. @@ -110,9 +112,34 @@ public function __invoke( // connection with a concurrent transfer. $easy = $this->factory->create($request, $options); - \curl_exec($easy->handle); + try { + \curl_exec($easy->handle); + } catch (CanceledException $cancellation) { + // Swoole throws from the wait when the coroutine is canceled with + // an exception. Rethrowing it keeps promise-based middleware, such + // as retries, from handling it. + CurlFactory::finishCanceled($easy, $this->factory, $cancellation); + + throw $cancellation; + } + $easy->errno = \curl_errno($easy->handle); + // @TODO: Preserve error 42 for custom factories until Swoole + // distinguishes an interrupted curl_exec() from a callback abort on the + // same transfer. + if (CurlFactory::wasCanceled($easy) + && $this->factory instanceof CurlFactory + && \Swoole\Coroutine::getCid() > 0 + && (\Swoole\Runtime::getHookFlags() & \SWOOLE_HOOK_NATIVE_CURL) !== 0 + ) { + $cancellation = new CanceledException('The cURL transfer was canceled.'); + CurlFactory::finishCanceled($easy, $this->factory, $cancellation); + + /** @var PromiseInterface */ + return P\Create::rejectionFor($cancellation); + } + return CurlFactory::finish($this, $easy, $this->factory); } diff --git a/src/Handler/CurlMultiHandler.php b/src/Handler/CurlMultiHandler.php index 940c12c48..8d8cd5cc7 100644 --- a/src/Handler/CurlMultiHandler.php +++ b/src/Handler/CurlMultiHandler.php @@ -18,6 +18,7 @@ use GuzzleHttp\TransportSharing; use Psr\Http\Message\RequestInterface; use Psr\Http\Message\ResponseInterface; +use Swoole\Coroutine\CanceledException; /** * Returns an asynchronous response using curl_multi_* functions. @@ -409,6 +410,16 @@ function () use ($id, $waitToken, $easy, &$promise): void { : new RequestException($message, $easy->request); $promise->reject($failure); + } catch (\Throwable $e) { + // The promise is rejected with this failure, so its + // transfer must not keep running unobserved. + try { + $this->cancel($id, $waitToken); + } catch (\Throwable $cleanupFailure) { + // Preserve the original failure. + } + + throw $e; } finally { --$this->activeCalls; $this->notifyIdle(); @@ -909,10 +920,10 @@ private function tickFor(?int $targetId, ?object $waitToken): void return; } - if ($this->active && \curl_multi_select($this->getMultiHandle(), $this->effectiveSelectTimeout()) === -1) { + if ($this->active && $this->select($this->effectiveSelectTimeout()) === -1) { // Perform a usleep if a select returns -1. // See: https://bugs.php.net/bug.php?id=61141 - \usleep(250); + Clock::sleep(250); } do { @@ -924,13 +935,34 @@ private function tickFor(?int $targetId, ?object $waitToken): void // Prevent busy looping for slow HTTP requests. if ($exec === \CURLM_CALL_MULTI_PERFORM) { - \curl_multi_select($this->getMultiHandle(), $this->effectiveSelectTimeout()); + $this->select($this->effectiveSelectTimeout()); } } while ($exec === \CURLM_CALL_MULTI_PERFORM); $this->processMessages(); } + /** + * Waits for activity on the transfers. + * + * @throws CanceledException when canceling the owning coroutine interrupts + * the wait + */ + private function select(float $timeout): int + { + $multiHandle = $this->getMultiHandle(); + \swoole_clear_error(); + $selected = \curl_multi_select($multiHandle, $timeout); + + // Swoole's hooked select runs no PHP code, so nothing else can have + // changed the coroutine's cancellation state since the wait. + if (CoroutineCancellation::interrupted(\SWOOLE_ERROR_CO_CANCELED)) { + throw new CanceledException('Waiting for the cURL multi handler was canceled.'); + } + + return $selected; + } + /** * Runs \curl_multi_exec() inside the event loop, to prevent busy looping */ diff --git a/src/Handler/DeadlineSourceStream.php b/src/Handler/DeadlineSourceStream.php index 122548dca..aa1394827 100644 --- a/src/Handler/DeadlineSourceStream.php +++ b/src/Handler/DeadlineSourceStream.php @@ -76,7 +76,7 @@ public function read(int $length): string if ($this->readTimeout !== null) { $wait = \min($wait, $this->readTimeout - ($now - $idleStart)); } - \usleep((int) \ceil($wait * 1e6)); + Clock::sleep((int) \ceil($wait * 1e6)); } } } diff --git a/src/Handler/EasyHandle.php b/src/Handler/EasyHandle.php index 99eb58ab4..7dc8147ea 100644 --- a/src/Handler/EasyHandle.php +++ b/src/Handler/EasyHandle.php @@ -98,6 +98,12 @@ final class EasyHandle */ public bool $progressAborted = false; + /** + * @var bool Whether a CURLOPT_PREREQFUNCTION callback from the "curl" + * request option aborted the transfer + */ + public bool $prerequestAborted = false; + /** * @var \Throwable|null Exception during createResponse (if any) */ diff --git a/src/Handler/RequestFraming.php b/src/Handler/RequestFraming.php index c9772dc37..7efc83b45 100644 --- a/src/Handler/RequestFraming.php +++ b/src/Handler/RequestFraming.php @@ -9,6 +9,7 @@ use GuzzleHttp\Psr7; use GuzzleHttp\Psr7\Exception\TimeoutException; use Psr\Http\Message\RequestInterface; +use Swoole\Coroutine\CanceledException; /** * Validates and normalizes request framing before a handler performs I/O. @@ -169,7 +170,9 @@ public static function bodySize( * Materializes the body, stopping at the selected Content-Length when * present. * - * @throws RequestException when the body cannot be fully rewound or read + * @throws RequestException when the body cannot be fully rewound or read + * @throws CanceledException when canceling the coroutine interrupts reading + * the body */ public function materialize(): string { @@ -239,6 +242,9 @@ public function materialize(): string return $contents; } + /** + * @return RequestException|CanceledException + */ private static function bodyException( #[\SensitiveParameter] RequestInterface $request, @@ -246,7 +252,15 @@ private static function bodyException( \Exception $exception, string $timeoutMessage, string $fallbackMessage - ): RequestException { + ): \Exception { + $cancellation = CoroutineCancellation::fromStreamFailure( + $exception, + CoroutineCancellation::isStockStream($request->getBody()) + ); + if ($cancellation !== null) { + return $cancellation; + } + $message = $exception instanceof TimeoutException ? $timeoutMessage : ($exception->getMessage() !== '' ? $exception->getMessage() : $fallbackMessage); diff --git a/src/Handler/StreamCancellation.php b/src/Handler/StreamCancellation.php new file mode 100644 index 000000000..89569f577 --- /dev/null +++ b/src/Handler/StreamCancellation.php @@ -0,0 +1,53 @@ +captured = false; + \swoole_clear_error(); + } + + /** + * Returns whether canceling the coroutine interrupted the operation, which + * must have failed. + */ + public function interrupted(): bool + { + return $this->captured || CoroutineCancellation::interrupted(\SOCKET_ECANCELED); + } + + /** + * Wraps a stream notification callback so it captures the cancellation + * state before running. + */ + public function wrapNotification(callable $notification): callable + { + return function (...$arguments) use ($notification): void { + $this->captured = $this->captured || CoroutineCancellation::interrupted(\SOCKET_ECANCELED); + $notification(...$arguments); + + // A callback's own socket error must not look like the transport's. + \swoole_clear_error(); + }; + } +} diff --git a/src/Handler/StreamHandler.php b/src/Handler/StreamHandler.php index 34fe46757..9dd2b2ce4 100644 --- a/src/Handler/StreamHandler.php +++ b/src/Handler/StreamHandler.php @@ -32,6 +32,7 @@ use Psr\Http\Message\StreamFactoryInterface; use Psr\Http\Message\StreamInterface; use Psr\Http\Message\UriInterface; +use Swoole\Coroutine\CanceledException; /** * HTTP handler that uses PHP's HTTP stream wrapper. @@ -240,7 +241,8 @@ public function __invoke( } $deadline = null; - $stream = $this->createStream($request, $options, $body, $deadline); + $cancellation = new StreamCancellation(); + $stream = $this->createStream($request, $options, $body, $cancellation, $deadline); $headers = \stream_get_meta_data($stream)['wrapper_data']; return $this->createResponse( @@ -249,7 +251,8 @@ public function __invoke( $stream, \is_array($headers) ? $headers : [], $startTime, - $deadline + $deadline, + $cancellation ); } catch (\InvalidArgumentException $e) { throw $e; @@ -258,7 +261,7 @@ public function __invoke( throw $e; } - if (!$e instanceof TransferException) { + if (!$e instanceof TransferException && !$e instanceof CanceledException) { $message = $e->getMessage(); $e = self::createStreamFailureException($message, $request, $e, []); } @@ -406,7 +409,8 @@ private function createResponse( #[\SensitiveParameter] array $hdrs, ?float $startTime, - ?float $deadline + ?float $deadline, + StreamCancellation $cancellation ): PromiseInterface { try { [$ver, $status, $reason, $headers] = HeaderProcessor::parseHeaders($hdrs); @@ -445,6 +449,10 @@ private function createResponse( $stream = $streamFactory->createStreamFromResource($stream); if ($framingFailure === null && $deadline !== null && empty($options['stream'])) { $stream = self::createDeadlineSource($stream, $resource, $deadline, $options); + } elseif (\get_class($stream) === Psr7\Stream::class) { + // Only the stock stream's read is known to be a single blocking + // read of the transport. + $stream = new CancelableTransportStream($stream, $cancellation); } if ($chunked || !empty($options['stream'])) { $stream = new TransportStream($stream); @@ -518,7 +526,9 @@ private function createResponse( try { $options['on_headers']($response, $request); } catch (\Throwable $e) { - $reason = new ResponseException('An error was encountered during the on_headers event', $request, $response, $e); + $reason = $e instanceof CanceledException + ? $e + : new ResponseException('An error was encountered during the on_headers event', $request, $response, $e); $this->invokeStats($options, $request, $startTime, $response, $reason); /** @var PromiseInterface */ @@ -538,9 +548,13 @@ private function createResponse( // a fully received no-content response. } } elseif ($sink !== $stream) { + // A caller's resource sink is decorated, but writes to a stock + // stream. + $stockSink = (isset($options['sink']) && \is_resource($options['sink'])) + || CoroutineCancellation::isStockStream($sink); try { - $this->drain($request, $response, $stream, $sink, $declaredLength, $encodedBody); - } catch (ResponseException $e) { + $this->drain($request, $response, $stream, $sink, $stockSink, $declaredLength, $encodedBody); + } catch (ResponseException|CanceledException $e) { $this->invokeStats($options, $request, $startTime, $response, $e); /** @var PromiseInterface */ @@ -731,6 +745,8 @@ private static function checkDecode( * Drains the source stream into the "sink" client option. * * @throws \RuntimeException when the sink option is invalid. + * @throws CanceledException when canceling the coroutine interrupts reading + * or writing the response body. */ private function drain( #[\SensitiveParameter] @@ -739,6 +755,7 @@ private function drain( ResponseInterface $response, StreamInterface $source, StreamInterface $sink, + bool $stockSink, ?string $declaredResponseBodyLength, ?EncodedBodyStream $encodedBody = null ): StreamInterface { @@ -748,13 +765,13 @@ private function drain( $copyLimit = $encodedBody === null ? $declaredLength ?? -1 : -1; try { - $target = $this->createResponseSink($request, $response, $sink); + $target = $this->createResponseSink($request, $response, $sink, $stockSink); // If a content-length header is provided, then stop reading once // that number of bytes has been read. This can prevent infinitely // reading from a stream when dealing with servers that do not // honor Connection: Close headers. $copied = Psr7\Utils::copyToStream($source, $target, $copyLimit); - } catch (ResponseException $e) { + } catch (ResponseException|CanceledException $e) { throw $e; } catch (TimeoutException $e) { throw new ResponseTimeoutException( @@ -811,12 +828,13 @@ private function drain( private function createResponseSink( RequestInterface $request, ResponseInterface $response, - StreamInterface $sink + StreamInterface $sink, + bool $stockSink ): StreamInterface { return Psr7\FnStream::decorate($sink, [ 'close' => static function (): void { }, - 'write' => static function (string $data) use ($request, $response, $sink): int { + 'write' => static function (string $data) use ($request, $response, $sink, $stockSink): int { try { $written = $sink->write($data); } catch (TimeoutException $e) { @@ -827,6 +845,11 @@ private function createResponseSink( $e ); } catch (\Exception $e) { + $cancellation = CoroutineCancellation::fromStreamFailure($e, $stockSink); + if ($cancellation !== null) { + throw $cancellation; + } + throw new ResponseException( $e->getMessage() !== '' ? $e->getMessage() : 'Failed to write the response body', $request, @@ -928,6 +951,7 @@ private function createStream( #[\SensitiveParameter] array $options, string $body, + StreamCancellation $cancellation, ?float &$deadline ) { // Report a stream-open failure against the request passed here, not the @@ -1007,6 +1031,10 @@ private function createStream( $uri = $this->resolveHost($request, $options); + if (isset($params['notification'])) { + $params['notification'] = $cancellation->wrapNotification($params['notification']); + } + $contextResource = $this->createResource( static function () use ($context, $params) { return \stream_context_create($context, $params); @@ -1014,7 +1042,7 @@ static function () use ($context, $params) { ); try { - $resource = $this->createResource(function () use ($uri, $contextResource, $idleTimeout, $timeout, &$deadline) { + $resource = $this->createResource(function () use ($uri, $contextResource, $idleTimeout, $timeout, $cancellation, &$deadline) { $deadline = $timeout > 0 ? Clock::now() + $timeout / 1000 : null; // Blank the from ini setting for the transfer so ambient @@ -1031,6 +1059,7 @@ static function () use ($context, $params) { } } try { + $cancellation->begin(); $resource = @\fopen((string) $uri, 'r', false, $contextResource); } finally { if ($blankFrom && --self::$fromBlankDepth === 0 && self::$fromToRestore !== false) { @@ -1039,6 +1068,10 @@ static function () use ($context, $params) { } if (false === $resource) { + if ($cancellation->interrupted()) { + throw new CanceledException('Opening the stream was canceled.'); + } + return false; } diff --git a/tests/CancelingStreamWrapper.php b/tests/CancelingStreamWrapper.php new file mode 100644 index 000000000..d250f7fa9 --- /dev/null +++ b/tests/CancelingStreamWrapper.php @@ -0,0 +1,78 @@ +pop(5); + self::assertTrue(Coroutine::isCanceled()); + Clock::sleep(1000); + + self::cancelCurrentCoroutineAfter(0.01); + $start = Clock::now(); + try { + Clock::sleep(5000000); + } catch (CanceledException $e) { + $exception = $e; + } + $elapsed = Clock::now() - $start; + }); + + self::assertInstanceOf(CanceledException::class, $exception); + self::assertLessThan(1, $elapsed); + } } diff --git a/tests/Handler/CurlFactoryTest.php b/tests/Handler/CurlFactoryTest.php index 3341e8d93..4c8824ae8 100644 --- a/tests/Handler/CurlFactoryTest.php +++ b/tests/Handler/CurlFactoryTest.php @@ -406,7 +406,10 @@ public function testAllowsPrereqFunctionCurlOption(): void $option = (int) \constant('CURLOPT_PREREQFUNCTION'); $ok = (int) \constant('CURL_PREREQFUNC_OK'); - $callback = static function () use ($ok): int { + $received = null; + $callback = static function (...$arguments) use ($ok, &$received): int { + $received = $arguments; + return $ok; }; @@ -418,7 +421,9 @@ public function testAllowsPrereqFunctionCurlOption(): void ]); try { - self::assertSame($callback, $_SERVER['_curl'][$option]); + self::assertSame($ok, $_SERVER['_curl'][$option]('handle', '127.0.0.1', '127.0.0.2', 80, 54321)); + self::assertSame(['handle', '127.0.0.1', '127.0.0.2', 80, 54321], $received); + self::assertFalse($easy->prerequestAborted); } finally { $factory->release($easy); } diff --git a/tests/Handler/CurlHandlerTest.php b/tests/Handler/CurlHandlerTest.php index 5e1121aff..b1477a51b 100644 --- a/tests/Handler/CurlHandlerTest.php +++ b/tests/Handler/CurlHandlerTest.php @@ -22,21 +22,28 @@ use GuzzleHttp\Psr7\Response; use GuzzleHttp\RequestOptions; use GuzzleHttp\Server\Server; +use GuzzleHttp\Tests\CancelingStreamWrapper; use GuzzleHttp\Tests\Psr17SpyFactory; use GuzzleHttp\Tests\SpyResponse; use GuzzleHttp\Tests\SpyStream; use GuzzleHttp\Tests\StrictReadableResourceStreamFactory; use GuzzleHttp\Tests\UnvalidatedUri; use GuzzleHttp\Tests\UnvalidatedUriRequest; +use GuzzleHttp\TransferStats; use GuzzleHttp\TransportSharing; use PHPUnit\Framework\TestCase; use Psr\Http\Message\RequestInterface; +use Swoole\Coroutine; +use Swoole\Coroutine\CanceledException; +use Swoole\Coroutine\Channel; /** * @covers \GuzzleHttp\Handler\CurlHandler */ class CurlHandlerTest extends TestCase { + use RunsInCoroutines; + protected function getHandler(array $options = []): CurlHandler { return new CurlHandler($options); @@ -503,6 +510,255 @@ public static function unsupportedTransferEncodingProvider(): iterable yield 'coding after chunked' => ['chunked, gzip', 'Invalid Transfer-Encoding response header: chunked is not the final transfer coding']; } + /** + * @dataProvider cancellationProvider + */ + public function testCancelingTheCoroutineStopsTheTransfer(bool $throwException): void + { + $handler = new CurlHandler(); + $promise = null; + $exception = null; + $reported = []; + $elapsed = null; + + self::runInCoroutine(static function () use ($handler, $throwException, &$promise, &$exception, &$reported, &$elapsed): void { + // Accepts connections without ever answering. + $server = \stream_socket_server('tcp://127.0.0.1:0'); + $url = 'http://'.\stream_socket_get_name($server, false).'/'; + + // A cancellation the coroutine handled leaves its flag set. + self::cancelCurrentCoroutineAfter(0.01); + (new Channel())->pop(5); + + self::cancelCurrentCoroutineAfter(0.05, $throwException); + $start = Clock::now(); + try { + $promise = $handler(new Request('GET', $url), [ + 'timeout' => 5, + 'on_stats' => static function (TransferStats $stats) use (&$reported): void { + $reported[] = $stats->getHandlerErrorData(); + }, + ]); + $promise->wait(); + } catch (\Throwable $e) { + $exception = $e; + } + $elapsed = Clock::now() - $start; + \fclose($server); + }); + + // A thrown cancellation leaves the handler call itself, so + // promise-based middleware never handles it. + self::assertSame($throwException, $promise === null); + self::assertInstanceOf(CanceledException::class, $exception); + self::assertSame([$exception], $reported); + self::assertLessThan(1, $elapsed); + self::assertCount(1, self::readIdleHandles(self::readFactory($handler))); + } + + public static function cancellationProvider(): iterable + { + yield 'without an exception' => [false]; + yield 'with an exception' => [true]; + } + + public function testCancellationDuringTheFinalProgressUpdateStillStopsTheTransfer(): void + { + $exception = null; + $canceledUpdates = 0; + + self::runInCoroutine(static function () use (&$exception, &$canceledUpdates): void { + $server = \stream_socket_server('tcp://127.0.0.1:0'); + $url = 'http://'.\stream_socket_get_name($server, false).'/'; + + self::cancelCurrentCoroutineAfter(0.05); + try { + (new CurlHandler())(new Request('GET', $url), [ + 'timeout' => 5, + 'progress' => static function () use (&$canceledUpdates): void { + if (Coroutine::isCanceled()) { + ++$canceledUpdates; + // Coroutine I/O resets the cancellation flag. + Coroutine::sleep(0.001); + } + }, + ])->wait(); + } catch (\Throwable $e) { + $exception = $e; + } + \fclose($server); + }); + + if ($canceledUpdates === 0) { + self::markTestSkipped('libcurl did not run a final progress update on premature removal.'); + } + + self::assertInstanceOf(CanceledException::class, $exception); + } + + /** + * @dataProvider unexplainedAbortProvider + */ + public function testAbortsWithoutProvenCancellationRemainCurlErrors(callable $createHandler): void + { + if (!\defined('CURLOPT_PREREQFUNCTION')) { + self::markTestSkipped('CURLOPT_PREREQFUNCTION is not available.'); + } + + Server::flush(); + Server::enqueue([new Response(), new Response()]); + $prerequests = 0; + $canceledWhenAborting = null; + $exception = null; + + $handler = $createHandler(static function () use (&$prerequests, &$canceledWhenAborting): int { + if (++$prerequests === 1) { + return (int) \constant('CURL_PREREQFUNC_OK'); + } + + // Canceling another coroutine records the same error as an + // interrupted transfer. + $canceledWhenAborting = Coroutine::isCanceled(); + Coroutine::cancel(Coroutine::create(static function (): void { + Coroutine::sleep(1); + })); + + return (int) \constant('CURL_PREREQFUNC_ABORT'); + }); + + self::runInCoroutine(static function () use ($handler, &$exception): void { + $handler(new Request('GET', Server::$url), [])->wait(); + + // A cancellation the coroutine handled leaves its flag set, and + // the reused connection lets the transfer reach the callback + // without a wait that would reset it. + self::cancelCurrentCoroutineAfter(0.01); + (new Channel())->pop(5); + try { + $handler(new Request('GET', Server::$url), [])->wait(); + } catch (\Throwable $e) { + $exception = $e; + } + }); + + self::assertTrue($canceledWhenAborting); + self::assertInstanceOf(RequestException::class, $exception); + self::assertStringStartsWith('cURL error 42: ', $exception->getMessage()); + } + + public static function unexplainedAbortProvider(): iterable + { + yield 'pre-request option' => [static function (callable $prerequest): callable { + $handler = new CurlHandler(); + + return static function (RequestInterface $request, array $options) use ($handler, $prerequest) { + return $handler($request, $options + [ + 'curl' => [(int) \constant('CURLOPT_PREREQFUNCTION') => $prerequest], + ]); + }; + }]; + yield 'custom factory callback' => [static function (callable $prerequest): callable { + return new CurlHandler(['handle_factory' => new class($prerequest) implements CurlFactoryInterface { + /** @var callable */ + private $prerequest; + + private CurlFactory $factory; + + public function __construct(callable $prerequest) + { + $this->prerequest = $prerequest; + $this->factory = new CurlFactory(1); + } + + public function create(RequestInterface $request, array $options): EasyHandle + { + $easy = $this->factory->create($request, $options); + \curl_setopt($easy->handle, (int) \constant('CURLOPT_PREREQFUNCTION'), $this->prerequest); + + return $easy; + } + + public function release(EasyHandle $easy): void + { + $this->factory->release($easy); + } + }]); + }]; + } + + /** + * @dataProvider thrownCancellationProvider + */ + public function testCancellationsThrownIntoTheTransferRejectWithThem(callable $createTransfer): void + { + Server::flush(); + Server::enqueue([new Response(200, [], 'body')]); + [$request, $options] = $createTransfer(); + $handler = new CurlHandler(); + $reported = []; + + $promise = $handler($request, $options + [ + 'on_stats' => static function (TransferStats $stats) use (&$reported): void { + $reported[] = $stats->getHandlerErrorData(); + }, + ]); + + try { + $promise->wait(); + self::fail('Expected the cancellation'); + } catch (CanceledException $e) { + self::assertSame([$e], $reported); + } + + self::assertCount(1, self::readIdleHandles(self::readFactory($handler))); + } + + public static function thrownCancellationProvider(): iterable + { + $throw = static function (): void { + throw new CanceledException(); + }; + + yield 'file sink' => [static function (): array { + return [new Request('GET', Server::$url), ['sink' => CancelingStreamWrapper::open()]]; + }]; + yield 'file body' => [static function (): array { + return [new Request('PUT', Server::$url, [], Psr7\Utils::streamFor(CancelingStreamWrapper::open())), []]; + }]; + yield 'on_headers' => [static function () use ($throw): array { + return [new Request('GET', Server::$url), ['on_headers' => $throw]]; + }]; + yield 'on_trailers' => [static function () use ($throw): array { + return [new Request('GET', Server::$url), ['on_trailers' => $throw]]; + }]; + } + + /** + * @dataProvider wrappedCancellationProvider + */ + public function testApplicationFailuresCarryingACancellationStayWrapped(array $options): void + { + Server::flush(); + Server::enqueue([new Response(200, [], 'body')]); + + try { + (new CurlHandler())(new Request('GET', Server::$url), $options)->wait(); + self::fail('Expected the application failure'); + } catch (RequestException $e) { + self::assertSame('Application failure', $e->getPrevious()->getMessage()); + } + } + + public static function wrappedCancellationProvider(): iterable + { + $fail = static function (): void { + throw new \RuntimeException('Application failure', 0, new CanceledException()); + }; + + yield 'custom sink' => [['sink' => Psr7\FnStream::decorate(Psr7\Utils::streamFor(''), ['write' => $fail])]]; + yield 'on_headers' => [['on_headers' => $fail]]; + } + private static function readFactory(CurlHandler $handler): CurlFactory { $readFactory = \Closure::bind(static function (CurlHandler $handler): CurlFactory { diff --git a/tests/Handler/CurlMultiHandlerTest.php b/tests/Handler/CurlMultiHandlerTest.php index 1efee49ea..242e5fae6 100644 --- a/tests/Handler/CurlMultiHandlerTest.php +++ b/tests/Handler/CurlMultiHandlerTest.php @@ -30,9 +30,12 @@ use GuzzleHttp\TransportSharing; use PHPUnit\Framework\TestCase; use Psr\Http\Message\RequestInterface; +use Swoole\Coroutine\CanceledException; class CurlMultiHandlerTest extends TestCase { + use RunsInCoroutines; + public function setUp(): void { $_SERVER['curl_test'] = true; @@ -2266,6 +2269,78 @@ public function testCancelClearsCallbacks(): void } } + /** + * @dataProvider failedWaitProvider + */ + public function testFailedWaitRemovesOnlyItsTransfer(callable $interrupt, array $options, array $siblingOptions, string $expected): void + { + $failure = null; + $state = null; + $remaining = null; + $sibling = null; + $siblingBody = null; + + self::runInCoroutine(static function () use ($interrupt, $options, $siblingOptions, &$failure, &$state, &$remaining, &$sibling, &$siblingBody): void { + // Accepts connections without ever answering. + $silent = \stream_socket_server('tcp://127.0.0.1:0'); + $server = new \Swoole\Coroutine\Http\Server('127.0.0.1', 0); + $server->handle('/', static function ($request, $response): void { + \Swoole\Coroutine::sleep(0.2); + $response->end('sibling'); + }); + \Swoole\Coroutine::create(static function () use ($server): void { + $server->start(); + }); + + try { + $handler = new CurlMultiHandler(); + $promise = $handler(new Request('GET', 'http://'.\stream_socket_get_name($silent, false).'/'), $options + ['timeout' => 5]); + $sibling = $handler(new Request('GET', 'http://127.0.0.1:'.$server->port.'/'), $siblingOptions + ['timeout' => 5]); + + $interrupt(); + try { + $promise->wait(); + } catch (\Throwable $e) { + $failure = $e; + } + + $state = $promise->getState(); + $remaining = \array_column(self::readMultiProperty($handler, 'handles'), 'deferred'); + $siblingBody = (string) $sibling->wait()->getBody(); + } finally { + // A running server would keep the scheduler from returning. + $server->shutdown(); + \fclose($silent); + } + }); + + self::assertInstanceOf($expected, $failure); + self::assertSame(P\PromiseInterface::REJECTED, $state); + self::assertSame([$sibling], $remaining); + self::assertSame('sibling', $siblingBody); + } + + public static function failedWaitProvider(): iterable + { + $staleThenCancel = static function (): void { + // A cancellation the coroutine handled leaves its flag set. + self::cancelCurrentCoroutineAfter(0.01); + (new \Swoole\Coroutine\Channel())->pop(5); + self::cancelCurrentCoroutineAfter(0.05); + }; + + yield 'canceled select' => [$staleThenCancel, [], [], CanceledException::class]; + yield 'canceled delay' => [$staleThenCancel, ['delay' => 5000], ['delay' => 100], CanceledException::class]; + yield 'thrown cancellation' => [static function (): void { + self::cancelCurrentCoroutineAfter(0.05, true); + }, [], [], CanceledException::class]; + yield 'failing queued task' => [static function (): void { + P\Utils::queue()->add(static function (): void { + throw new \RuntimeException('Queued task failed.'); + }); + }, [], [], \RuntimeException::class]; + } + public function testCanCancelFromProgressCallback(): void { Server::flush(); @@ -5044,40 +5119,6 @@ public function track(P\PromiseInterface $promise): void }; } - /** - * Runs the callback in a coroutine scheduler with its own task queue. A - * coroutine that drains the shared queue would also run tasks left by - * other tests. The scheduler leaves Swoole's runtime hooks enabled, so they - * are restored for the tests that follow. Call the test server's control - * methods, such as Server::enqueue(), outside the callback: its client - * reuses cURL handles created without the hooks, which the hooked cURL - * functions reject. - */ - private static function runInCoroutine(callable $callback): void - { - $queue = P\Utils::queue(); - $hookFlags = \Swoole\Runtime::getHookFlags(); - P\Utils::queue(new P\TaskQueue(false)); - $failure = null; - - try { - \Swoole\Coroutine\run(static function () use ($callback, &$failure): void { - try { - $callback(); - } catch (\Throwable $e) { - $failure = $e; - } - }); - } finally { - \Swoole\Runtime::setHookFlags($hookFlags); - P\Utils::queue($queue); - } - - if ($failure !== null) { - throw $failure; - } - } - /** * Older libcurl delegates numeric shorthand to the platform resolver, * which rejects it on Windows. Validation is covered separately. diff --git a/tests/Handler/RunsInCoroutines.php b/tests/Handler/RunsInCoroutines.php new file mode 100644 index 000000000..a73b5dcc6 --- /dev/null +++ b/tests/Handler/RunsInCoroutines.php @@ -0,0 +1,58 @@ +pop(5); + self::cancelCurrentCoroutineAfter(0.1); + } + + $start = Clock::now(); + $promise = (new StreamHandler())(new Request('GET', 'http://'.\stream_socket_get_name($server, false).'/'), $options + [ + 'read_timeout' => 5, + 'debug' => $debug, + 'on_stats' => static function (TransferStats $stats) use (&$reported): void { + $reported[] = $stats; + }, + ]); + try { + $promise->wait(); + } catch (\Throwable $e) { + $failure = $e; + } + $elapsed = Clock::now() - $start; + + $done->push(true); + \fclose($debug); + \unlink($debugFile); + \fclose($server); + }); + + self::assertInstanceOf($expected, $failure); + self::assertLessThan(1, $elapsed); + self::assertCount(1, $reported); + self::assertSame($failure, $reported[0]->getHandlerErrorData()); + self::assertSame($hasResponse, $reported[0]->hasResponse()); + } + + public static function interruptedTransferProvider(): iterable + { + $stallMidBody = static function ($connection, Channel $done): void { + \fwrite($connection, "HTTP/1.1 200 OK\r\nContent-Length: 100\r\nConnection: close\r\n\r\n".\str_repeat('x', 10)); + $done->pop(5); + }; + + yield 'opening' => [null, [], true, CanceledException::class, false]; + yield 'reading the body' => [$stallMidBody, [], true, CanceledException::class, true]; + yield 'reading through a custom stream' => [$stallMidBody, [RequestOptions::STREAM_FACTORY => new Psr17SpyFactory()], true, ResponseTransferException::class, true]; + yield 'connection reset' => [static function ($connection): void { + \fwrite($connection, "HTTP/1.1 200 OK\r\nContent-Length: 100\r\nConnection: close\r\n\r\n".\str_repeat('x', 10)); + Coroutine::sleep(0.1); + \socket_set_option(\socket_import_stream($connection), \SOL_SOCKET, \SO_LINGER, ['l_onoff' => 1, 'l_linger' => 0]); + \fclose($connection); + }, [], false, ResponseTransferException::class, true]; + } + + public function testCancelingAStreamedBodyReadThrowsTheCancellation(): void + { + $failure = null; + $statsCalls = 0; + + self::runInCoroutine(static function () use (&$failure, &$statsCalls): void { + $server = \stream_socket_server('tcp://127.0.0.1:0'); + $done = new Channel(1); + Coroutine::create(static function () use ($server, $done): void { + $connection = \stream_socket_accept($server, 5); + \fread($connection, 8192); + \fwrite($connection, "HTTP/1.1 200 OK\r\nContent-Length: 100\r\nConnection: close\r\n\r\n".\str_repeat('x', 10)); + $done->pop(5); + }); + + $response = (new StreamHandler())(new Request('GET', 'http://'.\stream_socket_get_name($server, false).'/'), [ + 'stream' => true, + 'timeout' => 5, + 'on_stats' => static function () use (&$statsCalls): void { + ++$statsCalls; + }, + ])->wait(); + $body = $response->getBody(); + $body->read(10); + + self::cancelCurrentCoroutineAfter(0.05); + try { + $body->read(100); + } catch (\Throwable $e) { + $failure = $e; + } + + $done->push(true); + \fclose($server); + }); + + self::assertInstanceOf(CanceledException::class, $failure); + self::assertSame(1, $statsCalls); + } + + /** + * @dataProvider thrownCancellationProvider + */ + public function testCancellationsThrownIntoTheTransferRejectWithThem(callable $createTransfer): void + { + Server::flush(); + Server::enqueue([new Response(200, [], 'body')]); + [$request, $options] = $createTransfer(); + $reported = []; + + $promise = (new StreamHandler())($request, $options + [ + 'on_stats' => static function (TransferStats $stats) use (&$reported): void { + $reported[] = $stats->getHandlerErrorData(); + }, + ]); + + try { + $promise->wait(); + self::fail('Expected the cancellation'); + } catch (CanceledException $e) { + self::assertSame([$e], $reported); + } + } + + public static function thrownCancellationProvider(): iterable + { + yield 'file sink' => [static function (): array { + return [new Request('GET', Server::$url), ['sink' => CancelingStreamWrapper::open()]]; + }]; + yield 'file body' => [static function (): array { + return [new Request('PUT', Server::$url, [], Psr7\Utils::streamFor(CancelingStreamWrapper::open())), []]; + }]; + yield 'on_headers' => [static function (): array { + return [new Request('GET', Server::$url), ['on_headers' => static function (): void { + throw new CanceledException(); + }]]; + }]; + } + + /** + * @dataProvider wrappedCancellationProvider + */ + public function testApplicationFailuresCarryingACancellationStayWrapped(array $options): void + { + Server::flush(); + Server::enqueue([new Response(200, [], 'body')]); + + try { + (new StreamHandler())(new Request('GET', Server::$url), $options)->wait(); + self::fail('Expected the application failure'); + } catch (RequestException $e) { + self::assertSame('Application failure', $e->getPrevious()->getMessage()); + } + } + + public static function wrappedCancellationProvider(): iterable + { + $fail = static function (): void { + throw new \RuntimeException('Application failure', 0, new CanceledException()); + }; + + yield 'custom sink' => [['sink' => FnStream::decorate(Psr7\Utils::streamFor(''), ['write' => $fail])]]; + yield 'on_headers' => [['on_headers' => $fail]]; + } + private static function assertResponseContentLengthPlatformException(ResponseException $e): void { self::assertNotInstanceOf(ResponseTransferException::class, $e); @@ -6627,7 +6820,7 @@ private function invokeStreamHandlerCreateResponse(StreamHandler $handler, Reque $method->setAccessible(true); } - return $method->invoke($handler, $request, $options, $stream, $headers, Clock::now(), null); + return $method->invoke($handler, $request, $options, $stream, $headers, Clock::now(), null, new StreamCancellation()); } public function testProtocolsOptionRejectsDisallowedStreamScheme(): void From f4265ab4a4bf48f3966033294c40a7cf7ba2b297 Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Thu, 19 Nov 2026 00:24:31 +0000 Subject: [PATCH 4/4] Clarify where cancellation reaches middleware and rewinds A cancellation that curl_exec() throws leaves the handler call, so middleware in the handler stack never sees it. Global middleware runs outside the stack, where the client turns the throw into a rejected promise, so it does receive it. The handler guide and the comment in CurlHandler said retry middleware never handles it; both now limit that to the handler stack and say what global middleware sees. The handler guide also promised the plain cancellation for every interrupted operation. A stream seek or rewind interrupted by a cancellation can still be reported as a request or response exception, so the guide now says so. The comment above finish()'s callback check claimed that at most one callback failure is recorded. libcurl calls the progress callback once more after a write callback stops the transfer, so a progress failure can follow a sink failure. The check already follows createRejection()'s order; the comment now says why that order matters. --- docs/handlers.md | 20 +++++++++++--------- src/Handler/CurlFactory.php | 4 +++- src/Handler/CurlHandler.php | 4 ++-- 3 files changed, 16 insertions(+), 12 deletions(-) diff --git a/docs/handlers.md b/docs/handlers.md index b0f1f03da..33fb5ae30 100644 --- a/docs/handlers.md +++ b/docs/handlers.md @@ -292,18 +292,20 @@ of a transfer error, whether or not `Swoole\Coroutine::cancel()` was asked to throw. This includes a cancellation thrown into a callback such as `on_headers`, `progress` or `on_trailers`, into a read of the request body or into a write to the `sink`. An application exception that carries a cancellation keeps its own -meaning, as does a failure from a custom stream implementation. An interrupted -request delay throws the cancellation. +meaning, as does a failure from a custom stream implementation. A cancellation +while a stream seeks or rewinds can still be reported as a request or response +exception. An interrupted request delay throws the cancellation. - `CurlHandler` releases the transfer and reports the cancellation to `on_stats`. If `curl_exec()` itself throws the cancellation, it leaves the - handler call, so promise-based middleware such as retries never handles it. - Any other cancellation rejects the promise. Reading a request body smaller - than 1 MB happens before the transfer starts, so a cancellation there is - thrown. When the coroutine is canceled without an exception, a transfer - created by a custom `handle_factory` keeps its cURL error, because the - factory's callbacks can abort a transfer with the error Swoole reports for - that cancellation. + handler call, so promise-based middleware in the handler stack, such as + retries, never handles it. Global middleware runs outside the handler stack + and receives it as a rejection. Any other cancellation rejects the promise. + Reading a request body smaller than 1 MB happens before the transfer starts, + so a cancellation there is thrown. When the coroutine is canceled without an + exception, a transfer created by a custom `handle_factory` keeps its cURL + error, because the factory's callbacks can abort a transfer with the error + Swoole reports for that cancellation. - `CurlMultiHandler` throws it from `tick()` and `execute()` and leaves the pending transfers running. Waiting on a promise instead rejects the promise with it and removes the promise's transfer; other transfers stay pending. A diff --git a/src/Handler/CurlFactory.php b/src/Handler/CurlFactory.php index 67dd631fe..1409dd54e 100644 --- a/src/Handler/CurlFactory.php +++ b/src/Handler/CurlFactory.php @@ -1058,7 +1058,9 @@ public static function finish( EasyHandle $easy, CurlFactoryInterface $factory ): PromiseInterface { - // A callback's failure stops the transfer, so at most one is recorded. + // Same order as createRejection(), which matters because libcurl's + // final progress update can record a failure after another callback + // stopped the transfer. $callbackFailure = $easy->onHeadersException ?? $easy->progressException ?? $easy->bodyReadException diff --git a/src/Handler/CurlHandler.php b/src/Handler/CurlHandler.php index 43bca293c..047890618 100644 --- a/src/Handler/CurlHandler.php +++ b/src/Handler/CurlHandler.php @@ -116,8 +116,8 @@ public function __invoke( \curl_exec($easy->handle); } catch (CanceledException $cancellation) { // Swoole throws from the wait when the coroutine is canceled with - // an exception. Rethrowing it keeps promise-based middleware, such - // as retries, from handling it. + // an exception. Rethrowing it keeps promise-based middleware in the + // handler stack, such as retries, from handling it. CurlFactory::finishCanceled($easy, $this->factory, $cancellation); throw $cancellation;