# Листовые узлы

Соединения листовых узлов расширяют кластеры NATS лёгкими соединениями, инициируемыми периферийными серверами к центральному кластеру. Протокол оптимизирован для топологии «центр — лучи» с небольшими накладными расходами. В отличие от маршрутов кластера, эти соединения асимметричны: периферийный узел инициирует и поддерживает соединение с центром.

## Обзор

Таблица перечисляет сообщения протокола листовых узлов. Имена операций не чувствительны к регистру: `LS+ foo\r\n` и `ls+ foo\r\n` эквивалентны.

| Сообщение             | Отправитель        | Описание                                                                 |
| --------------------- | ------------------ | ------------------------------------------------------------------------ |
| [`INFO`](#info)       | Все серверы        | Отправляется после подключения с расширениями листовых узлов             |
| [`CONNECT`](#connect) | Листовой узел      | Устанавливает и аутентифицирует соединение                               |
| [`LS+`](#ls)          | Все серверы        | Подписывает на тему, при необходимости с группой очереди и весом         |
| [`LS-`](#ls-1)        | Все серверы        | Отменяет подписку на тему, при необходимости для группы очереди          |
| [`LMSG`](#lmsg)       | Все серверы        | Доставляет сообщение с темой, необязательным ответом и группами очередей |
| [`LDS`](#lds)         | Центральный сервер | Темы обнаружения циклов маршрутизации                                    |
| [`PING`](#ping-pong)  | Все серверы        | Проверка активности PING                                                 |
| [`PONG`](#ping-pong)  | Все серверы        | Ответ проверки активности PONG                                           |
| [`-ERR`](#err)        | Все серверы        | Ошибка протокола, которая может вызвать отключение листового узла        |

## INFO

`INFO` листового узла содержит возможности сервера и настройки для подключения. Центральный и листовой серверы обмениваются INFO при установлении соединения.

### Синтаксис

```
INFO {<key>:<value>,...}
```

Поля, относящиеся к листовым узлам:

* `server_id`: уникальный идентификатор сервера NATS
* `version`: версия сервера NATS
* `proto`: версия протокола (1 для текущего протокола листовых узлов)
* `go`: версия Go, которой собран сервер
* `host`: хост из конфигурации листового узла
* `port`: порт соединений листовых узлов
* `headers`: поддержка заголовков (true/false)
* `jetstream`: включён ли JetStream
* `compression`: режим сжатия (`off`, `accept`, `s2_auto`, `s2_fast`, `s2_better`, `s2_uncompressed`)
* `cluster`: имя кластера, если сервер входит в кластер
* `domain`: имя домена JetStream
* `xkey`: открытый xkey сервера для шифрования
* `auth_required`: обязательность аутентификации
* `tls_required`: обязательность TLS
* `tls_verify`: обязательность проверки сертификата TLS
* `max_payload`: максимальный принимаемый размер нагрузки
* `client_id`: идентификатор клиента для согласования сжатия
* `nonce`: одноразовое значение для операций безопасности
* `connect_urls`: альтернативные серверы подключения

### Пример

```
INFO {"server_id":"NCXU7YJOG5XAU","version":"2.10.0","proto":1,"go":"go1.21","host":"localhost","port":7422,"headers":true,"max_payload":1048576,"jetstream":true,"compression":"s2_auto","cluster":"hub-cluster","domain":"hub","connect_urls":["localhost:7422"]}
```

## CONNECT

`CONNECT` отправляется листовым узлом для аутентификации и задания параметров соединения. Включает конфигурацию и возможности листового узла.

### Синтаксис

```
CONNECT {<key>:<value>,...}
```

Допустимые параметры:

* `version`: версия сервера листового узла
* `server_id`: уникальный идентификатор листового узла
* `name`: имя его сервера
* `domain`: домен JetStream листового узла
* `cluster`: имя кластера листового узла, если используется кластеризация
* `hub`: является ли соединение центральным (true/false)
* `headers`: поддерживаются ли заголовки
* `jetstream`: включён ли JetStream на листовом узле
* `compression`: запрашиваемый режим сжатия
* `remote_account`: учётная запись привязки соединения
* `proto`: версия протокола
* `nkey`: открытый NKey для аутентификации
* `jwt`: JWT для аутентификации
* `sig`: подпись для аутентификации nkey
* `user`: имя пользователя базовой аутентификации
* `pass`: пароль базовой аутентификации
* `auth_token`: токен аутентификации
* `tls_required`: требуется ли TLS

### Пример

```
CONNECT {"version":"2.10.0","server_id":"NATS123","name":"edge-1","cluster":"edge","hub":false,"headers":true,"jetstream":false,"compression":"s2_auto","remote_account":"EDGE_ACCOUNT","proto":1}\r\n
```

## LS+

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

### Синтаксис

**Обычная подписка**

```
LS+ <subject>\r\n
```

**Подписка группы очереди**

```
LS+ <subject> <queue_group>\r\n
```

**Подписка группы очереди с весом**

```
LS+ <subject> <queue_group> <weight>\r\n
```

где:

* `subject`: тема подписки с поддержкой подстановочных символов
* `queue_group`: необязательное имя группы очереди
* `weight`: необязательный вес распределения очереди, по умолчанию 1

### Примеры

```
LS+ orders.new\r\n

LS+ orders.> fulfillment\r\n

LS+ orders.> fulfillment 4\r\n
```

### Поддержка исходного кластера

При поддержке LNOCU (Leaf Node Origin Cluster Unsub) LS+ может включать сведения об исходном кластере для предотвращения циклов:

```
LS+ <subject> <queue_group> <weight> <origin_cluster>\r\n
```

## LS-

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

### Синтаксис

**Обычная отписка**

```
LS- <subject>\r\n
```

**Отписка группы очереди**

```
LS- <subject> <queue_group>\r\n
```

где:

* `subject`: тема отменяемой подписки
* `queue_group`: необязательное имя группы очереди

### Примеры

```
LS- orders.old\r\n

LS- orders.cancelled fulfillment\r\n
```

### Поддержка исходного кластера

При поддержке LNOCU LS- может включать информацию об исходном кластере:

```
LS- <subject> <queue_group> <origin_cluster>\r\n
```

## LMSG

Сообщение протокола `LMSG` доставляет данные через соединение листового узла. Поддерживаются темы ответа, выбор групп очередей и заголовки.

### Синтаксис

**Обычное сообщение**

```
LMSG <subject> <size>\r\n[payload]\r\n
```

**Сообщение с темой ответа**

```
LMSG <subject> + <reply> <size>\r\n[payload]\r\n
```

**Сообщение с группами очередей**

```
LMSG <subject> | <queue_group1> [queue_group2...] <size>\r\n[payload]\r\n
```

**Сообщение с темой ответа и группами очередей**

```
LMSG <subject> + <reply> <queue_group1> [queue_group2...] <size>\r\n[payload]\r\n
```

**Сообщение с заголовками**

```
LMSG <subject> [+ reply] [| queue_groups...] <header_size> <total_size>\r\n[headers]\r\n[payload]\r\n
```

где:

* `subject`: тема доставки сообщения
* `+`: признак следующей темы ответа
* `reply`: необязательная тема ответа
* `|`: признак следующих групп очередей
* `queue_group`: целевые группы очередей
* `header_size`: размер заголовков в байтах для сообщений с заголовками
* `total_size`: общий размер заголовков и нагрузки
* `size`: размер нагрузки в байтах для сообщений без заголовков
* `headers`: заголовки NATS в стандартном формате
* `payload`: полезная нагрузка сообщения

### Примеры

```
LMSG orders.new 11\r\nHello World\r\n
```

```
LMSG orders.new + _INBOX.123 11\r\nHello World\r\n
```

```
LMSG orders.new | fulfillment 11\r\nHello World\r\n
```

```
LMSG orders.new + _INBOX.123 fulfillment shipping 11\r\nHello World\r\n
```

```
LMSG orders.new 22 33\r\nNATS/1.0\r\nFoo: Bar\r\n\r\nHello World\r\n
```

## LDS

Темы обнаружения циклов (Loop Detection Subjects, LDS) — специальные темы для выявления и предотвращения циклов маршрутизации в сложных топологиях листовых узлов.

### Формат

```
$LDS.<unique_id>
```

где:

* `$LDS.`: фиксированный префикс тем обнаружения циклов
* `unique_id`: уникальный идентификатор, создаваемый для учётной записи

### Назначение

Получив собственную тему LDS через соединение листового узла, сервер обнаруживает цикл и принимает меры:

1. Записывает обнаружение цикла в журнал
2. Закрывает соединение
3. Задерживает переподключение на 30 секунд
4. Предотвращает бесконечное хождение сообщений по циклу

### Пример

```
$LDS.5XZq8bFpWH1234567890abcdef
```

## Сжатие

Листовые узлы поддерживают сжатие S2 для сокращения трафика, особенно полезное для WAN.

### Режимы сжатия

* `off`: без сжатия
* `accept`: принимать сжатые соединения, но не инициировать
* `s2_auto`: автоматически выбирать сжатие по RTT
* `s2_fast`: быстрое S2 с меньшей нагрузкой на процессор и меньшей степенью сжатия
* `s2_better`: более эффективное S2 с большей нагрузкой на процессор
* `s2_uncompressed`: кадры S2 без сжатия

### Согласование

Сжатие согласуется при обмене INFO:

1. Обе стороны объявляют возможности сжатия в INFO
2. Листовой узел предлагает режим в CONNECT
3. Центральный сервер принимает или изменяет режим
4. После успешного согласования начинается сжатие S2

### Автоматический режим

В режиме `s2_auto` решение зависит от RTT:

* Сжатие включается при RTT выше порога, обычно в WAN
* Отключается в LAN с низкой задержкой
* Динамически подстраивается под соединение

## Поддержка WebSocket

Листовые узлы могут подключаться через WebSocket для прохождения межсетевых экранов и совместимости с браузерным транспортом.

### Путь WebSocket

```
ws://server:port/leafnode
```

### Возможности

* Стандартный протокол листовых узлов поверх кадров WebSocket
* Необязательное сжатие per-message-deflate
* Маскирование кадров, отключаемое для производительности
* Те же методы аутентификации и сообщения протокола

### Пример URL подключения

```
ws://hub.example.com:443/leafnode
```

## Разрешения и безопасность

### Привязка учётной записи

Листовой узел можно привязать к учётной записи через `remote_account` в CONNECT:

* Сообщения ограничиваются этой учётной записью
* Исключается утечка сообщений между учётными записями
* Поддерживается изолированное размещение арендаторов на периферии

### Нарушения разрешений

При нарушении разрешений:

* Соединение закрывается с `-ERR 'Permissions Violation'`
* Переподключение задерживается на 30 секунд
* Нарушение записывается для аудита безопасности

### Способы аутентификации

Листовые узлы поддерживают:

* NKey с подписью
* JWT с NKey
* Имя пользователя и пароль
* Токен аутентификации
* Клиентские сертификаты TLS

## PING/PONG

`PING` и `PONG` проверяют доступность между листовым и центральным узлами. Серверы отправляют `PING` с настраиваемым интервалом. Отсутствие ответа `PONG` приводит к закрытию соединения.

### Синтаксис

```
PING\r\n
```

```
PONG\r\n
```

## -ERR

`-ERR` сообщает об ошибке протокола, авторизации или выполнения. Большинство ошибок закрывает соединение листового узла.

### Синтаксис

```
-ERR <error message>
```

### Распространённые ошибки листовых узлов

* `-ERR 'Permissions Violation'`: запрещена тема или публикация
* `-ERR 'Loop Detected'`: LDS обнаружил цикл маршрутизации
* `-ERR 'Authorization Violation'`: ошибка аутентификации или авторизации
* `-ERR 'Maximum Payload Exceeded'`: сообщение превышает max\_payload
* `-ERR 'Invalid Subject'`: некорректная тема в сообщении протокола
* `-ERR 'Leafnode Not Allowed'`: сервер не настроен для листовых узлов
