Weitersager
A Proxy that receives text messages via JSON over HTTP and shows them on IRC.
Based on syslog2IRC.
Requirements
Installation
Weitersager and its dependencies can be installed via pip:
$ pip install weitersager
Usage
Start Weitersager with a configuration file:
$ weitersager example.toml
Configuration
An example configuration file, example.toml
, in TOML format:
[http]
host = "127.0.0.1" # optional
port = 8080 # optional
api_tokens = [ "123xyz" ] # optional
[irc.server]
host = "irc.server.example"
port = 6667 # optional
password = "secret" # optional
rate_limit = 0.5 # optional; limit of messages per second
[irc.bot]
nickname = "Weitersager"
realname = "Weitersager" # optional
[irc]
channels = [
{ name = "#party" },
{ name = "#secretlab", password = "555-secret" },
]
IRC Dummy Mode
If no value for irc.server.host
is set, Weitersager will not attempt to connect to an IRC server and start in IRC dummy mode. It will still accept messages, but it will write them to STDOUT. This can be useful for testing.
HTTP API
To send messages to IRC, send an HTTP POST request to URL path /
at the address and port the application is listening on.
The body has to be in JSON format and contain two keys, channel
and text
, with string values:
{
"channel": "#party",
"text": "Oh yeah!"
}
Example HTTPie call to send a message to Weitersager on localhost, port 8080:
$ http --json post :8080 channel='#party' text='Oh yeah!'
Authorization
To protect the HTTP API a bit, requests can be required to include an authorization header with a valid token to be accepted.
The authorization check becomes active if at least one API token is configured. A command line tool is provided to generate secure tokens:
$ weitersager-token
e72CbijlYLqjaRIv0uMNBpgZKl397FEp-Y8PNEXn5vM
Multiple API tokens can be configured so that each legitimate client can be given its own token which can than be revoked (by removing it from the configuration, and restarting) individually.
Header format:
Authorization: Token <a token of your choosing>
Example authorization header:
Authorization: Token e72CbijlYLqjaRIv0uMNBpgZKl397FEp-Y8PNEXn5vM
Example HTTPie call with authorization header:
$ http --json post :8080 Authorization:'Token e72CbijlYLqjaRIv0uMNBpgZKl397FEp-Y8PNEXn5vM' channel='#party' text='Oh yeah!'
Note that Weitersager itself only uses unencrypted HTTP, so the API tokens are passed in the clear. That might suffice if you run it on the same host as the HTTP clients. Otherwise you might want to look into hiding Weitersager behind a web server or proxy that can add TLS encryption.
Implementation Details
A Note on Threads
This tool uses threads. Besides the main thread, there are two additional threads: one for the message receiver and one for the IRC bot. Both are configured to be daemon threads.
The dummy bot, on the other hand, does not run in a thread.
A Python application exits if no more non-daemon threads are running.
The user has to manually interrupt the application to exit.
For details, see the documentation on the threading
module that is part of Python's standard library.