[WIP] Enhanced matrix bridge.

Author: ro-i

zulip/integrations/bridge_with_matrix/README.md

@@ -1,20 +1,29 @@
 # Matrix <--> Zulip bridge
 
-This acts as a bridge between Matrix and Zulip. It also enables a
-Zulip topic to be federated between two Zulip servers.
+This acts as a bridge between Matrix and Zulip.
 
-## Usage
+### Enhanced Features
+- Supporting multiple (Zulip topic, Matrix channel)-pairs.
+- Handling files according to their mimetype.
 
-### For IRC bridges
 
-Matrix has been bridged to the listed
-[IRC networks](https://github.com/matrix-org/matrix-appservice-irc/wiki/Bridged-IRC-networks),
-where the 'Room alias format' refers to the `room_id` for the corresponding IRC channel.
+## Installation
 
-For example, for the freenode channel `#zulip-test`, the `room_id` would be
-`#freenode_#zulip-test:matrix.org`.
+Run `pip install -r requirements.txt` in order to install the requirements.
+
+Please note that the `libmagic`-library is required to be installed on your
+system, which is usually the case on Linux systems. On Windows, you need to
+additionally run `pip install -r requirements_windows.txt` in order to add
+`python-magic-bin` which ships the necessary DLLs.
+
+In case you'd like encryption to work, you need pip to install the `matrix-nio`
+package with e2e support:
+- First, you need to make sure that the development files of the `libolm`
+  C-library are installed on your system! See [the corresponding documentation
+  of matrix-nio](https://github.com/poljar/matrix-nio#installation) for further
+  information on this point.
+- `pip install matrix-nio[e2e]`
 
-Hence, this can also be used as a IRC <--> Zulip bridge.
 
 ## Steps to configure the Matrix bridge
 
@@ -27,19 +36,43 @@ details mentioned below. For example:
 * If you are running from the Zulip GitHub repo: `python matrix_bridge.py --write-sample-config matrix_bridge.conf`
 
 ### 1. Zulip endpoint
-1. Create a generic Zulip bot, with a full name like `IRC Bot` or `Matrix Bot`.
-2. Subscribe the bot user to the stream you'd like to bridge your IRC or Matrix
-   channel into.
+1. Create a generic Zulip bot, with a full name such as `Matrix Bot`.
+2. The bot is able to subscribe to the necessary streams itself if they are
+   public. (It may even create them if they do not exist and if the bot user
+   has enough rights to create streams.)
+   Otherwise, you need to add the bot manually.
 3. In the `zulip` section of the configuration file, enter the bot's `zuliprc`
    details (`email`, `api_key`, and `site`).
 4. In the same section, also enter the Zulip `stream` and `topic`.
 
 ### 2. Matrix endpoint
-1. Create a user on [matrix.org](https://matrix.org/), preferably with
-   a formal name like to `zulip-bot`.
-2. In the `matrix` section of the configuration file, enter the user's username
-   and password.
-3. Also enter the `host` and `room_id` into the same section.
+1. Create a user on the matrix server of your choice, e.g. [matrix.org](https://matrix.org/),
+   preferably with a descriptive name such as `zulip-bot`.
+2. In the `matrix` section of the configuration file, enter the user's Matrix
+   user ID `mxid` and password. Please use the Matrix user ID ([MXID](https://matrix.org/faq/#what-is-a-mxid%3F))
+   as format for the username!
+3. Create the Matrix room(s) to be bridged in case they do not exits yet.
+   Remember to invite the bot to private rooms! Otherwise, this error will be
+   thrown: `Matrix bridge error: JoinError: M_UNKNOWN No known servers`.
+4. Enter the `host` and `room_id` into the same section.
+   In case the room is private you need to use the `Internal room ID` which has
+   the format `!aBcDeFgHiJkLmNoPqR:example.org`.
+   In the official Matrix client [Element](https://github.com/vector-im), you
+   can find this `Internal room ID` in the `Room Settings` under `Advanced`.
+
+### Adding more (Zulip topic, Matrix channel)-pairs
+1. Create a new section with a name starting with `additional_bridge`.
+2. Add a `room_id` for the Matrix side and a `stream` and a `topic` for the
+   Zulip side.
+
+Example:
+```
+[additional_bridge1]
+room_id = #zulip:matrix.org
+stream = matrix test
+topic = matrix test topic
+```
+
 
 ## Running the bridge
 
@@ -50,9 +83,29 @@ in a file called `matrix_bridge.conf`:
 
 * If you are running from the Zulip GitHub repo: run `python matrix_bridge.py -c matrix_bridge.conf`
 
-## Caveats for IRC mirroring
+
+## Notes regarding IRC
+
+### Usage for IRC bridges
+
+This can also be used to indirectly bridge between IRC and Zulip.
+
+Matrix has been bridged to the listed
+[IRC networks](https://github.com/matrix-org/matrix-appservice-irc/wiki/Bridged-IRC-networks),
+where the 'Room alias format' refers to the `room_id` for the corresponding IRC channel.
+
+For example, for the freenode channel `#zulip-test`, the `room_id` would be
+`#freenode_#zulip-test:matrix.org`.
+
+### Caveats for IRC mirroring
 
 There are certain
 [IRC channels](https://github.com/matrix-org/matrix-appservice-irc/wiki/Channels-from-which-the-IRC-bridge-is-banned)
 where the Matrix.org IRC bridge has been banned for technical reasons.
 You can't mirror those IRC channels using this integration.
+
+
+## TODO
+
+- Adding support for editing and deleting messages?
+- Handling encryption on the Matrix side (may need further discussion).

zulip/integrations/bridge_with_matrix/matrix_bridge.conf

@@ -0,0 +1,18 @@
+[matrix]
+host = https://matrix.org
+mxid = @username:matrix.org
+password = password
+room_id = #zulip:matrix.org
+
+[zulip]
+email = [email protected]
+api_key = aPiKeY
+site = https://chat.zulip.org
+stream = test here
+topic = matrix
+
+[additional_bridge1]
+room_id = #example:matrix.org
+stream = new test
+topic = matrix
+