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.
Weitersager emerged from syslog2IRC and offers a generic, not syslog-specific input interface.
- Copyright:
2007-2022 Jochen Kupperschmidt
- License:
MIT, see LICENSE for details.
Code Status
Requirements
Installation
Weitersager and its dependencies can be installed via pip:
$ pip install weitersager
To update an installed copy of Weitersager to the most recent release:
$ pip install -U weitersager
Usage
Start Weitersager with a configuration file:
$ weitersager config.toml
Configuration
Configuration is done as a file in TOML format.
A very basic configuration is very short. By default, the HTTP server runs on port 8080 on localhost. All that needs to be specified are the IRC server host, bot nickname, and channel(s) to join.
[irc.server]
host = "irc.server.example"
[irc.bot]
nickname = "Weitersager"
[[irc.channels]]
name = "#lobby"
A lot more can be configured, though:
log_level = "debug" # optional; default: `"debug"`
[http]
host = "127.0.0.1" # optional; default: `"127.0.0.1"`
port = 8080 # optional; default: `8080`
api_tokens = [ "123xyz" ] # optional; default: `[]`
[irc.server]
host = "irc.server.example"
port = 6667 # optional; default: `6667`
ssl = false # optional; default: `false`
password = "secret" # optional; default: no password
rate_limit = 0.5 # optional; limit of messages
# per second; default: no limit
[irc.bot]
nickname = "Weitersager"
realname = "Weitersager" # optional; default: `"Weitersager"`
[irc]
commands = [ # optional; default: `[]`
"MODE Weitersager +i",
]
[[irc.channels]]
name = "#party"
[[irc.channels]]
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!'
Channel Tokens
As of version 0.9, Weitersager supports an alternative HTTP endpoint using a secret token as part of the URL instead of an authorization header. This makes it a bit easier to use for clients.
Each secret token is mapped to a channel, so each URL already implicitly (though intransparently, for the caller) defines the channel the submitted text should be sent to.
This pattern is also used by popular messaging services like Slack and Discord for incoming webhooks.
To expose a channel via this endpoint, just add one or more tokens to it:
[[irc.channels]]
name = "#secretlab"
tokens = [
"A2x23NmcdQgWJ8-5PivbvPX4KmdL9oa7Sy8Jj_9ldoY",
"JMApghB7wkHCtw0TcQ1Bu7zY-wG03os61bBDXfAZ4Yc",
]
To generate a token, use the weitersager-token command. Feel free to use a separate token for each client/app that calls the endpoint to be able to revoke tokens separately (by simply removing them from the configuration) if need be.
As a result, these endpoints become available:
/ct/A2x23NmcdQgWJ8-5PivbvPX4KmdL9oa7Sy8Jj_9ldoY
/ct/JMApghB7wkHCtw0TcQ1Bu7zY-wG03os61bBDXfAZ4Yc
Call them like this (note that neither the Authorization header nor the channel key in the payload are specified):
$ http --json post :8080/ct/A2x23NmcdQgWJ8-5PivbvPX4KmdL9oa7Sy8Jj_9ldoY text='Oh yeah!'
Run in a Docker Container
Build a container image, tagged weitersager:
$ docker build -t weitersager .
Start the container, using configuration file config_example_docker.toml (which should expose Weitersager inside the container on host 0.0.0.0 and port 8080), exposing Weitersager on the Docker host on host 127.0.0.1 and port 9000:
$ docker run -d \
--mount type=bind,source="$(pwd)"/config_example_docker.toml,destination=/app/config.toml,readonly \
-p 127.0.0.1:9000:8080 \
weitersager
The local configuration file is made available to the container through a bind mount.
Using Docker Compose
A configuration file for Docker Compose, docker-compose.yaml, is also available. Adjust as necessary, then run Weitersager in a container using:
$ docker-compose up --detach
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.
Changelog
0.9 (2022-05-07)
Introduced alternative endpoints using secret “channel tokens” as part of the URL.
0.8.1 (2022-05-05)
Fixed Werkzeug dependency missing in setup.cfg.
0.8 (2022-05-04)
Recreated HTTP server as a WSGI application, built with Werkzeug and served by wsgiref.
Return status code 415 (“Unsupported Media Type”) if request content type is not application/json.
0.7.2 (2022-05-03)
Return status code 404 (“Not Found”) on requests to any path other than /.
Added Docker-specific configuration file example.
Added configuration file for Docker Compose.
0.7.1 (2022-04-27)
Changed application path in Docker container from /home/user to /app. This is relevant when mounting the configuration file into the container.
0.7 (2022-04-26)
Added support for Python 3.10.
Expect config file to be mounted into Docker container.
Use non-inline array of tables for IRC channels in TOML configuration examples.
Reintroduce announcer as abstraction.
Updated irc version to 20.0.0 (from 19.0.1).
Updated rtoml to 0.7.1 (from 0.6.1).
0.6 (2021-05-07)
Switched to using Python’s logging mechanism directly, with different log levels. Removed function util.log.
Made the application’s log level configurable.
Enabled threading for the HTTP server to reduce blocking.
Introduced an internal queue to decouple reception of HTTP requests from announcing messages on IRC.
Added support for custom IRC commands to send after connecting (authentication, cloaking, flood protection, etc.).
Updated rtoml to 0.6.1 (from 0.5.0).
0.5 (2021-02-07)
Added support for Python 3.9.
Added support for SSL connections to IRC servers.
Changed prefix of authorization header value from WTRSGR to less awkward Token.
Removed handler to shut down Weitersager via private IRC message. It doesn’t provide enough relevant value.
Added command line option --version to show Weitersager’s version.
Updated rtoml to 0.5.0 (from 0.4.0).
Include tests and other useful files in source distribution archive.
0.4 (2020-10-11)
Added command line tool to generate secure tokens (which can be used as API tokens).
Allow to configure a rate limit for the IRC connection, i.e. the maximum number of messages per second to send. This can prevent the bot from getting kicked (or even banned) from a channel because of flooding.
Added exemplary Dockerfile.
Added type hints.
Updated rtoml to 0.4.0 (from 0.3.0).
0.3 (2020-09-16)
Introduced TOML-based configuration file.
Added dependency on rtoml 0.3.0.
Moved IRC channel configuration from Python code to configuration file.
Moved IRC server and bot name configuration from command line arguments to configuration file.
Moved HTTP receiver configuration from command line arguments to configuration file.
Made configuration filename a required command line argument.
Turned the stray run script into an actual entry point console script.
Added support for IRC server password.
Added optional HTTP authorization via API tokens.
0.2 (2020-09-13)
Raised minimum Python version to 3.7.
HTTP protocol was changed:
Only a single channel is allowed per message.
Response code for successful submit was changed from 200 (OK) to more appropriate 202 (Accepted).
Divided code base into separate modules in a package.
Switch to a src/ layout.
Dependency versions have been pinned.
Updated irc version to 19.0.1 (from 12.3).
Updated blinker to 1.4 (from 1.3).
Do not use tox for tests anymore.
Use dataclass instead of namedtuple for value objects.
Allowed for custom shutdown predicate.
0.1 (2015-04-24)
First official release (at LANresort 2015)
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.9-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8c483744a6d03cbf1c054c8e582bc02b3ef236e11584e11bd0716a5d1ed20c7c |
|
MD5 | 0777073b509cb86d7b15dc6e7c1619dc |
|
BLAKE2b-256 | 88972fd77dfb71d1f8ded8bbe00036d795823c96aebe568145d5d282b5b61321 |