Я пишу на Go клиент и сервер для туннелей до локальной машины, по смыслу то же, что делает ngrok. Снаружи всё выглядит просто: запустил команду, получил публичный адрес. Внутри набралось несколько мест, где первая версия вела себя неправильно. Ниже расскажу, как устроена схема, и разберу четыре таких места с кодом.

Статья рассчитана на тех, кто знает, что такое TCP и NAT, но сам туннели не писал.

Соединение идёт изнутри наружу

Ноутбук разработчика почти всегда стоит за NAT. Подключиться к нему из интернета нельзя: у него нет адреса, на который можно прийти. Зато сам ноутбук спокойно открывает исходящие соединения. На этом всё и построено: клиент подключается к серверу с публичным адресом и держит соединение открытым. Когда на сервер приходит запрос от внешнего пользователя, сервер отправляет его клиенту по уже открытому соединению, а клиент передаёт его в локальный порт.

Входящий порт не работает, исходящий туннель работает
Входящий порт не работает, исходящий туннель работает

В качестве транспорта у меня WebSocket поверх HTTPS на 443 порту. Причина приземлённая: такой трафик пропускают корпоративные прокси и файрволы, которые режут всё остальное. QUIC и DTLS клиент тоже умеет, но по умолчанию они выключены, потому что UDP закрыт в заметной части сетей.

Зачем нужен мультиплексор

WebSocket даёт один двунаправленный канал. Внешних подключений при этом много: браузер открывает к сайту шесть соединений сразу, и у каждого свой поток байтов. Если писать их в один канал подряд, на другой стороне их уже не разобрать.

Открывать отдельный WebSocket на каждое внешнее подключение дорого: это новый TLS‑хендшейк на каждый запрос картинки. Поэтому поверх одного WebSocket работает мультиплексор. Я взял smux: он режет канал на пронумерованные потоки и отдаёт каждый как обычный net.Conn. yamux из HashiCorp решает ту же задачу, выбор между ними был почти произвольным.

Один долгий туннель и несколько логических потоков внутри
Один долгий туннель и несколько логических потоков внутри

Роли распределены непривычно. TCP‑соединение открывает клиент, а потоки внутри него открывает сервер, по одному на каждое внешнее подключение. Клиент их принимает:

cfg := smux.DefaultConfig()
cfg.KeepAliveInterval = settings.SmuxKeepAliveInterval
cfg.KeepAliveTimeout = settings.SmuxKeepAliveTimeout

sess, err := smux.Client(wsconn.NewWSConn(conn), cfg)

wsconn здесь — небольшой адаптер, который превращает WebSocket с его сообщениями в io.ReadWriteCloser, потому что smux хочет поток байтов. В начале каждого потока сервер пишет короткую преамбулу с адресом назначения. Клиент читает её с таймаутом, открывает TCP до локального сервиса и копирует байты в обе стороны.

WebSocket даёт транспорт, smux даёт независимые потоки
WebSocket даёт транспорт, smux даёт независимые потоки

Грабли первые: два keepalive с разными числами

Простаивающее соединение по дороге кто‑нибудь закроет: NAT забудет запись, балансировщик отрежет по таймауту. Поэтому в туннеле два уровня пингов. WebSocket шлёт ping раз в 30 секунд, чтобы промежуточные узлы видели активность. smux шлёт свой keepalive раз в 25 секунд и считает сессию мёртвой, если 60 секунд ничего не пришло.

Проблема в том, что эти числа задаются на обеих сторонах независимо. В тестовом клиенте у меня стоял таймаут smux в 2 секунды, а сервер слал keepalive раз в 25. Пока по туннелю шли данные, всё работало. Стоило ему помолчать две секунды, клиент решал, что сервер умер, и рвал сессию. Тесты с постоянным трафиком проходили, тест с паузой падал, и по логам это выглядело как случайный обрыв сети.

Правило, которое я из этого вынес: таймаут на одной стороне должен быть заметно больше интервала на другой, с запасом хотя бы в два пропущенных пинга. Отсюда 25 и 60.

Грабли вторые: сессия мертва, но говорит, что жива

Цикл приёма потоков сначала выглядел так: если AcceptStream вернул ошибку, проверить sess.IsClosed() и переподключиться, если сессия закрыта. Оказалось, что AcceptStream может вернуть ошибку раньше, чем smux пометит сессию закрытой. Клиент видел ошибку, видел «сессия открыта», шёл на следующий круг и получал ту же ошибку. Процесс крутился в цикле на 100% ядра, туннель при этом не работал.

Сейчас цикл не спрашивает у сессии, жива ли она. Любая ошибка приёма означает, что сессию надо выбросить и после паузы открыть новую:

st, err := sess.AcceptStream()
if err != nil {
    if ctx.Err() != nil {
        return ctx.Err()
    }
    l.sessions.resetSession()
    if waitErr := l.wait(ctx, l.retry.Next()); waitErr != nil {
        return waitErr
    }
    continue
}
l.retry.Reset()
l.dispatch(st)

Пауза растёт экспоненциально от 1 до 30 секунд и сбрасывается после первого успешно принятого потока. Без потолка клиент после долгого простоя сервера возвращался бы через несколько минут. Без роста тысяча клиентов после рестарта сервера приходила бы одновременно каждую секунду.

Один обрыв ломает все потоки, поэтому нужен reconnect с backoff
Один обрыв ломает все потоки, поэтому нужен reconnect с backoff

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

Грабли третьи: localhost и 127.0.0.1 — разные адреса

Команда tunnel 8000 сначала разворачивалась в 127.0.0.1:8000. Потом пришла жалоба: в браузере http://localhost:4321 открывается, а через туннель 502. Дев‑сервер слушал только ::1, то есть IPv6. Браузер пробует оба адреса и этого не замечает, а клиент шёл строго на IPv4 и получал connection refused.

Проверяется это двумя командами:

curl -I http://localhost:4321/
curl -I http://127.0.0.1:4321/

Если первая отвечает, а вторая нет, сервис слушает только IPv6. Теперь короткая форма с номером порта разворачивается в localhost:порт, и Go сам перебирает адреса. Явно указанный host:port клиент не трогает. Для UDP я оставил 127.0.0.1: там нет соединения, по отказу которого можно перейти на другой адрес.

Грабли четвёртые: локальный сервис лежит

Разработчик перезапускает свой сервер десятки раз в день. Первая версия при неудачном подключении к локальному порту считала туннель сломанным и закрывала его. Публичный адрес менялся, вебхук в чужой админке приходилось перенастраивать.

Сейчас туннель живёт независимо от локального сервиса. На каждый входящий поток клиент заново пробует подключиться к порту. Если не вышло, он пишет в поток строку с ошибкой, и сервер отдаёт наружу 502. Если вышло, пишет подтверждение и начинает копировать данные:

{"ok":true}
{"ok":false,"error":"dial tcp [::1]:8000: connect: connection refused"}

Эта строка нужна серверу, чтобы отличить «у пользователя не запущено приложение» от «сломался туннель». Для первого случая показывается страница с подсказкой, второй уходит в мониторинг.

Что бы я сделал иначе

Преамбулу и подтверждение стоило сразу сделать бинарными с номером версии. JSON‑строки удобно читать в дампе, но менять их формат без поломки старых клиентов трудно.

Второе — справедливость между потоками. smux не ограничивает отдельный поток, и одна большая загрузка заметно тормозит остальные запросы в том же туннеле. Пока это закрыто общим лимитом скорости на туннель, нормального решения у меня нет. Если кто‑то решал это поверх smux или yamux, расскажите в комментариях.