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:
77
docs/USAGE.md
Normal file
77
docs/USAGE.md
Normal 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.
|
||||
Reference in New Issue
Block a user