# EVENT JOURNAL & BUS — `core/events.uc`

Кольцевой журнал событий и шина фактов: единственный способ, которым наблюдатели
узнают, что что-то произошло. 591 строка, экспортируется через
`module_exports()`.

Документ описывает фактический код.

---

## 1. Два разных механизма, один модуль

В модуле два слоя, их важно не путать:

- **шина (`bus`)** — доставка факта подписчикам **в памяти процесса**;
- **журнал (`journal`)** — кольцевой буфер на диске для **послезапросного** чтения.

Факт может уйти в шину и не попасть в журнал; и наоборот. Журнал — для
диагностики постфактум (что было за минуту до деградации), шина — для реакции
в текущем процессе (watchdog чинит немедленно).

---

## 2. Шина

```ucode
let bus = require("core.events").bus({ journal: journal_instance });
bus.subscribe("dns.down", handler);
bus.emit("dns.down", payload);
```

Подписчики вызываются в порядке подписки. Факт — `{ type, payload }`;
тип приходит из реестра событий, а не из строки в коде, чтобы опечатка в имени
не превращалась в молчащий подписчик.

`attach_journal()` подключает журнал к шине так, что каждый опубликованный факт
автоматически попадает в буфер.

---

## 3. Журнал

Файл: `/var/run/tachyon/events.jsonl` — построчный JSON, не один большой файл.

Фолбэк: если `/var/run` недоступен для записи, журнал уходит в
`/tmp/tachyon/events.jsonl`. Это не деградация без последствий — на части
прошивок `/var/run` смонтирован read-only, и без фолбэка диагностика молча
переставала бы писаться.

### Ограничители

| Параметр | По умолчанию | Зачем |
|---|---|---|
| `max_entries` | 500 | кольцо по числу записей |
| `max_bytes` | 256 КБ | кольцо по размеру |

Оба ограничителя нужны одновременно: записи сильно различаются по размеру
(одна — короткий факт, другая — дамп ошибки), и лимит только по числу дал бы
вытеснение всего буфера одной большой записью.

`compact()` переписывает буфер атомарно при достижении предела — не в
`/var/run/tachyon` (это tmpfs, там каждый байт занят), а через tmp-файл с
последующим `mv`.

---

## 4. Санитизация секретов

Журнал читают люди и агенты, поэтому секреты маскируются **на записи**, а не на
чтении.

Ключи в JSON-объектах:
`password`, `secret`, `token`, `auth`, `api_key`, `bot_token`, `private_key`,
`credential`, `cookie` и далее → `[REDACTED]`.

Значения в тексте:

| Что | Замена |
|---|---|
| токен Telegram-бота `\d{8,12}:...` | `[REDACTED_TELEGRAM_TOKEN]` |
| `Bearer <token>` | `Bearer [REDACTED_TOKEN]` |
| `vless://UUID@`, `trojan://PASS@` | `vless://[REDACTED_UUID]@` |
| секрет в query `?secret=...` | значение заменено |

Рекурсивный обход вложенных объектов и массивов: маскировать только верхний
уровень означало бы, что `{"a":{"b":{"bot_token":"..."}}}` утекает.

---

## 5. Схема записи

```
ts, ms, event, severity, source, job_id, correlation_id, message, data
```

`correlation_id` связывает факты одной операции: по нему восстанавливается
цепочка «задача стартовала → шаг упал → откат пошёл». Без него расследование
инцидента по разрозненным фактам невозможно.

---

## 6. Запросы

```ucode
journal.record(event, data, meta);
journal.query(filter);
journal.tail(n);
journal.stats();
journal.clear();
```

`query(filter_opts)` — фильтрация по имени события, уровню серьёзности,
источнику, `job_id`, `correlation_id`, диапазону времени и тексту сообщения,
плюс сортировка и `tail(n)`.

CLI: `core/events.uc <selftest|record|query|tail|stats|clear|redact>`.
Бэкенд-биндинги: `event_query`, `event_tail`, `event_stats`, `event_clear`,
`event_record` (+ алиасы через дефис).

---

## 7. Клиенты

`eventClient.ts`: `query`, `tail`, `stats`, `clear`, `record`, `poll`.

`poll()` — не подписка: это опрос с дедупликацией по идентификаторам, защитой
памяти и колбэком отписки. Фронтенд работает через `uci call` / `rpcd` без
постоянного сокета, поэтому «поток» здесь — синтезированный.

---

## 8. Тесты

`tests/event_journal_redaction.sh` — санитизация 11 типов ключей, вложенные
структуры и массивы, URL прокси, токены в тексте сообщений, запись и фильтрация,
защита от переполнения буфера, интеграция с шиной, CLI-подкоманды.

`tests/event_bus.sh` — доставка и порядок вызова подписчиков.
