workerpool

type AttemptsConfig struct {
	// Count — суммарное количество попыток, включая первую.
	// При использовании River установите 1, чтобы не дублировать ретраи.
	// Должно быть >= 1.
	Count int `yaml:"count" env-default:"3"`

	// MinDelay — начальная пауза перед первой повторной попыткой.
	MinDelay time.Duration `yaml:"min_delay" env-default:"1s"`

	// MaxDelay — верхняя граница экспоненциального backoff.
	// Должно быть >= MinDelay.
	MaxDelay time.Duration `yaml:"max_delay" env-default:"30s"`
}

type Config struct {
	// WorkerCount — количество горутин в глобальном пуле исполнения.
	// Все тенанты разделяют эту ёмкость. Должно быть > 0.
	WorkerCount int `yaml:"worker_count" env-default:"256"`

	// TaskQueueSize — ёмкость канала глобального пула.
	// Задачи, поступающие при заполненном канале, отклоняются немедленно.
	// Должно быть > 0.
	TaskQueueSize int `yaml:"task_queue_size" env-default:"512"`

	// TenantQueueSize — ёмкость буфера задач каждого тенанта.
	// Устанавливается однократно при создании тенанта; не изменяется
	// при обновлении лимита воркеров. Должно быть > 0.
	TenantQueueSize int `yaml:"tenant_queue_size" env-default:"64"`

	// GracefulTimeout — максимальное время ожидания завершения активных задач
	// при вызове Stop(). По истечении таймаута все активные контексты задач
	// принудительно отменяются. Должно быть > 0.
	GracefulTimeout time.Duration `yaml:"graceful_timeout" env-default:"30s"`

	// TaskTimeout — дедлайн по умолчанию для одного выполнения задачи.
	// Вызывающий код может задать более жёсткий дедлайн через Task.Ctx.
	// Должно быть > 0.
	TaskTimeout time.Duration `yaml:"task_timeout" env-default:"5m"`

	// TenantRefreshInterval — как часто менеджер перезапрашивает список
	// тенантов у TenantProvider. Должно быть > 0.
	TenantRefreshInterval time.Duration `yaml:"tenant_refresh_interval" env-default:"30s"`

	// RetryPolicy задаёт поведение при повторных попытках выполнения задачи.
	// При использовании River как job store River управляет внешними ретраями;
	// в этом случае установите Attempts.Count = 1.
	RetryPolicy RetryPolicy `yaml:"retry_policy"`
}

type ExecutorRegistry struct {
	// contains filtered or unexported fields
}

type HealthStatus struct {
	// Healthy равен true, пока менеджер работает и не находится в процессе
	// остановки. Используйте это поле как основной сигнал живости.
	Healthy bool `json:"healthy"`

	// Stopping равен true после вызова Stop().
	Stopping bool `json:"stopping"`

	// PoolQueueDepth — количество задач, ожидающих в очереди глобального пула.
	// Значение, близкое к PoolQueueCapacity, сигнализирует о backpressure.
	PoolQueueDepth int `json:"pool_queue_depth"`

	// PoolQueueCapacity — максимальная ёмкость очереди глобального пула
	// (Config.TaskQueueSize).
	PoolQueueCapacity int `json:"pool_queue_capacity"`

	// PoolWorkerCount — количество горутин-воркеров в глобальном пуле
	// (Config.WorkerCount).
	PoolWorkerCount int `json:"pool_worker_count"`

	// TenantCount — количество тенантов, отслеживаемых менеджером на момент снимка.
	TenantCount int `json:"tenant_count"`

	// Tenants содержит детальную информацию по каждому тенанту.
	// Порядок элементов не определён.
	Tenants []TenantHealth `json:"tenants"`
}

type JitterConfig struct {
	// MinDelay — минимальная задержка jitter. Должно быть >= 0.
	MinDelay time.Duration `yaml:"min_delay" env-default:"0s"`

	// MaxDelay — максимальная задержка jitter. Должно быть >= MinDelay.
	MaxDelay time.Duration `yaml:"max_delay" env-default:"5s"`
}

type RetryPolicy struct {
	// Jitter — случайная задержка перед самым первым выполнением задачи,
	// используемая для размазывания нагрузки по кластеру.
	Jitter JitterConfig `yaml:"jitter"`

	// Attempts — параметры повторных попыток при ошибках.
	Attempts AttemptsConfig `yaml:"attempts"`
}

type Task struct {
	// Ctx — контекст задачи с дедлайном и сигналом отмены.
	// Если Ctx содержит активный OTel-span (например, из River worker или
	// HTTP-обработчика), span пула станет его дочерним — иерархия
	// трассировки выстраивается автоматически через контекст.
	Ctx context.Context //nolint:containedctx // Task is a data envelope passed by value through channels, not a long-lived object; ctx must travel with it

	// TaskID — уникальный идентификатор конкретного запуска
	// (например, ID job в River). Используется в логах и атрибутах span.
	TaskID uuid.UUID

	// TenantID — идентификатор тенанта; используется для маршрутизации,
	// логирования и атрибутов метрик.
	TenantID uuid.UUID

	// ExecutorKey — строковый ключ для разрешения executor'а через
	// ExecutorRegistry. Заполняется, если executor хранится в реестре
	// (типичный случай при использовании River как job store).
	ExecutorKey string

	// Executor — реализация, вызываемая напрямую. Имеет приоритет над
	// ExecutorKey. Удобна для разовых задач без регистрации в реестре.
	Executor TaskExecutor

	// Complete вызывается ровно один раз после завершения задачи —
	// успешного, после исчерпания повторных попыток, после паники или
	// при остановке диспетчера. err == nil означает успех.
	Complete func(err error)
}

type TaskExecutor interface {
	// Execute выполняет работу. Не-nil ошибка инициирует повторную попытку
	// согласно RetryPolicy пула. workerID идентифицирует слот глобального
	// пула, исполняющий задачу (начинается с 0).
	Execute(ctx context.Context, tenantID uuid.UUID, workerID int) error
}

type Tenant interface {
	// ID возвращает уникальный идентификатор тенанта. Никогда не должен
	// возвращать uuid.Nil.
	ID() uuid.UUID

	// WorkerLimit возвращает максимальное количество одновременно
	// выполняемых задач для этого тенанта. Изменение значения вступает в силу
	// на следующем цикле обновления.
	WorkerLimit() int
}

type TenantHealth struct {
	// TenantID — идентификатор тенанта.
	TenantID uuid.UUID `json:"tenant_id"`

	// QueueDepth — количество задач, ожидающих в локальном буфере тенанта.
	// Значение, близкое к QueueCapacity, означает, что SubmitTask начнёт
	// возвращать ошибку «очередь заполнена» для этого тенанта.
	QueueDepth int `json:"queue_depth"`

	// QueueCapacity — полная ёмкость буфера задач тенанта
	// (Config.TenantQueueSize).
	QueueCapacity int `json:"queue_capacity"`

	// WorkerLimit — максимальное количество одновременных задач тенанта
	// согласно последнему ответу TenantProvider.
	WorkerLimit int `json:"worker_limit"`
}

type TenantProvider interface {
	// List возвращает всех тенантов, которым должны быть назначены
	// воркеры. Тенант, отсутствующий в результате, будет удалён из
	// внутреннего состояния менеджера.
	List(ctx context.Context) ([]Tenant, error)
}

type WorkerManager struct {
	// contains filtered or unexported fields
}

type WorkerManagerParams struct {
	// TenantProvider поставляет список тенантов, которым нужны воркеры.
	TenantProvider TenantProvider

	// Config содержит все настраиваемые параметры. Config.Validate()
	// вызывается внутри NewWorkerManager — передавать невалидный конфиг
	// не нужно.
	Config Config

	// ExecutorRegistry, если задан, используется SubmitTask для разрешения
	// Task.ExecutorKey в Task.Executor у задач, которые не заполнили
	// Executor напрямую. Опционально: если задачи всегда приходят с уже
	// заполненным Executor, оставьте nil.
	ExecutorRegistry *ExecutorRegistry

	// Logger используется менеджером и внутренним пулом (с добавленным
	// атрибутом component). Опционально: если не задан, используется
	// slog.Default().
	Logger *slog.Logger
}