docs: spec for custom records and orphan domain cleanup
Two operational problems on the domain check page: records deliberately added outside the template keep showing up as prunes (drift + scheduler notifications), and domains whose zones were deleted at the provider are never removed by a re-import. Design decisions: custom marks are scoped per domain, the template wins over a mark (a mark only applies to Kind == Delete), marks live in their own domain_custom_records table, and orphan domains are removed inside the import transaction with a guard that skips deletion when the provider returns zero zones. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018Yr8frsaxBgab1Aa7yfPuU
This commit is contained in:
Claude Opus 5
@@ -0,0 +1,238 @@
|
|||||||
|
# Custom-записи в диффе и очистка доменов удалённых зон
|
||||||
|
|
||||||
|
Дата: 2026-08-19
|
||||||
|
Статус: утверждён к реализации
|
||||||
|
|
||||||
|
## Задача
|
||||||
|
|
||||||
|
Две связанные проблемы эксплуатации, обе всплывают на странице `DOMAIN / CHECK`.
|
||||||
|
|
||||||
|
1. **Осознанные записи вне шаблона.** Оператор добавляет в зону запись, которой
|
||||||
|
нет в шаблоне (`CNAME admin.example.ru.`, `app`, `dav`). Каждый чек кладёт её
|
||||||
|
в `PRUNES`, домен получает статус `drift`, планировщик шлёт уведомление.
|
||||||
|
Убрать шум можно только внеся запись в шаблон — но шаблон общий для многих
|
||||||
|
зон, а запись специфична для одной. Нужна возможность пометить такую запись
|
||||||
|
«это осознанно, не проверять», с обратимым действием.
|
||||||
|
|
||||||
|
2. **Домены исчезнувших зон.** `ImportDomains` только создаёт домены
|
||||||
|
(`ON CONFLICT DO NOTHING`). Если зона удалена у провайдера, домен остаётся в
|
||||||
|
БД навсегда: планировщик чекает его, получает ошибку провайдера, домен висит
|
||||||
|
в статусе `error` и генерирует уведомления. Переимпорт ситуацию не лечит.
|
||||||
|
|
||||||
|
## Принятые решения
|
||||||
|
|
||||||
|
| Вопрос | Решение |
|
||||||
|
|---|---|
|
||||||
|
| Скоуп custom-записей | Привязка к домену. Исключение действует только в своей зоне |
|
||||||
|
| Конфликт с шаблоном | Шаблон побеждает: пометка действует только на `Kind == Delete` |
|
||||||
|
| Хранение | Отдельная таблица `domain_custom_records` |
|
||||||
|
| Orphan-домены | Удаляются в транзакции переимпорта, с гардом на пустой ответ провайдера |
|
||||||
|
|
||||||
|
## Часть 1. Custom-записи
|
||||||
|
|
||||||
|
### Модель данных
|
||||||
|
|
||||||
|
Миграция `0005_domain_custom_records.sql`:
|
||||||
|
|
||||||
|
```sql
|
||||||
|
CREATE TABLE domain_custom_records (
|
||||||
|
domain_id uuid NOT NULL REFERENCES domains(id) ON DELETE CASCADE,
|
||||||
|
record_key text NOT NULL,
|
||||||
|
note text NOT NULL DEFAULT '',
|
||||||
|
created_at timestamptz NOT NULL DEFAULT now(),
|
||||||
|
PRIMARY KEY (domain_id, record_key)
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
`record_key` — тот же `RecordDiff.Key()` = `"ТИП имя."` (нормализованный,
|
||||||
|
материализованный: с подставленным именем зоны, без `{{domain_name}}`). Ключ
|
||||||
|
идентифицирует RRset целиком, а не конкретные значения: если значения записи в
|
||||||
|
зоне изменятся, она останется скрытой. Это осознанный выбор — «эта запись живёт
|
||||||
|
вне шаблона, её содержимое сервис не контролирует».
|
||||||
|
|
||||||
|
Составной PK делает добавление идемпотентным (`ON CONFLICT DO NOTHING`).
|
||||||
|
Каскад от `domains` убирает строки вместе с доменом (в том числе при очистке
|
||||||
|
orphan-доменов из части 2).
|
||||||
|
|
||||||
|
`note` заполняется пустой строкой — колонка задел под «зачем добавлено»; UI её
|
||||||
|
пока не пишет и не показывает.
|
||||||
|
|
||||||
|
### Store
|
||||||
|
|
||||||
|
Запросы в `internal/store/queries/customs.sql`:
|
||||||
|
|
||||||
|
- `AddCustomRecord` — `INSERT ... ON CONFLICT (domain_id, record_key) DO NOTHING`
|
||||||
|
- `DeleteCustomRecord` — `DELETE WHERE domain_id = $1 AND record_key = $2`
|
||||||
|
- `ListCustomKeys` — `SELECT record_key ... WHERE domain_id = $1 ORDER BY record_key`
|
||||||
|
|
||||||
|
Тенант-скоуп обеспечивается на уровне store-методов: `AddCustom`/`DeleteCustom`
|
||||||
|
принимают `(domainID, projectID, key)` и сперва делают скоупленный
|
||||||
|
`GetDomain(domainID, projectID)` — тем же приёмом, что `SetDomainTemplate`
|
||||||
|
проверяет принадлежность шаблона. Домен чужого проекта → `pgx.ErrNoRows` → 404.
|
||||||
|
|
||||||
|
`internal/store/db/*.sql.go` правится вручную (sqlc в среде нет): порядок колонок
|
||||||
|
в SQL-строке, в `*Row`-структуре и в `row.Scan(...)` обязан совпадать 1:1.
|
||||||
|
|
||||||
|
### Дифф
|
||||||
|
|
||||||
|
`internal/diff`:
|
||||||
|
|
||||||
|
```go
|
||||||
|
type RecordDiff struct {
|
||||||
|
// ...
|
||||||
|
ReadOnly bool // NS/SOA — показываются, но не применяются
|
||||||
|
Custom bool // осознанная запись вне шаблона — показывается, но не считается дрифтом
|
||||||
|
}
|
||||||
|
|
||||||
|
// MarkCustom помечает диффы, чей ключ есть в keys, как Custom. Помечаются
|
||||||
|
// ТОЛЬКО Kind == Delete и !ReadOnly: шаблон побеждает — как только шаблон
|
||||||
|
// начинает описывать этот ключ, запись возвращается в Updates/InSync, а
|
||||||
|
// лежащая в БД пометка перестаёт действовать (но не удаляется).
|
||||||
|
func (c *Changeset) MarkCustom(keys []string)
|
||||||
|
|
||||||
|
// Customs возвращает помеченные диффы. Не пересекается с Updates()/Prunes().
|
||||||
|
func (c Changeset) Customs() []RecordDiff
|
||||||
|
```
|
||||||
|
|
||||||
|
`Actionable()`, `Updates()`, `Prunes()` пропускают `Custom` наравне с `ReadOnly`.
|
||||||
|
Следствия: `service.DeriveStatus` даёт `in_sync`, планировщик по таким доменам
|
||||||
|
молчит, а `service.Apply` физически не может применить custom-ключ — он
|
||||||
|
итерирует `cs.Prunes()`, откуда custom исключён (защита от фронта, приславшего
|
||||||
|
ключ со старого снапшота).
|
||||||
|
|
||||||
|
Инвариант, который держим тестом: `Updates()` и `Prunes()` по-прежнему разбивают
|
||||||
|
`Actionable()` на два непересекающихся множества, а `Customs()` и `ReadOnly`
|
||||||
|
живут вне `Actionable()`.
|
||||||
|
|
||||||
|
### Сервис
|
||||||
|
|
||||||
|
`service.DomainRef` получает поле `CustomKeys []string`; `store.LoadDomain`
|
||||||
|
дочитывает их отдельным запросом `ListCustomKeys`. `resolve()` вызывает
|
||||||
|
`cs.MarkCustom(ref.CustomKeys)` сразу после `diff.Diff(...)` — единственная точка
|
||||||
|
пометки, как `tmpl.Materialize` для плейсхолдеров.
|
||||||
|
|
||||||
|
### API
|
||||||
|
|
||||||
|
Обе ручки — под `RequireAuth` + `RequireProjectAccess`, домен грузится парой
|
||||||
|
`(did, pid)`:
|
||||||
|
|
||||||
|
```
|
||||||
|
POST /api/projects/{pid}/domains/{did}/customs {"key":"CNAME admin.example.ru."} → 201
|
||||||
|
DELETE /api/projects/{pid}/domains/{did}/customs?key=CNAME%20admin.example.ru. → 204
|
||||||
|
```
|
||||||
|
|
||||||
|
Пустой `key` → 400. Домен не найден в проекте → 404. Ключ в теле POST и в
|
||||||
|
query-параметре DELETE, а не в path-сегменте: ключ содержит пробел и точки, и
|
||||||
|
path-сегмент потребовал бы двойного кодирования.
|
||||||
|
|
||||||
|
Ответ чека расширяется полем `customs`, инициализируемым пустым слайсом (nil
|
||||||
|
даёт JSON `null`, на котором падает `.map` на фронте):
|
||||||
|
|
||||||
|
```go
|
||||||
|
type changesetResponse struct {
|
||||||
|
Updates []recordView `json:"updates"`
|
||||||
|
Prunes []recordView `json:"prunes"`
|
||||||
|
Customs []recordView `json:"customs"`
|
||||||
|
ReadOnly []recordView `json:"readOnly"`
|
||||||
|
InSync int `json:"inSyncCount"`
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
`recordView` получает поле `custom bool` — по симметрии с `readOnly`, чтобы
|
||||||
|
строку можно было отрисовать правильно вне зависимости от секции.
|
||||||
|
|
||||||
|
### Фронт
|
||||||
|
|
||||||
|
`ChangesetResponse` и `RecordView` в `web/src/api/types.ts` — плюс `customs` и
|
||||||
|
`custom`. Хуки `useAddCustom(domainId)` / `useRemoveCustom(domainId)`
|
||||||
|
инвалидируют ключ запроса чека.
|
||||||
|
|
||||||
|
`DiffView` получает четвёртый тон `custom` (иконка `BookmarkCheck`, свой
|
||||||
|
CSS-токен `--diff-custom`), секция рендерится между `Prunes` и `Read-only`.
|
||||||
|
Чекбоксов в ней нет — записи не применяются.
|
||||||
|
|
||||||
|
Действия на строках:
|
||||||
|
|
||||||
|
- в `Prunes` — кнопка «В customs», `aria-label={`В customs ${type} ${name}`}`
|
||||||
|
- в `Customs` — кнопка «Вернуть в дифф» (`Undo2`),
|
||||||
|
`aria-label={`Вернуть в дифф ${type} ${name}`}`
|
||||||
|
|
||||||
|
`RecordRow` получает необязательный слот `action?: ReactNode` справа от имени —
|
||||||
|
секции `update`/`readonly` его не передают.
|
||||||
|
|
||||||
|
## Часть 2. Очистка доменов удалённых зон
|
||||||
|
|
||||||
|
### Поведение
|
||||||
|
|
||||||
|
`ImportDomains` переименовывается по смыслу в синхронизацию: в одной транзакции
|
||||||
|
|
||||||
|
1. создаются домены для новых зон (как сейчас, `ON CONFLICT DO NOTHING`);
|
||||||
|
2. удаляются домены **этого** `provider_account_id`, чьих `zone_id` нет в ответе
|
||||||
|
провайдера.
|
||||||
|
|
||||||
|
Скоуп удаления — аккаунт, а не проект: у проекта может быть несколько
|
||||||
|
provider-аккаунтов, и зоны одного не должны влиять на домены другого.
|
||||||
|
|
||||||
|
### Гард на пустой ответ
|
||||||
|
|
||||||
|
Если `ListZones` вернул ноль зон — не удаляется ничего. Пустой список
|
||||||
|
неотличим от «аккаунт временно потерял доступ к зонам», а ценой ошибки будет
|
||||||
|
удаление всех доменов аккаунта вместе с историей чеков. Ошибка `ListZones`
|
||||||
|
поднимается наружу и до store не доходит, так что случай «частичный список без
|
||||||
|
ошибки» остаётся только теоретическим (в клиенте Selectel — при неувеличивающемся
|
||||||
|
`next_offset`); гард на пустой ответ закрывает практически значимую часть риска.
|
||||||
|
|
||||||
|
### Что удаляется каскадом
|
||||||
|
|
||||||
|
`check_runs` (история чеков) и `domain_custom_records` — обе таблицы ссылаются на
|
||||||
|
`domains` с `ON DELETE CASCADE`. Привязка шаблона у удаляемого домена просто
|
||||||
|
исчезает; сам шаблон не трогается. Операция необратима — поэтому и нужен гард.
|
||||||
|
|
||||||
|
### Контракт ответа
|
||||||
|
|
||||||
|
```go
|
||||||
|
type importResponse struct {
|
||||||
|
Created []domainResponse `json:"created"`
|
||||||
|
Removed []domainResponse `json:"removed"`
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Это ломающее изменение: сейчас ручка отдаёт голый массив созданных доменов.
|
||||||
|
Фронт правится в том же коммите, иначе задеплоенный бандл получит объект там,
|
||||||
|
где ждёт массив. UI показывает «Создано N, удалено M».
|
||||||
|
|
||||||
|
## Тесты
|
||||||
|
|
||||||
|
**Go, без Docker:**
|
||||||
|
|
||||||
|
- `internal/diff` — `MarkCustom` метит только `Delete`; шаблон побеждает (ключ,
|
||||||
|
описанный шаблоном, остаётся в `Updates`); `Actionable/Updates/Prunes`
|
||||||
|
исключают `Custom`; `Customs()` возвращает помеченные
|
||||||
|
- `internal/service` — `resolve` метит диффы ключами из `DomainRef`; `Apply` не
|
||||||
|
применяет custom-ключ, присланный в `req.Prunes`; `DeriveStatus` = `in_sync`,
|
||||||
|
когда единственное расхождение — custom
|
||||||
|
- `internal/api` — POST/DELETE customs (201/204), пустой ключ → 400, чужой домен
|
||||||
|
→ 404, `customs` присутствует в ответе чека и не `null`; import отдаёт
|
||||||
|
`{created, removed}`
|
||||||
|
|
||||||
|
**Go, с Docker (testcontainers):**
|
||||||
|
|
||||||
|
- `internal/store` — add идемпотентен, delete снимает пометку, `ListCustomKeys`
|
||||||
|
скоуплен по домену, каскад при удалении домена; синхронизация импорта удаляет
|
||||||
|
только домены своего аккаунта и ничего не удаляет при пустом списке зон
|
||||||
|
|
||||||
|
**Фронт (Vitest + RTL):**
|
||||||
|
|
||||||
|
- секция `CUSTOMS` рендерится и не содержит чекбоксов
|
||||||
|
- «В customs» на строке prune дёргает мутацию с ключом записи
|
||||||
|
- «Вернуть в дифф» на строке custom дёргает мутацию удаления
|
||||||
|
- страница аккаунтов показывает «Создано N, удалено M» после импорта
|
||||||
|
|
||||||
|
## За рамками
|
||||||
|
|
||||||
|
- пометка по значению записи, а не по типу+имени
|
||||||
|
- массовое добавление в customs одним действием
|
||||||
|
- авто-очистка ключей, чьи записи исчезли из зоны (мусор безвреден: дифф их не
|
||||||
|
порождает, а `note`/`created_at` дают контекст при разборе)
|
||||||
|
- редактирование `note` из UI
|
||||||
|
- dry-run и подтверждение удаления orphan-доменов
|
||||||
Reference in New Issue
Block a user