Add configurable session pool size limit

[vgvoleg]

Closes #209.

Adds the optional sessionPoolMaxSize client setting. The default remains unlimited for backward compatibility; a positive value caps the number of idle, busy, and in-progress session creations owned by that client.

Capacity is reserved before CreateSession, released on both success and failure, and exhaustion is reported as ClientResourceExhaustedException. Session pools are now client-scoped instead of process-wide static state so limits and sessions do not leak across separate Ydb clients.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 53.97%. Comparing base (95214df) to head (a114cf9).

Additional details and impacted files

@@             Coverage Diff              @@
##               main     #298      +/-   ##
============================================
+ Coverage     52.67%   53.97%   +1.30%     
- Complexity      989     1013      +24     
============================================
  Files            66       66              
  Lines          2690     2740      +50     
============================================
+ Hits           1417     1479      +62     
+ Misses         1273     1261      -12     

Components	Coverage Δ
Native SDK	53.97% <100.00%> (+1.30%)	⬆️

Files with missing lines	Coverage Δ
src/Sessions/MemorySessionPool.php	97.87% <100.00%> (+26.44%)	⬆️
src/Table.php	76.05% <100.00%> (+4.73%)	⬆️
src/Ydb.php	79.85% <100.00%> (+4.41%)	⬆️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Copilot review overview

🟡 Changes recommended

Pool ownership is table-scoped rather than client-scoped, allowing multiple tables for one client to exceed the configured limit.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1

Open (1)

• Share session pool across tables using the same Ydb client · New

What changed in this PR

Adds configurable session-pool limits and isolates pools from process-wide static state.

Changes:

• Adds and validates sessionPoolMaxSize.
• Tracks active and reserved session capacity.
• Documents and tests pool limits and client isolation.

File	Description
src/​Ydb.php	Parses and exposes the pool limit.
src/​Table.php	Creates instance pools and reserves creation capacity.
src/​Sessions/​MemorySessionPool.php	Enforces limits and tracks reservations.
src/​Contracts/​SessionPoolCapacityContract.php	Defines capacity reservation operations.
tests/​SessionPoolSizeLimitTest.php	Tests limits, failures, reuse, and isolation.
README.md	Documents configuration and exhaustion behavior.
CHANGELOG.md	Records the new setting.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🔵 Needs a closer look

The in-progress session creation limit lacks regression coverage.

Review effort: Balanced
Findings: None

Resolved since last review (1)

• Share session pool across tables using the same Ydb client

Previously missed (1)

In code that hasn't changed since last review

Test concurrent CreateSession capacity consumption

tests/​SessionPoolSizeLimitTest.php:106

This test only attempts the second creation after the first request and reservation have completed, so it does not verify the new requirement that an in-progress CreateSession consumes capacity. The suite would still pass if $reservedSlots were removed from the capacity calculation. Add a re-entrant or otherwise paused CreateSession test that attempts another creation while the first request is outstanding and asserts ClientResourceExhaustedException.

[Copilot]

Copilot review overview

🔵 Needs a closer look

Configuration validation currently accepts integral floating-point values despite requiring a positive integer.

Review effort: Balanced
Findings: None

Previously missed (1)

In code that hasn't changed since last review

Reject integral floats for positive integer validation

src/​Ydb.php:274

FILTER_VALIDATE_INT converts an integral float such as 1.0 to integer 1, so this accepts a value that the documented “positive integer” contract—and MemorySessionPool's constructor—rejects. Explicitly reject floats before filtering (while retaining numeric-string support if intended).

[Copilot]

Copilot review overview

🔵 Needs a closer look

Custom pools lacking the optional capacity contract silently bypass the configured client limit.

Review effort: Balanced
Findings: None

Previously missed (1)

In code that hasn't changed since last review

Custom pools bypass configured session pool limits

src/​Table.php:173

A configured limit is silently bypassed for every existing custom SessionPoolContract that does not implement the new optional capacity contract: both capacityPool and reservation remain null, so repeated createSession() calls can add unlimited sessions despite sessionPoolMaxSize. This contradicts the client-level limit exposed by the setting. Please enforce capacity independently of the pool, or reject an incompatible custom pool when a finite limit is configured.

[Copilot]

Copilot review overview

🟢 Approval recommended

The implementation consistently enforces client-scoped capacity and includes strong regression coverage.

Review effort: Balanced
Findings: None