# Cheatsheet

## Run

```bash
bouncer -c config/bouncer.toml         # start
bouncer -c config/bouncer.toml -v      # start (debug)
bouncer --version                      # version
bouncer --help                         # help
```

## 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
```