iptvc/AGENTS.md

Контекст проекта: IPTV Checker (iptvc)

Важно: Этот файл создан автоматически на основе анализа кодовой базы. Используй его как справочный контекст при внесении изменений.

---

Обзор проекта

IPTV Checker (iptvc) — консольная утилита для проверки доступности IPTV-плейлистов и каналов в форматах m3u / m3u8.

• Назначение: Быстрая массовая проверка плейлистов из файлов, по URL или из INI-реестра с расчётом статистики (online/offline).
• Экосистема: Часть проекта m3u.su.
• Лицензия: MIT (см. LICENSE).
• Автор: Антон Аксенов.

Основные технологии

• Язык: Go 1.23.6+
• CLI-фреймворк: spf13/cobra
• Кеширование: Redis / KeyDB (опционально, через go-redis/v9)
• Конфигурация окружения: godotenv + переменные окружения
• Парсинг INI: gopkg.in/ini.v1

Архитектура

Приложение построено по классической для Go CLI схеме:

cmd/          — команды Cobra (root, check)
app/          — бизнес-логика и инфраструктура
  app.go      — инициализация конфигурации, логгера, кеша; глобальные аргументы
  checker/    — ядро проверки: подготовка списков, HTTP-опрос каналов, семафоры
  playlist/   — модели Playlist/Channel/Group, парсинг m3u/m3u8
  inifile/    — чтение реестра плейлистов из INI
  config/     — чтение конфигурации из env (.env)
  cache/      — подключение к Redis/KeyDB
  logger/     — настройка вывода логов
  tagfile/    — работа с файлом тегов (channels.json)
  utils/      — вспомогательные функции (MD5, Fetch, ExpandPath и др.)
main.go       — точка входа: контекст с отменой по сигналу, делегация cmd.ExecuteContext

---

Сборка и запуск

Локальная разработка

# Быстрый запуск из исходников
go run .

# Сборка бинаря
go build -o iptvc .

# Показать справку
./iptvc help

# Проверить плейлист из файла
./iptvc check -f mypls.m3u

# Проверить плейлист по ссылке
./iptvc check -u http://m3u.su/XYZ

# Проверить плейлисты из INI-файла
./iptvc check -i playlists.ini

# Только JSON-результат, без логов
./iptvc check -f mypls.m3u -j -q

Makefile

Команда	Описание
make help	Справка по целям
make fmt	go fmt ./...
make vet	go vet ./...
make tidy	go mod tidy && go mod verify
make lint	fmt + vet + сборка в /dev/null
make clean	Удаление скомпилированных бинарей и bin/
make linux	Сборка для Linux (GOARCH=amd64 по умолчанию)
make win	Сборка для Windows
make darwin	Сборка для macOS
make release	Полный релиз: все ОС × amd64 + arm64, упаковка в zip

Примечание: Переменная GOARCH переопределяется через окружение, например: make linux GOARCH=arm64.

Docker

# Ручная сборка образа
docker build -t iptvc:latest .

# Скрипт сборки и публикации (с версионированием через git-тег)
./build-docker-image.sh [TAG]

Dockerfile использует многоступенчатую сборку:

1. golang:1.25-alpine — компиляция бинаря (CGO_ENABLED=0, trimpath, ldflags)
2. alpine:3.22.2 — финальный минимальный образ с непривилегированным пользователем.

---

Конфигурация

Приложение читает переменные окружения (файл .env опционален).

Переменная	По умолчанию	Описание
CACHE_ENABLED	false	Включить подключение к кешу
CACHE_HOST	localhost	Хост Redis/KeyDB
CACHE_PORT	6379	Порт
CACHE_USERNAME	—	Пользователь
CACHE_PASSWORD	—	Пароль
CACHE_DB	0	Номер БД
CACHE_TTL	1800	TTL записей в секундах

Файл .env.example содержит пример заполнения.

---

Ключевые файлы и пакеты

Путь	Назначение
main.go	Точка входа: context.WithCancel, обработка SIGINT/SIGTERM, вызов cmd.ExecuteContext
cmd/root.go	Корневая команда Cobra, глобальный флаг --verbose
cmd/check.go	Команда check: флаги (-f, -u, -i, -c, -t, -r, -j, -q, --repeat, --every), цикл повторений, вызов checker
app/app.go	Глобальные объекты Args, Cache, Config; Init() и Shutdown()
app/checker/checker.go	Ядро: подготовка списков, скачивание плейлистов, HTTP-опрос каналов с семафором, динамический расчёт timeout/routines, кеширование результатов
app/playlist/playlist.go	Структуры Playlist, Channel, Group; парсинг m3u/m3u8 (атрибуты #EXTINF, #EXTGRP, заголовок #EXTM3U)
app/config/config.go	Чтение конфигурации из env с дефолтами
app/inifile/inifile.go	Чтение реестра плейлистов в формате INI
app/cache/cache.go	Инициализация клиента Redis/KeyDB
app/tagfile/tagfile.go	Загрузка и поиск тегов для каналов
app/utils/utils.go	Утилиты: Fetch, ExpandPath, Md5str, ArrayUnique
app/utils/utils_test.go	Тесты утилит
app/config/config_test.go	Тесты конфигурации
app/playlist/playlist_test.go	Тесты парсера плейлистов
docs/json.md	Документация по структуре JSON-вывода
build-docker-image.sh	Скрипт сборки и пуша Docker-образа с версией из git
Dockerfile	Многоступенчатая сборка контейнера

---

Правила разработки

Стиль кода

• Код оформлен в едином стиле с лидирующими комментариями-заголовками (автор, лицензия, ссылка на репозиторий).
• Используются экспортируемые имена с подробными комментариями на русском языке (доминирующий язык комментариев).
• Глобальные переменные приложения (Args, Cache, Config) расположены в app/app.go.

Тестирование

• Модульные тесты присутствуют для пакетов utils, config, playlist.
• Для запуска: go test ./....

Линтинг

• В Makefile есть цель lint, объединяющая go fmt, go vet и проверочную сборку.
• Перед коммитом рекомендуется выполнять make lint.

Работа с зависимостями

• Модули Go (go.mod / go.sum).
• Обновление/очистка: make tidy.

Соглашения по логике

• Динамические параметры проверки: количество горутин и HTTP-таймаут рассчитываются в calcParameters(count) на основе числа каналов. Чем больше каналов — тем больше параллелизм, но таймаут сокращается.
• Семафор: количество одновременных проверок ограничено через буферизированный канал (chSemaphores).
• User-Agent: при проверке каналов используется фиксированный заголовок Mozilla/5.0 WINK/1.31.1 (AndroidTV/9) HlsWinkPlayer.
• TLS: проверка выполняется с InsecureSkipVerify: true.
• Кеш: результаты проверки плейлистов сериализуются в JSON и сохраняются в Redis с TTL.

---

Коды возврата

Код	Значение
0	Успех
1	Общая ошибка
2	Команда check запущена без параметров -f, -u и -c (и нет INI по умолчанию)
130	Прерывание по сигналу (SIGINT / SIGTERM)