# BBRKN DNS Configurator

## Описание

**BBRKN** — это инструмент для автоматического формирования и деплоя конфигураций
для `dnsmasq` (через Pi-hole), необходимых для корректной работы целевых сайтов и сервисов.

Проект решает задачу: у нас есть список базовых доменов (`domains.txt`), но для работы
сайтов часто требуется множество дополнительных ресурсов — CDN, API-эндпоинты,
трекеры и т.д. Ручное отслеживание этих зависимостей неудобно.

Для этого используется сервис на базе Chromium, который автоматически анализирует
страницу и возвращает список всех связанных доменов. Проект берёт этот список,
нормализует его и формирует два конфигурационных файла для `dnsmasq`:

- `91-ipset-bbrkn.conf` — добавляет все домены в ipset `bbrkn`
- `92-resolve-bbrkn.conf` — указывает резолвить все эти домены через DNS-сервер `8.8.8.8`

Эти файлы затем автоматически деплоятся в Pi-hole и активируются перезапуском контейнера.

---

## Архитектура

```mermaid
flowchart TD
    A[domains.txt] --> B[generate-configs.sh]
    B -->|HTTP API| C[Chromium service<br/>API_URL]
    B --> D[91-ipset-bbrkn.conf<br/>92-resolve-bbrkn.conf]
    D --> E[deploy-to-gateway.sh]
    E --> F[Pi-hole<br/>dnsmasq]
```

---

## Переменные окружения

Все важные параметры конфигурируются через **переменные окружения**.
Если переменная не задана, используется дефолтное значение.

| Переменная         | По умолчанию                             | Назначение                                  |
| ------------------ | ---------------------------------------- | ------------------------------------------- |
| `INPUT_FILE`       | `domains.txt`                            | Входной список доменов                      |
| `IPSET_CONF`       | `/tmp/91-ipset-bbrkn.conf`               | Временный файл конфигурации для ipset       |
| `RESOLVE_CONF`     | `/tmp/92-resolve-bbrkn.conf`             | Временный файл конфигурации для серверов    |
| `API_URL`          | `http://10.100.1.2:3000/domains?domain=` | Адрес API сервиса Chromium                  |
| `DNS_SERVER`       | `8.8.8.8`                                | DNS-сервер, через который резолвятся домены |
| `TARGET_DIR`       | `/opt/appdata/pihole/etc/dnsmasq.d`      | Директория для установки конфигов в Pi-hole |
| `DOCKER_CONTAINER` | `pihole`                                 | Имя контейнера Pi-hole                      |

👉 В Forgejo workflow все эти переменные задаются в секции `env:`.

---

## Пример работы

Пример запроса к Chromium-сервису:

```bash
curl "http://10.100.1.2:3000/domains?domain=pornhub.com"
```

Ответ:

```json
{
  "domains": [
    "a.adtng.com",
    "cdn1-smallimg.phncdn.com",
    "ei.phncdn.com",
    "ht-cdn2.adtng.com",
    "media.trafficjunky.net",
    "pix-cdn77.phncdn.com",
    "pornhub.com",
    "www.pornhub.com"
  ]
}
```

В итоговые конфиги будут добавлены все эти домены.

Если сайт недоступен (например, сервисный домен):

```bash
curl "http://10.100.1.2:3000/domains?domain=bt1.t-ru.org"
```

Ответ:

```json
{
  "error": "page.goto: net::ERR_NAME_NOT_RESOLVED at https://bt1.t-ru.org/"
}
```

Такой домен будет классифицирован как `service` и попадёт в конфиг без связанных.

---

## Установка и запуск

### Требования

* Linux-система или self-hosted runner Forgejo
* [Pi-hole](https://pi-hole.net/)
* [jq](https://stedolan.github.io/jq/) для парсинга JSON
* make
* docker (для управления Pi-hole контейнером)
* доступ к сервису Chromium (по умолчанию: `http://10.100.1.2:3000/domains`)

### Ручной запуск

```bash
make clean     # очистка временных файлов
make check     # только отчёт по доменам
make test      # генерация + превью файлов
make deploy    # генерация + деплой на шлюз
```

### Автоматический запуск (Forgejo CI/CD)

Workflow (`.forgejo/workflows/deploy.yml`) автоматически срабатывает при изменении `domains.txt`.
CI делает:

1. Валидацию синтаксиса `domains.txt`
2. `make clean`
3. `make all` (генерация + деплой)
4. Сохранение артефактов (`91-ipset-bbrkn.conf` и `92-resolve-bbrkn.conf`)

---

## Пример отладочного отчёта

```
===== DEBUG REPORT =====
Original domains file: 50 entries
Final unique domains: 135
  - Base domains:     50
  - Related domains:  85

auth.openai.com - site
cdn.oaistatic.com - site
oaistatic.com - site
ab.chatgpt.com - site
realtime.chatgpt.com - site
ws.chatgpt.com - site
chatgpt.com - site
byspotify.com - site
pscdn.co - service
...
========================
```

---

## Траблшутинг

### 1. Chromium-сервис недоступен

* Проверь, что сервис слушает на `${API_URL}`.
* Убедись, что firewall не блокирует доступ с runner-а.
* Можно протестировать напрямую:

  ```bash
  curl "${API_URL}example.com"
  ```

  Если ответа нет или ошибка — перезапусти сервис.

### 2. В отчёте все домены помечены как `service`

Это значит, что сервис не смог открыть страницы. Возможные причины:

* Сайты блокируются провайдером → нужен обход (VPN/проксирование).
* Chromium-сервис работает без доступа к интернету.

### 3. Конфиги пустые или слишком маленькие

* Проверь содержимое `domains.txt` (убери комментарии, пустые строки).
* Убедись, что `jq` установлен (иначе парсинг JSON не сработает).
* В debug-отчёте будет видно, какие домены обработаны.

### 4. Pi-hole не поднимается после деплоя

* Запусти `docker logs ${DOCKER_CONTAINER}`, проверь ошибки.
* Откати конфиги из бэкапа (они создаются с суффиксом `.backup.YYYYMMDD-HHMMSS`).
* Убедись, что новые конфиги не содержат невалидных строк.

### 5. Forgejo CI падает

* Проверь, что runner имеет доступ к `/tmp` (для генерации файлов).
* Проверь, что установлены зависимости: `make`, `jq`, `docker`.
* Логи CI подскажут, на каком шаге сломалось (`check`, `generate`, `deploy`).

---

## Зачем это нужно?

* Автоматически отслеживать **скрытые зависимости сайтов** (CDN, API-сервера и т.п.).
* Поддерживать актуальные списки для маршрутизации/блокировки/разделения трафика.
* Исключить ручную рутину: всё обновление конфигов делается одной командой или автоматически через CI/CD.