socktop-webterm/IDLE_TIMEOUT_QUICKREF.md

# Idle Timeout Quick Reference

## TL;DR
- **Default Timeout**: 5 minutes of inactivity
- **What Triggers Cleanup**: No keyboard input, no resize events
- **What Keeps Alive**: Any typing, window resizing
- **Check Interval**: Every 30 seconds
- **Purpose**: Prevent orphaned terminal processes from accumulating

---

## Configuration (src/lib.rs)

```rust
const IDLE_TIMEOUT: Duration = Duration::from_secs(300);        // 5 minutes
const IDLE_CHECK_INTERVAL: Duration = Duration::from_secs(30);  // Check every 30s
```

---

## Quick Adjustments

### Conservative (10 minutes)
```rust
const IDLE_TIMEOUT: Duration = Duration::from_secs(600);
```

### Aggressive (1 minute)
```rust
const IDLE_TIMEOUT: Duration = Duration::from_secs(60);
```

### Testing (30 seconds)
```rust
const IDLE_TIMEOUT: Duration = Duration::from_secs(30);
```

---

## Environment Variable Support (Optional)

Add to `Terminal::new()`:
```rust
let idle_timeout = std::env::var("IDLE_TIMEOUT_SECS")
    .ok()
    .and_then(|s| s.parse().ok())
    .map(Duration::from_secs)
    .unwrap_or(IDLE_TIMEOUT);
```

Then run with:
```bash
IDLE_TIMEOUT_SECS=600 cargo run
```

Or in Docker:
```dockerfile
ENV IDLE_TIMEOUT_SECS=600
```

---

## Log Messages to Watch

```
INFO  webterm - Started Terminal
INFO  webterm - Terminal idle timeout reached (5m 0s idle), stopping session
INFO  webterm - Stopping Terminal
INFO  webterm - Stopped Terminal
```

---

## Testing

### Test Idle Timeout
1. Start server: `cargo run`
2. Connect in browser
3. Stop typing/interacting
4. Wait 5 minutes (or configured timeout)
5. Check logs for timeout message
6. Verify process gone: `ps aux | grep socktop-agent`

### Test Page Refresh
1. Connect and note PID: `ps aux | grep socktop-agent`
2. Refresh page (creates new session)
3. Old PID should disappear after timeout
4. New PID should be present

### Test Active Session
1. Connect and actively type
2. Session stays alive indefinitely
3. Each keystroke resets the timer

---

## Monitoring Commands

### Count Active Sessions
```bash
ps aux | grep socktop-agent | grep -v grep | wc -l
```

### List All Sessions
```bash
ps aux | grep socktop-agent | grep -v grep
```

### Watch in Real-Time
```bash
watch -n 5 'ps aux | grep socktop-agent | grep -v grep'
```

### Tail Logs for Timeouts
```bash
tail -f /path/to/logs | grep "idle timeout"
```

---

## Activity Types

| Activity | Resets Timer? | Notes |
|----------|--------------|-------|
| Keyboard input | ✅ Yes | Any typing in terminal |
| Window resize | ✅ Yes | Browser window resize |
| Mouse events | ❌ No | Not implemented |
| PTY output | ❌ No | Program output doesn't count |
| Heartbeat | ❌ No | Connection check only |

---

## Common Scenarios

### Scenario 1: User Refreshes Page
- Old session: Times out after 5 min ✅
- New session: Created immediately ✅
- Result: Clean transition, old resources freed

### Scenario 2: User Abandons Tab
- Session: Times out after 5 min ✅
- Resources: Fully cleaned up ✅
- Result: No grey goo accumulation

### Scenario 3: Long-Running Command
- User starts: `tail -f /var/log/syslog`
- User walks away
- After 5 min: Session killed ⚠️
- Solution: Increase timeout or use tmux/screen

### Scenario 4: Active Development
- User types commands frequently
- Timer resets with each command ✅
- Session never times out ✅
- Result: Uninterrupted workflow

---

## Tuning Guide

| Use Case | Recommended Timeout | Rationale |
|----------|---------------------|-----------|
| Development | 10-15 minutes | Avoid interrupting debugging |
| Production | 5 minutes | Balance UX and resources |
| Public demo | 1-2 minutes | Aggressive resource reclaim |
| Long tasks | 30-60 minutes | Allow batch jobs to complete |
| High traffic | 2-3 minutes | Prevent resource exhaustion |

---

## Troubleshooting

### Sessions Timing Out Too Quickly
- Increase `IDLE_TIMEOUT` value
- Check that activity tracking is working (look for resets in logs)
- Ensure message handlers are updating `last_activity`

### Sessions Not Cleaning Up
- Check `IDLE_CHECK_INTERVAL` is set correctly
- Verify interval callback is registered in `started()`
- Look for errors in logs preventing `ctx.stop()`

### Too Many Processes Accumulating
- Decrease `IDLE_TIMEOUT` value
- Add session limits (max concurrent)
- Check for other resource leaks

---

## Performance Impact

- **Memory**: ~16 bytes per Terminal (2 fields: Instant + Duration)
- **CPU**: Negligible (30s interval check)
- **I/O**: None (in-memory timestamp comparison)
- **Overall**: Very low overhead ✅

---

## See Also

- [IDLE_TIMEOUT.md](IDLE_TIMEOUT.md) - Full documentation
- [CONVERSATION_SUMMARY.md](CONVERSATION_SUMMARY.md) - Implementation discussion
- [DOCKER_DEPLOYMENT.md](DOCKER_DEPLOYMENT.md) - Deployment guide

---

## Quick Checklist

Before deploying:
- [ ] Set appropriate `IDLE_TIMEOUT` for your use case
- [ ] Test with quick timeout (30s) to verify behavior
- [ ] Set up log monitoring for timeout events
- [ ] Document timeout policy for users
- [ ] Consider adding metrics/alerting
- [ ] Plan for handling long-running commands

After deploying:
- [ ] Monitor timeout frequency in logs
- [ ] Check resource usage (CPU, memory, process count)
- [ ] Gather user feedback on timeout duration
- [ ] Adjust timeout based on real-world usage
- [ ] Set up alerts for abnormal process counts