From 86d63ab2aac5b9b99da3c48f3f094dcc62860477 Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Tue, 21 Jul 2026 21:42:33 +0300 Subject: [PATCH] =?UTF-8?q?docs(proxy-client):=20=D1=81=D0=BF=D1=80=D0=BE?= =?UTF-8?q?=D0=B5=D0=BA=D1=82=D0=B8=D1=80=D0=BE=D0=B2=D0=B0=D0=BD=20=D1=81?= =?UTF-8?q?=D0=B0=D0=BC=D0=BE=D1=81=D1=82=D0=BE=D1=8F=D1=82=D0=B5=D0=BB?= =?UTF-8?q?=D1=8C=D0=BD=D1=8B=D0=B9=20=D1=83=D1=81=D1=82=D0=B0=D0=BD=D0=BE?= =?UTF-8?q?=D0=B2=D1=89=D0=B8=D0=BA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - отдельный пакет должен устанавливаться без общего dotfiles и обязательного stow. - Что: - зафиксирована единая раскладка симлинков через stow или ln. - отделены файлы пакета от машинного конфига и закрытого профиля. - добавлены правила конфликтов, настройки Bash и проверки установки. - Проверка: - git diff --cached --check. --- docs/specs/2026-07-15-proxy-client-design.md | 114 +++++++++++++++++-- 1 file changed, 102 insertions(+), 12 deletions(-) diff --git a/docs/specs/2026-07-15-proxy-client-design.md b/docs/specs/2026-07-15-proxy-client-design.md index 0345263..e4b3a4a 100644 --- a/docs/specs/2026-07-15-proxy-client-design.md +++ b/docs/specs/2026-07-15-proxy-client-design.md @@ -2,7 +2,8 @@ Дата: 2026-07-15 -Статус: реализация готова к ручной приёмке; публичное имя уточнено 2026-07-21 +Статус: основная реализация принята вручную; самостоятельный установщик +спроектирован 2026-07-21, но ещё не реализован ## Проблема @@ -48,8 +49,9 @@ proxy-переменных совместима с локальным Xray бе JSON Xray. - Сохранить совместимость Bash-функций с внешним Hiddify. - Позволить настраивать машинный `NO_PROXY` без правки файлов репозитория. -- Поддержать выборочную установку после `git clone`: через stow, ручные - симлинки или копирование. +- Поддержать самостоятельную установку из отдельно скопированного каталога + `proxy-client/` без зависимости от общего установщика dotfiles и без + обязательного stow. ## Не входит в объём @@ -89,6 +91,22 @@ Bash нужен только там, где необходимо изменит требует кода, но не решает основную боль: безопасный запуск `pclaude` и `pcodex` из точечной ссылки Hiddify. +### Доставка отдельного пакета + +Рассмотрены четыре способа подключить отдельно скопированный каталог: + +- оставить только инструкции для stow и ручных симлинков — просто, но сохраняет + легко забываемые шаги; +- копировать файлы в домашний каталог — не требует сохранять исходный каталог, + но усложняет обновления и расходится с моделью dotfiles; +- требовать stow — даёт привычное управление ссылками, но добавляет + необязательную зависимость на удалённых серверах; +- дать пакету собственный установщик, который использует stow при наличии и + создаёт те же симлинки напрямую без него. + +Выбран последний вариант. Он сохраняет один результат установки при разном +составе машины и не требует второй копии обновляемых файлов. + ## Рекомендуемое решение ### Границы компонентов @@ -376,15 +394,50 @@ CLI раскладывается как `~/.local/bin/proxy-client`. Машин `~/.config/proxy-client/`. Шаблоны не подменяют настоящие пользовательские файлы. -В корне этого каталога находится самостоятельный `README.md`. Он является -основной инструкцией клиента и исключается из раскладки stow. README остаётся -рядом с кодом при выборочном клонировании или копировании каталога. Корневой -README репозитория только кратко описывает подсистему и ссылается на него. +В корне этого каталога находятся самостоятельный `README.md` и пакетный +`install.sh`. Оба файла относятся к исходному каталогу и исключаются из +раскладки stow. README остаётся рядом с кодом при выборочном клонировании или +копировании каталога. Корневой README репозитория только кратко описывает +подсистему и ссылается на него. -После клонирования репозитория пакет можно подключить отдельно от общего -`install.sh`. README также должен описывать эквивалентные ручные симлинки и -копирование файлов. Полный `install.sh` подключает этот же stow-пакет вместе с -остальными dotfiles и не имеет отдельной реализации. +Пакетный установщик связывает отдельно скопированный каталог с домашним +каталогом и не зависит от положения или наличия остальных dotfiles. Если stow +доступен, установщик использует его; если нет — создаёт тот же набор симлинков +напрямую. Выбранный механизм явно показывается пользователю, но не меняет +результат. Исходный каталог должен оставаться на прежнем пути всё время +использования ссылок. + +Установщик управляет только тремя публичными артефактами: CLI, `shell.bash` и +каталогом шаблонов. Машинный `config` и закрытый `default.url` не входят в +раскладку stow, никогда не создаются, не заменяются и не связываются +установщиком. Их наличие в исходном каталоге также не должно расширять набор +управляемых путей. + +Домашние `~/.local/bin` и `~/.config/proxy-client` остаются настоящими +каталогами. Stow не должен сворачивать их или их родителей в одну ссылку на +исходное дерево: ссылками становятся только три перечисленных артефакта. Это +одновременно сохраняет место для машинных файлов и делает результат stow +совпадающим с прямой раскладкой через `ln -s`. + +Перед записью установщик проверяет весь набор назначений. Правильная ссылка на +текущий исходный каталог считается уже установленной; любой другой файл, +каталог или симлинк считается конфликтом. При конфликте установщик ничего не +меняет и сообщает все пути, которые пользователь должен разобрать вручную. +Принудительной замены и автоматических резервных копий нет. + +По умолчанию установщик идемпотентно подключает Bash-модуль в `~/.bashrc` и при +необходимости добавляет `~/.local/bin` в `PATH`. Уже существующее подключение +через dotfiles не дублируется. Управляемый блок помечается, повторно не +добавляется и может быть полностью отключён параметром `--no-shell-setup`. + +Установщик не выбирает режим прокси, не создаёт конфигурацию, не читает VLESS, +не устанавливает Xray и не проверяет сеть. После раскладки он проверяет только +локальные требования и исправность CLI и Bash-модуля, затем печатает краткую +подсказку для текущей shell-сессии и направляет пользователя в README за +настройкой режима. Недоступный прокси не делает установку неуспешной. + +Полный корневой `install.sh` продолжает подключать тот же stow-пакет вместе с +остальными dotfiles и не получает отдельной реализации этой логики. ## Решения и отклонённые альтернативы @@ -412,6 +465,14 @@ README репозитория только кратко описывает по автоматическое распределение портов отложены до появления реальной нужды. - Официальный системный установщик отклонён: он требует root и создаёт systemd-службы. Пользовательская установка соответствует выбранной модели. +- Копирование файлов пакета отклонено: оно создаёт отдельные экземпляры, + усложняет обновление и нарушает общую с dotfiles модель симлинков. +- Обязательный stow отклонён как лишняя зависимость. Прямые симлинки дают тот же + результат на машине без stow, а автоматический выбор механизма не меняет + публичное поведение пакета. +- Автоматическая настройка режима, установка Xray и проверка сети отклонены для + установщика пакета. Эти операции зависят от машины, могут требовать секретов + или сети и уже имеют отдельные явные команды и инструкции. - Готовые JSON и полный импорт Hiddify отклонены как основной интерфейс: точечная VLESS-ссылка проще для пользователя и ограничивает область преобразования. @@ -428,6 +489,15 @@ README репозитория только кратко описывает по истинное значение сопровождается предупреждением. - Старые дистрибутивы могут иметь Python ниже 3.8. CLI проверяет версию до основной работы и сообщает обнаруженную и требуемую версии. +- Симлинки зависят от постоянного пути исходного каталога. Установщик явно + сообщает эту зависимость и при повторном запуске принимает только ссылки на + текущий источник. +- Изменение `~/.bashrc` может конфликтовать с пользовательским способом загрузки + оболочки. Установщик распознаёт собственный блок и известное подключение из + dotfiles, не дублирует их и предоставляет `--no-shell-setup`. +- Частичная установка может оставить неоднозначное состояние. Все конфликты + назначений проверяются до изменений; проверки охватывают отсутствие новых + ссылок и правок shell при отказе. - `NO_PROXY` реализуется программами неодинаково. README рекомендует точные IP и домены, а CIDR описывает как совместимость best-effort. - Разные пользователи делят сетевое пространство имён. Настраиваемый порт и @@ -463,6 +533,22 @@ README репозитория только кратко описывает по - Регрессионные Bash-тесты подтверждают прежнее поведение Hiddify при отсутствии машинного конфига, оба регистра proxy-переменных, настраиваемый `NO_PROXY` и отсутствие автоматического запроса внешнего IP в `proxy_on`/`proxy_off`. +- Проверки самостоятельной установки покрывают путь со stow и без него, + одинаковый набор итоговых ссылок, запуск не из каталога пакета и каталог с + пробелами в пути. +- В обоих путях домашние каталоги остаются обычными каталогами, а пакетные + `README.md` и `install.sh` не появляются в домашнем каталоге через stow. +- Повторный запуск не меняет уже правильную установку. Конфликт любого + назначения обнаруживается до записи; чужие файлы, каталоги и ссылки остаются + неизменными. +- Машинный `config` и закрытый `default.url` не управляются установщиком даже + при их наличии в исходном каталоге или домашнем каталоге. +- Настройка Bash проверяется для нового `~/.bashrc`, уже помеченного блока, + подключения из полного dotfiles и режима `--no-shell-setup`. Добавление + `~/.local/bin` не дублируется. +- Локальная проверка установки не обращается к сети и не требует доступного + прокси. Неисправный или отсутствующий машинный конфиг не отменяет успешную + раскладку пакета. - Ручная проверка выполняется минимум на Ubuntu с Python 3.10 и на одной целевой удалённой системе. РЕД ОС, Astra Linux и Alt Linux проверяются по мере доступности: недоступная среда явно записывается как неподтверждённая, а @@ -474,7 +560,11 @@ README репозитория только кратко описывает по реализацией. Она должна описывать: - различие внешнего Hiddify и управляемого Xray; -- выборочная установка через stow, ручные симлинки и копирование; +- самостоятельный `install.sh`, его автоматический выбор stow или прямых + симлинков, требование сохранять исходный каталог и режим + `--no-shell-setup`; +- границу между управляемыми файлами пакета и создаваемыми вручную машинным + конфигом и закрытым профилем; - создание машинного INI из шаблона и отдельного файла VLESS-ссылки; - команды управления, `proxy_on/off`, `pclaude/pcodex`; - настройка `NO_PROXY`, ограничения CIDR и диагностика;