fix(pools): release the reserved slot when connection creation fails

[loks0n]

The bug

Pool::pop() reserves capacity by incrementing connectionsCreated before the connection exists, then releases it in a catch:

$this->connectionsCreated++;          // reserved, lock released
...
try {
    $connection = $this->createConnection();
    ...
    return $connection;
} catch (\Exception $e) {             // ← only Exception
    $this->connectionsCreated--;
}

The init callback is caller-supplied, so an Error is entirely reachable — a TypeError from the callback, or a failure inside an adapter. Anything that isn't an Exception escapes the catch and keeps the slot.

Each leaked slot is permanent for the life of the process, and they accumulate one failed pop() at a time. Once connectionsCreated reaches size, the first branch never fires again and the pool reports itself empty while nothing is in use:

Pool 'db-…' is empty (size 24, active 0, idle 0)

active 0, idle 0 with size 24 is the tell — all capacity reserved, nothing checked out, nothing to hand back.

The consequence is worse than the arithmetic suggests. An upstream backend outage should degrade into slow acquisition and recover when the backend does. Instead every failed pop ratchets capacity down, so the process stays broken after the outage clears. Only a restart recovers it.

The fix

Catch \Throwable, and move the release into a finally guarded by a $reserved flag, so the reservation is balanced on every path out of the block rather than the ones a catch happens to enumerate.

destroyConnection() already uses catch (\Throwable) a few lines below for the same reason — this brings pop() in line with it.

Test

Drains a size-2 pool with five pop()s against an init callback that throws a TypeError:

before:  Failed asserting that 0 is identical to 2     ← capacity gone
after:   OK

That is the production signature reproduced as a unit test — capacity at zero with nothing handed out.

Full suite: 108 tests, 372 assertions, green. bin/monorepo check pools clean (PHPStan level 8, Pint, Rector).

PHPStan flagged the first version of the test for catching \TypeError — dead, because with the fix pop() surfaces exhaustion as an Exception with the original attached as previous. The test now asserts that instead, which is a better check anyway.

Prior art

Filed previously as utopia-php/pools#34 and auto-closed by the mirror-redirect bot ("development happens in packages/pools in the monorepo"). That version changed the catch only; this one adds the finally so the balance does not depend on enumerating throwable types.

Not included

createConnection() retries internally (reconnectAttempts) inside pop()'s own retry loop (retryAttempts), both defaulting to 3 with 1s sleeps. Against a backend that consumes a full connect timeout, one pop() can take ~35s before failing. That is a defaults question rather than a correctness one, and consumers can already scope it per pool, so I have left it alone here.

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

Updates pool acquisition cleanup so failed connection creation always releases reserved capacity.

• Catches all Throwable failures from caller-supplied connection initialization.
• Balances capacity reservations through a guarded finally block.
• Adds regression coverage for repeated initialization failures caused by TypeError.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
packages/pools/src/Pools/Pool.php	Ensures failed connection creation releases its reserved capacity slot, including when initialization throws an Error.
packages/pools/tests/Pools/Scopes/PoolTestScope.php	Adds regression coverage confirming repeated TypeError failures do not permanently reduce pool capacity.

_{Reviews (2): Last reviewed commit: "fix(pools): release the reserved slot wh..." | Re-trigger Greptile}