# Заголовки API JetStream

Полный справочник заголовков, используемых в операциях JetStream: при публикации и доставке сообщений, а также для различных возможностей JetStream.

## Заголовки публикации сообщений

Заголовки публикации сообщений в потоки JetStream.

### Идентификация и дедупликация сообщений

| Заголовок                   | Значение                           | Описание                                                                                                                                            |
| --------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Nats-Msg-Id`               | Уникальный идентификатор сообщения | Уникальный идентификатор сообщения для дедупликации. Сообщения с одинаковым идентификатором в пределах окна дедупликации отклоняются как дубликаты. |
| `Nats-Expected-Last-Msg-Id` | Идентификатор сообщения            | Сообщение сохраняется только при совпадении идентификатора последнего сообщения с этим значением                                                    |

### Заголовки ожидаемого состояния

Эти заголовки проверяют ожидаемое состояние при публикации. Если условия не выполнены, публикация завершается ошибкой.

| Заголовок                                     | Значение         | Описание                                                                                                  |
| --------------------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------- |
| `Nats-Expected-Stream`                        | Имя потока       | Проверяет, что сообщение публикуется в ожидаемый поток                                                    |
| `Nats-Expected-Last-Sequence`                 | Порядковый номер | Сообщение сохраняется только при совпадении последнего порядкового номера потока с этим значением         |
| `Nats-Expected-Last-Subject-Sequence`         | Порядковый номер | Сообщение сохраняется только при совпадении последнего порядкового номера этого субъекта с этим значением |
| `Nats-Expected-Last-Subject-Sequence-Subject` | Субъект          | Задаёт субъект для проверки ожидаемого последнего порядкового номера субъекта                             |

### Свёртка сообщений

| Заголовок              | Значение        | Описание                                                                                                                                    |
| ---------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `Nats-Rollup`          | `sub` или `all` | Указывает, что сообщение должно заменить предыдущие. `sub` заменяет все предыдущие сообщения того же субъекта, `all` — все сообщения потока |
| `Nats-Schedule-Rollup` | Строка          |                                                                                                                                             |

### Размер сообщения

| Заголовок       | Значение        | Описание                                     |
| --------------- | --------------- | -------------------------------------------- |
| `Nats-Msg-Size` | Размер в байтах | Указывает размер полезной нагрузки сообщения |

### TTL сообщения

| Заголовок  | Значение                                    | Описание                                                                          |
| ---------- | ------------------------------------------- | --------------------------------------------------------------------------------- |
| `Nats-TTL` | Строка длительности (например, `60s`, `5m`) | Время жизни сообщения. По истечении этого срока сообщение автоматически удаляется |

### Операции со счётчиками

| Заголовок              | Значение | Описание                                       |
| ---------------------- | -------- | ---------------------------------------------- |
| `Nats-Incr`            | Число    | Значение приращения для операций со счётчиками |
| `Nats-Counter-Sources` | JSON     | Источники значений счётчиков в формате JSON    |

### Пакетные операции

Заголовки атомарной пакетной публикации:

| Заголовок             | Значение             | Описание                                                         |
| --------------------- | -------------------- | ---------------------------------------------------------------- |
| `Nats-Batch-Id`       | Идентификатор пакета | Уникальный идентификатор пакета                                  |
| `Nats-Batch-Sequence` | Порядковый номер     | Порядковый номер внутри пакета                                   |
| `Nats-Batch-Commit`   | `1`                  | Помечает последнее сообщение пакета, запуская атомарную фиксацию |

### Запланированные сообщения

Заголовки доставки сообщений по расписанию:

| Заголовок                 | Значение                                    | Описание                                                    |
| ------------------------- | ------------------------------------------- | ----------------------------------------------------------- |
| `Nats-Schedule`           | Выражение cron                              | Шаблон расписания доставки сообщений                        |
| `Nats-Schedule-Time-Zone` | Строка                                      |                                                             |
| `Nats-Schedule-TTL`       | Строка длительности (например, `60s`, `5m`) | Время жизни расписания                                      |
| `Nats-Schedule-Target`    | Субъект                                     | Целевой субъект доставки по расписанию                      |
| `Nats-Schedule-Source`    | Субъект                                     | Исходный субъект доставки сообщений по расписанию           |
| `Nats-Scheduler`          | Идентификатор планировщика                  | Идентификатор планировщика                                  |
| `Nats-Schedule-Next`      | Временная метка RFC3339 или `purge`         | Время следующего запуска по расписанию или указание очистки |

## Заголовки доставки сообщений

Заголовки, добавляемые JetStream при доставке сообщений потребителям.

### Информация о потоке

| Заголовок              | Значение                | Описание                                                                                                                                                             |
| ---------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Nats-Last-Stream`     | Порядковый номер        | Последний порядковый номер потока на момент доставки                                                                                                                 |
| `Nats-Stream`          | Имя потока              | Имя потока, из которого получено сообщение                                                                                                                           |
| `Nats-Sequence`        | Порядковый номер        | Порядковый номер сообщения в потоке                                                                                                                                  |
| `Nats-Time-Stamp`      | Временная метка RFC3339 | Временная метка сохранения сообщения                                                                                                                                 |
| `Nats-Subject`         | Субъект                 | Исходный субъект публикации сообщения                                                                                                                                |
| `Nats-Last-Sequence`   | Порядковый номер        | Последний порядковый номер в потоке на момент доставки этого сообщения                                                                                               |
| `Nats-UpTo-Sequence`   | Порядковый номер        | Верхняя граница порядкового номера для пакетной доставки                                                                                                             |
| `Nats-Stream-Identity` | Строка                  | JSStreamIdentity — идентификатор потока, используемый для отклонения создания потребителя при несовпадении и возвращаемый в ответах на создание и сброс потребителя. |

### Информация о потребителе

| Заголовок               | Значение         | Описание                                                              |
| ----------------------- | ---------------- | --------------------------------------------------------------------- |
| `Nats-Last-Consumer`    | Порядковый номер | Последний доставленный порядковый номер потребителя                   |
| `Nats-Consumer-Stalled` | Субъект ответа   | Указывает, что потребитель приостановлен, и содержит счётчик доставки |

### Заголовки pull-запросов

Заголовки ответов на pull-запросы:

| Заголовок               | Значение        | Описание                                                       |
| ----------------------- | --------------- | -------------------------------------------------------------- |
| `Nats-Num-Pending`      | Количество      | Число ожидающих сообщений потребителя                          |
| `Nats-Pending-Messages` | Количество      | Число ожидающих сообщений для pull-запроса                     |
| `Nats-Pending-Bytes`    | Размер в байтах | Число ожидающих байтов для pull-запроса                        |
| `Nats-Pin-Id`           | NUID            | Идентификатор закрепления приоритетной группы для pull-запроса |

### Информация об источнике и зеркале

| Заголовок            | Значение                       | Описание                                                              |
| -------------------- | ------------------------------ | --------------------------------------------------------------------- |
| `Nats-Stream-Source` | Информация об источнике потока | Информация об исходном потоке в формате: имя-потока > номер > субъект |

### Тип ответа

| Заголовок            | Значение           | Описание                 |
| -------------------- | ------------------ | ------------------------ |
| `Nats-Response-Type` | Строка типа ответа | Тип отправляемого ответа |

## Заголовки API

Заголовки запросов и ответов API JetStream.

| Заголовок                 | Значение         | Описание                                         |
| ------------------------- | ---------------- | ------------------------------------------------ |
| `Nats-Required-Api-Level` | Номер уровня API | Минимальный уровень API, необходимый для запроса |

## Заголовки маркеров

Заголовки для обозначения специальных типов сообщений в потоках.

| Заголовок            | Значение                       | Описание                                  |
| -------------------- | ------------------------------ | ----------------------------------------- |
| `Nats-Marker-Reason` | `MaxAge`, `Purge` или `Remove` | Причина маркера: MaxAge, Purge или Remove |

## Заголовки аутентификации и авторизации

Заголовки auth callout и авторизации.

| Заголовок           | Значение                            | Описание                                              |
| ------------------- | ----------------------------------- | ----------------------------------------------------- |
| `Nats-Request-Info` | Информация о клиенте в формате JSON | Информация об авторизации клиента для запроса         |
| `Nats-Server-Xkey`  | Строка X-Key                        | X-Key сервера для зашифрованных запросов auth callout |

## Заголовки трассировки сообщений

Заголовки трассировки и диагностики сообщений.

| Заголовок                   | Значение        | Описание                                                       |
| --------------------------- | --------------- | -------------------------------------------------------------- |
| `Nats-Trace-Dest`           | Субъект         | Субъект назначения трассировки сообщений                       |
| `Nats-Trace-Hop`            | Число переходов | Число переходов трассировки                                    |
| `Nats-Trace-Origin-Account` | Имя аккаунта    | Исходный аккаунт трассировки сообщений                         |
| `Nats-Trace-Only`           | Логический флаг | Указывает режим только трассировки (сообщение не доставляется) |

## Заголовки хранилища ключей и значений

Заголовки хранилища ключей и значений NATS, построенного на JetStream.

| Заголовок      | Значение                 | Описание                            |
| -------------- | ------------------------ | ----------------------------------- |
| `KV-Operation` | `PUT`, `DEL` или `PURGE` | Тип операции KV: PUT, DEL или PURGE |

## Примеры использования

### Публикация с дедупликацией

```
Nats-Msg-Id: unique-message-123
```

### Публикация с проверкой ожидаемого состояния

```
Nats-Expected-Last-Sequence: 42

Nats-Expected-Stream: my-stream
```

### Пакетная публикация

```
Nats-Batch-Id: batch-456

Nats-Batch-Sequence: 1
```

Для последнего сообщения пакета:

```
Nats-Batch-Id: batch-456

Nats-Batch-Sequence: 10

Nats-Batch-Commit: 1
```

### Запланированное сообщение

```
Nats-Schedule: 0 */5 * * * *

Nats-Schedule-TTL: 24h

Nats-Schedule-Target: notifications.email
```

## Примечания

* Имена заголовков чувствительны к регистру
* Некоторые заголовки устанавливаются сервером автоматически; клиентам не следует задавать их вручную
* Заголовки с префиксом `Nats-Expected-` используются для оптимистического управления конкурентным доступом
* Заголовок `Nats-Rollup` используется совместно с настройкой потока `MaxMsgsPerSubject`
* Пакетные операции требуют успеха всех сообщений пакета, иначе весь пакет отклоняется
* Операции со счётчиками атомарны и поддерживают распределённые счётчики в кластерных потоках
