irc-forgejo-webhook

A forgejo webhook that publishes events to an irc channel

License

Licensed under the Apache License, Version 2.0 or the MIT license, at your option.

Features

• All forgejo webhook event types supported
• Events for private repositories are ignored
• Checks for new forgejo versions
• IRC TLS support
• IRC SASL and CertFP Authentication
• Suitable for a system webhook

Limitations

• Only a single irc channel is supported
• Only listens for webhooks on localhost

How to Run

Usage: irc-forgejo-webhook --irc-config FILE --forgejo-base-url URL --webhook-port PORT

Options:
  -c, --irc-config FILE       Load irc config FILE
  -d, --dns-resolver IP:PORT  Check for forgejo updates using dns server IP:PORT
  -f, --forgejo-base-url URL  Access forgejo at URL
  -h, --help                  Display this message and exit
  -p, --webhook-port PORT     Listen on PORT for http webhook callbacks
  -v, --version               Display version and exit

IRC config file format is documented at: https://github.com/aatxe/irc
Webhook URL is: http://127.0.0.1:PORT/irc-forgejo-webhook

Build Instructions

./build.sh

Contributing

Unless you state otherwise you agree to license any contribution you make under the license in the License section.

Architecture

• Async rust using the tokio runtime
• Follows the tokio tutorial to tell tasks to exit and wait for them to finish
• Axum for webhook
• IRC crate for IRC
• Hickory resolver for checking for forgejo updates
• Rustls using aws_lc_rs crypto provider

Async Tasks

Name	Talks to	Shutdown condition
Main	All tasks	All other tasks have exited
Version Check	IRC Send	Shutdown signal
Axum HTTP Server	IRC Send	Shutdown signal
IRC Connect and Receive	Main, IRC Send, IRC Join Timeout	Disconnected from IRC server
IRC Join Timeout	Main	Timout, Shutdown signal
IRC Send	None	Sending tasks have exited

Other tasks may be spawned by libraries.

Functional Specification

We must never crash.

We may only panic before we are fully started or because of a program error. Remote connections must not be able to trigger a panic.

A version check is done by periodically comparing the released version published in a TXT DNS record at release.forgejo.org to the currently installed version published at the API version endpoint of our forgejo instance. If the versions differ we send a message to the IRC channel. We supress any further version messages to the chat room unless the version numbers change.

We connect to an IRC server and join one and only one channel. If we do not receive acknowledgement from the server that we joined the room we assume we are permanently unable to join the room and shut down.

If we are kicked from our channel or are killed by in IRC operator we shut down. If we are disconnected from IRC for any other reason we reconnect after a short delay.

We listen for webhook callbacks on the loopback interface only. If we do not understand a callback we log it but return success back to the caller.

We only send webhook events about public repositories to the IRC channel.

If we generate an IRC message that is longer than the maximum allowed IRC message length we truncate the end of the message.

We filter out any nonprintable characters from IRC messages. Importantly, this includes CRLF and NUL.

We rate limit sending IRC messages to avoid getting disconnected as a spam bot.