Merge pull request #94 from VEAF/feat-enhance-rest-api-from-development

feat: enhanced restapi with weather information (/servers) and server attendance statistics (/server_attendance).

Author: karel26

.gitignore

@@ -19,3 +19,4 @@ Scripts/net/DCSServerBot/DCSServerBotConfig.lua
 /logs/
 /config/
 /.emmyrc.json
+.copilot-docs/*

plugins/restapi/CHANGELOG.md

@@ -0,0 +1,125 @@
+# REST API Plugin Changelog
+
+This document tracks all notable changes made to the REST API plugin.
+
+## [Unreleased] - 2025-12-26
+
+### 🆕 Added
+
+#### Weather Integration in `/servers` Endpoint
+- **Comprehensive weather data**: Temperature, wind speed/direction, pressure, visibility, cloud coverage
+- **Real-time DCS integration**: Weather extracted from active mission weather system  
+- **Configurable**: Control via `include_weather` setting (default: true)
+
+#### New `/server_attendance` Endpoint
+- **Multi-period analytics**: 24h, 7d, 30d player statistics with Discord member engagement
+- **Enhanced server insights**: Top theatres, missions, and modules by playtime and usage
+- **Combat statistics**: Total sorties, kills, deaths, PvP metrics from mv_serverstats
+- **Daily trends**: 7-day player activity trends for graphing
+- **Inspired by Discord `/serverstats`**: Comprehensive data matching monitoring plugin functionality
+
+#### Configuration Options
+- `include_weather: true/false` - Toggle weather in server responses
+- `server_attendance.enabled: true/false` - Enable attendance analytics endpoint
+
+### 🔄 Changed  
+
+#### Centralized Server Name Resolution
+- **Unified server handling**: All endpoints now use centralized `get_resolved_server()` method
+- **Alias support**: Endpoints support both instance aliases (nodes.yaml) and full DCS server names (servers.yaml)  
+- **Affected endpoints**: `/serverstats`, `/leaderboard`, `/topkills`, `/topkdr`, `/trueskill`, `/highscore`, `/weaponpk`, `/stats`, `/modulestats`, `/traps`, `/server_attendance`
+
+#### Code Architecture Improvements
+- **Simplified SQL construction**: Removed overly complex `get_server_where_clause_and_params()` helper
+- **Readable patterns**: Straightforward conditional SQL with direct parameter passing
+- **Better maintainability**: Clear, transparent code structure while preserving functionality
+
+### 🐛 Fixed
+
+#### Endpoint Corrections
+- **`/modulestats` endpoint**: Fixed incorrect method mapping (`self.stats` → `self.modulestats`) and response model (`ModuleStats` → `list[ModuleStats]`)
+- **SQL syntax errors**: Resolved parameter binding issues in database queries
+- **Weather data extraction**: Corrected data structure parsing from DCS mission weather
+
+#### Data Model Validation  
+- **Response validation**: Fixed Pydantic model validation errors
+- **Type consistency**: Proper typing for all new data structures
+
+### 📊 Enhanced Data Models
+
+#### New Pydantic Models
+```python
+# Weather information
+class WeatherInfo(BaseModel):
+    temperature: float | None
+    wind_speed: float | None  
+    wind_direction: int | None
+    pressure: float | None
+    visibility: float | None
+    cloud_coverage: str | None
+
+# Top statistics for server attendance
+class TopTheatre(BaseModel):
+    theatre: str
+    playtime_hours: int
+
+class TopMission(BaseModel):
+    mission_name: str
+    playtime_hours: int
+    
+class TopModule(BaseModel):
+    module: str
+    playtime_hours: int
+    unique_players: int
+    total_uses: int
+
+# Enhanced server attendance with comprehensive analytics
+class ServerAttendanceStats(BaseModel):
+    current_players: int
+    unique_players_24h: int
+    total_playtime_hours_24h: float
+    discord_members_24h: int
+    unique_players_7d: int  
+    total_playtime_hours_7d: float
+    discord_members_7d: int
+    unique_players_30d: int
+    total_playtime_hours_30d: float
+    discord_members_30d: int
+    daily_trend: list[dict]
+    top_theatres: list[TopTheatre]
+    top_missions: list[TopMission]  
+    top_modules: list[TopModule]
+    total_sorties: int | None
+    total_kills: int | None
+    total_deaths: int | None
+    total_pvp_kills: int | None
+    total_pvp_deaths: int | None
+```
+
+### 🚀 Performance & Technical Details
+
+#### Database Integration
+- **Monitoring plugin patterns**: Leverages existing monitoring infrastructure SQL queries
+- **Materialized views**: Efficient use of `mv_serverstats` for performance
+- **Optimized queries**: Following established DCS server integration patterns
+
+#### Backward Compatibility
+- **Zero breaking changes**: All existing API consumers continue working unchanged
+- **Opt-in features**: New functionality enabled by default but configurable
+- **Migration-free**: No configuration changes required for existing setups
+
+### 📈 Impact
+
+#### For API Consumers
+- **Richer server data**: Weather and comprehensive attendance analytics
+- **Better server identification**: Flexible server name resolution (aliases + full names)
+- **Enhanced dashboards**: More detailed metrics for monitoring and visualization
+
+#### For Developers  
+- **Cleaner codebase**: Simplified, maintainable SQL construction patterns
+- **Consistent patterns**: Unified server resolution across all endpoints
+- **Better documentation**: Complete API models with examples and validation
+
+---
+
+**Summary**: This release significantly enhances the REST API plugin with comprehensive server analytics, weather integration, and improved code architecture while maintaining full backward compatibility.

plugins/restapi/README.md

@@ -19,6 +19,9 @@ DEFAULT:
       filter:               # config parameter (in this case, the server filter list)
         - 'MyPrivateServer' # Do not show a server named "MyPrivateServer"
         - '(.*)Private(.*)' # Do not show any server that has "Private" in its name 
+      include_weather: true # Include weather information in /servers endpoint (default: true)
+    server_attendance:      # /server_attendance 
+      enabled: true         # Enable the server attendance statistics endpoint (default: true)
 ```
 
 > [!WARNING]
@@ -30,7 +33,8 @@ The following commands are available through the API
 | API               | GET / POST | Parameters                                            | Description                                                                           |
 |-------------------|------------|-------------------------------------------------------|---------------------------------------------------------------------------------------|
 | /serverstats      | GET        |                                                       | A comprehensive statistic for your whole setup.                                       |
-| /servers          | GET        |                                                       | Status for each server.                                                               |
+| /servers          | GET        |                                                       | Status for each server, including weather information if enabled.                     |
+| /server_attendance| GET        | [server_name: string]                                 | Comprehensive server attendance statistics, top theatres/missions/modules, and daily trends. |
 | /getuser          | POST       | nick: string                                          | Return a list of players ordered by last seen that match this nick.                   |
 | /stats            | POST       | nick: string, date: date                              | Statistics of this player                                                             |
 | /highscore        | GET        | [server_name: string], [period: string], [limit: int] | Highscore output                                                                      |
@@ -48,3 +52,79 @@ The following commands are available through the API
 > [!NOTE]
 > To get more detailled API documentation, please enable debug in your WebService config and 
 > access https://localhost:9876/docs.
+
+## New Features
+
+### Weather Information
+The `/servers` endpoint now includes real-time weather data for running DCS servers:
+```json
+{
+  "weather": {
+    "temperature": 16.0,
+    "wind_speed": 0.968,
+    "wind_direction": 290,
+    "pressure": 765.0,
+    "visibility": 5000,
+    "clouds_base": 0,
+    "clouds_density": 0,
+    "precipitation": 0,
+    "fog_enabled": false,
+    "dust_enabled": false
+  }
+}
+```
+
+### Server Attendance Statistics
+The `/server_attendance` endpoint provides comprehensive server attendance analytics:
+
+- **Server attendance statistics**: Current active players, unique players, total playtime hours, and Discord member engagement for different time periods (24h, 7d, 30d)
+- **Top statistics**: Most popular theatres, missions, and modules by playtime and usage
+- **Daily trends**: Daily unique player counts for the last 7 days to analyze server activity patterns
+- **Combat statistics**: Total sorties, kills, deaths, and PvP statistics from mv_serverstats
+
+**Global statistics (no parameters):**
+```bash
+GET /server_attendance
+```
+
+**Server-specific statistics (using DCS server name):**
+```bash
+GET /server_attendance?server_name=VEAF (www.veaf.org) [fr] - Private Foothold 2
+```
+
+**Server-specific statistics (using instance alias):**
+```bash
+GET /server_attendance?server_name=foothold2_server
+```
+
+**Response example:**
+```json
+{
+  "current_players": 8,
+  "unique_players_24h": 15,
+  "total_playtime_hours_24h": 45.5,
+  "discord_members_24h": 12,
+  "unique_players_7d": 35,
+  "total_playtime_hours_7d": 180.2,
+  "discord_members_7d": 28,
+  "unique_players_30d": 85,
+  "total_playtime_hours_30d": 720.8,
+  "discord_members_30d": 65,
+  "daily_trend": [
+    {"date": "2025-12-24", "unique_players": 15},
+    {"date": "2025-12-25", "unique_players": 18}
+  ]
+}
+```
+
+### Server Name Resolution
+All endpoints that accept a `server_name` parameter now support both server naming conventions seamlessly:
+- **Instance alias**: `foothold2_server` (from nodes.yaml configuration)
+- **DCS server name**: `VEAF (www.veaf.org) [fr] - Private Foothold 2` (from servers.yaml configuration)
+
+The resolution is handled transparently by the `get_resolved_server()` method, which:
+1. Checks if the provided name is already a full DCS server name
+2. If not, searches instance aliases and returns the corresponding DCS server name
+3. Returns both the resolved name and server object for use in endpoints
+
+This approach ensures consistent behavior across all endpoints while maintaining simple, readable SQL construction patterns.