9954a890c3
New docs/DEPLOY.md covering container image, compose config, volume mounts, host networking, operations, and troubleshooting. Updated README, INSTALL, CHEATSHEET, and DEBUG to reference it. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
117 lines
2.6 KiB
Markdown
117 lines
2.6 KiB
Markdown
# Cheatsheet
|
|
|
|
## Run
|
|
|
|
```bash
|
|
bouncer -c config/bouncer.toml # start
|
|
bouncer -c config/bouncer.toml -v # start (debug)
|
|
bouncer --version # version
|
|
bouncer --help # help
|
|
```
|
|
|
|
## Podman
|
|
|
|
```bash
|
|
make build # build container image
|
|
make up # podman-compose up -d
|
|
make down # podman-compose down
|
|
make logs # podman logs -f bouncer
|
|
```
|
|
|
|
```bash
|
|
podman logs bouncer 2>&1 | grep -E 'INFO|WARN' # filtered logs
|
|
podman exec -it bouncer bash # shell into container
|
|
podman ps --filter name=bouncer # status
|
|
```
|
|
|
|
## Develop
|
|
|
|
```bash
|
|
make dev # install with dev deps into .venv
|
|
make test # pytest
|
|
make lint # ruff check
|
|
make fmt # black + ruff --fix
|
|
make run # run with config/bouncer.toml
|
|
make clean # rm .venv, build artifacts
|
|
```
|
|
|
|
## Client Auth
|
|
|
|
```
|
|
PASS <network>:<password> # select network + authenticate
|
|
PASS <password> # use first network
|
|
```
|
|
|
|
## Connection States
|
|
|
|
```
|
|
DISCONNECTED -> CONNECTING -> REGISTERING -> PROBATION (15s) -> READY
|
|
```
|
|
|
|
| State | What happens |
|
|
|-------|-------------|
|
|
| CONNECTING | TCP + SOCKS5 + TLS handshake |
|
|
| REGISTERING | Random nick/user/realname sent to server |
|
|
| PROBATION | 15s wait, watching for K-line |
|
|
| READY | Switch to configured nick, join channels |
|
|
|
|
## Reconnect Backoff
|
|
|
|
```
|
|
5s -> 10s -> 30s -> 60s -> 120s -> 300s (cap)
|
|
```
|
|
|
|
## Config Skeleton
|
|
|
|
```toml
|
|
[bouncer]
|
|
bind / port / password
|
|
[bouncer.backlog]
|
|
max_messages / replay_on_connect
|
|
|
|
[proxy]
|
|
host / port
|
|
|
|
[networks.<name>] # repeatable
|
|
host / port / tls
|
|
nick / channels / autojoin
|
|
password # optional, IRC server PASS
|
|
```
|
|
|
|
## Files
|
|
|
|
| Path | Purpose |
|
|
|------|---------|
|
|
| `config/bouncer.toml` | Active config (gitignored) |
|
|
| `config/bouncer.example.toml` | Example template |
|
|
| `config/bouncer.db` | SQLite backlog (auto-created) |
|
|
|
|
## Backlog Queries
|
|
|
|
```sql
|
|
-- recent messages
|
|
SELECT * FROM messages ORDER BY id DESC LIMIT 20;
|
|
|
|
-- per-network counts
|
|
SELECT network, COUNT(*) FROM messages GROUP BY network;
|
|
|
|
-- last seen state
|
|
SELECT * FROM client_state;
|
|
```
|
|
|
|
## Source Layout
|
|
|
|
```
|
|
src/bouncer/
|
|
__main__.py # entry point, event loop
|
|
cli.py # argparse
|
|
config.py # TOML loader
|
|
irc.py # IRC message parse/format
|
|
proxy.py # SOCKS5 connector (local DNS, multi-IP)
|
|
network.py # server connection + state machine
|
|
client.py # client session handler
|
|
router.py # message routing + backlog trigger
|
|
server.py # TCP listener
|
|
backlog.py # SQLite store/replay/prune
|
|
```
|