From 150b3a6c8be6f57744fad54140e33d4d19840221 Mon Sep 17 00:00:00 2001 From: zarazaex69 Date: Mon, 11 May 2026 15:32:12 +0300 Subject: [PATCH] doc: actyalize --- docs/about.md | 39 +++++++++++++++++++++------------------ docs/fast.md | 12 ++++++------ docs/manual.md | 4 ++-- docs/settings.md | 13 ++++++++++++- docs/sub.md | 6 +++--- docs/uri.md | 12 ++++++------ 6 files changed, 50 insertions(+), 36 deletions(-) diff --git a/docs/about.md b/docs/about.md index 96c5785..79bdd51 100644 --- 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=` (сменить ветку), `--no-cache` (очистить Go-кеш перед сборкой) | +| `srv.sh` | Интерактивный скрипт запуска сервера через Podman. Задаёт вопросы про auth/transport/room/key, собирает образ, запускает контейнер. Флаги: `--branch=` (сменить ветку), `--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://?@#%$` | +| `settings.md` | Матрица совместимости auth×transport, все CLI флаги с описанием, готовые команды | +| `uri.md` | URI формат для клиентских приложений: `olcrtc://?@#%$` | | `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://?@#%$ +olcrtc://?@#%$ ``` Где `` - опциональный блок `` с параметрами транспорта. diff --git a/docs/fast.md b/docs/fast.md index c707359..4c766c8 100644 --- 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: diff --git a/docs/manual.md b/docs/manual.md index ea2d22f..9fb6bc8 100644 --- 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 diff --git a/docs/settings.md b/docs/settings.md index e24bd30..9d6424d 100644 --- 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` | Токен доступа | + ## Необязательные флаги | Флаг | Описание | diff --git a/docs/sub.md b/docs/sub.md index 4ac5669..d9eb4e9 100644 --- a/docs/sub.md +++ b/docs/sub.md @@ -92,8 +92,8 @@ olcrtc://... Каждая строка сервера содержит один `olcrtc`-URI в формате из [uri.md](uri.md): ```text -olcrtc://?@#%$ -olcrtc://?@#%$ +olcrtc://?@#%$ +olcrtc://?@#%$ ``` Одна строка = один сервер/одна запись подписки. @@ -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) diff --git a/docs/uri.md b/docs/uri.md index 2cc1269..5f02c3d 100644 --- a/docs/uri.md +++ b/docs/uri.md @@ -19,8 +19,8 @@ ## Формат ```text -olcrtc://?@#%$ -olcrtc://?@#%$ +olcrtc://?@#%$ +olcrtc://?@#%$ ``` Все поля после `olcrtc://` считаются частью клиентского соглашения. @@ -33,10 +33,10 @@ olcrtc://?@#%` | Имя carrier, например `telemost`, `jazz`, `wbstream` | +| `` | Имя auth-провайдера, например `telemost`, `jazz`, `wbstream` | | `` | Имя транспорта, например `datachannel`, `vp8channel`, `seichannel`, `videochannel` | | payload | Параметры транспорта в ``. Ключи совпадают с CLI-флагами без дефиса. Блок опускается если используются defaults | -| `` | Идентификатор комнаты или carrier-specific room URL/ID | +| `` | Идентификатор комнаты или auth-specific room URL/ID | | `` | Ключ шифрования в hex, обычно 64 символа (`32` байта) | | `` | Идентификатор клиента. Должен совпадать с ожидаемым значением на сервере. Один client-id может держать бесконечное количество соединений, но SFU ограничивает полосу на участника — оптимально 1 client-id = 1 пользователь (не обязательно) | | `` | Свободный комментарий для UI/метаданных, например `RU / olc free sub / IPv6` | @@ -86,7 +86,7 @@ Payload не используется. | URI поле | Параметр / значение | |----------|---------------------| -| `` | `-auth` | +| `` | `-auth` | | `` | `-transport` | | payload | соответствующие флаги транспорта | | `` | `-id` | @@ -207,4 +207,4 @@ olcrtc://telemost?videochannel