Add Floating IP scanning and a durable address registry with configurable history depth

Adds POST /api/v1/admin/ips/scan (plus an optional periodic ticker) to discover free Floating IPs in the OpenStack project and feed them straight into the check queue. More importantly, decouples check/event history from ip_queue's lifecycle: a new ip_registry table (migration 0007) gives every address ever submitted a durable identity, so deleting it from the queue no longer destroys its history — it's still reachable via the new GET /api/v1/admin/registry[/{ip}] endpoints and the dashboard's /registry pages, with retention depth configurable in check cycles per address (history_retention_cycles, 0 = unlimited). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-23 09:52:01 +03:00
1 parent 78b20fa5be
commit 582b44f314
@@ -28,6 +28,7 @@ JSON, базовый префикс прикладных методов — `/ap
 - [Методы для prober](#методы-для-prober)
 - [Служебные и административные методы](#служебные-и-административные-методы)
 - [Управление очередью и конфигурацией](#управление-очередью-и-конфигурацией)
+- [Реестр адресов и история проверок](#реестр-адресов-и-история-проверок)
 - [Модель состояний и связь методов с ней](#модель-состояний-и-связь-методов-с-ней)
 - [Сквозной пример работы (curl)](#сквозной-пример-работы-curl)

@@ -416,12 +417,18 @@ YAML для этой секции больше не перечитывается

 ### `DELETE /api/v1/admin/ips/{ip}`, `POST /api/v1/admin/ips/delete`, `POST /api/v1/admin/ips/clear`

-**Безвозвратное удаление**, в отличие от `cancel` выше: строка `ip_queue`
-и вся её история (`checks`, `events`) стираются физически, без возможности
-восстановления. Работает из любого состояния, включая активно
-проверяемое — если Floating IP привязан, он отвязывается тем же
-best-effort способом, что и при `cancel`/обычном завершении, владеющий
-валидатор освобождается.
+Удаляет строку `ip_queue` — адрес пропадает из очереди/`GET
+/api/v1/admin/ips*` — безвозвратно, без возможности восстановить именно
+эту строку. Работает из любого состояния, включая активно проверяемое —
+если Floating IP привязан, он отвязывается тем же best-effort способом,
+что и при `cancel`/обычном завершении, владеющий валидатор освобождается.
+
+**Накопленная история адреса при этом не теряется**: `checks`/`events`
+остаются в реестре (`ip_registry`, см. раздел [«Реестр
+адресов»](#реестр-адресов-и-история-проверок) ниже) и доступны через `GET
+/api/v1/admin/registry/{ip}` даже после удаления строки из очереди — в
+отличие от `ip_queue`, реестровая запись никогда не удаляется этими
+методами.

 | Метод | Путь | Тело | Успех | Ошибки |
 |---|---|---|---|---|
@@ -433,7 +440,95 @@ best-effort способом, что и при `cancel`/обычном заве
 идут в `not_found`, не ошибка — тот же терпимый стиль, что у `POST
 /api/v1/admin/ips`). `POST .../clear` удаляет **вообще всё**, что сейчас в
 очереди, включая адреса в процессе проверки — самая опасная операция
-этого API, используйте с осторожностью.
+этого API, используйте с осторожностью (и, опять же, ничья история при
+этом физически не стирается — см. выше).
+
+### `POST /api/v1/admin/ips/scan`
+
+Сканирует текущий проект OpenStack на предмет свободных (не привязанных ни
+к одному порту) Floating IP и сразу передаёт найденный список в `POST
+/api/v1/admin/ips` — тот же add/requeue/reorder-вызов, как если бы
+оператор ввёл эти адреса вручную. Не принимает тело запроса.
+
+Ответ (`200`):
+```json
+{
+  "scanned_free": 3,
+  "added": ["203.0.113.20"],
+  "requeued": [],
+  "reordered": ["203.0.113.10", "203.0.113.11"],
+  "skipped_in_progress": []
+}
+```
+
+`scanned_free` — сколько свободных Floating IP нашлось в проекте всего
+(включая уже стоящие в очереди — они попадут в `reordered`, а не
+`added`). Если свободных адресов нет вообще, это не ошибка: ответ будет
+`{"scanned_free": 0, "added": [], ...}`.
+
+Помимо ручного вызова, сканирование можно включить по расписанию —
+`orchestrator.fip_scan_interval_seconds` в `control-api.yaml` (0, по
+умолчанию, — только по запросу через эту ручку или кнопку «Сканировать
+Floating IP» в дашборде).
+
+## Реестр адресов и история проверок
+
+В отличие от `ip_queue` (текущая рабочая очередь, см. выше), реестр —
+`ip_registry` — это накопительная запись **обо всех адресах, когда-либо
+поставленных на проверку**, вне зависимости от того, стоят ли они сейчас в
+очереди. Запись в реестре переживает удаление адреса из `ip_queue` (`DELETE
+/api/v1/admin/ips/{ip}` и т.п.) и повторное добавление того же адреса
+позже — обе истории (до и после) остаются доступны и не перекрывают друг
+друга (каждой постановке на проверку соответствует свой `cycle_id`,
+уникальный в пределах адреса на всё время).
+
+### `GET /api/v1/admin/registry`
+
+Список всех адресов реестра с краткой сводкой по каждому.
+
+```json
+[
+  {
+    "ip_address": "203.0.113.10",
+    "first_seen_at": "2026-01-10T12:00:00Z",
+    "last_seen_at": "2026-02-01T09:00:00Z",
+    "total_cycles": 4,
+    "last_result": "pass",
+    "last_checked_at": "2026-02-01T09:05:00Z",
+    "in_queue": true,
+    "current_state": "done"
+  }
+]
+```
+
+`in_queue`/`current_state` отражают, есть ли у адреса сейчас живая строка в
+`ip_queue`, а не только в реестре.
+
+### `GET /api/v1/admin/registry/{ip}`
+
+Реестровая запись по одному адресу плюс вся сохранённая история проверок
+по нему, по всем циклам (не только текущему — в отличие от `GET
+/api/v1/admin/ips/{ip}`, который отдаёт проверки только текущей попытки).
+Порядок — от новых циклов к старым.
+
+```json
+{
+  "registry": { "ip_address": "203.0.113.10", "total_cycles": 4, "...": "..." },
+  "checks": [
+    {"CycleID": 4, "Source": "egress", "CheckType": "https", "Success": true, "...": "..."},
+    {"CycleID": 3, "Source": "egress", "CheckType": "https", "Success": false, "...": "..."}
+  ]
+}
+```
+
+`404`, если адрес никогда не ставился на проверку.
+
+**Глубина хранения.** Сколько последних циклов на адрес хранится в
+`checks` (и синхронно — в `events`), управляется полем
+`history_retention_cycles` в `GET`/`PUT /api/v1/admin/config/orchestrator`
+(0, по умолчанию, — без ограничения). Сама реестровая запись (`ip_address`,
+`first_seen_at`, счётчик циклов) не удаляется никогда, независимо от этой
+настройки — она лишь ограничивает глубину детальной истории проверок.

 ```bash
 curl -s -X DELETE "$BASE/api/v1/admin/ips/203.0.113.10"
@@ -497,25 +592,33 @@ curl -s -X POST "$BASE/api/v1/admin/ips/clear"

 ### Настройки оркестратора: `/api/v1/admin/config/orchestrator`

-Единственный на сегодня параметр — `fip_settle_seconds`: пауза между
-привязкой Floating IP к валидатору и моментом, когда self-check по этому
-адресу становится доступен агенту (`GET
-/api/v1/agents/{id}/assignment` до истечения паузы отдаёт `204`, как если
-бы валидатору просто нечего было делать — никаких изменений в протоколе
-агента). Нужна, чтобы дать data plane OpenStack время реально начать
-пропускать трафик через только что привязанный адрес, прежде чем
-запускать по нему проверки. `0` — без паузы (поведение по умолчанию, как
-до появления этого параметра).
+Два параметра:
+
+- `fip_settle_seconds` — пауза между привязкой Floating IP к валидатору и
+  моментом, когда self-check по этому адресу становится доступен агенту
+  (`GET /api/v1/agents/{id}/assignment` до истечения паузы отдаёт `204`,
+  как если бы валидатору просто нечего было делать — никаких изменений в
+  протоколе агента). Нужна, чтобы дать data plane OpenStack время реально
+  начать пропускать трафик через только что привязанный адрес, прежде чем
+  запускать по нему проверки. `0` — без паузы (поведение по умолчанию, как
+  до появления этого параметра).
+- `history_retention_cycles` — сколько последних циклов проверки хранить
+  на адрес в реестре (`GET /api/v1/admin/registry/{ip}`, см.
+  [«Реестр адресов»](#реестр-адресов-и-история-проверок)). `0` — без
+  ограничения (поведение по умолчанию).

 | Метод | Путь | Тело | Успех | Ошибки |
 |---|---|---|---|---|
-| GET | `/api/v1/admin/config/orchestrator` | — | `{"fip_settle_seconds":N}` | |
-| PUT | `/api/v1/admin/config/orchestrator` | `{"fip_settle_seconds":N}` | `200` | `400`, если `N < 0`, или если `fip_settle_seconds + self_check_timeout_seconds >= lease_ttl_seconds` (пауза не должна съедать весь лизинг адреса — иначе self-check не успеет пройти до истечения `lease_ttl_seconds`, и адрес будет вечно возвращаться в очередь) |
+| GET | `/api/v1/admin/config/orchestrator` | — | `{"fip_settle_seconds":N,"history_retention_cycles":M}` | |
+| PUT | `/api/v1/admin/config/orchestrator` | `{"fip_settle_seconds":N,"history_retention_cycles":M}` | `200` | `400`, если `N < 0` или `M < 0`, или если `fip_settle_seconds + self_check_timeout_seconds >= lease_ttl_seconds` (пауза не должна съедать весь лизинг адреса — иначе self-check не успеет пройти до истечения `lease_ttl_seconds`, и адрес будет вечно возвращаться в очередь) |

 Как и остальные разделы этой группы, YAML-поле `orchestrator.
 fip_settle_seconds` в `control-api.yaml` — только одноразовый bootstrap
 для пустой БД; дальше источник истины — сама база, менять значение нужно
 через `PUT` выше (или страницу `/settings` в дашборде).
+`history_retention_cycles` не имеет YAML-эквивалента вообще — управляется
+только через `PUT` выше/дашборд, значение по умолчанию `0` всегда
+применяется на пустой БД.

 ### Типы проверок пробера: `/api/v1/admin/config/inbound-checks`

@@ -633,12 +736,15 @@ queued ──(control-api сам, без вызова API)──▶ assigning_fi
  "cancelled"`)** — `POST /api/v1/admin/ips/{ip}/cancel`;
 - **`done`/`failed`/`occupied` → `queued` (новая попытка)** — `POST
  /api/v1/admin/ips` с уже завершённым (или занятым) адресом в списке;
- **любое состояние → адрес физически исчезает из очереди**, вместе со
-  всей историей — `DELETE /api/v1/admin/ips/{ip}`, `POST
-  /api/v1/admin/ips/delete`, `POST /api/v1/admin/ips/clear` (см.
+- **любое состояние → адрес физически исчезает из очереди** — `DELETE
+  /api/v1/admin/ips/{ip}`, `POST /api/v1/admin/ips/delete`, `POST
+  /api/v1/admin/ips/clear` (см.
  [выше](#delete-apiv1adminipsip-post-apiv1adminipsdelete-post-apiv1adminipsclear)).
  Не путать с cancel — cancel сохраняет запись как историю (`failed`/
-  `cancelled`), delete стирает её целиком без возможности восстановления.
+  `cancelled`) прямо в `ip_queue`; delete убирает саму строку `ip_queue`
+  безвозвратно, но накопленная история проверок остаётся в реестре (`GET
+  /api/v1/admin/registry/{ip}`) — см.
+  [«Реестр адресов»](#реестр-адресов-и-история-проверок).

 ## Сквозной пример работы (curl)

@@ -49,13 +49,15 @@ admin-dashboard -config /etc/cloud-ip-validator/admin-dashboard.yaml
 | Страница | Назначение |
 |---|---|
 | `/overview` | Сводная статистика: счётчики по состояниям, «текущая проверка» (live-снимок всех IP не в терминальном состоянии) и «последние N завершённых» (по умолчанию 20, `overview.last_completed_count`) с разбивкой pass/partial/fail/cancelled. Обновляется каждые `overview.poll_interval_seconds` секунд без перезагрузки страницы. |
-| `/ips` | Полная очередь. Форма сверху принимает список адресов (по одному на строке или через запятую) и отправляет их в `POST /api/v1/admin/ips` — **один и тот же вызов** добавляет новые адреса и принудительно перезапускает уже завершённые (см. ниже). У каждого адреса — кнопка «Перепроверить» (для `done`/`failed`) или «Отменить» (для активных состояний), и всегда — «Удалить» (безвозвратно, в отличие от «Отменить», см. ниже). Чекбоксы у строк + кнопка «Удалить выбранные» удаляют список одним вызовом; «Очистить всё» удаляет вообще всё, включая активные проверки — обе операции требуют явного подтверждения. Пока не истекла настроенная на `/settings` пауза (`fip_settle_seconds`), только что привязавший Floating IP адрес показывает отдельный бейдж «прогрев FIP» вместо обычного статуса. Если на момент попытки привязки Floating IP оказался уже занят другим портом (дрейф состояния облака или ошибочно переданный адрес), цикл проверки для него не запускается — адрес показывает отдельный бейдж «занят» (отличный от «fail») и строку `fip_occupied` в списке событий на его странице; кнопка «Перепроверить» ставит его в очередь заново. |
-| `/ips/{ip}` | Детали одного адреса: все проверки текущей попытки и вся история событий. |
+| `/ips` | Полная очередь. Форма сверху принимает список адресов (по одному на строке или через запятую) и отправляет их в `POST /api/v1/admin/ips` — **один и тот же вызов** добавляет новые адреса и принудительно перезапускает уже завершённые (см. ниже). Кнопка «Сканировать Floating IP» делает то же самое автоматически: находит в проекте OpenStack все свободные (не привязанные к порту) Floating IP и сразу ставит их в очередь (`POST /api/v1/admin/ips/scan`, см. [API.md](API.md#post-apiv1adminipsscan)) — то же сканирование можно включить по расписанию через `orchestrator.fip_scan_interval_seconds`. У каждого адреса — кнопка «Перепроверить» (для `done`/`failed`) или «Отменить» (для активных состояний), и всегда — «Удалить» (безвозвратно убирает адрес из очереди, но не из реестра — см. ниже). Чекбоксы у строк + кнопка «Удалить выбранные» удаляют список одним вызовом; «Очистить всё» удаляет вообще всё, включая активные проверки — обе операции требуют явного подтверждения. Пока не истекла настроенная на `/settings` пауза (`fip_settle_seconds`), только что привязавший Floating IP адрес показывает отдельный бейдж «прогрев FIP» вместо обычного статуса. Если на момент попытки привязки Floating IP оказался уже занят другим портом (дрейф состояния облака или ошибочно переданный адрес), цикл проверки для него не запускается — адрес показывает отдельный бейдж «занят» (отличный от «fail») и строку `fip_occupied` в списке событий на его странице; кнопка «Перепроверить» ставит его в очередь заново. |
+| `/ips/{ip}` | Детали одного адреса, пока он в очереди: все проверки текущей попытки и вся история событий, плюс ссылка на полную историю в реестре (см. ниже). |
+| `/registry` | **Реестр** — все адреса, когда-либо поставленные на проверку, независимо от того, стоят ли они сейчас в очереди. Переживает удаление адреса из `/ips` и повторное добавление того же адреса позже (см. «Реестр адресов» ниже). |
+| `/registry/{ip}` | Полная сохранённая история проверок одного адреса по всем циклам (не только текущему) — в отличие от `/ips/{ip}`, которая показывает только текущую попытку. |
 | `/validators` | Список валидаторов + создание/изменение `os_port_id`/удаление. |
 | `/sites` | Площадки — число слотов не ограничено, форма сверху добавляет новый слот, назначить/сменить/освободить `site_id` в каждой строке; колонка «Статус» показывает бейдж подключения пробера (`unregistered`/`idle`/`unreachable`, по аналогии с `/validators`), см. [USAGE.md](USAGE.md#состояния-площадки). |
 | `/targets` | Группы целей для egress-проверок — создание/редактирование/удаление. |
 | `/check-types` | Типы проверок (`https`/`icmp`/`ssh`/...), включение/выключение, привязка к группам целей. |
-| `/settings` | Две формы: `fip_settle_seconds` — пауза (в секундах) между привязкой Floating IP и началом self-check («прогрев» дата-плейна OpenStack, см. [USAGE.md](USAGE.md#пауза-перед-self-check-fip_settle_seconds)); и типы проверок пробера — TCP-порты (через запятую) + чекбокс ICMP, общие для всех площадок (см. [USAGE.md](USAGE.md#управление-типами-проверок-пробера)). |
+| `/settings` | Три формы: `fip_settle_seconds` — пауза (в секундах) между привязкой Floating IP и началом self-check («прогрев» дата-плейна OpenStack, см. [USAGE.md](USAGE.md#пауза-перед-self-check-fip_settle_seconds)); `history_retention_cycles` — сколько последних циклов проверки хранить на адрес в реестре (0 — без ограничения); и типы проверок пробера — TCP-порты (через запятую) + чекбокс ICMP, общие для всех площадок (см. [USAGE.md](USAGE.md#управление-типами-проверок-пробера)). |

 ### «Текущая» и «последняя завершённая» проверка

@@ -83,20 +85,38 @@ admin-dashboard -config /etc/cloud-ip-validator/admin-dashboard.yaml
 (дашборд честно показывает это в таблице, а не делает вид, что запрос
 ничего не значил).

-### Удаление адресов — безвозвратно, в отличие от «Отменить»
+### Удаление адресов — безвозвратно из очереди, но не из реестра

 «Отменить» (`POST .../cancel`) останавливает проверку, но сохраняет
 адрес и его историю как `failed`/`cancelled` — он остаётся виден в
 очереди. «Удалить» (кнопка в строке, «Удалить выбранные» по чекбоксам,
-«Очистить всё») стирает строку и всю её историю проверок/событий
-физически, без возможности восстановления — работает из любого
-состояния, включая активно проверяемое (Floating IP отвязывается,
+«Очистить всё») убирает строку из `/ips` безвозвратно — работает из
+любого состояния, включая активно проверяемое (Floating IP отвязывается,
 валидатор освобождается). Все три операции удаления в UI защищены
 `hx-confirm` с формулировкой, отражающей необратимость — «Очистить всё»
-предупреждает отдельно, так как затрагивает и активные проверки. Подробнее
-— [API.md](API.md#delete-apiv1adminipsip-post-apiv1adminipsdelete-post-apiv1adminipsclear)
+предупреждает отдельно, так как затрагивает и активные проверки.
+
+**Накопленная история при этом не теряется** — она остаётся в
+[реестре](#реестр-адресов) (`/registry/{ip}`) даже после того, как адрес
+пропал из `/ips`, и продолжает пополняться, если адрес позже добавят
+заново. Подробнее —
+[API.md](API.md#delete-apiv1adminipsip-post-apiv1adminipsdelete-post-apiv1adminipsclear)
 и [USAGE.md](USAGE.md#удаление-адресов-из-очереди).

+### Реестр адресов
+
+`/registry` решает задачу, которую `/ips` принципиально не может: история
+проверок конкретного адреса не должна теряться только из-за того, что его
+временно вывели из очереди (например, адрес переиспользуют для другой
+цели) и позже добавили обратно — возможно, под другим циклом проверки.
+Каждая запись реестра живёт всё время, что адрес когда-либо существовал в
+системе, и не удаляется вместе со строкой `ip_queue`. Единственное, что
+можно ограничить — глубину детальной истории проверок на один адрес
+(`history_retention_cycles` на `/settings`, по циклам, а не по времени);
+сама запись в реестре (когда адрес впервые встречен, сколько всего было
+циклов) остаётся всегда. Подробнее —
+[API.md](API.md#реестр-адресов-и-история-проверок).
+
 ## Конфигурация

 См. `configs/admin-dashboard.example.yaml`. Ключевые поля:
@@ -11,10 +11,12 @@

 - [Как устроена работа с системой](#как-устроена-работа-с-системой)
 - [Добавление новых IP в очередь](#добавление-новых-ip-в-очередь)
+- [Сканирование Floating IP из OpenStack](#сканирование-floating-ip-из-openstack)
 - [Наблюдение за очередью](#наблюдение-за-очередью)
 - [Значения полей IP](#значения-полей-ip)
 - [Как читать итоговый результат (pass/partial/fail)](#как-читать-итоговый-результат-passpartialfail)
 - [Просмотр деталей и истории по конкретному адресу](#просмотр-деталей-и-истории-по-конкретному-адресу)
+- [Реестр адресов и глубина истории](#реестр-адресов-и-глубина-истории)
 - [Управление валидаторами](#управление-валидаторами)
 - [Управление площадками (проберами)](#управление-площадками-проберами)
 - [Управление типами проверок пробера](#управление-типами-проверок-пробера)
@@ -75,6 +77,31 @@ curl -s -X POST http://<control-api>:8080/api/v1/admin/ips \
 при разворачивании стенда — но для повседневного добавления адресов проще
 и быстрее пользоваться API выше.

+## Сканирование Floating IP из OpenStack
+
+Вместо того чтобы перечислять адреса вручную, можно попросить control-api
+самому найти их в облаке:
+
+```bash
+curl -s -X POST http://<control-api>:8080/api/v1/admin/ips/scan
+```
+
+Сканируются все Floating IP текущего проекта OpenStack, но в очередь
+ставятся только **свободные** — те, что не привязаны сейчас ни к одному
+порту (это и есть пул адресов, ожидающих проверки перед повторной
+выдачей). Уже привязанные к чему-то Floating IP игнорируются. Внутри
+вызов делает то же самое, что и обычное добавление — новые адреса
+встают в очередь, уже завершённые перезапускаются, активно проверяемые не
+трогаются (см. [выше](#добавление-новых-ip-в-очередь)).
+
+В `admin-dashboard` то же самое — кнопка «Сканировать Floating IP» на
+странице `/ips`.
+
+Если хочется, чтобы сканирование происходило само по расписанию, а не
+только по запросу — задайте `orchestrator.fip_scan_interval_seconds`
+(в секундах) в `control-api.yaml`; `0` (по умолчанию) оставляет только
+ручной запуск через ручку/кнопку выше.
+
 ## Наблюдение за очередью

 Общая сводка:
@@ -198,6 +225,41 @@ curl -s http://<control-api>:8080/api/v1/admin/ips/203.0.113.10 \
  | jq '.checks[] | select(.Success==false)'
 ```

+Это — только текущая попытка. Полная история адреса за всё время, включая
+предыдущие попытки и даже периоды, когда адрес не стоял в очереди вовсе,
+смотрится через реестр — см. следующий раздел.
+
+## Реестр адресов и глубина истории
+
+`GET /api/v1/admin/ips/{ip}` (и `/ips/{ip}` в дашборде) показывает только
+*текущую* попытку проверки. Но если адрес удалили из очереди и позже
+добавили заново, это уже новая попытка — а куда девается история старой?
+Она не пропадает: control-api ведёт отдельный **реестр** (`ip_registry`) —
+запись обо всех адресах, когда-либо поставленных на проверку, вместе с
+полной накопленной историей проверок по каждому, независимо от того,
+удалялся ли адрес из очереди и добавлялся ли повторно.
+
+```bash
+# все адреса, когда-либо ставившиеся на проверку, с краткой сводкой
+curl -s http://<control-api>:8080/api/v1/admin/registry | python3 -m json.tool
+
+# полная история проверок одного адреса, по всем циклам, не только текущему
+curl -s http://<control-api>:8080/api/v1/admin/registry/203.0.113.10 | python3 -m json.tool
+```
+
+В `admin-dashboard` — страницы `/registry` (список) и `/registry/{ip}`
+(история конкретного адреса), со ссылкой туда со страницы `/ips/{ip}`.
+
+**Глубина хранения.** Чтобы история не росла бесконечно на адресах,
+которые перепроверяют очень часто, можно ограничить, сколько последних
+циклов проверки хранить на каждый адрес — `history_retention_cycles` на
+странице `/settings` (или `PUT /api/v1/admin/config/orchestrator`, см.
+[API.md](API.md#настройки-оркестратора-apiv1adminconfigorchestrator)).
+`0` (по умолчанию) — хранить без ограничения. Ограничение действует только
+на глубину детальной истории проверок; сама запись в реестре (что адрес
+существует, когда впервые встречен, сколько всего было циклов) не
+удаляется никогда.
+
 ## Управление валидаторами

 Список валидаторов и их текущее состояние:
@@ -457,12 +519,16 @@ curl -s http://<control-api>:8080/api/v1/admin/ips/203.0.113.10 | python3 -m jso

 ## Удаление адресов из очереди

-**Отличие от отмены (`cancel`) выше: удаление безвозвратно.** Cancel
-переводит адрес в `failed`/`cancelled` и сохраняет запись как историю —
-её видно в очереди и в деталях адреса. Delete физически стирает строку
-`ip_queue` и всю её историю проверок и событий: адрес полностью исчезает,
-восстановить его нельзя. Если нужно просто остановить зависшую проверку,
-но сохранить её результат в истории — используйте
+**Отличие от отмены (`cancel`) выше: удаление безвозвратно убирает адрес
+из очереди.** Cancel переводит адрес в `failed`/`cancelled` и сохраняет
+запись как историю — её видно в очереди и в деталях адреса. Delete
+физически стирает строку `ip_queue`: адрес полностью исчезает из
+`/ips`/`/ips/{ip}`, восстановить именно эту строку нельзя. Накопленная
+история проверок при этом **не теряется** — она остаётся в
+[реестре](#реестр-адресов-и-глубина-истории) (`/registry/{ip}`) и видна
+там даже после удаления адреса из очереди. Если нужно просто остановить
+зависшую проверку, но сохранить её результат прямо в очереди —
+используйте
 [«Принудительную остановку проверки»](#принудительная-остановка-проверки)
 выше, а не удаление.