Перейти к содержанию

Workers

Описание секции workers для фоновых воркеров.

Секция workers

Конфигурация фоновых воркеров.

workers:
  - name: notification_bot
    generator_type: telegram

  - name: background_processor
    generator_type: daemon

Поля

Поле Обязательно Описание
name Да Имя воркера
generator_type Да Тип генератора: telegram или daemon
generator_template Нет Имя кастомного шаблона

Типы воркеров

Telegram Bot

Telegram бот с поддержкой webhooks и polling.

workers:
  - name: notification_bot
    generator_type: telegram

Генерируемые обработчики

Событие Handler Назначение
PreCheckoutQuery PreCheckout Валидация платежа
SuccessfulPayment Purchase Обработка платежа
CallbackQuery CallbackQuery Callback от кнопок
Message TextMessage Обработка текста/команд

Генерируемая структура

internal/app/{app}/worker/telegram/{worker_name}/
├── router.go         # Маршрутизация событий
├── handler/
│   └── handler.go    # Обработчики (ваш код)
└── commands/
    └── commands.go   # Команды бота

Точки расширения: customize()

Сгенерированный воркер правится только ниже маркера «add your code after this message», но кое-что проекту нужно поменять внутри сгенерированного Run(), роутера и реестра команд. Всё это делается из одного места — метода customize(), который Create() зовёт на свежесконструированном воркере, до Init и Run.

По умолчанию customize() промотирован из встроенного EmptyCustomizer и ничего не делает. Проект объявляет свой — метод на *Worker перекрывает промотированный:

// internal/app/worker/telegrambot/dispatch.go — ваш файл в пакете воркера
func (w *Worker) customize() {
    // Свои команды — в реестр воркера
    w.AddCommands(
        telegram.Cmd{
            Name:    CmdHelp,
            Private: true,
            Handler: func(ctx context.Context, h any, params string) (telegram.Response, error) {
                return h.(*handler.Handler).Help(ctx, params)
            },
        },
    )

    // Хуки пакета — здесь же
    updateHandler = (*Worker).dispatchUpdate
    updateHandlerIdle = updatesIdle
    unknownCommandHandler = func(ctx context.Context, w *Worker, rd telegram.RequestData) {
        w.clearStaleDialogState(ctx, rd.Actor.ID)
    }
}

Файл может быть и своим файлом пакета, и секцией ниже disclaimer-маркера в psg_telegram_gen.go — regenerate эту правку не трогает.

Команды. Реестр команд — поле воркера (w.cmds), а не package-global cmdMaps, наполняемый из init(): порядок инициализации пакетов на него не влияет, и два воркера в одном процессе не делят один набор команд. Команды генератора (generatedCommands() в psg_const_gen.go) Create() добавляет первыми, затем зовёт customize() — команда проекта с тем же Name перекрывает сгенерированную.

Хуки пакета. Переназначаются из customize(), не из init(): в сгенерированных проектах init() запрещён линтером (gochecknoinits).

Хук По умолчанию Зачем переназначать
updateHandler = (*Worker).handleUpdate лог апдейта, JobStarter, разбор его ошибок — апдейты строго по одному разложить апдейты по очередям (например, по автору), чтобы одна долгая команда не держала всех пользователей
updateHandlerIdle = func() bool { return true } GracefulStop ждёт только пустой канал апдейтов дождаться, пока переназначенный обработчик закончит начатое
unknownCommandHandler = func(ctx, w, rd) {} неизвестная команда только логируется сбросить состояние диалога пользователя, чтобы старая кнопка не оставила его на полушаге

Обработчик по умолчанию пишет в лог апдейт целиком; если в сообщениях бота бывают секреты (токены, пароли), переназначенный обработчик должен логировать только updateID. JobStarter для неподдержанных типов апдейта пишет в лог только updateID и тип.

Проекты, зарегистрированные до появления customize(), наполняли cmdMaps из своего init(). Миграция — в DEPRECATION.md.

Daemon

Фоновый демон для периодических задач.

workers:
  - name: background_processor
    generator_type: daemon

Генерируемая структура

internal/app/{app}/worker/daemon/{worker_name}/
├── worker.go         # Основной воркер
└── handler/
    └── handler.go    # Логика обработки (ваш код)

Подключение воркеров к приложению

Воркеры подключаются через секцию applications:

workers:
  - name: notification_bot
    generator_type: telegram

  - name: background_processor
    generator_type: daemon

applications:
  # Выделенный воркер instance
  - name: worker
    workers: [notification_bot, background_processor]
    transport: [sys]  # Системные endpoints для метрик

  # Или комбинированное приложение
  - name: monolith
    transport: [api, sys]
    workers: [notification_bot]

Жизненный цикл воркера

┌────────────────────────────────────────────┐
│                ИНИЦИАЛИЗАЦИЯ                │
│  1. Создание воркера                        │
│  2. Инициализация зависимостей              │
└────────────────────────────────────────────┘
                      │
                      ▼
┌────────────────────────────────────────────┐
│                   ЗАПУСК                    │
│  1. Запуск в отдельной горутине            │
│  2. Telegram: подключение к API            │
│  3. Daemon: запуск цикла обработки         │
└────────────────────────────────────────────┘
                      │
                      ▼
┌────────────────────────────────────────────┐
│                  РАБОТА                     │
│  - Telegram: обработка событий от бота     │
│  - Daemon: выполнение периодических задач  │
└────────────────────────────────────────────┘
                      │
                      ▼
┌────────────────────────────────────────────┐
│                ЗАВЕРШЕНИЕ                   │
│  1. Graceful shutdown                       │
│  2. Завершение текущих операций            │
│  3. Освобождение ресурсов                  │
└────────────────────────────────────────────┘

Конфигурация через OnlineConf

Telegram Bot

Путь Описание
{service}/worker/telegram/{name}/token Bot token
{service}/worker/telegram/{name}/webhook_url Webhook URL (опционально)

Daemon

Путь Описание
{service}/worker/daemon/{name}/interval Интервал выполнения
{service}/worker/daemon/{name}/enabled Включен/выключен

Конфигурация таймеров daemon worker через переменные окружения

Два таймера внутреннего цикла daemon worker'а можно переопределить через env vars (полезно для goat-тестов и проектов с use_envs: true). Если переменная не задана или не парсится, используется дефолт.

Env var Дефолт Описание
WORKER_{NAME}_NEW_CYCLE_TIMEOUT 10s Пауза между итерациями цикла, когда GetTasks вернул nil
WORKER_{NAME}_ERROR_TIMEOUT 10s Пауза после ошибки в GetTasks

{NAME} — имя воркера в верхнем регистре. Значение должно парситься через time.ParseDuration (например, 500ms, 1m30s).

Пример: для воркера с именем supervisor ускорить goat-тесты можно так:

envVars["WORKER_SUPERVISOR_NEW_CYCLE_TIMEOUT"] = "200ms"

Пример полной конфигурации

main:
  name: notification-service
  logger: zerolog

git:
  repo: github.com/myorg/notification-service
  module_path: github.com/myorg/notification-service

rest:
  - name: sys
    generator_type: template
    generator_template: sys
    port: 9090
    version: v1

workers:
  - name: telegram_bot
    generator_type: telegram

  - name: email_sender
    generator_type: daemon

drivers:
  - name: telegram
    import: pkg/drivers/telegram
    package: telegram
    obj_name: TelegramDriver

applications:
  - name: notifier
    workers: [telegram_bot, email_sender]
    transport: [sys]
    driver: [telegram]