# `intersection.php` — сидер ключей `replace.cidr4`

[For English: README.en.md](README.en.md)

Одноразовый PHP-скрипт: проходит по всем конфигам порталов в
`config/<группа>/<портал>.json`, и для каждого портала, чей `cidr4`
содержит любую зону из файла `cidr4.txt`, добавляет эту зону как
ключ в `replace.cidr4` с пустым значением `[]`.

Используется чтобы массово разметить порталы, которые делят «широкие»
CIDR-зоны (типа `172.217.0.0/16` у google/yandex) — см. подробности
о самой фиче в [../REPLACE.md](../REPLACE.md).

## Что именно делает скрипт

1. Читает `cidr4.txt` — по одной CIDR-зоне на строку. Пустые строки
   и строки, начинающиеся на `#`, пропускаются.
2. Рекурсивно обходит `config/*/*.json`.
3. Для каждого портала: если `cidr4` содержит зоны из списка, добавляет
   их в `replace.cidr4` с пустым `[]` в значении (если ключа ещё нет).
4. Дополнительно создаёт каноническую форму
   `replace: {cidr4: {...}, cidr6: {}}`, если поля раньше не было.
5. Переписывает JSON портала в том же порядке ключей, в котором его
   пишет сам сервер через `Site::saveConfig`.

**Идемпотентно.** Повторный запуск — no-op. Уже заполненные
`value`-массивы (которые успел нарастить `reload`) не затираются.

## Запуск

Запускать из корня проекта:

```bash
# Напрямую
php docs/intersection/intersection.php

# Через docker compose
docker compose run --rm app php docs/intersection/intersection.php
```

Порог памяти в скрипте поднят до 4 ГБ (`ini_set('memory_limit', '4048M')`)
для чтения тяжёлых конфигов вроде Adobe / Amazon с тысячами доменов.

## Формат `cidr4.txt`

Одна CIDR-зона на строку в точно той форме, в которой она встречается
в `cidr4` порталов (сравнение **строкой байт-в-байт**, без
нормализации). Пустые строки и `#`-комментарии пропускаются:

```
# Akamai
23.32.0.0/11
23.192.0.0/11
104.64.0.0/10

# Google
172.217.0.0/16
216.58.192.0/19
```

## Что происходит после запуска

Перезапустите сервер. На следующем `reload`-цикле при
`SYS_REPLACE_ESCALATE_IPS=true` (дефолт) пустые value-массивы ключей
будут заполнены `/32` адресами портала, попавшими в ключевую зону.
Если дополнительно включён `SYS_REPLACE_AGGREGATE_SUBNETS=true` и
пороги `SYS_REPLACE_COLLAPSE_THRESHOLD_*` — сработают агрегация и
плотностное схлопывание. Подробности — в [../REPLACE.md](../REPLACE.md).

## Защиты от кривого ввода

-   Файл конфига с корнем не `object` — пропуск + сообщение в `stderr`.
-   `replace`, `replace.cidr4`, `replace.cidr6` не-`object` —
    пропуск + сообщение. Вручную ломать структуру не стоит, но
    скрипт не затрёт её молча.
-   Пустой `cidr4` портала или отсутствующий — портал не трогается.
-   Зона из `cidr4.txt`, которой нет ни у одного портала — тихо
    игнорируется.

## Когда НЕ стоит запускать

-   Если `cidr4.txt` сейчас редактируется/под версионным контролем
    с правками — дождитесь, пока список стабилизируется.
-   Если на сервере параллельно идёт `reload`-цикл крупного портала —
    скрипт может записать конфиг поверх свежей эскалации. Лучше
    остановить сервис перед запуском или дождаться тихого момента.
-   Многократные прогоны «просто на всякий случай» — скрипт
    идемпотентен, но `mtime` файлов сдвигается.