From cb507941bb43473986b6c3c6c7c09838d3ba818e Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Wed, 18 Nov 2026 21:27:36 +0000 Subject: [PATCH 01/33] Keep requested numeric cache keys from taking positional defaults Cache::many() and Cache::get(array) treat numeric entries as requested keys and string-keyed entries as defaults. A missed key that matched an array position took that entry as its default: many(['x' => 'default', 'a', '0']) returned 'a' for key 0, and sparse lists such as array_unique() results returned another requested key. Laravel's array_is_list() check only covered plain lists. On a miss, skip keys that PHP stores as integers, since those entries are always requested keys. The protected handleManyResult() hook keeps its signature and original argument, and batches where every key is found do no extra work. String keys such as '02' still supply their defaults. Validation: the new mixed and sparse regression case failed before the fix; CacheRepositoryTest passes, formatting and full static analysis pass. --- src/cache/src/Repository.php | 3 ++- tests/Cache/CacheRepositoryTest.php | 13 +++++++++++++ 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/src/cache/src/Repository.php b/src/cache/src/Repository.php index 3de9ec527..3d75a1bf9 100644 --- a/src/cache/src/Repository.php +++ b/src/cache/src/Repository.php @@ -1165,7 +1165,8 @@ protected function handleManyResult(array $keys, string $key, mixed $value): mix // genuine miss (null) and cached-null (sentinel) both resolve to the // per-key default, matching get()'s convention. if (is_null($value) || $value === NullSentinel::VALUE) { - return (isset($keys[$key]) && ! array_is_list($keys)) ? value($keys[$key]) : null; + // PHP stores canonical integer strings as integer keys, which are requested keys rather than defaults. + return isset($keys[$key]) && (string) (int) $key !== $key ? value($keys[$key]) : null; } return $value; diff --git a/tests/Cache/CacheRepositoryTest.php b/tests/Cache/CacheRepositoryTest.php index d281eefab..9e62dbbd7 100644 --- a/tests/Cache/CacheRepositoryTest.php +++ b/tests/Cache/CacheRepositoryTest.php @@ -165,6 +165,19 @@ public function testGetReturnsMultipleValuesFromCacheWhenGivenAnArrayOfOneTwoThr $this->assertEquals([1 => null, 2 => null, 3 => null], $repo->get([1, 2, 3])); } + public function testGetDoesNotUseRequestedKeysAsDefaultsForNumericKeys(): void + { + $repo = $this->getRepository(); + $repo->getStore()->expects('many')->with(['foo', '02', 'bar', '0'])->returns(['foo' => null, '02' => null, 'bar' => null, '0' => null]); + $repo->getStore()->expects('many')->with(['2', 'bar'])->returns(['2' => null, 'bar' => null]); + + $this->assertSame( + ['foo' => 'default', '02' => 'zero-two', 'bar' => null, 0 => null], + $repo->get(['foo' => 'default', '02' => 'zero-two', 'bar', '0']) + ); + $this->assertSame([2 => null, 'bar' => null], $repo->get([1 => '2', 2 => 'bar'])); + } + public function testDefaultValueIsReturned(): void { $repo = $this->getRepository(); From 6bce7bbf1beb7f11a78e97828874bffd1455da24 Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Thu, 19 Nov 2026 02:24:21 +0000 Subject: [PATCH 02/33] docs: track removing native Windows runtime support Hypervel runs on Swoole, which does not support native Windows. Record the framework-wide cleanup: remove Windows-only code paths and test expectations across every package, including standalone ones, and point Windows developers to WSL 2 in the platform docs. Public Laravel-compatible helpers and signatures stay, as does handling of Windows-originated input that is valid on a supported host. --- docs/todo.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/todo.md b/docs/todo.md index dec93ad04..3fbd1d8d7 100644 --- a/docs/todo.md +++ b/docs/todo.md @@ -21,6 +21,8 @@ ## Framework-wide +- Remove native Windows runtime support across all Hypervel packages, including standalone packages that do not depend on Swoole. Remove code paths and test expectations used only when running on native Windows, and direct Windows developers to WSL 2 in the platform docs. Preserve public Laravel-compatible helpers and signatures. Keep handling Windows-originated input wherever it is valid on a supported host. + - Audit the entire codebase for behavior missing from its contracts, designing them as complete greenfield framework interfaces rather than copying Laravel's omissions. Add methods every conforming implementation must provide, based on real consumers and implementation semantics; keep internal helpers and implementation- or driver-specific capabilities off general contracts. Update implementations, tests and public-contract documentation together. - In a separate PR, make factory-created dates immutable by contract, removing the application-wide mutable opt-out from `Date` / `DateFactory`, `now()` and `today()`. Audit custom classes, factories, callbacks and consumers; preserve useful timezone, locale and test-clock customization and immutable subclasses. Keep explicit mutable conversion at third-party boundaries. Update runtime enforcement, return types, tests and docs together, then tighten `hypervel/phpstan` typing and discarded-date diagnostics wherever immutability is guaranteed; retain accurate handling of external mutable dates. Review the Laravel API departures before implementation. From 0f21dbde766cb5d26fa0ccd6e0630282a93a962d Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Thu, 19 Nov 2026 03:18:20 +0000 Subject: [PATCH 03/33] Stop a canceled coroutine's sleep at the interruption Sleep splits a duration into a whole-second sleep and a microsecond remainder. When a non-throwing cancellation interrupted the whole-second part, the remainder still ran, and that normal wait cleared the coroutine's cancellation state, so the caller could no longer observe it. Inside a canceled coroutine, an interrupted whole-second sleep now ends the current iteration and returns to the caller's while condition. Sleeping outside coroutines, including signal-interrupted sleeps, is unchanged. Validation: the new SleepTest regression fails on the previous implementation and passes; SleepTest, formatting and full static analysis pass. --- src/support/src/Sleep.php | 8 +++++--- tests/Support/SleepTest.php | 15 +++++++++++++++ 2 files changed, 20 insertions(+), 3 deletions(-) diff --git a/src/support/src/Sleep.php b/src/support/src/Sleep.php index 8979e113c..74ded7b25 100644 --- a/src/support/src/Sleep.php +++ b/src/support/src/Sleep.php @@ -8,6 +8,7 @@ use Closure; use DateInterval; use DateTimeInterface; +use Hypervel\Engine\Coroutine; use Hypervel\Support\Attributes\TestsOnly; use Hypervel\Support\Facades\Date; use Hypervel\Support\Traits\Macroable; @@ -313,9 +314,10 @@ protected function goodnight(): void $microseconds = (int) $this->duration->totalMicroseconds - $seconds * Carbon::MICROSECONDS_PER_SECOND; while ($while()) { - if ($seconds > 0) { - // @phpstan-ignore hypervel.rawSleep (the Sleep implementation itself) - sleep($seconds); + // @phpstan-ignore hypervel.rawSleep (the Sleep implementation itself) + if ($seconds > 0 && sleep($seconds) !== 0 && Coroutine::isCanceled()) { + // Sleeping the remainder would hide the coroutine's cancellation from its caller. + continue; } if ($microseconds > 0) { diff --git a/tests/Support/SleepTest.php b/tests/Support/SleepTest.php index 49b3a4ca5..5ca1bade4 100644 --- a/tests/Support/SleepTest.php +++ b/tests/Support/SleepTest.php @@ -6,6 +6,7 @@ use Carbon\CarbonInterval; use DateInterval; +use Hypervel\Engine\Coroutine; use Hypervel\Support\Carbon; use Hypervel\Support\CarbonImmutable; use Hypervel\Support\Facades\Date; @@ -83,6 +84,20 @@ public function testItSleepsForTheFullDurationOnEveryWhileIteration(): void $this->assertGreaterThanOrEqual(2.9, $elapsed); } + public function testCancelingTheCoroutineEndsTheSleepWithoutSleepingTheRemainder(): void + { + $coroutine = Coroutine::id(); + Coroutine::create(static function () use ($coroutine): void { + usleep(50000); + Coroutine::cancelById($coroutine); + }); + + Sleep::for(1.5)->seconds(); + + // Sleeping the remainder would have reset the coroutine's cancellation state. + $this->assertTrue(Coroutine::isCanceled()); + } + #[TestWith([0])] #[TestWith([2])] public function testFakeSleepRespectsWhile(int $iterations): void From 158e31981e8553199c098bbd261af381899f71a0 Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Thu, 19 Nov 2026 03:18:20 +0000 Subject: [PATCH 04/33] Detect streaming cancellation only at the transport's own waits Coroutine::isCanceled() describes the coroutine's most recent wait, and it stays set after a cancellation the caller handled. The streaming body read it after curl_multi_exec(), which never waits, so every streaming request made after a handled cancellation failed with CanceledException. The body now clears Swoole's error before its hooked curl_multi_select() and treats the wait as canceled only when the coroutine is canceled and the select reported SWOOLE_ERROR_CO_CANCELED. The hooked select runs no PHP code, so that error belongs to this wait. The check after curl_multi_exec() is removed, along with the -1 select branch, which the hooked positive-timeout select never returns. The request delay applies the same check around its sleep. The unwrap of a cancellation that Guzzle wraps while rewinding or replaying the request body is kept. Root and hypervel/http now require hypervel/guzzle 8.5.0.2, whose transport stops promptly when a coroutine is canceled. Validation: regressions for a request after a handled cancellation and for a canceled delay fail before the change and pass; the streaming handler, streaming client and connection-release tests, formatting and full static analysis pass. --- composer.json | 2 +- src/http/composer.json | 2 +- src/http/src/Client/CurlStreamingBody.php | 16 +++------ src/http/src/Client/CurlStreamingHandler.php | 8 +++++ .../Http/Client/CurlStreamingHandlerTest.php | 35 +++++++++++++++++++ 5 files changed, 50 insertions(+), 13 deletions(-) diff --git a/composer.json b/composer.json index 69f0928b2..42373aeb4 100644 --- a/composer.json +++ b/composer.json @@ -59,7 +59,7 @@ "google/protobuf": "^5.35", "guzzlehttp/psr7": "^3.1", "guzzlehttp/uri-template": "^1.0 || ^2.0", - "hypervel/guzzle": "^8.3", + "hypervel/guzzle": "^8.5.0.2", "hypervel/guzzle-promises": "^3.1", "laravel/agent-detector": "^2.0.5", "laravel/serializable-closure": "^2.0.11", diff --git a/src/http/composer.json b/src/http/composer.json index 8499b9739..03ca8f2a1 100644 --- a/src/http/composer.json +++ b/src/http/composer.json @@ -39,7 +39,7 @@ "hypervel/coroutine": "^0.4", "hypervel/database": "^0.4", "hypervel/engine": "^0.4", - "hypervel/guzzle": "^8.3", + "hypervel/guzzle": "^8.5.0.2", "hypervel/guzzle-promises": "^3.1", "hypervel/macroable": "^0.4", "hypervel/object-pool": "^0.4", diff --git a/src/http/src/Client/CurlStreamingBody.php b/src/http/src/Client/CurlStreamingBody.php index d4be73f54..2fbfa8688 100644 --- a/src/http/src/Client/CurlStreamingBody.php +++ b/src/http/src/Client/CurlStreamingBody.php @@ -262,10 +262,6 @@ protected function advance(): void { $result = curl_multi_exec($this->connection->handle, $running); - if (Coroutine::isCanceled()) { - throw new CanceledException('The streaming request was canceled.'); - } - if ($result !== CURLM_OK) { throw new RuntimeException('Unable to read the streaming response: ' . curl_multi_strerror($result)); } @@ -333,7 +329,7 @@ protected function advance(): void try { $this->completedResponse = CurlFactory::finish($retry, $easy, $this->factory)->wait(); } catch (TransferException $exception) { - // Completion callbacks run after the native cancellation check above. + // Guzzle still wraps a cancellation thrown while rewinding or replaying the request body. // @phpstan-ignore hypervel.cancellation.exactType (restores the direct cancellation Guzzle wrapped; a deeper carrier still propagates) if ($exception->getPrevious() instanceof CanceledException) { throw $exception->getPrevious(); @@ -369,17 +365,15 @@ protected function wait(?float &$idleDeadline, bool $headers = false): void throw new RuntimeException('The streaming response read timed out.'); } + // The hooked select runs no PHP code, so after clearing, a cancellation error can only come from this wait. + swoole_clear_error(); $selected = curl_multi_select($this->connection->handle, min(1.0, $remaining)); - if (Coroutine::isCanceled()) { + if (Coroutine::isCanceled() && swoole_last_error() === SWOOLE_ERROR_CO_CANCELED) { throw new CanceledException('The streaming request was canceled.'); } - if ($selected === -1) { - // libcurl can briefly have no descriptors while scheduling its next action. - // @phpstan-ignore hypervel.rawSleep (libcurl needs real time to schedule its next action) - usleep(1000); - } elseif ($selected > 0 && $this->readTimeout > 0) { + if ($selected > 0 && $this->readTimeout > 0) { $idleDeadline = hrtime(true) / 1e9 + $this->readTimeout; } } diff --git a/src/http/src/Client/CurlStreamingHandler.php b/src/http/src/Client/CurlStreamingHandler.php index b9f3ad25a..6a9d270f5 100644 --- a/src/http/src/Client/CurlStreamingHandler.php +++ b/src/http/src/Client/CurlStreamingHandler.php @@ -18,11 +18,13 @@ use GuzzleHttp\Psr7\HttpFactory; use GuzzleHttp\TransportSharing; use Hypervel\Coroutine\Coroutine; +use Hypervel\Engine\Coroutine as EngineCoroutine; use Hypervel\Support\Sleep; use InvalidArgumentException; use Psr\Http\Message\RequestInterface; use Psr\Http\Message\ResponseInterface; use RuntimeException; +use Swoole\Coroutine\CanceledException; use Swoole\Runtime; use Throwable; @@ -97,7 +99,13 @@ public function __invoke(RequestInterface $request, array $options): PromiseInte HostValidator::assertRequestHost($request); if (isset($options['delay'])) { + // An earlier, handled cancellation must not make this delay look canceled. + swoole_clear_error(); Sleep::usleep((int) ($options['delay'] * 1000)); + + if (EngineCoroutine::isCanceled() && swoole_last_error() === SWOOLE_ERROR_CO_CANCELED) { + throw new CanceledException('The streaming request was canceled.'); + } } $timeout = $this->timeout($options['timeout'] ?? 0, 'timeout'); diff --git a/tests/Http/Client/CurlStreamingHandlerTest.php b/tests/Http/Client/CurlStreamingHandlerTest.php index 751603dfd..cbc87aef1 100644 --- a/tests/Http/Client/CurlStreamingHandlerTest.php +++ b/tests/Http/Client/CurlStreamingHandlerTest.php @@ -376,6 +376,41 @@ public static function trailerBodySizes(): array return [[5], [65536]]; } + public function testAHandledCancellationDoesNotCancelALaterRequest(): void + { + $server = LoopbackHttpServer::start([['body' => 'hello']]); + $coroutine = Coroutine::id(); + Coroutine::create(static function () use ($coroutine): void { + usleep(10000); + Coroutine::cancelById($coroutine); + }); + + $this->assertFalse((new Channel(1))->pop(1)); + $this->assertTrue(Coroutine::isCanceled()); + + $response = (new Factory)->withOptions(['stream' => true])->get('http://127.0.0.1:' . $server->port); + + $this->assertSame('hello', $response->body()); + } + + public function testCancelingTheDelayCancelsTheRequest(): void + { + $coroutine = Coroutine::id(); + Coroutine::create(static function () use ($coroutine): void { + usleep(50000); + Coroutine::cancelById($coroutine); + }); + + try { + // The canceled delay ends the request before it connects. + (new Factory)->withOptions(['stream' => true, 'delay' => 1500])->get('http://127.0.0.1:1'); + + $this->fail('Expected the delay cancellation.'); + } catch (CanceledException $exception) { + $this->assertSame('The streaming request was canceled.', $exception->getMessage()); + } + } + public function testAbandonedResponseBodyIsReleasedWithoutCyclicGarbageCollection(): void { $factory = new class(new CurlFactory(0)) implements CurlFactoryInterface { From c3cde009cc2c20490815169b4c410b9098c12d30 Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Thu, 19 Nov 2026 03:18:20 +0000 Subject: [PATCH 05/33] Classify credential cancellation only from this call's waits SerializedCredentialProvider treated any provider failure as a cancellation while the coroutine's cancellation flag was set. The flag survives a cancellation the caller already handled, so an ordinary rejection from a provider that never waited was reported as CanceledException. The provider now clears Swoole's error after taking the lock and before invoking the provider. A failure without a cancellation in its chain counts as canceled only when the coroutine is canceled and a wait during the call reported SWOOLE_ERROR_CO_CANCELED or SOCKET_ECANCELED. This keeps the fallback for SDK providers that rethrow an interrupted fetch without its cause, including a second interruption after a handled one. Validation: the ordinary-rejection regression fails before the change and passes; the translated-cancellation test covers clean and previously canceled entry with lock release; credential provider and consumer tests, formatting and full static analysis pass. --- .../src/Aws/SerializedCredentialProvider.php | 9 ++- .../SerializedCredentialProviderTest.php | 64 +++++++++++++++---- 2 files changed, 57 insertions(+), 16 deletions(-) diff --git a/src/support/src/Aws/SerializedCredentialProvider.php b/src/support/src/Aws/SerializedCredentialProvider.php index 9c7678200..c7ec97131 100644 --- a/src/support/src/Aws/SerializedCredentialProvider.php +++ b/src/support/src/Aws/SerializedCredentialProvider.php @@ -68,6 +68,9 @@ public function __invoke(mixed ...$arguments): PromiseInterface static::$owners[$this->lockKey] = $coroutine; } + // An earlier, handled cancellation must not make this provider's failure look canceled. + swoole_clear_error(); + try { return Create::promiseFor(($this->provider)(...$arguments)->wait()); } catch (Throwable $exception) { @@ -75,8 +78,10 @@ public function __invoke(mixed ...$arguments): PromiseInterface throw $exception; } - // SDK providers can wrap an interrupted fetch in CredentialsException. - if (EngineCoroutine::isCanceled()) { + // SDK providers can rethrow an interrupted fetch without its cause. + if (EngineCoroutine::isCanceled() + && in_array(swoole_last_error(), [SWOOLE_ERROR_CO_CANCELED, SOCKET_ECANCELED], true) + ) { throw new CanceledException('Resolving AWS credentials was canceled.', previous: $exception); } diff --git a/tests/Support/SerializedCredentialProviderTest.php b/tests/Support/SerializedCredentialProviderTest.php index 2ab45ab11..52bb3b55d 100644 --- a/tests/Support/SerializedCredentialProviderTest.php +++ b/tests/Support/SerializedCredentialProviderTest.php @@ -14,6 +14,7 @@ use Hypervel\Support\Aws\SerializedCredentialProvider; use Hypervel\Tests\TestCase; use PHPUnit\Framework\Attributes\DataProvider; +use PHPUnit\Framework\Attributes\TestWith; use RuntimeException; use Swoole\Coroutine\CanceledException; @@ -190,27 +191,33 @@ public function testCancellationExceptionIsPropagatedUnchangedAndReleasesTheLock $this->assertSame('next', $provider()->wait()->getAccessKeyId()); } - public function testTranslatedCancellationRemainsCancellationAndReleasesTheLock(): void + #[TestWith([false], 'clean entry')] + #[TestWith([true], 'after a handled cancellation')] + public function testTranslatedCancellationRemainsCancellationAndReleasesTheLock(bool $handledCancellation): void { $started = new Channel(1); - $blocked = new Channel(1); $finished = new Channel(1); $failure = new RuntimeException('The SDK translated an interrupted fetch.'); $calls = 0; - $provider = new SerializedCredentialProvider(function () use (&$calls, $started, $blocked, $failure): PromiseInterface { + $provider = new SerializedCredentialProvider(function () use (&$calls, $started, $failure): PromiseInterface { if (++$calls > 1) { return Create::promiseFor(new Credentials('next', 'secret')); } - return new Promise(static function () use ($started, $blocked, $failure): never { + return new Promise(static function () use ($started, $failure): never { $started->push(true); - $blocked->pop(); + // A native wait, like the SDK's transfer, reports its cancellation. + usleep(2000000); throw $failure; }); }); - $owner = go(static function () use ($provider, $finished): void { + $owner = go(function () use ($provider, $finished, $handledCancellation): void { + if ($handledCancellation) { + $this->handleCancellation(); + } + try { $provider(); $finished->push(null); @@ -219,18 +226,47 @@ public function testTranslatedCancellationRemainsCancellationAndReleasesTheLock( } }); + $this->assertTrue($started->pop(1)); + // Channel delivery can resume us before the owner enters its wait. + usleep(1000); + $this->assertTrue(Coroutine::cancelById($owner)); + $result = $finished->pop(1); + $this->assertInstanceOf(CanceledException::class, $result); + $this->assertSame($failure, $result->getPrevious()); + $this->assertSame('next', $provider()->wait()->getAccessKeyId()); + } + + public function testAFailureAfterAHandledCancellationIsNotReportedAsCanceled(): void + { + $this->handleCancellation(); + $failure = new RuntimeException('Credentials unavailable.'); + $provider = new SerializedCredentialProvider(static fn (): PromiseInterface => Create::rejectionFor($failure)); + + $result = $provider(); + try { - $this->assertTrue($started->pop(1)); - $this->assertTrue(Coroutine::cancelById($owner)); - $result = $finished->pop(1); - $this->assertInstanceOf(CanceledException::class, $result); - $this->assertSame($failure, $result->getPrevious()); - $this->assertSame('next', $provider()->wait()->getAccessKeyId()); - } finally { - $blocked->close(); + $result->wait(); + $this->fail('The credential failure was not propagated.'); + } catch (RuntimeException $exception) { + $this->assertSame($failure, $exception); } } + /** + * Leave the current coroutine canceled by an earlier wait that it handled. + */ + private function handleCancellation(): void + { + $coroutine = Coroutine::id(); + go(static function () use ($coroutine): void { + usleep(10000); + Coroutine::cancelById($coroutine); + }); + + $this->assertFalse((new Channel(1))->pop(1)); + $this->assertTrue(Coroutine::isCanceled()); + } + public function testCancelingALockWaiterDoesNotReleaseTheOwnersLock(): void { $entered = new Channel(2); From 5a9a2b21e293b432c0117494e605ec2d230673fe Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Thu, 19 Nov 2026 03:18:20 +0000 Subject: [PATCH 06/33] Classify Redis cancellation at each native operation Redis cancellation was inferred from the coroutine's cancellation flag in outer layers, after macros, reconnects and callbacks had run. The flag survives a cancellation the caller already handled, so a synchronous phpredis failure, such as a corrupt serialized value, was reported as CanceledException. phpredis keeps a thrown cancellation as the exception's cause, and a non-throwing cancellation leaves SOCKET_ECANCELED. Each native boundary now clears Swoole's error immediately before the operation and classifies its failure before invalidation reads the client: command dispatch, evalWithShaCache(), discardTransaction(), close(), heartbeat pings, reconnects, Cluster connects and each Sentinel node. Macros keep their own failures and invalidation. Proxy commands and Cluster discovery keep exception identity. Held and pinned callbacks, and transaction callbacks and EXEC separately, classify escaping phpredis failures after a clear, so native pipelines executed inside them keep real cancellations. Tests that simulated cancellation by throwing a plain RedisException after a canceled channel pop now use the cause phpredis actually provides. Validation: RESP-server tests cover stalled commands, transaction EXEC, held pipeline EXEC and DISCARD under throwing and non-throwing cancellation, and a failure after a handled cancellation keeps its RedisException; the Redis unit, integration and Redis cache suites, formatting and full static analysis pass. --- src/redis/src/PhpRedisClusterConnection.php | 1 + src/redis/src/PhpRedisConnection.php | 2 + src/redis/src/RedisCancellation.php | 7 +- src/redis/src/RedisConnection.php | 46 ++++-- src/redis/src/RedisProxy.php | 21 +-- src/redis/src/RedisSentinelFactory.php | 2 + .../Redis/RedisCancellationLifecycleTest.php | 135 +++++++++++++++++- tests/Redis/RedisCancellationTest.php | 55 +++---- tests/Redis/RedisConnectionTest.php | 85 +++-------- tests/Redis/RedisProxyTest.php | 71 ++++----- 10 files changed, 257 insertions(+), 168 deletions(-) diff --git a/src/redis/src/PhpRedisClusterConnection.php b/src/redis/src/PhpRedisClusterConnection.php index da9a066c1..c7eb807e0 100644 --- a/src/redis/src/PhpRedisClusterConnection.php +++ b/src/redis/src/PhpRedisClusterConnection.php @@ -371,6 +371,7 @@ protected function createRedisCluster(): RedisCluster ); } + swoole_clear_error(); $redis = new RedisCluster(...$parameters); } catch (Throwable $exception) { if ($cancellation = RedisCancellation::cancellationFrom( diff --git a/src/redis/src/PhpRedisConnection.php b/src/redis/src/PhpRedisConnection.php index 23fd219c9..5044bad4a 100644 --- a/src/redis/src/PhpRedisConnection.php +++ b/src/redis/src/PhpRedisConnection.php @@ -39,6 +39,8 @@ public function __construct(Container $container, ConnectionPool $pool, array $c public function reconnect(): bool { try { + swoole_clear_error(); + $database = ! $this->invalid && $this->connection instanceof Redis && $this->connection->isConnected() diff --git a/src/redis/src/RedisCancellation.php b/src/redis/src/RedisCancellation.php index c45b5eef2..fe3ebab8b 100644 --- a/src/redis/src/RedisCancellation.php +++ b/src/redis/src/RedisCancellation.php @@ -20,6 +20,9 @@ class RedisCancellation { /** * Resolve an exact or native phpredis cancellation. + * + * Call swoole_clear_error() immediately before the native operation, so an earlier + * cancellation the coroutine already handled cannot be mistaken for this one. */ public static function cancellationFrom(Throwable $exception, string $message): ?CanceledException { @@ -28,8 +31,10 @@ public static function cancellationFrom(Throwable $exception, string $message): return $exception; } + // phpredis keeps a thrown cancellation as the cause; a non-throwing one leaves only the socket error. if (($exception instanceof RedisException || $exception instanceof RedisClusterException) - && EngineCoroutine::isCanceled() + && (Coroutine::causedByCancellation($exception) + || (EngineCoroutine::isCanceled() && swoole_last_error() === SOCKET_ECANCELED)) ) { return new CanceledException($message, previous: $exception); } diff --git a/src/redis/src/RedisConnection.php b/src/redis/src/RedisConnection.php index 4bf9f7ea3..d62f50a8e 100644 --- a/src/redis/src/RedisConnection.php +++ b/src/redis/src/RedisConnection.php @@ -361,20 +361,29 @@ public function __construct(Container $container, ConnectionPool $pool, array $c */ public function __call(string $name, array $arguments): mixed { + $command = false; + try { if (static::hasMacro($name)) { return $this->macroCall($name, $arguments); } $name = strtolower($name); + $command = true; + swoole_clear_error(); $result = $this->executeCommand($name, $arguments); } catch (RedisException|RedisClusterException|ErrorException $exception) { + // Classify before invalidation reads the client's state; a macro's failure keeps its own meaning. + $cancellation = $command + ? RedisCancellation::cancellationFrom($exception, "Executing Redis command [{$name}] was canceled.") + : null; + // REMOVED: Laravel's command retry loop can replay writes Redis already committed. - if ($this->shouldInvalidateAfter($exception)) { + if ($cancellation !== null || $this->shouldInvalidateAfter($exception)) { $this->markInvalid(); } - throw $exception; + throw $cancellation ?? $exception; } if ($name === 'watch' && $result !== false) { @@ -662,6 +671,7 @@ protected function parseBackoffAlgorithm(mixed $algorithm): int public function close(): bool { try { + swoole_clear_error(); $this->connection?->close(); } catch (Throwable $exception) { if ($cancellation = RedisCancellation::cancellationFrom( @@ -723,11 +733,8 @@ public function release(): void try { $queueing = $this->isQueueingMode(); } catch (Throwable $exception) { - if ($cancellation = RedisCancellation::cancellationFrom( - $exception, - 'Inspecting Redis connection state during release was canceled.', - )) { - $this->releaseAfterCancellation($cancellation); + if (Coroutine::causedByCancellation($exception)) { + $this->releaseAfterCancellation($exception); } $this->markInvalid(); @@ -789,10 +796,9 @@ public function release(): void } } } catch (Throwable $exception) { - if ($cancellation = RedisCancellation::cancellationFrom( - $exception, - 'Preparing the Redis connection for release was canceled.', - )) { + // Only SELECT waits here, and command dispatch already classified its cancellation. + if (Coroutine::causedByCancellation($exception)) { + $cancellation = $exception; $this->markInvalid(); } else { $this->markInvalid(); @@ -867,7 +873,12 @@ private function releaseAfterCancellation(Throwable $cancellation): never */ public function discardTransaction(): bool|Redis { - $result = $this->connection->discard(); + try { + swoole_clear_error(); + $result = $this->connection->discard(); + } catch (RedisException|RedisClusterException $exception) { + throw RedisCancellation::cancellationFrom($exception, 'Discarding the Redis transaction was canceled.') ?? $exception; + } if ($result !== false) { $this->watching = false; @@ -986,6 +997,8 @@ public static function hasHashTag(string $key): bool protected function pingForHeartbeat(): bool { try { + swoole_clear_error(); + if ($this->connection instanceof Redis) { return $this->connection->ping() !== false; } @@ -1979,6 +1992,8 @@ public function evalWithShaCache(string $script, array $keys = [], array $args = $combinedArgs = [...$keys, ...$args]; try { + swoole_clear_error(); + // Clear any stale error from previous commands to ensure getLastError() // reflects this call, not a previous one $this->connection->clearLastError(); @@ -2010,11 +2025,14 @@ public function evalWithShaCache(string $script, array $keys = [], array $args = return $this->normalizeNullReplies($result); } catch (RedisException|RedisClusterException|ErrorException $exception) { - if ($this->shouldInvalidateAfter($exception)) { + // Classify before invalidation reads the client's state. + $cancellation = RedisCancellation::cancellationFrom($exception, 'Executing the Redis script was canceled.'); + + if ($cancellation !== null || $this->shouldInvalidateAfter($exception)) { $this->markInvalid(); } - throw $exception; + throw $cancellation ?? $exception; } } diff --git a/src/redis/src/RedisProxy.php b/src/redis/src/RedisProxy.php index c71ff7939..a8ee4a5e9 100644 --- a/src/redis/src/RedisProxy.php +++ b/src/redis/src/RedisProxy.php @@ -224,7 +224,11 @@ private function executeMultiExec(string $command, ?callable $callback = null): $cleanupFailure = null; try { - $result = tap($instance, $callback)->exec(); + // The callback drives the native client, so classify its escaping failures and EXEC's separately. + swoole_clear_error(); + $callback($instance); + swoole_clear_error(); + $result = $instance->exec(); if ($command === 'multi' && $hasExistingConnection) { $connection = CoroutineContext::get($this->getContextKey()); @@ -294,10 +298,8 @@ public function __call(string $name, array $arguments): mixed ? $connection->discardTransaction() : $connection->{$name}(...$arguments); } catch (Throwable $throwable) { - $commandException = RedisCancellation::cancellationFrom( - $throwable, - "Executing Redis command [{$name}] was canceled.", - ) ?? $throwable; + $commandException = $throwable; + if (! Coroutine::causedByCancellation($commandException)) { try { $dispatcher = $connection->getEventDispatcher(); @@ -585,6 +587,8 @@ public function withConnection(callable $callback, bool $transform = true): mixe try { $connection->getConnection(); + // The callback can drive the native client directly, such as a pipeline it executes. + swoole_clear_error(); $result = $callback($connection); } catch (Throwable $exception) { $operationFailure = RedisCancellation::cancellationFrom( @@ -633,6 +637,7 @@ public function withPinnedConnection(callable $callback): mixed try { $connection->getConnection(); + swoole_clear_error(); $result = $callback(); } catch (Throwable $exception) { $operationFailure = RedisCancellation::cancellationFrom( @@ -736,10 +741,8 @@ public function subscriber(): Subscriber $connection->getConnection(); $masters = $connection->masters(); } catch (Throwable $exception) { - $discoveryException = RedisCancellation::cancellationFrom( - $exception, - 'Discovering Redis Cluster masters was canceled.', - ) ?? $exception; + // Master discovery reads the client's cached topology; only reconnecting waits, and it classifies itself. + $discoveryException = $exception; } if ($contextConnection === null) { diff --git a/src/redis/src/RedisSentinelFactory.php b/src/redis/src/RedisSentinelFactory.php index 5479e20ab..33f290c44 100644 --- a/src/redis/src/RedisSentinelFactory.php +++ b/src/redis/src/RedisSentinelFactory.php @@ -57,6 +57,8 @@ public function resolveMaster(array $config): array } try { + swoole_clear_error(); + $options = [ 'host' => $hasScheme ? "{$resolved['scheme']}://{$resolved['host']}" diff --git a/tests/Redis/RedisCancellationLifecycleTest.php b/tests/Redis/RedisCancellationLifecycleTest.php index b29126df8..7fad0cd40 100644 --- a/tests/Redis/RedisCancellationLifecycleTest.php +++ b/tests/Redis/RedisCancellationLifecycleTest.php @@ -4,6 +4,7 @@ namespace Hypervel\Tests\Redis; +use Closure; use Hypervel\ConnectionPool\Exceptions\ConnectionException; use Hypervel\Engine\Channel; use Hypervel\Engine\Coroutine; @@ -11,16 +12,22 @@ use Hypervel\Redis\Events\CommandFailed; use Hypervel\Redis\Pool\PoolManager; use Hypervel\Redis\RedisConnection; +use Hypervel\Redis\RedisProxy; use Hypervel\Support\Facades\Redis as RedisFacade; use Hypervel\Testbench\TestCase; use Hypervel\Tests\Redis\Fixtures\RespServer; +use PHPUnit\Framework\Attributes\DataProvider; +use PHPUnit\Framework\Attributes\TestWith; +use Redis; use RedisException; use Swoole\Coroutine\CanceledException; use Throwable; class RedisCancellationLifecycleTest extends TestCase { - public function testBlockedCommandCancellationInvalidatesAndReturnsTheLeaseWithoutEvents(): void + #[TestWith([true], 'throwing cancellation')] + #[TestWith([false], 'non-throwing cancellation')] + public function testBlockedCommandCancellationInvalidatesAndReturnsTheLeaseWithoutEvents(bool $throwException): void { $server = new RespServer; $commandReceived = new Channel(1); @@ -62,6 +69,7 @@ public function testBlockedCommandCancellationInvalidatesAndReturnsTheLeaseWitho $exception = $this->cancelAfter( static fn () => $connection->blpop('blocked', 0), $commandReceived, + $throwException, ); $this->assertInstanceOf(CanceledException::class, $exception); @@ -151,6 +159,127 @@ public function testBlockedSelectCancellationRepairsPoolCapacity(): void } } + #[DataProvider('nativeClientOperations')] + public function testNativeClientCancellationIsClassifiedAtItsBoundary( + string $stallOn, + Closure $operation, + string $message, + bool $throwException, + ): void { + $server = new RespServer; + $entered = new Channel(1); + $releaseServer = new Channel(1); + $server->start(function ($client) use ($stallOn, $entered, $releaseServer): void { + while (is_string($command = fread($client, 4096)) && $command !== '') { + if (str_contains($command, $stallOn)) { + $entered->push(true); + $releaseServer->pop(2.0); + + return; + } + + fwrite($client, str_contains($command, 'MULTI') ? "+OK\r\n" : "+QUEUED\r\n"); + } + }); + + [$host, $port] = $server->hostAndPort(); + $connectionName = 'canceled_native_client'; + $this->configureConnection($connectionName, $host, $port); + $redis = RedisFacade::connection($connectionName); + + try { + $exception = $this->cancelAfter(static fn () => $operation($redis), $entered, $throwException); + + $this->assertInstanceOf(CanceledException::class, $exception); + $this->assertSame($message, $exception->getMessage()); + $this->assertInstanceOf(RedisException::class, $exception->getPrevious()); + } finally { + $releaseServer->push(true); + + try { + $server->wait(); + } finally { + $this->app->make(PoolManager::class)->purge($connectionName); + } + } + } + + /** + * Provide native-client operations that wait outside command dispatch, in both cancellation modes. + */ + public static function nativeClientOperations(): iterable + { + $operations = [ + 'transaction exec' => [ + 'EXEC', + static fn (RedisProxy $redis) => $redis->transaction(static fn (Redis $client) => $client->set('key', 'value')), + 'Executing the Redis transaction was canceled.', + ], + 'held pipeline exec' => [ + 'SET', + static fn (RedisProxy $redis) => $redis->withConnection( + static fn (RedisConnection $connection) => $connection->pipeline()->set('key', 'value')->exec(), + ), + 'Using a Redis connection was canceled.', + ], + 'held discard' => [ + 'DISCARD', + static fn (RedisProxy $redis) => $redis->withConnection(static function (RedisConnection $connection): void { + $connection->multi(); + $connection->discardTransaction(); + }), + 'Discarding the Redis transaction was canceled.', + ], + ]; + + foreach ($operations as $name => $operation) { + yield "{$name}, throwing" => [...$operation, true]; + yield "{$name}, non-throwing" => [...$operation, false]; + } + } + + public function testFailureAfterAHandledCancellationKeepsItsRedisException(): void + { + $server = new RespServer; + $releaseServer = new Channel(1); + $server->start(static function () use ($releaseServer): void { + $releaseServer->pop(2.0); + }); + + [$host, $port] = $server->hostAndPort(); + $connectionName = 'stale_cancellation'; + $this->configureConnection($connectionName, $host, $port, [ + 'options' => ['prefix' => '', 'serializer' => Redis::SERIALIZER_PHP], + ]); + $redis = RedisFacade::connection($connectionName); + + try { + // Connect first, because connecting waits and would reset the cancellation state. + $this->assertIsString($redis->_serialize('value')); + $coroutine = Coroutine::id(); + Coroutine::create(static function () use ($coroutine): void { + usleep(10000); + Coroutine::cancelById($coroutine); + }); + + $this->assertFalse((new Channel(1))->pop(1.0)); + $this->assertTrue(Coroutine::isCanceled()); + + // The unserialize failure doesn't wait, so the earlier cancellation must not claim it. + $this->expectException(RedisException::class); + + $redis->_unserialize('corrupt'); + } finally { + $releaseServer->push(true); + + try { + $server->wait(); + } finally { + $this->app->make(PoolManager::class)->purge($connectionName); + } + } + } + /** * Configure shared Redis options and one connection for a local test server. * @@ -190,7 +319,7 @@ private function configureConnection(string $name, string $host, int $port, arra /** * Cancel an operation after its native I/O boundary has been reached. */ - private function cancelAfter(callable $operation, Channel $entered): Throwable + private function cancelAfter(callable $operation, Channel $entered, bool $throwException = true): Throwable { $result = new Channel(1); $coroutine = Coroutine::create(static function () use ($operation, $result): void { @@ -208,7 +337,7 @@ private function cancelAfter(callable $operation, Channel $entered): Throwable $enteredOperation = $entered->pop(2.0); if ($enteredOperation) { - $cancellationRequested = Coroutine::cancelById($coroutine->getId(), throwException: true); + $cancellationRequested = Coroutine::cancelById($coroutine->getId(), $throwException); } } finally { try { diff --git a/tests/Redis/RedisCancellationTest.php b/tests/Redis/RedisCancellationTest.php index 83cec0dfa..0996edfac 100644 --- a/tests/Redis/RedisCancellationTest.php +++ b/tests/Redis/RedisCancellationTest.php @@ -50,38 +50,39 @@ public function testFailureSelectionPreservesWrappedCancellation(bool $operation $this->assertSame($operationCanceled ? $operation : $cleanup, $caught); } - public function testItNormalizesOnlyNativePhpRedisFailuresAtTheCancellationBoundary(): void + public function testItNormalizesOnlyPhpRedisFailuresCarryingACancellation(): void { - $blocker = new Channel(1); - $cancellations = []; $failures = [ - new RedisException('read canceled'), - new RedisClusterException('cluster read canceled'), + new RedisException('read canceled', previous: new CanceledException), + new RedisClusterException('cluster read canceled', previous: new CanceledException), ]; - $coroutine = Coroutine::create(function () use ($blocker, $failures, &$cancellations): void { - try { - $blocker->pop(); - } catch (CanceledException) { - foreach ($failures as $failure) { - $cancellations[] = RedisCancellation::cancellationFrom($failure, 'Reading from Redis was canceled.'); - } - - $cancellations[] = RedisCancellation::cancellationFrom( - new RuntimeException('failed'), - 'Reading from Redis was canceled.', - ); - } + foreach ($failures as $failure) { + $cancellation = RedisCancellation::cancellationFrom($failure, 'Reading from Redis was canceled.'); + + $this->assertInstanceOf(CanceledException::class, $cancellation); + $this->assertSame('Reading from Redis was canceled.', $cancellation->getMessage()); + $this->assertSame($failure, $cancellation->getPrevious()); + } + + $this->assertNull(RedisCancellation::cancellationFrom( + new RuntimeException('failed', previous: new CanceledException), + 'Reading from Redis was canceled.', + )); + } + + public function testItDoesNotClassifyAFailureAfterAHandledCancellation(): void + { + $coroutine = Coroutine::id(); + Coroutine::create(static function () use ($coroutine): void { + usleep(10000); + Coroutine::cancelById($coroutine); }); - $this->assertTrue(Coroutine::cancelById($coroutine->getId(), throwException: true)); - $this->assertCount(3, $cancellations); - $this->assertInstanceOf(CanceledException::class, $cancellations[0]); - $this->assertSame('Reading from Redis was canceled.', $cancellations[0]->getMessage()); - $this->assertSame($failures[0], $cancellations[0]->getPrevious()); - $this->assertInstanceOf(CanceledException::class, $cancellations[1]); - $this->assertSame('Reading from Redis was canceled.', $cancellations[1]->getMessage()); - $this->assertSame($failures[1], $cancellations[1]->getPrevious()); - $this->assertNull($cancellations[2]); + $this->assertFalse((new Channel(1))->pop(1)); + $this->assertTrue(Coroutine::isCanceled()); + swoole_clear_error(); + + $this->assertNull(RedisCancellation::cancellationFrom(new RedisException('failed'), 'Reading from Redis was canceled.')); } } diff --git a/tests/Redis/RedisConnectionTest.php b/tests/Redis/RedisConnectionTest.php index f93808f38..e96a7721f 100644 --- a/tests/Redis/RedisConnectionTest.php +++ b/tests/Redis/RedisConnectionTest.php @@ -5,7 +5,6 @@ namespace Hypervel\Tests\Redis; use BadMethodCallException; -use Closure; use ErrorException; use Hypervel\ConnectionPool\Events\ConnectionReleasing; use Hypervel\ConnectionPool\Exceptions\ConnectionException; @@ -14,8 +13,6 @@ use Hypervel\Contracts\ConnectionPool\ConnectionPool; use Hypervel\Contracts\Container\Container as ContainerContract; use Hypervel\Contracts\Log\StdoutLoggerInterface; -use Hypervel\Coroutine\Coroutine; -use Hypervel\Engine\Coroutine as EngineCoroutine; use Hypervel\Events\Dispatcher; use Hypervel\Redis\Exceptions\InvalidRedisOptionException; use Hypervel\Redis\Exceptions\LuaScriptException; @@ -43,7 +40,6 @@ use ReflectionProperty; use RuntimeException; use Swoole\Coroutine\CanceledException; -use Swoole\Coroutine\Channel as SwooleChannel; use Symfony\Component\Process\Process; use Throwable; use TypeError; @@ -433,9 +429,13 @@ public function isInvalidForTest(): bool $this->assertTrue($connection->isInvalidForTest()); } - public function testReleasePreservesExactCancellationWithoutDispatchingReleaseObservers(): void + #[TestWith([false], 'direct cancellation')] + #[TestWith([true], 'phpredis failure carrying a cancellation')] + public function testReleasePreservesCancellationWithoutDispatchingReleaseObservers(bool $carried): void { - $cancellation = new CanceledException('mode canceled'); + $cancellation = $carried + ? new RedisException('mode canceled', previous: new CanceledException) + : new CanceledException('mode canceled'); $releaseObserved = false; $container = $this->getContainer(); $dispatcher = new Dispatcher($container); @@ -443,6 +443,9 @@ public function testReleasePreservesExactCancellationWithoutDispatchingReleaseOb $releaseObserved = true; }); $container->instance('events', $dispatcher); + $logger = Double::for(StdoutLoggerInterface::class)->strict(); + $logger->expects('log')->never(); + $container->instance(StdoutLoggerInterface::class, $logger); $pool = Double::for(ConnectionPool::class)->strict(); $pool->allows('getOptions')->returns(PoolOptions::fromArray(['events' => [ConnectionReleasing::class]])); $pool->expects('release')->with(Argument::type(RedisConnection::class)); @@ -456,7 +459,7 @@ public function testReleasePreservesExactCancellationWithoutDispatchingReleaseOb try { $connection->release(); $this->fail('Expected the cancellation to escape.'); - } catch (CanceledException $exception) { + } catch (Throwable $exception) { $this->assertSame($cancellation, $exception); } @@ -467,39 +470,6 @@ public function testReleasePreservesExactCancellationWithoutDispatchingReleaseOb ); } - public function testReleaseNormalizesWrappedPhpRedisCancellation(): void - { - $nativeFailure = new RedisException('mode canceled'); - $releaseObserved = false; - $container = $this->getContainer(); - $dispatcher = new Dispatcher($container); - $dispatcher->listen(ConnectionReleasing::class, function () use (&$releaseObserved): void { - $releaseObserved = true; - }); - $container->instance('events', $dispatcher); - $logger = Double::for(StdoutLoggerInterface::class)->strict(); - $logger->expects('log')->never(); - $container->instance(StdoutLoggerInterface::class, $logger); - $pool = Double::for(ConnectionPool::class)->strict(); - $pool->allows('getOptions')->returns(PoolOptions::fromArray(['events' => [ConnectionReleasing::class]])); - $pool->expects('release')->with(Argument::type(RedisConnection::class)); - $pool->expects('discard')->never(); - $redis = Double::for(Redis::class)->strict(); - $redis->expects('getMode')->throws($nativeFailure); - $redis->expects('close')->never(); - $connection = $this->mockRedisConnection(container: $container, pool: $pool); - $connection->setActiveConnection($redis); - - $exception = $this->captureCancellationAtBoundary(function () use ($connection): void { - $connection->release(); - }); - - $this->assertInstanceOf(CanceledException::class, $exception); - $this->assertSame($nativeFailure, $exception->getPrevious()); - $this->assertFalse($releaseObserved); - $this->assertTrue($connection->isInvalidForTest()); - } - public function testReleasePreservesOperationCancellationOverPoolCleanupCancellation(): void { $cancellation = new CanceledException('mode canceled'); @@ -557,7 +527,7 @@ public function testCancellationFromQueueingWarningInvalidatesAndReleasesWithout public function testReleaseNormalizesWrappedCancellationFromNativeClose(): void { - $nativeFailure = new RedisException('close canceled'); + $nativeFailure = new RedisException('close canceled', previous: new CanceledException); $logger = Double::for(StdoutLoggerInterface::class)->strict(); $logger->expects('log')->never(); $container = $this->getContainer(); @@ -571,12 +541,16 @@ public function testReleaseNormalizesWrappedCancellationFromNativeClose(): void $redis->expects('close')->throws($nativeFailure); $connection = $this->mockRedisConnection(container: $container, pool: $pool); $connection->setActiveConnection($redis); + $exception = null; - $exception = $this->captureCancellationAtBoundary(function () use ($connection): void { + try { $connection->release(); - }); + } catch (Throwable $caught) { + $exception = $caught; + } $this->assertInstanceOf(CanceledException::class, $exception); + $this->assertSame('Closing the Redis connection was canceled.', $exception->getMessage()); $this->assertSame($nativeFailure, $exception->getPrevious()); $this->assertNull($connection->client()); } @@ -3861,31 +3835,6 @@ protected function getMockedPool(): ConnectionPool return $pool; } - /** - * Capture cancellation raised while the current coroutine is canceled. - */ - protected function captureCancellationAtBoundary(Closure $callback): Throwable - { - $blocker = new SwooleChannel(1); - $captured = null; - $coroutineId = Coroutine::create(function () use ($blocker, $callback, &$captured): void { - try { - $blocker->pop(); - } catch (CanceledException) { - try { - $callback(); - } catch (Throwable $exception) { - $captured = $exception; - } - } - }); - - $this->assertTrue(EngineCoroutine::cancelById($coroutineId, throwException: true)); - $this->assertInstanceOf(Throwable::class, $captured); - - return $captured; - } - protected function getContainer(array $definitions = []): Container { $container = new Container; diff --git a/tests/Redis/RedisProxyTest.php b/tests/Redis/RedisProxyTest.php index bca2ae1ea..1ac8b5fcb 100644 --- a/tests/Redis/RedisProxyTest.php +++ b/tests/Redis/RedisProxyTest.php @@ -866,7 +866,7 @@ public function testCommandCancellationSkipsFailureEventAndStillReleasesTheConne public function testCommandNormalizesWrappedPhpRedisCancellation(): void { - $nativeFailure = new RedisException('command canceled'); + $nativeFailure = new RedisException('command canceled', previous: new CanceledException); $dispatcher = Double::for(Dispatcher::class)->strict(); $dispatcher->expects('hasListeners')->never(); $connection = $this->createMockRedisConnection( @@ -874,15 +874,17 @@ public function testCommandNormalizesWrappedPhpRedisCancellation(): void exception: $nativeFailure, eventDispatcher: $dispatcher, ); - $connection->nativeClientForTest()->expects('getLastError')->returns(null); $connection->expects('release'); - $redis = $this->createRedis($connection); + $exception = null; - $exception = $this->captureCancellationAtBoundary(function () use ($redis): void { - $redis->get('key'); - }); + try { + $this->createRedis($connection)->get('key'); + } catch (Throwable $caught) { + $exception = $caught; + } $this->assertInstanceOf(CanceledException::class, $exception); + $this->assertSame('Executing Redis command [get] was canceled.', $exception->getMessage()); $this->assertSame($nativeFailure, $exception->getPrevious()); } @@ -1180,21 +1182,24 @@ public function testCallbackTransactionPreservesOperationCancellationOverCleanup public function testCallbackTransactionNormalizesWrappedPhpRedisCancellation(): void { - $nativeFailure = new RedisException('exec canceled'); + $nativeFailure = new RedisException('exec canceled', previous: new CanceledException); $transaction = Double::for(PhpRedis::class)->strict(); $transaction->expects('exec')->throws($nativeFailure); $connection = $this->mockConnection(); $connection->nativeClientForTest()->expects('multi')->returns($transaction); $connection->expects('invalidate'); $connection->expects('release'); - $redis = $this->createRedis($connection); + $exception = null; - $exception = $this->captureCancellationAtBoundary(function () use ($redis): void { - $redis->transaction(static function (): void { + try { + $this->createRedis($connection)->transaction(static function (): void { }); - }); + } catch (Throwable $caught) { + $exception = $caught; + } $this->assertInstanceOf(CanceledException::class, $exception); + $this->assertSame('Executing the Redis transaction was canceled.', $exception->getMessage()); $this->assertSame($nativeFailure, $exception->getPrevious()); } @@ -1903,12 +1908,12 @@ public function testPinnedClusterDiscoveryFailureKeepsTheCallersConnection(): vo }); } - public function testClusterDiscoveryNormalizesWrappedCancellationAndStillReleases(): void + public function testClusterDiscoveryCancellationIsPreservedAndStillReleases(): void { - $nativeFailure = new RedisClusterException('Master discovery canceled.'); + $cancellation = new RedisClusterException('Master discovery canceled.', previous: new CanceledException); $connection = Double::for(PhpRedisClusterConnection::class)->strict(); $connection->expects('getConnection'); - $connection->expects('masters')->throws($nativeFailure); + $connection->expects('masters')->throws($cancellation); $connection->expects('release')->throws(new RuntimeException('Release failed.')); $pool = Double::for(RedisPool::class)->strict(); $pool->expects('getConfig')->returns([ @@ -1920,14 +1925,13 @@ public function testClusterDiscoveryNormalizesWrappedCancellationAndStillRelease $pool->expects('borrow')->returns($connection); $poolManager = Double::for(new PoolManager(new Container))->passthru(); $poolManager->expects('pool')->with('default')->returns($pool); - $redis = new RedisProxy($poolManager, 'default', $this->sentinelFactory()); - $exception = $this->captureCancellationAtBoundary(function () use ($redis): void { - $redis->subscriber(); - }); - - $this->assertInstanceOf(CanceledException::class, $exception); - $this->assertSame($nativeFailure, $exception->getPrevious()); + try { + (new RedisProxy($poolManager, 'default', $this->sentinelFactory()))->subscriber(); + $this->fail('Expected the discovery cancellation to escape.'); + } catch (Throwable $exception) { + $this->assertSame($cancellation, $exception); + } } #[TestWith([false], 'direct cancellation')] @@ -2239,31 +2243,6 @@ private function mockSubscriber( return $subscriber; } - /** - * Capture cancellation raised while the current coroutine is canceled. - */ - private function captureCancellationAtBoundary(callable $callback): Throwable - { - $blocker = new SwooleChannel(1); - $captured = null; - $coroutineId = Coroutine::create(function () use ($blocker, $callback, &$captured): void { - try { - $blocker->pop(); - } catch (CanceledException) { - try { - $callback(); - } catch (Throwable $exception) { - $captured = $exception; - } - } - }); - - $this->assertTrue(EngineCoroutine::cancelById($coroutineId, throwException: true)); - $this->assertInstanceOf(Throwable::class, $captured); - - return $captured; - } - /** * Create a release-counting Redis proxy with the given mock connections. */ From b0dbf6a06892c2f7666ce7a2bfbe1b3243cfb77f Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Thu, 19 Nov 2026 11:31:43 +0000 Subject: [PATCH 07/33] Require hypervel/guzzle 8.5.0.2 in hypervel/foundation 158e31981 raised root and hypervel/http to hypervel/guzzle ^8.5.0.2 but left hypervel/foundation at ^8.3, while PackageMetadataTest keeps foundation's direct framework dependencies on root's constraints. Foundation now matches root. Validation: PackageMetadataTest and the Foundation suite pass. --- src/foundation/composer.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/foundation/composer.json b/src/foundation/composer.json index f39cf4221..75204bdc0 100644 --- a/src/foundation/composer.json +++ b/src/foundation/composer.json @@ -51,7 +51,7 @@ "hypervel/engine": "^0.4", "hypervel/events": "^0.4", "hypervel/filesystem": "^0.4", - "hypervel/guzzle": "^8.3", + "hypervel/guzzle": "^8.5.0.2", "hypervel/http": "^0.4", "hypervel/http-server": "^0.4", "hypervel/log": "^0.4", From 80e5262686489af2959c4389a2a140a4f33780bc Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Thu, 19 Nov 2026 11:32:03 +0000 Subject: [PATCH 08/33] Add releaseUsingBackoff() to InteractsWithQueue A job could release itself only with an explicit delay, so honoring its own backoff schedule meant repeating the worker's backoff calculation. releaseUsingBackoff() releases the job with the delay for its current attempt, using the last delay once the attempts outnumber the schedule, and releases immediately without a backoff. Port laravel/framework#62435 (d48449f1eb6859a716f117a71cce7153efc8105c), with native types. Upstream has no docs; queues.md gains a paragraph under "Manually Releasing a Job". Validation: all four upstream InteractsWithQueueTest cases ported and passing; formatting and full static analysis pass. --- src/docs/queues.md | 6 ++ src/queue/src/InteractsWithQueue.php | 22 ++++++++ tests/Queue/InteractsWithQueueTest.php | 76 ++++++++++++++++++++++++++ 3 files changed, 104 insertions(+) diff --git a/src/docs/queues.md b/src/docs/queues.md index fb651e392..88e79906c 100644 --- a/src/docs/queues.md +++ b/src/docs/queues.md @@ -2319,6 +2319,12 @@ $this->release(10); $this->release(now()->plus(seconds: 10)); ``` +If the job defines a [backoff](#dealing-with-failed-jobs), the `releaseUsingBackoff` method releases it with the delay for the current attempt, just as the worker would after an exception. Once the attempts outnumber the configured delays, the last delay is used. A job without a backoff is released for immediate processing: + +```php +$this->releaseUsingBackoff(); +``` + After releasing a job, return from its handler. If a worker-processed job throws after release, the worker reports the exception but does not fail or release that attempt again. Exceptions thrown after release do not count toward `maxExceptions`. The next delivery checks the job's attempt limit as usual. diff --git a/src/queue/src/InteractsWithQueue.php b/src/queue/src/InteractsWithQueue.php index fc9bdf45c..9482b7304 100644 --- a/src/queue/src/InteractsWithQueue.php +++ b/src/queue/src/InteractsWithQueue.php @@ -66,6 +66,28 @@ public function release(DateInterval|DateTimeInterface|int $delay = 0): void } } + /** + * Release the job back into the queue using its backoff for the current attempt. + */ + public function releaseUsingBackoff(): void + { + if (! $this->job) { + return; + } + + $backoff = method_exists($this->job, 'backoff') ? $this->job->backoff() : null; + + if (is_null($backoff)) { + $this->release(); + + return; + } + + $backoff = explode(',', (string) $backoff); + + $this->release((int) ($backoff[$this->attempts() - 1] ?? end($backoff))); + } + /** * Indicate that queue interactions like fail, delete, and release should be faked. * diff --git a/tests/Queue/InteractsWithQueueTest.php b/tests/Queue/InteractsWithQueueTest.php index 815efcfb6..ac462d332 100644 --- a/tests/Queue/InteractsWithQueueTest.php +++ b/tests/Queue/InteractsWithQueueTest.php @@ -8,6 +8,7 @@ use Exception; use Hypervel\Contracts\Queue\Job; use Hypervel\Queue\InteractsWithQueue; +use Hypervel\Queue\Jobs\FakeJob; use Hypervel\Support\CarbonImmutable; use Hypervel\Tests\TestCase; use JMac\Testing\Double; @@ -78,4 +79,79 @@ public function testAssertsReleaseOfFakeJobReleasedDirectlyWithDateInterval(): v $job->assertReleased(60); } + + public function testReleaseUsingBackoffUsesTheDelayForTheCurrentAttempt(): void + { + $job = $this->jobWithBackoff('10,30,60', attempts: 2); + + $job->releaseUsingBackoff(); + + $this->assertSame(30, $job->job->releaseDelay); + } + + public function testReleaseUsingBackoffUsesTheLastDelayWhenAttemptsExceedTheSchedule(): void + { + $job = $this->jobWithBackoff('10,30,60', attempts: 5); + + $job->releaseUsingBackoff(); + + $this->assertSame(60, $job->job->releaseDelay); + } + + public function testReleaseUsingBackoffSupportsASingleValue(): void + { + $job = $this->jobWithBackoff(15, attempts: 3); + + $job->releaseUsingBackoff(); + + $this->assertSame(15, $job->job->releaseDelay); + } + + public function testReleaseUsingBackoffReleasesImmediatelyWithoutABackoff(): void + { + $job = $this->jobWithBackoff(null, attempts: 1); + + $job->releaseUsingBackoff(); + + $this->assertTrue($job->job->isReleased()); + $this->assertSame(0, $job->job->releaseDelay); + } + + /** + * Create a job whose fake queue job reports the given backoff and attempt count. + */ + protected function jobWithBackoff(int|string|null $backoff, int $attempts): object + { + $job = new class { + use InteractsWithQueue; + }; + + $job->job = new class($backoff, $attempts) extends FakeJob { + /** + * Create a fake job with the given backoff and attempt count. + */ + public function __construct(protected int|string|null $backoff, protected int $attemptCount) + { + parent::__construct(); + } + + /** + * Get the backoff for the job. + */ + public function backoff(): int|string|null + { + return $this->backoff; + } + + /** + * Get the number of times the job has been attempted. + */ + public function attempts(): int + { + return $this->attemptCount; + } + }; + + return $job; + } } From 6e9ebfb10dd8706b539b2efc5d4750f40575016b Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Thu, 19 Nov 2026 11:32:17 +0000 Subject: [PATCH 09/33] Add the RetryFor queue attribute and refresh retry deadlines on manual retry Jobs, queued listeners, mailables and notifications can declare a fixed retry window with #[RetryFor(...)] instead of a retryUntil() method. Dispatch turns the window into a deadline from when the job is queued; a retryUntil method or property takes precedence. Manual queue:retry now refreshes deadlines that would otherwise expire the retry before it runs. Fixing upstream defects found while porting: - A job's explicit retryUntil property keeps its absolute deadline instead of being replaced by the attribute window, as at dispatch. - Queued listeners stored only the dispatch-time deadline, so a retried listener failed immediately. The dispatcher now keeps the attribute's window on CallQueuedListener::$retryFor for refreshing, and a listener's retryUntil() method is called again with the stored event data, as dispatch does (owner-approved behavior change). Other stored deadlines, including hook-supplied ones, are kept. Port laravel/framework#62434 (9e1684e76a47df7a03220f30924332378f7c7c16), with CarbonImmutable for held dates. Upstream has no docs; queues.md "Time Based Attempts" documents the attribute and events.md points to it. Validation: QueueRetryForAttributeTest (all upstream cases) and QueueRetryCommandTest pass, including listeners dispatched through the event dispatcher and retried later, each fix failing without its branch; the Queue, Integration/Queue, Events, Mail and Notifications suites, formatting and full static analysis pass. --- src/docs/events.md | 4 +- src/docs/queues.md | 21 +- src/events/src/CallQueuedListener.php | 7 + src/events/src/Dispatcher.php | 8 +- src/mail/src/SendQueuedMailable.php | 6 +- .../src/SendQueuedNotifications.php | 6 +- src/queue/src/Attributes/RetryFor.php | 28 +++ src/queue/src/Console/RetryCommand.php | 35 +++- src/queue/src/Queue.php | 5 +- tests/Queue/QueueRetryCommandTest.php | 138 +++++++++++++ tests/Queue/QueueRetryForAttributeTest.php | 182 ++++++++++++++++++ 11 files changed, 428 insertions(+), 12 deletions(-) create mode 100644 src/queue/src/Attributes/RetryFor.php create mode 100644 tests/Queue/QueueRetryForAttributeTest.php diff --git a/src/docs/events.md b/src/docs/events.md index 72305426e..37a7e03a6 100644 --- a/src/docs/events.md +++ b/src/docs/events.md @@ -850,7 +850,9 @@ public function retryUntil(): DateTimeInterface } ``` -If both `retryUntil` and `tries` are defined, Hypervel gives precedence to the `retryUntil` method. +For a fixed window from when the listener is queued, you may use the [RetryFor attribute](/docs/{{version}}/queues#time-based-attempts) instead, such as `#[RetryFor(minutes: 5)]`. + +If both a retry window and `tries` are defined, Hypervel gives precedence to the retry window. #### Specifying Queued Listener Backoff diff --git a/src/docs/queues.md b/src/docs/queues.md index 88e79906c..382c18e8c 100644 --- a/src/docs/queues.md +++ b/src/docs/queues.md @@ -1921,10 +1921,27 @@ public function retryUntil(): DateTimeInterface } ``` -If both `retryUntil` and `tries` are defined, Hypervel gives precedence to the `retryUntil` method. +When the window is a fixed length of time from when the job is queued, you may use the `RetryFor` attribute instead. Its first argument is in seconds, and `minutes` and `hours` may be passed by name. A `retryUntil` method or property takes precedence over the attribute: + +```php + [!NOTE] -> You may also define a `Tries` attribute or `retryUntil` method on your [queued event listeners](/docs/{{version}}/events#queued-event-listeners) and [queued notifications](/docs/{{version}}/notifications#queueing-notifications). +> You may also define a `Tries` or `RetryFor` attribute or a `retryUntil` method on your [queued event listeners](/docs/{{version}}/events#queued-event-listeners), [queued notifications](/docs/{{version}}/notifications#queueing-notifications) and queued mailables. #### Max Exceptions diff --git a/src/events/src/CallQueuedListener.php b/src/events/src/CallQueuedListener.php index 6f5256034..245a2b5cc 100644 --- a/src/events/src/CallQueuedListener.php +++ b/src/events/src/CallQueuedListener.php @@ -58,6 +58,13 @@ class CallQueuedListener implements ShouldQueue */ public DateTimeInterface|int|null $retryUntil = null; + /** + * The retry window in seconds when the deadline comes from the listener's RetryFor attribute. + * + * Unlike Laravel, the window is kept so queue:retry can refresh the deadline. + */ + public ?int $retryFor = null; + /** * The number of seconds the job can run before timing out. */ diff --git a/src/events/src/Dispatcher.php b/src/events/src/Dispatcher.php index 2209fd83f..187386cd8 100755 --- a/src/events/src/Dispatcher.php +++ b/src/events/src/Dispatcher.php @@ -37,12 +37,14 @@ use Hypervel\Queue\Attributes\FailOnTimeout; use Hypervel\Queue\Attributes\MaxExceptions; use Hypervel\Queue\Attributes\Queue as QueueAttribute; +use Hypervel\Queue\Attributes\RetryFor; use Hypervel\Queue\Attributes\Timeout; use Hypervel\Queue\Attributes\Tries; use Hypervel\Queue\Attributes\UniqueFor; use Hypervel\Support\Arr; use Hypervel\Support\Attributes\BootOnly; use Hypervel\Support\Attributes\BootOrTestsOnly; +use Hypervel\Support\CarbonImmutable; use Hypervel\Support\Collection; use Hypervel\Support\Queue\Concerns\ResolvesQueueRoutes; use Hypervel\Support\Str; @@ -1068,7 +1070,11 @@ protected function propagateListenerOptions(mixed $listener, CallQueuedListener $job->backoff = method_exists($listener, 'backoff') ? $listener->backoff(...$data) : $this->getAttributeValue($listener, Backoff::class, 'backoff'); $job->maxExceptions = $this->getAttributeValue($listener, MaxExceptions::class, 'maxExceptions'); - $job->retryUntil = method_exists($listener, 'retryUntil') ? $listener->retryUntil(...$data) : null; + $job->retryUntil = match (true) { + method_exists($listener, 'retryUntil') => $listener->retryUntil(...$data), + ! is_null($job->retryFor = $this->getAttributeValue($listener, RetryFor::class)) => CarbonImmutable::now()->addSeconds($job->retryFor), + default => null, + }; $job->shouldBeEncrypted = $listener instanceof ShouldBeEncrypted; $job->timeout = $this->getAttributeValue($listener, Timeout::class, 'timeout'); $job->failOnTimeout = $this->getAttributeValue($listener, FailOnTimeout::class, 'failOnTimeout') ?? false; diff --git a/src/mail/src/SendQueuedMailable.php b/src/mail/src/SendQueuedMailable.php index 50e9a36b1..adbcf5ee6 100644 --- a/src/mail/src/SendQueuedMailable.php +++ b/src/mail/src/SendQueuedMailable.php @@ -19,9 +19,11 @@ use Hypervel\Queue\Attributes\MaxExceptions; use Hypervel\Queue\Attributes\Queue as QueueAttribute; use Hypervel\Queue\Attributes\ReadsQueueAttributes; +use Hypervel\Queue\Attributes\RetryFor; use Hypervel\Queue\Attributes\Timeout; use Hypervel\Queue\Attributes\Tries; use Hypervel\Queue\InteractsWithQueue; +use Hypervel\Support\CarbonImmutable; use Throwable; class SendQueuedMailable @@ -128,7 +130,9 @@ public function backoff(): mixed public function retryUntil(): ?DateTimeInterface { if (! method_exists($this->mailable, 'retryUntil') && ! isset($this->mailable->retryUntil)) { - return null; + $retryFor = $this->getAttributeValue($this->mailable, RetryFor::class); + + return is_null($retryFor) ? null : CarbonImmutable::now()->addSeconds($retryFor); } return $this->mailable->retryUntil ?? $this->mailable->retryUntil(); diff --git a/src/notifications/src/SendQueuedNotifications.php b/src/notifications/src/SendQueuedNotifications.php index 816082bc2..b82bd76bf 100644 --- a/src/notifications/src/SendQueuedNotifications.php +++ b/src/notifications/src/SendQueuedNotifications.php @@ -18,10 +18,12 @@ use Hypervel\Queue\Attributes\FailOnTimeout; use Hypervel\Queue\Attributes\MaxExceptions; use Hypervel\Queue\Attributes\ReadsQueueAttributes; +use Hypervel\Queue\Attributes\RetryFor; use Hypervel\Queue\Attributes\Timeout; use Hypervel\Queue\Attributes\Tries; use Hypervel\Queue\InteractsWithQueue; use Hypervel\Queue\SerializesModels; +use Hypervel\Support\CarbonImmutable; use Hypervel\Support\Collection; use Throwable; @@ -177,7 +179,9 @@ public function backoff(): mixed public function retryUntil(): ?DateTimeInterface { if (! method_exists($this->notification, 'retryUntil') && ! isset($this->notification->retryUntil)) { - return null; + $retryFor = $this->getAttributeValue($this->notification, RetryFor::class); + + return is_null($retryFor) ? null : CarbonImmutable::now()->addSeconds($retryFor); } return $this->notification->retryUntil ?? $this->notification->retryUntil(); diff --git a/src/queue/src/Attributes/RetryFor.php b/src/queue/src/Attributes/RetryFor.php new file mode 100644 index 000000000..69bd18f9d --- /dev/null +++ b/src/queue/src/Attributes/RetryFor.php @@ -0,0 +1,28 @@ +retryFor = $seconds + ($minutes * 60) + ($hours * 3600); + } +} diff --git a/src/queue/src/Console/RetryCommand.php b/src/queue/src/Console/RetryCommand.php index 6093888c4..f5f484cbf 100644 --- a/src/queue/src/Console/RetryCommand.php +++ b/src/queue/src/Console/RetryCommand.php @@ -12,13 +12,18 @@ use Hypervel\Contracts\Events\Dispatcher; use Hypervel\Contracts\Queue\Queue; use Hypervel\Database\Eloquent\ModelNotFoundException; +use Hypervel\Events\CallQueuedListener; +use Hypervel\Queue\Attributes\ReadsQueueAttributes; +use Hypervel\Queue\Attributes\RetryFor; use Hypervel\Queue\Events\JobRetryRequested; use Hypervel\Queue\Failed\FailedJobProviderInterface; use Hypervel\Queue\Jobs\JobName; use Hypervel\Queue\QueuePoolProxy; use Hypervel\Queue\SqsQueue; use Hypervel\Support\Enumerable; +use Hypervel\Support\InteractsWithTime; use Hypervel\Support\LazyCollection; +use ReflectionClass; use RuntimeException; use stdClass; use Symfony\Component\Console\Attribute\AsCommand; @@ -26,6 +31,9 @@ #[AsCommand(name: 'queue:retry')] class RetryCommand extends Command { + use InteractsWithTime; + use ReadsQueueAttributes; + /** * The console command signature. */ @@ -204,14 +212,31 @@ protected function refreshRetryUntil(string $payload): string return json_encode($payload, JSON_THROW_ON_ERROR); } - if (is_object($instance) && ! $instance instanceof __PHP_Incomplete_Class && method_exists($instance, 'retryUntil')) { - $retryUntil = $instance->retryUntil(); + if (! is_object($instance) || $instance instanceof __PHP_Incomplete_Class) { + return json_encode($payload, JSON_THROW_ON_ERROR); + } - $payload['retryUntil'] = $retryUntil instanceof DateTimeInterface - ? $retryUntil->getTimestamp() - : $retryUntil; + if (method_exists($instance, 'retryUntil')) { + $retryUntil = $instance->retryUntil(); + } elseif ($instance instanceof CallQueuedListener && method_exists($instance->class, 'retryUntil')) { + // Unlike Laravel, a queued listener's deadline is recalculated too, from its method as dispatch does. + $retryUntil = (new ReflectionClass($instance->class)) + ->newInstanceWithoutConstructor() + ->retryUntil(...array_values($instance->data)); + } elseif ($instance instanceof CallQueuedListener && ! is_null($instance->retryFor)) { + // Dispatch keeps the listener's RetryFor window on the job so it can be refreshed here. + $retryUntil = $this->availableAt($instance->retryFor); + } elseif (! isset($instance->retryUntil) && ! is_null($retryFor = $this->getAttributeValue($instance, RetryFor::class))) { + // Unlike Laravel, a retryUntil property keeps its absolute deadline, as it does at dispatch. + $retryUntil = $this->availableAt($retryFor); + } else { + return json_encode($payload, JSON_THROW_ON_ERROR); } + $payload['retryUntil'] = $retryUntil instanceof DateTimeInterface + ? $retryUntil->getTimestamp() + : $retryUntil; + return json_encode($payload, JSON_THROW_ON_ERROR); } diff --git a/src/queue/src/Queue.php b/src/queue/src/Queue.php index 8af92a251..a7c94d49c 100644 --- a/src/queue/src/Queue.php +++ b/src/queue/src/Queue.php @@ -26,6 +26,7 @@ use Hypervel\Queue\Attributes\FailOnTimeout; use Hypervel\Queue\Attributes\MaxExceptions; use Hypervel\Queue\Attributes\ReadsQueueAttributes; +use Hypervel\Queue\Attributes\RetryFor; use Hypervel\Queue\Attributes\Timeout; use Hypervel\Queue\Attributes\Tries; use Hypervel\Queue\Concerns\StagesOutboxJobs; @@ -353,7 +354,9 @@ public function getJobBackoff(mixed $job): mixed public function getJobExpiration(mixed $job): mixed { if (! method_exists($job, 'retryUntil') && ! isset($job->retryUntil)) { - return null; + $retryFor = $this->getAttributeValue($job, RetryFor::class); + + return is_null($retryFor) ? null : $this->availableAt($retryFor); } $expiration = $job->retryUntil ?? $job->retryUntil(); diff --git a/tests/Queue/QueueRetryCommandTest.php b/tests/Queue/QueueRetryCommandTest.php index 19b42bad6..c5a1de9e9 100644 --- a/tests/Queue/QueueRetryCommandTest.php +++ b/tests/Queue/QueueRetryCommandTest.php @@ -8,10 +8,15 @@ use Aws\Result; use Aws\Sqs\SqsClient; use Generator; +use Hypervel\Container\Container; use Hypervel\Contracts\Events\Dispatcher; use Hypervel\Contracts\Queue\Queue as QueueContract; +use Hypervel\Contracts\Queue\ShouldQueue; use Hypervel\Database\Eloquent\ModelNotFoundException; +use Hypervel\Events\CallQueuedListener; +use Hypervel\Events\Dispatcher as EventDispatcher; use Hypervel\Foundation\Application; +use Hypervel\Queue\Attributes\RetryFor; use Hypervel\Queue\Console\RetryCommand; use Hypervel\Queue\Events\JobRetryRequested; use Hypervel\Queue\Failed\FailedJobProviderInterface; @@ -19,8 +24,10 @@ use Hypervel\Queue\QueueManager; use Hypervel\Queue\SqsQueue; use Hypervel\Queue\SyncQueue; +use Hypervel\Support\CarbonImmutable; use Hypervel\Support\Collection; use Hypervel\Support\LazyCollection; +use Hypervel\Support\Testing\Fakes\QueueFake; use Hypervel\Tests\TestCase; use JMac\Testing\Double; use JMac\Testing\Integrations\PHPUnit\VerifiesDoubles; @@ -205,6 +212,88 @@ public function testRefreshesTheRetryUntilTimestampWhenTheJobDefinesRetryUntil(b $this->runRetryCommand(['id' => ['1']], $failer, ['database' => $queue]); } + public function testRefreshesTheRetryUntilTimestampWhenTheJobDefinesRetryForAttribute(): void + { + CarbonImmutable::setTestNow('2026-01-01 00:00:00'); + + $failer = Double::for(FailedJobProviderInterface::class)->strict(); + $queue = Double::for(QueueContract::class)->strict(); + + $job = $this->failedJob( + id: '1', + connection: 'database', + queue: 'default', + payload: ['retryUntil' => 0], + job: new QueueRetryCommandTestJobWithRetryForAttribute + ); + + $failer->expects('find')->with('1')->returns($job); + $queue->expects('pushRaw')->with(Argument::satisfies(function (string $payload): bool { + return json_decode($payload, true)['retryUntil'] === CarbonImmutable::now()->addSeconds(90)->getTimestamp(); + }), 'default', []); + $failer->expects('forget')->with('1'); + + $this->runRetryCommand(['id' => ['1']], $failer, ['database' => $queue]); + } + + public function testKeepsTheRetryUntilPropertyOfAJobWithTheRetryForAttribute(): void + { + $failer = Double::for(FailedJobProviderInterface::class)->strict(); + $queue = Double::for(QueueContract::class)->strict(); + + $job = $this->failedJob( + id: '1', + connection: 'database', + queue: 'default', + payload: ['retryUntil' => 1234567890], + job: new QueueRetryCommandTestJobWithRetryForAttributeAndRetryUntilProperty + ); + + $failer->expects('find')->with('1')->returns($job); + $queue->expects('pushRaw')->with(Argument::satisfies(function (string $payload): bool { + return json_decode($payload, true)['retryUntil'] === 1234567890; + }), 'default', []); + $failer->expects('forget')->with('1'); + + $this->runRetryCommand(['id' => ['1']], $failer, ['database' => $queue]); + } + + #[TestWith([QueueRetryCommandTestListenerWithRetryForAttribute::class, 1767312090])] + #[TestWith([QueueRetryCommandTestListenerWithRelativeRetryUntil::class, 1767312600])] + #[TestWith([QueueRetryCommandTestListenerWithRetryUntil::class, 111])] + #[TestWith([QueueRetryCommandTestListener::class, 111])] + public function testRecalculatesTheRetryUntilTimestampOfAQueuedListener(string $listener, int $retryUntil): void + { + CarbonImmutable::setTestNow('2026-01-01 00:00:00'); + + $listenerQueue = new QueueFake(new Container); + $events = new EventDispatcher; + $events->setQueueResolver(fn (): QueueFake => $listenerQueue); + $events->listen('some.event', $listener . '@handle'); + $events->dispatch('some.event', [111]); + + CarbonImmutable::setTestNow('2026-01-02 00:00:00'); + + $failer = Double::for(FailedJobProviderInterface::class)->strict(); + $queue = Double::for(QueueContract::class)->strict(); + + $job = $this->failedJob( + id: '1', + connection: 'database', + queue: 'default', + payload: ['retryUntil' => 111], + job: $listenerQueue->pushed(CallQueuedListener::class)->sole() + ); + + $failer->expects('find')->with('1')->returns($job); + $queue->expects('pushRaw')->with(Argument::satisfies(function (string $payload) use ($retryUntil): bool { + return json_decode($payload, true)['retryUntil'] === $retryUntil; + }), 'default', []); + $failer->expects('forget')->with('1'); + + $this->runRetryCommand(['id' => ['1']], $failer, ['database' => $queue]); + } + public function testPassesQueueableOptionsToTheQueueWhenRetryingASingleJob(): void { $failer = Double::for(FailedJobProviderInterface::class)->strict(); @@ -896,6 +985,55 @@ public function retryUntil(): int } } +#[RetryFor(90)] +class QueueRetryCommandTestJobWithRetryForAttribute +{ +} + +#[RetryFor(90)] +class QueueRetryCommandTestJobWithRetryForAttributeAndRetryUntilProperty +{ + public int $retryUntil = 1234567890; +} + +class QueueRetryCommandTestListener implements ShouldQueue +{ + /** + * Handle the event. + */ + public function handle(): void + { + } +} + +#[RetryFor(90)] +class QueueRetryCommandTestListenerWithRetryForAttribute extends QueueRetryCommandTestListener +{ +} + +#[RetryFor(90)] +class QueueRetryCommandTestListenerWithRetryUntil extends QueueRetryCommandTestListener +{ + /** + * Return the retry deadline carried by the event. + */ + public function retryUntil(int $retryUntil): int + { + return $retryUntil; + } +} + +class QueueRetryCommandTestListenerWithRelativeRetryUntil extends QueueRetryCommandTestListener +{ + /** + * Return a retry deadline relative to now. + */ + public function retryUntil(): CarbonImmutable + { + return CarbonImmutable::now()->addMinutes(10); + } +} + class QueueRetryCommandTestJobWithMissingModel { /** diff --git a/tests/Queue/QueueRetryForAttributeTest.php b/tests/Queue/QueueRetryForAttributeTest.php new file mode 100644 index 000000000..44fc49c07 --- /dev/null +++ b/tests/Queue/QueueRetryForAttributeTest.php @@ -0,0 +1,182 @@ +assertSame( + CarbonImmutable::now()->addSeconds(90)->getTimestamp(), + (new NullQueue)->getJobExpiration(new RetryForAttributeJob) + ); + } + + public function testAttributeAcceptsMinutesAndHours(): void + { + $this->assertSame(90, (new RetryFor(90))->retryFor); + $this->assertSame(90, (new RetryFor(seconds: 90))->retryFor); + $this->assertSame(600, (new RetryFor(minutes: 10))->retryFor); + $this->assertSame(36000, (new RetryFor(hours: 10))->retryFor); + $this->assertSame(5430, (new RetryFor(seconds: 30, minutes: 30, hours: 1))->retryFor); + } + + public function testJobExpirationIsCalculatedFromNamedUnits(): void + { + $this->assertSame( + CarbonImmutable::now()->addMinutes(10)->getTimestamp(), + (new NullQueue)->getJobExpiration(new RetryForAttributeJobUsingMinutes) + ); + + $this->assertSame( + CarbonImmutable::now()->addHours(4)->getTimestamp(), + (new NullQueue)->getJobExpiration(new RetryForAttributeJobUsingHours) + ); + } + + public function testJobExpirationIsInheritedFromAParentClassAttribute(): void + { + $this->assertSame( + CarbonImmutable::now()->addSeconds(90)->getTimestamp(), + (new NullQueue)->getJobExpiration(new RetryForAttributeChildJob) + ); + } + + public function testRetryUntilMethodTakesPrecedenceOverTheAttribute(): void + { + $this->assertSame( + CarbonImmutable::now()->addSeconds(5)->getTimestamp(), + (new NullQueue)->getJobExpiration(new RetryForAttributeJobWithRetryUntilMethod) + ); + } + + public function testRetryUntilPropertyTakesPrecedenceOverTheAttribute(): void + { + $job = new RetryForAttributeJob; + $job->retryUntil = 1234567890; + + $this->assertSame(1234567890, (new NullQueue)->getJobExpiration($job)); + } + + public function testJobExpirationIsNullWithoutTheAttribute(): void + { + $this->assertNull((new NullQueue)->getJobExpiration(new RetryForAttributeJobWithoutAttribute)); + } + + public function testQueuedMailableUsesTheAttribute(): void + { + $job = new SendQueuedMailable(new RetryForAttributeMailable); + + $this->assertEquals(CarbonImmutable::now()->addSeconds(90), $job->retryUntil()); + $this->assertSame( + CarbonImmutable::now()->addSeconds(90)->getTimestamp(), + (new NullQueue)->getJobExpiration($job) + ); + } + + public function testQueuedNotificationUsesTheAttribute(): void + { + $job = new SendQueuedNotifications('notifiables', new RetryForAttributeNotification); + + $this->assertEquals(CarbonImmutable::now()->addSeconds(90), $job->retryUntil()); + $this->assertSame( + CarbonImmutable::now()->addSeconds(90)->getTimestamp(), + (new NullQueue)->getJobExpiration($job) + ); + } + + public function testQueuedListenerUsesTheAttribute(): void + { + $dispatcher = new Dispatcher; + $queue = new QueueFake(new Container); + + $dispatcher->setQueueResolver(fn () => $queue); + $dispatcher->listen('some.event', RetryForAttributeListener::class . '@handle'); + $dispatcher->dispatch('some.event', ['foo']); + + $queue->assertPushed(CallQueuedListener::class, function (CallQueuedListener $job): bool { + return $job->retryUntil == CarbonImmutable::now()->addSeconds(90); + }); + } +} + +#[RetryFor(90)] +class RetryForAttributeJob +{ + public ?int $retryUntil = null; +} + +#[RetryFor(minutes: 10)] +class RetryForAttributeJobUsingMinutes +{ +} + +#[RetryFor(hours: 4)] +class RetryForAttributeJobUsingHours +{ +} + +class RetryForAttributeChildJob extends RetryForAttributeJob +{ +} + +#[RetryFor(90)] +class RetryForAttributeJobWithRetryUntilMethod +{ + /** + * Get the time at which the job should stop retrying. + */ + public function retryUntil(): DateTimeInterface + { + return CarbonImmutable::now()->addSeconds(5); + } +} + +class RetryForAttributeJobWithoutAttribute +{ +} + +#[RetryFor(90)] +class RetryForAttributeMailable extends Mailable +{ +} + +#[RetryFor(90)] +class RetryForAttributeNotification extends Notification +{ +} + +#[RetryFor(90)] +class RetryForAttributeListener implements ShouldQueue +{ + /** + * Handle the event. + */ + public function handle(): void + { + } +} From 490d292cd0efcb345dbc3ce47032a75368c96eea Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Thu, 19 Nov 2026 11:32:22 +0000 Subject: [PATCH 10/33] Cover cursor pagination of unions ordered by aliased expressions Hypervel maps union paging columns by position and rejects computed union paging columns with fromSub() guidance, so the patched union branch does not exist here. The upstream regression is ported: it asserts the documented rejection of the direct union, then runs upstream's data and assertions in both directions through fromSub(). Port laravel/framework#62433 (21d4d8a49dbf3fbbc660123f0ae2052e96a4ad49); test only. Validation: EloquentCursorPaginateTest passes on SQLite, MySQL, MariaDB and PostgreSQL. --- .../Database/EloquentCursorPaginateTest.php | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/tests/Integration/Database/EloquentCursorPaginateTest.php b/tests/Integration/Database/EloquentCursorPaginateTest.php index 00442122d..8820ebae2 100644 --- a/tests/Integration/Database/EloquentCursorPaginateTest.php +++ b/tests/Integration/Database/EloquentCursorPaginateTest.php @@ -775,6 +775,39 @@ public function testPaginationWithMultipleAliasesAndMultipleOrders(): void $this->assertEquals(2, current($result->items())->rank); } + public function testPaginationWithUnionAndAliasedExpressions(): void + { + TestUser::fillAndInsert([['name' => 'alpha'], ['name' => 'bravo']]); + TestPost::fillAndInsert([['title' => 'bravo'], ['title' => 'charlie']]); + + $union = fn (): QueryBuilder => TestPost::select('test_posts.id')->selectRaw('UPPER(test_posts.title) as label')->toBase() + ->unionAll(TestUser::select('test_users.id')->selectRaw('UPPER(test_users.name) as label')->toBase()); + + // Hypervel rejects computed union paging columns rather than guessing a raw selection's width. + try { + $union()->orderBy('label')->orderBy('id')->cursorPaginate(2, ['*'], 'cursor', new Cursor(['label' => 'BRAVO', 'id' => 1])); + $this->fail('The computed union paging column must be rejected.'); + } catch (InvalidArgumentException $exception) { + $this->assertStringContainsString('fromSub()', $exception->getMessage()); + } + + $query = fn (string $direction): QueryBuilder => DB::query()->fromSub($union(), 'entries') + ->orderBy('label', $direction) + ->orderBy('id', $direction); + + $first = $query('asc')->cursorPaginate(2); + $second = $query('asc')->cursorPaginate(2, ['*'], 'cursor', $first->nextCursor()); + + $this->assertSame(['BRAVO', 'CHARLIE'], collect($second->items())->pluck('label')->all()); + $this->assertEquals([2, 2], collect($second->items())->pluck('id')->all()); + + $first = $query('desc')->cursorPaginate(2); + $second = $query('desc')->cursorPaginate(2, ['*'], 'cursor', $first->nextCursor()); + + $this->assertSame(['BRAVO', 'ALPHA'], collect($second->items())->pluck('label')->all()); + $this->assertEquals([1, 1], collect($second->items())->pluck('id')->all()); + } + public function testPaginationWithAliasedOrderBy(): void { TestUser::fillAndInsert([[], [], [], [], [], []]); From 724c4de46280361730e9c12f006a1daeaf22c347 Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Thu, 19 Nov 2026 11:32:28 +0000 Subject: [PATCH 11/33] Give an unaliased subquery in from() a default alias from() with a subquery and no alias passed null to fromSub()'s string alias, throwing TypeError. Laravel now passes an empty alias, but PostgreSQL rejects the resulting as "" ("zero-length delimited identifier") and an empty alias would qualify columns as ".column". An omitted subquery alias now defaults to hypervel_table; explicit aliases are unchanged. Port laravel/framework#62430 (507be989d71068f0ca05f7cb2b426c14a27e67c8), adapting its expected SQL to the default alias. Validation: testFromSubWithoutAlias passes; QueryBuilderTest's unaliased DB::table(Closure) runs on SQLite, MySQL, MariaDB and PostgreSQL and fails on PostgreSQL with the empty alias; formatting and full static analysis pass. --- src/database/src/Query/Builder.php | 3 ++- tests/Database/DatabaseQueryBuilderTest.php | 26 +++++++++++++++++++ .../Integration/Database/QueryBuilderTest.php | 7 +++++ 3 files changed, 35 insertions(+), 1 deletion(-) diff --git a/src/database/src/Query/Builder.php b/src/database/src/Query/Builder.php index e6327c2d4..2c6a926ea 100644 --- a/src/database/src/Query/Builder.php +++ b/src/database/src/Query/Builder.php @@ -572,7 +572,8 @@ public function distinct(): static public function from(Closure|self|EloquentBuilder|Relation|ExpressionContract|string $table, ?string $as = null): static { if ($this->isQueryable($table)) { - return $this->fromSub($table, $as); + // Laravel uses an empty alias here, which PostgreSQL rejects; every supported database accepts a name. + return $this->fromSub($table, $as ?? 'hypervel_table'); } if ($table instanceof ExpressionContract && $as !== null && $as !== '') { diff --git a/tests/Database/DatabaseQueryBuilderTest.php b/tests/Database/DatabaseQueryBuilderTest.php index 0c60b0e86..55d9df282 100755 --- a/tests/Database/DatabaseQueryBuilderTest.php +++ b/tests/Database/DatabaseQueryBuilderTest.php @@ -9,6 +9,7 @@ use DateInterval; use DatePeriod; use DateTime; +use ErrorException; use Hypervel\Contracts\Database\Query\ConditionExpression; use Hypervel\Contracts\Database\Query\Expression as ExpressionContract; use Hypervel\Database\Connection; @@ -8872,6 +8873,31 @@ public function testFrom(): void $this->assertSame('select * from (select * from "users") as "u"', $builder->toSql()); } + public function testFromSubWithoutAlias(): void + { + $errorReporting = error_reporting(E_ALL); + + set_error_handler(function (int $level, string $message, string $file = '', int $line = 0): never { + throw new ErrorException($message, 0, $level, $file, $line); + }); + + try { + $builder = $this->getBuilder(); + $builder->selectRaw('1')->from(function ($query) { + $query->selectRaw('1 as a'); + }); + $this->assertSame('select 1 from (select 1 as a) as "hypervel_table"', $builder->toSql()); + + $builder = $this->getMySqlBuilder(); + $builder->selectRaw('1')->from($this->getMySqlBuilder()->selectRaw('1 as a')); + $this->assertSame('select 1 from (select 1 as a) as `hypervel_table`', $builder->toSql()); + } finally { + restore_error_handler(); + + error_reporting($errorReporting); + } + } + public function testFromSub(): void { $builder = $this->getBuilder(); diff --git a/tests/Integration/Database/QueryBuilderTest.php b/tests/Integration/Database/QueryBuilderTest.php index 5bd4e4d57..d73e157f4 100644 --- a/tests/Integration/Database/QueryBuilderTest.php +++ b/tests/Integration/Database/QueryBuilderTest.php @@ -375,6 +375,13 @@ public function testFromWithSubQuery(): void $query->selectRaw("'Fake Post' as title"); }, 'posts')->first()->title ); + + $this->assertSame( + 'Fake Post', + DB::table(function ($query) { + $query->selectRaw("'Fake Post' as title"); + })->first()->title + ); } public function testWhereValueSubQuery(): void From 5dd33452bb7b6ced3922d6337ccf6d7c0e4900fd Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Thu, 19 Nov 2026 11:32:56 +0000 Subject: [PATCH 12/33] Add RawTemplate for inline Blade components A component's render() string was resolved as a view name when a matching view existed and compiled as Blade otherwise, so the same string could mean either. Returning a RawTemplate, directly or from a render closure, always compiles the string as an inline template and never looks it up as a view. Component caches raw-template view names separately from view-name lookups, cleared with its other caches. make:component --inline generates a RawTemplate-based class from a publishable stub. Fixing an inherited defect (owner-approved recompilation cost): Blade::render(..., deleteCachedView: true) unlinked a content-addressed source shared with components and overlapping renders of the same template. Each deletable render now writes its own source and builds the view through Factory::makeFromTemporaryFile(), then removes its source and compiled file; factories without temporary views keep the named render. Port laravel/framework#62419 (94f01e85452dd9ea24853689912f026fc78ff878). blade.md ports the documentation from laravel/docs f501c677 (RawTemplate example and warning, attributes and slots under inline views) and notes the deleteCachedView cost. Validation: all upstream ComponentTest, BladeTest and ComponentMakeCommandTest cases pass; the shared-source regression fails before the fix and passes after; View, Blade compiler and generator suites, formatting and full static analysis pass. --- src/docs/blade.md | 90 +++++------ .../src/Console/ComponentMakeCommand.php | 6 +- .../src/Console/StubPublishCommand.php | 1 + .../Console/stubs/view-component.inline.stub | 27 ++++ src/view/src/Compilers/BladeCompiler.php | 40 ++++- src/view/src/Component.php | 25 +++- src/view/src/Factory.php | 19 +++ src/view/src/RawTemplate.php | 21 +++ .../Generators/ComponentMakeCommandTest.php | 9 +- tests/Integration/View/BladeTest.php | 98 ++++++++++++ tests/View/ComponentTest.php | 141 ++++++++++++++++++ 11 files changed, 425 insertions(+), 52 deletions(-) create mode 100644 src/foundation/src/Console/stubs/view-component.inline.stub create mode 100644 src/view/src/RawTemplate.php diff --git a/src/docs/blade.md b/src/docs/blade.md index a0032d07b..ad6f622ce 100644 --- a/src/docs/blade.md +++ b/src/docs/blade.md @@ -989,44 +989,6 @@ You may execute this method from your component template by invoking the variabl ``` - -#### Accessing Attributes and Slots Within Component Classes - -Blade components also allow you to access the component name, attributes, and slot inside the class's render method. However, in order to access this data, you should return a closure from your component's `render` method: - -```php -use Closure; - -/** - * Get the view / contents that represent the component. - */ -public function render(): Closure -{ - return function () { - return '
Components content
'; - }; -} -``` - -The closure returned by your component's `render` method may also receive a `$data` array as its only argument. This array will contain several elements that provide information about the component: - -```php -return function (array $data) { - // $data['componentName']; - // $data['attributes']; - // $data['slot']; - - return '
Components content
'; -}; -``` - -> [!WARNING] -> The elements in the `$data` array should never be directly embedded into the Blade string returned by your `render` method, as doing so could allow remote code execution via malicious attribute content. - -The `componentName` is equal to the name used in the HTML tag after the `x-` prefix. So ``'s `componentName` will be `alert`. The `attributes` element will contain all of the attributes that were present on the HTML tag. The `slot` element is a `Hypervel\View\ComponentSlot` instance with the contents of the component's slot. - -The closure should return a string. If the returned string corresponds to an existing view, that view will be rendered; otherwise, the returned string will be evaluated as an inline Blade view. - #### Additional Dependencies @@ -1395,22 +1357,27 @@ To interact with slot attributes, you may access the `attributes` property of th ### Inline Component Views -For very small components, it may feel cumbersome to manage both the component class and the component's view template. For this reason, you may return the component's markup directly from the `render` method: +For very small components, it may feel cumbersome to manage both the component class and the component's view template. For this reason, you may return the component's markup directly from the `render` method by wrapping it in a `Hypervel\View\RawTemplate` instance: ```php +use Hypervel\View\RawTemplate; + /** * Get the view / contents that represent the component. */ -public function render(): string +public function render(): RawTemplate { - return <<<'blade' + return new RawTemplate(<<<'blade'
{{ $slot }}
- blade; + blade); } ``` +> [!WARNING] +> A `RawTemplate` is compiled and executed as Blade, so injected content could allow remote code execution. Never build the template from untrusted data. Instead, pass the data to the component and display it using Blade's escaped `{{ }}` syntax. + #### Generating Inline View Components @@ -1420,6 +1387,41 @@ To create a component that renders an inline view, you may use the `inline` opti php artisan make:component Alert --inline ``` + +#### Accessing Attributes and Slots in Inline Views + +If you need the component name, attributes, or slot inside the class's `render` method, you may return a closure instead. The closure receives a `$data` array as its only argument: + +```php +use Closure; +use Hypervel\View\RawTemplate; + +/** + * Get the view / contents that represent the component. + */ +public function render(): Closure +{ + return function (array $data) { + // $data['componentName']; + // $data['attributes']; + // $data['slot']; + + if ($data['slot']->isEmpty()) { + return new RawTemplate('
No content provided.
'); + } + + return new RawTemplate('
{{ $slot }}
'); + }; +} +``` + +The `componentName` is equal to the name used in the HTML tag after the `x-` prefix. So ``'s `componentName` will be `alert`. The `attributes` element will contain all of the attributes that were present on the HTML tag. The `slot` element is a `Hypervel\View\ComponentSlot` instance with the contents of the component's slot. + +The closure should return either the name of a view or a `RawTemplate` instance. + +> [!WARNING] +> The elements in the `$data` array should be treated as untrusted, since they contain the attributes and slot content passed to the component. Never embed them into the template returned by your closure, as doing so could allow remote code execution. + ### Dynamic Components @@ -1941,8 +1943,10 @@ return Blade::render( ); ``` +For templates you render repeatedly, leave `deleteCachedView` off. Enabling it makes repeated renders slower because Blade recompiles the template and writes a new file each time, even when only the data changes. + > [!WARNING] -> Keep inline Blade templates stable and pass changing values as view data or slots. Hypervel caches and stores each distinct template string separately for reuse, so continually generating unique Blade source grows worker memory and stored view artifacts. +> The template string passed to the `render` method is compiled and executed as Blade, so injected content could allow remote code execution. Never build the template from untrusted data. Instead, pass the data using the method's second argument and display it using Blade's escaped `{{ }}` syntax. Keeping the template stable also matters for performance: by default, Hypervel caches and stores each distinct template string separately for reuse, so continually generating unique Blade source grows worker memory and stored view artifacts. ## Rendering Blade Fragments diff --git a/src/foundation/src/Console/ComponentMakeCommand.php b/src/foundation/src/Console/ComponentMakeCommand.php index d7dde9b1f..7d65a27e6 100644 --- a/src/foundation/src/Console/ComponentMakeCommand.php +++ b/src/foundation/src/Console/ComponentMakeCommand.php @@ -95,7 +95,7 @@ protected function buildClass(string $name): string if ($this->option('inline')) { return str_replace( ['DummyView', '{{ view }}'], - "<<<'blade'\n
\n \n
\nblade", + "<<<'blade'\n
\n {{-- " . Inspiring::quotes()->random() . " --}}\n
\n blade", parent::buildClass($name) ); } @@ -135,7 +135,9 @@ protected function getView(): string */ protected function getStub(): string { - return $this->resolveStubPath('/stubs/view-component.stub'); + return $this->option('inline') + ? $this->resolveStubPath('/stubs/view-component.inline.stub') + : $this->resolveStubPath('/stubs/view-component.stub'); } /** diff --git a/src/foundation/src/Console/StubPublishCommand.php b/src/foundation/src/Console/StubPublishCommand.php index 84fb5dce1..8a8c164b3 100644 --- a/src/foundation/src/Console/StubPublishCommand.php +++ b/src/foundation/src/Console/StubPublishCommand.php @@ -65,6 +65,7 @@ public function handle(): void __DIR__ . '/stubs/test.stub' => 'test.stub', __DIR__ . '/stubs/test.unit.stub' => 'test.unit.stub', __DIR__ . '/stubs/trait.stub' => 'trait.stub', + __DIR__ . '/stubs/view-component.inline.stub' => 'view-component.inline.stub', __DIR__ . '/stubs/view-component.stub' => 'view-component.stub', __DIR__ . '/../../../database/src/Console/Factories/stubs/factory.stub' => 'factory.stub', __DIR__ . '/../../../database/src/Console/Seeds/stubs/seeder.stub' => 'seeder.stub', diff --git a/src/foundation/src/Console/stubs/view-component.inline.stub b/src/foundation/src/Console/stubs/view-component.inline.stub new file mode 100644 index 000000000..34a875152 --- /dev/null +++ b/src/foundation/src/Console/stubs/view-component.inline.stub @@ -0,0 +1,27 @@ +make(ViewFactory::class); + + // Each deletable render owns its source file, so deleting it cannot break another render of the same + // template. Factory implementations without temporary views keep the named render below. + if ($deleteCachedView && $factory instanceof Factory) { + $hash = hash('xxh128', $string); + $directory = $container->make('config')->string('view.compiled'); + $path = $directory . '/' . $hash . '-' . bin2hex(random_bytes(8)) . '.blade.php'; + $files = $container->make(Filesystem::class); + $view = null; + + $files->ensureDirectoryExists($directory); + + try { + $files->put($path, $string); + $view = $factory->makeFromTemporaryFile('__components::' . $hash, $path, $data); + + return $view->render(); + } finally { + @unlink($path); + + if ($view instanceof View && ($engine = $view->getEngine()) instanceof CompilerEngine) { + @unlink($engine->getCompiler()->getCompiledPath($path)); + } + } + } + $component = new class($string) extends Component { /** * Create a new inline Blade component instance. @@ -352,9 +384,7 @@ public function resolveView(): string } }; - $view = Container::getInstance() - ->make(ViewFactory::class) - ->make($component->resolveView(), $data); + $view = $factory->make($component->resolveView(), $data); return tap($view->render(), function () use ($component, $string, $view, $deleteCachedView) { if ($deleteCachedView) { @@ -375,7 +405,7 @@ public static function renderComponent(Component $component): string $view = value($component->resolveView(), $data); - if ($view instanceof View) { + if ($view instanceof ViewContract) { return $view->with($data)->render(); } if ($view instanceof Htmlable) { diff --git a/src/view/src/Component.php b/src/view/src/Component.php index fc00a4d3e..061642814 100644 --- a/src/view/src/Component.php +++ b/src/view/src/Component.php @@ -78,10 +78,17 @@ abstract class Component */ protected static array $ignoredParameterNames = []; + /** + * The cache of blade view names for raw templates, keyed by template. + * + * @var array + */ + protected static array $rawTemplateViewCache = []; + /** * Get the view / view contents that represent the component. */ - abstract public function render(): ViewContract|Htmlable|Closure|string; + abstract public function render(): ViewContract|Htmlable|RawTemplate|Closure|string; /** * Resolve the component instance with the given data. @@ -143,6 +150,10 @@ public function resolveView(): ViewContract|Htmlable|Closure|string return $view; } + if ($view instanceof RawTemplate) { + return $this->createBladeViewFromRawTemplate($view); + } + return $this->extractBladeViewFromString($view); }; @@ -170,6 +181,17 @@ protected function extractBladeViewFromString(string $contents): string return static::$bladeViewCache[$key] = $this->createBladeViewFromString($this->factory(), $contents); } + /** + * Create a Blade view from the given raw template. + */ + protected function createBladeViewFromRawTemplate(RawTemplate $template): string + { + return static::$rawTemplateViewCache[static::bladeViewCacheKey($template->template)] ??= $this->createBladeViewFromString( + $this->factory(), + $template->template + ); + } + /** * Get the cache key for the given Blade view contents. */ @@ -406,6 +428,7 @@ public static function ignoredParameterNames(): array public static function flushCache(): void { static::$bladeViewCache = []; + static::$rawTemplateViewCache = []; static::$constructorParametersCache = []; static::$methodCache = []; static::$propertyCache = []; diff --git a/src/view/src/Factory.php b/src/view/src/Factory.php index 14292adcb..827839c9c 100755 --- a/src/view/src/Factory.php +++ b/src/view/src/Factory.php @@ -130,6 +130,25 @@ public function file(string $path, Arrayable|array $data = [], array $mergeData }); } + /** + * Create a view for a source file that will be deleted after rendering. + * + * The view name must already be normalized. The path is unique to one render, + * so it is not kept in the engine cache. + * + * @internal + */ + public function makeFromTemporaryFile(string $view, string $path, Arrayable|array $data = []): ViewContract + { + try { + return tap($this->viewInstance($view, $path, $this->parseData($data)), function ($view) { + $this->callCreator($view); + }); + } finally { + unset($this->pathEngineCache[$path]); + } + } + /** * Get the evaluated view contents for the given view. */ diff --git a/src/view/src/RawTemplate.php b/src/view/src/RawTemplate.php new file mode 100644 index 000000000..e9a6ee3e0 --- /dev/null +++ b/src/view/src/RawTemplate.php @@ -0,0 +1,21 @@ +assertFileContains([ 'namespace App\View\Components;', 'use Hypervel\View\Component;', + 'use Hypervel\View\RawTemplate;', 'class Foo extends Component', - "return <<<'blade'", + 'public function render(): RawTemplate', + "return new RawTemplate(<<<'blade'", + '{{--', + ], 'app/View/Components/Foo.php'); + + $this->assertFileNotContains([ + '