Merge branch 'feature-better-async' into 'main'

Invoke the bot callback in an async wrapper.

See merge request !1

readme.md

@@ -2,28 +2,43 @@
 
 *note:* This is currently a (functional) work in progress.
 
+Most development takes place on our gitlab server. We mirror to github because people have trouble finding
+working errbot matrix backends, and well... ours kinda works :). PRs/issues/comments welcome.
+
 ## Features
-* Get message from matrix (rooms, private messages)
-* Send messages to matrix (responses) - with markdown support
+* Single (1:1) rooms with the bot, which it considers private
+* Group/named rooms
+  * Room spesific full-names
+  * Room aliases (#thing:example.com) are recognised and resolve correctly
+* Sending of reactions to events
+* Listening for reactions ([see the our errbot-matrix plugin](https://git.fossgalaxy.com/irc/errbot/errbot-matrix/-/blob/main/matrix.py))
+* Notices, emotes, images - although the syntax requires a tidy up
+* Exposing of matrix state (power levels, presence)
+* Messages feature matrix spesific metadata in `extras` (event ids, times, etc...)
+* Token-based auth, just like most native matrix bots :)
+  * Name detection based on token
 
 ### Still todo
 Most (all) of these are in the library, just need mapping
 
-* General code tidy up
-* Some missing features for backend API (room methods, user methods)
-* Support for e2e encryption (the matrix library natively supports it)
-* Support for non-text message types (ie, images)
-* Support for reactions
+* Some missing features for backend API (invites, room methods)
+* Support for non-text message types (ie, images - limited support in place)
+* Support for redacting reactions (adding implemented, removing not implemented)
+* Support for message editing/redactions
 
 # Known issues
 
-## Strange setup
-The bot will exit if you use password authentication (after displaying the token and device id) - you then
-need to manually stick these in the config file. Would be better if the bot could cache this in some errbot-y
-way.
+* Plugins that use images are unlikey to work - this is due to how matrix deals with images.
+* !room join doesn't work, invite the bot to a room via matrix's invite process
+* Although implemented, matrix chat effects don't seem to work.
+* The bot defaults to 'text' rather than the more correct 'notice' for outgoing messages - it might not play nice with other bots.
+* Careful when accessing async code, it works as-is, but can be a bit temprimental if you call async methods from sync ones.
+
+# Setup Steps
 
-If the bot doesn't do this, the bot generates a new device on each connection, which quickly becomes madness
-on the server-side (100s of devices when developing). By fixing the device ID and token, this doesn't happen.
+The bot requires an exisitng account and access token. Once you have these setting up the bot is relatively
+simple. The backend isn't currently on pypy, so you need to put it somewhere the bot can find it. We store
+ours in a backends directory.
 
 The configuration file for errbot looks like this:
 
@@ -33,14 +48,16 @@ bot_extra_backend_dir = r'./backends/' # path to backends folder
 
 BOT_IDENTITY = {
     'homeserver': 'https://matrix.fgmx.uk',
-    'username': '@errbot:fossgalaxy.com',
-
-    # set these to get the token and device id
-    'password': '', # not used if token is set
-    'device': '', # not used if token is set
-
-    # once known...
-    #'device_id': '', # DEVICE ID HERE
-    #'token': '' # ACCESS TOKEN HERE
+    'token': 'MATRIX_ACCESS_TOKEN'
 }
 ```
+
+If you'd like to see a dockerised example, [fg-errbot's repo](https://git.fossgalaxy.com/irc/errbot/fg-errbot)
+is our production setup, and it's FOSS. You can also find our collection of [errbot plugins](https://git.fossgalaxy.com/irc/errbot)
+on our gitlab server.
+
+If you'd like to see the matrix-spesific features exposed by the backend, ([see the our errbot-matrix plugin](https://git.fossgalaxy.com/irc/errbot/errbot-matrix/-/blob/main/matrix.py)).
+
+## Thanks
+This repository was inspired by existing err backends on github, namely the discord, slack and nio-matrix
+backends.

requirements.txt

 matrix-nio
+pillow