remram44 / matrix-appservice-gitter-twisted

Matrix-Gitter bridge using Twisted

Status: development stopped since I have no server to run Matrix on. Unfortunately in its current state, Synapse's disk and memory usage exceed what my machine can take.

Matrix-Gitter bridge using Twisted

This is a Python 2 application using Twisted that bridges the Matrix chat network with the Gitter system.

This is supposed to be deployed as a Matrix application service alongside a homeserver. It allows users to log in to their personal Gitter accounts and chat in Gitter rooms via their Matrix client.

Contrary to other bridges, this doesn't link a public Matrix room with a Gitter one. You won't be able to join a Gitter room without a Gitter account. On the other hand, Gitter users won't see the difference between a Matrix user and a normal Gitter user, since they will appear to be chatting natively.

User experience

Interaction happens through a bot. Just start chatting with @gitter:example.com, and it will give you a link to log in to your Gitter account. Then the bot will invite you to the Gitter rooms you are already in. Those are private rooms, that do NOT have an alias like #gitterHQ/gitter.

The user can join or leave Gitter rooms by sending commands to the bot.

Current status

This works but is still in development. While you are welcome to use it, expect bugs and do not rely on it in a production environment. Feedback is appreciated.

Deployment guide

• Install and setup a homeserver

• Sign up for a Gitter application on https://developer.gitter.im/apps; your URL should be your server hostname (gitter_login_url in settings) with path /callback, example https://example.com/callback.

• Write a registration file for this application service, based on this:

  id: gitter                      # An identifier, unique within your appservices
  hs_token: "changeme42changeme"  # Token you will set in the settings as matrix_homeserver_token
  as_token: "changeme42changeme"  # Token you will set in the settings as matrix_appservice_token
  namespaces:
    users:
      - exclusive: true
        regex: '@gitter.*'        # You can't change this currently
    aliases: []
    rooms: []
  url: 'https://127.0.0.1:8445'   # URL of your appservice; probably local. Port should match matrix_appservice_port
  sender_localpart: gitter        # Has to fall within user namespace regex, and match matrix_botname in settings

• Create settings.py and edit the configuration

  unique_secret_key = 'change this before running'    # A unique secret string for HMAC
  
  matrix_appservice_port = 8445                       # Should match url in registration
  matrix_homeserver_url = 'https://127.0.0.1:8448/'   # URL of your homeserver, usually local
  matrix_homeserver_domain = 'gitter.remram.fr'       # The domain your homeserver uses
  matrix_botname = '@gitter:gitter.remram.fr'         # Should be sender_localpart in registration + domain
  matrix_appservice_token = 'changeme42changeme'      # as_token from registration
  matrix_homeserver_token = 'changeme42changeme'      # hs_token from registration
  
  gitter_login_port = 80                              # Port the OAuth webapp is listening on. Should match
                                                      # gitter_login_url, unless you have a reverse proxy in the middle
  gitter_login_url = 'http://gitter.remram.fr/'       # URL sent to users to register. When registering your
                                                      # Gitter app, use this + /callback as redirect URL
  gitter_oauth_key = 'get this from Gitter'           # Key for your registered Gitter app
  gitter_oauth_secret = 'get this from Gitter'        # Secret for your registered Gitter app

• Run this software; it will create a file database.sqlite in the current folder, so make sure it has permission to do that.

Internals

The database is created on the first runs. It contains the following tables:

• users: contains informations about a user on either service. It might be a Matrix user that did not authenticate with Gitter yet, or an active bridge user. The table contains usernames, Gitter OAuth tokens, and the ID of the private chat room of the bot with the Matrix user.
• rooms: contains information about bridged rooms. Linked to a Matrix user. Maps a Matrix room ID with a Gitter room name and ID.

The bot responds to invite requests. When it joins, if more than one persom is in the chat, it will print a message and leave (and remember not to accept invites for that room in the future). Else, it will set this room as the private chat with that user in the database, leaving the previous one if it was set, and display instructions (with link to auth page).

The auth page is an HTML page allowing a user to auth her Gitter account using OAuth2.

Recognized bot commands:

• list: displays the list of Gitter room the user is in, with an asterix for rooms he has joined on Matrix.
• gjoin <gitter-room>: join a new room on Gitter
• gpart <gitter-room>: leave a room on Gitter. Kick you out of the Matrix room if you were on it
• invite <gitter-room>: if you are not on a Matrix room for that Gitter room, create one, populate it with virtual users and invite you to it
• logout: throw away your Gitter credentials. Kick you out of all rooms you are in

matrix-appservice-gitter-twisted's Issues

Set the gitter room avatar on the matrix side

Since both Gitter and Matrix support room avatars it would be nice to set gitter room avatar on the matrix side. This would help to distinguish the rooms.

Closing the Gitter stream when the room is destroyed

I don't know how to close a Twisted web response.

See matrix.py:132:

        if self.stream_response is not None:
            pass  # FIXME: how to close the connection?

Rewrite with async/await

Lots of callbacks in there. It would look a lot better with async/await.

Create virtual user for bot on first run

It seems that inviting the bot from a federated room doesn't work unless we register it properly with the homeserver beforehand.

This means:

• The bot (usually @gitter) has to fall within the reserved user namespace in the registration file
• The virtual user needs to be created via an API call

The appservice could really create that user itself on the first run. That will probably avoid a lot of headaches down the road.

$ curl -X POST -H 'accept: application/json' \
    -d '{"type": "m.login.application.service", "username": "gitter"}' \
    https://myhomeserver:8448/_matrix/client/r0/register?access_token=xxxxxxxx

Don't bridge Gitter rooms the user is not in

Currently you can bridge a room you are not in on Gitter.

Import history when creating bridged room

Right now the room is created empty, although Gitter supports retrieving old messages and Matrix supports injecting them.

Importing the full history is not a good idea, but a limited number of recent messages would be useful.

Fix user join/leave on Matrix

Currently, no list of users is obtained from Gitter: a user shows up in the Matrix room when he first speaks, and is never removed.

• Shouldn't invite/join users everytime they speak
• The full list of users should be obtained when the room is created, and virtual users created then
• We should react to the user join/leave events and add/remove virtual users then

Sending a message yourself from Gitter doesn't make it appear in Matrix

If you are using this bridge but send a message directly from the Gitter website, this message won't appear in your Matrix room at all. This could be fixed by keeping track of the message the bot sends, and forwarding the message from your Gitter user that it didn't send.

That would mean that a gitter_yourname Matrix user would appear, which would be awkward once #1 is fixed.

Images from Gitter to Matrix

Markdown issue, follows on #7

Gitter allows the ![alt](http://image.png) syntax to insert images in messages. Even though I correctly render to <img> in HTML, Riot strips it, only rendering attachments and previews.

I don't know how to fix this. There is just no way to get Riot to render embedded images.

Markdown roundtrip

Markdown posted on Matrix gets posted on Gitter fine, but markdown in Gitter shows up as text in Matrix. I must have missed something in the message format.

Add support to hipchat

Hello,

Firstly, thanks for your work.

Please could you add support to connect to hipchat?

Thanks again.

Ordering messages is not enforced on Matrix

When forwarding from Gitter to Matrix, it is possible for the homeserver not to handle requests in order, which can mean the messages are posted out of order. Particularly possible since we do multiple API requests to post (invite, join, post).