Implement comprehensive rate limiting system and item spawn configuration

Major Features Added: - Complete token bucket rate limiting for IRC commands and web interface - Per-user rate tracking with category-based limits (Basic, Gameplay, Management, Admin, Web) - Admin commands for rate limit management (\!rate_stats, \!rate_user, \!rate_unban, \!rate_reset) - Automatic violation tracking and temporary bans with cleanup - Global item spawn multiplier system with 75% spawn rate reduction - Central admin configuration system (config.py) - One-command bot startup script (start_petbot.sh) Rate Limiting: - Token bucket algorithm with burst capacity and refill rates - Category limits: Basic (20/min), Gameplay (10/min), Management (5/min), Web (60/min) - Graceful violation handling with user-friendly error messages - Admin exemption and override capabilities - Background cleanup of old violations and expired bans Item Spawn System: - Added global_spawn_multiplier to config/items.json for easy adjustment - Reduced all individual spawn rates by 75% (multiplied by 0.25) - Admins can fine-tune both global multiplier and individual item rates - Game engine integration applies multiplier to all spawn calculations Infrastructure: - Single admin user configuration in config.py - Enhanced startup script with dependency management and verification - Updated documentation and help system with rate limiting guide - Comprehensive test suite for rate limiting functionality Security: - Rate limiting protects against command spam and abuse - IP-based tracking for web interface requests - Proper error handling and status codes (429 for rate limits) 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-07-15 20:10:43 +00:00 · 2025-07-15 20:10:43 +00:00 · 915aa00bea
commit 915aa00bea
parent f8ac661cd1
28 changed files with 5730 additions and 57 deletions
--- a/INSTALLATION.md
+++ b/INSTALLATION.md
@ -0,0 +1,462 @@
+# PetBot Installation Guide
+
+## Overview
+
+PetBot is a Python-based IRC bot with web interface for Pokemon-style pet collecting. This guide covers complete installation and setup.
+
+## Prerequisites
+
+### System Requirements
+
+- **Python**: 3.7 or higher
+- **pip**: Python package installer
+- **Operating System**: Linux, macOS, or Windows with Python support
+- **Memory**: 512MB RAM minimum
+- **Storage**: 1GB available space
+- **Network**: Internet connection for IRC and web access
+
+### Required Python Packages
+
+- `irc>=20.3.0` - IRC client library
+- `aiosqlite>=0.19.0` - Async SQLite database interface
+- `python-dotenv>=1.0.0` - Environment variable loading
+
+## Installation Methods
+
+### Method 1: Automatic Installation (Recommended)
+
+#### Step 1: Download and Run Installation Script
+
+```bash
+# Make the script executable
+chmod +x install_prerequisites.sh
+
+# Run the installation
+./install_prerequisites.sh
+```
+
+#### Step 2: Alternative Python Script
+
+If the shell script doesn't work:
+
+```bash
+python3 install_prerequisites.py
+```
+
+### Method 2: Manual Installation
+
+#### Step 1: Install System Dependencies
+
+**Ubuntu/Debian:**
+```bash
+sudo apt update
+sudo apt install python3 python3-pip python3-venv
+```
+
+**CentOS/RHEL:**
+```bash
+sudo yum install python3 python3-pip
+```
+
+**macOS:**
+```bash
+# Install Homebrew if not installed
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
+# Install Python
+brew install python3
+```
+
+**Windows:**
+1. Download Python from https://python.org/downloads/
+2. Run installer and check "Add Python to PATH"
+3. Open Command Prompt as administrator
+
+#### Step 2: Install Python Packages
+
+```bash
+# Install from requirements file
+pip3 install -r requirements.txt
+
+# Or install individually
+pip3 install irc>=20.3.0 aiosqlite>=0.19.0 python-dotenv>=1.0.0
+```
+
+#### Step 3: Create Required Directories
+
+```bash
+mkdir -p data backups logs
+```
+
+#### Step 4: Make Scripts Executable (Linux/macOS)
+
+```bash
+chmod +x run_bot_debug.py
+chmod +x run_bot_with_reconnect.py
+chmod +x test_backup_simple.py
+chmod +x test_reconnection.py
+```
+
+## Verification
+
+### Test Installation
+
+```bash
+# Test backup system
+python3 test_backup_simple.py
+
+# Test IRC reconnection system
+python3 test_reconnection.py
+```
+
+### Expected Output
+
+Both tests should show:
+```
+🎉 All tests passed! ... is working correctly.
+```
+
+## Configuration
+
+### IRC Settings
+
+The bot connects to IRC with default settings:
+
+```python
+config = {
+    "server": "irc.libera.chat",
+    "port": 6667,
+    "nickname": "PetBot",
+    "channel": "#petz",
+    "command_prefix": "!"
+}
+```
+
+To modify these settings, edit the configuration in:
+- `run_bot_debug.py` (line 21-27)
+- `run_bot_with_reconnect.py` (line 35-41)
+
+### Database Configuration
+
+The bot uses SQLite database stored in `data/petbot.db`. No additional configuration required.
+
+### Web Server Configuration
+
+The web server runs on port 8080 by default. To change:
+- Edit `webserver.py` or bot runner files
+- Update the port number in web server initialization
+
+## Running the Bot
+
+### Option 1: Debug Mode (Original)
+
+```bash
+python3 run_bot_debug.py
+```
+
+**Features:**
+- Basic IRC connection
+- Console debugging output
+- Module loading and validation
+- Web server on port 8080
+
+### Option 2: Auto-Reconnect Mode (Recommended)
+
+```bash
+python3 run_bot_with_reconnect.py
+```
+
+**Features:**
+- Automatic IRC reconnection
+- Connection health monitoring
+- Exponential backoff for reconnection
+- Comprehensive logging
+- Connection statistics
+- Web server on port 8080
+
+### Running as a Service (Linux)
+
+Create a systemd service file:
+
+```bash
+sudo nano /etc/systemd/system/petbot.service
+```
+
+```ini
+[Unit]
+Description=PetBot IRC Bot
+After=network.target
+
+[Service]
+Type=simple
+User=petbot
+WorkingDirectory=/path/to/petbot
+ExecStart=/usr/bin/python3 run_bot_with_reconnect.py
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Enable and start:
+
+```bash
+sudo systemctl enable petbot
+sudo systemctl start petbot
+sudo systemctl status petbot
+```
+
+## Web Interface
+
+### Access
+
+- **Local**: http://localhost:8080
+- **Production**: Configure reverse proxy for HTTPS
+
+### Available Pages
+
+- `/` - Homepage and help
+- `/players` - Player leaderboard
+- `/player/<name>` - Player profile
+- `/teambuilder/<name>` - Team builder with PIN verification
+
+## Troubleshooting
+
+### Common Issues
+
+#### 1. ModuleNotFoundError
+
+**Error:** `ModuleNotFoundError: No module named 'irc'`
+
+**Solution:**
+```bash
+pip3 install irc>=20.3.0 aiosqlite>=0.19.0 python-dotenv>=1.0.0
+```
+
+#### 2. Permission Denied
+
+**Error:** `Permission denied: './install_prerequisites.sh'`
+
+**Solution:**
+```bash
+chmod +x install_prerequisites.sh
+```
+
+#### 3. Database Errors
+
+**Error:** `sqlite3.OperationalError: unable to open database file`
+
+**Solution:**
+```bash
+mkdir -p data
+chmod 755 data
+```
+
+#### 4. IRC Connection Issues
+
+**Error:** `Could not connect to irc.libera.chat:6667`
+
+**Solution:**
+- Check internet connection
+- Verify IRC server is accessible
+- Check firewall settings
+- Try different IRC server/port
+
+#### 5. Web Interface Not Accessible
+
+**Error:** `Connection refused on port 8080`
+
+**Solution:**
+- Check if bot is running
+- Verify port 8080 is not blocked
+- Check firewall settings
+- Try accessing via 127.0.0.1:8080
+
+### Debugging
+
+#### Enable Debug Logging
+
+```bash
+python3 run_bot_with_reconnect.py > logs/bot.log 2>&1
+```
+
+#### Check System Resources
+
+```bash
+# Check memory usage
+free -h
+
+# Check disk space
+df -h
+
+# Check network connectivity
+ping irc.libera.chat
+```
+
+#### Test Individual Components
+
+```bash
+# Test database
+python3 -c "from src.database import Database; db = Database(); print('Database OK')"
+
+# Test IRC connection manager
+python3 -c "from src.irc_connection_manager import IRCConnectionManager; print('IRC manager OK')"
+
+# Test web server
+python3 -c "import webserver; print('Web server OK')"
+```
+
+## Security Considerations
+
+⚠️ **Important**: Review `issues.txt` for security vulnerabilities before production deployment.
+
+### Immediate Actions Required
+
+1. **HTTPS**: Run behind reverse proxy with SSL
+2. **Authentication**: Implement web interface authentication
+3. **Input Validation**: Fix XSS vulnerabilities
+4. **Access Control**: Implement proper user authorization
+
+### Production Checklist
+
+- [ ] SSL/TLS certificate installed
+- [ ] Reverse proxy configured (nginx/Apache)
+- [ ] Firewall rules configured
+- [ ] User authentication implemented
+- [ ] Input validation added
+- [ ] Security headers configured
+- [ ] Database backups scheduled
+- [ ] Log rotation configured
+- [ ] Monitoring alerts set up
+
+## Performance Optimization
+
+### Database
+
+- Enable WAL mode for better concurrent access
+- Regular VACUUM operations
+- Monitor database size and growth
+
+### Web Server
+
+- Use reverse proxy for static files
+- Enable gzip compression
+- Implement caching for static content
+
+### IRC Connection
+
+- Monitor connection stability
+- Adjust reconnection parameters if needed
+- Set up connection monitoring alerts
+
+## Backup and Recovery
+
+### Automated Backups
+
+The bot includes automated backup system:
+
+```bash
+# Manual backup
+python3 -c "
+import asyncio
+from src.backup_manager import BackupManager
+bm = BackupManager()
+result = asyncio.run(bm.create_backup('manual', True))
+print(f'Backup created: {result}')
+"
+```
+
+### Recovery
+
+```bash
+# List available backups
+ls -la backups/
+
+# Restore from backup (use admin command or direct restore)
+python3 -c "
+import asyncio
+from src.backup_manager import BackupManager
+bm = BackupManager()
+result = asyncio.run(bm.restore_backup('backup_filename.db.gz'))
+print(f'Restore result: {result}')
+"
+```
+
+## Monitoring
+
+### Connection Health
+
+Use the connection monitoring commands:
+
+```
+!status        # Check connection status
+!uptime        # Show uptime and stats
+!ping          # Test responsiveness
+!connection_stats  # Detailed statistics
+```
+
+### Log Monitoring
+
+Monitor logs for:
+- Connection failures
+- Database errors
+- Command execution errors
+- Security events
+
+### System Resources
+
+Monitor:
+- Memory usage
+- CPU usage
+- Disk space
+- Network connectivity
+
+## Development
+
+### Adding New Features
+
+1. Follow patterns in `CLAUDE.md`
+2. Create new modules in `modules/`
+3. Update documentation
+4. Add tests
+5. Test thoroughly
+
+### Contributing
+
+1. Review security issues in `issues.txt`
+2. Follow coding conventions
+3. Add comprehensive tests
+4. Update documentation
+5. Consider security implications
+
+## Support
+
+### Documentation
+
+- `README.md` - Project overview
+- `CLAUDE.md` - Development guidelines
+- `TODO.md` - Current project status
+- `issues.txt` - Security audit findings
+- `BACKUP_SYSTEM_INTEGRATION.md` - Backup system guide
+
+### Getting Help
+
+1. Check error logs and console output
+2. Review troubleshooting section
+3. Test with provided test scripts
+4. Check network connectivity
+5. Verify all dependencies are installed
+
+## Next Steps
+
+1. ✅ Complete installation
+2. ✅ Test basic functionality
+3. ✅ Configure IRC settings
+4. ✅ Start the bot
+5. ✅ Access web interface
+6. 📋 Review security issues
+7. 🔧 Configure for production
+8. 🚀 Deploy and monitor
+
+Congratulations! Your PetBot should now be running successfully. 🐾