Пакет · cpool

Свой адаптер

Адаптер — единственное место, знающее, что лежит в пуле. Три метода, и почти вся сложность сосредоточена в одном из них.

Контракт

php
interface ConnectionFactory
{
  public function create(): object;
  public function validate(object $connection): bool;
  public function close(object $connection): void;
}

Если у соединения есть сессионное состояние — транзакция, режим, выбранная база, — адаптер дополнительно реализует необязательный четвёртый метод. Он описан ниже.

php
interface ResettableConnectionFactory extends ConnectionFactory
{
  public function reset(object $connection): bool;
}

create()

Открывает одно соединение и возвращает его. Может бросать — пул завернёт любое исключение в PoolException::connectFailed(), поэтому вызывающий видит один тип независимо от драйвера.

Здесь делается полное рукопожатие: подключение, аутентификация, выбор базы, сессионные параметры. Недонастроенное соединение, отданное пулу, станет недонастроенным соединением у случайного заёмщика позже.

validate() — здесь ошибаются чаще всего

Отвечает на один вопрос: сработал бы сейчас запрос на этом соединении?

php
public function validate(object $connection): bool
{
  try {
      $connection->query('SELECT 1');   // Redis: $connection->ping()
      return true;
  } catch (Throwable) {
      return false;
  }
}

Три правила:

Возвращайте false, а не бросайте. Брошенное исключение пул тоже считает признаком смерти, так что ничего не сломается — но намерение размывается, а в трассе появляется шум.

Один round-trip, не больше. Проверка выполняется на большинстве выдач, и всё дорогое здесь оплачивает каждый запрос.

Проверяйте соединение, а не схему. SELECT 1 и PING отвечают «сокет жив». Проверка, которая трогает таблицу, провалится и при её блокировке — и пул начнёт увлечённо выселять совершенно исправные соединения.

Свежее соединение не проверяется

У только что созданного соединения метка последнего использования — момент создания, поэтому оно попадает в окно aliveBypassWindow и выдаётся без проверки. Проверять сокет, который сами же открыли секунду назад, значит платить за рукопожатие дважды.

close()

Освобождает ресурс. Ошибки здесь пул игнорирует: соединение и так уходит, а исключение только скрыло бы причину, по которой его закрывают.

Некоторым драйверам делать нечего — PDO закрывается при разыменовании, и пустое тело честнее выдуманного вызова. Другим нужен явный close().

reset() — если у соединения есть сессия

Соединение живёт дольше заёмщика, и всё, что заёмщик на нём оставил, достаётся следующему. Для базы это открытая транзакция: запрос начал её, упал до commit(), и соединение вернулось в пул посреди транзакции. Следующий заёмщик пишет внутрь чужой транзакции — его записи пропадут вместе с ней, а его собственный beginTransaction() упадёт с «already active». Для Redis то же самое делают брошенный MULTI, незакрытый pipeline() и переключённая через SELECT база.

validate() этого не видит и не должен: SELECT 1 прекрасно отвечает изнутри открытой транзакции, соединение живое. Для этого случая есть отдельный метод — reset() из интерфейса ResettableConnectionFactory.

Пул вызывает его при каждом release(), до того как соединение вернётся в оборот. true — соединение чистое и идёт обратно в пул; false или брошенное исключение — привести его в порядок не удалось, и пул его выселяет. evict() reset() не вызывает: мёртвое соединение закрывают, а не чистят.

php
public function reset(object $connection): bool
{
  if (!$connection->inTransaction()) {
      return true;                     // обычный случай — без похода на сервер
  }
  $this->logger->error('connection returned with an open transaction — rolled back');
  $connection->rollBack();

  return true;
}

Три правила:

Чистый случай — без round-trip. reset() вызывается на каждом возврате, то есть на каждом запросе. Узнавайте состояние у драйвера, который и так его помнит: inTransaction() у PDO, getMode() и getDbNum() у phpredis. Запрос к серверу «на всякий случай» оплачивает каждый запрос.

Отменять, а не завершать. Откат, а не commit(); DISCARD, а не EXEC. Заёмщик не довёл работу до конца, и завершить её за него — значит опубликовать то, что он не собирался публиковать.

Сообщать в лог. Соединение с хвостом на возврате — это ошибка в коде того, кто его держал: забытый commit(), исключение мимо finally, ранний return. Пул лечит последствия, но причину видно только в логе.

Почему отдельный интерфейс

reset() — не четвёртый метод ConnectionFactory, а отдельный интерфейс, который её расширяет. Адаптеру, которому нечего сбрасывать, ничего не нужно менять, а пул вызывает reset() только у тех, кто его объявил.

Полный пример: Redis

src/RedisFactory.php
<?php

use Flytachi\Winter\CPool\ResettableConnectionFactory;

final readonly class RedisFactory implements ResettableConnectionFactory
{
  public function __construct(
      private string $host,
      private int    $port = 6379,
      private string $password = '',
      private int    $database = 0,
  ) {}

  public function create(): object
  {
      $redis = new \Redis();
      $redis->connect($this->host, $this->port, 2.0);

      if ($this->password !== '') {
          $redis->auth($this->password);
      }
      $redis->select($this->database);

      return $redis;
  }

  public function validate(object $connection): bool
  {
      try {
          return $connection->ping() !== false;
      } catch (\Throwable) {
          return false;
      }
  }

  public function close(object $connection): void
  {
      try {
          $connection->close();
      } catch (\Throwable) {
          // уже закрыто — делать нечего
      }
  }

  public function reset(object $connection): bool
  {
      try {
          if ($connection->getMode() !== \Redis::ATOMIC) {
              $connection->discard();          // брошенный MULTI или pipeline()
          }
          if ($connection->getDbNum() !== $this->database) {
              $connection->select($this->database);
          }
          return true;
      } catch (\Throwable) {
          return false;                        // пул выселит соединение
      }
  }
}

Обе проверки в reset() бесплатны: режим и номер базы phpredis хранит у себя, на сервер идёт только сама уборка — и только когда убирать есть что.

Чего адаптер делать не должен

Кэшировать соединение. Адаптер создаёт, пул владеет. Адаптер, запоминающий свой результат, превращает пул из десяти соединений в одно, разделённое на десятерых — ровно тот баг, ради которого пул и существует.

Считать, что его вызовут один раз. create() работает при каждом росте пула и после каждого выселенного соединения. Всё одноразовое — чтение конфигурации, резолв хоста — место в конструкторе.

Хранить состояние запроса. Адаптер живёт дольше любого заёмщика. Идентификатор арендатора или контекст пользователя, захваченный в него, утечёт в соединения чужих запросов.

Дальше