Памятка для AI-агентов и новых разработчиков. Прочитайте её целиком перед изменениями. Подробности по подсистемам — в docs/.
SSH Tunnel (applicationId и namespace — top.rootu.ssh.tunnel) — приложение для
Android и Android TV (minSdk 24, targetSdk/compileSdk 36). Оно заворачивает трафик выбранных
приложений в SSH-проброс ssh -D: системный тоннель (Android VpnService) → собственный
userspace TCP/IP → локальный SOCKS5 → SSH-каналы direct-tcpip (JSch).
Назначение: работа и тестирование мобильных приложений внутри сети предприятия.
В README и пользовательских текстах продукт описывается как «тоннель» / «проброс», а не «VPN».
Имена классов Android API (VpnService и т. п.) это не касается.
Модуль один — :app. Kotlin, Jetpack Compose (Material3), MVVM на StateFlow и корутинах,
Room для серверов и правил приложений, SharedPreferences для настроек, JSch (mwiede) + BouncyCastle
для SSH. Проект изначально сгенерирован в Google AI Studio — комментарии в app/build.gradle.kts
про signingConfigs оставлены намеренно.
gradle :app:testDebugUnitTest # юнит-тесты (JUnit + Robolectric)
gradle :app:assembleDebug
gradle :app:assembleRelease # R8 + shrinkResources включеныgradlewв репозитории нет, используйте установленный Gradle или Android Studio.- CI нет. Если Android SDK недоступен (облачная песочница,
dl.google.comзакрыт), используйтеtools/sandbox-check— см. docs/TESTING.md:tools/sandbox-check/net-tests— JVM-тесты сетевого ядра (быстро, без Android);tools/sandbox-check/compile— компиляция всех исходников против android-all + Compose Desktop со стабами Android-only API.
- Release собирается с R8. Новая библиотека с рефлексией → правила в
app/proguard-rules.pro. - Версия берётся из git (
versionCode= число коммитов,versionName=git describe --tags), поэтому нужна полная история. Релиз — тегvX.Y.Z→.github/workflows/release.ymlподписывает APK и публикует GitHub Release, его находит встроенное обновление. См. docs/RELEASES.md.
server/sshtunnel-user.sh Интерактивный скрипт для сервера: пользователь только для ssh -D (docs/SERVER.md)
app/src/main/java/
├── com/jcraft/jsch/ChannelWindowControl.java Доступ к package-private окну канала JSch (см. NETWORKING)
└── top/rootu/ssh/tunnel/
├── MainActivity.kt Навигация (NavigationRail на ТВ/широких экранах, BottomBar на телефоне)
├── data/
│ ├── model/ SshServerProfile, AppRoutingRule, VpnStats/VpnStatus, лог
│ ├── local/ Room: AppDatabase, ServerDao, AppRuleDao
│ └── repository/ VpnRepository (UI-доступ к данным), VpnPrefs (ключи и дефолты настроек)
├── vpn/
│ ├── SshVpnService.kt Жизненный цикл: TUN, SOCKS, SSH, переподключение, статистика, уведомления
│ ├── VpnTunPacketHandler Чтение TUN (poll), маршрутизация TCP/DNS/UDP
│ ├── Socks5ProxyServer Локальный SOCKS5 → TunnelTransport
│ ├── SshTunnelClient JSch-сессия, implements TunnelTransport
│ ├── SshChannelBuffer Неблокирующий приёмный буфер канала с управлением окном SSH
│ ├── TunnelTransport Интерфейс транспорта (SSH в проде, фейк в тестах)
│ └── net/ Чистый Kotlin без Android: Packets, TcpProxySession, Socks5Client,
│ DnsMessages/DnsCache, Cidr, ByteQueue, GeoIpLookup (внешний IP)
├── receiver/BootReceiver Автозапуск после загрузки
├── update/ ReleaseInfo (разбор релиза GitHub, чистый Kotlin), UpdateManager (загрузка,
│ проверка подписи, установка через FileProvider)
└── ui/
├── MainViewModel.kt Единая VM для всех экранов
├── screens/ Home, Apps, Servers, Logs, Settings
├── components/ SettingSwitchRow, ReconnectBanner, TvTextField
├── util/ tvFocusVisual / tvCardFocusable, isTvDevice, OEM battery helper
└── theme/
- Подключение: UI (
HomeScreen) →VpnService.prepare→MainViewModel.startVpn→SshVpnServiceACTION_CONNECT→runTunnel: SOCKS5 →establishTun→VpnTunPacketHandler→runSshLoop(подключение и переподключения). - Пакет приложения: TUN →
VpnTunPacketHandler.handlePacket→TcpProxySession→Socks5Client→Socks5ProxyServer→SshTunnelClient.openStream(direct-tcpip). - Состояние для UI: статические
StateFlowвSshVpnService.Companion(vpnStatus,vpnStats,activeServer,logs), их читаетMainViewModel. - Настройки маршрутизации (приложения, политика, DNS, обход LAN) применяются при создании TUN.
Если их меняют при активном тоннеле,
MainViewModel.needsReconnectпоказываетReconnectBanner.
- Никаких утечек мимо тоннеля. TUN живёт всё время работы сервиса, в том числе во время переподключения SSH; при недоступном SSH приложения получают RST. Не закрывайте TUN «на время» и не добавляйте маршруты/исключения, которые пустят DNS или TCP выбранных приложений напрямую. IPv6 на TUN намеренно не настраивается (Android тогда блокирует IPv6 для выбранных приложений).
- Не блокируйте сессионный поток JSch. Данные каналов принимает только
SshChannelBuffer(никогда не блокирует). Не используйтеchannel.getInputStream()уdirect-tcpip. - Блокирующий I/O — на своих пулах потоков, не на
Dispatchers.IO(лимит 64 потока ведёт к зависанию при множестве соединений). - Состояние жизненного цикла
SshVpnServiceменяется только в главном потоке (serviceScopeнаDispatchers.Main.immediate), блокирующее — вwithContext(IO). - Сетевое ядро (
vpn/net) — без Android-зависимостей, чтобы тестироваться на JVM. Новая логика пакетов/TCP/DNS покрывается тестами вapp/src/test/java/top/rootu/ssh/tunnel/vpn. - Ключи настроек — только через
VpnPrefs. Меняется смысл ключа → новый ключ + миграция, старый не переиспользовать. Новая настройка проходит путь:VpnPrefs→VpnRepository→MainViewModel→SettingsScreen, а если влияет на TUN —markRoutingChanged(). - Управление с пульта обязательно. Любой новый интерактивный элемент должен получать фокус
с D-pad, показывать фокус (
tvFocusVisual) и срабатывать на OK. Правила — в docs/TV_UI.md. - Тексты и локализация: все видимые пользователю строки (UI, тосты, уведомления, сообщения
журнала и ошибки SSH) — только в ресурсах:
res/values/strings.xml(английский, по умолчанию) иres/values-ru/strings.xml(русский). Новая строка добавляется в оба файла с одинаковыми плейсхолдерами (%1$s,%1$d). В Compose —stringResource(...), вне Compose —context.getString(...). Не разбирайте локализованный текст в логике (пример: результат проверки сервера — флагisTestFailed, а неstartsWith("Error")). В текстах на обоих языках — «тоннель»/«tunnel», а не «VPN» (кроме названий системных пунктов меню Android иACTIVATE_VPN).vpn/netиSocks5ProxyServerбез Android-зависимостей: локализованные сообщения пишетSshVpnService. - Комментарии в коде — на английском, коротко, в стиле окружающего кода.
- Фокус в Compose:
onFocusChangedвидит только focus target после себя в цепочке модификаторов.tvFocusVisualставится передclickable, лишнийfocusable()передclickableсоздаёт второй target, и OK перестаёт работать. - Вложенные focusable внутри focusable-карточки недоступны стрелками. Делайте их соседями
(см.
ServerItemCard). - TUN-дескриптор неблокирующий:
read()возвращает 0 — ждать черезOs.poll, не крутиться в цикле. - Порядок в JSch:
setServerAliveIntervalпослеtimeout(интервал и есть таймаут сокета). Потоки канала подключаются доconnect(). - Текстовые поля только через
TvTextField. ОбычныйOutlinedTextFieldна ТВ открывает клавиатуру при простом перемещении фокуса и снова открывает её после «Назад». Формы с полями — полноэкранные, не вAlertDialog(окно диалога «прыгает» при изменении содержимого). - На ТВ нет многих системных Activity (выбор файла, окно подтверждения тоннеля):
оборачивайте
launch(...)вtry/catch (ActivityNotFoundException). - Room-синхронизация списка приложений — одной транзакцией (
withTransaction), иначе Flow эмитит сотни раз.
- Сообщения коммитов — Conventional Commits на английском:
type(scope): summary(feat/fix/refactor/docs/chore; scope:vpn,ui,build,docs, ...). - Одна логическая правка — один коммит. Force-push в общие ветки запрещён.