Полный справочник заголовков, используемых в операциях 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-запросы:
| Заголовок | Значение | Описание |
|---|
Nats-Num-Pending | Количество | Число ожидающих сообщений потребителя |
Nats-Pending-Messages | Количество | Число ожидающих сообщений для pull-запроса |
Nats-Pending-Bytes | Размер в байтах | Число ожидающих байтов для pull-запроса |
Nats-Pin-Id | NUID | Идентификатор закрепления приоритетной группы для pull-запроса |
| Заголовок | Значение | Описание |
|---|
Nats-Stream-Source | Информация об источнике потока | Информация об исходном потоке в формате: имя-потока > номер > субъект |
Тип ответа
| Заголовок | Значение | Описание |
|---|
Nats-Response-Type | Строка типа ответа | Тип отправляемого ответа |
Заголовки запросов и ответов 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
- Пакетные операции требуют успеха всех сообщений пакета, иначе весь пакет отклоняется
- Операции со счётчиками атомарны и поддерживают распределённые счётчики в кластерных потоках