# План: удаление адресов из очереди (точечное, массовое, полная очистка)
> Статус: **реализовано**. Актуальное описание — [docs/API.md](API.md#delete-apiv1adminipsip-post-apiv1adminipsdelete-post-apiv1adminipsclear),
> [docs/USAGE.md](USAGE.md#удаление-адресов-из-очереди),
> [docs/DASHBOARD.md](DASHBOARD.md).
## Context
Сейчас у оператора есть только два способа убрать адрес из активной
обработки — `POST /api/v1/admin/ips/{ip}/cancel` (переводит в `failed` с
`overall_result=cancelled`, но строка и вся история проверок остаются
навсегда) и косвенно `POST /api/v1/admin/ips` (принудительный повтор).
Настоящего удаления — чтобы адрес вообще пропал из очереди и его больше
никто не видел — нет. Нужно три операции: точечное удаление одного
адреса, удаление списка адресов одной командой, полная очистка очереди —
всё с поддержкой в UI дашборда.
**Согласованные решения:**
- **Удаление безвозвратно**: строка `ip_queue` и вся её история
(`checks`, `events` с этим `ip_id`) удаляются физически, без возможности
восстановления. Не путать с `cancel` — cancel сохраняет запись как
историю, delete стирает её целиком.
- **Можно удалить адрес в любом состоянии**, включая активно проверяемый
(`assigning_fip`/`awaiting_self_check`/`checking`/`aggregating`) —
удаление само выполняет то же самое, что `ForceCancel` делает для
освобождения ресурсов (отвязка FIP, освобождение валидатора), и сразу
переходит к физическому удалению строки, не задерживаясь в
промежуточном состоянии `cancelled`.
- **«Очистить список» = удалить вообще всё**, включая активные проверки —
не только `queued`/терминальные.
- **UI**: чекбоксы в таблице очереди + кнопка «Удалить выбранные» для
массового удаления списка; отдельная кнопка «Очистить всё» для полной
очистки; кнопка «Удалить» в каждой строке для точечного удаления.
## 1. База данных — `internal/db`
**Ограничение схемы**, которое определяет реализацию: `checks.ip_id`
(NOT NULL) и `events.ip_id` ссылаются на `ip_queue(id)` без `ON DELETE
CASCADE` (`internal/db/migrations/0001_init.sql`), `validators.current_ip_id`
тоже ссылается на `ip_queue(id)`. При `foreign_keys=ON` (уже включено в
`db.Open`) физическое удаление строки `ip_queue` требует явно в той же
транзакции: очистить `current_ip_id` у владеющего валидатора (если есть),
удалить связанные `checks`, удалить связанные `events` — тот же паттерн,
что уже применён в `DeleteValidator` (`internal/db/queries_validators.go`)
для `owner_validator_id`.
`internal/db/models.go`: новый тип результата массовой операции —
```go
type DeleteIPsResult struct {
Deleted []string
NotFound []string
}
```
`internal/db/queries_ipqueue.go`, новые функции:
- `DeleteIP(ctx, ipID int64) error` — одна транзакция: освобождает
владеющего валидатора (`UPDATE validators SET state=idle,
current_ip_id=NULL WHERE current_ip_id=?`), удаляет `checks`/`events`
по `ip_id`, удаляет строку `ip_queue`. `ErrNotFound`, если строки нет
(`RowsAffected==0` на финальном DELETE).
- `DeleteIPs(ctx, addresses []string) (DeleteIPsResult, error)` — одна
транзакция на весь список: по каждому адресу резолвит `id` (не найден →
в `NotFound`, не ошибка — тот же терпимый стиль, что у `SubmitIPs`),
иначе повторяет шаги `DeleteIP` для этого `id`, добавляет адрес в
`Deleted`. Используется и для точечного удаления списка, и (вызовом с
полным списком адресов из `ListIPs`) для операции «очистить всё» —
отдельная функция для «удалить всё» не нужна.
## 2. Оркестратор — `internal/orchestrator/orchestrator.go`
DB-слой не ходит в OpenStack, поэтому отвязку floating IP для адресов с
непустым `FIPID` должен делать оркестратор — по той же best-effort схеме,
что уже в `ForceCancel`/`aggregateAndRelease` (лог при ошибке, не
прерывает операцию: DB-состояние обязано освободиться в любом случае).
```go
// DeleteIP disassociates the floating IP if attached, then permanently
// removes the address and its history — differs from ForceCancel, which
// keeps a cancelled record instead of deleting it.
func (o *Orchestrator) DeleteIP(ctx context.Context, ipAddress string) error
// DeleteIPs does the same for a specific list in one call.
func (o *Orchestrator) DeleteIPs(ctx context.Context, addresses []string) (db.DeleteIPsResult, error)
// ClearQueue deletes every address currently in the queue, regardless of state.
func (o *Orchestrator) ClearQueue(ctx context.Context) (db.DeleteIPsResult, error)
```
`DeleteIP`: `GetIPByAddress` (обернуть `sql.ErrNoRows` в `db.ErrNotFound`,
как уже сделано в `ForceCancel`) → если `FIPID != ""` →
`OS.DisassociateFloatingIP` (best-effort) → `DB.DeleteIP(ctx, item.ID)`.
`DeleteIPs`: по каждому адресу — `GetIPByAddress` (не найден — пропустить,
`DB.DeleteIPs` сам отметит его в `NotFound`), если `FIPID != ""` —
отвязать; затем один вызов `DB.DeleteIPs(ctx, addresses)`.
`ClearQueue`: `DB.ListIPs` → для каждой с непустым `FIPID` отвязать →
`DB.DeleteIPs(ctx, всеАдреса)`.
Все три логируют событие (`o.event(...)`, `event_type`:
`"ip_deleted"`/`"ips_deleted"`/`"queue_cleared"`) — но пишется общесистемное
событие с `ip_id=nil` и адресами в `payload`, а не привязанное к
конкретному `ip_id`: сам IP исчезнет вместе со своими событиями этим же
вызовом, так что привязка к нему бессмысленна.
## 3. HTTP API — `internal/httpapi`
Три новых маршрута под `/api/v1/admin/ips`, по аналогии с уже
реализованными `submit`/`cancel` (`docs/API.md#управление-очередью-и-конфигурацией`):
| Метод | Путь | Тело | Успех | Ошибки |
|---|---|---|---|---|
| DELETE | `/api/v1/admin/ips/{ip}` | — | `200 {"ok":true}` | `404` неизвестный адрес |
| POST | `/api/v1/admin/ips/delete` | `{"addresses":[...]}` | `200 {"deleted":[...],"not_found":[...]}` | `400` пустой список |
| POST | `/api/v1/admin/ips/clear` | — | `200 {"deleted":[...]}` | — |
Выбор `POST .../delete` и `POST .../clear` вместо `DELETE` с телом —
чтобы не смешивать «удалить один по пути» (чистый REST) с «удалить по
списку/всё» (тело обязательно), и по аналогии с уже существующим
паттерном action-эндпоинтов (`.../cancel`). Оба пути статические
литералы — с существующим `.../ips/{ip}/cancel` не пересекаются (разное
число сегментов), с реальными IP-адресами как значением `{ip}` тоже
(слова "delete"/"clear" не бывают адресами).
Новые DTO в `internal/httpapi/dto_admin.go` (snake_case, по образцу
`submitIPsResponse`):
```go
type deleteIPsRequest struct{ Addresses []string `json:"addresses"` }
type deleteIPsResponse struct {
Deleted []string `json:"deleted"`
NotFound []string `json:"not_found"`
}
type clearQueueResponse struct{ Deleted []string `json:"deleted"` }
```
Новые хендлеры в `internal/httpapi/handlers_admin.go` (в отличие от
`handleAdminSubmitIPs`, который зовёт `s.DB` напрямую, эти три идут через
`s.Orch` — нужен `OS.DisassociateFloatingIP`):
`handleAdminDeleteIP`, `handleAdminDeleteIPs`, `handleAdminClearQueue` —
ошибки маппятся через уже существующий `writeDBError`.
`routes.go`: добавить три `mux.HandleFunc(...)` рядом с существующими
`/api/v1/admin/ips*`.
## 4. Dashboard — `internal/dashboard`
`dto.go`: `deleteIPsResponse{Deleted, NotFound []string}`,
`clearQueueResponse{Deleted []string}` — зеркало новых control-api DTO.
`client.go`: `DeleteIP(ctx, ip) error`, `DeleteIPs(ctx, addresses
[]string) (deleteIPsResponse, error)`, `ClearQueue(ctx) (clearQueueResponse,
error)` — по образцу существующих методов `CancelIP`/`SubmitIPs`.
`handlers_ips.go`, новые хендлеры (все, как и остальные мутации `/ips/*`,
безусловно перерисовывают `ips_table` через уже существующий
`renderIPsTable` — сравнение с предыдущим состоянием не нужно, таблица
после удаления просто станет короче):
- `handleIPDelete` — `DELETE /ips/{ip}` → `s.CA.DeleteIP`.
- `handleIPsDeleteSelected` — `POST /ips/delete` → парсит
`r.ParseForm()` + `r.Form["addresses"]` (чекбоксы с одинаковым
`name="addresses"` в одной форме — стандартная сериализация форм,
htmx отправит все отмеченные); пустой список → баннер `ErrValidation`-стиль
(`400`, «ничего не выбрано»), не идёт в API.
- `handleIPsClear` — `POST /ips/clear` → `s.CA.ClearQueue`, без тела.
`routes.go`: три новых маршрута рядом с существующими `/ips*`.
### Шаблоны — `templates/ips.html`
- Каждая строка таблицы получает чекбокс
``
в новой первой колонке; чекбокс в `` для «выбрать всё»
(простой инлайновый `onclick`, без Alpine — переключает `checked` у
всех `input[name=addresses]` в форме, минимальная логика, JS-фреймворк
не нужен).
- Вся таблица оборачивается в `