# MUD Keep-Alive Proxy

A lightweight TCP proxy that keeps your MUD connection alive when your client disconnects. No more losing your session because your phone went to sleep, your WiFi dropped, or you closed your laptop.

## What It Does

When you play a MUD (Multi-User Dungeon) from a mobile device or over an unreliable connection, you can get disconnected frequently. Each time, you have to reconnect, re-login, and lose any unsaved progress or context.

The MUD Keep-Alive Proxy sits between your MUD client and the MUD server:

```
MUD Client  -->  Proxy (your machine)  -->  MUD Server
```

- If your client disconnects, the proxy keeps the MUD connection alive
- The proxy sends periodic keepalive pings to prevent idle timeouts
- When you reconnect, missed output is replayed automatically
- Your character stays in-game the entire time

## Prerequisites

- **Python 3.8 or later** (included with macOS and most Linux distributions)
- Verify your version: `python3 --version`

## Quick Start

### 1. Download

Download `mud_proxy.py` to any folder on your machine.

### 2. Configure

Open `mud_proxy.py` in any text editor and find the **CONFIGURATION** section near the top. Change these two settings at minimum:

```python
# The MUD server you want to connect to
MUD_HOST = "your-mud-server.com"   # <-- Change this
MUD_PORT = 4000                     # <-- Change this
```

Optionally adjust the proxy port and keepalive interval:

```python
PROXY_PORT = 4000              # The port your MUD client connects to
KEEPALIVE_INTERVAL = 120       # Seconds between keepalive pings (0 to disable)
```

### 3. Run

```bash
python3 mud_proxy.py
```

You should see:

```
[2025-01-01 12:00:00] INFO MUD Keep-Alive Proxy v1.0.0 started
[2025-01-01 12:00:00] INFO Listening on ('0.0.0.0', 4000)
[2025-01-01 12:00:00] INFO Forwarding to your-mud-server.com:4000
[2025-01-01 12:00:00] INFO Ready for connections.
```

### 4. Connect Your MUD Client

Instead of connecting to the MUD server directly, connect to the proxy:

- **Host:** `localhost` (or the machine's IP if running remotely)
- **Port:** `4000` (or whatever you set `PROXY_PORT` to)

That's it. You're playing through the proxy.

## Configuration Reference

| Setting | Default | Description |
|---------|---------|-------------|
| `MUD_HOST` | `your-mud-server.com` | Hostname or IP of the MUD server |
| `MUD_PORT` | `4000` | Port of the MUD server |
| `PROXY_HOST` | `0.0.0.0` | Interface to listen on (`0.0.0.0` = all interfaces) |
| `PROXY_PORT` | `4000` | Port your MUD client connects to |
| `KEEPALIVE_INTERVAL` | `120` | Seconds between keepalive pings to the MUD server. Set to `0` to disable. |
| `KEEPALIVE_COMMAND` | `""` (empty) | Command sent as keepalive. Empty line works for most MUDs. Other options: `"idle"`, `"look"` |
| `ORPHAN_TIMEOUT_MINUTES` | `60` | Minutes to keep MUD connection alive after client disconnects. Set to `0` to close immediately. |
| `BUFFER_MAX_KB` | `64` | Max KB of MUD output to buffer while client is disconnected |
| `MAX_CONNECTIONS` | `10` | Maximum simultaneous client connections |
| `LOG_LEVEL` | `INFO` | Logging verbosity: `DEBUG`, `INFO`, `WARNING`, `ERROR` |

## Using with MUD Portal (iOS)

MUD Portal is a MUD client for iPhone. To use it with this proxy:

1. Run the proxy on a machine that stays online (a home server, VPS, or always-on desktop)
2. In MUD Portal, create a new server entry:
   - **Host:** Your proxy machine's IP address (e.g., `192.168.1.100` for LAN, or your public IP/domain for remote)
   - **Port:** Your `PROXY_PORT` (default `4000`)
3. Connect as usual. The proxy handles everything transparently.

If your phone goes to sleep or you switch apps, the proxy keeps your MUD session alive. When MUD Portal reconnects, you pick up right where you left off.

## Running as a Background Service

### Using screen (Linux/macOS)

```bash
screen -S mudproxy python3 mud_proxy.py
```

Detach with `Ctrl+A, D`. Reattach with `screen -r mudproxy`.

### Using tmux (Linux/macOS)

```bash
tmux new -s mudproxy python3 mud_proxy.py
```

Detach with `Ctrl+B, D`. Reattach with `tmux attach -t mudproxy`.

### Using nohup (Linux/macOS)

```bash
nohup python3 mud_proxy.py > mud_proxy.log 2>&1 &
echo $! > mud_proxy.pid
```

Stop with: `kill $(cat mud_proxy.pid)`

### Using systemd (Linux)

Create `/etc/systemd/system/mud-proxy.service`:

```ini
[Unit]
Description=MUD Keep-Alive Proxy
After=network.target

[Service]
Type=simple
User=your-username
WorkingDirectory=/path/to/proxy
ExecStart=/usr/bin/python3 /path/to/mud_proxy.py
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
```

Then:

```bash
sudo systemctl daemon-reload
sudo systemctl enable mud-proxy
sudo systemctl start mud-proxy
```

Check status: `sudo systemctl status mud-proxy`

View logs: `journalctl -u mud-proxy -f`

## Troubleshooting

### "Could not reach the MUD server (timeout)"

- Verify `MUD_HOST` and `MUD_PORT` are correct
- Test the MUD server directly: `telnet your-mud-server.com 4000`
- Check that the MUD server is running and accepting connections
- If the MUD server is on a different network, check firewall rules

### "Connection refused" when connecting MUD client to proxy

- Make sure the proxy is running
- Check that `PROXY_PORT` matches what your client is connecting to
- If running on a remote machine, check that the port is open in the firewall

### Proxy connects but I get disconnected immediately

- The MUD server may be rejecting connections from the proxy's IP
- Some MUD servers have connection limits per IP
- Try increasing `KEEPALIVE_INTERVAL` if the MUD server is rate-limiting

### Character goes AFK / gets kicked while proxied

- Reduce `KEEPALIVE_INTERVAL` (try 60 seconds)
- Change `KEEPALIVE_COMMAND` to something the MUD recognizes (e.g., `"idle"` or `"look"`)
- Some MUDs detect and kick idle characters regardless of network activity

### "PROXY_PORT and MUD_PORT cannot be the same"

If your MUD server runs on the same machine as the proxy, you must use different ports:

```python
MUD_HOST = "127.0.0.1"
MUD_PORT = 4000       # The MUD server's port
PROXY_PORT = 4001     # A different port for the proxy
```

### Session not resuming after reconnect

- Auto-resume works by matching your IP address. If your IP changed (e.g., switching from WiFi to cellular), you'll get a new session instead of resuming.
- The orphan timeout may have expired. Increase `ORPHAN_TIMEOUT_MINUTES` if needed.

## How It Works (Technical)

The proxy is a single-file asyncio application with no external dependencies. When a client connects:

1. The proxy opens a TCP connection to the MUD server
2. Two relay tasks forward data in each direction (client -> MUD, MUD -> client)
3. A keepalive task periodically sends a command to the MUD server
4. TCP-level keepalives detect dead network connections

If the client disconnects:

1. The session is marked "orphaned"
2. The MUD connection stays alive
3. MUD output is buffered (up to `BUFFER_MAX_KB`)
4. Keepalive pings continue
5. After `ORPHAN_TIMEOUT_MINUTES`, the MUD connection is closed

When a new client connects from the same IP:

1. The proxy detects the orphaned session
2. Buffered output is replayed
3. Normal relay resumes

## License

MIT License. Use it however you like.