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)

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)

const IDLE_TIMEOUT: Duration = Duration::from_secs(600);

Aggressive (1 minute)

const IDLE_TIMEOUT: Duration = Duration::from_secs(60);

Testing (30 seconds)

const IDLE_TIMEOUT: Duration = Duration::from_secs(30);

---

Environment Variable Support (Optional)

Add to Terminal::new():

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:

IDLE_TIMEOUT_SECS=600 cargo run

Or in Docker:

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

ps aux | grep socktop-agent | grep -v grep | wc -l

List All Sessions

ps aux | grep socktop-agent | grep -v grep

Watch in Real-Time

watch -n 5 'ps aux | grep socktop-agent | grep -v grep'

Tail Logs for Timeouts

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 - Full documentation
• CONVERSATION_SUMMARY.md - Implementation discussion
• 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