Merge 0.4 framework performance improvements into feature/ai

Bring in the shared HTTP handler and idle database session release improvements, process cleanup corrections, regression coverage and recorded benchmark results from PR #669.

Preserve the AI destination-policy middleware and existing uncommitted AI work. The receive-buffer source and regression test already matched the incoming framework versions. Verify the merged tree with formatting, static analysis and focused AI streaming, Bedrock HTTP and remote-file tests.

Author: binaryfire

AGENTS.md

@@ -386,6 +386,7 @@ Decide where state lives before writing code:
 
 Classes that use static caching need a `flushState()` method for test cleanup — see "Static state and test cleanup" under Writing Tests.
 
+- **Release idle pooled connections before unrelated long waits** — Holding connections while waiting for external services or child coroutines can exhaust pools and limit concurrency. Release them at the appropriate shared boundary, preserving active operations and session ownership; consider reacquisition costs rather than adding release calls indiscriminately. For database sessions, reuse `ConnectionResolver::releaseIdleConnections()`, which preserves transactions and explicit pins. See `Mailer::sendSymfonyMessage()` and `ConcurrentImportRunner::wait()` for examples.
 - **Treat coroutine cancellation separately from errors** — Code that owns coroutine cancellation must pass `CanceledException` through unchanged and clean up the children or resources it owns. Add this only where cancellation can actually happen and mishandling it causes a real bug—not to every `catch (Throwable)`.
 - **Contain cancellation in direct engine coroutines** — A callback passed directly to `Engine\Coroutine` must catch cancellation after cleanup so it cannot terminate the worker. The higher-level `Coroutine` class already provides this protection.
 

docs/todo.md

@@ -48,7 +48,7 @@
 ## HTTP Client
 
 - Before the Hypervel 0.4 release, require Guzzle 8 across the root and split packages, remove Guzzle 7 compatibility branches and its CI job, and update the related Promises/PSR-7 constraints and documentation. Recheck consumer compatibility and retain applicable tests on Guzzle 8.
-- If [Guzzle #3935](https://github.com/guzzle/guzzle/pull/3935) merges, once the minimum supported Guzzle versions include it, pass `max_idle_handles` directly to `Utils::chooseHandler()` and remove Hypervel's custom idle-handle composition, preserving the connection option and default of 256.
+- If [Guzzle #3935](https://github.com/guzzle/guzzle/pull/3935) merges, once the minimum supported Guzzle versions include it, pass `max_idle_handles` directly to `Utils::chooseHandler()` and replace the custom composition in `Http\Client\Guzzle\HandlerFactory`, preserving the connection option and default of 256 for the HTTP client, Pusher and Scout SDK clients.
 - Recheck streaming performance once a build containing the Swoole native `curl_multi_select()` fix is available. The affected hook can consume ready response data internally and then wait for another event or its timeout before returning. Hypervel therefore sometimes delays an SSE event or completion by up to one second, even though the data has arrived. This requires no Hypervel workaround.
   - Run `Hypervel\Tests\Http\Client\CurlStreamingHandlerTest::testNativeWaitReportsDataArrivingBetweenPerformAndSelect` against the patched extension with its temporary version-gate skip removed locally. Verify both mid-stream readiness and completion, plus the existing quiet-provider timeout/cancellation and cleanup tests. Update the committed version gate only after identifying the actual fixed release; the current gate does not establish that a later release is fixed.
   - In an idle window, use `tests/Benchmarks/HttpTransport` and its README to repeat alternating paired measurements before/after high-water buffering on the same patched runtime. Keep dependencies, TLS verification, idle-retention bound, PHP/OPcache/JIT/GC settings and request concurrency identical. Cover paced events, unpaced bulk responses and slow consumers, then repeat sustained concurrent traffic. Check first-event and completion latency (including outliers), throughput, client CPU, memory, connection reuse and descriptor cleanup. Confirm the one-second stalls disappear without changing Hypervel's select interval or buffering strategy.

src/broadcasting/composer.json

@@ -33,6 +33,7 @@
         "hypervel/container": "^0.4",
         "hypervel/context": "^0.4",
         "hypervel/contracts": "^0.4",
+        "hypervel/database": "^0.4",
         "hypervel/foundation": "^0.4",
         "hypervel/http": "^0.4",
         "hypervel/object-pool": "^0.4",

src/broadcasting/src/BroadcastManager.php

@@ -36,6 +36,7 @@
 use Hypervel\Contracts\Queue\Factory as Queue;
 use Hypervel\Contracts\Redis\Factory as RedisFactory;
 use Hypervel\Foundation\Http\Middleware\PreventRequestForgery;
+use Hypervel\Http\Client\Guzzle\HandlerFactory;
 use Hypervel\Http\Request;
 use Hypervel\ObjectPool\Concerns\HasPoolProxy;
 use Hypervel\Queue\Attributes\Connection as ConnectionAttribute;
@@ -413,22 +414,14 @@ public function pusher(array $config): Pusher
         );
 
         if (! isset($clientOptions['handler'])) {
-            foreach (['max_host_connections', 'max_total_connections'] as $option) {
-                if (isset($clientOptions[$option])) {
-                    throw new InvalidArgumentException(
-                        "The [{$option}] broadcasting client option requires a shared multi-handler, which is unsafe across coroutines. Bound coroutine concurrency or use rate limiting instead."
-                    );
-                }
-            }
-
-            $handlerOptions = Arr::only($clientOptions, ['transport_sharing']);
+            $handlerOptions = Arr::only($clientOptions, ['transport_sharing', 'max_host_connections', 'max_total_connections']);
             unset($clientOptions['transport_sharing']);
 
             if (($clientOptions['multiplex'] ?? null) === Multiplexing::NONE) {
                 $handlerOptions['multiplex'] = Multiplexing::NONE;
             }
 
-            $sharedHandler = Utils::chooseHandler($handlerOptions)(...);
+            $sharedHandler = HandlerFactory::create($handlerOptions)(...);
 
             // Async transfers may share a multi-handler only within their owning coroutine.
             $clientOptions['handler'] = HandlerStack::create(

src/broadcasting/src/Broadcasters/AblyBroadcaster.php

@@ -9,6 +9,7 @@
 use Ably\Models\Message as AblyMessage;
 use Hypervel\Broadcasting\BroadcastException;
 use Hypervel\Contracts\Container\Container;
+use Hypervel\Database\ConnectionResolver;
 use Hypervel\Http\Request;
 use Hypervel\Support\Str;
 use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
@@ -126,8 +127,11 @@ public function broadcast(array $channels, string $event, array $payload = []):
                 $channel = $this->ably->channels->get($name);
 
                 try {
+                    $message = $this->buildAblyMessage($event, $payload);
+                    ConnectionResolver::releaseIdleConnections();
+
                     /* @phpstan-ignore arguments.count, argument.type (Ably declares two @method publish() overloads and PHPStan keeps only the last; publish(...$args) accepts a Message as its sole argument.) */
-                    $channel->publish($this->buildAblyMessage($event, $payload));
+                    $channel->publish($message);
                 } finally {
                     if ($channel->getCipherParams() === null) {
                         $this->ably->channels->release($name);

src/broadcasting/src/Broadcasters/PusherBroadcaster.php

@@ -6,6 +6,7 @@
 
 use Hypervel\Broadcasting\BroadcastException;
 use Hypervel\Contracts\Container\Container;
+use Hypervel\Database\ConnectionResolver;
 use Hypervel\Http\Request;
 use Hypervel\Support\Arr;
 use Hypervel\Support\Collection;
@@ -136,6 +137,7 @@ public function broadcast(array $channels, string $event, array $payload = []):
 
         try {
             $channels->chunk(100)->each(function ($channels) use ($event, $payload, $parameters) {
+                ConnectionResolver::releaseIdleConnections();
                 $this->pusher->trigger($channels->toArray(), $event, $payload, $parameters);
             });
         } catch (ApiErrorException $e) {

src/broadcasting/src/Mercure/Hub.php

@@ -7,6 +7,7 @@
 use Closure;
 use Hypervel\Contracts\ObjectPool\Factory;
 use Hypervel\Contracts\Routing\UrlGenerator;
+use Hypervel\Database\ConnectionResolver;
 use Hypervel\ObjectPool\PoolDefinition;
 use Hypervel\ObjectPool\PoolProxy;
 use Symfony\Component\Mercure\Hub as SymfonyHub;
@@ -101,6 +102,7 @@ public function publish(Update $update): string
     {
         $url = $this->getUrl();
         $publicUrl = $this->getPublicUrl();
+        ConnectionResolver::releaseIdleConnections();
         $lease = $this->lease();
 
         try {

src/cache/src/Limiters/ConcurrencyLimiter.php

@@ -9,6 +9,7 @@
 use Hypervel\Contracts\Cache\RefreshableLock;
 use Hypervel\Contracts\Limiters\Lease;
 use Hypervel\Contracts\Limiters\LimiterTimeoutException;
+use Hypervel\Database\ConnectionResolver;
 use Hypervel\Support\Sleep;
 use Hypervel\Support\Str;
 use Swoole\Coroutine\CanceledException;
@@ -64,6 +65,7 @@ public function acquire(int $timeout, int $sleep = 250): Lease
                 throw new LimiterTimeoutException;
             }
 
+            ConnectionResolver::releaseIdleConnections();
             Sleep::usleep($sleep * 1000);
         }
 

src/cache/src/Lock.php

@@ -6,6 +6,7 @@
 
 use Hypervel\Contracts\Cache\Lock as LockContract;
 use Hypervel\Contracts\Cache\LockTimeoutException;
+use Hypervel\Database\ConnectionResolver;
 use Hypervel\Support\CarbonImmutable;
 use Hypervel\Support\InteractsWithTime;
 use Hypervel\Support\Sleep;
@@ -105,6 +106,7 @@ public function block(int $seconds, ?callable $callback = null): mixed
                 throw new LockTimeoutException;
             }
 
+            ConnectionResolver::releaseIdleConnections();
             Sleep::usleep($this->sleepMilliseconds * 1000);
         }
 

src/concurrency/composer.json

@@ -32,6 +32,7 @@
         "hypervel/context": "^0.4",
         "hypervel/contracts": "^0.4",
         "hypervel/coroutine": "^0.4",
+        "hypervel/database": "^0.4",
         "hypervel/log": "^0.4",
         "hypervel/process": "^0.4",
         "hypervel/support": "^0.4",