mirror of
https://github.com/openlibrecommunity/olcrtc.git
synced 2026-06-04 19:39:45 +00:00
doc: add sub doc for SUB format
This commit is contained in:
zarazaex69
151
docs/sub.md
Normal file
151
docs/sub.md
Normal file
@@ -0,0 +1,151 @@
|
||||
# Формат подписки `sub.md`
|
||||
|
||||
`sub.md` это обычный текстовый файл, который хостится на сервере и отдаётся как plain text.
|
||||
|
||||
Пример URL:
|
||||
|
||||
```text
|
||||
https://killpeople.freegore.xyz/sub
|
||||
```
|
||||
|
||||
Внутри файл содержит список `olcrtc`-URI из [uri.md](uri.md) и дополнительные технические поля для клиента.
|
||||
|
||||
Важно: это соглашение **для клиентских приложений**. Сам `olcrtc` такой файл не читает и не обрабатывает.
|
||||
|
||||
---
|
||||
|
||||
## Назначение
|
||||
|
||||
Формат нужен для клиентских подписок:
|
||||
|
||||
- список серверов в одном файле
|
||||
- метаданные подписки для UI
|
||||
- метаданные отдельных серверов
|
||||
- информация для автообновления подписки
|
||||
|
||||
---
|
||||
|
||||
## Общая структура
|
||||
|
||||
Файл читается сверху вниз и состоит из:
|
||||
|
||||
1. глобальных полей подписки с префиксом `#`
|
||||
2. строк `olcrtc://...`
|
||||
3. локальных полей конкретного сервера с префиксом `##`
|
||||
|
||||
Базовая схема:
|
||||
|
||||
```text
|
||||
#name: ...
|
||||
#update: ...
|
||||
#refresh: ...
|
||||
#color: ...
|
||||
#icon: ...
|
||||
#used: ...
|
||||
#available: ...
|
||||
|
||||
olcrtc://...
|
||||
##name: ...
|
||||
##color: ...
|
||||
##icon: ...
|
||||
##used: ...
|
||||
##available: ...
|
||||
##ip: ...
|
||||
##comment: ...
|
||||
|
||||
olcrtc://...
|
||||
##name: ...
|
||||
##comment: ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Глобальные поля подписки
|
||||
|
||||
Строки вида `#key: value` относятся ко всей подписке.
|
||||
|
||||
| Поле | Значение |
|
||||
|------|----------|
|
||||
| `#name:` | Имя подписки |
|
||||
| `#update:` | Время последнего обновления в Unix time |
|
||||
| `#refresh:` | Через какой интервал клиенту нужно обновлять подписку, например `5s`, `10m`, `6h` |
|
||||
| `#color:` | Цвет подписки. Поле только для UI |
|
||||
| `#icon:` | Иконка подписки. Поле только для UI |
|
||||
| `#used:` | Сколько уже использовано, например `10mb/10gb` |
|
||||
| `#available:` | Сколько доступно всего по подписке, например `1.1gb` |
|
||||
|
||||
`#available:` это именно значение на уровне всей подписки. Если клиент умеет считать остаток сам, он может использовать это поле как исходные данные или как отображаемую подсказку.
|
||||
|
||||
---
|
||||
|
||||
## Строки серверов
|
||||
|
||||
Каждая строка сервера содержит один `olcrtc`-URI в формате из [uri.md](uri.md):
|
||||
|
||||
```text
|
||||
olcrtc://<Carrier>?<Transport>@<RoomID>#<EncryptionKey>%<ClientID>$<MIMO>
|
||||
```
|
||||
|
||||
Одна строка = один сервер/одна запись подписки.
|
||||
|
||||
Пустые строки между элементами допустимы.
|
||||
|
||||
---
|
||||
|
||||
## Локальные поля сервера
|
||||
|
||||
Строки вида `##key: value` относятся только к **последнему URI**, который был объявлен выше.
|
||||
|
||||
То есть клиент должен привязывать блок `##...` к ближайшей предыдущей строке `olcrtc://...`.
|
||||
|
||||
| Поле | Значение |
|
||||
|------|----------|
|
||||
| `##name:` | Имя сервера/узла |
|
||||
| `##color:` | Цвет для UI |
|
||||
| `##icon:` | Иконка для UI |
|
||||
| `##used:` | Использование для конкретного сервера, например `500mb/10gb` |
|
||||
| `##available:` | Доступный объём для конкретного сервера |
|
||||
| `##ip:` | IP-адрес сервера, если его нужно показать клиенту |
|
||||
| `##comment:` | Свободный комментарий |
|
||||
|
||||
Локальные поля почти повторяют глобальные, но без `refresh`, потому что период обновления задаётся на уровне всей подписки.
|
||||
|
||||
## Рекомендации по значениям
|
||||
|
||||
- Для `#update:` использовать Unix time в секундах.
|
||||
- Для `#refresh:` использовать короткие интервалы вида `5s`, `10m`, `6h`, `1d`.
|
||||
- Для `#color:` использовать один стабильный формат в рамках клиента, например `#RRGGBB`.
|
||||
- Для `#icon:` использовать строковый идентификатор или emoji.
|
||||
- Для `#used:` и `#available:` использовать человекочитаемые единицы `kb`, `mb`, `gb`, `tb`.
|
||||
|
||||
---
|
||||
|
||||
## Полный пример
|
||||
|
||||
```text
|
||||
#name: Zarazaex Free RU
|
||||
#update: 1778011200
|
||||
#refresh: 10m
|
||||
#color: #4A90E2
|
||||
#icon: 🇷🇺
|
||||
#used: 10mb/10gb
|
||||
#available: 9.99gb
|
||||
|
||||
olcrtc://wbstream?seichannel@room-01#d823fa01cb3e0609b67322f7cf984c4ee2e4ce2e294936fc24ef38c9e59f4799%android-01$RU / olcng free sub / IPv6
|
||||
##name: RU-1
|
||||
##icon: 🇷🇺
|
||||
##color: #4A90E2
|
||||
##used: 500mb/10gb
|
||||
##available: 9.5gb
|
||||
##ip: 203.0.113.10
|
||||
##comment: basic free node
|
||||
|
||||
olcrtc://jazz?datachannel@abc123xyz#aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa%android-01$DE / backup / IPv4
|
||||
##name: DE-Backup
|
||||
##icon: 🇩🇪
|
||||
##color: #2EBD85
|
||||
##comment: reserve route
|
||||
```
|
||||
|
||||
## Имплементация клиента для подписок
|
||||
на данный момент - не существует единой реализации, но в скором времени они точно появятся даже в официальном репозитории
|
||||
Reference in New Issue
Block a user