8cc57a7af4
Multiplex all networks onto a single client connection using /network suffixes on channels and nicks. PASS is now just the password (no network prefix). Channels appear as #channel/network, foreign nicks as nick/network, own nicks stay bare. New namespace.py module with pure encode/decode functions. Router tracks clients globally (not per-network), namespaces messages before delivery. Client attaches to all networks on connect, sends synthetic JOIN/TOPIC/NAMES for every channel across all networks. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
94 lines
2.5 KiB
Markdown
94 lines
2.5 KiB
Markdown
# bouncer
|
|
|
|
IRC bouncer with SOCKS5 proxy support and persistent message backlog.
|
|
|
|
## Features
|
|
|
|
- **Multi-network multiplexing**: single client connection sees all networks via `/network` suffixes
|
|
- All outbound connections routed through SOCKS5 proxy
|
|
- Stealth connect: registers with a random pronounceable nick and generic identity
|
|
- Probation window: waits 15s after registration to detect K-lines before revealing real nick
|
|
- Persistent message backlog (SQLite) with replay on reconnect
|
|
- Multiple clients can attach simultaneously
|
|
- Password authentication
|
|
- TLS support for IRC server connections
|
|
- Automatic reconnection with exponential backoff
|
|
- Local DNS resolution with multi-address failover
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
cd ~/git/bouncer
|
|
make dev
|
|
|
|
cp config/bouncer.example.toml config/bouncer.toml
|
|
$EDITOR config/bouncer.toml
|
|
|
|
bouncer -c config/bouncer.toml -v
|
|
```
|
|
|
|
## Connect
|
|
|
|
From your IRC client, connect to `127.0.0.1:6667` with:
|
|
|
|
```
|
|
PASS yourpassword
|
|
```
|
|
|
|
A single connection gives you all configured networks. Channels and nicks
|
|
appear with a `/network` suffix:
|
|
|
|
```
|
|
Client sees: Server sends/receives:
|
|
#libera/libera <-> #libera (on libera network)
|
|
#debian/oftc <-> #debian (on oftc network)
|
|
user123/libera <-> user123 (on libera network)
|
|
```
|
|
|
|
## How It Works
|
|
|
|
```
|
|
IRC Client(s) --> [bouncer:6667] --> Router --> [SOCKS5:1080] --> IRC Server(s)
|
|
|
|
|
Backlog
|
|
(SQLite)
|
|
```
|
|
|
|
1. Bouncer connects to IRC server via SOCKS5 with a random identity
|
|
2. Survives 15s probation (K-line detection)
|
|
3. Switches to your configured nick
|
|
4. Joins configured channels
|
|
5. Clients connect to bouncer, receive backlog replay and channel state
|
|
|
|
## Podman Deployment
|
|
|
|
```bash
|
|
cp config/bouncer.example.toml config/bouncer.toml
|
|
$EDITOR config/bouncer.toml
|
|
|
|
make build
|
|
make up
|
|
make logs
|
|
```
|
|
|
|
See [docs/DEPLOY.md](docs/DEPLOY.md) for full container documentation.
|
|
|
|
## Documentation
|
|
|
|
| Document | Description |
|
|
|----------|-------------|
|
|
| [docs/INSTALL.md](docs/INSTALL.md) | Prerequisites and setup |
|
|
| [docs/USAGE.md](docs/USAGE.md) | Comprehensive guide |
|
|
| [docs/DEPLOY.md](docs/DEPLOY.md) | Podman container deployment |
|
|
| [docs/CHEATSHEET.md](docs/CHEATSHEET.md) | Quick reference |
|
|
| [docs/DEBUG.md](docs/DEBUG.md) | Troubleshooting |
|
|
|
|
## Development
|
|
|
|
```bash
|
|
make dev # Install with dev deps
|
|
make test # Run tests
|
|
make lint # Run linter
|
|
make fmt # Format code
|
|
```
|