A proxy to forward messages received via HTTP to to IRC
Project description
A proxy that receives text messages via JSON over HTTP and shows them on IRC.
Based on syslog2IRC.
- Copyright:
2007-2020 Jochen Kupperschmidt
- License:
MIT, see LICENSE for details.
Code Status
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!'
Implementation Details
Shutdown
Weitersager can be modified so that it can be shut down via private IRC message.
This can be useful for testing, when external auto-restart is set up, or as a starting point to implement custom private message handling.
To enable it, pass keyword argument shutdown_predicate=default_shutdown_predicate to the constructor of weitersager.irc.Bot. If enabled, in order to shut down Weitersager, send a query message with the text shutdown! to the IRC bot. The bot should then quit, and Weitersager should exit.
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.
A Python application exits if no more non-daemon threads are running.
In order to exit Weitersager when shutdown is requested on IRC, the IRC bot will call die(), which will join the IRC bot thread. The main thread and the (daemonized) message receiver thread remain.
Additionally, a dedicated signal is sent that sets a flag that causes the main loop to stop. As the message receiver thread is the only one left, but runs as a daemon, the application exits.
The dummy bot, on the other hand, does not run in a thread. 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.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for Weitersager-0.4-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | bf759401991363f872fd3d6ae776e34a76172380aea606942408cebd7cf8b2d5 |
|
MD5 | 31e55bd5acef548e53b761ee246d316a |
|
BLAKE2b-256 | ae424ae72132e26516148c368c93deff89b42f1fe5d3e708f6789ae07ccc7d78 |