Skip to content

Commit

Permalink
doc/user: add relay "api" (issue #2066)
Browse files Browse the repository at this point in the history
  • Loading branch information
@flashcode
flashcode committed May 19, 2024
1 parent 44ca4b4 commit 54f2c7f
Show file tree
Hide file tree
Showing 7 changed files with 402 additions and 66 deletions.
73 changes: 62 additions & 11 deletions doc/de/weechat_user.de.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,8 @@ wesentliche Merkmale:
https://datatracker.ietf.org/doc/html/rfc2812[2812 ^↗^^],
https://datatracker.ietf.org/doc/html/rfc2813[2813 ^↗^^] und
https://datatracker.ietf.org/doc/html/rfc7194[7194 ^↗^^]
* IRC proxy und relay für remote Schnittstellen
// TRANSLATION MISSING
* IRC proxy and relay for WeeChat and remote interfaces
* Betriebssystemunabhängig (GNU/Linux, *BSD, macOS, Windows und weitere)
* 100% GPL, freie Software

Expand Down Expand Up @@ -132,8 +133,10 @@ Die folgende Tabelle zeigt eine Auflistung der Pakete, die zum Erstellen von Wee
Relay-Erweiterung: Untersützung von TLS Verbindungen.

| zlib1g-dev |
// TRANSLATION MISSING
| Logger-Erweitertung: Kompression von rotierenden Protokolldateien (gzip). +
Relay-Erweiterung: Kompression von Nachrichten (WeeChat -> client) with https://zlib.net/[zlib ^↗^^] (weechat protocol). +
Relay-Erweiterung: Kompression von Nachrichten (WeeChat -> client) with https://zlib.net/[zlib ^↗^^]
(api and weechat protocols). +
Script-Erweiterung: Lesen der Repository-Indexdatei (gzip).
|===

Expand Down Expand Up @@ -163,8 +166,10 @@ WeeChat optional sind:
| Relay-Erweiterung: Protokoll "api" (HTTP REST API).

| libzstd-dev | ≥ 0.8.1
// TRANLSATION MISSING
| Logger-Erweiterung: Kompression von rotierenden Protokolldateien (zstandard). +
Relay-Erweiterung: Kompression von Nachrichten (WeeChat -> client) with https://facebook.github.io/zstd/[Zstandard ^↗^^] (weechat protocol).
Relay-Erweiterung: Kompression von Nachrichten (WeeChat -> client) with https://facebook.github.io/zstd/[Zstandard ^↗^^]
(api and weechat protocols).

| libaspell-dev / libenchant-dev |
| Spell Erweiterung.
Expand Down Expand Up @@ -4606,8 +4611,16 @@ Die Relay-Erweiterung wird genutzt um Daten, mittels unterschiedlicher Protokoll

* _irc_: IRC Proxy: um mittels einem oder mehreren IRC-Clients eine Verbindung zu
IRC Servern zu unterhalten.
* _weechat_: Protokoll, das von Remote-Schnittstellen zur Anzeige und Interaktion verwendet wird
WeeChat, siehe https://weechat.org/about/interfaces/[this page ^↗^^].
// TRANSLATION MISSING
* _api_: HTTP REST API, used by WeeChat and remote interfaces to display and
interact with WeeChat
// TRANSLATION MISSING
* _weechat_: protocol used by remote interfaces to display and interact with
WeeChat.

// TRANSLATION MISSING
For _api_ and _weechat_ protocols, see the list of remote interfaces on
https://weechat.org/about/interfaces/[this page ^↗^^].

[[relay_password]]
=== Passwort
Expand All @@ -4619,14 +4632,15 @@ Es wird dringend empfohlen, mit diesen Befehlen ein Passwort für das Relay fest
/set relay.network.password "${sec.data.relay}"
----

Dieses Passwort wird sowohl für das _irc_ als auch für das _weechat_ Protokoll
verwendet.
// TRANSLATION MISSING
This password is used with all protocols.

[[relay_totp]]
=== TOTP

TOTP (Time-based One-Time Passwort) ist eine Zwei-Faktor-Authentifizierung
für das _weechat_ Protokoll, als Ergänzung zum eigentlichen Passwort.
// TRANSLATION MISSING
TOTP (Time-based One-Time Password) can be used as secondary authentication
factor for _api_ and _weechat_ protocols, in addition to the password.

Diese Funktion is optional und erhöht den Sicherheitsgrad.

Expand Down Expand Up @@ -4723,6 +4737,40 @@ folgenden Befehlen einrichten:
/set irc.server.relay.password "${sec.data.relay_libera}"
----

// TRANSLATION MISSING
[[relay_api_protocol]]
=== API protocol

The Relay plugin can send data to a remote WeeChat or interface using an
HTTP REST API protocol.

You can browse and test the API online:
https://weechat.org/api/[WeeChat Relay API ^↗^^].

You can connect with WeeChat or a remote interface, see
https://weechat.org/about/interfaces/[this page ^↗^^].

For example:

----
/relay add api 9000
----

Now you can connect on port 9000 with a WeeChat or a remote interface using
password "mypassword".

To connect to an _api_ relay with WeeChat:

----
/remote add weechat http://localhost:9000 -password=mypassword
/remote connect weechat
----

[NOTE]
The remote WeeChat must expose the same API version as the local WeeChat, so
it's highly recommended to use exactly the same WeeChat version on remote
and local client.

[[relay_weechat_protocol]]
=== WeeChat Protokoll

Expand Down Expand Up @@ -4763,7 +4811,10 @@ websocket = new WebSocket("ws://server.com:9000/weechat");
----

Der Port (im Beispiel: 9000) ist der Port der in der Relay Erweiterung angegeben wurde.
Die URI muss immer auf "/weechat" enden (_irc_ und _weechat_ Protokoll).

// TRANSLATION MISSING
The URI must end with "/weechat" for _irc_ and _weechat_ protocols and "/api"
for _api_ protocol.

[[relay_unix_socket]]
=== UNIX Domain Sockets
Expand Down Expand Up @@ -4808,7 +4859,7 @@ Sektionen in Datei _relay.conf_:
| network | /set relay.network.* | Netzwerkoptionen.
| irc | /set relay.irc.* | für das IRC Protokoll spezifische Optionen (IRC Proxy).
| port | <<command_relay_relay,/relay add>> +
/set relay.port.* | Ports zur Nutzung der Relay-Erweiterung (IRC und weechat Protokolle) (Optionen können in Sektion hinzugefügt/entfernt werden).
/set relay.port.* | Ports zur Nutzung der Relay-Erweiterung (Optionen können in Sektion hinzugefügt/entfernt werden).
|===

Optionen:
Expand Down
58 changes: 50 additions & 8 deletions doc/en/weechat_user.en.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ Main features are:
https://datatracker.ietf.org/doc/html/rfc2812[2812 ^↗^^],
https://datatracker.ietf.org/doc/html/rfc2813[2813 ^↗^^] and
https://datatracker.ietf.org/doc/html/rfc7194[7194 ^↗^^]
* IRC proxy and relay for remote interfaces
* IRC proxy and relay for WeeChat and remote interfaces
* multi-platform (GNU/Linux, *BSD, macOS, Windows and other)
* 100% GPL, free software

Expand Down Expand Up @@ -128,7 +128,8 @@ WeeChat:

| zlib1g-dev |
| Logger plugin: compression of rotated log files (gzip). +
Relay plugin: compression of messages (WeeChat -> client) with https://zlib.net/[zlib ^↗^^] (weechat protocol). +
Relay plugin: compression of messages with https://zlib.net/[zlib ^↗^^]
(api and weechat protocols). +
Script plugin: read of repository index file (gzip).
|===

Expand Down Expand Up @@ -159,7 +160,8 @@ WeeChat:

| libzstd-dev | ≥ 0.8.1
| Logger plugin: compression of rotated log files (zstandard). +
Relay plugin: compression of messages (WeeChat -> client) with https://facebook.github.io/zstd/[Zstandard ^↗^^] (weechat protocol).
Relay plugin: compression of messages with https://facebook.github.io/zstd/[Zstandard ^↗^^]
(api and weechat protocols).

| libaspell-dev / libenchant-dev |
| Spell plugin.
Expand Down Expand Up @@ -4527,8 +4529,13 @@ The Relay plugin is used to relay data via network, using different protocols:

* _irc_: IRC proxy: used to share connections to IRC servers with one or many
other IRC clients
* _api_: HTTP REST API, used by WeeChat and remote interfaces to display and
interact with WeeChat
* _weechat_: protocol used by remote interfaces to display and interact with
WeeChat, see https://weechat.org/about/interfaces/[this page ^↗^^].
WeeChat.

For _api_ and _weechat_ protocols, see the list of remote interfaces on
https://weechat.org/about/interfaces/[this page ^↗^^].

[[relay_password]]
=== Password
Expand All @@ -4540,13 +4547,13 @@ It is highly recommended to set a password for relay, with these commands:
/set relay.network.password "${sec.data.relay}"
----

This password is used for _irc_ and _weechat_ protocols.
This password is used with all protocols.

[[relay_totp]]
=== TOTP

TOTP (Time-based One-Time Password) can be used as secondary authentication
factor for _weechat_ protocol, in addition to the password.
factor for _api_ and _weechat_ protocols, in addition to the password.

This is optional and increases the security level.

Expand Down Expand Up @@ -4638,6 +4645,39 @@ commands:
/set irc.server.relay.password "${sec.data.relay_libera}"
----

[[relay_api_protocol]]
=== API protocol

The Relay plugin can send data to a remote WeeChat or interface using an
HTTP REST API protocol.

You can browse and test the API online:
https://weechat.org/api/[WeeChat Relay API ^↗^^].

You can connect with WeeChat or a remote interface, see
https://weechat.org/about/interfaces/[this page ^↗^^].

For example:

----
/relay add api 9000
----

Now you can connect on port 9000 with a WeeChat or a remote interface using
password "mypassword".

To connect to an _api_ relay with WeeChat:

----
/remote add weechat http://localhost:9000 -password=mypassword
/remote connect weechat
----

[NOTE]
The remote WeeChat must expose the same API version as the local WeeChat, so
it's highly recommended to use exactly the same WeeChat version on remote
and local client.

[[relay_weechat_protocol]]
=== WeeChat protocol

Expand Down Expand Up @@ -4677,7 +4717,9 @@ websocket = new WebSocket("ws://server.com:9000/weechat");
----

The port (9000 in example) is the port defined in Relay plugin.
The URI must always end with "/weechat" (for _irc_ and _weechat_ protocols).

The URI must end with "/weechat" for _irc_ and _weechat_ protocols and "/api"
for _api_ protocol.

[[relay_unix_socket]]
=== UNIX domain sockets
Expand Down Expand Up @@ -4720,7 +4762,7 @@ Sections in file _relay.conf_:
| network | /set relay.network.* | Network options.
| irc | /set relay.irc.* | Options specific to irc protocol (irc proxy).
| port | <<command_relay_relay,/relay add>> +
/set relay.port.* | Ports used for relay (irc and weechat protocols) (options can be added/removed in section).
/set relay.port.* | Ports used for relay (options can be added/removed in section).
|===

Options:
Expand Down
61 changes: 51 additions & 10 deletions doc/fr/weechat_user.fr.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ Ses principales fonctionnalités sont les suivantes :
https://datatracker.ietf.org/doc/html/rfc2812[2812 ^↗^^],
https://datatracker.ietf.org/doc/html/rfc2813[2813 ^↗^^] et
https://datatracker.ietf.org/doc/html/rfc7194[7194 ^↗^^]
* proxy IRC et relai pour interfaces distantes
* proxy IRC et relai pour WeeChat et interfaces distantes
* multi plates-formes (GNU/Linux, *BSD, macOS, Windows et d'autres systèmes)
* 100% GPL, logiciel libre

Expand Down Expand Up @@ -128,7 +128,8 @@ Le tableau suivant liste les paquets *requis* pour construire WeeChat :

| zlib1g-dev |
| Extension Logger : compression des fichiers de log qui tournent (gzip). +
Extention Relay : compression des messages (WeeChat -> client) avec https://zlib.net/[zlib ^↗^^] (protocole weechat). +
Extention Relay : compression des messages (WeeChat -> client) avec https://zlib.net/[zlib ^↗^^]
(protocoles api et weechat). +
Extension Script : lecture du fichier d'index du dépôt (gzip).
|===

Expand Down Expand Up @@ -158,7 +159,8 @@ Le tableau suivant liste les paquets optionnels pour compiler WeeChat :

| libzstd-dev | ≥ 0.8.1
| Extension Logger : compression des fichiers de log qui tournent (zstandard). +
Extension Relay : compression des messages (WeeChat -> client) avec https://facebook.github.io/zstd/[Zstandard ^↗^^] (protocole weechat).
Extension Relay : compression des messages (WeeChat -> client) avec https://facebook.github.io/zstd/[Zstandard ^↗^^]
(protocoles api et weechat).

| libaspell-dev / libenchant-dev |
| Extension spell.
Expand Down Expand Up @@ -4658,8 +4660,13 @@ utilisant divers protocoles :

* _irc_ : proxy IRC : utilisé pour partager la connexions aux serveurs IRC avec
un ou plusieurs autres clients IRC
* _api_ : API REST HTTP, utilisée par WeeChat et les interfaces distantes pour
afficher et interagir avec WeeChat
* _weechat_ : protocole utilisé par les interfaces distantes pour afficher et
interagir avec WeeChat, voir https://weechat.org/about/interfaces/[cette page ^↗^^].
interagir avec WeeChat.

Pour les protocoles _api_ et _weechat_, voir la liste des interfaces distantes
sur https://weechat.org/about/interfaces/[cette page ^↗^^].

[[relay_password]]
=== Mot de passe
Expand All @@ -4672,14 +4679,14 @@ commandes :
/set relay.network.password "${sec.data.relay}"
----

Ce mot de passe sera utilisé pour les protocoles _irc_ et _weechat_.
Ce mot de passe est utilisé avec tous les protocoles.

[[relay_totp]]
=== TOTP

TOTP (« Time-based One-Time Password » : mot de passe à usage unique basé sur le
temps) peut être utilisé comme second facteur d'authentification pour le protocole
_weechat_, en plus du mot de passe.
temps) peut être utilisé comme second facteur d'authentification pour les
protocoles _api_ et _weechat_, en plus du mot de passe.

Il est optionnel et augmente le niveau de sécurité.

Expand Down Expand Up @@ -4776,6 +4783,39 @@ avec ces commandes :
/set irc.server.relay.password "${sec.data.relay_libera}"
----

[[relay_api_protocol]]
=== API protocol

L'extension Relay peut envoyer les données à un autre WeeChat ou une interface
distante avec un protocol HTTP de type API REST.

Vous pouvez parcourir et tester l'API en ligne :
https://weechat.org/api/[API Relay WeeChat ^↗^^].

Vous pouvez vous connecter avec WeeChat ou une interface distante, voir
https://weechat.org/about/interfaces/[cette page ^↗^^].

Par exemple :

----
/relay add api 9000
----

Maintenant vous pouvez vous connecter sur le port 9000 avec une interface
distante en utilisant le mot de passe "motdepasse".

Pour vous connecter à un relai _api_ avec WeeChat :

----
/remote add weechat http://localhost:9000 -password=motdepasse
/remote connect weechat
----

[NOTE]
Le WeeChat distant doit exposer exactement la même version d'API que le WeeChat
local, il est donc fortement recommandé d'utiliser exactement la même version
de WeeChat de chaque côté.

[[relay_weechat_protocol]]
=== Protocole WeeChat

Expand Down Expand Up @@ -4819,8 +4859,9 @@ websocket = new WebSocket("ws://server.com:9000/weechat");
----

Le port (9000 dans l'exemple) est le port défini dans l'extension Relay.
L'URI doit toujours se terminer par "/weechat" (pour les protocoles _irc_ et
_weechat_).

L'URI doit se terminer par "/weechat" pour les protocoles _irc_ et _weechat_ et
"/api" pour le protocole _api_.

[[relay_unix_socket]]
=== UNIX domain sockets
Expand Down Expand Up @@ -4865,7 +4906,7 @@ Sections dans le fichier _relay.conf_ :
| network | /set relay.network.* | Options réseau.
| irc | /set relay.irc.* | Options spécifiques au protocole irc (proxy irc).
| port | <<command_relay_relay,/relay add>> +
/set relay.port.* | Ports utilisés pour le relai (protocoles irc et weechat) (les options peuvent être ajoutées/supprimées dans la section).
/set relay.port.* | Ports utilisés pour le relai (les options peuvent être ajoutées/supprimées dans la section).
|===

Options :
Expand Down

0 comments on commit 54f2c7f

Please sign in to comment.