Перейти к основному содержимому
Версия: 2.14

Темы между учётными записями

Поток, читающий источник или зеркало из другой учётной записи либо домена 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 сброса потребителя.