From 537ae61f639964a26c7f01ac83688ed27e37dd72 Mon Sep 17 00:00:00 2001
From: goodvin <goodvin.l4@gmail.com>
Date: Sat, 21 Mar 2026 09:46:15 +0300
Subject: [PATCH] =?UTF-8?q?=D0=A0=D0=B5=D1=84=D0=B0=D0=BA=D1=82=D0=BE?=
 =?UTF-8?q?=D1=80=D0=B8=D0=BD=D0=B3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .forgejo/workflows/deploy.yaml |  30 +--
 .gitignore                     |   3 +
 Makefile                       |  21 +-
 README.md                      | 348 +++++++++++++++++++--------------
 scripts/deploy-to-gateway.sh   | 120 ++++++++++--
 scripts/generate-configs.sh    | 277 ++++++++++++++++++--------
 6 files changed, 525 insertions(+), 274 deletions(-)

diff --git a/.forgejo/workflows/deploy.yaml b/.forgejo/workflows/deploy.yaml
index fda2345..c677c24 100644
--- a/.forgejo/workflows/deploy.yaml
+++ b/.forgejo/workflows/deploy.yaml
@@ -3,6 +3,7 @@ name: Deploy DNS Configuration
 on:
   push:
     branches: [ main ]
+  workflow_dispatch:  # Ручной запуск из UI
 
 jobs:
   deploy:
@@ -11,7 +12,7 @@ jobs:
       DEBUG: 1
       DEBUG_LOG: /tmp/generate-configs.debug.log
       # ==== Конфигурация проекта ====
-      INPUT_FILE: domains.txt
+      DOMAINS_FILE: domains.txt
 
       # Временные конфиги (куда пишутся generate-configs.sh)
       IPSET_CONF: /tmp/91-ipset-bbrkn.conf
@@ -20,9 +21,6 @@ jobs:
       # DNS-сервер для резолвинга
       DNS_SERVER: 10.100.1.2
 
-      # Адрес сервиса Chromium
-      API_URL: http://10.100.1.2:3000/domains?domain=
-
       # Директория конфигов на шлюзе
       TARGET_DIR: /opt/appdata/pihole/etc/dnsmasq.d
 
@@ -31,35 +29,21 @@ jobs:
 
       IGNORE_PARTS: "doubleclick yandex mail.ru bigsv.ru mts.ru rambler.ru yadro.ru aif.ru vkvideo.ru tns-counter.ru st.vk.com vk.com"
 
+      # Кэш API-ответов (self-hosted runner сохраняет workspace между запусками)
+      CACHE_DIR: .cache/api
+      CACHE_TTL_DAYS: 15
+
     steps:
       - name: Checkout repository
         uses: actions/checkout@v3
 
-      - name: Validate domains file
-        run: |
-          if [ ! -f domains.txt ]; then
-            echo "Error: domains.txt not found"
-            exit 1
-          fi
-          # Проверка синтаксиса доменов
-          grep -v '^#' domains.txt | grep -v '^$' | while read domain; do
-            if ! echo "$domain" | grep -qE '^[a-zA-Z0-9-]+(\.[a-zA-Z0-9-]+)+$'; then
-              echo "Error: Invalid domain format: $domain"
-              exit 1
-            fi
-          done
-
-      - name: Prepare Makefile
-        run: |
-          chmod +x scripts/generate-configs.sh
-          chmod +x scripts/deploy-to-gateway.sh
-
       - name: Run workflow (clean → all)
         run: |
           make clean
           make all
 
       - name: Upload configs as artifacts
+        if: always()  # Загружаем артефакты даже при падении — для отладки
         uses: actions/upload-artifact@v3
         with:
           name: dnsmasq-configs
diff --git a/.gitignore b/.gitignore
index 8c2b884..e5d0620 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,6 @@
+# API response cache
+.cache/
+
 # ---> VisualStudioCode
 .vscode/*
 !.vscode/settings.json
diff --git a/Makefile b/Makefile
index ed10dc4..396fcc4 100644
--- a/Makefile
+++ b/Makefile
@@ -3,16 +3,19 @@
 # ===============================
 
 # --- Переменные окружения (с дефолтами для локального запуска) ---
-IPSET_CONF    ?= /tmp/91-ipset-bbrkn.conf
-RESOLVE_CONF  ?= /tmp/92-resolve-bbrkn.conf
-CHROME_SERVER ?= http://10.100.1.2:3000
-DOMAINS_FILE  ?= domains.txt
+IPSET_CONF     ?= /tmp/91-ipset-bbrkn.conf
+RESOLVE_CONF   ?= /tmp/92-resolve-bbrkn.conf
+CHROME_SERVER  ?= http://10.100.1.2:3000
+DOMAINS_FILE   ?= domains.txt
+DNS_SERVER     ?= 10.100.1.2
+CACHE_DIR      ?= .cache/api
+CACHE_TTL_DAYS ?= 15
 
 # Экспортируем переменные, чтобы они были доступны внутри shell-скриптов
-export IPSET_CONF RESOLVE_CONF CHROME_SERVER DOMAINS_FILE
+export IPSET_CONF RESOLVE_CONF CHROME_SERVER DOMAINS_FILE DNS_SERVER CACHE_DIR CACHE_TTL_DAYS
 
 # --- Основные цели ---
-.PHONY: all clean check generate deploy
+.PHONY: all clean cache-clean check generate deploy
 
 all: generate deploy
 	@echo "✅ Конфиги успешно сгенерированы и задеплоены"
@@ -21,6 +24,11 @@ clean:
 	@echo "🧹 Очистка временных файлов"
 	@rm -f $(IPSET_CONF) $(RESOLVE_CONF)
 
+cache-clean:
+	@echo "🗑  Очистка кэша API ($(CACHE_DIR))"
+	@rm -rf $(CACHE_DIR)
+	@echo "✔ Кэш очищен"
+
 check:
 	@echo "🔍 Проверка файла доменов ($(DOMAINS_FILE))"
 	@if [ ! -f "$(DOMAINS_FILE)" ]; then \
@@ -44,4 +52,3 @@ deploy:
 	@echo "🚀 Деплой конфигов в систему"
 	@chmod +x scripts/deploy-to-gateway.sh
 	@./scripts/deploy-to-gateway.sh
-
diff --git a/README.md b/README.md
index 45a8999..2b5d65e 100644
--- a/README.md
+++ b/README.md
@@ -1,176 +1,221 @@
-# DNS Bypass Config Generator
+# bbrkn — DNS Bypass Config Generator
 
-Этот проект автоматизирует генерацию конфигураций для **Pi-hole / dnsmasq**, чтобы маршрутизировать трафик к заблокированным доменам через VPN-туннель (WireGuard).
+Автоматизирует генерацию конфигураций **Pi-hole / dnsmasq** для маршрутизации трафика заблокированных доменов через VPN-туннель (WireGuard).
 
-Скрипт `generate-configs.sh`:
-- нормализует входные доменные имена;
-- для каждого домена запрашивает внешний API (Chromium headless service);
-- определяет, является ли домен **сайтом** (site), **сервисом** (service) или **мертвым**;
-- формирует конфиги:
-  - `91-ipset-bbrkn.conf` — правила `ipset` для маркировки трафика;
-  - `92-resolve-bbrkn.conf` — правила `server=` для резолвинга через Google DNS.
-
----
-
-## Классификация доменов
-
-1. **Сайт (site)**  
-   API возвращает JSON с полем `relatedDomains`.  
-   В конфиги попадает **сам домен** + все связанные домены.
-
-2. **Сервис (service)**  
-   API возвращает ошибку:
-   - `ERR_CERT_COMMON_NAME_INVALID`  
-   - `ERR_CONNECTION_REFUSED`  
-   В конфиги попадает только **сам домен**.
-
-3. **Мертвый домен**  
-   API возвращает ошибку:
-   - `ERR_NAME_NOT_RESOLVED`  
-   - `Timeout`  
-   Такие домены полностью исключаются из конфигов.
-
----
-
-## Переменные окружения
-
-| Переменная     | Значение (по умолчанию) | Описание |
-|----------------|-------------------------|----------|
-| `DOMAINS_FILE` | `domains.txt`          | Входной файл со списком доменов |
-| `IPSET_CONF`   | `/tmp/91-ipset-bbrkn.conf` | Файл с правилами ipset |
-| `RESOLVE_CONF` | `/tmp/92-resolve-bbrkn.conf` | Файл с правилами server= |
-| `CHROME_SERVER`| `http://127.0.0.1:3000` | Адрес API headless Chromium |
-| `DNS_SERVER`   | `8.8.8.8`              | DNS для резолвинга через VPN |
-| `DEBUG`        | `0`                    | Включить (1) / выключить (0) отладку |
-| `DEBUG_LOG`    | `/tmp/generate-configs.debug.log` | Файл для подробного лога |
-
----
-
-## Запуск
-
-```bash
-# обычный запуск
-./generate-configs.sh
-
-# отладочный режим
-DEBUG=1 ./generate-configs.sh
-
-# dry-run (ничего не пишет в файлы)
-./generate-configs.sh --dry-run
-````
-
-После запуска будут сгенерированы файлы:
-
-* `$IPSET_CONF` — список правил ipset;
-* `$RESOLVE_CONF` — список правил server=.
-
----
-
-## Интеграция в CI/CD
-
-Переменные окружения передаются в `make` и далее в скрипт:
-
-```yaml
-jobs:
-  generate-configs:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-
-      - name: Run generator
-        run: |
-          make generate-configs
-        env:
-          DOMAINS_FILE: domains.txt
-          IPSET_CONF: ./out/91-ipset-bbrkn.conf
-          RESOLVE_CONF: ./out/92-resolve-bbrkn.conf
-          CHROME_SERVER: http://chrome-headless:3000
-          DNS_SERVER: 8.8.8.8
-```
-
-Файл `Makefile` прокидывает переменные дальше:
-
-```make
-generate-configs:
-	./generate-configs.sh
-```
-
----
-
-## Архитектура решения
+## Как это работает
 
 ```mermaid
 flowchart TD
-  A[Клиент в локальной сети] -->|DNS запрос| B[Pi-hole DNS на шлюзе]
-  B -->|если домен заблокирован| C[Google DNS 8.8.8.8 через VPN]
-  C --> D[Ответ с IP]
-  D --> B
-  B -->|IP в ipset| E[iptables / netfilter]
-  E -->|маршрутизация по mark| F[VPN WireGuard]
-  F --> G[Интернет ресурс]
+  A[domains.txt] --> B[generate-configs.sh]
+  B -->|кэш .cache/api| B
+  B -->|MISS / EXPIRED| C[Chromium headless API]
+  C --> B
+  B --> D[91-ipset-bbrkn.conf]
+  B --> E[92-resolve-bbrkn.conf]
+  D --> F[deploy-to-gateway.sh]
+  E --> F
+  F -->|backup + copy| G[Pi-hole dnsmasq.d/]
+  F -->|docker restart| H[Pi-hole container]
+  F -->|DNS health check| H
+  H -->|rollback если упал| G
 
-  subgraph "CI/CD"
-    X[domains.txt] --> Y[generate-configs.sh]
-    Y --> P1[ipset conf]
-    Y --> P2[resolve conf]
+  subgraph "Трафик клиента"
+    K[Клиент] -->|DNS запрос| H
+    H -->|домен в ipset → mark| I[iptables]
+    I --> J[WireGuard VPN]
+    J --> L[Интернет]
   end
 ```
 
 ---
 
-## Диаграмма потока обработки
+## Классификация доменов
 
-```mermaid
-sequenceDiagram
-  participant Client
-  participant PiHole
-  participant ChromeAPI
-  participant VPN
-  participant Internet
+Для каждого домена из `domains.txt` скрипт обращается к Chromium headless API и классифицирует результат:
 
-  Client->>PiHole: DNS-запрос к домену
-  PiHole->>ChromeAPI: Проверка домена
-  ChromeAPI-->>PiHole: relatedDomains / error
-  PiHole->>VPN: Резолвинг через 8.8.8.8 (для заблокированных)
-  VPN->>Internet: Запрос к сайту
-  Internet-->>VPN: Ответ
-  VPN-->>PiHole: IP-адрес
-  PiHole-->>Client: Ответ DNS
-  Client->>Internet: Трафик с IP через VPN
+| Результат API | Действие |
+|---|---|
+| JSON с `relatedDomains` | **Сайт** — добавляется домен + все связанные субдомены |
+| JSON с `error: ERR_NAME_NOT_RESOLVED` или `Timeout` | **Мёртвый домен** — пропускается, в конфиг не попадает |
+| JSON с любой другой ошибкой (`ERR_CERT_*`, `ERR_CONNECTION_REFUSED` и т.д.) | **Сервис** — добавляется только сам домен без субдоменов (не HTTP-сервис: SMTP, VPN, игровой сервер и т.п.) |
+| API недоступен (не 200 / не JSON после всех попыток) | **Fallback** — домен всё равно добавляется без субдоменов; фиксируется в разделе отчёта `API FAILURES` |
+
+> Любой домен из `domains.txt` гарантированно попадает в финальный конфиг, даже если API недоступен.
+
+### Формат выходных файлов
+
+Домены группируются по базовому домену с комментарием:
+
+```
+# example.com — 4 subdomains
+ipset=/example.com/bbrkn
+ipset=/static.example.com/bbrkn
+ipset=/api.example.com/bbrkn
+...
+
+# some-service.com — 0 subdomains
+ipset=/some-service.com/bbrkn
 ```
 
 ---
 
-## Отчёт после запуска
+## Структура проекта
 
-Скрипт выводит статистику:
-
-* количество строк во входном файле;
-* сколько доменов нормализовано / отброшено;
-* сколько API-ответов успешные, сервисные, мёртвые;
-* список **валидных основных сайтов**.
+```
+bbrkn/
+├── domains.txt                        # список доменов для обхода
+├── Makefile                           # управление сборкой и деплоем
+├── scripts/
+│   ├── generate-configs.sh            # генерация dnsmasq-конфигов
+│   └── deploy-to-gateway.sh           # деплой в Pi-hole + rollback
+└── .forgejo/workflows/deploy.yaml     # CI/CD на self-hosted runner
+```
 
 ---
 
-## Пример
+## Makefile
+
+```bash
+make all          # generate + deploy (полный цикл)
+make generate     # только сгенерировать конфиги
+make deploy       # только задеплоить в Pi-hole
+make clean        # удалить сгенерированные конфиги из /tmp
+make cache-clean  # очистить кэш API-ответов (.cache/api/)
+make check        # проверить синтаксис domains.txt
+```
+
+---
+
+## Переменные окружения
+
+### generate-configs.sh
+
+| Переменная | По умолчанию | Описание |
+|---|---|---|
+| `DOMAINS_FILE` | `domains.txt` | Входной файл со списком доменов |
+| `IPSET_CONF` | `/tmp/91-ipset-bbrkn.conf` | Выходной файл правил ipset |
+| `RESOLVE_CONF` | `/tmp/92-resolve-bbrkn.conf` | Выходной файл правил server= |
+| `CHROME_SERVER` | `http://127.0.0.1:3000` | Адрес Chromium headless API |
+| `DNS_SERVER` | `8.8.8.8` | DNS-сервер для резолвинга через VPN |
+| `IGNORE_PARTS` | _(пусто)_ | Подстроки через пробел — домены с совпадением игнорируются |
+| `CACHE_DIR` | `.cache/api` | Директория кэша API-ответов |
+| `CACHE_TTL_DAYS` | `15` | Время жизни кэша в днях; `0` — отключить кэш |
+| `STRICT_MODE` | `0` | `1` — завершать с кодом 1 при любых ошибках API |
+| `DEBUG` | `0` | `1` — включить подробный лог |
+| `DEBUG_LOG` | `/tmp/generate-configs.debug.log` | Путь к файлу отладочного лога |
+
+### deploy-to-gateway.sh
+
+| Переменная | По умолчанию | Описание |
+|---|---|---|
+| `TARGET_DIR` | `/opt/appdata/pihole/etc/dnsmasq.d` | Директория dnsmasq в Pi-hole |
+| `IPSET_CONF` | `/tmp/91-ipset-bbrkn.conf` | Сгенерированный файл ipset |
+| `RESOLVE_CONF` | `/tmp/92-resolve-bbrkn.conf` | Сгенерированный файл server= |
+| `DOCKER_CONTAINER` | `pihole` | Имя Docker-контейнера Pi-hole |
+| `DNS_LISTEN_ADDR` | `127.0.0.1` | Адрес, на котором Pi-hole слушает DNS |
+| `DNS_CHECK_DOMAIN` | `google.com` | Домен для DNS health check после рестарта |
+
+---
+
+## Кэш API-ответов
+
+При каждом запуске ответы Chromium API сохраняются в `$CACHE_DIR/<domain>.json`. При повторном запуске:
+
+- Если файл кэша **свежее** `CACHE_TTL_DAYS` дней → ответ берётся из кэша, Chromium не запускается.
+- Если файл **старше** TTL → перезапрашивается и кэш обновляется.
+- Если кэш **повреждён** (невалидный JSON) → перезапрашивается автоматически.
+
+На self-hosted runner workspace сохраняется между запусками, поэтому повторные CI-запуски значительно быстрее.
+
+```bash
+# Сбросить кэш и запросить всё заново
+make cache-clean && make generate
+
+# Отключить кэш для одного запуска
+CACHE_TTL_DAYS=0 make generate
+```
+
+---
+
+## Деплой и автооткат
+
+`deploy-to-gateway.sh` выполняет следующие шаги:
+
+1. Проверяет наличие сгенерированных конфигов.
+2. Создаёт timestamped-бэкапы текущих конфигов в `TARGET_DIR`.
+3. Копирует новые конфиги в `TARGET_DIR`.
+4. Перезапускает контейнер Pi-hole.
+5. Ждёт запуска (до 30 секунд, polling через `docker inspect`).
+6. Выполняет DNS health check через `dig` / `nslookup`.
+7. При ошибке на шагах 5 или 6 — **автоматически откатывается**: восстанавливает бэкапы и перезапускает контейнер со старой конфигурацией.
+
+---
+
+## Запуск вручную
+
+```bash
+# Полный цикл
+make all
+
+# Только генерация (без деплоя)
+make generate
+
+# Dry-run — проверить что будет сгенерировано, ничего не записывать
+./scripts/generate-configs.sh --dry-run
+
+# Отладочный режим
+DEBUG=1 make generate
+
+# Строгий режим — завершить с ошибкой если часть доменов не опросилась
+STRICT_MODE=1 make generate
+```
+
+---
+
+## CI/CD
+
+Workflow запускается при push в `main`, а также **вручную из UI** (`workflow_dispatch`).
+
+```
+push → main
+  └─ make clean
+  └─ make all
+       ├─ generate-configs.sh   (генерация с кэшем)
+       └─ deploy-to-gateway.sh  (деплой + rollback)
+  └─ upload artifacts (конфиги + debug-лог, даже при падении)
+```
+
+Self-hosted runner работает непосредственно на шлюзе, поэтому деплой происходит локально без SSH.
+
+---
+
+## Пример отчёта
 
 ```
 ===== DEBUG REPORT =====
-Input file: domains.txt
-Raw input lines: 100
-Processed lines: 100
-Normalized OK: 97
-Normalized skipped: 3
+Input file:              domains.txt
+Raw input lines:         170
+Processed lines:         170
+Normalized OK:           165
+Normalized skipped:      5
+Ignored (IGNORE_PARTS):  12
 
-API success (sites): 25
-API error/ignored: 5
-Related domains added: 122
-Final unique domains: 140
+Cache hits:              148  (TTL: 15d, dir: .cache/api)
+Cache expired/refetched: 3
+API success (sites):     11
+API error/failed:        3
+Related domains added:   87
+Final unique domains:    256
 
 ---- VALID BASE SITES ----
-example1.com
-example2.org
-example3.info
+example.com
+another-site.org
+...
+
+---- API FAILURES (added without subdomains) ----
+some-domain.com → api_failed_added_without_subdomains
+...
+
 ===== END DEBUG REPORT =====
 ```
 
@@ -178,9 +223,14 @@ example3.info
 
 ## Зависимости
 
-* `bash`
-* `curl`
-* `jq`
+| Инструмент | Где используется |
+|---|---|
+| `bash` 4.2+ | оба скрипта |
+| `curl` | запросы к Chromium API |
+| `jq` | парсинг JSON-ответов |
+| `docker` | перезапуск Pi-hole |
+| `ipset` | сброс маршрутов после деплоя |
+| `dig` или `nslookup` | DNS health check (опционально) |
 
 ---
 
diff --git a/scripts/deploy-to-gateway.sh b/scripts/deploy-to-gateway.sh
index 3308236..3205164 100644
--- a/scripts/deploy-to-gateway.sh
+++ b/scripts/deploy-to-gateway.sh
@@ -10,40 +10,130 @@ RESOLVE_CONF="${RESOLVE_CONF:-/tmp/92-resolve-bbrkn.conf}"
 
 DOCKER_CONTAINER="${DOCKER_CONTAINER:-pihole}"
 
+# Адрес, на котором слушает Pi-hole DNS (для health check)
+DNS_LISTEN_ADDR="${DNS_LISTEN_ADDR:-127.0.0.1}"
+# Домен для проверки DNS после рестарта
+DNS_CHECK_DOMAIN="${DNS_CHECK_DOMAIN:-google.com}"
+
+# Имена назначения (без basename — используем параметрическую подстановку)
+ipset_name="${IPSET_CONF##*/}"
+resolve_name="${RESOLVE_CONF##*/}"
+ipset_dest="$TARGET_DIR/$ipset_name"
+resolve_dest="$TARGET_DIR/$resolve_name"
+
+# Пути к бэкапам (заполняются ниже, нужны для rollback)
+IPSET_BACKUP=""
+RESOLVE_BACKUP=""
+
 echo "Deploying configuration files to $TARGET_DIR"
 
-# Проверка существования сгенерированных файлов
+# ==============================
+# Проверка входных файлов
+# ==============================
 if [ ! -f "$IPSET_CONF" ] || [ ! -f "$RESOLVE_CONF" ]; then
-    echo "Error: one or both config files not found!"
-    exit 1
+  echo "Error: one or both config files not found!"
+  exit 1
 fi
 
+# ==============================
+# Функция отката: восстанавливает бэкапы и перезапускает контейнер
+# ==============================
+rollback() {
+  echo "[ROLLBACK] Restoring previous configuration..."
+  local restored=false
+  if [ -n "$IPSET_BACKUP" ] && [ -f "$IPSET_BACKUP" ]; then
+    cp "$IPSET_BACKUP" "$ipset_dest"
+    echo "[ROLLBACK] Restored $ipset_dest"
+    restored=true
+  fi
+  if [ -n "$RESOLVE_BACKUP" ] && [ -f "$RESOLVE_BACKUP" ]; then
+    cp "$RESOLVE_BACKUP" "$resolve_dest"
+    echo "[ROLLBACK] Restored $resolve_dest"
+    restored=true
+  fi
+  if $restored; then
+    echo "[ROLLBACK] Restarting $DOCKER_CONTAINER with previous config..."
+    docker restart "$DOCKER_CONTAINER" 2>/dev/null || true
+  else
+    echo "[ROLLBACK] No backups found, cannot restore"
+  fi
+  echo "[ROLLBACK] Done"
+}
+
+# ==============================
 # Бэкап существующих файлов
-if [ -f "$TARGET_DIR/$(basename "$IPSET_CONF")" ]; then
-    cp "$TARGET_DIR/$(basename "$IPSET_CONF")" "$TARGET_DIR/$(basename "$IPSET_CONF").backup.$(date +%Y%m%d-%H%M%S)"
+# ==============================
+ts=$(date +%Y%m%d-%H%M%S)
+if [ -f "$ipset_dest" ]; then
+  IPSET_BACKUP="${ipset_dest}.backup.${ts}"
+  cp "$ipset_dest" "$IPSET_BACKUP"
+  echo "Backed up $ipset_dest → $IPSET_BACKUP"
 fi
-if [ -f "$TARGET_DIR/$(basename "$RESOLVE_CONF")" ]; then
-    cp "$TARGET_DIR/$(basename "$RESOLVE_CONF")" "$TARGET_DIR/$(basename "$RESOLVE_CONF").backup.$(date +%Y%m%d-%H%M%S)"
+if [ -f "$resolve_dest" ]; then
+  RESOLVE_BACKUP="${resolve_dest}.backup.${ts}"
+  cp "$resolve_dest" "$RESOLVE_BACKUP"
+  echo "Backed up $resolve_dest → $RESOLVE_BACKUP"
 fi
 
+# ==============================
 # Копирование новых файлов
-cp "$IPSET_CONF" "$TARGET_DIR/"
+# ==============================
+cp "$IPSET_CONF"   "$TARGET_DIR/"
 cp "$RESOLVE_CONF" "$TARGET_DIR/"
 
+# ==============================
 # Перезапуск контейнера
+# ==============================
 echo "Restarting $DOCKER_CONTAINER container..."
 docker restart "$DOCKER_CONTAINER"
 
-sleep 25
-if ! docker ps | grep -q "$DOCKER_CONTAINER"; then
-    echo "Error: $DOCKER_CONTAINER container failed to start"
-    exit 1
-fi
+# Ждём запуска — polling через docker inspect вместо sleep + docker ps
+echo "Waiting for $DOCKER_CONTAINER to be ready (up to 30s)..."
+ready=false
+for i in $(seq 1 30); do
+  status=$(docker inspect "$DOCKER_CONTAINER" --format '{{.State.Status}}' 2>/dev/null || echo "missing")
+  if [ "$status" = "running" ]; then
+    ready=true
+    break
+  fi
+  sleep 1
+done
 
+if ! $ready; then
+  echo "Error: $DOCKER_CONTAINER failed to start after 30s (status: $status)"
+  rollback
+  exit 1
+fi
+echo "$DOCKER_CONTAINER is running"
+
+# ==============================
+# DNS health check
+# ==============================
+dns_health_check() {
+  if command -v dig >/dev/null 2>&1; then
+    dig +short +time=3 +tries=2 "@$DNS_LISTEN_ADDR" "$DNS_CHECK_DOMAIN" >/dev/null 2>&1
+  elif command -v nslookup >/dev/null 2>&1; then
+    nslookup "$DNS_CHECK_DOMAIN" "$DNS_LISTEN_ADDR" >/dev/null 2>&1
+  else
+    echo "Warning: neither 'dig' nor 'nslookup' found, skipping DNS health check"
+    return 0
+  fi
+}
+
+echo "Running DNS health check ($DNS_CHECK_DOMAIN via $DNS_LISTEN_ADDR)..."
+if ! dns_health_check; then
+  echo "Error: DNS health check failed — Pi-hole not responding on $DNS_LISTEN_ADDR"
+  rollback
+  exit 1
+fi
+echo "DNS health check passed"
+
+# ==============================
 # Очистка IPSET
+# ==============================
 echo "Flushing ipset bbrkn..."
-ipset flush bbrkn 
+ipset flush bbrkn
 
 echo "Deployment completed successfully"
-DOMAIN_COUNT=$(grep -c '^ipset=' "$TARGET_DIR/$(basename "$IPSET_CONF")" || echo "0")
+DOMAIN_COUNT=$(grep -c '^ipset=' "$ipset_dest" || echo "0")
 echo "Applied configuration for $DOMAIN_COUNT domains"
diff --git a/scripts/generate-configs.sh b/scripts/generate-configs.sh
index 218406a..e9e234b 100644
--- a/scripts/generate-configs.sh
+++ b/scripts/generate-configs.sh
@@ -19,6 +19,13 @@ IGNORE_PARTS="${IGNORE_PARTS:-}"
 DEBUG="${DEBUG:-0}"
 DEBUG_LOG="${DEBUG_LOG:-/tmp/generate-configs.debug.log}"
 
+# Кэш API-ответов. TTL в днях; 0 — отключить кэш.
+CACHE_DIR="${CACHE_DIR:-.cache/api}"
+CACHE_TTL_DAYS="${CACHE_TTL_DAYS:-15}"
+
+# При STRICT_MODE=1 завершается с кодом 1 если есть ошибки API
+STRICT_MODE="${STRICT_MODE:-0}"
+
 DRY_RUN=false
 if [[ "${1:-}" == "--dry-run" ]]; then
   DRY_RUN=true
@@ -26,20 +33,21 @@ fi
 
 # Helpers
 log()  { printf '%s\n' "$*"; }
-dbg()  { if [ "$DEBUG" != "0" ]; then printf '[DEBUG] %s\n' "$*" | tee -a "$DEBUG_LOG"; fi }
-err()  { printf '[ERROR] %s\n' "$*" | tee -a "$DEBUG_LOG" >&2; }
+dbg()  { if [ "$DEBUG" != "0" ]; then printf '[DEBUG] %s\n' "$*" | tee -a "$DEBUG_LOG" >&2; fi; }
+err()  { printf '[ERROR] %s\n' "$*" >&2; }
+warn() { printf '[WARN]  %s\n' "$*" >&2; }
 
 if ! command -v curl >/dev/null 2>&1; then err "curl is required"; exit 2; fi
-if ! command -v jq >/dev/null 2>&1; then err "jq is required"; exit 2; fi
+if ! command -v jq   >/dev/null 2>&1; then err "jq is required";   exit 2; fi
 
 if [ "$DEBUG" != "0" ]; then : > "$DEBUG_LOG"; dbg "Debugging enabled"; fi
 
 log "Starting generate-configs.sh"
-dbg "ENV: INPUT_FILE=$INPUT_FILE IPSET_CONF=$IPSET_CONF RESOLVE_CONF=$RESOLVE_CONF API_URL=$API_URL DNS_SERVER=$DNS_SERVER IGNORE_PARTS='$IGNORE_PARTS' DRY_RUN=$DRY_RUN"
+dbg "ENV: INPUT_FILE=$INPUT_FILE IPSET_CONF=$IPSET_CONF RESOLVE_CONF=$RESOLVE_CONF API_URL=$API_URL DNS_SERVER=$DNS_SERVER IGNORE_PARTS='$IGNORE_PARTS' DRY_RUN=$DRY_RUN CACHE_DIR=$CACHE_DIR CACHE_TTL_DAYS=$CACHE_TTL_DAYS STRICT_MODE=$STRICT_MODE"
 
-if ! $DRY_RUN; then
-  : > "$IPSET_CONF"
-  : > "$RESOLVE_CONF"
+if [ ! -f "$INPUT_FILE" ]; then
+  err "Input file not found: $INPUT_FILE"
+  exit 3
 fi
 
 declare -A DOM_ROLE
@@ -47,8 +55,7 @@ declare -A EXPANDED
 declare -A SOURCES
 declare -A ERRORS
 declare -A VALID_SITES
-
-# для отчёта по игнорируемым доменам
+declare -A SITE_RELATED   # base_domain -> space-separated list of its related domains
 declare -A IGNORED_DOMAINS
 
 total_lines=0
@@ -58,17 +65,24 @@ api_success=0
 api_error=0
 related_total=0
 ignored_total=0
+cache_hit=0
+cache_expired=0
 
+# Оптимизировано: ~1 подпроцесс на вызов (вместо 6 в оригинале).
+# Регекс проверяет RFC 1123: каждый лейбл начинается и заканчивается буквой/цифрой.
 normalize_domain() {
-  local raw="$1"
-  raw="$(printf '%s' "$raw" | sed -E 's/#.*$//' | awk '{$1=$1};1')"
+  local raw="${1%%#*}"                           # strip inline comment (bash)
+  raw="${raw#"${raw%%[! $'\t']*}"}"              # ltrim whitespace (bash)
+  raw="${raw%"${raw##*[! $'\t']}"}"              # rtrim whitespace (bash)
   [ -z "$raw" ] && return 1
-  raw="$(printf '%s' "$raw" | tr '[:upper:]' '[:lower:]')"
-  raw="$(printf '%s' "$raw" | sed -E 's/^\*\.\s*//; s/^\.+//; s/\.+$//; s/\.+/./g')"
-  if ! printf '%s' "$raw" | grep -Eq '^[a-z0-9-]+(\.[a-z0-9-]+)+$'; then return 1; fi
-  if ! printf '%s' "$raw" | grep -Eq '\.[a-z0-9-]{2,}$'; then return 2; fi
+  raw="${raw,,}"                                 # lowercase (bash builtin)
+  raw="${raw#\*.}"                               # strip wildcard prefix (bash)
+  raw=$(sed -E 's/^\.+//; s/\.+$//; s/\.+/./g' <<< "$raw")  # normalize dots (1 subprocess)
+  [ -z "$raw" ] && return 1
+  # RFC 1123: каждый лейбл начинается и заканчивается на [a-z0-9], внутри допустимы дефисы
+  [[ "$raw" =~ ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$ ]] || return 1
+  [[ "$raw" =~ \.[a-z0-9-]{2,}$ ]] || return 2  # TLD минимум 2 символа
   printf '%s' "$raw"
-  return 0
 }
 
 should_ignore_domain() {
@@ -83,14 +97,77 @@ should_ignore_domain() {
   return 1
 }
 
-if [ ! -f "$INPUT_FILE" ]; then
-  err "Input file not found: $INPUT_FILE"
-  exit 3
-fi
-
-raw_total_lines=$(wc -l < "$INPUT_FILE" | tr -d ' ')
+# raw_total_lines через awk корректно считает строки даже без финального \n
+raw_total_lines=$(awk 'END{print NR}' "$INPUT_FILE")
 dbg "Raw input lines: $raw_total_lines"
 
+# Один tmp-файл для тела curl-ответа — создаётся один раз, переиспользуется
+tmp_body=$(mktemp)
+trap 'rm -f "$tmp_body"' EXIT
+
+# Глобальная переменная для ответа API (избегаем subshell — счётчики сохраняются)
+RESP=""
+max_attempts=5
+
+# query_api <domain>
+#   Пишет ответ в RESP и возвращает 0 при успехе, 1 при полном провале.
+#   Кэширует успешные ответы в $CACHE_DIR/<domain>.json на $CACHE_TTL_DAYS дней.
+query_api() {
+  local dom="$1"
+  local cache_file="$CACHE_DIR/${dom}.json"
+  RESP=""
+
+  # --- Проверяем кэш (если TTL > 0) ---
+  if [ "$CACHE_TTL_DAYS" -gt 0 ] && [[ -f "$cache_file" ]]; then
+    # find возвращает путь только если файл СТАРШЕ TTL; пустой вывод — кэш свежий
+    if ! find "$cache_file" -mtime "+${CACHE_TTL_DAYS}" 2>/dev/null | grep -q .; then
+      if jq -e . < "$cache_file" >/dev/null 2>&1; then
+        dbg "  -> Cache HIT for $dom (TTL: ${CACHE_TTL_DAYS}d)"
+        cache_hit=$((cache_hit + 1))
+        RESP=$(<"$cache_file")
+        return 0
+      fi
+      dbg "  -> Cache file corrupt for $dom, re-fetching"
+    else
+      dbg "  -> Cache EXPIRED for $dom"
+      cache_expired=$((cache_expired + 1))
+    fi
+  fi
+
+  # --- Запрос к API с повторными попытками ---
+  local attempt=0 http_code
+  while :; do
+    attempt=$((attempt + 1))
+    dbg "  -> API attempt #$attempt for $dom"
+    http_code=$(curl -sS --compressed -m 10 --connect-timeout 5 --retry 2 --retry-connrefused \
+         -H 'Accept: application/json' \
+         -o "$tmp_body" -w '%{http_code}' \
+         "${API_URL}${dom}" 2>>"$DEBUG_LOG" || echo "000")
+
+    if [ "$http_code" = "200" ] && jq -e . < "$tmp_body" >/dev/null 2>&1; then
+      if [ "$CACHE_TTL_DAYS" -gt 0 ]; then
+        mkdir -p "$CACHE_DIR"
+        cp "$tmp_body" "$cache_file"
+      fi
+      RESP=$(<"$tmp_body")
+      return 0
+    fi
+
+    dbg "  -> HTTP=$http_code"
+
+    if [ "$attempt" -ge "$max_attempts" ]; then
+      return 1
+    fi
+
+    sleep_time=$(( 1 << (attempt - 1) ))
+    dbg "  -> Retry after ${sleep_time}s..."
+    sleep "$sleep_time"
+  done
+}
+
+# ==============================
+# Основной цикл обработки доменов
+# ==============================
 lineno=0
 while IFS= read -r line || [ -n "$line" ]; do
   lineno=$((lineno+1))
@@ -106,66 +183,36 @@ while IFS= read -r line || [ -n "$line" ]; do
   normalized_ok=$((normalized_ok+1))
   dbg "  -> NORMALIZED: $dom_norm"
 
-  # Игнорируем по подстрокам
   if should_ignore_domain "$dom_norm"; then
     ignored_total=$((ignored_total+1))
     continue
   fi
 
-  max_attempts=5
-  attempt=0
-  resp=""
-  http_code=0
-
-  while :; do
-    attempt=$((attempt+1))
-    tmp_body=$(mktemp)
-    tmp_header=$(mktemp)
-
-    dbg "  -> API attempt #$attempt for $dom_norm"
-    curl -sS --compressed -m 10 --connect-timeout 5 --retry 2 --retry-connrefused \
-         -H 'Accept: application/json' \
-         -D "$tmp_header" -o "$tmp_body" "${API_URL}${dom_norm}" 2>>"$DEBUG_LOG" || true
-
-    http_code=$(awk '/^HTTP/{code=$2} END{print code}' "$tmp_header")
-    resp=$(cat "$tmp_body")
-    rm -f "$tmp_body" "$tmp_header"
-
-    preview="$(printf '%s' "$resp" | tr '\n' ' ' | cut -c1-400)"
-    dbg "  -> HTTP=$http_code, preview=$preview"
-
-    if [ "$http_code" = "200" ] && jq -e . >/dev/null 2>&1 <<<"$resp"; then
-      break
-    fi
-
-    if [ "$attempt" -ge "$max_attempts" ]; then
-      api_error=$((api_error+1))
-      ERRORS["$dom_norm"]="http_${http_code}_or_nonjson"
-      dbg "  -> Failed after ${attempt} attempts: HTTP=${http_code}, preview=${preview}"
-      resp=""
-      break
-    fi
-
-    sleep_time=$(( 1 << (attempt - 1) ))
-    dbg "  -> Retry after ${sleep_time}s..."
-    sleep "$sleep_time"
-  done
-
-  if [ -z "$resp" ] || ! jq -e . >/dev/null 2>&1 <<<"$resp"; then
-    dbg "  -> non-JSON or empty response, skipping domain: $dom_norm"
+  if ! query_api "$dom_norm"; then
+    # API полностью недоступен (не 200 / не JSON после всех попыток).
+    # Домен явно указан в domains.txt — добавляем без субдоменов и фиксируем в отчёте.
+    api_error=$((api_error+1))
+    ERRORS["$dom_norm"]="api_failed_added_without_subdomains"
+    dbg "  -> Failed after $max_attempts attempts, adding as fallback (no subdomains)"
+    DOM_ROLE["$dom_norm"]="service"
+    SOURCES["$dom_norm"]="base"
+    EXPANDED["$dom_norm"]=1
     continue
   fi
+  resp="$RESP"
 
   if jq -e 'has("error")' <<<"$resp" >/dev/null; then
     err_msg="$(jq -r '.error' <<<"$resp")"
     dbg "  -> API error: $err_msg"
     if grep -Eq "ERR_NAME_NOT_RESOLVED|Timeout" <<<"$err_msg"; then
+      # Домен не резолвится в DNS — бессмысленно добавлять в маршрутизацию
       continue
     fi
+    # Не-HTTP сервис (SMTP, игровой сервер, VPN и т.п.) — домен существует в DNS,
+    # но Chromium не может его обойти. Добавляем без субдоменов. Это не ошибка.
     DOM_ROLE["$dom_norm"]="service"
     SOURCES["$dom_norm"]="base"
     EXPANDED["$dom_norm"]=1
-    ERRORS["$dom_norm"]="$err_msg"
     continue
   fi
 
@@ -186,34 +233,88 @@ while IFS= read -r line || [ -n "$line" ]; do
       continue
     fi
 
+    # Инкрементируем related_total только для новых доменов (фикс дублей)
+    [ -z "${EXPANDED[$nd]:-}" ] && related_total=$((related_total+1))
     EXPANDED["$nd"]=1
     [ -z "${SOURCES[$nd]:-}" ] && SOURCES["$nd"]="related"
-    related_total=$((related_total+1))
+    SITE_RELATED["$dom_norm"]+="$nd "
   done
 done < "$INPUT_FILE"
 
+# ==============================
+# Строим упорядоченный список: базовые домены + их субдомены, с комментариями
+# ==============================
+declare -A WRITTEN=()
+declare -A OUTPUT_COMMENT=()
+declare -a ORDERED_DOMS=()
+
+for dom in $(printf '%s\n' "${!EXPANDED[@]}" | sort -u); do
+  [[ "${SOURCES[$dom]:-}" == "related" ]] && continue
+
+  # Собираем ещё не записанные связанные домены.
+  # while выполняется в subshell — читает снимок WRITTEN, что корректно исключает
+  # домены, уже занятые предыдущим базовым доменом.
+  mapfile -t base_related < <(
+    if [[ -n "${SITE_RELATED[$dom]:-}" ]]; then
+      tr ' ' '\n' <<< "${SITE_RELATED[$dom]}" | grep -v '^$' | sort -u | \
+        while IFS= read -r rd; do
+          [[ -z "${WRITTEN[$rd]:-}" ]] && printf '%s\n' "$rd"
+        done
+    fi
+  )
+
+  OUTPUT_COMMENT["$dom"]="# ${dom} — ${#base_related[@]} subdomains"
+  ORDERED_DOMS+=("$dom")
+  WRITTEN["$dom"]=1
+
+  for rd in "${base_related[@]+"${base_related[@]}"}"; do
+    ORDERED_DOMS+=("$rd")
+    WRITTEN["$rd"]=1
+  done
+done
+
+# Все оставшиеся домены (related чей базовый пропущен/упал с ошибкой)
+for dom in $(printf '%s\n' "${!EXPANDED[@]}" | sort -u); do
+  [[ -n "${WRITTEN[$dom]:-}" ]] && continue
+  ORDERED_DOMS+=("$dom")
+done
+
 mapfile -t ALL_DOMAINS < <(printf "%s\n" "${!EXPANDED[@]}" | sort -u)
 
+# Записываем конфиги одним батчем (не по одной строке через >>)
 if ! $DRY_RUN; then
-  for d in "${ALL_DOMAINS[@]}"; do
-    printf 'ipset=/%s/bbrkn\n' "$d" >> "$IPSET_CONF"
-    printf 'server=/%s/%s\n' "$d" "$DNS_SERVER" >> "$RESOLVE_CONF"
-  done
+  {
+    for d in "${ORDERED_DOMS[@]}"; do
+      [[ -n "${OUTPUT_COMMENT[$d]:-}" ]] && printf '%s\n' "${OUTPUT_COMMENT[$d]}"
+      printf 'ipset=/%s/bbrkn\n' "$d"
+    done
+  } > "$IPSET_CONF"
+  {
+    for d in "${ORDERED_DOMS[@]}"; do
+      [[ -n "${OUTPUT_COMMENT[$d]:-}" ]] && printf '%s\n' "${OUTPUT_COMMENT[$d]}"
+      printf 'server=/%s/%s\n' "$d" "$DNS_SERVER"
+    done
+  } > "$RESOLVE_CONF"
 fi
 
+# ==============================
+# Итоговый отчёт
+# ==============================
 echo
 echo "===== DEBUG REPORT ====="
-echo "Input file: $INPUT_FILE"
-echo "Raw input lines: $raw_total_lines"
-echo "Processed lines: $total_lines"
-echo "Normalized OK: $normalized_ok"
-echo "Normalized skipped: $normalized_skip"
-echo "Ignored (by IGNORE_PARTS): $ignored_total"
+echo "Input file:              $INPUT_FILE"
+echo "Raw input lines:         $raw_total_lines"
+echo "Processed lines:         $total_lines"
+echo "Normalized OK:           $normalized_ok"
+echo "Normalized skipped:      $normalized_skip"
+echo "Ignored (IGNORE_PARTS):  $ignored_total"
 echo
-echo "API success (sites): $api_success"
-echo "API error/ignored: $api_error"
-echo "Related domains added: $related_total"
-echo "Final unique domains: ${#ALL_DOMAINS[@]}"
+echo "Cache hits:              $cache_hit  (TTL: ${CACHE_TTL_DAYS}d, dir: $CACHE_DIR)"
+echo "Cache expired/refetched: $cache_expired"
+echo "API success (sites):     $api_success"
+echo "API error/failed:        $api_error"
+echo "Related domains added:   $related_total"
+echo "Final unique domains:    ${#ALL_DOMAINS[@]}"
 echo
 echo "---- VALID BASE SITES ----"
 printf '%s\n' "${!VALID_SITES[@]}" | sort
@@ -223,9 +324,25 @@ if [ "$ignored_total" -gt 0 ]; then
   for d in $(printf '%s\n' "${!IGNORED_DOMAINS[@]}" | sort); do
     printf '%s (matched: %s)\n' "$d" "${IGNORED_DOMAINS[$d]}"
   done
+  echo
+fi
+if [ "${#ERRORS[@]}" -gt 0 ]; then
+  echo "---- API FAILURES (added without subdomains) ----"
+  for d in $(printf '%s\n' "${!ERRORS[@]}" | sort); do
+    printf '%s → %s\n' "$d" "${ERRORS[$d]}"
+  done
+  echo
 fi
 echo "===== END DEBUG REPORT ====="
 
 if [ "$DEBUG" != "0" ]; then
   echo "Detailed debug log: $DEBUG_LOG"
 fi
+
+# Завершаемся с ошибкой если STRICT_MODE=1 и были провалы API
+if [ "$api_error" -gt 0 ]; then
+  warn "$api_error domain(s) failed API queries — see FAILED DOMAINS in report above"
+  if [ "$STRICT_MODE" != "0" ]; then
+    exit 1
+  fi
+fi