mirror of
https://github.com/telemt/telemt.git
synced 2026-11-22 15:26:37 +03:00
Links for WEB in Docs
This commit is contained in:
@@ -32,10 +32,12 @@ Leiten Sie den vollständigen konfigurierten WEB-Bereich an Telemt weiter. Beim
|
||||
| --- | --- | --- |
|
||||
| `GET` | `BASE?bridge=<capability>` | Erstes Bridge-Dokument oder, mit Recovery-`Accept`-Header und optionalem Bearer, die Recovery-Repräsentation. |
|
||||
| `POST`, `DELETE` | `BASEapi/v1/session` | Parent-Sitzung erstellen oder schließen. |
|
||||
| `POST` | `BASEapi/v1/up` | Uplink des HTTPS-Carriers. |
|
||||
| `POST` | `BASEapi/v1/down` | Downlink des HTTPS-Carriers. |
|
||||
| `POST`, `PUT` | `BASEapi/v1/up` | Uplink des HTTPS-Carriers. |
|
||||
| `POST`, `PUT` | `BASEapi/v1/down` | Downlink des HTTPS-Carriers. |
|
||||
| `GET` | `BASEapi/v1/ws` | WebSocket-Upgrade. |
|
||||
|
||||
`web.carrier_method` wählt `post` (Standard) oder `put` für neue Bridge-Seiten; der Server akzeptiert beide Methoden auf `/up` und `/down`. Bestehende Seiten behalten ihre Methode bei der Wiederherstellung. `web.conveyor = true` (Standard) erlaubt für neue HTTPS-Sitzungen ein ausdrücklich ausgehandeltes Sendefenster von 1 bis 4; deaktiviert bleibt der Upload sequenziell. Bestehende Sitzungen behalten ihr Fenster. Methoden für Sitzungserstellung, Löschung und WebSocket Upgrade bleiben unverändert. Siehe [Methoden- und Pipelining-Vertrag](../Config_params/CONFIG_PARAMS.de.md#webcarrier_method).
|
||||
|
||||
`POST BASEapi/v1/diagnostic` ist eine interne Sideband-Route der generierten Bridge und keine öffentliche Client-API. Das Routing ist groß-/kleinschreibungssensitiv und bytegenau: Es gibt keine Aliase, Varianten mit zusätzlichen oder percent-encoded Schrägstrichen und keine Query-Parameter an Carrier-Endpunkten. Ein falsch geformter Request mit einer vom aktuellen Prozess authentifizierten Capability oder einem solchen Bearer erhält lokal ein nicht cachebares `404`; ein nicht passender Request ohne authentisches Carrier-Material folgt dem konfigurierten Decoy. `base_path` ändert nur diese Routen des WEB-Listeners. Control API, `/web-status` und Prometheus-Metriken erhalten kein Präfix.
|
||||
|
||||
## Unterstützter Client-Vertrag
|
||||
@@ -57,7 +59,7 @@ tg://webproxy?server=proxy.example.com&secret=dd0123456789abcdef0123456789abcdef
|
||||
tg://webproxy?server=proxy.example.com%2Ftelegram%2Fweb&secret=cAABAgMEBQYHCAkKCwwNDg8
|
||||
```
|
||||
|
||||
Telemt gibt beim Prozessstart Links für die durch `[general.links].show` ausgewählten WEB-Profile über das vorhandene Log-Target `telemt::links` aus. Root-Links behalten das bisherige hexadezimale Secret. Bei einem Pfad-Link ist `HOST/BASE` im Parameter `server` percent-encoded; das Secret ist ungepolstertes base64url von `0x70 || client_secret`, wobei `client_secret` im Modus `plain` das rohe 16-Byte-Secret und im Modus `dd` den Wert `0xdd || secret` bezeichnet. Die Users-API liefert nur das rohe Secret und keinen WEB-Link. `[general.links].public_host` und `public_port` wirken nur auf native Links und überschreiben keine WEB-vhost-Links.
|
||||
Telemt gibt beim Prozessstart Links für die durch `[general.links].show` ausgewählten WEB-Profile über das vorhandene Log-Target `telemt::links` aus. Root-Links behalten das bisherige hexadezimale Secret. Bei einem Pfad-Link ist `HOST/BASE` im Parameter `server` percent-encoded; das Secret ist ungepolstertes base64url von `0x70 || client_secret`, wobei `client_secret` im Modus `plain` das rohe 16-Byte-Secret und im Modus `dd` den Wert `0xdd || secret` bezeichnet. `GET /v1/users/{username}/links?transport=web` liefert WEB-Links mit Zugangsdaten über denselben Formatter, unabhängig vom `show`-Filter für die Startausgabe. `[general.links].public_host` und `public_port` wirken nur auf native Links und überschreiben keine WEB-vhost-Links.
|
||||
|
||||
## Voraussetzungen
|
||||
|
||||
@@ -655,7 +657,7 @@ curl -sS -X POST http://127.0.0.1:9091/v1/users/web-user/rotate-secret \
|
||||
-d '{}'
|
||||
```
|
||||
|
||||
Nach einer Secret-Rotation erstellt der Config-Watcher die WEB-Capabilities neu. Die Users-API liefert das Secret, aber keine `tg://webproxy`-URL. Erstellen Sie den Link mit dem konfigurierten Hostnamen und der `plain`- oder `dd`-Darstellung des Profils. Entfernen und aktivieren Sie vor dem Löschen eines Benutzers zuerst das WEB-Profil, das auf ihn verweist, damit die resultierende Konfiguration gültig bleibt.
|
||||
Nach einer Secret-Rotation erstellt der Config-Watcher die WEB-Capabilities neu. Rufen Sie `GET /v1/users/{username}/links?transport=web` ab und prüfen Sie vor der Ausgabe wirksamer Links, ob `usable=true` gilt. Solange das veröffentlichte Profil und die prozessweite Zulassung das neue Secret nicht akzeptieren, enthält die Antwort keine Links und meldet pending oder unavailable. `view=desired` zeigt eine Vorschau für exakte konfigurierte Hosts und Pfade mit `usable=false`; Wildcard-Muster werden nie als Links ausgegeben. Die [Beschreibung der WEB-Links](../Architecture/API/API.md#web-user-links) erläutert Grenzen des Snapshots und Fehler. Entfernen und aktivieren Sie vor dem Löschen eines Benutzers zuerst das WEB-Profil, das auf ihn verweist, damit die resultierende Konfiguration gültig bleibt.
|
||||
|
||||
Der vollständige Vertrag für Requests, Revisionen, Fehler und alle Benutzer-Endpunkte steht in der [Dokumentation der Control API](../Architecture/API/API.md).
|
||||
|
||||
|
||||
@@ -32,10 +32,12 @@ Let `BASE` mean `/` for an empty `base_path`, or `/<base_path>/` otherwise. The
|
||||
| --- | --- | --- |
|
||||
| `GET` | `BASE?bridge=<capability>` | Initial bridge document, or the recovery representation when the recovery `Accept` header and optional bearer are present. |
|
||||
| `POST`, `DELETE` | `BASEapi/v1/session` | Create or close the parent session. |
|
||||
| `POST` | `BASEapi/v1/up` | HTTPS carrier uplink. |
|
||||
| `POST` | `BASEapi/v1/down` | HTTPS carrier downlink. |
|
||||
| `POST`, `PUT` | `BASEapi/v1/up` | HTTPS carrier uplink. |
|
||||
| `POST`, `PUT` | `BASEapi/v1/down` | HTTPS carrier downlink. |
|
||||
| `GET` | `BASEapi/v1/ws` | WebSocket Upgrade. |
|
||||
|
||||
`web.carrier_method` selects `post` (default) or `put` for new bridge pages; the server accepts both on `/up` and `/down`. Existing pages retain their method during recovery. `web.conveyor = true` (default) permits an explicitly negotiated uplink window of 1–4 for new HTTPS sessions; disabling it retains serialized uploads. Existing sessions keep their window. These settings do not alter session creation, deletion or WebSocket Upgrade methods. See the [method and conveyor contract](../Config_params/CONFIG_PARAMS.en.md#webcarrier_method).
|
||||
|
||||
`POST BASEapi/v1/diagnostic` is an internal generated-bridge sideband route, not a public client API. Route matching is case-sensitive and byte-exact: there are no aliases, extra-slash variants, percent-encoded slash variants, or query parameters on carrier endpoints. A wrong-shaped request containing a capability or bearer authenticated by the current process receives a local no-store `404`; an unmatched request without authentic carrier material follows the configured decoy. `base_path` changes only these WEB listener routes. It does not prefix the Control API, `/web-status`, or Prometheus metrics.
|
||||
|
||||
## Supported client contract
|
||||
@@ -57,7 +59,7 @@ tg://webproxy?server=proxy.example.com&secret=dd0123456789abcdef0123456789abcdef
|
||||
tg://webproxy?server=proxy.example.com%2Ftelegram%2Fweb&secret=cAABAgMEBQYHCAkKCwwNDg8
|
||||
```
|
||||
|
||||
Telemt prints links at process startup for WEB profiles selected by `[general.links].show` through the existing `telemt::links` log target. Root links keep the legacy hexadecimal secret. A path link percent-encodes `HOST/BASE` in `server` and uses unpadded base64url of `0x70 || client_secret`, where `client_secret` is the raw 16-byte secret in `plain` mode or `0xdd || secret` in `dd` mode. The users API returns only the raw secret, not a WEB link. `[general.links].public_host` and `public_port` affect native links only and do not override WEB vhost links.
|
||||
Telemt prints links at process startup for WEB profiles selected by `[general.links].show` through the existing `telemt::links` log target. Root links keep the legacy hexadecimal secret. A path link percent-encodes `HOST/BASE` in `server` and uses unpadded base64url of `0x70 || client_secret`, where `client_secret` is the raw 16-byte secret in `plain` mode or `0xdd || secret` in `dd` mode. `GET /v1/users/{username}/links?transport=web` returns credential-bearing WEB links using the same formatter, independently of the startup `show` filter. `[general.links].public_host` and `public_port` affect native links only and do not override WEB vhost links.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
@@ -641,7 +643,7 @@ curl -sS -X POST http://127.0.0.1:9091/v1/users/web-user/rotate-secret \
|
||||
-d '{}'
|
||||
```
|
||||
|
||||
The config watcher rebuilds WEB capabilities after a secret rotation. The users API returns the secret, not a `tg://webproxy` URL; construct the link with the configured hostname and the profile's `plain` or `dd` representation. Before deleting a user referenced by a WEB profile, remove and apply that profile first so the resulting configuration remains valid.
|
||||
The config watcher rebuilds WEB capabilities after a secret rotation. Read `GET /v1/users/{username}/links?transport=web` and check `usable=true` before provisioning its effective links. Until the published binding and process admission accept the new credential, the response withholds links as pending or unavailable. `view=desired` previews exact configured hosts and paths with `usable=false`; wildcard patterns are never emitted as links. See [WEB user links](../Architecture/API/API.md#web-user-links) for snapshot limits and errors. Before deleting a user referenced by a WEB profile, remove and apply that profile first so the resulting configuration remains valid.
|
||||
|
||||
See the complete [Control API contract](../Architecture/API/API.md) for request envelopes, revisions, failure modes, and all user endpoints.
|
||||
|
||||
|
||||
@@ -32,10 +32,12 @@ WEB-listener Telemt
|
||||
| --- | --- | --- |
|
||||
| `GET` | `BASE?bridge=<capability>` | Исходный bridge document или recovery representation при наличии recovery-заголовка `Accept` и необязательного bearer. |
|
||||
| `POST`, `DELETE` | `BASEapi/v1/session` | Создание или закрытие parent session. |
|
||||
| `POST` | `BASEapi/v1/up` | Uplink HTTPS carrier. |
|
||||
| `POST` | `BASEapi/v1/down` | Downlink HTTPS carrier. |
|
||||
| `POST`, `PUT` | `BASEapi/v1/up` | Uplink HTTPS carrier. |
|
||||
| `POST`, `PUT` | `BASEapi/v1/down` | Downlink HTTPS carrier. |
|
||||
| `GET` | `BASEapi/v1/ws` | WebSocket Upgrade. |
|
||||
|
||||
`web.carrier_method` выбирает `post` (по умолчанию) или `put` для новых страниц моста; сервер принимает оба метода на `/up` и `/down`. Существующие страницы сохраняют метод при восстановлении. `web.conveyor = true` (по умолчанию) разрешает явно согласуемое окно отправки от 1 до 4 для новых HTTPS-сессий; при отключении отправка последовательная. Действующие сессии сохраняют своё окно. Эти параметры не меняют методы создания и удаления сессии или WebSocket Upgrade. См. [контракт метода и конвейера](../Config_params/CONFIG_PARAMS.ru.md#webcarrier_method).
|
||||
|
||||
`POST BASEapi/v1/diagnostic` — внутренний sideband-маршрут сгенерированного bridge, а не публичный client API. Сопоставление путей регистрозависимо и побайтно точно: нет aliases, вариантов с лишним или percent-encoded слешем и query parameters у carrier endpoints. Запрос неправильной формы с capability или bearer, аутентифицированным текущим процессом, получает локальный не кэшируемый `404`; несовпавший запрос без подлинного carrier material следует в настроенный decoy. `base_path` меняет только эти маршруты WEB-listener. Он не добавляется к Control API, `/web-status` или Prometheus metrics.
|
||||
|
||||
## Поддерживаемый контракт клиента
|
||||
@@ -57,7 +59,7 @@ tg://webproxy?server=proxy.example.com&secret=dd0123456789abcdef0123456789abcdef
|
||||
tg://webproxy?server=proxy.example.com%2Ftelegram%2Fweb&secret=cAABAgMEBQYHCAkKCwwNDg8
|
||||
```
|
||||
|
||||
При запуске процесса Telemt печатает ссылки для WEB-профилей, выбранных в `[general.links].show`, через существующий log target `telemt::links`. Root-ссылки сохраняют прежний шестнадцатеричный secret. В path-ссылке `HOST/BASE` в параметре `server` percent-encoded, а secret равен base64url без padding от `0x70 || client_secret`, где `client_secret` — исходный 16-байтовый secret для режима `plain` либо `0xdd || secret` для режима `dd`. Users API возвращает только исходный секрет, а не WEB-ссылку. `[general.links].public_host` и `public_port` влияют только на нативные ссылки и не переопределяют ссылки WEB-vhost.
|
||||
При запуске процесса Telemt печатает ссылки для WEB-профилей, выбранных в `[general.links].show`, через существующий log target `telemt::links`. Root-ссылки сохраняют прежний шестнадцатеричный secret. В path-ссылке `HOST/BASE` в параметре `server` percent-encoded, а secret равен base64url без padding от `0x70 || client_secret`, где `client_secret` — исходный 16-байтовый secret для режима `plain` либо `0xdd || secret` для режима `dd`. `GET /v1/users/{username}/links?transport=web` возвращает WEB-ссылки с учётными данными через тот же форматтер, независимо от фильтра `show` для вывода при запуске. `[general.links].public_host` и `public_port` влияют только на нативные ссылки и не переопределяют ссылки WEB-vhost.
|
||||
|
||||
## Предварительные требования
|
||||
|
||||
@@ -648,7 +650,7 @@ curl -sS -X POST http://127.0.0.1:9091/v1/users/web-user/rotate-secret \
|
||||
-d '{}'
|
||||
```
|
||||
|
||||
После ротации секрета config watcher перестраивает WEB capabilities. Users API возвращает секрет, но не URL `tg://webproxy`; соберите ссылку из настроенного hostname и представления `plain` или `dd` соответствующего профиля. Перед удалением пользователя, на которого ссылается WEB-профиль, сначала удалите и примените этот профиль, чтобы итоговая конфигурация оставалась валидной.
|
||||
После ротации секрета config watcher перестраивает WEB capabilities. Запросите `GET /v1/users/{username}/links?transport=web` и проверьте `usable=true` перед выдачей действующих ссылок. Пока опубликованный профиль и механизм допуска процесса не принимают новый секрет, ответ не содержит ссылок и сообщает pending или unavailable. `view=desired` показывает предварительные ссылки для точных хостов и путей с `usable=false`; wildcard-шаблоны в ссылки не попадают. Ограничения снимка и ошибки описаны в [контракте WEB-ссылок](../Architecture/API/API.md#web-user-links). Перед удалением пользователя, на которого ссылается WEB-профиль, сначала удалите и примените этот профиль, чтобы итоговая конфигурация оставалась валидной.
|
||||
|
||||
Полный контракт запросов, revisions, ошибок и всех user endpoints приведён в [документации Control API](../Architecture/API/API.md).
|
||||
|
||||
|
||||
Reference in New Issue
Block a user