[WIP] Enhanced matrix bridge.

Author: ro-i

zulip/integrations/bridge_with_matrix/README.md

@@ -1,20 +1,19 @@
 # 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`.
+In case you'd like encryption to work, you need pip to install the `matrix-nio`
+package with e2e support: `matrix-nio[e2e]`. Caution: you have to install the
+development files of the `libolm` C-library first! Please refer to [the
+corresponding documentation of matrix-nio](https://github.com/poljar/matrix-nio#installation).
 
-Hence, this can also be used as a IRC <--> Zulip bridge.
 
 ## Steps to configure the Matrix bridge
 
@@ -27,20 +26,37 @@ 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`.
+1. Create a user on the matrix server of your choice, e.g. [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.
+   and password. Please use the Matrix user ID ([MXID](https://matrix.org/faq/#what-is-a-mxid%3F))
+   as format for the username!
 3. Also enter the `host` and `room_id` into the same section.
 
+### 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
 
 After the steps above have been completed, assuming you have the configuration
@@ -50,9 +66,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
+
+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`.
+
+Hence, this can also be used as a IRC <--> Zulip bridge.
+
+### 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,13 @@
+[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
+