Темы между учётными записями
Поток, читающий источник или зеркало из другой учётной записи либо домена JetStream, управляет потребителем исходного потока с другой стороны границы. Все темы этого потребителя должны проходить границу через экспорт и импорт или разрешения соединения листового узла. Отсутствие темы редко вызывает ошибку: обычно репликация останавливается или не начинается.
Здесь перечислены темы каждого типа потребителя источника, последствия отсутствия тем и проверенные конфигурации учётных записей и листовых узлов. Также рассматриваются клиент, читающий потребителя другой учётной записи, и форматы тем v1 и v2.
Потребители источников
Источник или зеркало читает исходный поток через push-потребителя. Его тип зависит от конфигурации источника и политики хранения исходного потока:
| Потребитель | Условия | Время жизни |
|---|---|---|
| Временный | Нет блока consumer, исходный поток использует хранение limits. | Сервер создаёт имя JS_SRC_<hash>-<suffix> (JS_MIRROR_… для зеркала) и удаляет потребителя через 10 секунд бездействия. |
| Долговременный под управлением сервера (2.14+) | Нет блока consumer, исходный поток использует workqueue или interest. | Исходный сервер превращает запрос создания в долговременного потребителя JS_SRC_<hash> (JS_MIRROR_<hash> для зеркала) с политикой подтверждений flow_control. Он существует до ручного удаления или удаления источника из читающего потока, который отправляет запрос удаления без гарантии успеха. |
| Долговременный, заданный пользователем (2.14+) | В источнике или зеркале есть блок consumer. | Вы сами создаёте и удаляете потребителя исходного потока. Читающий поток только сбрасывает его состояние. |
Долговременный потребитель с политикой flow_control считает каждый ответ управления потоком подтверждением. Так исходный поток workqueue или interest узнаёт о сохранении сообщения и возможности безопасного удаления.
Темы
Префикс api в блоке external заменяет $JS.API во всех темах запросов. При "api": "ACC.ORIGIN.API" читающий поток отправляет ACC.ORIGIN.API.CONSUMER.CREATE.EVENTS, а импорт возвращает тему $JS.API.CONSUMER.CREATE.EVENTS в исходной учётной записи. Примеры используют ACC.<account>.API с такой же структурой, как у префикса домена $JS.<domain>.API. Не начинайте темы с $: они зарезервированы для сервера.
| Тема | Направление | Тип экспорта | Кто использует |
|---|---|---|---|
$JS.API.CONSUMER.CREATE.<stream> | читающий поток → источник | service | Временный и управляемый сервером потребители; при отсутствии фильтра или нескольких фильтрах. |
$JS.API.CONSUMER.CREATE.<stream>.<consumer>.<filter> | читающий поток → источник | service | Временный и управляемый сервером потребители; при одном фильтре или одном преобразовании темы. |
$JS.API.CONSUMER.DELETE.<stream>.<consumer> | читающий поток → источник | service | Управляемый сервером (2.14+); при удалении источника, зеркала или читающего потока, а также повышении зеркала до основного. |
$JS.API.CONSUMER.RESET.<stream>.<consumer> | читающий поток → источник | service | Заданный пользователем долговременный (2.14+); вместо создания при каждом подключении источника. |
$JSC.R.…, ответы на перечисленные запросы | источник → читающий поток | нет | Все типы. Импорт сервиса переписывает тему ответа; разрешение нужно только при прохождении листового узла. |
| Тема доставки | источник → читающий поток | stream | Все типы. Передаёт сообщения, heartbeat и запросы управления потоком. |
$JS.FC.… | читающий поток → источник | service | Все типы. Ответ управления потоком, также являющийся подтверждением для двух долговременных типов. |
В списке нет $JS.ACK, используемой подтверждениями клиентских потребителей. Временный потребитель источника использует политику none, а потребитель с flow_control вообще не слушает $JS.ACK.
Тема доставки зависит от потребителя:
- Временные и управляемые сервером потребители получают новую тему при каждом создании:
<deliver>.S.<uid>для источника,<deliver>.M.<uid>для зеркала, где<deliver>— префиксdeliverблокаexternal. Без префикса используются$JS.S.<uid>или$JS.M.<uid>. Экспортируйте через шаблон, напримерDELIVER.TARGET.COPY.>. - Заданный пользователем долговременный потребитель использует точную
deliver_subjectблокаconsumer, совпадающую с собственнойdeliver_subjectпотребителя. Префиксdeliverигнорируется.
Задавайте временным и управляемым сервером потребителям префикс deliver, уникальный для одного отношения обмена. В примерах используется DELIVER.<sourcing account>.<sourcing stream>. Любая импортирующая тему учётная запись получает все её сообщения. Поэтому экспорт $JS.S.>, $JS.M.> или общего префикса нескольких читающих записей позволяет каждой читать чужие копии. Ограничение экспорта нужной записью через accounts: [ … ] заставляет сервер отклонять импорт остальных.
Если тема отсутствует
| Чего нет | Временный | Долговременный под управлением сервера | Долговременный пользователя |
|---|---|---|---|
| Создание | Сообщения не поступают. | Как для временного. | Не используется. |
| Удаление | Не используется: потребитель удаляется через 10 секунд бездействия. | Остаётся в исходном потоке после исчезновения источника; в потоке interest продолжает удерживать сообщения. | Не используется. |
| Сброс | Не используется. | Не используется. | Сообщения не поступают. |
| Тема доставки | Потребитель создаётся, не получает интереса и удаляется через 10 секунд. Источник создаёт его снова, но сообщения не идут. | Сообщения не идут, потребитель сохраняется. | Сообщения не поступают. |
$JS.FC | Сообщения идут до накопления около 2 МБ в ожидании ответа управления потоком, затем останавливаются с stream source consumer stalled on flow control (ошибка 10228). | То же, при этом исходный поток хранит все сообщения без подтверждений. | Доставка останавливается на max_ack_pending с ошибкой 10228, подтверждений нет. |
Учётные записи: временные и управляемые сервером потребители
Эта конфигурация позволяет источнику или зеркалу учётной записи TARGET читать поток EVENTS учётной записи ORIGIN. Работает для обоих типов потребителей и разрешает их только на EVENTS:
accounts {
ORIGIN {
jetstream: enabled
exports [
{ service: "$JS.API.CONSUMER.CREATE.EVENTS", accounts: [TARGET] }
{ service: "$JS.API.CONSUMER.CREATE.EVENTS.>", accounts: [TARGET] }
{ service: "$JS.API.CONSUMER.DELETE.EVENTS.*", accounts: [TARGET] }
{ stream: "DELIVER.TARGET.COPY.>", accounts: [TARGET] }
{ service: "$JS.FC.EVENTS.>", accounts: [TARGET] }
{ service: "$JS.FC.*.*.EVENTS.>", accounts: [TARGET] }
]
}
TARGET {
jetstream: enabled
imports [
{ service: { account: ORIGIN, subject: "$JS.API.CONSUMER.CREATE.EVENTS" }, to: "ACC.ORIGIN.API.CONSUMER.CREATE.EVENTS" }
{ service: { account: ORIGIN, subject: "$JS.API.CONSUMER.CREATE.EVENTS.>" }, to: "ACC.ORIGIN.API.CONSUMER.CREATE.EVENTS.>" }
{ service: { account: ORIGIN, subject: "$JS.API.CONSUMER.DELETE.EVENTS.*" }, to: "ACC.ORIGIN.API.CONSUMER.DELETE.EVENTS.*" }
{ stream: { account: ORIGIN, subject: "DELIVER.TARGET.COPY.>" } }
{ service: { account: ORIGIN, subject: "$JS.FC.EVENTS.>" } }
{ service: { account: ORIGIN, subject: "$JS.FC.*.*.EVENTS.>" } }
]
}
}
$JS.API.CONSUMER.CREATE.EVENTS.> не соответствует точной $JS.API.CONSUMER.CREATE.EVENTS, поэтому нужны обе записи. Серверы до 2.14 не отправляют удаление и не используют v2 $JS.FC; дополнительные записи безвредны и сохранят работоспособность после обновления. Две записи $JS.FC покрывают форматы тем v1 и v2. Для всех потоков ORIGIN используйте $JS.API.CONSUMER.> и $JS.FC.>. accounts: [TARGET] ограничивает каждый экспорт учётной записью TARGET.
Источник потока COPY ссылается на аналогичную конфигурацию:
{
"name": "COPY",
"sources": [
{
"name": "EVENTS",
"external": { "api": "ACC.ORIGIN.API", "deliver": "DELIVER.TARGET.COPY" }
}
]
}
Учётные записи: долговременный потребитель пользователя
Такого потребителя создаёт исходная учётная запись; читающей нужно только сбрасывать его состояние и получать данные. Экспорт можно ограничить одним потребителем.
Создайте потребителя исходного потока с политикой flow_control и push-темой deliver_subject:
{
"durable_name": "COPY_SRC",
"deliver_subject": "DELIVER.TARGET.COPY_SRC",
"ack_policy": "flow_control"
}
Сервер задаёт flow_control: true, idle_heartbeat в 1 секунду и стандартный max_ack_pending 1000. Он отклоняет ack_wait, backoff и max_deliver.
Экспортируйте только этого потребителя:
accounts {
ORIGIN {
jetstream: enabled
exports [
{ service: "$JS.API.CONSUMER.RESET.EVENTS.COPY_SRC", accounts: [TARGET] }
{ stream: "DELIVER.TARGET.COPY_SRC", accounts: [TARGET] }
{ service: "$JS.FC.EVENTS.COPY_SRC.*", accounts: [TARGET] }
{ service: "$JS.FC.*.*.EVENTS.COPY_SRC.*", accounts: [TARGET] }
]
}
TARGET {
jetstream: enabled
imports [
{ service: { account: ORIGIN, subject: "$JS.API.CONSUMER.RESET.EVENTS.COPY_SRC" }, to: "ACC.ORIGIN.API.CONSUMER.RESET.EVENTS.COPY_SRC" }
{ stream: { account: ORIGIN, subject: "DELIVER.TARGET.COPY_SRC" } }
{ service: { account: ORIGIN, subject: "$JS.FC.EVENTS.COPY_SRC.*" } }
{ service: { account: ORIGIN, subject: "$JS.FC.*.*.EVENTS.COPY_SRC.*" } }
]
}
}
Источник задаёт имя потребителя и тему доставки. Префикс api по-прежнему нужен, а deliver — нет:
{
"name": "COPY",
"sources": [
{
"name": "EVENTS",
"external": { "api": "ACC.ORIGIN.API" },
"consumer": { "name": "COPY_SRC", "deliver_subject": "DELIVER.TARGET.COPY_SRC" }
}
]
}
Источник с блоком consumer не может дополнительно задавать opt_start_seq, opt_start_time и filter_subject: задайте их потребителю. Два источника одного потока не могут разделять одного потребителя.
Потребители под управлением другой учётной записи
Клиент, создающий и читающий потребителя потока другой учётной записи, использует API JetStream и $JS.ACK, в отличие от механизма источников:
accounts {
ORIGIN {
jetstream: enabled
exports [
{ service: "$JS.API.>", response: stream }
{ service: "$JS.ACK.>" }
{ stream: "DELIVER.READER.>" }
]
}
TARGET {
imports [
{ service: { account: ORIGIN, subject: "$JS.API.>" }, to: "ACC.ORIGIN.API.>" }
{ service: { account: ORIGIN, subject: "$JS.ACK.>" } }
{ stream: { account: ORIGIN, subject: "DELIVER.READER.>" } }
]
}
}
Клиент задаёт префикс API JetStream ACC.ORIGIN.API.
- Для
$JS.API.>нужноresponse: stream, поскольку pull-запрос получает по ответу на сообщение. $JS.ACK.>передаёт подтверждения. Они публикуются в тему$JS.ACKиз сообщения, и импорт сервиса её не переписывает. Без импорта синхронное подтверждение завершаетсяno responders available for request, а по истечении ожидания сообщение доставляется снова.- Экспорт потока
DELIVER.READER.>нужен только push-потребителю, отправляющему сообщения вdeliver_subject. Без него сообщения не поступают. Pull-потребители отвечают через импорт API и в нём не нуждаются.
Листовые узлы
Поток одного домена JetStream может читать источник другого домена через соединение листового узла. Темы те же, но есть два различия:
- Ответы
$JSC.Rне переписываются, поэтому проходят соединение и требуют разрешения. - Разрешения соединения листового узла заменяют экспорт и импорт.
При разных доменах соединение запрещает $JS.API.>, $KV.> и $OBJ.> в обоих направлениях. Запросам нужен доменный префикс $JS.<domain>.API, который принимающий сервер преобразует в собственный $JS.API. Разрешения проверяются до преобразования и должны задавать $JS.<domain>.API, а не $JS.API.
Разрешения листового узла задаются на центральном сервере пользователю подключения: publish ограничивает отправляемое листовым узлом в центр, subscribe — отправляемое центром листовому узлу. $JS.ACK освобождён от проверки сообщений, отправленных листовым узлом; $JS.FC и $JSC.R — нет.
Поток листового узла читает источник из центра
Центр работает в домене HUB и содержит EVENTS. Источник листового узла использует "api": "$JS.HUB.API". Для временного или управляемого сервером потребителя с "deliver": "DELIVER.LEAF.COPY":
permissions: {
publish: { allow: [
"$JS.HUB.API.CONSUMER.CREATE.EVENTS",
"$JS.HUB.API.CONSUMER.CREATE.EVENTS.>",
"$JS.HUB.API.CONSUMER.DELETE.EVENTS.*",
"$JS.FC.EVENTS.>",
"$JS.FC.*.*.EVENTS.>"
] }
subscribe: { allow: [ "DELIVER.LEAF.COPY.>", "$JSC.R.>" ] }
}
Для пользовательского долговременного потребителя COPY_SRC с deliver_subject, равной DELIVER.LEAF.COPY_SRC:
permissions: {
publish: { allow: [
"$JS.HUB.API.CONSUMER.RESET.EVENTS.COPY_SRC",
"$JS.FC.EVENTS.COPY_SRC.*",
"$JS.FC.*.*.EVENTS.COPY_SRC.*"
] }
subscribe: { allow: [ "DELIVER.LEAF.COPY_SRC", "$JSC.R.>" ] }
}
Без $JSC.R.> данные не идут, а источник не показывает ошибки. Для ограничения одним потоком см. форматы $JSC.R.
Центр читает источник из листового узла
При чтении потоком центра источника домена LEAF направления меняются местами. Источник центра задаёт "api": "$JS.LEAF.API" и "deliver": "DELIVER.HUB.COPY", а разрешения того же пользователя листового узла становятся такими:
permissions: {
publish: { allow: [ "DELIVER.HUB.COPY.>", "$JSC.R.>" ] }
subscribe: { allow: [
"$JS.LEAF.API.CONSUMER.CREATE.EVENTS",
"$JS.LEAF.API.CONSUMER.CREATE.EVENTS.>",
"$JS.LEAF.API.CONSUMER.DELETE.EVENTS.*",
"$JS.FC.EVENTS.>",
"$JS.FC.*.*.EVENTS.>"
] }
}
Если листовой узел дополнительно ограничивает свою сторону через deny_imports или deny_exports удалённого соединения, эти темы также нельзя запрещать.
Форматы тем
У $JS.ACK, $JS.FC и $JSC.R есть формат v2, добавляющий домен и хеш учётной записи. Одинаковые имена потоков и потребителей разных доменов и записей перестают конфликтовать, а разрешение можно ограничить одним потоком.
Форматы $JS.ACK и $JS.FC
| Тема | Формат | Серверы |
|---|---|---|
$JS.ACK v1 | $JS.ACK.<stream>.<consumer>.<num delivered>.<stream seq>.<consumer seq>.<timestamp>.<num pending> | все |
$JS.ACK v2 | $JS.ACK.<domain>.<account hash>.<stream>.<consumer>.<num delivered>.<stream seq>.<consumer seq>.<timestamp>.<num pending> | 2.14+ |
$JS.FC v1 | $JS.FC.<stream>.<consumer>.<uid> | все |
$JS.FC v2 | $JS.FC.<domain>.<account hash>.<stream>.<consumer>.<uid> | 2.14+ |
<domain> — домен JetStream сервера потребителя или _, если домена нет. <account hash> — хеш учётной записи потребителя.
Флаг js_ack_fc_v2 сервера потребителя выбирает формат обеих тем. В 2.14 и 2.15 он по умолчанию выключен, с 2.16 — включён:
feature_flags {
js_ack_fc_v2: true
}
Серверы 2.14 и новее принимают оба формата независимо от флага. До 2.14 существует только v1, а конфигурация с блоком feature_flags не загружается.
Форматы $JSC.R
| Формат | Серверы |
|---|---|
v1 $JSC.R.<uid> | все |
v2 $JSC.R.<domain>.<account hash>.<stream>.<consumer>.<uid> | 2.15+ |
В v2 <stream> и <consumer> обозначают исходный поток и его потребителя. <account hash> — хеш учётной записи читающего потока. <domain> — второй сегмент префикса api: домен для $JS.<domain>.API или учётная запись для ACC.<account>.API. Без блока external используется _.
Флаг js_api_reply_v2 выбирает формат и по умолчанию выключен. Отвечающий сервер не разбирает тему ответа, поэтому флаг нужен только серверу читающего потока:
feature_flags {
js_api_reply_v2: true
}
При включённом v2 на листовом узле разрешение может задать один удалённый поток вместо $JSC.R.>:
subscribe: { allow: [ "DELIVER.LEAF.COPY.>", "$JSC.R.HUB.*.EVENTS.>" ] }
Без флага разрешение не совпадает ни с одним ответом, и источник не запускается.
Ограниченные экспорты и разрешения
Экспорт, импорт или разрешение только с префиксом охватывает оба формата. Ограничение потоком или потребителем требует обеих форм для работы после смены значения по умолчанию:
| Область | Запись v1 | Запись v2 |
|---|---|---|
| Подтверждения одного потока | $JS.ACK.<stream>.> | $JS.ACK.*.*.<stream>.> |
| Управление потоком одного потока | $JS.FC.<stream>.> | $JS.FC.*.*.<stream>.> |
| Управление потоком одного потребителя | $JS.FC.<stream>.<consumer>.* | $JS.FC.*.*.<stream>.<consumer>.* |
| Ответы одного исходного потока | недоступно, используйте $JSC.R.> | $JSC.R.<domain>.*.<stream>.> |
Запись только v1 перестаёт совпадать после переключения сервера потребителя на v2. Подтверждения больше не достигают исходной учётной записи, а чтение источника останавливается на управлении потоком.
См. также
- Обновление до 2.14: долговременные источники, политика подтверждений
flow_control, API сброса потребителя и смена формата тем. - Изучение → Зеркала и источники: создание зеркала и источника, в том числе через границы учётных записей и доменов.
- Конфигурация потока: все поля блоков
externalиconsumerисточника или зеркала. - ADR-60: долговременные источники и API сброса потребителя.