dotfiles/.scratch/proxy-client-simplify/spec.md

Упрощение proxy-client

Status: ready-for-agent

Зачем

proxy-client — личный клиент для владельца и нескольких друзей, а не промышленное ПО. Большая часть кода и тестов — защита от сценариев, которые на личной машине не случаются (повторное использование PID, подложный state.json, zip-бомба в проверенном по SHA-256 официальном архиве, гонка status с параллельным start). Эта защита стоит сотни строк кода и тестов и около минуты прогона. Цель — оставить существенную сложность и убрать случайную.

Принцип: простой код, который честно делает своё дело и понятно сообщает об ошибке. Не защищаемся от самого пользователя и от его собственных файлов.

Что сохраняем (обязательное поведение)

• Команды и их договор: install [--replace], status, env, run -- CMD, start [-f FILE], stop; коды выхода (2 без подкоманды, 127 — команда не найдена, 128+N — дочерний процесс убит сигналом N); восемь proxy-переменных.
• Отказ без запасного пути: выбран Xray, но он не запущен — ошибка, а не переход на Hiddify.
• Машинный INI: строгий формат как сейчас (он маленький и понятный).
• Разбор VLESS: поддерживаемые TCP/REALITY и XHTTP/TLS, VLESS-шифрование mlkem768x25519plus, неизвестные query-параметры отклоняются.
• Точная версия Xray 26.3.27 для install и start (сознательное решение).
• Установка Xray: официальный архив, проверка SHA-256 по .dgst, атомарная замена через временный каталог рядом с назначением; --replace не пишет через симлинк; неудачная установка не портит старый бинарник.
• start только на loopback-адресе; занятый порт — понятная ошибка.
• Не выводим UUID, ключи REALITY и path XHTTP в stdout/stderr.
• client.json и state.json — права 600 в каталоге 700 (в них секреты).
• Один управляемый Xray за раз: блокировка flock на время start.
• Остановка: Ctrl+C или stop гасят Xray и удаляют служебные файлы; если супервизор убит (SIGKILL), stop добивает оставшийся Xray и чистит файлы.
• Python 3.8+ (у друзей старые дистрибутивы), только стандартная библиотека.

Что упрощаем

1. Проверка «тот ли процесс». Вместо boot_id + starttime + /proc/PID/exe
   • разрешения argv супервизора относительно его cwd: Xray — PID жив и /proc/PID/exe совпадает с xray_path; супервизор — PID жив (и, если дёшево, его cmdline упоминает proxy-client). Непохожий процесс считаем мёртвым: сигнал не шлём, файлы считаем устаревшими и чистим. Состояние «не удалось подтвердить, удалите файлы вручную» исчезает. Двойная проверка под блокировкой при чистке устаревших файлов не нужна. state.json читаем без строгой схемы: битый файл — понятная ошибка с путём.
2. Скачивание Xray. Убрать три уровня ограничений размера, сверку Content-Length, строгую грамматику .dgst. Достаточно: скачать, найти в .dgst строку SHA2-256=, сравнить без учёта регистра. Убрать O_EXCL/0600 для кандидата внутри закрытого временного каталога и требование «каталог установки внутри $HOME».
3. install и работающий Xray. Замена бинарника под работающим процессом на Linux безопасна: не блокировать install, а напомнить перезапустить start. Блокировку start на время install не брать.
4. Разбор ссылки. extra — обычный json.loads + проверка, что это объект (без своих проверок повторных ключей и NaN: xray run -test проверит). allowInsecure/insecure — принимаются с любым значением и игнорируются; при истинном значении (1, true) — предупреждение.
5. Установщик пакета proxy-client/install.sh. Один способ — прямые симлинки (без Stow). Не перезаписывать чужие файлы и сообщить обо всех конфликтах сразу. Разрешить ~/.local и ~/.config, которые сами являются ссылками. Блок в ~/.bashrc — дописать, если нет маркера; без разбора «повреждённых» блоков, поиска .bash_custom и точного текста export PATH.
6. Подсказки об ошибках с файлами называют файл полным путём и дают готовую команду. Пример: «файл профиля /home/u/.config/proxy-client/default.url доступен другим пользователям; выполните: chmod 600 /home/u/...». Если профиль — симлинк, называть конечный файл (права ставятся на него).

Где живут тесты (согласовано с владельцем)

1. Команда proxy-client: argv → код выхода, вывод, созданные файлы, запущенные и остановленные процессы.
2. Разбор ссылки: parse_vless + build_xray_config (ссылка → JSON Xray) — быстрые табличные тесты без запуска процессов.
3. Установка Xray: command_install с подставляемым скачивателем.
4. Функции Bash: через поддельный исполняемый файл в PROXY_CLIENT_BIN.
5. Установщик пакета: через временный HOME.

Больше нигде. Запрещено: подмена внутренних функций через __globals__ / mock.patch.dict, проверки порядка внутренних вызовов, тесты тестовых подделок, по нескольку полных циклов start/stop ради одного утверждения.

Задачи

• issues/01-cli.md — CLI и Python-тесты.
• issues/02-installer-shell.md — установщик пакета, shell-тесты, запускалка.
• После 01 и 02 (делает оркестратор): привести разделы docs/specs/2026-07-15-proxy-client-design.md про установку, жизненный цикл, доставку, риски и проверку в соответствие с кодом; добавить в proxy-client/README.md ссылку на спецификацию для тех, кто меняет код.