a58848395c
Update README, PROJECT, ROADMAP, TASKS, TODO, USAGE, CHEATSHEET, INSTALL, and DEBUG to reflect stealth connect, probation window, markov nick generation, local DNS resolution, and multi-IP failover. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
66 lines
2.2 KiB
Markdown
66 lines
2.2 KiB
Markdown
# Project: bouncer
|
|
|
|
## Purpose
|
|
|
|
IRC bouncer that maintains persistent connections to IRC servers through a
|
|
SOCKS5 proxy, allowing IRC clients to connect/disconnect while keeping the
|
|
session alive and replaying missed messages.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
IRC Client(s) --> [bouncer:6667] --> Router --> [SOCKS5:1080] --> IRC Server(s)
|
|
|
|
|
Backlog
|
|
(SQLite)
|
|
```
|
|
|
|
### Connection State Machine
|
|
|
|
```
|
|
DISCONNECTED -> CONNECTING -> REGISTERING -> PROBATION (15s) -> READY
|
|
| | |
|
|
'--------------+--------------'
|
|
(failure = backoff + retry)
|
|
```
|
|
|
|
- **CONNECTING**: SOCKS5 + optional TLS handshake
|
|
- **REGISTERING**: Random nick/user/realname sent to server
|
|
- **PROBATION**: 15s window to detect K-lines before exposing real identity
|
|
- **READY**: Configured nick set, channels joined, clients served
|
|
|
|
### Components
|
|
|
|
| Module | Responsibility |
|
|
|--------|---------------|
|
|
| `irc.py` | IRC protocol parser/formatter (RFC 2812 subset) |
|
|
| `config.py` | TOML configuration loading and validation |
|
|
| `proxy.py` | SOCKS5 async connector with local DNS + multi-IP failover |
|
|
| `network.py` | Server connection state machine, stealth registration |
|
|
| `server.py` | TCP listener accepting IRC client connections |
|
|
| `client.py` | Per-client session, PASS/NICK/USER handshake |
|
|
| `router.py` | Message routing between clients and networks |
|
|
| `backlog.py` | SQLite message storage and replay |
|
|
|
|
### Key Decisions
|
|
|
|
- **asyncio**: single-threaded async for all I/O
|
|
- **python-socks**: async SOCKS5 proxy support
|
|
- **aiosqlite**: non-blocking SQLite for backlog
|
|
- **No IRC library**: manual protocol handling (IRC is line-based)
|
|
- **Markov nicks**: English bigram frequencies for pronounceable random nicks
|
|
- **Local DNS**: resolve before SOCKS5 to handle proxies without DNS support
|
|
- **Multi-IP**: try all resolved addresses, skip unreachable exit IPs
|
|
|
|
## Dependencies
|
|
|
|
| Package | Version | Purpose |
|
|
|---------|---------|---------|
|
|
| python-socks[asyncio] | >=2.4 | SOCKS5 proxy |
|
|
| aiosqlite | >=0.19 | Async SQLite |
|
|
|
|
## Requirements
|
|
|
|
- Python 3.10+
|
|
- SOCKS5 proxy on 127.0.0.1:1080
|