diff --git a/docs/core/tasks.md b/docs/core/tasks.md index c375308..7d3a8ce 100644 --- a/docs/core/tasks.md +++ b/docs/core/tasks.md @@ -2591,6 +2591,52 @@ Keeping all support in one place (Discord) so Meg and staff only have one queue --- +### 86. Whitelist Manager - Panel v1.12.1 API Compatibility Fix +**Time:** 1-2 hours +**Status:** 🔵 TO DO — BROKEN (needs fix when home) +**Priority:** Tier 3 — Enhancement (workaround exists) +**Documentation:** `docs/tasks/whitelist-manager-v1-12-compatibility/` + +**⚠️ CRITICAL: Always check Whitelist Manager after Panel or Wings updates!** + +**Problem:** +- Whitelist Manager built against Panel v1.11.x API (February 2026) +- Panel upgraded to v1.12.1 on March 13, 2026 +- API response format changed +- All servers showing "UNKNOWN" status +- Server grouping broken (wrong counts, unknown group appeared) + +**Root Cause:** +Python code still parsing old v1.11.x API format. Needs update to handle v1.12.1 response structure. + +**Impact:** +- ❌ Status detection broken (cosmetic) +- ✅ Core functions likely still work (add/remove player) +- ✅ Workaround: Use Panel console directly + +**Fix:** +1. SSH to Billing VPS (38.68.14.188) +2. Review Whitelist Manager Python code +3. Update API response parsing (v1.11.x → v1.12.1 format) +4. Test with live servers +5. Restart service +6. Verify all servers show correct status + +**Likely code change:** +- `server['attributes']['feature_limits']['whitelist']` → `server['attributes']['limits']['whitelist_enabled']` +- Add fallback for both formats +- Better error handling + +**Prevention:** +Add to Panel update checklist: "Verify Whitelist Manager functionality after ANY Panel/Wings update. Test server status detection. Reference Task #86 if broken." + +**Workaround Until Fixed:** +Use Pterodactyl Panel console at panel.firefrostgaming.com → Console tab → `whitelist add/remove ` + +**See task directory for complete fix procedure, API format comparison, and prevention checklist.** + +--- + --- diff --git a/docs/tasks/whitelist-manager-v1-12-compatibility/README.md b/docs/tasks/whitelist-manager-v1-12-compatibility/README.md new file mode 100644 index 0000000..1c5d66c --- /dev/null +++ b/docs/tasks/whitelist-manager-v1-12-compatibility/README.md @@ -0,0 +1,487 @@ +# Task #86: Whitelist Manager - Panel v1.12.1 API Compatibility Fix + +**Status:** IDENTIFIED - Ready to fix +**Owner:** Michael "Frostystyle" Krause +**Priority:** Tier 3 - Enhancement (workaround exists) +**Created:** March 30, 2026 +**Time Estimate:** 1-2 hours + +--- + +## ⚠️ CRITICAL REMINDER + +**ALWAYS check Whitelist Manager after Panel or Wings updates!** + +Pterodactyl API format can change between versions. When you update Panel or Wings, immediately verify Whitelist Manager is still functioning correctly. + +**Quick check after updates:** +1. Visit whitelist.firefrostgaming.com +2. Verify server statuses show correctly (not all "UNKNOWN") +3. Test add/remove player on one server +4. Check Recent Activity log + +If broken, refer to this task for fix procedure. + +--- + +## Problem Statement + +**What's Broken:** +- Whitelist Manager dashboard at whitelist.firefrostgaming.com +- All servers showing "UNKNOWN" status +- Status badges not displaying (WHITELISTED/PUBLIC/OFF) +- Server grouping incorrect (wrong counts, unknown servers) + +**Root Cause:** +- Whitelist Manager built against Pterodactyl Panel v1.11.x API (February 2026) +- Panel upgraded to v1.12.1 on March 13, 2026 +- API response format changed between versions +- Python code still parsing old v1.11.x format +- Status detection code failing silently + +**Impact:** +- ⚠️ Status detection broken (cosmetic) +- ✅ Core functions likely still work (add/remove player) +- ✅ Workaround available (use Panel console directly) + +--- + +## Screenshots + +**Current broken state (March 30, 2026):** +- All servers: "UNKNOWN" status +- TX1 shows "5 servers" but lists more +- NC1 shows "2 servers" but has more +- "Unknown (4 servers)" group appeared +- Recent Activity still logging (service running) + +--- + +## Technical Details + +### What Changed in Panel v1.12.1 + +**API response structure changed.** + +**v1.11.x format (what Whitelist Manager expects):** +```json +{ + "attributes": { + "name": "Stoneblock 4 - TX", + "feature_limits": { + "whitelist": true + }, + "environment": { + "WHITELIST_ENABLED": "true" + } + } +} +``` + +**v1.12.1 format (what Panel now returns - SUSPECTED):** +```json +{ + "attributes": { + "name": "Stoneblock 4 - TX", + "limits": { + "whitelist_enabled": true + }, + "container": { + "environment": { + "WHITELIST_ENABLED": "true" + } + } + } +} +``` + +**Key changes:** +- `feature_limits` → `limits` +- `whitelist` → `whitelist_enabled` +- `environment` moved under `container` +- Possible: field names changed (camelCase vs snake_case) + +### Where the Code Is Broken + +**Location:** Billing VPS (38.68.14.188) +**Service:** whitelist-manager (systemd) +**Code location:** `/opt/whitelist-manager/` or `/var/www/whitelist-manager/` (verify) + +**Files likely affected:** +1. Main Flask app (app.py, whitelist.py, or main.py) +2. Pterodactyl API integration module +3. Server status detection function +4. Server grouping logic + +**Specific functions to check:** +- `get_server_status(server)` - status detection +- `parse_server_response(data)` - API parsing +- `group_servers_by_node(servers)` - grouping logic + +--- + +## Fix Procedure + +### Step 1: Access Billing VPS + +```bash +ssh architect@38.68.14.188 +``` + +### Step 2: Locate Whitelist Manager Code + +```bash +# Common locations +ls -la /opt/whitelist-manager/ +ls -la /var/www/whitelist-manager/ +ls -la /home/architect/whitelist-manager/ + +# Or find it +sudo find / -name "whitelist*" -type d 2>/dev/null | grep -v node_modules +``` + +### Step 3: Check Service Logs + +```bash +# View recent errors +sudo journalctl -u whitelist-manager -n 100 --no-pager + +# Filter for API errors +sudo journalctl -u whitelist-manager | grep -i "error\|fail\|api" | tail -50 + +# Look for KeyError or AttributeError (common in dict parsing) +sudo journalctl -u whitelist-manager | grep -i "KeyError\|AttributeError" | tail -20 +``` + +### Step 4: Test Pterodactyl API Manually + +```bash +# Get Panel API key from environment or config +sudo cat /opt/whitelist-manager/.env | grep PTERODACTYL_API_KEY +# Or +sudo systemctl show whitelist-manager | grep API_KEY + +# Test API endpoint +curl -H "Authorization: Bearer YOUR_API_KEY_HERE" \ + https://panel.firefrostgaming.com/api/application/servers \ + | python3 -m json.tool > /tmp/panel-api-response.json + +# Review the response structure +less /tmp/panel-api-response.json +``` + +**Look for:** +- Where server status/whitelist info is located +- Field names (whitelist vs whitelist_enabled) +- Structure changes (nested objects) + +### Step 5: Update Python Code + +**Navigate to code directory:** +```bash +cd /opt/whitelist-manager # or wherever it's located +source venv/bin/activate # activate virtual environment +``` + +**Find status detection code:** +```bash +grep -r "feature_limits" . +grep -r "get_server_status" . +grep -r "WHITELISTED" . +``` + +**Example fix (BEFORE):** +```python +def get_server_status(server): + """Detect if server has whitelist enabled""" + try: + if server['attributes']['feature_limits']['whitelist']: + return "WHITELISTED" + return "PUBLIC" + except KeyError: + return "UNKNOWN" +``` + +**Example fix (AFTER):** +```python +def get_server_status(server): + """Detect if server has whitelist enabled - Panel v1.12.1 compatible""" + try: + attrs = server.get('attributes', {}) + + # Try v1.12.x format first + limits = attrs.get('limits', {}) + if limits.get('whitelist_enabled', False): + return "WHITELISTED" + + # Fallback to v1.11.x format for compatibility + feature_limits = attrs.get('feature_limits', {}) + if feature_limits.get('whitelist', False): + return "WHITELISTED" + + return "PUBLIC" + except Exception as e: + print(f"Error detecting server status: {e}") + return "UNKNOWN" +``` + +**Key changes:** +- Use `.get()` instead of direct dict access (safer) +- Try new format first, fallback to old +- Better error handling +- Log errors for debugging + +### Step 6: Update Server Grouping (If Broken) + +**Find grouping code:** +```bash +grep -r "group.*server" . +grep -r "TX1\|NC1" . +``` + +**Check for:** +- Node detection logic (how it determines TX1 vs NC1) +- Possibly using server IP or name patterns +- May need to update if Panel changed how node info is returned + +### Step 7: Test Changes + +```bash +# Stop service +sudo systemctl stop whitelist-manager + +# Run in debug mode +python3 app.py --debug +# Or +flask run --debug + +# Check for errors in output +# Test in browser: http://38.68.14.188:5000 +``` + +**Verify:** +- Servers load correctly +- Statuses show (WHITELISTED/PUBLIC/OFF) +- Grouping correct (TX1 = 5 servers, NC1 = 6 servers) +- Add/remove player still works + +### Step 8: Restart Service + +```bash +# If running in debug, stop it (Ctrl+C) + +# Restart production service +sudo systemctl restart whitelist-manager + +# Check status +sudo systemctl status whitelist-manager + +# Verify no errors +sudo journalctl -u whitelist-manager -n 20 --no-pager +``` + +### Step 9: Verify in Browser + +**Visit:** https://whitelist.firefrostgaming.com + +**Check:** +- ✅ Server statuses display correctly +- ✅ TX1: 5 servers group +- ✅ NC1: 6 servers group +- ✅ No "Unknown" group (unless actual unknown servers) +- ✅ Add player works +- ✅ Remove player works +- ✅ Recent Activity logs correctly + +### Step 10: Document Changes + +**Update this file with:** +- Exact code changes made +- API format differences found +- Any gotchas for future updates + +**Add note to Panel update checklist:** +- Always verify Whitelist Manager after Panel updates +- Test server status detection +- Reference this task if broken + +--- + +## Prevention for Future Updates + +### Create Post-Update Checklist + +**After ANY Panel or Wings update:** + +1. ✅ Visit whitelist.firefrostgaming.com +2. ✅ Verify server statuses (not all "UNKNOWN") +3. ✅ Check server grouping (correct counts) +4. ✅ Test add player to one server +5. ✅ Test remove player from one server +6. ✅ Check Recent Activity log +7. ✅ If broken → Task #86 fix procedure + +**Add to Panel update documentation:** +"After Panel update, immediately verify Whitelist Manager functionality. See Task #86 for fix procedure if API compatibility broken." + +### Version Compatibility Matrix + +| Panel Version | Whitelist Manager Status | Notes | +|---------------|-------------------------|-------| +| v1.11.x | ✅ Working | Original development version | +| v1.12.0 | ❓ Unknown | Not tested | +| v1.12.1 | ❌ BROKEN | Status detection fails - needs update | +| v1.13.x | ❓ Future | Test immediately after upgrade | + +**Update this table after each Panel upgrade.** + +--- + +## Workaround (Until Fixed) + +**Use Pterodactyl Panel console directly:** + +1. Go to https://panel.firefrostgaming.com +2. Navigate to Servers +3. Select server +4. Click "Console" tab +5. Type commands: + - `whitelist add ` + - `whitelist remove ` + - `whitelist list` + +**Or SSH to nodes:** +```bash +# TX1 Dallas +ssh architect@38.68.14.26 + +# NC1 Charlotte +ssh architect@216.239.104.130 +``` + +Then use Pterodactyl console from Panel. + +--- + +## Dependencies + +**Blocks:** Nothing (workaround exists) + +**Blocked By:** Nothing (ready to fix) + +**Related Tasks:** +- Task #7: Whitelist Manager (original deployment) +- Task #47: Whitelist Manager Refinements (Mayview grouping) +- Task #3: Pterodactyl Panel Update v1.12.1 (what broke it) + +--- + +## Success Criteria + +**Fix is complete when:** + +- ✅ All servers show correct status (WHITELISTED/PUBLIC/OFF) +- ✅ Server grouping correct (TX1: 5 servers, NC1: 6 servers) +- ✅ No "Unknown" group (unless legitimate unknown servers) +- ✅ Add player function works +- ✅ Remove player function works +- ✅ Bulk operations work (add/remove to ALL) +- ✅ Recent Activity logs correctly +- ✅ Code updated to handle both v1.11.x and v1.12.x API formats +- ✅ Documentation updated with fix details +- ✅ Post-update checklist added to Panel update procedure + +--- + +## Technical Notes + +### API Versioning + +Pterodactyl does NOT use semantic API versioning. The API is tightly coupled to Panel version. + +**This means:** +- Minor Panel updates (1.11 → 1.12) can break API compatibility +- No deprecation warnings +- No API changelog +- Must test integrations after EVERY Panel update + +**Best practice:** +- Write defensive code (use `.get()`, handle missing keys) +- Support multiple API formats when possible +- Log API responses for debugging +- Add version detection to code + +### Code Quality Improvements + +**When fixing, also improve:** + +1. **Error handling** - Better logging of API errors +2. **API response caching** - Reduce API calls +3. **Health check endpoint** - `/health` that tests API connectivity +4. **Version detection** - Log Panel version from API +5. **Fallback behavior** - Graceful degradation if API fails + +**Example health check:** +```python +@app.route('/health') +def health_check(): + """Health check endpoint - tests Panel API connectivity""" + try: + response = requests.get( + f"{PANEL_URL}/api/application/servers", + headers={"Authorization": f"Bearer {API_KEY}"}, + timeout=5 + ) + if response.status_code == 200: + data = response.json() + return { + "status": "healthy", + "panel_api": "connected", + "servers_count": len(data.get('data', [])) + }, 200 + else: + return { + "status": "unhealthy", + "panel_api": "error", + "error_code": response.status_code + }, 500 + except Exception as e: + return { + "status": "unhealthy", + "panel_api": "unreachable", + "error": str(e) + }, 500 +``` + +--- + +## Related Documentation + +- **Original Deployment:** `docs/tasks/whitelist-manager/` +- **Panel Update Log:** `docs/tasks/pterodactyl-panel-update/` +- **Infrastructure Manifest:** `docs/core/infrastructure-manifest.md` +- **Task Master List:** `docs/core/tasks.md` + +--- + +## Future Enhancements (Phase 2) + +**While fixing, consider adding:** + +1. **Panel version detection** - Log Panel version on startup +2. **API format auto-detection** - Detect v1.11.x vs v1.12.x format +3. **Health monitoring** - `/health` endpoint for uptime monitoring +4. **Better error messages** - User-facing errors if API fails +5. **Retry logic** - Auto-retry failed API calls + +**Don't over-engineer** - just get it working first, then iterate. + +--- + +**Fire + Frost + Foundation = Where Love Builds Legacy** 💙🔥❄️ + +--- + +**Document Status:** ACTIVE +**Task Status:** IDENTIFIED - Ready to fix +**Ready to Build:** Yes (when home)