Трансляция сообщений

Аннотация

Приводятся требования по организации передачи сообщений в пределах эмуляции.

Механизм

Для передачи сообщений между акторами в пределах эмуляции планируется использование механизма Redis Pub/Sub. Это позволит быстро реализовать широковещательную трансляцию.

Учетные записи

Для целей подключения к Redis создано несколько учетных записей. Реквизиты доступа к учетным записям Redis представлены в совместной базе паролей команды разработчиков Viewergy Model.

Количество учетных записей соответствует числу сервисов. Так, например, все Пользователи будут «жить» в одном сервисе, и этот сервис будет иметь свою учетную запись в Redis. Значит, по сути, все пользователи будут «пользоваться» одной и той же учетной записью: технической учетной записью для сервиса «Пользователи».

Дополнительная учётная запись может быть использована для подключения участников команды разработки (через инструменты типа Redis Insight или другие).

Каналы и их именование

Для унификации структуры обмена сообщениями должен использоваться фиксированный формат имен каналов Redis Pub/Sub. Формат имени канала должен включать в себя три компонента, разделенных точками:

... где:

level — уровень симуляции: micro, meso, macro;
actor_type — тип актора (например: miner, exchange, timer, calendar, user, oracle, world и др.);
event_type — тип события (краткое описание действия или состояния: mined, order_cancelled, tick, rollover, created, updated, failed и т. п.).

Примеры каналов:

micro.miner.mined — событие добычи токена майнером: майнер успешно добыл токены;
meso.exchange.order_cancelled — событие отмены ордера на бирже;
macro.timer.tick — событие тика таймера мирового времени;
macro.calendar.rollover — событие смены календарного периода (дня, недели, месяца и т. д.).

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

Среди каналов можно будет легко найти нужный: уровней всего три: micro, meso, macro. В пределах уровней — ограниченное число акторов. У каждого актора — ограниченное число типа событий.

Формат сообщений

С целью унификации, каждое сообщение, передаваемое через Redis Pub/Sub, должно иметь единообразную структуру и состоять из двух основных частей:

header — заголовок сообщения, содержащий служебную, идентификационную и маршрутизационную информацию;
payload — полезная нагрузка, содержащая данные события.

Общий формат сообщения:

{
  "header": { ... },
  "payload": { ... }
}

Заголовок сообщения должен включать следующие поля:

id — уникальный идентификатор сообщения (UUIDv4);
schema — имя схемы сообщения (например: timer.tick, miner.mined, income_source.bond_placement_completed);
schema_version — версия схемы сообщения (используем семантическое версионирование формата "MAJOR.MINOR.PATCH");
ts_utc — момент отправки сообщения в формате UTC;
game_time — игровое (симуляционное) календарное время отправки сообщения (при наличии);
tick — номер тика симуляции, в который было сгенерировано сообщение;
broadcast.type — степень широковещательности:
- WORLD — всем акторам без исключения;
- LEVEL — всем акторам конкретного уровня (micro, meso, macro);
- KIND — всем акторам определенного вида (например, miner, exchange);
- CLASS — всем акторам определенного класса внутри вида;
- ACTOR — конкретному уникальному актору;
broadcast.value — конкретное значение (например, для LEVEL — здесь указываем какой: micro, meso, macro или идентификатор UUIDv4 конкретного уникального адресата (только если выбран "type": "ACTOR");
priority — приоритет сообщения: LOW, NORMAL, HIGH.

Пример структуры заголовка:

{
  "header": {
    "id": "f3f8b640-2a9b-4a19-9b2e-1234567890ab",
    "schema": "timer.tick",
    "schema_version": "0.1.0",
    "ts_utc": "2025-11-17T12:34:56Z",
    "game_time": "0001-02-06T12:00",
    "tick": 120345,
    "broadcast":
    {
      "type": "LEVEL",
      "value": "micro"
    },
    "priority": "NORMAL"
  }
}

Payload

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

Payload должен включать следующие поля:

text — человекочитаемое краткое описание события;
data — произвольный JSON-объект, содержащий доменные данные события (структура определяется типом события);
meta.tags — список тегов (для классификации и быстрой фильтрации);
meta.sender — информация об отправителе (если требуется), например: текущее состояние или статус;
meta.extra — произвольный объект для дополнительных параметров, не относящихся к основным данным.

Пример полезной нагрузки:

{
  "payload": {
    "text": "Tick 120345: наступил новый игровой час.",
    "data": {
      "tick": 120345,
      "game_time": {
        "year": 1,
        "month": 2,
        "day": 6,
        "hour": 12,
        "min": 0
      }
    },
    "meta": {
      "tags": ["time", "timer", "world"],
      "sender": {
          // здесь может быть информация об отправителе, например, текущее состояние таймера
        },     
      "extra": { 
          // здесь может быть дополнительная информация 
        }
    }
  }
}

Применимость формата

Для простых событий (например, тиков таймера) достаточно нескольких полей в разделе data.
Для сложных событий (например, завершения финансовых операций) структура data может содержать вложенные объекты и большие наборы данных.
Header остаётся стабильным и обеспечивает маршрутизацию, трассировку и единый формат для всех типов событий.
Payload предоставляет гибкость: как для простых, так и для высокодетализированных событий.

Прочее

Требований в части безопасности не предъявляется. Сообщения не содержат чувствительной информации, и конфиденциальность передачи не требуется.

22 November 2025