# RustStream
**RustStream** подписывает Rust-сервис на потоки событий и публикует в них сообщения. Сервис при
этом не привязан к одному брокеру очереди. Ядро - это трейты и рантайм с роутером. Вместе с ядром
поставляются кодеки, генерация AsyncAPI, метрики Prometheus и набор проверок `conformance` для
авторов адаптаций библиотек брокеров.
Фреймворк определяют два архитектурных обязательства:
1. **Полноценный интерфейс для сторонних брокеров.** Контракт ядра - трейты и типы, и ядро не
зависит ни от одного клиента брокера. Адаптация библиотеки каждого брокера - самостоятельный
крейт. Соблюдение контракта проверяет набор `conformance`.
2. **Конфигурация брокера остаётся в адаптации его библиотеки.** В ядре нет ни настроек, ни
умолчаний, привязанных к конкретному брокеру очереди. Каждая адаптация объявляет свой `Config`.
Поэтому изменение клиентской библиотеки затрагивает только её адаптацию, а не фреймворк.
=== "Макросы"
```rust
--8<-- "examples/quickstart.rs"
```
=== "Вручную"
```rust
--8<-- "examples/manual/quickstart.rs"
```
`#[ruststream::app]` генерирует `main` со всем шаблонным кодом рантайма. Поэтому `cargo run -- run`
запускает сервис, а `cargo run -- asyncapi gen` печатает его AsyncAPI-документ.
## Принципы устройства
- **Полностью асинхронный, на tokio.** В публичном API нет блокирующих вызовов.
- **Обобщённое ядро, никакого `dyn` в контракте.** Контракт построен на ассоциированных типах и
нативном `async fn in trait`. Стирание типов, если оно нужно сервису, выполняет рантайм.
- **Подписчики - это `Stream`, а не колбэки.** Обратное давление обеспечивает сам `Stream`. Колбэки
надстраивает рантайм.
- **Ack поглощает `self`.** Второй ack - ошибка компиляции.
- **Трейты-совместимости для необязательных возможностей.** `BatchSubscriber`,
`TransactionalPublisher`, `RequestReply`, `Partitioned` и `Seekable` не входят в обязательный
интерфейс.
## Куда идти дальше
<div class="grid cards" markdown>
- :material-download: **[Установка](getting-started/installation.md)** - подключение крейта и выбор фич.
- :material-rocket-launch: **[Быстрый старт](getting-started/quickstart.md)** - сервис из шаблона одной командой `cargo generate`.
- :material-school: **[Учебник](getting-started/tutorial.md)** - первый сервис шаг за шагом.
- :material-test-tube: **[Тестирование](https://docs.rs/ruststream/latest/ruststream/testing/index.html)** - тесты обработчиков внутри процесса, без сервера.
- :material-web: **[HTTP-фреймворки](https://docs.rs/ruststream/latest/ruststream/runtime/index.html#running-beside-another-server)** - сервис рядом с axum и транзакционный outbox.
- :material-transit-connection-variant: **[Брокеры](brokers/index.md)** - in-memory брокер и адаптации библиотек остальных брокеров.
- :material-server-network: **[Авторам брокеров](broker-authors/index.md)** - как написать адаптацию библиотеки брокера: контракт и проверки `conformance`.
</div>
## Что входит в этот репозиторий
Этот сайт документирует `ruststream` - ядро, не зависящее от брокера. Адаптации библиотек
конкретных брокеров (NATS, Kafka, RabbitMQ, Redis, MQTT и других) поставляются отдельными
крейтами. Каждая адаптация подключает `ruststream` с crates.io.
Справочник по Rust API опубликован на [docs.rs](https://docs.rs/ruststream) - см.
[Справочник API](reference.md).