Перейти к содержанию

Архитектура

Формат протокола

Протокол 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  │        │
│   └─────────────────────────┘        │
└──────────────────────────────────────┘

Процесс запрос-ответ:

  1. Call() регистрирует колбэк в хранилище по ключу (Msg << 32) | Sync.
  2. Пакет отправляется в канал out для горутины записи.
  3. При получении ответа 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:

mux := iproto.NewServeMux()
mux.Handle(1, echoHandler)
mux.Handle(2, timeHandler)

При получении пакета 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 задач параллельно с отменой.