Руководство разработчика по ngrok

Компоненты

Проект ngrok состоит из двух компонентов: клиента ngrok (ngrok) и сервера ngrok (ngrokd). Клиент ngrok является более сложным компонентом, поскольку имеет пользовательские интерфейсы для отображения сохранённых запросов и ответов.

Сборка

git clone git@github.com:inconshreveable/ngrok.git
cd ngrok && make
bin/ngrok [LOCAL PORT]

Существуют цели Makefile для сборки только клиента или сервера.

make client
make server

Примечание: Вы должны собирать с Go 1.1+! У вас должен быть установлен Mercurial SCM.

Сборка версий выпуска

И клиент, и сервер содержат статические файлы активов. К ним относятся сертификаты TLS/SSL и html/css/js для веб-интерфейса клиента. Версии выпуска встраивают все эти данные в сами двоичные файлы, тогда как отладочные версии считывают эти файлы из файловой системы.

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

Существуют цели Makefile для создания клиента и сервера для выпусков:

make release-client
make release-server
make release-all

Разработка локально

Стратегия, которую я использую для разработки на ngrok, заключается в следующем:

Добавьте следующие строки в /etc/hosts:

127.0.0.1 ngrok.me
127.0.0.1 test.ngrok.me

Запустите ngrokd со следующими параметрами:

./bin/ngrokd -domain ngrok.me

Создайте файл конфигурации ngrok «debug.yml» со следующим содержимым:

server_addr: ngrok.me:4443
tunnels:
  test:
    proto:
      http: 8080

Затем запустите ngrok с помощью одной из следующих команд:

./bin/ngrok -config=debug.yml -log=ngrok.log start test
./bin/ngrok -config=debug.yml -log=ngrok.log -subdomain=test 8080

Это позволит вам настроить клиент ngrok для взаимодействия с сервером ngrok локально под вашим контролем. Счастливого хакинга!

Сетевой протокол и туннелирование

На высоком уровне туннелирование ngrok работает следующим образом:

Установка соединения и аутентификация

1. Клиент инициирует длительное TCP-соединение с сервером, через которое они будут передавать сообщения инструкций JSON. Это соединение называется Control Connection.
2. После установления соединения клиент отправляет сообщение Auth с информацией об аутентификации и версии.
3. Сервер проверяет сообщение Auth клиента и отправляет сообщение AuthResp, указывающее на успех или неудачу.

Создание туннеля

1. Затем клиент может попросить сервер создать туннели для него, отправив сообщения ReqTunnel.
2. Когда сервер получает сообщение ReqTunnel, он отправляет 1 или более сообщений NewTunnel, которые указывают на успешное создание туннеля или указывают на сбой.

Туннельные соединения

1. При получении нового общедоступного соединения сервер находит соответствующий туннель, проверяя заголовок HTTP-хоста (или номер порта для TCP-туннелей). Это соединение из общедоступного интернета называется Public Connection.
2. Сервер отправляет сообщение ReqProxy клиенту через управляющее соединение.
3. Клиент устанавливает новое TCP-соединение с сервером под названием Proxy Connection.
4. Клиент отправляет сообщение RegProxy по прокси-соединению, чтобы сервер мог связать его с управляющим соединением (и, следовательно, с туннелями, за которые он отвечает).
5. Сервер отправляет сообщение StartProxy по прокси-соединению с метаданными о соединении (IP-адрес клиента и имя туннеля).
6. Сервер начинает копировать трафик байт за байтом с публичного соединения на прокси-соединение и наоборот.
7. Клиент открывает соединение с локальным адресом, настроенным для этого туннеля. Это называется Private Connection.
8. Клиент начинает копировать трафик байт за байтом из прокси-соединения в частное соединение и наоборот.

Обнаружение мёртвых туннелей

1. Чтобы определить, жив ли туннель, клиент периодически отправляет Ping-сообщения через управляющее соединение на сервер, который отвечает Pong-сообщениями.
2. Если туннель считается мёртвым, сервер очистит его. Всё состояние этого туннеля и клиент попытается повторно подключиться и установить новый туннель.

Формат передачи данных по сети

Сообщения передаются по сети в виде сетевых строк вида:

<длина сообщения><полезная нагрузка сообщения>

Длина сообщения отправляется как 64-битное целое число с прямым порядком байтов.

Код

Определения и общие процедуры протокола находятся в папке src/ngrok/msg

src/ngrok/msg/msg.go

Здесь определены все различные типы сообщений (Auth, AuthResp, ReqTunnel, RegProxy, StartProxy и т. д.) и задокументированы их поля. Это хорошее место, чтобы понять, какие именно сообщения отправляются между клиентом и сервером.

ngrokd — сервер

Код

Код для сервера находится в папке src/ngrok/server

Точка входа

Точка входа ngrokd находится в src/ngrok/server/main.go. В src/ngrok/main/ngrokd/ngrokd.go есть заглушка для создания двоичного файла с правильным именем и нахождения в собственном пакете «main», чтобы соответствовать системе сборки Go.

ngrok — клиент

Код

Код клиента находится в папке src/ngrok/client

Точка входа

Точка входа ngrok находится в src/ngrok/client/main.go. В src/ngrok/main/ngrok/ngrok.go есть заглушка для создания двоичного файла с правильным именем и нахождения в собственном пакете «main», чтобы соответствовать системе сборки Go.

Статические ресурсы

HTML-код и код JavaScript для веб-интерфейса ngrok, а также другие статические ресурсы, такие как сертификаты TLS/SSL, находятся в каталоге верхнего уровня assets.

Дополнительно

Более подробную документацию можно найти в комментариях к самому коду.