feat: initial IRC bouncer implementation

Async Python IRC bouncer with SOCKS5 proxy support, multi-network
connections, password auth, and persistent SQLite backlog with replay.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
user
2026-02-19 11:29:59 +01:00
commit ced6232373
28 changed files with 2079 additions and 0 deletions

77
docs/USAGE.md Normal file
View File

@@ -0,0 +1,77 @@
# Usage
## Starting the Bouncer
```bash
bouncer -c config/bouncer.toml -v
```
| Flag | Description |
|------|-------------|
| `-c, --config PATH` | Config file (default: `config/bouncer.toml`) |
| `-v, --verbose` | Debug logging |
| `--version` | Show version |
## Connecting with an IRC Client
Configure your IRC client to connect to the bouncer:
| Setting | Value |
|---------|-------|
| Server | `127.0.0.1` |
| Port | `6667` (or as configured) |
| Password | `networkname:yourpassword` |
### Password Format
```
PASS <network>:<password>
```
- `network` -- matches a `[networks.NAME]` section in config
- `password` -- the `bouncer.password` value from config
If you omit the network prefix (`PASS yourpassword`), the first configured network is used.
### Client Examples
**irssi:**
```
/connect -password libera:mypassword 127.0.0.1 6667
```
**weechat:**
```
/server add bouncer 127.0.0.1/6667 -password=libera:mypassword
/connect bouncer
```
**hexchat:**
Set server password to `libera:mypassword` in the network settings.
## Multiple Networks
Define multiple `[networks.*]` sections in the config. Connect with different passwords to access each:
```
PASS libera:mypassword # connects to libera
PASS oftc:mypassword # connects to oftc
```
Multiple clients can attach to the same network simultaneously.
## Backlog
Messages are stored in `bouncer.db` (SQLite) next to the config file. When you reconnect, missed messages are automatically replayed.
Configure backlog in `bouncer.toml`:
```toml
[bouncer.backlog]
max_messages = 10000 # per network, 0 = unlimited
replay_on_connect = true # set false to disable replay
```
## Stopping
Press `Ctrl+C` or send `SIGTERM`. The bouncer shuts down gracefully.