Superset 26.500.0: проверка готовности сервера и повтор GET после быстрого 5xx

Superset 26.500.0 из коробочного Битрикс24 нужен тем, кто обращается из своего кода к собственному (self-hosted) серверу BI Конструктора. У публичных провайдеров два новых метода: ServerProvider::checkReadiness() проверяет, что Superset видит свою базу метаданных, а DatasetProvider::listPhysical() отдаёт только датасеты на таблицах. Коннектор к Superset теперь один раз повторяет GET после быстрого 5xx и умеет писать эти повторы в лог superset.SupersetInstance, а из публичного API ничего не удалено.

Новое

Проверьте, готов ли сервер

ping() спрашивает у Superset /health. Новый checkReadiness(?float $timeBudget = null) запрашивает список дашбордов из одной записи, а за ним Superset идёт в базу метаданных. По докблоку метода запущенный сервер, который ещё не достучался до своей базы, ответит здесь серверной ошибкой.

Статус ответа лежит в getData()['httpStatus'] как есть, включая 555 и 521. Код 555 коннектор подставляет вместо ответов 502 и 503, в модуле он называется DEACTIVATED_INSTANCE, а в докблоках спящим инстансом. Код 521 — это SERVER_DOWN. Если итоговый запрос получил 4xx, а обновление токена упало с 5xx, метод вернёт статус обновления токена, и ошибка авторизации не спрячет серверную причину.

Код 555 при импорте теперь тоже не теряется. Ошибки импорта дашборда, чарта и датасета на инстансе в этом состоянии несут строку '555' в Error::getCode(), и спящий инстанс можно отличить от обычного сбоя.

$timeBudget задаёт секунды на всю проверку вместе с обновлением токена. Таймауты каждого запроса режутся под остаток: половина на соединение, остальное на чтение. Когда до дедлайна меньше 2 с, запрос уже не уходит, и проверка заканчивается кодом 521 с ошибкой «Superset request time limit exceeded». У проверки свой коннектор с таймаутами 5 с на соединение и 10 на чтение, повторов у него нет.

Возьмите только датасеты на таблицах

DatasetProvider::listPhysical() возвращает все физические датасеты инстанса, то есть построенные на таблице, без виртуальных SQL-датасетов. Фильтрует сам Superset оператором dataset_is_null_or_empty по колонке sql, и виртуальные датасеты даже не передаются по сети.

За пределами модуля superset оба метода в коробке пока никто не вызывает. В своём модуле их стоит связать так, чтобы чтение шло только после успешной проверки готовности.

        <?php declare(strict_types=1);

namespace Vendor\Bi\Application;

use Bitrix\Main\Error;
use Bitrix\Main\Loader;
use Bitrix\Main\Result;
use Bitrix\Superset\Public\Providers\DatasetProvider;
use Bitrix\Superset\Public\Providers\SelfHostedServerProvider;
use Bitrix\Superset\Public\Providers\ServerProvider;

final class PhysicalDatasetReader
{
    public function read(float $timeBudget = 8.0): Result
    {
        Loader::requireModule('superset');

        $server = SelfHostedServerProvider::findReference();
        if ($server === null) {
            return (new Result())->addError(new Error('Superset server is not configured'));
        }

        $readiness = (new ServerProvider($server))->checkReadiness($timeBudget);
        $status = (int)($readiness->getData()['httpStatus'] ?? 0);
        if ($status !== 200) {
            // 555 — Superset ответил 502/503 (инстанс спит), 521 — не ответил или не уложился в бюджет
            return (new Result())->addError(new Error('Superset is not ready', $status));
        }

        return (new DatasetProvider($server))->listPhysical();
    }
}

    

Датасеты придут в getData()['datasets'], и карту «ID датасета → таблица» соберёт array_column($result->getData()['datasets'], 'table_name', 'id').

Повтор GET после быстрого 5xx

GET-запросы к Superset идут через коннектор SupersetInstance, в том числе запросы публичных провайдеров. Если Superset ответил 5xx быстрее, чем за 5 с, коннектор выждет секунду и повторит запрос с таймаутами не больше 5 с на соединение и 10 на чтение. Это не касается ответов 502 и 503: коннектор заменяет их на 555. Ответы 555, 521 и медленные ошибки не повторяются. Если повтор вернул 521, наружу уходит первый ответ. Пользователь BI Конструктора увидит меньше случайных ошибок, а сбойный запрос станет дольше на секунду паузы плюс время второй попытки.

Повтор положен один на экземпляр коннектора. Объект провайдера держит свой коннектор, поэтому после первого повтора следующие быстрые 5xx через тот же объект придут без второй попытки.

Включите лог повторов

Каждый повтор пишется с уровнем warning в именованный логгер superset.SupersetInstance. В запись попадают путь без query-строки, оба статуса и время первой попытки. Пока логгер не описан в секции loggers файла .settings.php, записей нет. Добавьте его:

        'loggers' => [
    'value' => [
        'superset.SupersetInstance' => [
            'constructor' => static fn () => new \Bitrix\Main\Diag\FileLogger(
                '/var/log/bitrix/superset-retry.log',
                10 * 1024 * 1024,
            ),
            'level' => \Psr\Log\LogLevel::WARNING,
        ],
    ],
    'readonly' => true,
],