CLAUDE: Implement voice channel management system
Add comprehensive voice channel system for Discord gameplay with:
## New Features
- `/voice-channel public` - Create public voice channels with random codenames
- `/voice-channel private` - Create private team vs team channels with role permissions
- Automatic cleanup after configurable empty duration (default: 5 minutes)
- Restart-resilient JSON persistence for channel tracking
- Background monitoring service with graceful error handling
## Technical Implementation
- **Voice Commands Package** (`commands/voice/`)
- `channels.py` - Main slash command implementation with modern command groups
- `cleanup_service.py` - Background service for automatic channel deletion
- `tracker.py` - JSON-based persistent channel tracking
- `__init__.py` - Package setup with resilient loading
- **Bot Integration** - Voice cleanup service integrated into bot lifecycle
- **Service Dependencies** - Integration with team, league, and schedule services
- **Permission System** - Team-based Discord role permissions for private channels
## Key Features
- **Public Channels**: Random codenames, open speaking permissions
- **Private Channels**: "{Away} vs {Home}" naming, team role restrictions
- **Auto-cleanup**: Configurable intervals with empty duration thresholds
- **Restart Resilience**: JSON file persistence survives bot restarts
- **Error Handling**: Comprehensive validation and graceful degradation
- **Migration Support**: Deprecated old prefix commands with helpful messages
## Documentation & Testing
- Comprehensive README.md following project patterns
- Full test suite with 15+ test methods covering all scenarios
- Updated CLAUDE.md files with voice command documentation
- Clean IDE diagnostics with proper type safety
## Integration Points
- Team service for user validation and role lookup
- League service for current season/week information
- Schedule service for opponent detection in private channels
- Background task management in bot startup/shutdown
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Cal Corum
parent
1dd930e4b3
commit
8515caaf21
24
bot.py
24
bot.py
@ -115,6 +115,7 @@ class SBABot(commands.Bot):
|
|||||||
from commands.admin import setup_admin
|
from commands.admin import setup_admin
|
||||||
from commands.transactions import setup_transactions
|
from commands.transactions import setup_transactions
|
||||||
from commands.dice import setup_dice
|
from commands.dice import setup_dice
|
||||||
|
from commands.voice import setup_voice
|
||||||
|
|
||||||
# Define command packages to load
|
# Define command packages to load
|
||||||
command_packages = [
|
command_packages = [
|
||||||
@ -125,6 +126,7 @@ class SBABot(commands.Bot):
|
|||||||
("admin", setup_admin),
|
("admin", setup_admin),
|
||||||
("transactions", setup_transactions),
|
("transactions", setup_transactions),
|
||||||
("dice", setup_dice),
|
("dice", setup_dice),
|
||||||
|
("voice", setup_voice),
|
||||||
]
|
]
|
||||||
|
|
||||||
total_successful = 0
|
total_successful = 0
|
||||||
@ -156,13 +158,22 @@ class SBABot(commands.Bot):
|
|||||||
"""Initialize background tasks for the bot."""
|
"""Initialize background tasks for the bot."""
|
||||||
try:
|
try:
|
||||||
self.logger.info("Setting up background tasks...")
|
self.logger.info("Setting up background tasks...")
|
||||||
|
|
||||||
# Initialize custom command cleanup task
|
# Initialize custom command cleanup task
|
||||||
from tasks.custom_command_cleanup import setup_cleanup_task
|
from tasks.custom_command_cleanup import setup_cleanup_task
|
||||||
self.custom_command_cleanup = setup_cleanup_task(self)
|
self.custom_command_cleanup = setup_cleanup_task(self)
|
||||||
|
|
||||||
|
# Initialize voice channel cleanup service
|
||||||
|
from commands.voice.cleanup_service import VoiceChannelCleanupService
|
||||||
|
self.voice_cleanup_service = VoiceChannelCleanupService()
|
||||||
|
|
||||||
|
# Start voice channel monitoring (includes startup verification)
|
||||||
|
import asyncio
|
||||||
|
asyncio.create_task(self.voice_cleanup_service.start_monitoring(self))
|
||||||
|
self.logger.info("✅ Voice channel cleanup service started")
|
||||||
|
|
||||||
self.logger.info("✅ Background tasks initialized successfully")
|
self.logger.info("✅ Background tasks initialized successfully")
|
||||||
|
|
||||||
except Exception as e:
|
except Exception as e:
|
||||||
self.logger.error(f"❌ Failed to initialize background tasks: {e}", exc_info=True)
|
self.logger.error(f"❌ Failed to initialize background tasks: {e}", exc_info=True)
|
||||||
|
|
||||||
@ -300,6 +311,13 @@ class SBABot(commands.Bot):
|
|||||||
self.logger.info("Custom command cleanup task stopped")
|
self.logger.info("Custom command cleanup task stopped")
|
||||||
except Exception as e:
|
except Exception as e:
|
||||||
self.logger.error(f"Error stopping cleanup task: {e}")
|
self.logger.error(f"Error stopping cleanup task: {e}")
|
||||||
|
|
||||||
|
if hasattr(self, 'voice_cleanup_service'):
|
||||||
|
try:
|
||||||
|
self.voice_cleanup_service.stop_monitoring()
|
||||||
|
self.logger.info("Voice channel cleanup service stopped")
|
||||||
|
except Exception as e:
|
||||||
|
self.logger.error(f"Error stopping voice cleanup service: {e}")
|
||||||
|
|
||||||
# Call parent close method
|
# Call parent close method
|
||||||
await super().close()
|
await super().close()
|
||||||
|
|||||||
230
commands/voice/README.md
Normal file
230
commands/voice/README.md
Normal file
@ -0,0 +1,230 @@
|
|||||||
|
# Voice Channel Commands
|
||||||
|
|
||||||
|
This directory contains Discord slash commands for creating and managing voice channels for gameplay.
|
||||||
|
|
||||||
|
## Files
|
||||||
|
|
||||||
|
### `channels.py`
|
||||||
|
- **Commands**:
|
||||||
|
- `/voice-channel public` - Create a public voice channel for gameplay
|
||||||
|
- `/voice-channel private` - Create a private team vs team voice channel
|
||||||
|
- **Description**: Main command implementation with VoiceChannelCommands cog
|
||||||
|
- **Service Dependencies**:
|
||||||
|
- `team_service.get_teams_by_owner()` - Verify user has a team
|
||||||
|
- `league_service.get_current_state()` - Get current season/week info
|
||||||
|
- `schedule_service.get_team_schedule()` - Find opponent for private channels
|
||||||
|
- **Deprecated Commands**:
|
||||||
|
- `!vc`, `!voice`, `!gameplay` → Shows migration message to `/voice-channel public`
|
||||||
|
- `!private` → Shows migration message to `/voice-channel private`
|
||||||
|
|
||||||
|
### `cleanup_service.py`
|
||||||
|
- **Class**: `VoiceChannelCleanupService`
|
||||||
|
- **Description**: Manages automatic cleanup of bot-created voice channels
|
||||||
|
- **Features**:
|
||||||
|
- Restart-resilient channel tracking using JSON persistence
|
||||||
|
- Configurable cleanup intervals and empty thresholds
|
||||||
|
- Background monitoring loop with error recovery
|
||||||
|
- Startup verification to clean stale tracking entries
|
||||||
|
|
||||||
|
### `tracker.py`
|
||||||
|
- **Class**: `VoiceChannelTracker`
|
||||||
|
- **Description**: JSON-based persistent tracking of voice channels
|
||||||
|
- **Features**:
|
||||||
|
- Channel creation and status tracking
|
||||||
|
- Empty duration monitoring with datetime handling
|
||||||
|
- Cleanup candidate identification
|
||||||
|
- Automatic stale entry removal
|
||||||
|
|
||||||
|
### `__init__.py`
|
||||||
|
- **Function**: `setup_voice(bot)`
|
||||||
|
- **Description**: Package initialization with resilient cog loading
|
||||||
|
- **Integration**: Follows established bot architecture patterns
|
||||||
|
|
||||||
|
## Key Features
|
||||||
|
|
||||||
|
### Public Voice Channels (`/voice-channel public`)
|
||||||
|
- **Permissions**: Everyone can connect and speak
|
||||||
|
- **Naming**: Random codename generation (e.g., "Gameplay Phoenix", "Gameplay Thunder")
|
||||||
|
- **Requirements**: User must be on a current team
|
||||||
|
- **Auto-cleanup**: Configurable threshold (default: empty for configured minutes)
|
||||||
|
|
||||||
|
### Private Voice Channels (`/voice-channel private`)
|
||||||
|
- **Permissions**:
|
||||||
|
- Team members can connect and speak (using `team.lname` Discord roles)
|
||||||
|
- Everyone else can connect but only listen
|
||||||
|
- **Naming**: Automatic "{Away} vs {Home}" format based on current week's schedule
|
||||||
|
- **Opponent Detection**: Uses current league week to find scheduled opponent
|
||||||
|
- **Requirements**:
|
||||||
|
- User must be on a current team
|
||||||
|
- Team must have upcoming games in current week
|
||||||
|
- **Role Integration**: Finds Discord roles matching team full names (`team.lname`)
|
||||||
|
|
||||||
|
### Automatic Cleanup System
|
||||||
|
- **Monitoring Interval**: Configurable (default: 60 seconds)
|
||||||
|
- **Empty Threshold**: Configurable (default: 5 minutes empty before deletion)
|
||||||
|
- **Restart Resilience**: JSON file persistence survives bot restarts
|
||||||
|
- **Startup Verification**: Validates tracked channels still exist on bot startup
|
||||||
|
- **Graceful Error Handling**: Continues operation even if individual operations fail
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
### Command Flow
|
||||||
|
1. **Team Verification**: Check user has current team using `team_service`
|
||||||
|
2. **Channel Creation**: Create voice channel with appropriate permissions
|
||||||
|
3. **Tracking Registration**: Add channel to cleanup service tracking
|
||||||
|
4. **User Feedback**: Send success embed with channel details
|
||||||
|
|
||||||
|
### Permission System
|
||||||
|
```python
|
||||||
|
# Public channels - everyone can speak
|
||||||
|
overwrites = {
|
||||||
|
guild.default_role: discord.PermissionOverwrite(speak=True, connect=True)
|
||||||
|
}
|
||||||
|
|
||||||
|
# Private channels - team roles only can speak
|
||||||
|
overwrites = {
|
||||||
|
guild.default_role: discord.PermissionOverwrite(speak=False, connect=True),
|
||||||
|
user_team_role: discord.PermissionOverwrite(speak=True, connect=True),
|
||||||
|
opponent_team_role: discord.PermissionOverwrite(speak=True, connect=True)
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Cleanup Service Integration
|
||||||
|
```python
|
||||||
|
# Bot initialization (bot.py)
|
||||||
|
from commands.voice.cleanup_service import VoiceChannelCleanupService
|
||||||
|
self.voice_cleanup_service = VoiceChannelCleanupService()
|
||||||
|
asyncio.create_task(self.voice_cleanup_service.start_monitoring(self))
|
||||||
|
|
||||||
|
# Channel tracking
|
||||||
|
if hasattr(self.bot, 'voice_cleanup_service'):
|
||||||
|
cleanup_service = self.bot.voice_cleanup_service
|
||||||
|
cleanup_service.tracker.add_channel(channel, channel_type, interaction.user.id)
|
||||||
|
```
|
||||||
|
|
||||||
|
### JSON Data Structure
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"voice_channels": {
|
||||||
|
"123456789": {
|
||||||
|
"channel_id": "123456789",
|
||||||
|
"guild_id": "987654321",
|
||||||
|
"name": "Gameplay Phoenix",
|
||||||
|
"type": "public",
|
||||||
|
"created_at": "2025-01-15T10:30:00",
|
||||||
|
"last_checked": "2025-01-15T10:35:00",
|
||||||
|
"empty_since": "2025-01-15T10:32:00",
|
||||||
|
"creator_id": "111222333"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
### Cleanup Service Settings
|
||||||
|
- **`cleanup_interval`**: How often to check channels (default: 60 seconds)
|
||||||
|
- **`empty_threshold`**: Minutes empty before deletion (default: 5 minutes)
|
||||||
|
- **`data_file`**: JSON persistence file path (default: "data/voice_channels.json")
|
||||||
|
|
||||||
|
### Channel Categories
|
||||||
|
- Channels are created in the "Voice Channels" category if it exists
|
||||||
|
- Falls back to no category if "Voice Channels" category not found
|
||||||
|
|
||||||
|
### Random Codenames
|
||||||
|
```python
|
||||||
|
CODENAMES = [
|
||||||
|
"Phoenix", "Thunder", "Lightning", "Storm", "Blaze", "Frost", "Shadow", "Nova",
|
||||||
|
"Viper", "Falcon", "Wolf", "Eagle", "Tiger", "Shark", "Bear", "Dragon",
|
||||||
|
"Alpha", "Beta", "Gamma", "Delta", "Echo", "Foxtrot", "Golf", "Hotel",
|
||||||
|
"Crimson", "Azure", "Emerald", "Golden", "Silver", "Bronze", "Platinum", "Diamond"
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
### Common Scenarios
|
||||||
|
- **No Team Found**: User-friendly message directing to contact league administrator
|
||||||
|
- **No Upcoming Games**: Informative message about being between series
|
||||||
|
- **Missing Discord Roles**: Warning in embed about teams without speaking permissions
|
||||||
|
- **Permission Errors**: Clear message to contact server administrator
|
||||||
|
- **League Info Unavailable**: Graceful fallback with retry suggestion
|
||||||
|
|
||||||
|
### Service Dependencies
|
||||||
|
- **Graceful Degradation**: Voice channels work without cleanup service
|
||||||
|
- **API Failures**: Comprehensive error handling for external service calls
|
||||||
|
- **Discord Errors**: Specific handling for Forbidden, NotFound, etc.
|
||||||
|
|
||||||
|
## Testing Coverage
|
||||||
|
|
||||||
|
### Test Files
|
||||||
|
- **`tests/test_commands_voice.py`**: Comprehensive test suite covering:
|
||||||
|
- VoiceChannelTracker JSON persistence and datetime handling
|
||||||
|
- VoiceChannelCleanupService restart resilience and monitoring
|
||||||
|
- VoiceChannelCommands slash command functionality
|
||||||
|
- Error scenarios and edge cases
|
||||||
|
- Deprecated command migration messages
|
||||||
|
|
||||||
|
### Mock Objects
|
||||||
|
- Discord guild, channels, roles, and interactions
|
||||||
|
- Team service responses and player data
|
||||||
|
- Schedule service responses and game data
|
||||||
|
- League service current state information
|
||||||
|
|
||||||
|
## Integration Points
|
||||||
|
|
||||||
|
### Bot Integration
|
||||||
|
- **Package Loading**: Integrated into `bot.py` command package loading sequence
|
||||||
|
- **Background Tasks**: Cleanup service started in `_setup_background_tasks()`
|
||||||
|
- **Shutdown Handling**: Cleanup service stopped in `bot.close()`
|
||||||
|
|
||||||
|
### Service Layer
|
||||||
|
- **Team Service**: User team verification and ownership lookup
|
||||||
|
- **League Service**: Current season/week information retrieval
|
||||||
|
- **Schedule Service**: Team schedule and opponent detection
|
||||||
|
|
||||||
|
### Discord Integration
|
||||||
|
- **Application Commands**: Modern slash command interface with command groups
|
||||||
|
- **Permission Overwrites**: Fine-grained voice channel permission control
|
||||||
|
- **Embed Templates**: Consistent styling using established embed patterns
|
||||||
|
- **Error Handling**: Integration with global application command error handler
|
||||||
|
|
||||||
|
## Usage Examples
|
||||||
|
|
||||||
|
### Creating Public Channel
|
||||||
|
```
|
||||||
|
/voice-channel public
|
||||||
|
```
|
||||||
|
**Result**: Creates "Gameplay [Codename]" with public speaking permissions
|
||||||
|
|
||||||
|
### Creating Private Channel
|
||||||
|
```
|
||||||
|
/voice-channel private
|
||||||
|
```
|
||||||
|
**Result**: Creates "[Away] vs [Home]" with team-only speaking permissions
|
||||||
|
|
||||||
|
### Migration from Old Commands
|
||||||
|
```
|
||||||
|
!vc
|
||||||
|
```
|
||||||
|
**Result**: Shows deprecation message suggesting `/voice-channel public`
|
||||||
|
|
||||||
|
## Future Enhancements
|
||||||
|
|
||||||
|
### Potential Features
|
||||||
|
- **Channel Limits**: Per-user or per-team channel creation limits
|
||||||
|
- **Custom Names**: Allow users to specify custom channel names
|
||||||
|
- **Extended Permissions**: More granular permission control options
|
||||||
|
- **Channel Templates**: Predefined setups for different game types
|
||||||
|
- **Integration Webhooks**: Notifications when channels are created/deleted
|
||||||
|
|
||||||
|
### Configuration Options
|
||||||
|
- **Environment Variables**: Make cleanup intervals configurable via env vars
|
||||||
|
- **Per-Guild Settings**: Different settings for different Discord servers
|
||||||
|
- **Role Mapping**: Custom role name patterns for team permissions
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Last Updated**: January 2025
|
||||||
|
**Architecture**: Modern async Discord.py with JSON persistence
|
||||||
|
**Dependencies**: discord.py, team_service, league_service, schedule_service
|
||||||
50
commands/voice/__init__.py
Normal file
50
commands/voice/__init__.py
Normal file
@ -0,0 +1,50 @@
|
|||||||
|
"""
|
||||||
|
Voice Commands Package
|
||||||
|
|
||||||
|
This package contains voice channel management commands for gameplay.
|
||||||
|
"""
|
||||||
|
import logging
|
||||||
|
from discord.ext import commands
|
||||||
|
|
||||||
|
from .channels import VoiceChannelCommands
|
||||||
|
|
||||||
|
logger = logging.getLogger(__name__)
|
||||||
|
|
||||||
|
|
||||||
|
async def setup_voice(bot: commands.Bot):
|
||||||
|
"""
|
||||||
|
Setup all voice command modules.
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
tuple: (successful_count, failed_count, failed_modules)
|
||||||
|
"""
|
||||||
|
# Define all voice command cogs to load
|
||||||
|
voice_cogs = [
|
||||||
|
("VoiceChannelCommands", VoiceChannelCommands),
|
||||||
|
]
|
||||||
|
|
||||||
|
successful = 0
|
||||||
|
failed = 0
|
||||||
|
failed_modules = []
|
||||||
|
|
||||||
|
for cog_name, cog_class in voice_cogs:
|
||||||
|
try:
|
||||||
|
await bot.add_cog(cog_class(bot))
|
||||||
|
logger.info(f"✅ Loaded {cog_name}")
|
||||||
|
successful += 1
|
||||||
|
except Exception as e:
|
||||||
|
logger.error(f"❌ Failed to load {cog_name}: {e}", exc_info=True)
|
||||||
|
failed += 1
|
||||||
|
failed_modules.append(cog_name)
|
||||||
|
|
||||||
|
# Log summary
|
||||||
|
if failed == 0:
|
||||||
|
logger.info(f"🎉 All {successful} voice command modules loaded successfully")
|
||||||
|
else:
|
||||||
|
logger.warning(f"⚠️ Voice commands loaded with issues: {successful} successful, {failed} failed")
|
||||||
|
|
||||||
|
return successful, failed, failed_modules
|
||||||
|
|
||||||
|
|
||||||
|
# Export the setup function for easy importing
|
||||||
|
__all__ = ['setup_voice', 'VoiceChannelCommands']
|
||||||
348
commands/voice/channels.py
Normal file
348
commands/voice/channels.py
Normal file
@ -0,0 +1,348 @@
|
|||||||
|
"""
|
||||||
|
Voice Channel Commands
|
||||||
|
|
||||||
|
Implements slash commands for creating and managing voice channels for gameplay.
|
||||||
|
"""
|
||||||
|
import logging
|
||||||
|
import random
|
||||||
|
from typing import Optional
|
||||||
|
|
||||||
|
import discord
|
||||||
|
from discord.ext import commands
|
||||||
|
|
||||||
|
from services.team_service import team_service
|
||||||
|
from services.schedule_service import ScheduleService
|
||||||
|
from services.league_service import league_service
|
||||||
|
from utils.logging import get_contextual_logger
|
||||||
|
from utils.decorators import logged_command
|
||||||
|
from constants import SBA_CURRENT_SEASON
|
||||||
|
from views.embeds import EmbedTemplate
|
||||||
|
|
||||||
|
logger = logging.getLogger(f'{__name__}.VoiceChannelCommands')
|
||||||
|
|
||||||
|
# Random codenames for public channels
|
||||||
|
CODENAMES = [
|
||||||
|
"Phoenix", "Thunder", "Lightning", "Storm", "Blaze", "Frost", "Shadow", "Nova",
|
||||||
|
"Viper", "Falcon", "Wolf", "Eagle", "Tiger", "Shark", "Bear", "Dragon",
|
||||||
|
"Alpha", "Beta", "Gamma", "Delta", "Echo", "Foxtrot", "Golf", "Hotel",
|
||||||
|
"Crimson", "Azure", "Emerald", "Golden", "Silver", "Bronze", "Platinum", "Diamond"
|
||||||
|
]
|
||||||
|
|
||||||
|
|
||||||
|
def random_codename() -> str:
|
||||||
|
"""Generate a random codename for public channels."""
|
||||||
|
return random.choice(CODENAMES)
|
||||||
|
|
||||||
|
|
||||||
|
class VoiceChannelCommands(commands.Cog):
|
||||||
|
"""Voice channel management commands for gameplay."""
|
||||||
|
|
||||||
|
def __init__(self, bot: commands.Bot):
|
||||||
|
self.bot = bot
|
||||||
|
self.logger = get_contextual_logger(f'{__name__}.VoiceChannelCommands')
|
||||||
|
self.schedule_service = ScheduleService()
|
||||||
|
|
||||||
|
# Modern slash command group
|
||||||
|
voice_group = discord.app_commands.Group(
|
||||||
|
name="voice-channel",
|
||||||
|
description="Create voice channels for gameplay"
|
||||||
|
)
|
||||||
|
|
||||||
|
async def _get_user_team(self, user_id: int, season: Optional[int] = None):
|
||||||
|
"""
|
||||||
|
Get the user's current team.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
user_id: Discord user ID
|
||||||
|
season: Season to check (defaults to current)
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
Team object or None if not found
|
||||||
|
"""
|
||||||
|
season = season or SBA_CURRENT_SEASON
|
||||||
|
teams = await team_service.get_teams_by_owner(user_id, season)
|
||||||
|
return teams[0] if teams else None
|
||||||
|
|
||||||
|
async def _create_tracked_channel(
|
||||||
|
self,
|
||||||
|
interaction: discord.Interaction,
|
||||||
|
channel_name: str,
|
||||||
|
channel_type: str,
|
||||||
|
overwrites: dict
|
||||||
|
) -> discord.VoiceChannel:
|
||||||
|
"""
|
||||||
|
Create a voice channel and add it to tracking.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
interaction: Discord interaction
|
||||||
|
channel_name: Name for the voice channel
|
||||||
|
channel_type: Type of channel ('public' or 'private')
|
||||||
|
overwrites: Permission overwrites for the channel
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
Created Discord voice channel
|
||||||
|
"""
|
||||||
|
guild = interaction.guild
|
||||||
|
voice_category = discord.utils.get(guild.categories, name="Voice Channels")
|
||||||
|
|
||||||
|
# Create the voice channel
|
||||||
|
channel = await guild.create_voice_channel(
|
||||||
|
name=channel_name,
|
||||||
|
overwrites=overwrites,
|
||||||
|
category=voice_category
|
||||||
|
)
|
||||||
|
|
||||||
|
# Add to cleanup service tracking
|
||||||
|
if hasattr(self.bot, 'voice_cleanup_service'):
|
||||||
|
cleanup_service = self.bot.voice_cleanup_service # type: ignore[attr-defined]
|
||||||
|
cleanup_service.tracker.add_channel(channel, channel_type, interaction.user.id)
|
||||||
|
else:
|
||||||
|
self.logger.warning("Voice cleanup service not available, channel won't be tracked")
|
||||||
|
|
||||||
|
return channel
|
||||||
|
|
||||||
|
@voice_group.command(name="public", description="Create a public voice channel")
|
||||||
|
@logged_command("/voice-channel public")
|
||||||
|
async def create_public_channel(self, interaction: discord.Interaction):
|
||||||
|
"""Create a public voice channel for gameplay."""
|
||||||
|
await interaction.response.defer()
|
||||||
|
|
||||||
|
# Verify user has a team
|
||||||
|
user_team = await self._get_user_team(interaction.user.id)
|
||||||
|
if not user_team:
|
||||||
|
embed = EmbedTemplate.error(
|
||||||
|
title="No Team Found",
|
||||||
|
description="❌ You must be on a team to create voice channels.\n\n"
|
||||||
|
"Contact a league administrator if you believe this is an error."
|
||||||
|
)
|
||||||
|
await interaction.followup.send(embed=embed, ephemeral=True)
|
||||||
|
return
|
||||||
|
|
||||||
|
# Create channel with public permissions
|
||||||
|
overwrites = {
|
||||||
|
interaction.guild.default_role: discord.PermissionOverwrite(speak=True, connect=True)
|
||||||
|
}
|
||||||
|
|
||||||
|
channel_name = f"Gameplay {random_codename()}"
|
||||||
|
|
||||||
|
try:
|
||||||
|
channel = await self._create_tracked_channel(
|
||||||
|
interaction, channel_name, "public", overwrites
|
||||||
|
)
|
||||||
|
|
||||||
|
# Get actual cleanup time from service
|
||||||
|
cleanup_minutes = getattr(self.bot, 'voice_cleanup_service', None)
|
||||||
|
cleanup_time = cleanup_minutes.empty_threshold if cleanup_minutes else 15
|
||||||
|
|
||||||
|
embed = EmbedTemplate.success(
|
||||||
|
title="Voice Channel Created",
|
||||||
|
description=f"✅ Created public voice channel {channel.mention}\n\n"
|
||||||
|
f"**Channel:** {channel.name}\n"
|
||||||
|
f"**Type:** Public (everyone can speak)\n"
|
||||||
|
f"**Auto-cleanup:** {cleanup_time} minutes after becoming empty"
|
||||||
|
)
|
||||||
|
|
||||||
|
await interaction.followup.send(embed=embed)
|
||||||
|
|
||||||
|
except discord.Forbidden:
|
||||||
|
embed = EmbedTemplate.error(
|
||||||
|
title="Permission Error",
|
||||||
|
description="❌ I don't have permission to create voice channels.\n\n"
|
||||||
|
"Please contact a server administrator."
|
||||||
|
)
|
||||||
|
await interaction.followup.send(embed=embed, ephemeral=True)
|
||||||
|
except Exception as e:
|
||||||
|
self.logger.error(f"Error creating public voice channel: {e}")
|
||||||
|
embed = EmbedTemplate.error(
|
||||||
|
title="Creation Failed",
|
||||||
|
description="❌ An error occurred while creating the voice channel.\n\n"
|
||||||
|
"Please try again or contact support."
|
||||||
|
)
|
||||||
|
await interaction.followup.send(embed=embed, ephemeral=True)
|
||||||
|
|
||||||
|
@voice_group.command(name="private", description="Create a private team vs team voice channel")
|
||||||
|
@logged_command("/voice-channel private")
|
||||||
|
async def create_private_channel(self, interaction: discord.Interaction):
|
||||||
|
"""Create a private voice channel for team matchup."""
|
||||||
|
await interaction.response.defer()
|
||||||
|
|
||||||
|
# Verify user has a team
|
||||||
|
user_team = await self._get_user_team(interaction.user.id)
|
||||||
|
if not user_team:
|
||||||
|
embed = EmbedTemplate.error(
|
||||||
|
title="No Team Found",
|
||||||
|
description="❌ You must be on a team to create voice channels.\n\n"
|
||||||
|
"Contact a league administrator if you believe this is an error."
|
||||||
|
)
|
||||||
|
await interaction.followup.send(embed=embed, ephemeral=True)
|
||||||
|
return
|
||||||
|
|
||||||
|
# Get current league info
|
||||||
|
try:
|
||||||
|
current_info = await league_service.get_current_state()
|
||||||
|
if current_info is None:
|
||||||
|
embed = EmbedTemplate.error(
|
||||||
|
title="League Info Error",
|
||||||
|
description="❌ Unable to retrieve current league information.\n\n"
|
||||||
|
"Please try again later."
|
||||||
|
)
|
||||||
|
await interaction.followup.send(embed=embed, ephemeral=True)
|
||||||
|
return
|
||||||
|
|
||||||
|
current_season = current_info.season
|
||||||
|
current_week = current_info.week
|
||||||
|
except Exception as e:
|
||||||
|
self.logger.error(f"Error getting current league info: {e}")
|
||||||
|
embed = EmbedTemplate.error(
|
||||||
|
title="League Info Error",
|
||||||
|
description="❌ Unable to retrieve current league information.\n\n"
|
||||||
|
"Please try again later."
|
||||||
|
)
|
||||||
|
await interaction.followup.send(embed=embed, ephemeral=True)
|
||||||
|
return
|
||||||
|
|
||||||
|
# Find opponent from current week's schedule
|
||||||
|
try:
|
||||||
|
team_games = await self.schedule_service.get_team_schedule(
|
||||||
|
current_season, user_team.abbrev, weeks=1
|
||||||
|
)
|
||||||
|
|
||||||
|
current_week_games = [g for g in team_games
|
||||||
|
if g.week == current_week and not g.is_completed]
|
||||||
|
|
||||||
|
if not current_week_games:
|
||||||
|
embed = EmbedTemplate.warning(
|
||||||
|
title="No Games Found",
|
||||||
|
description=f"❌ No upcoming games found for {user_team.abbrev} in week {current_week}.\n\n"
|
||||||
|
f"You may be between series or all games for this week are complete."
|
||||||
|
)
|
||||||
|
await interaction.followup.send(embed=embed, ephemeral=True)
|
||||||
|
return
|
||||||
|
|
||||||
|
game = current_week_games[0] # Use first upcoming game
|
||||||
|
opponent_team = game.away_team if game.home_team.id == user_team.id else game.home_team
|
||||||
|
|
||||||
|
except Exception as e:
|
||||||
|
self.logger.error(f"Error getting team schedule: {e}")
|
||||||
|
embed = EmbedTemplate.error(
|
||||||
|
title="Schedule Error",
|
||||||
|
description="❌ Unable to retrieve your team's schedule.\n\n"
|
||||||
|
"Please try again later."
|
||||||
|
)
|
||||||
|
await interaction.followup.send(embed=embed, ephemeral=True)
|
||||||
|
return
|
||||||
|
|
||||||
|
# Setup permissions for team roles
|
||||||
|
user_team_role = discord.utils.get(interaction.guild.roles, name=user_team.lname)
|
||||||
|
opponent_team_role = discord.utils.get(interaction.guild.roles, name=opponent_team.lname)
|
||||||
|
|
||||||
|
# Start with default permissions (everyone can connect but not speak)
|
||||||
|
overwrites = {
|
||||||
|
interaction.guild.default_role: discord.PermissionOverwrite(speak=False, connect=True)
|
||||||
|
}
|
||||||
|
|
||||||
|
# Add speaking permissions for team roles
|
||||||
|
team_roles_found = []
|
||||||
|
if user_team_role:
|
||||||
|
overwrites[user_team_role] = discord.PermissionOverwrite(speak=True, connect=True)
|
||||||
|
team_roles_found.append(user_team.lname)
|
||||||
|
|
||||||
|
if opponent_team_role:
|
||||||
|
overwrites[opponent_team_role] = discord.PermissionOverwrite(speak=True, connect=True)
|
||||||
|
team_roles_found.append(opponent_team.lname)
|
||||||
|
|
||||||
|
# Create private channel with team names
|
||||||
|
away_name = game.away_team.sname
|
||||||
|
home_name = game.home_team.sname
|
||||||
|
channel_name = f"{away_name} vs {home_name}"
|
||||||
|
|
||||||
|
try:
|
||||||
|
channel = await self._create_tracked_channel(
|
||||||
|
interaction, channel_name, "private", overwrites
|
||||||
|
)
|
||||||
|
|
||||||
|
# Get actual cleanup time from service
|
||||||
|
cleanup_minutes = getattr(self.bot, 'voice_cleanup_service', None)
|
||||||
|
cleanup_time = cleanup_minutes.empty_threshold if cleanup_minutes else 15
|
||||||
|
|
||||||
|
embed = EmbedTemplate.success(
|
||||||
|
title="Private Voice Channel Created",
|
||||||
|
description=f"✅ Created private voice channel {channel.mention}\n\n"
|
||||||
|
f"**Matchup:** {away_name} vs {home_name}\n"
|
||||||
|
f"**Type:** Private (team members only can speak)\n"
|
||||||
|
f"**Auto-cleanup:** {cleanup_time} minutes after becoming empty"
|
||||||
|
)
|
||||||
|
|
||||||
|
embed.add_field(
|
||||||
|
name="Speaking Permissions",
|
||||||
|
value=f"🎤 **{user_team.abbrev}** - {user_team.lname}\n"
|
||||||
|
f"🎤 **{opponent_team.abbrev}** - {opponent_team.lname}\n"
|
||||||
|
f"👂 Everyone else can listen",
|
||||||
|
inline=False
|
||||||
|
)
|
||||||
|
|
||||||
|
if len(team_roles_found) < 2:
|
||||||
|
missing_roles = []
|
||||||
|
if not user_team_role:
|
||||||
|
missing_roles.append(user_team.lname)
|
||||||
|
if not opponent_team_role:
|
||||||
|
missing_roles.append(opponent_team.lname)
|
||||||
|
|
||||||
|
embed.add_field(
|
||||||
|
name="⚠️ Missing Roles",
|
||||||
|
value=f"Could not find Discord roles for: {', '.join(missing_roles)}\n"
|
||||||
|
f"These teams may not have speaking permissions.",
|
||||||
|
inline=False
|
||||||
|
)
|
||||||
|
|
||||||
|
await interaction.followup.send(embed=embed)
|
||||||
|
|
||||||
|
except discord.Forbidden:
|
||||||
|
embed = EmbedTemplate.error(
|
||||||
|
title="Permission Error",
|
||||||
|
description="❌ I don't have permission to create voice channels.\n\n"
|
||||||
|
"Please contact a server administrator."
|
||||||
|
)
|
||||||
|
await interaction.followup.send(embed=embed, ephemeral=True)
|
||||||
|
except Exception as e:
|
||||||
|
self.logger.error(f"Error creating private voice channel: {e}")
|
||||||
|
embed = EmbedTemplate.error(
|
||||||
|
title="Creation Failed",
|
||||||
|
description="❌ An error occurred while creating the voice channel.\n\n"
|
||||||
|
"Please try again or contact support."
|
||||||
|
)
|
||||||
|
await interaction.followup.send(embed=embed, ephemeral=True)
|
||||||
|
|
||||||
|
# Deprecated prefix commands with migration messages
|
||||||
|
@commands.command(name="vc", aliases=["voice", "gameplay"])
|
||||||
|
async def deprecated_public_voice(self, ctx: commands.Context):
|
||||||
|
"""Deprecated command - redirect to new slash command."""
|
||||||
|
embed = EmbedTemplate.info(
|
||||||
|
title="📢 Command Deprecated",
|
||||||
|
description=(
|
||||||
|
"The `!vc` command has been deprecated.\n\n"
|
||||||
|
"**Please use:** `/voice-channel public` for your voice channel needs.\n\n"
|
||||||
|
"The new slash commands provide better functionality and organization!"
|
||||||
|
)
|
||||||
|
)
|
||||||
|
embed.set_footer(text="💡 Tip: Type /voice-channel and see the available options!")
|
||||||
|
await ctx.send(embed=embed)
|
||||||
|
|
||||||
|
@commands.command(name="private")
|
||||||
|
async def deprecated_private_voice(self, ctx: commands.Context):
|
||||||
|
"""Deprecated command - redirect to new slash command."""
|
||||||
|
embed = EmbedTemplate.info(
|
||||||
|
title="📢 Command Deprecated",
|
||||||
|
description=(
|
||||||
|
"The `!private` command has been deprecated.\n\n"
|
||||||
|
"**Please use:** `/voice-channel private` for your private team channel needs.\n\n"
|
||||||
|
"The new slash commands provide better functionality and organization!"
|
||||||
|
)
|
||||||
|
)
|
||||||
|
embed.set_footer(text="💡 Tip: Type /voice-channel and see the available options!")
|
||||||
|
await ctx.send(embed=embed)
|
||||||
|
|
||||||
|
|
||||||
|
async def setup(bot: commands.Bot):
|
||||||
|
"""Load the voice channel commands cog."""
|
||||||
|
await bot.add_cog(VoiceChannelCommands(bot))
|
||||||
275
commands/voice/cleanup_service.py
Normal file
275
commands/voice/cleanup_service.py
Normal file
@ -0,0 +1,275 @@
|
|||||||
|
"""
|
||||||
|
Voice Channel Cleanup Service
|
||||||
|
|
||||||
|
Provides automatic cleanup of empty voice channels with restart resilience.
|
||||||
|
"""
|
||||||
|
import asyncio
|
||||||
|
import logging
|
||||||
|
|
||||||
|
import discord
|
||||||
|
from discord.ext import commands
|
||||||
|
|
||||||
|
from .tracker import VoiceChannelTracker
|
||||||
|
|
||||||
|
logger = logging.getLogger(f'{__name__}.VoiceChannelCleanupService')
|
||||||
|
|
||||||
|
|
||||||
|
class VoiceChannelCleanupService:
|
||||||
|
"""
|
||||||
|
Manages automatic cleanup of bot-created voice channels.
|
||||||
|
|
||||||
|
Features:
|
||||||
|
- Restart-resilient channel tracking
|
||||||
|
- Automatic empty channel cleanup
|
||||||
|
- Configurable cleanup intervals and thresholds
|
||||||
|
- Stale entry removal and recovery
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(self, data_file: str = "data/voice_channels.json"):
|
||||||
|
"""
|
||||||
|
Initialize the cleanup service.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
data_file: Path to the JSON data file for persistence
|
||||||
|
"""
|
||||||
|
self.tracker = VoiceChannelTracker(data_file)
|
||||||
|
self.cleanup_interval = 60 # 5 minutes check interval
|
||||||
|
self.empty_threshold = 5 # Delete after 15 minutes empty
|
||||||
|
self._running = False
|
||||||
|
|
||||||
|
async def start_monitoring(self, bot: commands.Bot) -> None:
|
||||||
|
"""
|
||||||
|
Start the cleanup monitoring loop.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
bot: Discord bot instance
|
||||||
|
"""
|
||||||
|
if self._running:
|
||||||
|
logger.warning("Cleanup service is already running")
|
||||||
|
return
|
||||||
|
|
||||||
|
self._running = True
|
||||||
|
logger.info("Starting voice channel cleanup service")
|
||||||
|
|
||||||
|
# On startup, verify tracked channels still exist and clean up stale entries
|
||||||
|
await self.verify_tracked_channels(bot)
|
||||||
|
|
||||||
|
# Start the monitoring loop
|
||||||
|
while self._running:
|
||||||
|
try:
|
||||||
|
await self.cleanup_cycle(bot)
|
||||||
|
await asyncio.sleep(self.cleanup_interval)
|
||||||
|
except Exception as e:
|
||||||
|
logger.error(f"Cleanup cycle error: {e}", exc_info=True)
|
||||||
|
# Use shorter retry interval on errors
|
||||||
|
await asyncio.sleep(60)
|
||||||
|
|
||||||
|
logger.info("Voice channel cleanup service stopped")
|
||||||
|
|
||||||
|
def stop_monitoring(self) -> None:
|
||||||
|
"""Stop the cleanup monitoring loop."""
|
||||||
|
self._running = False
|
||||||
|
logger.info("Stopping voice channel cleanup service")
|
||||||
|
|
||||||
|
async def verify_tracked_channels(self, bot: commands.Bot) -> None:
|
||||||
|
"""
|
||||||
|
Verify tracked channels still exist and clean up stale entries.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
bot: Discord bot instance
|
||||||
|
"""
|
||||||
|
logger.info("Verifying tracked voice channels on startup")
|
||||||
|
|
||||||
|
valid_channel_ids = []
|
||||||
|
channels_to_remove = []
|
||||||
|
|
||||||
|
for channel_data in self.tracker.get_all_tracked_channels():
|
||||||
|
try:
|
||||||
|
guild_id = int(channel_data["guild_id"])
|
||||||
|
channel_id = int(channel_data["channel_id"])
|
||||||
|
|
||||||
|
guild = bot.get_guild(guild_id)
|
||||||
|
if not guild:
|
||||||
|
logger.warning(f"Guild {guild_id} not found, removing channel {channel_data['name']}")
|
||||||
|
channels_to_remove.append(channel_id)
|
||||||
|
continue
|
||||||
|
|
||||||
|
channel = guild.get_channel(channel_id)
|
||||||
|
if not channel:
|
||||||
|
logger.warning(f"Channel {channel_data['name']} (ID: {channel_id}) no longer exists")
|
||||||
|
channels_to_remove.append(channel_id)
|
||||||
|
continue
|
||||||
|
|
||||||
|
# Channel exists and is valid
|
||||||
|
valid_channel_ids.append(channel_id)
|
||||||
|
|
||||||
|
except (ValueError, TypeError, KeyError) as e:
|
||||||
|
logger.warning(f"Invalid channel data: {e}, removing entry")
|
||||||
|
if "channel_id" in channel_data:
|
||||||
|
try:
|
||||||
|
channels_to_remove.append(int(channel_data["channel_id"]))
|
||||||
|
except (ValueError, TypeError):
|
||||||
|
pass
|
||||||
|
|
||||||
|
# Remove stale entries
|
||||||
|
for channel_id in channels_to_remove:
|
||||||
|
self.tracker.remove_channel(channel_id)
|
||||||
|
|
||||||
|
# Also clean up any additional stale entries
|
||||||
|
stale_removed = self.tracker.cleanup_stale_entries(valid_channel_ids)
|
||||||
|
total_removed = len(channels_to_remove) + stale_removed
|
||||||
|
|
||||||
|
if total_removed > 0:
|
||||||
|
logger.info(f"Cleaned up {total_removed} stale channel tracking entries")
|
||||||
|
|
||||||
|
logger.info(f"Verified {len(valid_channel_ids)} valid tracked channels")
|
||||||
|
|
||||||
|
async def cleanup_cycle(self, bot: commands.Bot) -> None:
|
||||||
|
"""
|
||||||
|
Check all tracked channels and cleanup empty ones.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
bot: Discord bot instance
|
||||||
|
"""
|
||||||
|
logger.debug("Starting cleanup cycle")
|
||||||
|
|
||||||
|
# Update status of all tracked channels
|
||||||
|
await self.update_all_channel_statuses(bot)
|
||||||
|
|
||||||
|
# Get channels ready for cleanup
|
||||||
|
channels_for_cleanup = self.tracker.get_channels_for_cleanup(self.empty_threshold)
|
||||||
|
|
||||||
|
if channels_for_cleanup:
|
||||||
|
logger.info(f"Found {len(channels_for_cleanup)} channels ready for cleanup")
|
||||||
|
|
||||||
|
# Delete empty channels
|
||||||
|
for channel_data in channels_for_cleanup:
|
||||||
|
await self.cleanup_channel(bot, channel_data)
|
||||||
|
|
||||||
|
async def update_all_channel_statuses(self, bot: commands.Bot) -> None:
|
||||||
|
"""
|
||||||
|
Update the empty status of all tracked channels.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
bot: Discord bot instance
|
||||||
|
"""
|
||||||
|
for channel_data in self.tracker.get_all_tracked_channels():
|
||||||
|
await self.check_channel_status(bot, channel_data)
|
||||||
|
|
||||||
|
async def check_channel_status(self, bot: commands.Bot, channel_data: dict) -> None:
|
||||||
|
"""
|
||||||
|
Check if a channel is empty and update tracking.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
bot: Discord bot instance
|
||||||
|
channel_data: Channel tracking data
|
||||||
|
"""
|
||||||
|
try:
|
||||||
|
guild_id = int(channel_data["guild_id"])
|
||||||
|
channel_id = int(channel_data["channel_id"])
|
||||||
|
|
||||||
|
guild = bot.get_guild(guild_id)
|
||||||
|
if not guild:
|
||||||
|
logger.debug(f"Guild {guild_id} not found for channel {channel_data['name']}")
|
||||||
|
return
|
||||||
|
|
||||||
|
channel = guild.get_channel(channel_id)
|
||||||
|
if not channel:
|
||||||
|
logger.debug(f"Channel {channel_data['name']} no longer exists, will be cleaned up")
|
||||||
|
self.tracker.remove_channel(channel_id)
|
||||||
|
return
|
||||||
|
|
||||||
|
# Ensure it's a voice channel before checking members
|
||||||
|
if not isinstance(channel, discord.VoiceChannel):
|
||||||
|
logger.warning(f"Channel {channel_data['name']} is not a voice channel, removing from tracking")
|
||||||
|
self.tracker.remove_channel(channel_id)
|
||||||
|
return
|
||||||
|
|
||||||
|
# Check if channel is empty
|
||||||
|
is_empty = len(channel.members) == 0
|
||||||
|
self.tracker.update_channel_status(channel_id, is_empty)
|
||||||
|
|
||||||
|
logger.debug(f"Channel {channel_data['name']}: {'empty' if is_empty else 'occupied'} "
|
||||||
|
f"({len(channel.members)} members)")
|
||||||
|
|
||||||
|
except Exception as e:
|
||||||
|
logger.error(f"Error checking channel status for {channel_data.get('name', 'unknown')}: {e}")
|
||||||
|
|
||||||
|
async def cleanup_channel(self, bot: commands.Bot, channel_data: dict) -> None:
|
||||||
|
"""
|
||||||
|
Delete an empty channel and remove from tracking.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
bot: Discord bot instance
|
||||||
|
channel_data: Channel tracking data
|
||||||
|
"""
|
||||||
|
try:
|
||||||
|
guild_id = int(channel_data["guild_id"])
|
||||||
|
channel_id = int(channel_data["channel_id"])
|
||||||
|
channel_name = channel_data["name"]
|
||||||
|
|
||||||
|
guild = bot.get_guild(guild_id)
|
||||||
|
if not guild:
|
||||||
|
logger.info(f"Guild {guild_id} not found, removing tracking for {channel_name}")
|
||||||
|
self.tracker.remove_channel(channel_id)
|
||||||
|
return
|
||||||
|
|
||||||
|
channel = guild.get_channel(channel_id)
|
||||||
|
if not channel:
|
||||||
|
logger.info(f"Channel {channel_name} already deleted, removing from tracking")
|
||||||
|
self.tracker.remove_channel(channel_id)
|
||||||
|
return
|
||||||
|
|
||||||
|
# Ensure it's a voice channel before checking members
|
||||||
|
if not isinstance(channel, discord.VoiceChannel):
|
||||||
|
logger.warning(f"Channel {channel_name} is not a voice channel, removing from tracking")
|
||||||
|
self.tracker.remove_channel(channel_id)
|
||||||
|
return
|
||||||
|
|
||||||
|
# Final check: make sure channel is still empty before deleting
|
||||||
|
if len(channel.members) > 0:
|
||||||
|
logger.info(f"Channel {channel_name} is no longer empty, skipping cleanup")
|
||||||
|
self.tracker.update_channel_status(channel_id, False)
|
||||||
|
return
|
||||||
|
|
||||||
|
# Delete the channel
|
||||||
|
await channel.delete(reason="Automatic cleanup - empty for 15+ minutes")
|
||||||
|
self.tracker.remove_channel(channel_id)
|
||||||
|
|
||||||
|
logger.info(f"✅ Cleaned up empty voice channel: {channel_name} (ID: {channel_id})")
|
||||||
|
|
||||||
|
except discord.NotFound:
|
||||||
|
# Channel was already deleted
|
||||||
|
logger.info(f"Channel {channel_data.get('name', 'unknown')} was already deleted")
|
||||||
|
self.tracker.remove_channel(int(channel_data["channel_id"]))
|
||||||
|
except discord.Forbidden:
|
||||||
|
logger.error(f"Missing permissions to delete channel {channel_data.get('name', 'unknown')}")
|
||||||
|
except Exception as e:
|
||||||
|
logger.error(f"Error cleaning up channel {channel_data.get('name', 'unknown')}: {e}")
|
||||||
|
|
||||||
|
def get_tracker(self) -> VoiceChannelTracker:
|
||||||
|
"""
|
||||||
|
Get the voice channel tracker instance.
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
VoiceChannelTracker instance
|
||||||
|
"""
|
||||||
|
return self.tracker
|
||||||
|
|
||||||
|
def get_stats(self) -> dict:
|
||||||
|
"""
|
||||||
|
Get cleanup service statistics.
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
Dictionary with service statistics
|
||||||
|
"""
|
||||||
|
all_channels = self.tracker.get_all_tracked_channels()
|
||||||
|
empty_channels = [ch for ch in all_channels if ch.get("empty_since")]
|
||||||
|
|
||||||
|
return {
|
||||||
|
"running": self._running,
|
||||||
|
"total_tracked": len(all_channels),
|
||||||
|
"empty_channels": len(empty_channels),
|
||||||
|
"cleanup_interval": self.cleanup_interval,
|
||||||
|
"empty_threshold": self.empty_threshold
|
||||||
|
}
|
||||||
222
commands/voice/tracker.py
Normal file
222
commands/voice/tracker.py
Normal file
@ -0,0 +1,222 @@
|
|||||||
|
"""
|
||||||
|
Voice Channel Tracker
|
||||||
|
|
||||||
|
Provides persistent tracking of bot-created voice channels using JSON file storage.
|
||||||
|
"""
|
||||||
|
import json
|
||||||
|
import logging
|
||||||
|
from datetime import datetime, timedelta
|
||||||
|
from pathlib import Path
|
||||||
|
from typing import Dict, List, Optional, Any
|
||||||
|
|
||||||
|
import discord
|
||||||
|
|
||||||
|
logger = logging.getLogger(f'{__name__}.VoiceChannelTracker')
|
||||||
|
|
||||||
|
|
||||||
|
class VoiceChannelTracker:
|
||||||
|
"""
|
||||||
|
Tracks bot-created voice channels with JSON file persistence.
|
||||||
|
|
||||||
|
Features:
|
||||||
|
- Persistent storage across bot restarts
|
||||||
|
- Channel creation and status tracking
|
||||||
|
- Cleanup candidate identification
|
||||||
|
- Automatic stale entry removal
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(self, data_file: str = "data/voice_channels.json"):
|
||||||
|
"""
|
||||||
|
Initialize the voice channel tracker.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
data_file: Path to the JSON data file
|
||||||
|
"""
|
||||||
|
self.data_file = Path(data_file)
|
||||||
|
self.data_file.parent.mkdir(exist_ok=True)
|
||||||
|
self._data: Dict[str, Any] = {}
|
||||||
|
self.load_data()
|
||||||
|
|
||||||
|
def load_data(self) -> None:
|
||||||
|
"""Load channel data from JSON file."""
|
||||||
|
try:
|
||||||
|
if self.data_file.exists():
|
||||||
|
with open(self.data_file, 'r') as f:
|
||||||
|
self._data = json.load(f)
|
||||||
|
logger.debug(f"Loaded {len(self._data.get('voice_channels', {}))} tracked channels")
|
||||||
|
else:
|
||||||
|
self._data = {"voice_channels": {}}
|
||||||
|
logger.info("No existing voice channel data found, starting fresh")
|
||||||
|
except Exception as e:
|
||||||
|
logger.error(f"Failed to load voice channel data: {e}")
|
||||||
|
self._data = {"voice_channels": {}}
|
||||||
|
|
||||||
|
def save_data(self) -> None:
|
||||||
|
"""Save channel data to JSON file."""
|
||||||
|
try:
|
||||||
|
with open(self.data_file, 'w') as f:
|
||||||
|
json.dump(self._data, f, indent=2, default=str)
|
||||||
|
logger.debug("Voice channel data saved successfully")
|
||||||
|
except Exception as e:
|
||||||
|
logger.error(f"Failed to save voice channel data: {e}")
|
||||||
|
|
||||||
|
def add_channel(
|
||||||
|
self,
|
||||||
|
channel: discord.VoiceChannel,
|
||||||
|
channel_type: str,
|
||||||
|
creator_id: int
|
||||||
|
) -> None:
|
||||||
|
"""
|
||||||
|
Add a new channel to tracking.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
channel: Discord voice channel object
|
||||||
|
channel_type: Type of channel ('public' or 'private')
|
||||||
|
creator_id: Discord user ID who created the channel
|
||||||
|
"""
|
||||||
|
self._data.setdefault("voice_channels", {})[str(channel.id)] = {
|
||||||
|
"channel_id": str(channel.id),
|
||||||
|
"guild_id": str(channel.guild.id),
|
||||||
|
"name": channel.name,
|
||||||
|
"type": channel_type,
|
||||||
|
"created_at": datetime.utcnow().isoformat(),
|
||||||
|
"last_checked": datetime.utcnow().isoformat(),
|
||||||
|
"empty_since": None,
|
||||||
|
"creator_id": str(creator_id)
|
||||||
|
}
|
||||||
|
self.save_data()
|
||||||
|
logger.info(f"Added channel to tracking: {channel.name} (ID: {channel.id})")
|
||||||
|
|
||||||
|
def update_channel_status(self, channel_id: int, is_empty: bool) -> None:
|
||||||
|
"""
|
||||||
|
Update channel empty status.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
channel_id: Discord channel ID
|
||||||
|
is_empty: Whether the channel is currently empty
|
||||||
|
"""
|
||||||
|
channels = self._data.get("voice_channels", {})
|
||||||
|
channel_key = str(channel_id)
|
||||||
|
|
||||||
|
if channel_key in channels:
|
||||||
|
channel_data = channels[channel_key]
|
||||||
|
channel_data["last_checked"] = datetime.utcnow().isoformat()
|
||||||
|
|
||||||
|
if is_empty and channel_data["empty_since"] is None:
|
||||||
|
# Channel just became empty
|
||||||
|
channel_data["empty_since"] = datetime.utcnow().isoformat()
|
||||||
|
logger.debug(f"Channel {channel_data['name']} became empty")
|
||||||
|
elif not is_empty and channel_data["empty_since"] is not None:
|
||||||
|
# Channel is no longer empty
|
||||||
|
channel_data["empty_since"] = None
|
||||||
|
logger.debug(f"Channel {channel_data['name']} is no longer empty")
|
||||||
|
|
||||||
|
self.save_data()
|
||||||
|
|
||||||
|
def remove_channel(self, channel_id: int) -> None:
|
||||||
|
"""
|
||||||
|
Remove channel from tracking.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
channel_id: Discord channel ID
|
||||||
|
"""
|
||||||
|
channels = self._data.get("voice_channels", {})
|
||||||
|
channel_key = str(channel_id)
|
||||||
|
|
||||||
|
if channel_key in channels:
|
||||||
|
channel_name = channels[channel_key]["name"]
|
||||||
|
del channels[channel_key]
|
||||||
|
self.save_data()
|
||||||
|
logger.info(f"Removed channel from tracking: {channel_name} (ID: {channel_id})")
|
||||||
|
|
||||||
|
def get_channels_for_cleanup(self, empty_threshold_minutes: int = 15) -> List[Dict[str, Any]]:
|
||||||
|
"""
|
||||||
|
Get channels that should be deleted based on empty duration.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
empty_threshold_minutes: Minutes a channel must be empty before cleanup
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
List of channel data dictionaries ready for cleanup
|
||||||
|
"""
|
||||||
|
cleanup_candidates = []
|
||||||
|
cutoff_time = datetime.utcnow() - timedelta(minutes=empty_threshold_minutes)
|
||||||
|
|
||||||
|
for channel_data in self._data.get("voice_channels", {}).values():
|
||||||
|
if channel_data["empty_since"]:
|
||||||
|
try:
|
||||||
|
# Parse empty_since timestamp
|
||||||
|
empty_since_str = channel_data["empty_since"]
|
||||||
|
# Handle both with and without timezone info
|
||||||
|
if empty_since_str.endswith('Z'):
|
||||||
|
empty_since_str = empty_since_str[:-1] + '+00:00'
|
||||||
|
|
||||||
|
empty_since = datetime.fromisoformat(empty_since_str.replace('Z', '+00:00'))
|
||||||
|
|
||||||
|
# Remove timezone info for comparison (both times are UTC)
|
||||||
|
if empty_since.tzinfo:
|
||||||
|
empty_since = empty_since.replace(tzinfo=None)
|
||||||
|
|
||||||
|
if empty_since <= cutoff_time:
|
||||||
|
cleanup_candidates.append(channel_data)
|
||||||
|
logger.debug(f"Channel {channel_data['name']} ready for cleanup (empty since {empty_since})")
|
||||||
|
|
||||||
|
except (ValueError, TypeError) as e:
|
||||||
|
logger.warning(f"Invalid timestamp for channel {channel_data.get('name', 'unknown')}: {e}")
|
||||||
|
|
||||||
|
return cleanup_candidates
|
||||||
|
|
||||||
|
def get_all_tracked_channels(self) -> List[Dict[str, Any]]:
|
||||||
|
"""
|
||||||
|
Get all currently tracked channels.
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
List of all tracked channel data dictionaries
|
||||||
|
"""
|
||||||
|
return list(self._data.get("voice_channels", {}).values())
|
||||||
|
|
||||||
|
def get_tracked_channel(self, channel_id: int) -> Optional[Dict[str, Any]]:
|
||||||
|
"""
|
||||||
|
Get data for a specific tracked channel.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
channel_id: Discord channel ID
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
Channel data dictionary or None if not tracked
|
||||||
|
"""
|
||||||
|
channels = self._data.get("voice_channels", {})
|
||||||
|
return channels.get(str(channel_id))
|
||||||
|
|
||||||
|
def cleanup_stale_entries(self, valid_channel_ids: List[int]) -> int:
|
||||||
|
"""
|
||||||
|
Remove tracking entries for channels that no longer exist.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
valid_channel_ids: List of channel IDs that still exist in Discord
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
Number of stale entries removed
|
||||||
|
"""
|
||||||
|
channels = self._data.get("voice_channels", {})
|
||||||
|
stale_entries = []
|
||||||
|
|
||||||
|
for channel_id_str, channel_data in channels.items():
|
||||||
|
try:
|
||||||
|
channel_id = int(channel_id_str)
|
||||||
|
if channel_id not in valid_channel_ids:
|
||||||
|
stale_entries.append(channel_id_str)
|
||||||
|
except (ValueError, TypeError):
|
||||||
|
logger.warning(f"Invalid channel ID in tracking data: {channel_id_str}")
|
||||||
|
stale_entries.append(channel_id_str)
|
||||||
|
|
||||||
|
# Remove stale entries
|
||||||
|
for channel_id_str in stale_entries:
|
||||||
|
channel_name = channels[channel_id_str].get("name", "unknown")
|
||||||
|
del channels[channel_id_str]
|
||||||
|
logger.info(f"Removed stale tracking entry: {channel_name} (ID: {channel_id_str})")
|
||||||
|
|
||||||
|
if stale_entries:
|
||||||
|
self.save_data()
|
||||||
|
|
||||||
|
return len(stale_entries)
|
||||||
325
models/README.md
Normal file
325
models/README.md
Normal file
@ -0,0 +1,325 @@
|
|||||||
|
# Models Directory
|
||||||
|
|
||||||
|
The models directory contains Pydantic data models for Discord Bot v2.0, providing type-safe representations of all SBA (Strat-o-Matic Baseball Association) entities. All models inherit from `SBABaseModel` and follow consistent validation patterns.
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
### Pydantic Foundation
|
||||||
|
All models use Pydantic v2 with:
|
||||||
|
- **Automatic validation** of field types and constraints
|
||||||
|
- **Serialization/deserialization** for API interactions
|
||||||
|
- **Type safety** with full IDE support
|
||||||
|
- **JSON schema generation** for documentation
|
||||||
|
- **Field validation** with custom validators
|
||||||
|
|
||||||
|
### Base Model (`base.py`)
|
||||||
|
The foundation for all SBA models:
|
||||||
|
|
||||||
|
```python
|
||||||
|
class SBABaseModel(BaseModel):
|
||||||
|
model_config = {
|
||||||
|
"validate_assignment": True,
|
||||||
|
"use_enum_values": True,
|
||||||
|
"arbitrary_types_allowed": True,
|
||||||
|
"json_encoders": {datetime: lambda v: v.isoformat() if v else None}
|
||||||
|
}
|
||||||
|
|
||||||
|
id: Optional[int] = None
|
||||||
|
created_at: Optional[datetime] = None
|
||||||
|
updated_at: Optional[datetime] = None
|
||||||
|
```
|
||||||
|
|
||||||
|
### Breaking Changes (August 2025)
|
||||||
|
**Database entities now require `id` fields** since they're always fetched from the database:
|
||||||
|
- `Player` model: `id: int = Field(..., description="Player ID from database")`
|
||||||
|
- `Team` model: `id: int = Field(..., description="Team ID from database")`
|
||||||
|
|
||||||
|
## Model Categories
|
||||||
|
|
||||||
|
### Core Entities
|
||||||
|
|
||||||
|
#### League Structure
|
||||||
|
- **`team.py`** - Team information, abbreviations, divisions
|
||||||
|
- **`division.py`** - Division structure and organization
|
||||||
|
- **`manager.py`** - Team managers and ownership
|
||||||
|
- **`standings.py`** - Team standings and rankings
|
||||||
|
|
||||||
|
#### Player Data
|
||||||
|
- **`player.py`** - Core player information and identifiers
|
||||||
|
- **`sbaplayer.py`** - Extended SBA-specific player data
|
||||||
|
- **`batting_stats.py`** - Batting statistics and performance metrics
|
||||||
|
- **`pitching_stats.py`** - Pitching statistics and performance metrics
|
||||||
|
- **`roster.py`** - Team roster assignments and positions
|
||||||
|
|
||||||
|
#### Game Operations
|
||||||
|
- **`game.py`** - Individual game results and scheduling
|
||||||
|
- **`transaction.py`** - Player transactions (trades, waivers, etc.)
|
||||||
|
|
||||||
|
#### Draft System
|
||||||
|
- **`draft_pick.py`** - Individual draft pick information
|
||||||
|
- **`draft_data.py`** - Draft round and selection data
|
||||||
|
- **`draft_list.py`** - Complete draft lists and results
|
||||||
|
|
||||||
|
#### Custom Features
|
||||||
|
- **`custom_command.py`** - User-created Discord commands
|
||||||
|
|
||||||
|
### Legacy Models
|
||||||
|
- **`current.py`** - Legacy model definitions for backward compatibility
|
||||||
|
|
||||||
|
## Model Validation Patterns
|
||||||
|
|
||||||
|
### Required Fields
|
||||||
|
Models distinguish between required and optional fields:
|
||||||
|
|
||||||
|
```python
|
||||||
|
class Player(SBABaseModel):
|
||||||
|
id: int = Field(..., description="Player ID from database") # Required
|
||||||
|
name: str = Field(..., description="Player full name") # Required
|
||||||
|
team_id: Optional[int] = None # Optional
|
||||||
|
position: Optional[str] = None # Optional
|
||||||
|
```
|
||||||
|
|
||||||
|
### Field Constraints
|
||||||
|
Models use Pydantic validators for data integrity:
|
||||||
|
|
||||||
|
```python
|
||||||
|
class BattingStats(SBABaseModel):
|
||||||
|
at_bats: int = Field(ge=0, description="At bats (non-negative)")
|
||||||
|
hits: int = Field(ge=0, le=Field('at_bats'), description="Hits (cannot exceed at_bats)")
|
||||||
|
|
||||||
|
@field_validator('batting_average')
|
||||||
|
@classmethod
|
||||||
|
def validate_batting_average(cls, v):
|
||||||
|
if v is not None and not 0.0 <= v <= 1.0:
|
||||||
|
raise ValueError('Batting average must be between 0.0 and 1.0')
|
||||||
|
return v
|
||||||
|
```
|
||||||
|
|
||||||
|
### Custom Validators
|
||||||
|
Models implement business logic validation:
|
||||||
|
|
||||||
|
```python
|
||||||
|
class Transaction(SBABaseModel):
|
||||||
|
transaction_type: str
|
||||||
|
player_id: int
|
||||||
|
from_team_id: Optional[int] = None
|
||||||
|
to_team_id: Optional[int] = None
|
||||||
|
|
||||||
|
@model_validator(mode='after')
|
||||||
|
def validate_team_requirements(self):
|
||||||
|
if self.transaction_type == 'trade':
|
||||||
|
if not self.from_team_id or not self.to_team_id:
|
||||||
|
raise ValueError('Trade transactions require both from_team_id and to_team_id')
|
||||||
|
return self
|
||||||
|
```
|
||||||
|
|
||||||
|
## API Integration
|
||||||
|
|
||||||
|
### Data Transformation
|
||||||
|
Models provide methods for API interaction:
|
||||||
|
|
||||||
|
```python
|
||||||
|
class Player(SBABaseModel):
|
||||||
|
@classmethod
|
||||||
|
def from_api_data(cls, data: Dict[str, Any]):
|
||||||
|
"""Create model instance from API response data."""
|
||||||
|
if not data:
|
||||||
|
raise ValueError(f"Cannot create {cls.__name__} from empty data")
|
||||||
|
return cls(**data)
|
||||||
|
|
||||||
|
def to_dict(self, exclude_none: bool = True) -> Dict[str, Any]:
|
||||||
|
"""Convert model to dictionary for API requests."""
|
||||||
|
return self.model_dump(exclude_none=exclude_none)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Serialization Examples
|
||||||
|
Models handle various data formats:
|
||||||
|
|
||||||
|
```python
|
||||||
|
# From API JSON
|
||||||
|
player_data = {"id": 123, "name": "Player Name", "team_id": 5}
|
||||||
|
player = Player.from_api_data(player_data)
|
||||||
|
|
||||||
|
# To API JSON
|
||||||
|
api_payload = player.to_dict(exclude_none=True)
|
||||||
|
|
||||||
|
# JSON string serialization
|
||||||
|
json_string = player.model_dump_json()
|
||||||
|
|
||||||
|
# From JSON string
|
||||||
|
player_copy = Player.model_validate_json(json_string)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Testing Requirements
|
||||||
|
|
||||||
|
### Model Validation Testing
|
||||||
|
All model tests must provide complete data:
|
||||||
|
|
||||||
|
```python
|
||||||
|
def test_player_creation():
|
||||||
|
# ✅ Correct - provides required ID field
|
||||||
|
player = Player(
|
||||||
|
id=123,
|
||||||
|
name="Test Player",
|
||||||
|
team_id=5,
|
||||||
|
position="1B"
|
||||||
|
)
|
||||||
|
assert player.id == 123
|
||||||
|
|
||||||
|
def test_incomplete_data():
|
||||||
|
# ❌ This will fail - missing required ID
|
||||||
|
with pytest.raises(ValidationError):
|
||||||
|
Player(name="Test Player") # Missing required id field
|
||||||
|
```
|
||||||
|
|
||||||
|
### Test Data Patterns
|
||||||
|
Use helper functions for consistent test data:
|
||||||
|
|
||||||
|
```python
|
||||||
|
def create_test_player(**overrides) -> Player:
|
||||||
|
"""Create a test player with default values."""
|
||||||
|
defaults = {
|
||||||
|
"id": 123,
|
||||||
|
"name": "Test Player",
|
||||||
|
"team_id": 1,
|
||||||
|
"position": "1B"
|
||||||
|
}
|
||||||
|
defaults.update(overrides)
|
||||||
|
return Player(**defaults)
|
||||||
|
|
||||||
|
def test_player_with_stats():
|
||||||
|
player = create_test_player(name="Star Player")
|
||||||
|
assert player.name == "Star Player"
|
||||||
|
assert player.id == 123 # Default from helper
|
||||||
|
```
|
||||||
|
|
||||||
|
## Field Types and Constraints
|
||||||
|
|
||||||
|
### Common Field Patterns
|
||||||
|
|
||||||
|
#### Identifiers
|
||||||
|
```python
|
||||||
|
id: int = Field(..., description="Database primary key")
|
||||||
|
player_id: int = Field(..., description="Foreign key to player")
|
||||||
|
team_id: Optional[int] = Field(None, description="Foreign key to team")
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Names and Text
|
||||||
|
```python
|
||||||
|
name: str = Field(..., min_length=1, max_length=100)
|
||||||
|
abbreviation: str = Field(..., min_length=2, max_length=5)
|
||||||
|
description: Optional[str] = Field(None, max_length=500)
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Statistics
|
||||||
|
```python
|
||||||
|
games_played: int = Field(ge=0, description="Games played (non-negative)")
|
||||||
|
batting_average: Optional[float] = Field(None, ge=0.0, le=1.0)
|
||||||
|
era: Optional[float] = Field(None, ge=0.0, description="Earned run average")
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Dates and Times
|
||||||
|
```python
|
||||||
|
game_date: Optional[datetime] = None
|
||||||
|
created_at: Optional[datetime] = None
|
||||||
|
season_year: int = Field(..., ge=1900, le=2100)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Model Relationships
|
||||||
|
|
||||||
|
### Foreign Key Patterns
|
||||||
|
Models reference related entities via ID fields:
|
||||||
|
|
||||||
|
```python
|
||||||
|
class Player(SBABaseModel):
|
||||||
|
id: int
|
||||||
|
team_id: Optional[int] = None # References Team.id
|
||||||
|
|
||||||
|
class BattingStats(SBABaseModel):
|
||||||
|
player_id: int # References Player.id
|
||||||
|
season: int
|
||||||
|
team_id: int # References Team.id
|
||||||
|
```
|
||||||
|
|
||||||
|
### Nested Objects
|
||||||
|
Some models contain nested structures:
|
||||||
|
|
||||||
|
```python
|
||||||
|
class CustomCommand(SBABaseModel):
|
||||||
|
name: str
|
||||||
|
creator: Manager # Nested Manager object
|
||||||
|
response: str
|
||||||
|
|
||||||
|
class DraftPick(SBABaseModel):
|
||||||
|
pick_number: int
|
||||||
|
player: Optional[Player] = None # Optional nested Player
|
||||||
|
team: Team # Required nested Team
|
||||||
|
```
|
||||||
|
|
||||||
|
## Validation Error Handling
|
||||||
|
|
||||||
|
### Common Validation Errors
|
||||||
|
- **Missing required fields** - Provide all required model fields
|
||||||
|
- **Type mismatches** - Ensure field types match model definitions
|
||||||
|
- **Constraint violations** - Check field validators and constraints
|
||||||
|
- **Invalid nested objects** - Validate all nested model data
|
||||||
|
|
||||||
|
### Error Examples
|
||||||
|
```python
|
||||||
|
try:
|
||||||
|
player = Player(name="Test") # Missing required id
|
||||||
|
except ValidationError as e:
|
||||||
|
print(e.errors())
|
||||||
|
# [{'type': 'missing', 'loc': ('id',), 'msg': 'Field required'}]
|
||||||
|
|
||||||
|
try:
|
||||||
|
stats = BattingStats(hits=5, at_bats=3) # hits > at_bats
|
||||||
|
except ValidationError as e:
|
||||||
|
print(e.errors())
|
||||||
|
# Constraint violation error
|
||||||
|
```
|
||||||
|
|
||||||
|
## Performance Considerations
|
||||||
|
|
||||||
|
### Model Instantiation
|
||||||
|
- Use `model_validate()` for external data
|
||||||
|
- Use `model_construct()` for trusted internal data (faster)
|
||||||
|
- Cache model instances when possible
|
||||||
|
- Avoid repeated validation of the same data
|
||||||
|
|
||||||
|
### Memory Usage
|
||||||
|
- Models are relatively lightweight
|
||||||
|
- Nested objects can increase memory footprint
|
||||||
|
- Consider using `__slots__` for high-volume models
|
||||||
|
- Use `exclude_none=True` to reduce serialization size
|
||||||
|
|
||||||
|
## Development Guidelines
|
||||||
|
|
||||||
|
### Adding New Models
|
||||||
|
1. **Inherit from SBABaseModel** for consistency
|
||||||
|
2. **Define required fields explicitly** with proper types
|
||||||
|
3. **Add field descriptions** for documentation
|
||||||
|
4. **Include validation rules** for data integrity
|
||||||
|
5. **Provide `from_api_data()` class method** if needed
|
||||||
|
6. **Write comprehensive tests** covering edge cases
|
||||||
|
|
||||||
|
### Model Evolution
|
||||||
|
- **Backward compatibility** - Add optional fields for new features
|
||||||
|
- **Migration patterns** - Handle schema changes gracefully
|
||||||
|
- **Version management** - Document breaking changes
|
||||||
|
- **API alignment** - Keep models synchronized with API
|
||||||
|
|
||||||
|
### Testing Strategy
|
||||||
|
- **Unit tests** for individual model validation
|
||||||
|
- **Integration tests** with service layer
|
||||||
|
- **Edge case testing** for validation rules
|
||||||
|
- **Performance tests** for large data sets
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Next Steps for AI Agents:**
|
||||||
|
1. Review existing model implementations for patterns
|
||||||
|
2. Understand the validation rules and field constraints
|
||||||
|
3. Check the service layer integration in `/services`
|
||||||
|
4. Follow the testing patterns with complete model data
|
||||||
|
5. Consider the API data format when creating new models
|
||||||
190
services/README.md
Normal file
190
services/README.md
Normal file
@ -0,0 +1,190 @@
|
|||||||
|
# Services Directory
|
||||||
|
|
||||||
|
The services directory contains the service layer for Discord Bot v2.0, providing clean abstractions for API interactions and business logic. All services inherit from `BaseService` and follow consistent patterns for data operations.
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
### Service Layer Pattern
|
||||||
|
Services act as the interface between Discord commands and the external API, providing:
|
||||||
|
- **Data validation** using Pydantic models
|
||||||
|
- **Error handling** with consistent exception patterns
|
||||||
|
- **Caching support** via Redis decorators
|
||||||
|
- **Type safety** with generic TypeVar support
|
||||||
|
- **Logging integration** with structured logging
|
||||||
|
|
||||||
|
### Base Service (`base_service.py`)
|
||||||
|
The foundation for all services, providing:
|
||||||
|
- **Generic CRUD operations** (Create, Read, Update, Delete)
|
||||||
|
- **API client management** with connection pooling
|
||||||
|
- **Response format handling** for API responses
|
||||||
|
- **Cache key generation** and management
|
||||||
|
- **Error handling** with APIException wrapping
|
||||||
|
|
||||||
|
```python
|
||||||
|
class BaseService(Generic[T]):
|
||||||
|
def __init__(self, model_class: Type[T], endpoint: str)
|
||||||
|
async def get_by_id(self, object_id: int) -> Optional[T]
|
||||||
|
async def get_all(self, params: Optional[List[tuple]] = None) -> Tuple[List[T], int]
|
||||||
|
async def create(self, model_data: Dict[str, Any]) -> Optional[T]
|
||||||
|
async def update(self, object_id: int, model_data: Dict[str, Any]) -> Optional[T]
|
||||||
|
async def delete(self, object_id: int) -> bool
|
||||||
|
```
|
||||||
|
|
||||||
|
## Service Files
|
||||||
|
|
||||||
|
### Core Entity Services
|
||||||
|
- **`player_service.py`** - Player data operations and search functionality
|
||||||
|
- **`team_service.py`** - Team information and roster management
|
||||||
|
- **`league_service.py`** - League-wide data and current season info
|
||||||
|
- **`standings_service.py`** - Team standings and division rankings
|
||||||
|
- **`schedule_service.py`** - Game scheduling and results
|
||||||
|
- **`stats_service.py`** - Player statistics (batting, pitching, fielding)
|
||||||
|
- **`roster_service.py`** - Team roster composition and position assignments
|
||||||
|
|
||||||
|
### Transaction Services
|
||||||
|
- **`transaction_service.py`** - Player transaction operations (trades, waivers, etc.)
|
||||||
|
- **`transaction_builder.py`** - Complex transaction building and validation
|
||||||
|
|
||||||
|
### Custom Features
|
||||||
|
- **`custom_commands_service.py`** - User-created custom Discord commands
|
||||||
|
|
||||||
|
## Caching Integration
|
||||||
|
|
||||||
|
Services support optional Redis caching via decorators:
|
||||||
|
|
||||||
|
```python
|
||||||
|
from utils.decorators import cached_api_call, cached_single_item
|
||||||
|
|
||||||
|
class PlayerService(BaseService[Player]):
|
||||||
|
@cached_api_call(ttl=600) # Cache for 10 minutes
|
||||||
|
async def get_players_by_team(self, team_id: int, season: int) -> List[Player]:
|
||||||
|
return await self.get_all_items(params=[('team_id', team_id), ('season', season)])
|
||||||
|
|
||||||
|
@cached_single_item(ttl=300) # Cache for 5 minutes
|
||||||
|
async def get_player_by_name(self, name: str) -> Optional[Player]:
|
||||||
|
players = await self.get_by_field('name', name)
|
||||||
|
return players[0] if players else None
|
||||||
|
```
|
||||||
|
|
||||||
|
### Caching Features
|
||||||
|
- **Graceful degradation** - Works without Redis
|
||||||
|
- **Automatic key generation** based on method parameters
|
||||||
|
- **TTL support** with configurable expiration
|
||||||
|
- **Cache invalidation** patterns for data updates
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
All services use consistent error handling:
|
||||||
|
|
||||||
|
```python
|
||||||
|
try:
|
||||||
|
result = await some_service.get_data()
|
||||||
|
return result
|
||||||
|
except APIException as e:
|
||||||
|
logger.error("API error occurred", error=e)
|
||||||
|
raise # Re-raise for command handlers
|
||||||
|
except Exception as e:
|
||||||
|
logger.error("Unexpected error", error=e)
|
||||||
|
raise APIException(f"Service operation failed: {e}")
|
||||||
|
```
|
||||||
|
|
||||||
|
### Exception Types
|
||||||
|
- **`APIException`** - API communication errors
|
||||||
|
- **`ValueError`** - Data validation errors
|
||||||
|
- **`ConnectionError`** - Network connectivity issues
|
||||||
|
|
||||||
|
## Usage Patterns
|
||||||
|
|
||||||
|
### Service Initialization
|
||||||
|
Services are typically initialized once and reused:
|
||||||
|
|
||||||
|
```python
|
||||||
|
# In services/__init__.py
|
||||||
|
from .player_service import PlayerService
|
||||||
|
from models.player import Player
|
||||||
|
|
||||||
|
player_service = PlayerService(Player, 'players')
|
||||||
|
```
|
||||||
|
|
||||||
|
### Command Integration
|
||||||
|
Services integrate with Discord commands via the `@logged_command` decorator:
|
||||||
|
|
||||||
|
```python
|
||||||
|
@discord.app_commands.command(name="player")
|
||||||
|
@logged_command("/player")
|
||||||
|
async def player_info(self, interaction: discord.Interaction, name: str):
|
||||||
|
player = await player_service.get_player_by_name(name)
|
||||||
|
if not player:
|
||||||
|
await interaction.followup.send("Player not found")
|
||||||
|
return
|
||||||
|
|
||||||
|
embed = create_player_embed(player)
|
||||||
|
await interaction.followup.send(embed=embed)
|
||||||
|
```
|
||||||
|
|
||||||
|
## API Response Format
|
||||||
|
|
||||||
|
Services handle the standard API response format:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"count": 150,
|
||||||
|
"players": [
|
||||||
|
{"id": 1, "name": "Player Name", ...},
|
||||||
|
{"id": 2, "name": "Another Player", ...}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The `BaseService._extract_items_and_count_from_response()` method automatically parses this format and returns typed model instances.
|
||||||
|
|
||||||
|
## Development Guidelines
|
||||||
|
|
||||||
|
### Adding New Services
|
||||||
|
1. **Inherit from BaseService** with appropriate model type
|
||||||
|
2. **Define specific business methods** beyond CRUD operations
|
||||||
|
3. **Add caching decorators** for expensive operations
|
||||||
|
4. **Include comprehensive logging** with structured context
|
||||||
|
5. **Handle edge cases** and provide meaningful error messages
|
||||||
|
|
||||||
|
### Service Method Patterns
|
||||||
|
- **Query methods** should return `List[T]` or `Optional[T]`
|
||||||
|
- **Mutation methods** should return the updated model or `None`
|
||||||
|
- **Search methods** should accept flexible parameters
|
||||||
|
- **Bulk operations** should handle batching efficiently
|
||||||
|
|
||||||
|
### Testing Services
|
||||||
|
- Use `aioresponses` for HTTP client mocking
|
||||||
|
- Test both success and error scenarios
|
||||||
|
- Validate model parsing and transformation
|
||||||
|
- Verify caching behavior when Redis is available
|
||||||
|
|
||||||
|
## Environment Integration
|
||||||
|
|
||||||
|
Services respect environment configuration:
|
||||||
|
- **`DB_URL`** - Database API endpoint
|
||||||
|
- **`API_TOKEN`** - Authentication token
|
||||||
|
- **`REDIS_URL`** - Optional caching backend
|
||||||
|
- **`LOG_LEVEL`** - Logging verbosity
|
||||||
|
|
||||||
|
## Performance Considerations
|
||||||
|
|
||||||
|
### Optimization Strategies
|
||||||
|
- **Connection pooling** via global API client
|
||||||
|
- **Response caching** for frequently accessed data
|
||||||
|
- **Batch operations** for bulk data processing
|
||||||
|
- **Lazy loading** for expensive computations
|
||||||
|
|
||||||
|
### Monitoring
|
||||||
|
- All operations are logged with timing information
|
||||||
|
- Cache hit/miss ratios are tracked
|
||||||
|
- API error rates are monitored
|
||||||
|
- Service response times are measured
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Next Steps for AI Agents:**
|
||||||
|
1. Review existing service implementations for patterns
|
||||||
|
2. Check the corresponding model definitions in `/models`
|
||||||
|
3. Understand the caching decorators in `/utils/decorators.py`
|
||||||
|
4. Follow the error handling patterns established in `BaseService`
|
||||||
|
5. Use structured logging with contextual information
|
||||||
364
tasks/README.md
Normal file
364
tasks/README.md
Normal file
@ -0,0 +1,364 @@
|
|||||||
|
# Tasks Directory
|
||||||
|
|
||||||
|
The tasks directory contains automated background tasks for Discord Bot v2.0. These tasks handle periodic maintenance, data cleanup, and scheduled operations that run independently of user interactions.
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
### Task System Design
|
||||||
|
Tasks in Discord Bot v2.0 follow these patterns:
|
||||||
|
- **Discord.py tasks** using the `@tasks.loop` decorator
|
||||||
|
- **Structured logging** with contextual information
|
||||||
|
- **Error handling** with graceful degradation
|
||||||
|
- **Guild-specific operations** respecting bot permissions
|
||||||
|
- **Configurable intervals** via task decorators
|
||||||
|
|
||||||
|
### Base Task Pattern
|
||||||
|
All tasks follow a consistent structure:
|
||||||
|
|
||||||
|
```python
|
||||||
|
from discord.ext import tasks
|
||||||
|
from utils.logging import get_contextual_logger
|
||||||
|
|
||||||
|
class ExampleTask:
|
||||||
|
def __init__(self, bot: commands.Bot):
|
||||||
|
self.bot = bot
|
||||||
|
self.logger = get_contextual_logger(f'{__name__}.ExampleTask')
|
||||||
|
self.task_loop.start()
|
||||||
|
|
||||||
|
def cog_unload(self):
|
||||||
|
"""Stop the task when cog is unloaded."""
|
||||||
|
self.task_loop.cancel()
|
||||||
|
|
||||||
|
@tasks.loop(hours=24) # Run daily
|
||||||
|
async def task_loop(self):
|
||||||
|
"""Main task implementation."""
|
||||||
|
try:
|
||||||
|
# Task logic here
|
||||||
|
pass
|
||||||
|
except Exception as e:
|
||||||
|
self.logger.error("Task failed", error=e)
|
||||||
|
|
||||||
|
@task_loop.before_loop
|
||||||
|
async def before_task(self):
|
||||||
|
"""Wait for bot to be ready before starting."""
|
||||||
|
await self.bot.wait_until_ready()
|
||||||
|
```
|
||||||
|
|
||||||
|
## Current Tasks
|
||||||
|
|
||||||
|
### Custom Command Cleanup (`custom_command_cleanup.py`)
|
||||||
|
**Purpose:** Automated cleanup system for user-created custom commands
|
||||||
|
|
||||||
|
**Schedule:** Daily (24 hours)
|
||||||
|
|
||||||
|
**Operations:**
|
||||||
|
- **Warning Phase:** Notifies users about commands at risk (unused for 60+ days)
|
||||||
|
- **Deletion Phase:** Removes commands unused for 90+ days
|
||||||
|
- **Admin Reporting:** Sends cleanup summaries to admin channels
|
||||||
|
|
||||||
|
#### Key Features
|
||||||
|
- **User Notifications:** Direct messages to command creators
|
||||||
|
- **Grace Period:** 30-day warning before deletion
|
||||||
|
- **Admin Transparency:** Optional summary reports
|
||||||
|
- **Bulk Operations:** Efficient batch processing
|
||||||
|
- **Error Resilience:** Continues operation despite individual failures
|
||||||
|
|
||||||
|
#### Configuration
|
||||||
|
The cleanup task respects guild settings and permissions:
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Configuration via get_config()
|
||||||
|
guild_id = config.guild_id # Target guild
|
||||||
|
admin_channels = ['admin', 'bot-logs'] # Admin notification channels
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Notification System
|
||||||
|
**Warning Embed (30 days before deletion):**
|
||||||
|
- Lists commands at risk
|
||||||
|
- Shows days since last use
|
||||||
|
- Provides usage instructions
|
||||||
|
- Links to command management
|
||||||
|
|
||||||
|
**Deletion Embed (after deletion):**
|
||||||
|
- Lists deleted commands
|
||||||
|
- Shows final usage statistics
|
||||||
|
- Provides recreation instructions
|
||||||
|
- Explains cleanup policy
|
||||||
|
|
||||||
|
#### Admin Summary
|
||||||
|
Optional admin channel reporting includes:
|
||||||
|
- Number of warnings sent
|
||||||
|
- Number of commands deleted
|
||||||
|
- Current system statistics
|
||||||
|
- Next cleanup schedule
|
||||||
|
|
||||||
|
## Task Lifecycle
|
||||||
|
|
||||||
|
### Initialization
|
||||||
|
Tasks are initialized when the bot starts:
|
||||||
|
|
||||||
|
```python
|
||||||
|
# In bot startup
|
||||||
|
def setup_cleanup_task(bot: commands.Bot) -> CustomCommandCleanupTask:
|
||||||
|
return CustomCommandCleanupTask(bot)
|
||||||
|
|
||||||
|
# Usage
|
||||||
|
cleanup_task = setup_cleanup_task(bot)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Execution Flow
|
||||||
|
1. **Bot Ready Check:** Wait for `bot.wait_until_ready()`
|
||||||
|
2. **Guild Validation:** Verify bot has access to configured guild
|
||||||
|
3. **Permission Checks:** Ensure bot can send messages/DMs
|
||||||
|
4. **Main Operation:** Execute task logic with error handling
|
||||||
|
5. **Logging:** Record operation results and performance metrics
|
||||||
|
6. **Cleanup:** Reset state for next iteration
|
||||||
|
|
||||||
|
### Error Handling
|
||||||
|
Tasks implement comprehensive error handling:
|
||||||
|
|
||||||
|
```python
|
||||||
|
async def task_operation(self):
|
||||||
|
try:
|
||||||
|
# Main task logic
|
||||||
|
result = await self.perform_operation()
|
||||||
|
self.logger.info("Task completed", result=result)
|
||||||
|
except SpecificException as e:
|
||||||
|
self.logger.warning("Recoverable error", error=e)
|
||||||
|
# Continue with degraded functionality
|
||||||
|
except Exception as e:
|
||||||
|
self.logger.error("Task failed", error=e)
|
||||||
|
# Task will retry on next interval
|
||||||
|
```
|
||||||
|
|
||||||
|
## Development Patterns
|
||||||
|
|
||||||
|
### Creating New Tasks
|
||||||
|
|
||||||
|
1. **Inherit from Base Pattern**
|
||||||
|
```python
|
||||||
|
class NewTask:
|
||||||
|
def __init__(self, bot: commands.Bot):
|
||||||
|
self.bot = bot
|
||||||
|
self.logger = get_contextual_logger(f'{__name__}.NewTask')
|
||||||
|
self.main_loop.start()
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Configure Task Schedule**
|
||||||
|
```python
|
||||||
|
@tasks.loop(minutes=30) # Every 30 minutes
|
||||||
|
# or
|
||||||
|
@tasks.loop(hours=6) # Every 6 hours
|
||||||
|
# or
|
||||||
|
@tasks.loop(time=datetime.time(hour=3)) # Daily at 3 AM UTC
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Implement Before Loop**
|
||||||
|
```python
|
||||||
|
@main_loop.before_loop
|
||||||
|
async def before_loop(self):
|
||||||
|
await self.bot.wait_until_ready()
|
||||||
|
self.logger.info("Task initialized and ready")
|
||||||
|
```
|
||||||
|
|
||||||
|
4. **Add Cleanup Handling**
|
||||||
|
```python
|
||||||
|
def cog_unload(self):
|
||||||
|
self.main_loop.cancel()
|
||||||
|
self.logger.info("Task stopped")
|
||||||
|
```
|
||||||
|
|
||||||
|
### Task Categories
|
||||||
|
|
||||||
|
#### Maintenance Tasks
|
||||||
|
- **Data cleanup** (expired records, unused resources)
|
||||||
|
- **Cache management** (clear stale entries, optimize storage)
|
||||||
|
- **Log rotation** (archive old logs, manage disk space)
|
||||||
|
|
||||||
|
#### User Management
|
||||||
|
- **Inactive user cleanup** (remove old user data)
|
||||||
|
- **Permission auditing** (validate role assignments)
|
||||||
|
- **Usage analytics** (collect usage statistics)
|
||||||
|
|
||||||
|
#### System Monitoring
|
||||||
|
- **Health checks** (verify system components)
|
||||||
|
- **Performance monitoring** (track response times)
|
||||||
|
- **Error rate tracking** (monitor failure rates)
|
||||||
|
|
||||||
|
### Task Configuration
|
||||||
|
|
||||||
|
#### Environment Variables
|
||||||
|
Tasks respect standard bot configuration:
|
||||||
|
```python
|
||||||
|
GUILD_ID=12345... # Target Discord guild
|
||||||
|
LOG_LEVEL=INFO # Logging verbosity
|
||||||
|
REDIS_URL=redis://... # Optional caching backend
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Runtime Configuration
|
||||||
|
Tasks use the central config system:
|
||||||
|
```python
|
||||||
|
from config import get_config
|
||||||
|
|
||||||
|
config = get_config()
|
||||||
|
guild = self.bot.get_guild(config.guild_id)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Logging and Monitoring
|
||||||
|
|
||||||
|
### Structured Logging
|
||||||
|
Tasks use contextual logging for observability:
|
||||||
|
|
||||||
|
```python
|
||||||
|
self.logger.info(
|
||||||
|
"Cleanup task starting",
|
||||||
|
guild_id=guild.id,
|
||||||
|
commands_at_risk=len(at_risk_commands)
|
||||||
|
)
|
||||||
|
|
||||||
|
self.logger.warning(
|
||||||
|
"User DM failed",
|
||||||
|
user_id=user.id,
|
||||||
|
reason="DMs disabled"
|
||||||
|
)
|
||||||
|
|
||||||
|
self.logger.error(
|
||||||
|
"Task operation failed",
|
||||||
|
operation="delete_commands",
|
||||||
|
error=str(e)
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Performance Tracking
|
||||||
|
Tasks log timing and performance metrics:
|
||||||
|
|
||||||
|
```python
|
||||||
|
start_time = datetime.utcnow()
|
||||||
|
# ... task operations ...
|
||||||
|
duration = (datetime.utcnow() - start_time).total_seconds()
|
||||||
|
|
||||||
|
self.logger.info(
|
||||||
|
"Task completed",
|
||||||
|
duration_seconds=duration,
|
||||||
|
operations_completed=operation_count
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Error Recovery
|
||||||
|
Tasks implement retry logic and graceful degradation:
|
||||||
|
|
||||||
|
```python
|
||||||
|
async def process_with_retry(self, operation, max_retries=3):
|
||||||
|
for attempt in range(max_retries):
|
||||||
|
try:
|
||||||
|
return await operation()
|
||||||
|
except RecoverableError as e:
|
||||||
|
if attempt == max_retries - 1:
|
||||||
|
raise
|
||||||
|
await asyncio.sleep(2 ** attempt) # Exponential backoff
|
||||||
|
```
|
||||||
|
|
||||||
|
## Testing Strategies
|
||||||
|
|
||||||
|
### Unit Testing Tasks
|
||||||
|
```python
|
||||||
|
@pytest.mark.asyncio
|
||||||
|
async def test_custom_command_cleanup():
|
||||||
|
# Mock bot and services
|
||||||
|
bot = AsyncMock()
|
||||||
|
task = CustomCommandCleanupTask(bot)
|
||||||
|
|
||||||
|
# Mock service responses
|
||||||
|
with patch('services.custom_commands_service') as mock_service:
|
||||||
|
mock_service.get_commands_needing_warning.return_value = []
|
||||||
|
|
||||||
|
# Test task execution
|
||||||
|
await task.cleanup_task()
|
||||||
|
|
||||||
|
# Verify service calls
|
||||||
|
mock_service.get_commands_needing_warning.assert_called_once()
|
||||||
|
```
|
||||||
|
|
||||||
|
### Integration Testing
|
||||||
|
```python
|
||||||
|
@pytest.mark.integration
|
||||||
|
async def test_cleanup_task_with_real_data():
|
||||||
|
# Test with actual Discord bot instance
|
||||||
|
# Use test guild and test data
|
||||||
|
# Verify real Discord API interactions
|
||||||
|
```
|
||||||
|
|
||||||
|
### Performance Testing
|
||||||
|
```python
|
||||||
|
@pytest.mark.performance
|
||||||
|
async def test_cleanup_task_performance():
|
||||||
|
# Test with large datasets
|
||||||
|
# Measure execution time
|
||||||
|
# Verify memory usage
|
||||||
|
```
|
||||||
|
|
||||||
|
## Security Considerations
|
||||||
|
|
||||||
|
### Permission Validation
|
||||||
|
Tasks verify bot permissions before operations:
|
||||||
|
|
||||||
|
```python
|
||||||
|
async def check_permissions(self, guild: discord.Guild) -> bool:
|
||||||
|
"""Verify bot has required permissions."""
|
||||||
|
bot_member = guild.me
|
||||||
|
|
||||||
|
# Check for required permissions
|
||||||
|
if not bot_member.guild_permissions.send_messages:
|
||||||
|
self.logger.warning("Missing send_messages permission")
|
||||||
|
return False
|
||||||
|
|
||||||
|
return True
|
||||||
|
```
|
||||||
|
|
||||||
|
### Data Privacy
|
||||||
|
Tasks handle user data responsibly:
|
||||||
|
- **Minimal data access** - Only access required data
|
||||||
|
- **Secure logging** - Avoid logging sensitive information
|
||||||
|
- **GDPR compliance** - Respect user data rights
|
||||||
|
- **Permission respect** - Honor user privacy settings
|
||||||
|
|
||||||
|
### Rate Limiting
|
||||||
|
Tasks implement Discord API rate limiting:
|
||||||
|
|
||||||
|
```python
|
||||||
|
async def send_notifications_with_rate_limiting(self, notifications):
|
||||||
|
"""Send notifications with rate limiting."""
|
||||||
|
for notification in notifications:
|
||||||
|
try:
|
||||||
|
await self.send_notification(notification)
|
||||||
|
await asyncio.sleep(1) # Avoid rate limits
|
||||||
|
except discord.HTTPException as e:
|
||||||
|
if e.status == 429: # Rate limited
|
||||||
|
retry_after = e.response.headers.get('Retry-After', 60)
|
||||||
|
await asyncio.sleep(int(retry_after))
|
||||||
|
```
|
||||||
|
|
||||||
|
## Future Task Ideas
|
||||||
|
|
||||||
|
### Potential Additions
|
||||||
|
- **Database maintenance** - Optimize database performance
|
||||||
|
- **Backup automation** - Create data backups
|
||||||
|
- **Usage analytics** - Generate usage reports
|
||||||
|
- **Health monitoring** - System health checks
|
||||||
|
- **Cache warming** - Pre-populate frequently accessed data
|
||||||
|
|
||||||
|
### Scalability Patterns
|
||||||
|
- **Task queues** - Distribute work across multiple workers
|
||||||
|
- **Sharding support** - Handle multiple Discord guilds
|
||||||
|
- **Load balancing** - Distribute task execution
|
||||||
|
- **Monitoring integration** - External monitoring systems
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Next Steps for AI Agents:**
|
||||||
|
1. Review the existing cleanup task implementation
|
||||||
|
2. Understand the Discord.py tasks framework
|
||||||
|
3. Follow the structured logging patterns
|
||||||
|
4. Implement proper error handling and recovery
|
||||||
|
5. Consider guild permissions and user privacy
|
||||||
|
6. Test tasks thoroughly before deployment
|
||||||
550
tests/test_commands_voice.py
Normal file
550
tests/test_commands_voice.py
Normal file
@ -0,0 +1,550 @@
|
|||||||
|
"""
|
||||||
|
Tests for voice channel commands
|
||||||
|
|
||||||
|
Validates voice channel creation, cleanup, and migration message functionality.
|
||||||
|
"""
|
||||||
|
import asyncio
|
||||||
|
import json
|
||||||
|
import tempfile
|
||||||
|
from datetime import datetime, timedelta
|
||||||
|
from pathlib import Path
|
||||||
|
from unittest.mock import AsyncMock, MagicMock, patch
|
||||||
|
|
||||||
|
import discord
|
||||||
|
import pytest
|
||||||
|
from discord.ext import commands
|
||||||
|
|
||||||
|
from commands.voice.channels import VoiceChannelCommands
|
||||||
|
from commands.voice.cleanup_service import VoiceChannelCleanupService
|
||||||
|
from commands.voice.tracker import VoiceChannelTracker
|
||||||
|
from models.game import Game
|
||||||
|
from models.team import Team
|
||||||
|
|
||||||
|
|
||||||
|
class TestVoiceChannelTracker:
|
||||||
|
"""Test voice channel tracker functionality."""
|
||||||
|
|
||||||
|
def test_tracker_initialization(self):
|
||||||
|
"""Test that tracker initializes correctly."""
|
||||||
|
with tempfile.TemporaryDirectory() as temp_dir:
|
||||||
|
data_file = Path(temp_dir) / "test_channels.json"
|
||||||
|
tracker = VoiceChannelTracker(str(data_file))
|
||||||
|
|
||||||
|
assert tracker.data_file == data_file
|
||||||
|
assert tracker._data == {"voice_channels": {}}
|
||||||
|
assert data_file.parent.exists()
|
||||||
|
|
||||||
|
def test_add_channel(self):
|
||||||
|
"""Test adding a channel to tracking."""
|
||||||
|
with tempfile.TemporaryDirectory() as temp_dir:
|
||||||
|
data_file = Path(temp_dir) / "test_channels.json"
|
||||||
|
tracker = VoiceChannelTracker(str(data_file))
|
||||||
|
|
||||||
|
# Mock channel
|
||||||
|
mock_channel = MagicMock(spec=discord.VoiceChannel)
|
||||||
|
mock_channel.id = 123456789
|
||||||
|
mock_channel.name = "Test Channel"
|
||||||
|
mock_guild = MagicMock()
|
||||||
|
mock_guild.id = 987654321
|
||||||
|
mock_channel.guild = mock_guild
|
||||||
|
|
||||||
|
tracker.add_channel(mock_channel, "public", 555666777)
|
||||||
|
|
||||||
|
# Verify data structure
|
||||||
|
channels = tracker._data["voice_channels"]
|
||||||
|
assert "123456789" in channels
|
||||||
|
channel_data = channels["123456789"]
|
||||||
|
|
||||||
|
assert channel_data["channel_id"] == "123456789"
|
||||||
|
assert channel_data["guild_id"] == "987654321"
|
||||||
|
assert channel_data["name"] == "Test Channel"
|
||||||
|
assert channel_data["type"] == "public"
|
||||||
|
assert channel_data["creator_id"] == "555666777"
|
||||||
|
assert channel_data["empty_since"] is None
|
||||||
|
|
||||||
|
# Verify file persistence
|
||||||
|
assert data_file.exists()
|
||||||
|
|
||||||
|
def test_update_channel_status(self):
|
||||||
|
"""Test updating channel empty status."""
|
||||||
|
with tempfile.TemporaryDirectory() as temp_dir:
|
||||||
|
data_file = Path(temp_dir) / "test_channels.json"
|
||||||
|
tracker = VoiceChannelTracker(str(data_file))
|
||||||
|
|
||||||
|
# Add a test channel
|
||||||
|
mock_channel = MagicMock(spec=discord.VoiceChannel)
|
||||||
|
mock_channel.id = 123456789
|
||||||
|
mock_channel.name = "Test Channel"
|
||||||
|
mock_guild = MagicMock()
|
||||||
|
mock_guild.id = 987654321
|
||||||
|
mock_channel.guild = mock_guild
|
||||||
|
|
||||||
|
tracker.add_channel(mock_channel, "public", 555666777)
|
||||||
|
|
||||||
|
# Test becoming empty
|
||||||
|
tracker.update_channel_status(123456789, True)
|
||||||
|
channel_data = tracker._data["voice_channels"]["123456789"]
|
||||||
|
assert channel_data["empty_since"] is not None
|
||||||
|
|
||||||
|
# Test becoming occupied
|
||||||
|
tracker.update_channel_status(123456789, False)
|
||||||
|
channel_data = tracker._data["voice_channels"]["123456789"]
|
||||||
|
assert channel_data["empty_since"] is None
|
||||||
|
|
||||||
|
def test_get_channels_for_cleanup(self):
|
||||||
|
"""Test getting channels ready for cleanup."""
|
||||||
|
with tempfile.TemporaryDirectory() as temp_dir:
|
||||||
|
data_file = Path(temp_dir) / "test_channels.json"
|
||||||
|
tracker = VoiceChannelTracker(str(data_file))
|
||||||
|
|
||||||
|
# Create test data with different timestamps
|
||||||
|
current_time = datetime.utcnow()
|
||||||
|
old_empty_time = current_time - timedelta(minutes=20)
|
||||||
|
recent_empty_time = current_time - timedelta(minutes=5)
|
||||||
|
|
||||||
|
tracker._data = {
|
||||||
|
"voice_channels": {
|
||||||
|
"123": {
|
||||||
|
"channel_id": "123",
|
||||||
|
"name": "Old Empty",
|
||||||
|
"empty_since": old_empty_time.isoformat()
|
||||||
|
},
|
||||||
|
"456": {
|
||||||
|
"channel_id": "456",
|
||||||
|
"name": "Recent Empty",
|
||||||
|
"empty_since": recent_empty_time.isoformat()
|
||||||
|
},
|
||||||
|
"789": {
|
||||||
|
"channel_id": "789",
|
||||||
|
"name": "Not Empty",
|
||||||
|
"empty_since": None
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
# Get channels for cleanup (15 minute threshold)
|
||||||
|
cleanup_candidates = tracker.get_channels_for_cleanup(15)
|
||||||
|
|
||||||
|
# Only the old empty channel should be ready for cleanup
|
||||||
|
assert len(cleanup_candidates) == 1
|
||||||
|
assert cleanup_candidates[0]["channel_id"] == "123"
|
||||||
|
|
||||||
|
def test_remove_channel(self):
|
||||||
|
"""Test removing a channel from tracking."""
|
||||||
|
with tempfile.TemporaryDirectory() as temp_dir:
|
||||||
|
data_file = Path(temp_dir) / "test_channels.json"
|
||||||
|
tracker = VoiceChannelTracker(str(data_file))
|
||||||
|
|
||||||
|
# Add a test channel
|
||||||
|
mock_channel = MagicMock(spec=discord.VoiceChannel)
|
||||||
|
mock_channel.id = 123456789
|
||||||
|
mock_channel.name = "Test Channel"
|
||||||
|
mock_guild = MagicMock()
|
||||||
|
mock_guild.id = 987654321
|
||||||
|
mock_channel.guild = mock_guild
|
||||||
|
|
||||||
|
tracker.add_channel(mock_channel, "public", 555666777)
|
||||||
|
assert "123456789" in tracker._data["voice_channels"]
|
||||||
|
|
||||||
|
# Remove channel
|
||||||
|
tracker.remove_channel(123456789)
|
||||||
|
assert "123456789" not in tracker._data["voice_channels"]
|
||||||
|
|
||||||
|
def test_cleanup_stale_entries(self):
|
||||||
|
"""Test cleaning up stale tracking entries."""
|
||||||
|
with tempfile.TemporaryDirectory() as temp_dir:
|
||||||
|
data_file = Path(temp_dir) / "test_channels.json"
|
||||||
|
tracker = VoiceChannelTracker(str(data_file))
|
||||||
|
|
||||||
|
# Create test data with some valid and invalid channel IDs
|
||||||
|
tracker._data = {
|
||||||
|
"voice_channels": {
|
||||||
|
"123": {"channel_id": "123", "name": "Valid 1"},
|
||||||
|
"456": {"channel_id": "456", "name": "Valid 2"},
|
||||||
|
"789": {"channel_id": "789", "name": "Stale 1"},
|
||||||
|
"999": {"channel_id": "999", "name": "Stale 2"}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
# Clean up stale entries (only 123 and 456 are valid)
|
||||||
|
removed_count = tracker.cleanup_stale_entries([123, 456])
|
||||||
|
|
||||||
|
assert removed_count == 2
|
||||||
|
assert len(tracker._data["voice_channels"]) == 2
|
||||||
|
assert "123" in tracker._data["voice_channels"]
|
||||||
|
assert "456" in tracker._data["voice_channels"]
|
||||||
|
assert "789" not in tracker._data["voice_channels"]
|
||||||
|
assert "999" not in tracker._data["voice_channels"]
|
||||||
|
|
||||||
|
|
||||||
|
class TestVoiceChannelCleanupService:
|
||||||
|
"""Test voice channel cleanup service functionality."""
|
||||||
|
|
||||||
|
@pytest.fixture
|
||||||
|
def cleanup_service(self):
|
||||||
|
"""Create a cleanup service instance."""
|
||||||
|
with tempfile.TemporaryDirectory() as temp_dir:
|
||||||
|
data_file = Path(temp_dir) / "test_channels.json"
|
||||||
|
return VoiceChannelCleanupService(str(data_file))
|
||||||
|
|
||||||
|
@pytest.fixture
|
||||||
|
def mock_bot(self):
|
||||||
|
"""Create a mock bot instance."""
|
||||||
|
bot = AsyncMock(spec=commands.Bot)
|
||||||
|
return bot
|
||||||
|
|
||||||
|
@pytest.mark.asyncio
|
||||||
|
async def test_verify_tracked_channels(self, cleanup_service, mock_bot):
|
||||||
|
"""Test verification of tracked channels on startup."""
|
||||||
|
# Add test data
|
||||||
|
cleanup_service.tracker._data = {
|
||||||
|
"voice_channels": {
|
||||||
|
"123": {
|
||||||
|
"channel_id": "123",
|
||||||
|
"guild_id": "999",
|
||||||
|
"name": "Valid Channel"
|
||||||
|
},
|
||||||
|
"456": {
|
||||||
|
"channel_id": "456",
|
||||||
|
"guild_id": "888",
|
||||||
|
"name": "Invalid Guild"
|
||||||
|
},
|
||||||
|
"789": {
|
||||||
|
"channel_id": "789",
|
||||||
|
"guild_id": "999",
|
||||||
|
"name": "Invalid Channel"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
# Mock guild and channel
|
||||||
|
mock_guild = MagicMock()
|
||||||
|
mock_guild.id = 999
|
||||||
|
mock_channel = MagicMock()
|
||||||
|
mock_channel.id = 123
|
||||||
|
|
||||||
|
mock_bot.get_guild.side_effect = lambda guild_id: mock_guild if guild_id == 999 else None
|
||||||
|
mock_guild.get_channel.side_effect = lambda channel_id: mock_channel if channel_id == 123 else None
|
||||||
|
|
||||||
|
await cleanup_service.verify_tracked_channels(mock_bot)
|
||||||
|
|
||||||
|
# Only valid channel should remain
|
||||||
|
assert len(cleanup_service.tracker._data["voice_channels"]) == 1
|
||||||
|
assert "123" in cleanup_service.tracker._data["voice_channels"]
|
||||||
|
|
||||||
|
@pytest.mark.asyncio
|
||||||
|
async def test_check_channel_status(self, cleanup_service, mock_bot):
|
||||||
|
"""Test checking individual channel status."""
|
||||||
|
# Mock guild and channel
|
||||||
|
mock_guild = MagicMock()
|
||||||
|
mock_guild.id = 999
|
||||||
|
mock_channel = MagicMock()
|
||||||
|
mock_channel.id = 123
|
||||||
|
mock_channel.members = [] # Empty channel
|
||||||
|
|
||||||
|
mock_bot.get_guild.return_value = mock_guild
|
||||||
|
mock_guild.get_channel.return_value = mock_channel
|
||||||
|
|
||||||
|
channel_data = {
|
||||||
|
"channel_id": "123",
|
||||||
|
"guild_id": "999",
|
||||||
|
"name": "Test Channel"
|
||||||
|
}
|
||||||
|
|
||||||
|
await cleanup_service.check_channel_status(mock_bot, channel_data)
|
||||||
|
|
||||||
|
# Should have called update_channel_status with is_empty=True
|
||||||
|
tracked_data = cleanup_service.tracker.get_tracked_channel(123)
|
||||||
|
# Since the channel wasn't previously tracked, update_channel_status won't work
|
||||||
|
# This test mainly verifies the method runs without error
|
||||||
|
|
||||||
|
@pytest.mark.asyncio
|
||||||
|
async def test_cleanup_channel(self, cleanup_service, mock_bot):
|
||||||
|
"""Test cleaning up an individual channel."""
|
||||||
|
# Mock guild and channel
|
||||||
|
mock_guild = MagicMock()
|
||||||
|
mock_guild.id = 999
|
||||||
|
mock_channel = AsyncMock()
|
||||||
|
mock_channel.id = 123
|
||||||
|
mock_channel.members = [] # Empty channel
|
||||||
|
|
||||||
|
mock_bot.get_guild.return_value = mock_guild
|
||||||
|
mock_guild.get_channel.return_value = mock_channel
|
||||||
|
|
||||||
|
# Add channel to tracking first
|
||||||
|
cleanup_service.tracker._data["voice_channels"]["123"] = {
|
||||||
|
"channel_id": "123",
|
||||||
|
"guild_id": "999",
|
||||||
|
"name": "Test Channel"
|
||||||
|
}
|
||||||
|
|
||||||
|
channel_data = {
|
||||||
|
"channel_id": "123",
|
||||||
|
"guild_id": "999",
|
||||||
|
"name": "Test Channel"
|
||||||
|
}
|
||||||
|
|
||||||
|
await cleanup_service.cleanup_channel(mock_bot, channel_data)
|
||||||
|
|
||||||
|
# Should have deleted the channel
|
||||||
|
mock_channel.delete.assert_called_once_with(reason="Automatic cleanup - empty for 15+ minutes")
|
||||||
|
|
||||||
|
# Should have removed from tracking
|
||||||
|
assert "123" not in cleanup_service.tracker._data["voice_channels"]
|
||||||
|
|
||||||
|
|
||||||
|
class TestVoiceChannelCommands:
|
||||||
|
"""Test voice channel command functionality."""
|
||||||
|
|
||||||
|
@pytest.fixture
|
||||||
|
def bot(self):
|
||||||
|
"""Create a mock bot instance."""
|
||||||
|
bot = AsyncMock(spec=commands.Bot)
|
||||||
|
# Mock voice cleanup service
|
||||||
|
bot.voice_cleanup_service = MagicMock()
|
||||||
|
bot.voice_cleanup_service.tracker = MagicMock()
|
||||||
|
return bot
|
||||||
|
|
||||||
|
@pytest.fixture
|
||||||
|
def voice_cog(self, bot):
|
||||||
|
"""Create VoiceChannelCommands cog instance."""
|
||||||
|
return VoiceChannelCommands(bot)
|
||||||
|
|
||||||
|
@pytest.fixture
|
||||||
|
def mock_interaction(self):
|
||||||
|
"""Create a mock Discord interaction."""
|
||||||
|
interaction = AsyncMock(spec=discord.Interaction)
|
||||||
|
|
||||||
|
# Mock the user
|
||||||
|
user = MagicMock(spec=discord.User)
|
||||||
|
user.id = 12345
|
||||||
|
user.display_name = "TestUser"
|
||||||
|
interaction.user = user
|
||||||
|
|
||||||
|
# Mock the guild
|
||||||
|
guild = MagicMock(spec=discord.Guild)
|
||||||
|
guild.id = 67890
|
||||||
|
guild.default_role = MagicMock()
|
||||||
|
interaction.guild = guild
|
||||||
|
|
||||||
|
# Mock response methods
|
||||||
|
interaction.response.defer = AsyncMock()
|
||||||
|
interaction.followup.send = AsyncMock()
|
||||||
|
|
||||||
|
return interaction
|
||||||
|
|
||||||
|
@pytest.fixture
|
||||||
|
def mock_context(self):
|
||||||
|
"""Create a mock Discord context for prefix commands."""
|
||||||
|
ctx = AsyncMock(spec=commands.Context)
|
||||||
|
|
||||||
|
# Mock the author (user)
|
||||||
|
author = MagicMock(spec=discord.User)
|
||||||
|
author.id = 12345
|
||||||
|
author.display_name = "TestUser"
|
||||||
|
ctx.author = author
|
||||||
|
|
||||||
|
# Mock send method
|
||||||
|
ctx.send = AsyncMock()
|
||||||
|
|
||||||
|
return ctx
|
||||||
|
|
||||||
|
@pytest.mark.asyncio
|
||||||
|
async def test_create_public_channel_success(self, voice_cog, mock_interaction):
|
||||||
|
"""Test successful public channel creation."""
|
||||||
|
# Mock user team
|
||||||
|
mock_team = MagicMock(spec=Team)
|
||||||
|
mock_team.id = 1
|
||||||
|
mock_team.abbrev = "NYY"
|
||||||
|
mock_team.lname = "New York Yankees"
|
||||||
|
|
||||||
|
# Mock voice category
|
||||||
|
mock_category = MagicMock()
|
||||||
|
mock_interaction.guild.categories = [mock_category]
|
||||||
|
|
||||||
|
# Mock created channel
|
||||||
|
mock_channel = AsyncMock(spec=discord.VoiceChannel)
|
||||||
|
mock_channel.id = 999888777
|
||||||
|
mock_channel.name = "Gameplay Phoenix"
|
||||||
|
mock_channel.mention = "#gameplay-phoenix"
|
||||||
|
|
||||||
|
with patch('commands.voice.channels.team_service') as mock_team_service:
|
||||||
|
with patch.object(mock_interaction.guild, 'create_voice_channel', return_value=mock_channel) as mock_create:
|
||||||
|
with patch('commands.voice.channels.random_codename', return_value="Phoenix"):
|
||||||
|
with patch('discord.utils.get', return_value=mock_category):
|
||||||
|
mock_team_service.get_teams_by_owner.return_value = [mock_team]
|
||||||
|
|
||||||
|
await voice_cog.create_public_channel.callback(voice_cog, mock_interaction)
|
||||||
|
|
||||||
|
# Verify response was deferred
|
||||||
|
mock_interaction.response.defer.assert_called_once()
|
||||||
|
|
||||||
|
# Verify channel was created
|
||||||
|
mock_create.assert_called_once()
|
||||||
|
args, kwargs = mock_create.call_args
|
||||||
|
assert kwargs['name'] == "Gameplay Phoenix"
|
||||||
|
assert kwargs['category'] == mock_category
|
||||||
|
|
||||||
|
# Verify success message was sent
|
||||||
|
mock_interaction.followup.send.assert_called_once()
|
||||||
|
call_args = mock_interaction.followup.send.call_args
|
||||||
|
assert 'embed' in call_args.kwargs
|
||||||
|
embed = call_args.kwargs['embed']
|
||||||
|
assert "Created public voice channel" in embed.title
|
||||||
|
|
||||||
|
@pytest.mark.asyncio
|
||||||
|
async def test_create_public_channel_no_team(self, voice_cog, mock_interaction):
|
||||||
|
"""Test public channel creation with no team."""
|
||||||
|
with patch('commands.voice.channels.team_service') as mock_team_service:
|
||||||
|
mock_team_service.get_teams_by_owner.return_value = []
|
||||||
|
|
||||||
|
await voice_cog.create_public_channel.callback(voice_cog, mock_interaction)
|
||||||
|
|
||||||
|
# Verify response was deferred
|
||||||
|
mock_interaction.response.defer.assert_called_once()
|
||||||
|
|
||||||
|
# Verify error message was sent
|
||||||
|
mock_interaction.followup.send.assert_called_once()
|
||||||
|
call_args = mock_interaction.followup.send.call_args
|
||||||
|
assert call_args.kwargs['ephemeral'] is True
|
||||||
|
embed = call_args.kwargs['embed']
|
||||||
|
assert "No Team Found" in embed.title
|
||||||
|
|
||||||
|
@pytest.mark.asyncio
|
||||||
|
async def test_create_private_channel_success(self, voice_cog, mock_interaction):
|
||||||
|
"""Test successful private channel creation."""
|
||||||
|
# Mock user team
|
||||||
|
mock_user_team = MagicMock(spec=Team)
|
||||||
|
mock_user_team.id = 1
|
||||||
|
mock_user_team.abbrev = "NYY"
|
||||||
|
mock_user_team.lname = "New York Yankees"
|
||||||
|
mock_user_team.sname = "Yankees"
|
||||||
|
|
||||||
|
# Mock opponent team
|
||||||
|
mock_opponent_team = MagicMock(spec=Team)
|
||||||
|
mock_opponent_team.id = 2
|
||||||
|
mock_opponent_team.abbrev = "BOS"
|
||||||
|
mock_opponent_team.lname = "Boston Red Sox"
|
||||||
|
mock_opponent_team.sname = "Red Sox"
|
||||||
|
|
||||||
|
# Mock game
|
||||||
|
mock_game = MagicMock(spec=Game)
|
||||||
|
mock_game.week = 5
|
||||||
|
mock_game.away_team = mock_user_team
|
||||||
|
mock_game.home_team = mock_opponent_team
|
||||||
|
mock_game.is_completed = False
|
||||||
|
|
||||||
|
# Mock current league info
|
||||||
|
mock_current = MagicMock()
|
||||||
|
mock_current.season = 12
|
||||||
|
mock_current.week = 5
|
||||||
|
|
||||||
|
# Mock voice category and roles
|
||||||
|
mock_category = MagicMock()
|
||||||
|
mock_user_role = MagicMock()
|
||||||
|
mock_opponent_role = MagicMock()
|
||||||
|
|
||||||
|
# Mock created channel
|
||||||
|
mock_channel = AsyncMock(spec=discord.VoiceChannel)
|
||||||
|
mock_channel.id = 999888777
|
||||||
|
mock_channel.name = "Yankees vs Red Sox"
|
||||||
|
mock_channel.mention = "#yankees-vs-red-sox"
|
||||||
|
|
||||||
|
with patch('commands.voice.channels.team_service') as mock_team_service:
|
||||||
|
with patch('commands.voice.channels.league_service') as mock_league_service:
|
||||||
|
with patch.object(voice_cog.schedule_service, 'get_team_schedule') as mock_schedule:
|
||||||
|
with patch.object(mock_interaction.guild, 'create_voice_channel', return_value=mock_channel) as mock_create:
|
||||||
|
with patch('discord.utils.get') as mock_utils_get:
|
||||||
|
|
||||||
|
mock_team_service.get_teams_by_owner.return_value = [mock_user_team]
|
||||||
|
mock_league_service.get_current.return_value = mock_current
|
||||||
|
mock_schedule.return_value = [mock_game]
|
||||||
|
|
||||||
|
# Mock discord.utils.get calls
|
||||||
|
def mock_get(collection, **kwargs):
|
||||||
|
if 'name' in kwargs and kwargs['name'] == "Voice Channels":
|
||||||
|
return mock_category
|
||||||
|
elif 'name' in kwargs and kwargs['name'] == "New York Yankees":
|
||||||
|
return mock_user_role
|
||||||
|
elif 'name' in kwargs and kwargs['name'] == "Boston Red Sox":
|
||||||
|
return mock_opponent_role
|
||||||
|
return None
|
||||||
|
|
||||||
|
mock_utils_get.side_effect = mock_get
|
||||||
|
|
||||||
|
await voice_cog.create_private_channel.callback(voice_cog, mock_interaction)
|
||||||
|
|
||||||
|
# Verify response was deferred
|
||||||
|
mock_interaction.response.defer.assert_called_once()
|
||||||
|
|
||||||
|
# Verify channel was created
|
||||||
|
mock_create.assert_called_once()
|
||||||
|
args, kwargs = mock_create.call_args
|
||||||
|
assert kwargs['name'] == "Yankees vs Red Sox"
|
||||||
|
assert kwargs['category'] == mock_category
|
||||||
|
|
||||||
|
# Verify success message was sent
|
||||||
|
mock_interaction.followup.send.assert_called_once()
|
||||||
|
call_args = mock_interaction.followup.send.call_args
|
||||||
|
assert 'embed' in call_args.kwargs
|
||||||
|
embed = call_args.kwargs['embed']
|
||||||
|
assert "Private Voice Channel Created" in embed.title
|
||||||
|
|
||||||
|
@pytest.mark.asyncio
|
||||||
|
async def test_deprecated_vc_command(self, voice_cog, mock_context):
|
||||||
|
"""Test deprecated !vc command shows migration message."""
|
||||||
|
await voice_cog.deprecated_public_voice.callback(voice_cog, mock_context)
|
||||||
|
|
||||||
|
# Verify migration message was sent
|
||||||
|
mock_context.send.assert_called_once()
|
||||||
|
call_args = mock_context.send.call_args
|
||||||
|
embed = call_args.kwargs['embed']
|
||||||
|
assert "Command Deprecated" in embed.title
|
||||||
|
assert "/voice-channel public" in embed.description
|
||||||
|
|
||||||
|
@pytest.mark.asyncio
|
||||||
|
async def test_deprecated_private_command(self, voice_cog, mock_context):
|
||||||
|
"""Test deprecated !private command shows migration message."""
|
||||||
|
await voice_cog.deprecated_private_voice.callback(voice_cog, mock_context)
|
||||||
|
|
||||||
|
# Verify migration message was sent
|
||||||
|
mock_context.send.assert_called_once()
|
||||||
|
call_args = mock_context.send.call_args
|
||||||
|
embed = call_args.kwargs['embed']
|
||||||
|
assert "Command Deprecated" in embed.title
|
||||||
|
assert "/voice-channel private" in embed.description
|
||||||
|
|
||||||
|
def test_random_codename_generation(self):
|
||||||
|
"""Test that random codename generation works."""
|
||||||
|
from commands.voice.channels import random_codename, CODENAMES
|
||||||
|
|
||||||
|
# Generate multiple codenames
|
||||||
|
generated = [random_codename() for _ in range(10)]
|
||||||
|
|
||||||
|
# All should be from the codenames list
|
||||||
|
for codename in generated:
|
||||||
|
assert codename in CODENAMES
|
||||||
|
|
||||||
|
# Should have some variety (unlikely all same)
|
||||||
|
unique_names = set(generated)
|
||||||
|
assert len(unique_names) > 1 # Should have at least some variety
|
||||||
|
|
||||||
|
def test_voice_group_attributes(self, voice_cog):
|
||||||
|
"""Test that voice command group has correct attributes."""
|
||||||
|
assert hasattr(voice_cog, 'voice_group')
|
||||||
|
assert voice_cog.voice_group.name == "voice-channel"
|
||||||
|
assert voice_cog.voice_group.description == "Create voice channels for gameplay"
|
||||||
|
|
||||||
|
def test_command_attributes(self, voice_cog):
|
||||||
|
"""Test that commands have correct attributes."""
|
||||||
|
# Test prefix commands exist
|
||||||
|
assert hasattr(voice_cog, 'deprecated_public_voice')
|
||||||
|
assert hasattr(voice_cog, 'deprecated_private_voice')
|
||||||
|
|
||||||
|
# Check command names and aliases
|
||||||
|
public_cmd = voice_cog.deprecated_public_voice
|
||||||
|
assert public_cmd.name == "vc"
|
||||||
|
assert public_cmd.aliases == ["voice", "gameplay"]
|
||||||
|
|
||||||
|
private_cmd = voice_cog.deprecated_private_voice
|
||||||
|
assert private_cmd.name == "private"
|
||||||
423
views/README.md
Normal file
423
views/README.md
Normal file
@ -0,0 +1,423 @@
|
|||||||
|
# Views Directory
|
||||||
|
|
||||||
|
The views directory contains Discord UI components for Discord Bot v2.0, providing consistent visual interfaces and interactive elements. This includes embeds, modals, buttons, select menus, and other Discord UI components.
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
### Component-Based UI Design
|
||||||
|
Views in Discord Bot v2.0 follow these principles:
|
||||||
|
- **Consistent styling** via centralized templates
|
||||||
|
- **Reusable components** for common UI patterns
|
||||||
|
- **Error handling** with graceful degradation
|
||||||
|
- **User interaction tracking** and validation
|
||||||
|
- **Accessibility** with proper labeling and feedback
|
||||||
|
|
||||||
|
### Base Components
|
||||||
|
All view components inherit from Discord.py base classes with enhanced functionality:
|
||||||
|
- **BaseView** - Enhanced discord.ui.View with logging and user validation
|
||||||
|
- **BaseModal** - Enhanced discord.ui.Modal with error handling
|
||||||
|
- **EmbedTemplate** - Centralized embed creation with consistent styling
|
||||||
|
|
||||||
|
## View Components
|
||||||
|
|
||||||
|
### Base View System (`base.py`)
|
||||||
|
|
||||||
|
#### BaseView Class
|
||||||
|
Foundation for all interactive views:
|
||||||
|
|
||||||
|
```python
|
||||||
|
class BaseView(discord.ui.View):
|
||||||
|
def __init__(self, timeout=180.0, user_id=None):
|
||||||
|
super().__init__(timeout=timeout)
|
||||||
|
self.user_id = user_id
|
||||||
|
self.logger = get_contextual_logger(f'{__name__}.BaseView')
|
||||||
|
|
||||||
|
async def interaction_check(self, interaction) -> bool:
|
||||||
|
"""Validate user permissions for interaction."""
|
||||||
|
|
||||||
|
async def on_timeout(self) -> None:
|
||||||
|
"""Handle view timeout gracefully."""
|
||||||
|
|
||||||
|
async def on_error(self, interaction, error, item) -> None:
|
||||||
|
"""Handle view errors with user feedback."""
|
||||||
|
```
|
||||||
|
|
||||||
|
#### ConfirmationView Class
|
||||||
|
Standard Yes/No confirmation dialogs:
|
||||||
|
|
||||||
|
```python
|
||||||
|
confirmation = ConfirmationView(
|
||||||
|
user_id=interaction.user.id,
|
||||||
|
confirm_callback=handle_confirm,
|
||||||
|
cancel_callback=handle_cancel
|
||||||
|
)
|
||||||
|
await interaction.followup.send("Confirm action?", view=confirmation)
|
||||||
|
```
|
||||||
|
|
||||||
|
#### PaginationView Class
|
||||||
|
Multi-page navigation for large datasets:
|
||||||
|
|
||||||
|
```python
|
||||||
|
pages = [embed1, embed2, embed3]
|
||||||
|
pagination = PaginationView(
|
||||||
|
pages=pages,
|
||||||
|
user_id=interaction.user.id,
|
||||||
|
show_page_numbers=True
|
||||||
|
)
|
||||||
|
await interaction.followup.send(embed=pagination.get_current_embed(), view=pagination)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Embed Templates (`embeds.py`)
|
||||||
|
|
||||||
|
#### EmbedTemplate Class
|
||||||
|
Centralized embed creation with consistent styling:
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Success embed
|
||||||
|
embed = EmbedTemplate.success(
|
||||||
|
title="Operation Completed",
|
||||||
|
description="Your request was processed successfully."
|
||||||
|
)
|
||||||
|
|
||||||
|
# Error embed
|
||||||
|
embed = EmbedTemplate.error(
|
||||||
|
title="Operation Failed",
|
||||||
|
description="Please check your input and try again."
|
||||||
|
)
|
||||||
|
|
||||||
|
# Warning embed
|
||||||
|
embed = EmbedTemplate.warning(
|
||||||
|
title="Careful!",
|
||||||
|
description="This action cannot be undone."
|
||||||
|
)
|
||||||
|
|
||||||
|
# Info embed
|
||||||
|
embed = EmbedTemplate.info(
|
||||||
|
title="Information",
|
||||||
|
description="Here's what you need to know."
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
#### EmbedColors Dataclass
|
||||||
|
Consistent color scheme across all embeds:
|
||||||
|
|
||||||
|
```python
|
||||||
|
@dataclass(frozen=True)
|
||||||
|
class EmbedColors:
|
||||||
|
PRIMARY: int = 0xa6ce39 # SBA green
|
||||||
|
SUCCESS: int = 0x28a745 # Green
|
||||||
|
WARNING: int = 0xffc107 # Yellow
|
||||||
|
ERROR: int = 0xdc3545 # Red
|
||||||
|
INFO: int = 0x17a2b8 # Blue
|
||||||
|
SECONDARY: int = 0x6c757d # Gray
|
||||||
|
```
|
||||||
|
|
||||||
|
### Modal Forms (`modals.py`)
|
||||||
|
|
||||||
|
#### BaseModal Class
|
||||||
|
Foundation for interactive forms:
|
||||||
|
|
||||||
|
```python
|
||||||
|
class BaseModal(discord.ui.Modal):
|
||||||
|
def __init__(self, title: str, timeout=300.0):
|
||||||
|
super().__init__(title=title, timeout=timeout)
|
||||||
|
self.logger = get_contextual_logger(f'{__name__}.BaseModal')
|
||||||
|
self.result = None
|
||||||
|
|
||||||
|
async def on_submit(self, interaction):
|
||||||
|
"""Handle form submission."""
|
||||||
|
|
||||||
|
async def on_error(self, interaction, error):
|
||||||
|
"""Handle form errors."""
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Usage Pattern
|
||||||
|
```python
|
||||||
|
class CustomCommandModal(BaseModal):
|
||||||
|
def __init__(self):
|
||||||
|
super().__init__(title="Create Custom Command")
|
||||||
|
|
||||||
|
name = discord.ui.TextInput(
|
||||||
|
label="Command Name",
|
||||||
|
placeholder="Enter command name...",
|
||||||
|
required=True,
|
||||||
|
max_length=50
|
||||||
|
)
|
||||||
|
|
||||||
|
response = discord.ui.TextInput(
|
||||||
|
label="Response",
|
||||||
|
placeholder="Enter command response...",
|
||||||
|
style=discord.TextStyle.paragraph,
|
||||||
|
required=True,
|
||||||
|
max_length=2000
|
||||||
|
)
|
||||||
|
|
||||||
|
async def on_submit(self, interaction):
|
||||||
|
# Process form data
|
||||||
|
command_data = {
|
||||||
|
"name": self.name.value,
|
||||||
|
"response": self.response.value
|
||||||
|
}
|
||||||
|
# Handle creation logic
|
||||||
|
```
|
||||||
|
|
||||||
|
### Common UI Elements (`common.py`)
|
||||||
|
|
||||||
|
#### Shared Components
|
||||||
|
- **Loading indicators** for async operations
|
||||||
|
- **Status messages** for operation feedback
|
||||||
|
- **Navigation elements** for multi-step processes
|
||||||
|
- **Validation displays** for form errors
|
||||||
|
|
||||||
|
### Specialized Views
|
||||||
|
|
||||||
|
#### Custom Commands (`custom_commands.py`)
|
||||||
|
Views specific to custom command management:
|
||||||
|
- Command creation forms
|
||||||
|
- Command listing with actions
|
||||||
|
- Bulk management interfaces
|
||||||
|
|
||||||
|
#### Transaction Management (`transaction_embed.py`)
|
||||||
|
Views for player transaction interfaces:
|
||||||
|
- Transaction proposal forms
|
||||||
|
- Approval/rejection workflows
|
||||||
|
- Transaction history displays
|
||||||
|
|
||||||
|
## Styling Guidelines
|
||||||
|
|
||||||
|
### Embed Consistency
|
||||||
|
All embeds should use EmbedTemplate methods:
|
||||||
|
|
||||||
|
```python
|
||||||
|
# ✅ Consistent styling
|
||||||
|
embed = EmbedTemplate.success("Player Added", "Player successfully added to roster")
|
||||||
|
|
||||||
|
# ❌ Inconsistent styling
|
||||||
|
embed = discord.Embed(title="Player Added", color=0x00ff00)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Color Usage
|
||||||
|
Use the standard color palette:
|
||||||
|
- **PRIMARY (SBA Green)** - Default for neutral information
|
||||||
|
- **SUCCESS (Green)** - Successful operations
|
||||||
|
- **ERROR (Red)** - Errors and failures
|
||||||
|
- **WARNING (Yellow)** - Warnings and cautions
|
||||||
|
- **INFO (Blue)** - General information
|
||||||
|
- **SECONDARY (Gray)** - Less important information
|
||||||
|
|
||||||
|
### User Feedback
|
||||||
|
Provide clear feedback for all user interactions:
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Loading state
|
||||||
|
embed = EmbedTemplate.info("Processing", "Please wait while we process your request...")
|
||||||
|
|
||||||
|
# Success state
|
||||||
|
embed = EmbedTemplate.success("Complete", "Your request has been processed successfully.")
|
||||||
|
|
||||||
|
# Error state with helpful information
|
||||||
|
embed = EmbedTemplate.error(
|
||||||
|
"Request Failed",
|
||||||
|
"The player name was not found. Please check your spelling and try again."
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Interactive Components
|
||||||
|
|
||||||
|
### Button Patterns
|
||||||
|
|
||||||
|
#### Action Buttons
|
||||||
|
```python
|
||||||
|
@discord.ui.button(label="Confirm", style=discord.ButtonStyle.success, emoji="✅")
|
||||||
|
async def confirm_button(self, interaction, button):
|
||||||
|
self.increment_interaction_count()
|
||||||
|
# Handle confirmation
|
||||||
|
await interaction.response.edit_message(content="Confirmed!", view=None)
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Navigation Buttons
|
||||||
|
```python
|
||||||
|
@discord.ui.button(emoji="◀️", style=discord.ButtonStyle.primary)
|
||||||
|
async def previous_page(self, interaction, button):
|
||||||
|
self.current_page = max(0, self.current_page - 1)
|
||||||
|
await interaction.response.edit_message(embed=self.get_current_embed(), view=self)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Select Menu Patterns
|
||||||
|
|
||||||
|
#### Option Selection
|
||||||
|
```python
|
||||||
|
@discord.ui.select(placeholder="Choose an option...")
|
||||||
|
async def select_option(self, interaction, select):
|
||||||
|
selected_value = select.values[0]
|
||||||
|
# Handle selection
|
||||||
|
await interaction.response.send_message(f"You selected: {selected_value}")
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Dynamic Options
|
||||||
|
```python
|
||||||
|
class PlayerSelectMenu(discord.ui.Select):
|
||||||
|
def __init__(self, players: List[Player]):
|
||||||
|
options = [
|
||||||
|
discord.SelectOption(
|
||||||
|
label=player.name,
|
||||||
|
value=str(player.id),
|
||||||
|
description=f"{player.position} - {player.team.abbrev}"
|
||||||
|
)
|
||||||
|
for player in players[:25] # Discord limit
|
||||||
|
]
|
||||||
|
super().__init__(placeholder="Select a player...", options=options)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
### View Error Handling
|
||||||
|
All views implement comprehensive error handling:
|
||||||
|
|
||||||
|
```python
|
||||||
|
async def on_error(self, interaction, error, item):
|
||||||
|
"""Handle view errors gracefully."""
|
||||||
|
self.logger.error("View error", error=error, item_type=type(item).__name__)
|
||||||
|
|
||||||
|
try:
|
||||||
|
embed = EmbedTemplate.error(
|
||||||
|
"Interaction Error",
|
||||||
|
"Something went wrong. Please try again."
|
||||||
|
)
|
||||||
|
|
||||||
|
if not interaction.response.is_done():
|
||||||
|
await interaction.response.send_message(embed=embed, ephemeral=True)
|
||||||
|
else:
|
||||||
|
await interaction.followup.send(embed=embed, ephemeral=True)
|
||||||
|
except Exception as e:
|
||||||
|
self.logger.error("Failed to send error message", error=e)
|
||||||
|
```
|
||||||
|
|
||||||
|
### User Input Validation
|
||||||
|
Forms validate user input before processing:
|
||||||
|
|
||||||
|
```python
|
||||||
|
async def on_submit(self, interaction):
|
||||||
|
# Validate input
|
||||||
|
if len(self.name.value) < 2:
|
||||||
|
embed = EmbedTemplate.error(
|
||||||
|
"Invalid Input",
|
||||||
|
"Command name must be at least 2 characters long."
|
||||||
|
)
|
||||||
|
await interaction.response.send_message(embed=embed, ephemeral=True)
|
||||||
|
return
|
||||||
|
|
||||||
|
# Process valid input
|
||||||
|
await self.create_command(interaction)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Accessibility Features
|
||||||
|
|
||||||
|
### User-Friendly Labels
|
||||||
|
- **Clear button labels** with descriptive text
|
||||||
|
- **Helpful placeholders** in form fields
|
||||||
|
- **Descriptive error messages** with actionable guidance
|
||||||
|
- **Consistent emoji usage** for visual recognition
|
||||||
|
|
||||||
|
### Permission Validation
|
||||||
|
Views respect user permissions and provide appropriate feedback:
|
||||||
|
|
||||||
|
```python
|
||||||
|
async def interaction_check(self, interaction) -> bool:
|
||||||
|
"""Check if user can interact with this view."""
|
||||||
|
if self.user_id and interaction.user.id != self.user_id:
|
||||||
|
await interaction.response.send_message(
|
||||||
|
"❌ You cannot interact with this menu.",
|
||||||
|
ephemeral=True
|
||||||
|
)
|
||||||
|
return False
|
||||||
|
return True
|
||||||
|
```
|
||||||
|
|
||||||
|
## Performance Considerations
|
||||||
|
|
||||||
|
### View Lifecycle Management
|
||||||
|
- **Timeout handling** prevents orphaned views
|
||||||
|
- **Resource cleanup** in view destructors
|
||||||
|
- **Interaction tracking** for usage analytics
|
||||||
|
- **Memory management** for large datasets
|
||||||
|
|
||||||
|
### Efficient Updates
|
||||||
|
```python
|
||||||
|
# ✅ Efficient - Only update what changed
|
||||||
|
await interaction.response.edit_message(embed=new_embed, view=self)
|
||||||
|
|
||||||
|
# ❌ Inefficient - Sends new message
|
||||||
|
await interaction.response.send_message(embed=new_embed, view=new_view)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Testing Strategies
|
||||||
|
|
||||||
|
### View Testing
|
||||||
|
```python
|
||||||
|
@pytest.mark.asyncio
|
||||||
|
async def test_confirmation_view():
|
||||||
|
view = ConfirmationView(user_id=123)
|
||||||
|
|
||||||
|
# Mock interaction
|
||||||
|
interaction = Mock()
|
||||||
|
interaction.user.id = 123
|
||||||
|
|
||||||
|
# Test button click
|
||||||
|
await view.confirm_button.callback(interaction)
|
||||||
|
|
||||||
|
assert view.result is True
|
||||||
|
```
|
||||||
|
|
||||||
|
### Modal Testing
|
||||||
|
```python
|
||||||
|
@pytest.mark.asyncio
|
||||||
|
async def test_custom_command_modal():
|
||||||
|
modal = CustomCommandModal()
|
||||||
|
|
||||||
|
# Set form values
|
||||||
|
modal.name.value = "test"
|
||||||
|
modal.response.value = "Test response"
|
||||||
|
|
||||||
|
# Mock interaction
|
||||||
|
interaction = Mock()
|
||||||
|
|
||||||
|
# Test form submission
|
||||||
|
await modal.on_submit(interaction)
|
||||||
|
|
||||||
|
# Verify processing
|
||||||
|
assert modal.result is not None
|
||||||
|
```
|
||||||
|
|
||||||
|
## Development Guidelines
|
||||||
|
|
||||||
|
### Creating New Views
|
||||||
|
1. **Inherit from base classes** for consistency
|
||||||
|
2. **Use EmbedTemplate** for all embed creation
|
||||||
|
3. **Implement proper error handling** in all interactions
|
||||||
|
4. **Add user permission checks** where appropriate
|
||||||
|
5. **Include comprehensive logging** with context
|
||||||
|
6. **Follow timeout patterns** to prevent resource leaks
|
||||||
|
|
||||||
|
### View Composition
|
||||||
|
- **Keep views focused** on single responsibilities
|
||||||
|
- **Use composition** over complex inheritance
|
||||||
|
- **Separate business logic** from UI logic
|
||||||
|
- **Make views testable** with dependency injection
|
||||||
|
|
||||||
|
### UI Guidelines
|
||||||
|
- **Follow Discord design patterns** for familiarity
|
||||||
|
- **Use consistent colors** from EmbedColors
|
||||||
|
- **Provide clear user feedback** for all actions
|
||||||
|
- **Handle edge cases** gracefully
|
||||||
|
- **Consider mobile users** in layout design
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Next Steps for AI Agents:**
|
||||||
|
1. Review existing view implementations for patterns
|
||||||
|
2. Understand the Discord UI component system
|
||||||
|
3. Follow the EmbedTemplate system for consistent styling
|
||||||
|
4. Implement proper error handling and user validation
|
||||||
|
5. Test interactive components thoroughly
|
||||||
|
6. Consider accessibility and user experience in design
|
||||||
Loading…
Reference in New Issue
Block a user