docs: add per-job timeout implementation plan
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
mixeme
@@ -0,0 +1,154 @@
|
||||
# План реализации: Per-job command timeout
|
||||
|
||||
Реализация пункта **«Per-job command timeout»** из [ROADMAP.md](../ROADMAP.md),
|
||||
построенная по образцу уже реализованного `overlap_policy` — тот же паттерн
|
||||
наследования «пусто → глобальный дефолт».
|
||||
|
||||
## Рекомендуемая модель
|
||||
|
||||
**Claude Opus** (Opus 4.8 или новее).
|
||||
|
||||
Обоснование: это не локальная правка, а сквозное изменение через слои
|
||||
(`domain → storage → runner → app seam → ui → tests`) со сменой сигнатуры
|
||||
`RunJob` и seam-типа `Service.runJob`, что затрагивает ~9 существующих тестов и
|
||||
несколько UI-файлов. Нужна аккуратность в резолве эффективного значения под
|
||||
`mu` и в сохранении контракта «раннер не знает о глобальном конфиге». Для такой
|
||||
кросс-слойной работы с тестами уместен Opus; Sonnet справится с отдельными
|
||||
шагами, но выше риск упустить обновление одного из вызовов/тестов.
|
||||
|
||||
Замечание по окружению: сборка и тесты GUI требуют **CGO + MSYS2 UCRT64**
|
||||
(дефолтный Bash-env идёт с `cgo off`).
|
||||
|
||||
---
|
||||
|
||||
## Модель данных
|
||||
|
||||
**[src/domain/job.go](../../src/domain/job.go)** — добавить поле в `Job`:
|
||||
|
||||
```go
|
||||
TimeoutSeconds int `json:"timeout_seconds,omitempty"` // 0 = наследовать глобальный дефолт
|
||||
```
|
||||
|
||||
**[src/domain/config.go](../../src/domain/config.go)** — добавить в `Config`:
|
||||
|
||||
```go
|
||||
DefaultTimeoutSeconds int `json:"default_timeout_seconds,omitempty"`
|
||||
```
|
||||
|
||||
Ключевое соглашение (как у `OverlapPolicy`): `0` на `Job` означает
|
||||
«наследовать», поэтому `normalizeJob` не должен затирать 0 глобальным значением.
|
||||
|
||||
## Дефолты и загрузка
|
||||
|
||||
**[src/storage/store.go](../../src/storage/store.go)** — по образцу `OverlapPolicy`:
|
||||
|
||||
- в литерал дефолтного `Config` добавить `DefaultTimeoutSeconds: 30`
|
||||
(сохраняет текущее поведение — 30 с);
|
||||
- в блоке нормализации после загрузки:
|
||||
`if config.DefaultTimeoutSeconds <= 0 { config.DefaultTimeoutSeconds = 30 }`.
|
||||
|
||||
Это переносит нынешнюю константу `commandTimeout = 30s` из `runner.go` в конфиг
|
||||
как значение по умолчанию.
|
||||
|
||||
## Runner (сохранить чистоту контракта)
|
||||
|
||||
Раннер не должен знать о глобальном конфиге — эффективный таймаут резолвится в
|
||||
app-слое и передаётся внутрь.
|
||||
|
||||
**[src/runner/runner.go](../../src/runner/runner.go)**:
|
||||
|
||||
- сигнатура `RunJob(ctx, job, trigger, logsDir)` →
|
||||
`RunJob(ctx, job, trigger, logsDir, timeout time.Duration)`;
|
||||
- `runCtx, cancel := context.WithTimeout(ctx, timeout)` вместо константы;
|
||||
- `runStateDetail(...)` принимает `timeout` и печатает его в сообщении
|
||||
`"Timed out after %s"` вместо `commandTimeout`;
|
||||
- **StartOnly не трогаем**: эта ветка использует `jobInvocation(ctx, …)`
|
||||
(не `runCtx`), поэтому run-таймаут её не касается — измерение launch latency
|
||||
сохраняется. Константу `commandTimeout` можно удалить, `commandWaitDelay`
|
||||
оставить.
|
||||
|
||||
## App-слой: резолв и проброс
|
||||
|
||||
**[src/app/run.go](../../src/app/run.go)** — добавить рядом с
|
||||
`effectiveOverlapPolicy`:
|
||||
|
||||
```go
|
||||
func (s *Service) effectiveTimeout(job *domain.Job) time.Duration {
|
||||
secs := job.TimeoutSeconds
|
||||
if secs <= 0 {
|
||||
secs = s.store.Config.DefaultTimeoutSeconds
|
||||
}
|
||||
return time.Duration(secs) * time.Second
|
||||
}
|
||||
```
|
||||
|
||||
Резолвить под `mu` в `startRunLocked` и класть в снапшот `runEnv` (там же, где
|
||||
`logsDir`/`maxFiles`) — новое поле `timeout time.Duration`. В `executeRun`
|
||||
передавать `env.timeout` в `s.runJob(...)`.
|
||||
|
||||
**[src/app/service.go](../../src/app/service.go)** — обновить тип seam-поля
|
||||
`runJob` (добавить `timeout time.Duration`); присваивание
|
||||
`runJob: runner.RunJob` останется валидным после смены сигнатуры.
|
||||
|
||||
## Валидация
|
||||
|
||||
**[src/app/operations.go](../../src/app/operations.go)**:
|
||||
|
||||
- `validateJob`:
|
||||
`if job.TimeoutSeconds < 0 { return errors.New("timeout must be zero (inherit) or a positive number of seconds") }`;
|
||||
- `validateConfig`:
|
||||
`if config.DefaultTimeoutSeconds <= 0 { return errors.New("default timeout must be a positive number of seconds") }`.
|
||||
|
||||
## UI
|
||||
|
||||
**Диалог задачи [src/ui/job_dialog.go](../../src/ui/job_dialog.go)** — рядом с
|
||||
«Overlap policy»: числовой `widget.NewEntry` «Timeout (s)» с плейсхолдером-
|
||||
подсказкой про наследование; пусто → `TimeoutSeconds = 0`, иначе `strconv.Atoi`
|
||||
с показом ошибки как у schedule.
|
||||
|
||||
**Настройки [src/ui/settings_view.go](../../src/ui/settings_view.go)** — в секцию
|
||||
«Queue» добавить поле «Default timeout (s)» рядом с «Default overlap policy»:
|
||||
инициализация из `store.Config.DefaultTimeoutSeconds`,
|
||||
`OnChanged → updateSaveState`, запись в `config.DefaultTimeoutSeconds` при
|
||||
сохранении и учёт в dirty-check.
|
||||
|
||||
**Панель деталей [src/ui/jobs_view_details.go](../../src/ui/jobs_view_details.go)**
|
||||
— новая строка «Timeout», отображающая эффективное значение через новый хелпер
|
||||
в [src/app/format.go](../../src/app/format.go):
|
||||
|
||||
```go
|
||||
func DisplayTimeout(job domain.Job, globalDefault int) string // "45 s" или "30 s (global default)"
|
||||
```
|
||||
|
||||
по образцу `DisplayOverlapPolicy`. Прокинуть `globalDefault` в
|
||||
`newDetailsPanel/update` так же, как уже прокинут `globalOverlapPolicy`.
|
||||
|
||||
## Тесты
|
||||
|
||||
- **[src/runner/runner_test.go](../../src/runner/runner_test.go)** — все 9 вызовов
|
||||
`RunJob` получают новый аргумент; добавить кейс: короткий per-job таймаут →
|
||||
`Failed / Timed out after …`; StartOnly с малым таймаутом → не таймаутит.
|
||||
- **[src/app/run_test.go](../../src/app/run_test.go)** — тест `effectiveTimeout`:
|
||||
инхерит при `TimeoutSeconds==0`, собственное значение перекрывает глобальное.
|
||||
- **[src/app/operations_test.go](../../src/app/operations_test.go)** —
|
||||
отрицательный per-job timeout и неположительный default отклоняются.
|
||||
- **[src/app/format_test.go](../../src/app/format_test.go)** — `DisplayTimeout`
|
||||
(собственное значение vs «(global default)»).
|
||||
- **settings / mainwindow тесты** — при необходимости обновить конструкторы
|
||||
`Config`.
|
||||
|
||||
## Документация
|
||||
|
||||
- Удалить раздел из [ROADMAP.md](../ROADMAP.md).
|
||||
- Обновить упоминания сигнатуры/таймаута `RunJob` в
|
||||
[ARCHITECTURE.md](../ARCHITECTURE.md).
|
||||
- Запись в [CHANGELOG.md](../CHANGELOG.md).
|
||||
|
||||
## Порядок работ
|
||||
|
||||
1. `domain` → storage-дефолты (компилируется, поведение прежнее);
|
||||
2. `runner` + seam-сигнатура + прогон таймаута через `runEnv` → чиним
|
||||
компиляцию тестов;
|
||||
3. валидация;
|
||||
4. UI (диалог, настройки, детали);
|
||||
5. тесты + доки.
|
||||
Reference in New Issue
Block a user