Cluster · разработчикам

Составной пример SDK

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

Сценарий

На странице модуля есть форма создания отчёта. Введённый текст отправляется в postman-echo.com, который возвращает его обратно. Передавай только искусственные данные: это внешний сервис, а не часть Cluster.

Одновременно модуль вызывает функцию digest зависимости. Она считает SHA-256 исходного текста. Дальше проверяется ответ HTTPS, результат зависимости и содержимое созданного файла.

Файл записывается через Writer, копия отправляется по HTTPS и удаляется после проверки. Счётчик, последняя запись и запись истории сохраняются одним Batch. Страница получает новое значение показателя и строку таблицы. В журнал попадает время выполнения.

Тот же сценарий доступен через кнопку в Telegram, одноразовое расписание и входящий запрос. Повторное нажатие на создание расписания возвращает уже ожидающую задачу. После её удаления можно создать новую.

Объекты

Согласованность

Изменения базы внутри Batch атомарны. Внешний HTTPS-запрос, файл, страница и журнал не входят в эту транзакцию. Например, сервис уже мог получить файл до отказа базы сохранить отчёт. Это нельзя отменить откатом локальной записи.

Если ошибка произошла до записи Batch, готовый файл отчёта удаляется. Копия для отправки удаляется при выходе из своего блока. При потере связи или отзыве права очистка может быть недоступна; срок хранения остаётся запасным способом освобождения места.

После записи базы отчёт считается созданным. Ошибка обновления страницы или уведомления зависимости не отменяет эту запись. publish() строит страницу по базе заново. Не повторяй создание всего отчёта только потому, что не удалось обновить его отображение.

Локальная блокировка упорядочивает обработчики одного процесса. Проверка версии счётчика нужна отдельно: второй процесс или другой разрешённый клиент всё равно может изменить запись. Конфликт не объединяется автоматически.

Запуск

Сначала опубликуй зависимость с её описанием, затем подставь полученный ID в HELPER, dependencies и ограничение modules.call примера. ID учебной зависимости в исходнике является образцом. Он не обозначает установленный у тебя модуль.

Оба экземпляра должны быть включены. Если у зависимости несколько экземпляров, выбери нужный в настройках привязки. Полные права на базу, файлы, Telegram или сеть примеру не нужны.

Опубликуй отчёты непубличной версией и установи в отдельный тестовый юзербот. Страница появится в настройках модуля. Для кнопки нужен подключённый личный бот.

Адрес входящего запроса создаётся отдельно, чтобы установка примера сама не выпускала ключ:

endpoint = await app.requests(self.receive).create()
path = endpoint.path
headers = endpoint.headers

Это действия внутри самого модуля, например в собственном обработчике настройки. Не публикуй headers на странице и не записывай ключ в журнал.

Проверки

Автоматические сценарии находятся в tests/test_reports_example.py, tests/test_image_generator.py и tests/test_ping_example.py. Они используют отдельные базы и настоящий модульный сокет. HTTPS и Telegram в этих тестах заменены управляемыми службами.

scripts/probe_sdk_objects.py дополнительно запускает отчёты, зависимость, генератор и Ping в gVisor. Сборка генератора получает Pillow из PyPI через службу сборки Cluster. HTTPS в этой проверке настоящий, Telegram и личный бот искусственные. Рабочие профили, сессии и сообщения проверка не использует.

Нужны настроенные gVisor, Podman, образ Python из конфигурации и возможность создавать тестовое хранилище. Результаты сохраняются в переданную папку:

python scripts/probe_sdk_objects.py /tmp/cluster-sdk-results

Справочник отдельных методов находится в объектах SDK. Генерация карточек и передача PNG между модулями описаны в Image Generator.