Clarify pool APIs and fix resource lifecycles

AGENTS.md

@@ -782,7 +782,7 @@ Read `docs/ai/porting-hyperf.md` only when porting a Hyperf package or update.
 
 If the Hypervel version of the package doesn't exist yet, create the skeleton using an existing package as a template:
 - **Porting a Laravel first-party package:** Use the `cache` package as reference
-- **Porting a Hyperf package:** Use the `pool` package as reference
+- **Porting a Hyperf package:** Use the `websocket-server` package as reference
 - **Porting a Laravel-ecosystem third-party package:** Use the `permission` package as a reference
 
 Read the reference package's `composer.json`, `LICENSE.md`, and `README.md` and create equivalents for the new package. Every package must be wired in both places: its own `src/{package}/composer.json` for the subtree split, and the root `composer.json` for monorepo development. Update autoloading, `replace`, and Hypervel provider / alias discovery metadata as needed, and add root dependencies with `composer require` — see Providers and Listeners for where providers should be registered. Create the README using the Package READMEs format under Development Conventions.

composer.json

@@ -33,6 +33,7 @@
             "Hypervel\\Bus\\": "src/bus/src/",
             "Hypervel\\Cache\\": "src/cache/src/",
             "Hypervel\\Config\\": "src/config/src/",
+            "Hypervel\\ConnectionPool\\": "src/connection-pool/src/",
             "Hypervel\\Console\\": "src/console/src/",
             "Hypervel\\Container\\": "src/container/src/",
             "Hypervel\\Context\\": "src/context/src/",
@@ -66,7 +67,6 @@
             "Hypervel\\Pagination\\": "src/pagination/src/",
             "Hypervel\\Passkeys\\": "src/passkeys/src/",
             "Hypervel\\Pipeline\\": "src/pipeline/src/",
-            "Hypervel\\Pool\\": "src/pool/src/",
             "Hypervel\\Process\\": "src/process/src/",
             "Hypervel\\Prompts\\": "src/prompts/src/",
             "Hypervel\\Queue\\": "src/queue/src/",
@@ -236,6 +236,7 @@
         "hypervel/concurrency": "self.version",
         "hypervel/conditionable": "self.version",
         "hypervel/config": "self.version",
+        "hypervel/connection-pool": "self.version",
         "hypervel/console": "self.version",
         "hypervel/container": "self.version",
         "hypervel/context": "self.version",
@@ -273,7 +274,6 @@
         "hypervel/pagination": "self.version",
         "hypervel/passkeys": "self.version",
         "hypervel/pipeline": "self.version",
-        "hypervel/pool": "self.version",
         "hypervel/process": "self.version",
         "hypervel/prompts": "self.version",
         "hypervel/queue": "self.version",

docs/ai/porting-hyperf.md

@@ -77,7 +77,7 @@ Before migrating a ConfigProvider, read:
 - `src/docs/packages.md#class-map-overrides` if the package uses class map replacement
 - `Hypervel\Support\ServiceProvider`
 
-Use existing Hypervel packages as pattern references. For low-level Swoole / Hyperf-style infrastructure, useful references include `pool`, `object-pool`, `engine`, `server`, `signal`, and `sentry`. The `database` package is a good reference for translating Hyperf provider patterns into Hypervel provider code.
+Use `websocket-server` as the package skeleton reference for Composer metadata, licensing, and provider discovery. For provider patterns, see `engine` for contract bindings and `signal` for worker-lifecycle listeners. The `database` package is a useful reference for more involved provider registration. Adapt the relevant pattern rather than copying a package's runtime-specific setup.
 
 ### Categorize the ConfigProvider entries
 

src/broadcasting/composer.json

@@ -35,12 +35,12 @@
         "symfony/http-kernel": "^8.1",
         "hypervel/bus": "^0.4",
         "hypervel/collections": "^0.4",
+        "hypervel/connection-pool": "^0.4",
         "hypervel/container": "^0.4",
         "hypervel/contracts": "^0.4",
         "hypervel/foundation": "^0.4",
         "hypervel/http": "^0.4",
         "hypervel/object-pool": "^0.4",
-        "hypervel/pool": "^0.4",
         "hypervel/queue": "^0.4",
         "hypervel/routing": "^0.4",
         "hypervel/support": "^0.4"

src/broadcasting/src/BroadcastManager.php

@@ -23,12 +23,12 @@
 use Hypervel\Contracts\Cache\Repository as Cache;
 use Hypervel\Contracts\Container\Container;
 use Hypervel\Contracts\Foundation\CachesRoutes;
+use Hypervel\Contracts\ObjectPool\Factory as PoolFactory;
 use Hypervel\Contracts\Queue\Factory as Queue;
 use Hypervel\Contracts\Redis\Factory as RedisFactory;
 use Hypervel\Foundation\Http\Middleware\PreventRequestForgery;
 use Hypervel\Http\Request;
-use Hypervel\ObjectPool\Contracts\Factory as PoolFactory;
-use Hypervel\ObjectPool\Traits\HasPoolProxy;
+use Hypervel\ObjectPool\Concerns\HasPoolProxy;
 use Hypervel\Queue\Attributes\Connection as ConnectionAttribute;
 use Hypervel\Queue\Attributes\Queue as QueueAttribute;
 use Hypervel\Queue\Attributes\ReadsQueueAttributes;
@@ -70,7 +70,7 @@ class BroadcastManager implements BroadcastingFactoryContract
     /**
      * The array of drivers which will be wrapped as pool proxies.
      */
-    protected array $poolables = [];
+    protected array $poolableDrivers = [];
 
     /**
      * Create a new manager instance.
@@ -310,7 +310,7 @@ protected function resolve(string $name): Broadcaster
 
         $constructionConfig = Arr::except($config, ['pool']);
 
-        return in_array($config['driver'], $this->poolables, true)
+        return in_array($config['driver'], $this->poolableDrivers, true)
             ? $this->createPoolProxy(
                 $config['driver'],
                 fn () => $this->doResolve(null, $constructionConfig),
@@ -530,7 +530,7 @@ public function purge(UnitEnum|string|null $name = null): void
 
         $config = $this->getConfig($name);
 
-        if (is_null($config) || ! in_array($config['driver'], $this->poolables, true)) {
+        if (is_null($config) || ! in_array($config['driver'], $this->poolableDrivers, true)) {
             return;
         }
 
@@ -541,7 +541,7 @@ public function purge(UnitEnum|string|null $name = null): void
             $constructionConfig,
         );
 
-        $this->poolFactory()->remove($definition->identity);
+        $this->poolFactory()->purge($definition->identity);
     }
 
     /**

src/broadcasting/src/Broadcasters/RedisBroadcaster.php

@@ -5,10 +5,10 @@
 namespace Hypervel\Broadcasting\Broadcasters;
 
 use Hypervel\Broadcasting\BroadcastException;
+use Hypervel\ConnectionPool\Exceptions\ConnectionException;
 use Hypervel\Contracts\Container\Container;
 use Hypervel\Contracts\Redis\Factory as Redis;
 use Hypervel\Http\Request;
-use Hypervel\Pool\Exceptions\ConnectionException;
 use Hypervel\Support\Arr;
 use RedisClusterException;
 use RedisException;

src/pool/README.md → src/connection-pool/README.md

@@ -1,8 +1,6 @@
-Pool for Hypervel
+Connection Pool for Hypervel
 ===
 
-[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/hypervel/pool)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/hypervel/connection-pool)
 
 Documentation: https://hypervel.org/docs/pools#connection-pools
-
-Ported from: https://github.com/hyperf/hyperf/tree/master/src/pool

src/pool/composer.json → src/connection-pool/composer.json

@@ -1,5 +1,5 @@
 {
-    "name": "hypervel/pool",
+    "name": "hypervel/connection-pool",
     "type": "library",
     "description": "Connection pooling for Hypervel packages.",
     "license": "MIT",
@@ -26,7 +26,7 @@
     },
     "autoload": {
         "psr-4": {
-            "Hypervel\\Pool\\": "src/"
+            "Hypervel\\ConnectionPool\\": "src/"
         }
     },
     "require": {

src/connection-pool/src/BorrowRateTracker.php

@@ -0,0 +1,124 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\ConnectionPool;
+
+use Hypervel\Contracts\ConnectionPool\UsageTracker;
+
+/**
+ * Track recent borrowing activity to shrink pools during periods of low usage.
+ */
+class BorrowRateTracker implements UsageTracker
+{
+    /**
+     * @var array<int, int>
+     */
+    protected array $borrows = [];
+
+    protected int $window = 10;
+
+    protected int $threshold = 5;
+
+    protected int $cooldown = 60;
+
+    protected ?int $startedAt = null;
+
+    protected ?int $lastTrimAt = null;
+
+    protected ?int $lastPrunedAt = null;
+
+    protected int $borrowCount = 0;
+
+    /**
+     * Record a successful connection borrow.
+     */
+    public function recordBorrow(): void
+    {
+        $now = $this->currentTime();
+
+        if ($this->startedAt === null) {
+            $this->startedAt = $now;
+            $this->lastTrimAt = $now;
+        }
+
+        $this->prune($now);
+        $this->borrows[$now] = ($this->borrows[$now] ?? 0) + 1;
+        ++$this->borrowCount;
+    }
+
+    /**
+     * Return the average number of borrows per sampled second.
+     */
+    public function getBorrowRate(): float
+    {
+        if ($this->startedAt === null) {
+            return 0.0;
+        }
+
+        $this->prune($this->currentTime());
+        $sampleCount = count($this->borrows);
+
+        return $sampleCount === 0 ? 0.0 : $this->borrowCount / $sampleCount;
+    }
+
+    /**
+     * Determine whether low usage and the cooldown permit trimming.
+     */
+    public function shouldTrimExcessIdle(): bool
+    {
+        if ($this->lastTrimAt === null) {
+            return false;
+        }
+
+        $now = $this->currentTime();
+
+        if ($this->lastTrimAt + $this->cooldown >= $now) {
+            return false;
+        }
+
+        $this->prune($now);
+        $sampleCount = count($this->borrows);
+
+        if (($sampleCount === 0 ? 0.0 : $this->borrowCount / $sampleCount) < $this->threshold) {
+            $this->lastTrimAt = $now;
+
+            return true;
+        }
+
+        return false;
+    }
+
+    /**
+     * Remove expired samples and fill completed seconds without borrows.
+     */
+    protected function prune(int $now): void
+    {
+        if ($this->lastPrunedAt === $now) {
+            return;
+        }
+
+        $latest = $now - $this->window + 1;
+
+        foreach ($this->borrows as $second => $count) {
+            if ($second < $latest) {
+                $this->borrowCount -= $count;
+                unset($this->borrows[$second]);
+            }
+        }
+
+        for ($second = max($this->startedAt, $latest); $second < $now; ++$second) {
+            $this->borrows[$second] ??= 0;
+        }
+
+        $this->lastPrunedAt = $now;
+    }
+
+    /**
+     * Return the current sampling second.
+     */
+    protected function currentTime(): int
+    {
+        return intdiv(hrtime(true), 1_000_000_000);
+    }
+}