jellybit/docs/adr/ADR-2026-06-13-go-single-binary.md

Go и доставка одним бинарём

• Дата: 2026-06-13

Контекст

Jellybit — новый сервис, который будет жить на домашнем медиа-сервере umbar. Нужно выбрать язык и способ доставки. Силы и ограничения:

• Это домашняя лаборатория, хочется максимально простой доставки: собрал здесь — скопировал готовый артефакт на сервер, без рантайма и лишних зависимостей на самой машине.
• В umbar уже устоялось разделение: Python+uv используется вместе с Ansible (инфраструктура), а не для прикладных сервисов.
• У автора уже есть несколько сервисов на Go — это знакомый и привычный стек именно под сервисы.
• Сервису нужны: клиент qBittorrent, обращения к LLM, опц. клиенты TMDB/TVDB, разбор имён релизов.

Рассмотренные варианты

• Go — один статический бинарь (CGO_ENABLED=0), копируется на сервер; минимальный docker-образ. Знакомый стек. Минус: нет хорошего аналога питоновского guessit для разбора имён релизов.
• Python + uv — богатая экосистема распознавания (guessit), но тянет рантайм и зависимости на сервер; в проекте уже занят инфра-ролью при Ansible. Смешивать прикладной сервис с инфра-тулингом не хочется.
• TypeScript / Node — экосистема есть, но рантайм на сервере и не основной стек автора для сервисов.

Решение

Пишем jellybit на Go, доставляем одним статическим бинарём: сборка в этом репозитории → готовый артефакт с нужной обвязкой копируется на umbar. На сервере не нужны ни рантайм, ни менеджер пакетов.

Причина: при домашней лаборатории решающее — простота доставки и знакомство со стеком, а не богатство библиотек распознавания. Слабость Go в разборе имён релизов закрываем дешёвым go-ptn плюс основной разбор всё равно делает LLM; при нехватке точности guessit можно завернуть лёгким сервисом-спутником рядом с бинарём (тоже один файл). Python остаётся за инфраструктурой (umbar, Ansible).

Последствия

• + Доставка тривиальна: один файл, без рантайма и зависимостей на сервере; минимальный docker-образ.
• + Стек знаком автору, переиспользуется опыт других Go-сервисов.
• + Чёткая граница: Go — прикладные сервисы, Python+uv — инфра.
• - Нет первоклассного guessit; точность пред-парса ниже. Митигация: go-ptn + LLM, при необходимости — guessit-спутник.
• - Часть клиентов (например, TVDB v4) придётся писать руками — зрелых готовых библиотек меньше, чем в Python.