Я пишу на 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 до локального сервиса и копирует байты в обе стороны.

Грабли первые: два 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 секунд и сбрасывается после первого успешно принятого потока. Без потолка клиент после долгого простоя сервера возвращался бы через несколько минут. Без роста тысяча клиентов после рестарта сервера приходила бы одновременно каждую секунду.

У схемы с одним соединением есть цена, которую переподключение не убирает: при обрыве падают все потоки сразу. Скачивание большого файла через туннель оборвётся вместе с остальными запросами.
Грабли третьи: 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, расскажите в комментариях.
