doc: actyalize

2026-05-26 07:08:11 +00:00 · 2026-05-11 15:32:12 +03:00
parent 68a144d6c0
commit 150b3a6c8b
6 changed files with 50 additions and 36 deletions
--- a/docs/about.md
+++ b/docs/about.md
@@ -15,7 +15,7 @@
 3. [Как это работает](#3-как-это-работает)
 4. [Архитектура](#4-архитектура)
 5. [Структура репозитория](#5-структура-репозитория)
-6. [Carriers - провайдеры](#6-carriers--провайдеры)
+6. [Auth-провайдеры](#6-auth-провайдеры)
 7. [Transports - транспорты](#7-transports--транспорты)
 8. [Шифрование](#8-шифрование)
 9. [Мультиплексирование](#9-мультиплексирование)
@@ -117,7 +117,7 @@
  Transport (datachannel / vp8channel / seichannel / videochannel)
       │
       ▼
-  Carrier (jazz / wbstream / telemost)
+  Auth (jazz / wbstream / telemost)
       │ WebRTC DataChannel или VideoTrack
       ▼
  SFU Яндекса / Сбера / WB   ← сервер в белом списке у всех провайдеров
@@ -163,7 +163,7 @@ internal/transport/     интерфейс Transport + реестр
    ├── seichannel/     H264 SEI NAL-юниты
    └── videochannel/   QR-коды / тайлы в VP8 видеофрейме через ffmpeg
    │
-internal/carrier/       интерфейс Carrier + реестр
+internal/auth/          реестр auth-провайдеров
    ├── builtin/        регистрация engine/auth адаптеров
    └── bytestream.go   ByteStream, VideoTrack capability
    │
@@ -254,7 +254,7 @@ internal/e2e/           E2E тесты на реальных провайдер
 | `transport.go` | Интерфейс `Transport` + реестр. `Features` описывает: надёжность, упорядоченность, message-oriented или stream, макс. размер payload |
 | `transport_test.go` | Тесты реестра |
 | `datachannel/transport.go` | Самый простой транспорт. Открывает ByteStream у carrier (DataChannel), просто форвардит байты. Лимит payload: 12KB |
-| `vp8channel/transport.go` | Данные кодируются в VP8 видеофреймы. Поверх carrier строится KCP (надёжный UDP-подобный протокол) для реорганизации и ретрансмиссии. Данные батчатся по N фреймов за тик. Keepalive через keyframe |
+| `vp8channel/transport.go` | Данные кодируются в VP8 видеофреймы. Поверх auth-провайдера строится KCP (надёжный UDP-подобный протокол) для реорганизации и ретрансмиссии. Данные батчатся по N фреймов за тик. Keepalive через keyframe |
 | `vp8channel/kcp.go` | KCP сессия: conv ID = `0xC0FFEE01`, MTU 1400, окно 4096 сегментов. Length-prefix framing поверх KCP stream mode (workaround бага kcp-go с фрагментацией) |
 | `vp8channel/kcpconn.go` | `io.ReadWriteCloser` адаптер для KCP |
 | `seichannel/transport.go` | Данные передаются в SEI NAL-юнитах внутри H264 видеопотока. Собственный бинарный протокол с magic `OVC1`, версией, типами фреймов Data/Ack, CRC32, sequence numbers. ACK timeout, фрагментация, ретрансмиссия |
@@ -272,7 +272,7 @@ internal/e2e/           E2E тесты на реальных провайдер
 | `bytestream.go` | `ByteStream` и `VideoTrack` интерфейсы |
 | `carrier_test.go` | Тесты |
 | `builtin/register.go` | Регистрирует все engine/auth комбинации в реестре carrier |
-| `builtin/engine_adapter.go` | Адаптер `engine.Session` → `carrier.Session` + `registerDirect()` для режима без auth |
+| `builtin/engine_adapter.go` | Адаптер `engine.Session` → `auth.Provider` + `registerDirect()` для режима без auth |

 ### `internal/engine/`

@@ -337,7 +337,7 @@ Wire-level SFU протоколы. Каждый умеет Connect/Send/Close/Wa

 | Файл | Что делает |
 |---|---|
-| `tunnel_test.go` | E2E тесты на реальных провайдерах. Матрица всех carrier × transport комбинаций. Запускается с флагом `-olcrtc.real-e2e`. В CI запускается на каждый push |
+| `tunnel_test.go` | E2E тесты на реальных провайдерах. Матрица всех auth × transport комбинаций. Запускается с флагом `-olcrtc.real-e2e`. В CI запускается на каждый push |

 ### `mobile/`

@@ -366,7 +366,7 @@ Wire-level SFU протоколы. Каждый умеет Connect/Send/Close/Wa

 | Файл | Что делает |
 |---|---|
-| `srv.sh` | Интерактивный скрипт запуска сервера через Podman. Задаёт вопросы про carrier/transport/room/key, собирает образ, запускает контейнер. Флаги: `--branch=<name>` (сменить ветку), `--no-cache` (очистить Go-кеш перед сборкой) |
+| `srv.sh` | Интерактивный скрипт запуска сервера через Podman. Задаёт вопросы про auth/transport/room/key, собирает образ, запускает контейнер. Флаги: `--branch=<name>` (сменить ветку), `--no-cache` (очистить Go-кеш перед сборкой) |
 | `cnc.sh` | Интерактивный скрипт запуска клиента через Podman |
 | `docker/olcrtc-entrypoint.sh` | Docker entrypoint: читает env переменные, формирует CLI флаги, запускает `olcrtc` |
 | `docker/olcrtc-healthcheck.sh` | Docker healthcheck: проверяет что процесс запущен |
@@ -384,15 +384,15 @@ Wire-level SFU протоколы. Каждый умеет Connect/Send/Close/Wa
 |---|---|
 | `fast.md` | Быстрый старт через скрипты (Podman) |
 | `manual.md` | Мануальная сборка: Go, mage, кросс-компиляция, все шаги |
-| `settings.md` | Матрица совместимости carrier×transport, все CLI флаги с описанием, готовые команды |
-| `uri.md` | URI формат для клиентских приложений: `olcrtc://<Carrier>?<Transport>@<RoomID>#<Key>%<ClientID>$<MIMO>` |
+| `settings.md` | Матрица совместимости auth×transport, все CLI флаги с описанием, готовые команды |
+| `uri.md` | URI формат для клиентских приложений: `olcrtc://<Auth>?<Transport>@<RoomID>#<Key>%<ClientID>$<MIMO>` |
 | `sub.md` | Формат подписок: список серверов в одном файле с метаданными |

 ---

-## 6. Carriers - провайдеры
+## 6. Auth-провайдеры

-Carrier - это WebRTC сервис видеозвонков, через который идёт туннель. Все три в белых списках у российских провайдеров.
+Auth-провайдер — это WebRTC сервис видеозвонков, через который идёт туннель. Все три в белых списках у российских провайдеров.

 ### SaluteJazz (`jazz`)

@@ -524,13 +524,13 @@ export all_proxy=socks5h://user:pass@127.0.0.1:8808  # с авторизацие
 Community Android клиент: [alananisimov/olcbox](https://github.com/alananisimov/olcbox)

 **API:**
- `Start(carrier, roomID, clientID, keyHex string)` - запустить туннель
+- `Start(auth, roomID, clientID, keyHex string)` - запустить туннель
 - `Stop()` - остановить
 - `IsRunning() bool`
 - `SetProtector(p SocketProtector)` - Android VPN bypass (VpnService.protect)
 - `SetLogWriter(w LogWriter)` - получать логи в Kotlin/Java

-По умолчанию использует `vp8channel` транспорт (наиболее совместимый). Если carrier - wbstream или jazz и DataChannel доступен - переключается на `datachannel`.
+По умолчанию использует `vp8channel` транспорт (наиболее совместимый). Если auth - wbstream или jazz и DataChannel доступен - переключается на `datachannel`.

 `protect.go` - механизм Android VPN protect: перед каждым `connect()` вызывается Kotlin-коллбэк который вызывает `VpnService.protect(fd)`. Без этого трафик olcRTC может рекурсивно идти через тот же VPN.

@@ -539,6 +539,7 @@ Community Android клиент: [alananisimov/olcbox](https://github.com/alanani
 ## 12. Go-либа (pkg/olcrtc)

 `pkg/olcrtc` - публичная Go-либа для встраивания olcrtc в другие Go-программы (sing-box, кастомные клиенты).
+Каждый провайдер реализует метод `DefaultServiceURL()`, что позволяет библиотеке автоматически заполнять адрес SFU при выборе провайдера.

 ```go
 import "github.com/openlibrecommunity/olcrtc/pkg/olcrtc"
@@ -664,7 +665,7 @@ openssl rand -hex 32
 ### Docker

 ```sh
-docker run -e OLCRTC_CARRIER=wbstream \
+docker run -e OLCRTC_AUTH=wbstream \
           -e OLCRTC_ROOM_ID=... \
           -e OLCRTC_KEY=... \
           olcrtc/server:local
@@ -679,7 +680,7 @@ docker run -e OLCRTC_CARRIER=wbstream \
 | Флаг | Описание |
 |---|---|
 | `-mode` | `srv` - сервер, `cnc` - клиент, `gen` - генерация Room ID |
-| `-auth` | `telemost`, `jazz`, `wbstream` |
+| `-auth` | `telemost`, `jazz`, `wbstream`, `none` |
 | `-transport` | `datachannel`, `vp8channel`, `seichannel`, `videochannel` |
 | `-id` | Room ID |
 | `-client-id` | Идентификатор клиента, должен совпадать на srv и cnc. Один client-id может держать бесконечное количество соединений, но SFU ограничивает полосу на участника — оптимально 1 client-id = 1 пользователь (не обязательно) |
@@ -688,9 +689,11 @@ docker run -e OLCRTC_CARRIER=wbstream \
 | `-data` | Всегда `data` |
 | `-dns` | DNS сервер, например `1.1.1.1:53` |

-### Прямой режим (без auth-провайдера)
+### Прямой режим

-Для подключения напрямую к любому LiveKit/Goolom/SaluteJazz SFU без сервисного login flow:
+Позволяет подключиться напрямую к любому LiveKit/Goolom/SaluteJazz SFU.
+При использовании `-auth none` флаги `-engine`, `-url` и `-token` обязательны.
+При использовании именованного провайдера эти флаги заполняются автоматически из `DefaultServiceURL()`, но могут быть переопределены вручную.

 | Флаг | Описание |
 |---|---|
@@ -767,7 +770,7 @@ docker run -e OLCRTC_CARRIER=wbstream \
 Соглашение для клиентских приложений. Сам `olcrtc` не парсит - используется в сторонних клиентах.

 ```
-olcrtc://<Carrier>?<Transport><payload>@<RoomID>#<Key>%<ClientID>$<MIMO>
+olcrtc://<Auth>?<Transport><payload>@<RoomID>#<Key>%<ClientID>$<MIMO>
 ```

 Где `<payload>` - опциональный блок `<key=value&...>` с параметрами транспорта.
--- a/docs/fast.md
+++ b/docs/fast.md
@@ -85,7 +85,7 @@ cd olcrtc
 ### Auth (на каком сервисе передавать трафик)

 ```
-Select auth:
+Select auth provider:
  1) telemost
  2) jazz
  3) wbstream
@@ -232,11 +232,11 @@ SEI ACK timeout in milliseconds [default: 3000]: 2000
 [+] Server started successfully!

 Container name: olcrtc-server
-Carrier:        Carrier
-Transport:      Transport
-Room ID:        Room ID
+Auth:           wbstream
+Transport:      datachannel
+Room ID:        abc123xyz
 Client ID:      default
-Encryption key: Encryption key
+Encryption key: d823fa01cb3e0609b67322f7cf984c4ee2e4ce2e294936fc24ef38c9e59f4799
 ```

 **Сохрани Room ID, Client ID и Encryption key** - они нужны для клиента.
@@ -253,7 +253,7 @@ cd olcrtc
 ./script/cnc.sh
 ```

-Отвечай на те же вопросы что на сервере - **carrier, transport, room ID и client ID должны совпадать**.
+Отвечай на те же вопросы что на сервере - **auth, transport, room ID и client ID должны совпадать**.

 Когда спросит client ID:

--- a/docs/manual.md
+++ b/docs/manual.md
@@ -159,7 +159,7 @@ CLIENT_ID=default

 ## Шаг 8: Запустить сервер

-На серверной машине (VPS и т.д.). Подбери нужную комбинацию carrier + transport из матрицы в [settings.md](settings.md).
+На серверной машине (VPS и т.д.). Подбери нужную комбинацию auth + transport из матрицы в [settings.md](settings.md).

 ### wbstream + datachannel (рекомендуется - максимальная скорость и пинг)

@@ -205,7 +205,7 @@ Room ID нужно передать клиенту.

 ## Шаг 9: Запустить клиент

-На своей машине. Carrier, transport, id, `client-id` и key должны совпадать с сервером.
+На своей машине. Auth, transport, id, `client-id` и key должны совпадать с сервером.

 ### wbstream + datachannel

--- a/docs/settings.md
+++ b/docs/settings.md
@@ -35,7 +35,7 @@
 | Флаг | Что вводить |
 |------|-------------|
 | `-mode` | `srv` на сервере, `cnc` на клиенте, `gen` для генерации Room ID |
-| `-auth` | `telemost`, `jazz` или `wbstream` |
+| `-auth` | `telemost`, `jazz`, `wbstream`, `none` |
 | `-transport` | `datachannel`, `vp8channel`, `seichannel` или `videochannel` |
 | `-id` | Room ID |
 | `-client-id` | Общий идентификатор клиента. Должен совпадать на сервере и клиенте. Один client-id может держать бесконечное количество соединений, но SFU ограничивает полосу на участника - оптимально 1 client-id = 1 пользователь (не обязательно) |
@@ -46,6 +46,17 @@

 ---

+## Прямой режим
+
+При использовании `-auth none` флаги `-engine`, `-url` и `-token` обязательны.
+Для остальных провайдеров они заполняются автоматически, но их можно переопределить.
+
+| Флаг | Описание |
+|------|----------|
+| `-engine` | `livekit`, `goolom` или `salutejazz` |
+| `-url` | WebSocket URL SFU |
+| `-token` | Токен доступа |
+
 ## Необязательные флаги

 | Флаг | Описание |
--- a/docs/sub.md
+++ b/docs/sub.md
@@ -92,8 +92,8 @@ olcrtc://...
 Каждая строка сервера содержит один `olcrtc`-URI в формате из [uri.md](uri.md):

 ```text
-olcrtc://<Carrier>?<Transport>@<RoomID>#<EncryptionKey>%<ClientID>$<MIMO>
-olcrtc://<Carrier>?<Transport><key=value&key=value>@<RoomID>#<EncryptionKey>%<ClientID>$<MIMO>
+olcrtc://<Auth>?<Transport>@<RoomID>#<EncryptionKey>%<ClientID>$<MIMO>
+olcrtc://<Auth>?<Transport><key=value&key=value>@<RoomID>#<EncryptionKey>%<ClientID>$<MIMO>
 ```

 Одна строка = один сервер/одна запись подписки.
@@ -165,4 +165,4 @@ olcrtc://wbstream?datachannel@abc123xyz#aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

 URI-формат для отдельного сервера: [uri.md](uri.md)

-Матрица совместимости carrier + transport: [settings.md](settings.md)
+Матрица совместимости auth + transport: [settings.md](settings.md)
--- a/docs/uri.md
+++ b/docs/uri.md
@@ -19,8 +19,8 @@
 ## Формат

 ```text
-olcrtc://<Carrier>?<Transport>@<RoomID>#<EncryptionKey>%<ClientID>$<MIMO>
-olcrtc://<Carrier>?<Transport><key=value&key=value>@<RoomID>#<EncryptionKey>%<ClientID>$<MIMO>
+olcrtc://<Auth>?<Transport>@<RoomID>#<EncryptionKey>%<ClientID>$<MIMO>
+olcrtc://<Auth>?<Transport><key=value&key=value>@<RoomID>#<EncryptionKey>%<ClientID>$<MIMO>
 ```

 Все поля после `olcrtc://` считаются частью клиентского соглашения.
@@ -33,10 +33,10 @@ olcrtc://<Carrier>?<Transport><key=value&key=value>@<RoomID>#<EncryptionKey>%<Cl

 | Поле | Значение |
 |------|----------|
-| `<Carrier>` | Имя carrier, например `telemost`, `jazz`, `wbstream` |
+| `<Auth>` | Имя auth-провайдера, например `telemost`, `jazz`, `wbstream` |
 | `<Transport>` | Имя транспорта, например `datachannel`, `vp8channel`, `seichannel`, `videochannel` |
 | payload | Параметры транспорта в `<key=value&...>`. Ключи совпадают с CLI-флагами без дефиса. Блок опускается если используются defaults |
-| `<RoomID>` | Идентификатор комнаты или carrier-specific room URL/ID |
+| `<RoomID>` | Идентификатор комнаты или auth-specific room URL/ID |
 | `<EncryptionKey>` | Ключ шифрования в hex, обычно 64 символа (`32` байта) |
 | `<ClientID>` | Идентификатор клиента. Должен совпадать с ожидаемым значением на сервере. Один client-id может держать бесконечное количество соединений, но SFU ограничивает полосу на участника — оптимально 1 client-id = 1 пользователь (не обязательно) |
 | `<MIMO>` | Свободный комментарий для UI/метаданных, например `RU / olc free sub / IPv6` |
@@ -86,7 +86,7 @@ Payload не используется.

 | URI поле | Параметр / значение |
 |----------|---------------------|
-| `<Carrier>` | `-auth` |
+| `<Auth>` | `-auth` |
 | `<Transport>` | `-transport` |
 | payload | соответствующие флаги транспорта |
 | `<RoomID>` | `-id` |
@@ -207,4 +207,4 @@ olcrtc://telemost?videochannel<video-w=1080&video-h=1080&video-fps=60&video-bitr

 Формат подписки (список серверов): [sub.md](sub.md)

-Матрица совместимости carrier + transport: [settings.md](settings.md)
+Матрица совместимости auth + transport: [settings.md](settings.md)