Архитектура¶
Формат протокола¶
Протокол iproto использует простой бинарный формат: 12-байтный заголовок и данные переменной длины.
Заголовок (12 байт)¶
+--------+--------+--------+--------+
| Msg (4 байта, little-endian) | Код сообщения/метода
+--------+--------+--------+--------+
| Len (4 байта, little-endian) | Длина данных в байтах
+--------+--------+--------+--------+
| Sync (4 байта, little-endian) | ID корреляции запрос-ответ
+--------+--------+--------+--------+
| Data (Len байт) | Данные
+--------+--------+--------+--------+
- Msg — определяет тип запроса (код метода). Используется
ServeMuxдля маршрутизации. - Len — длина данных.
- Sync — автоинкрементный ID для корреляции запросов и ответов.
Управляющие сообщения¶
| Код | Имя | Назначение |
|---|---|---|
0xff00 |
MessagePing |
Keepalive ping |
0xff01 |
MessageShutdown |
Graceful shutdown handshake |
Channel¶
Channel управляет одним TCP-соединением. Запускает две горутины — чтение и запись пакетов.
┌──────────────────────────────────────┐
│ Channel │
│ │
│ ┌──────────┐ ┌──────────────┐ │
│ │ Reader │ │ Writer │ │
│ │ goroutine │ │ goroutine │ │
│ └─────┬─────┘ └──────┬───────┘ │
│ │ │ │
│ ▼ ▲ │
│ ┌─────────┐ ┌─────────┐ │
│ │ Handler │ │ out │ │
│ │ (user) │ │ chan │ │
│ └─────────┘ └─────────┘ │
│ │
│ ┌─────────────────────────┐ │
│ │ Pending Store │ │
│ │ map[msg<<32|sync] fn │ │
│ └─────────────────────────┘ │
└──────────────────────────────────────┘
Процесс запрос-ответ:
Call()регистрирует колбэк в хранилище по ключу(Msg << 32) | Sync.- Пакет отправляется в канал
outдля горутины записи. - При получении ответа reader находит его по
(Msg, Sync)и вызывает колбэк.
Жизненный цикл:
NewChannel(conn, config)— создание канала.Init()— запуск горутин чтения/записи.Shutdown()— graceful shutdown с двусторонним handshake.Close()— немедленное закрытие.Done()— канал, сигнализирующий о полном закрытии.
Возможности:
- Настраиваемый ping/keepalive через
PingInterval. - Idle timeout через
IdleTimeout. - Лимит размера пакета через
SizeLimit(по умолчанию 100 МБ). - Перехват соединения через
Hijack().
Pool¶
Pool управляет несколькими Channel к одному адресу сервера.
┌──────────────────────────────────┐
│ Pool │
│ │
│ ┌──────────┐ ┌──────────┐ │
│ │ Channel │ │ Channel │ ... │
│ │ #0 │ │ #1 │ │
│ └──────────┘ └──────────┘ │
│ │
│ Round-robin балансировка │
│ Автоматическое переподключение │
│ Rate limiting (token bucket) │
└──────────────────────────────────┘
Ключевые особенности:
- Балансировка — round-robin через
NextChannel(). - Автопереподключение — через
BackgroundDialerс настраиваемым backoff. - Rate limiting — опциональный token bucket limiter с режимами shaping и policing.
- FailOnCutoff — при включении вызовы немедленно завершаются ошибкой, если нет онлайн-каналов.
Server¶
Server принимает входящие TCP-соединения и создаёт Channel для каждого.
srv := &iproto.Server{
ChannelConfig: &iproto.ChannelConfig{
Handler: myHandler,
},
}
srv.ListenAndServe(ctx, "tcp", ":3301")
Поле Accept позволяет настраивать создание Channel (например, отдельные пулы обработчиков для каждого соединения).
ServeMux¶
ServeMux маршрутизирует входящие пакеты к обработчикам по Header.Msg:
При получении пакета ServeMux.ServeIProto ищет обработчик по коду сообщения и вызывает его.
Сериализация¶
Режим по умолчанию (Little-Endian, фиксированная длина)¶
| Тип | Размер |
|---|---|
uint8 / int8 |
1 байт |
uint16 / int16 |
2 байта |
uint32 / int32 / int / uint |
4 байта |
uint64 / int64 |
8 байт |
string / []byte |
4-байтный префикс длины + данные |
struct |
поля кодируются по порядку |
slice |
4-байтный префикс количества + элементы |
Режим BER (переменная длина)¶
BER-кодирование использует 7 бит на байт, старший бит — индикатор продолжения. Маленькие значения занимают меньше байт:
5→05(1 байт)128→81 00(2 байта)100000→86 8d 20(3 байта)
Теги структур для смешивания режимов:
type Message struct {
Count uint32 `iproto:"ber"` // BER-кодирование
Name string // По умолчанию (LE fixed)
}
syncutil¶
Примитивы конкурентности, используемые внутренне и доступные пользователю:
- TaskGroup — выполнение до N задач одновременно. Возвращает каналы с результатами.
- TaskRunner — запуск ровно одной задачи; несколько вызывающих подписываются на один результат.
- Throttle — ограничение частоты вызова функции (не чаще одного раза за период).
- Multitask / Every / Each — запуск N задач параллельно с отменой.