This is the start of an implementation of a Matrix Bridge for connecting to Hades talker (hades-talker.org 6660).
This is a work in progress, and a successor to the mx-puppet-hades project.
It's pretty rough round the edges, with a pile of things still needing fixed. But it does work in the most basic sense.
An initial registration yaml file needs to be created for matrix. This can be generated by running the application with the --generate-yaml flag. This will create a file in the data directory called hades-bridge-registration.yaml.
e.g. ./HadesMatrixBridge --generate-yaml
This file requires to be edited, specifically to check and set the url parameter, which is the URL that the matrix server will use to communicate with the bridge. This URL must be accessible from the matrix server.
This file then needs to be registered with your matrix server.
If using docker, the following command will create the registration file and then exit. Note: Currently the '/path/to/data' directroy needs to be 'chmod 777', this should be fixed in a future release.
docker run --rm -v /path/to/data:/app/data ghcr.io/neilsb/hades-matrix-bridge:latest --generate-yamlThe application can be configured using either the appsettings.json file, environment variables or command line parameters. The command line parameters take precedence over environment variables, and Environment variables take precedence over the configuration file.
The following command line options are available:
--server-url: The URL of the Matrix server.--port: The port for the bridge to listen on. (Default: 9000)--bind: The address for the bridge to bind to. (Default: 0.0.0.0)--hades-server: The hades server hostname/ip (Default: hades-talker.org)--hades-port: The hades server port (Default 6660)--hades-debug-raw-logging: Capture all incoming Hades bytes,trueorfalse(Default: false)--hades-raw-log-directory: Capture directory (Default: data/logs/hades-raw under the application directory)--database-path: Path to the bridge database file (Default: data/hades_bridge.db)--telnet-proxy: Enable the telnet proxy,trueorfalse(Default: false). See Telnet Proxy--telnet-port: The port for the telnet proxy (Default: 7000)--telnet-bind: The address for the telnet proxy to bind to (Default: 0.0.0.0)--telnet-read-only: Ignore input from telnet proxy clients,trueorfalse(Default: true)
The application will check the data directory for a file called appsettings.json.
{
"Matrix": {
"ServerUrl": "https://matrix.example.com",
"Port": 9000
},
"Database": {
"Path": "data/hades_bridge.db"
},
"Hades": {
"Server": "hades-talker.org",
"Port": 6660
},
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.Hosting.Lifetime": "Information"
}
}
}You can override any configuration setting using environment variables. The naming convention is:
SectionName__SettingName
For example:
Matrix__ServerUrl=https://matrix.example.com
Matrix__Port=9000
Database__Path=data/hades_bridge.db
Hades__Server=hades-talker.org
Hades__Port=6660
The bridge can share its connection to Hades with ordinary telnet clients, which is useful for checking exactly what the bridge is receiving. When enabled, the bridge listens on the telnet proxy port and passes everything received from Hades, exactly as received, to every connected client.
By default the proxy is read-only, and anything typed into a connected client is ignored. If ReadOnly is set to false, anything typed is sent to Hades unaltered, as the linked user.
{
"Telnet": {
"Enabled": true,
"Port": 7000,
"BindAddress": "0.0.0.0",
"ReadOnly": true
}
}Each linked puppet has its own connection to Hades, so its own proxy port: Port + (puppet id - 1). Puppet 1 uses Port, puppet 2 uses Port + 1, etc. The port used for each puppet is logged when it starts.
Connect with any telnet client, e.g. telnet bridge-host 7000.
Warning: No username or password is needed to connect to the proxy. In read/write mode, anyone who can reach the port can talk on Hades as the linked user, so only make the port reachable from networks you trust. For example, set "BindAddress": "127.0.0.1", or with Docker publish the port to the local machine only with -p 127.0.0.1:7000:7000.
Enable raw captures in appsettings.json:
{
"Hades": {
"DebugRawLogging": true,
"RawLogDirectory": "/app/data/logs/hades-raw"
}
}Or set Hades__DebugRawLogging=true and optionally Hades__RawLogDirectory, or pass --hades-debug-raw-logging true. Restart the bridge after changing these settings. Capturing is independent of the normal logging level.
Each puppet writes to puppet-<id>-YYYY-MM-DD.jsonl, rolling at UTC midnight on the next received chunk. Reconnects and restarts append to the same file with a new session ID. The default directory is data/logs/hades-raw under the application directory (inside the existing data volume when using Docker); custom relative paths resolve against the working directory. Files are retained until manually removed. A write failure is reported in the normal logs and disables capture for that connection until it reconnects.
When running in Docker, you can pass environment variables using the -e flag:
NOTE: For Matrix__ServerUrl, if not using the standard https port (443), remember to append your port, eg :8448
docker run -d \
-e Matrix__ServerUrl=https://matrix.example.com \
-e Matrix__Port=9000 \
-e Database__Path=data/hades_bridge.db \
-e Hades__Server=hades-talker.org \
-e Hades__Port=6666 \
-p 9000:9000
ghcr.io/neilsb/hades-matrix-bridge:latestOr using a docker-compose.yml file: NOTE: For Matrix__ServerUrl, if not using the standard https port (443), remember to append your port, eg :8448
version: '3'
services:
hadesmatrixbridge:
image: ghcr.io/neilsb/hades-matrix-bridge:latest
environment:
- Matrix__ServerUrl=https://matrix.example.com
- Matrix__Port=9000
- Database__Path=data/hades_bridge.db
- Hades__Server=hades-talker.org
- Hades__Port=6660
ports:
- "9000:9000"
volumes:
- ./data:/app/dataTo build the project from source, you'll need to have .NET 10.0 installed. You can then build the project using the following command:
dotnet buildFor local development, you can create an appsettings.Development.json file with your development settings. This file is excluded from git by default.
First you create a room with the bridge bot (@hadesbot:YOURSERVER.COM), and say something to get the bot to join. Next you type link <username> <password> [matrix name], e.g. link bob p@ssw0rd.
The option "Matrix Name" parameter is your user on matrix. If set, when someone mentions your username on Hades your Matrix name will be added to the text to produce a matrix mention notification.
To see a list of existing puppets, use list. To unlink a puppet just talk to the brige bot and type unlink <puppet_id>.
Once linked, restart the application and when someone speaks in the Hades talker, a new room will be created, you'll need to rememer to accept the invitation.