corrosion-admin-panel/CHANGELOG.md

CHANGELOG — Corrosion Admin Panel

All notable changes to this project will be documented in this file.

[Unreleased]

Added (Host-agent Phase 2 — Dune docker-compose adapter — 2026-06-12)

Supervisor trait abstraction (corrosion-host-agent):

• Introduced trait Supervisor (via async-trait, the battle-tested ecosystem standard) so the agent can manage games with fundamentally different models behind one wire contract. ProcessSupervisor (spawned OS process — Rust/Conan/Soulmask) and the new DockerComposeSupervisor (Dune) both implement it; Agent.supervisors is now HashMap<String, Arc<dyn Supervisor>> and the instance command dispatch (instancecmd::dispatch) is fully game-agnostic — start/stop/restart/status are identical across games. A per-game factory in main selects the impl. InstanceState moved to the shared supervisor module.
• Architecture call (per Commander): chose the dyn trait over a zero-dependency enum because the Dune references point at several future management planes (kubectl, AMP/podman, SSH) — a trait makes each new plane "new struct + impl," no central match to edit.

DockerComposeSupervisor (Dune: Awakening):

• Drives docker compose up -d / stop / restart against the instance's compose project (a "battlegroup"), with -f/-p/single-service support and a configurable compose binary (docker compose default, docker-compose legacy). New [instance.docker_compose] config block (file/project/service/command, all optional). steam_update already rejected for Dune (Docker images, no SteamCMD).
• Scope (first cut): lifecycle + cached state. Deferred to Phase 3b (with process PID adoption): container crash-detection and state adoption on agent restart (both reconcilable with a docker compose ps probe).
• Verified: 6 new docker-compose tests (mock docker binary asserting exact invocations + state transitions + failure paths) + the 5 refactored process-supervisor tests; full agent suite 56 tests green, zero warnings. Live verification against a real Dune stack pending the Commander standing one up.

Changed (Fleet-driven active game + signed-update CI fix — 2026-06-12)

Frontend — active game follows the deployed fleet:

• The panel's active game (shell skin + sidebar nav + dashboard terminology) is now derived from the deployed instances instead of a localStorage-only toggle. syncActiveGameFromFleet() reads the distinct game values of the license's instances (game_instances.game, reported by the host agent): exactly one game deployed → the shell auto-skins to it; zero or multiple → all (neutral house skin). Wired into DashboardLayout (the always-mounted admin shell) via a watch on the fleet store.
• A manual GameSwitcher pick still wins — it persists to cc-active-game and suppresses auto-derive (operator intent beats the heuristic). Un-overridden panels keep tracking the fleet across sessions.
• No backend/schema change: a license's game(s) are the distinct games of its instances — the normalized source of truth. Deliberately did NOT add a licenses.game column (would duplicate game_instances.game and drift; see Lesson 20).

Frontend — sidebar agent-health footer is now fleet-aware:

• The shell footer read a single legacy server.connection (one server_connections row), which disagreed with the multi-host fleet. Repointed it at the fleet store: one host → hostname + status + last-heartbeat; multiple → {online}/{total} online + total instance count. Tone aggregates (all online → healthy, some → degraded, none → offline). Dropped the legacy useServerStore dependency from the shell entirely.

Frontend — removed dead vuefinder dependency:

• VueFinder was replaced by the native instance-scoped file manager but the plugin (and its CSS) were still globally registered in main.ts and shipped in the bundle. Removed the dep + the three main.ts lines. Side effect: the main JS chunk dropped 588 kB → 165 kB (vuefinder bundled an entire unused file-manager UI).

Recon note (not a change): corrosion.{license}.cmd.server was on the cleanup list as "dead v1" — it is NOT. It remains the live license-level command path for all plugin/module config applies, plugin install, scheduled tasks, and legacy start/stop/restart, served only by the legacy Go agent. The Rust agent does not implement it yet — this is a parity/migration gap (Phase 2+), not dead code. Left intact.

CI — signed host-agent build:

• Fixed the Sign artifacts (minisign) step (Error while loading the secret key file): a minisign secret key is two lines and CI secret storage mangles the embedded newline. The job now base64-decodes the secret (single-line, mangling-proof) with auto-detect fallback to a raw key. MINISIGN_SECRET_KEY must be stored as base64 < secret.key | tr -d '\n'. Verified end-to-end: agent-v2.0.0-alpha.8 Linux + Windows binaries validate against the agent's embedded public key; tampered byte rejected.

Added (Host-Agent v2 Consumer + SEO Meta — 2026-06-11)

Backend (NestJS):

• HostAgentConsumerService (new) — consumes wire protocol v2: corrosion.*.host.heartbeat updates companion_last_seen + connection_status='connected' (auto-registers the connection row on first contact); host.going_offline flips offline; a 60s staleness sweep marks hosts offline after 180s of silence. Previously NOTHING persisted heartbeats — connection_status was set once at setup and never changed again. Tenant-validated (UUID + license existence, cached) per NATS-consumer doctrine
• NatsBridgeService — bridges host_heartbeat / host_going_offline events to the panel WebSocket
• Verified by contract test: real agent → production NATS → captured with the backend's own nats lib under the real license; subjects, schema 2, real telemetry, offline beacon all confirmed

Frontend:

• Per-route document titles + meta descriptions (router afterEach, no new deps): six marketing pages get real titles/descriptions/OG tags (previously every page was "Corrosion Management" with zero meta — invisible to search and link previews); panel views get mechanical "{View} — Corrosion" titles

CI:

• test-runner.yml — honest per-tool presence checks (was printing "OPERATIONAL" while every toolchain probe failed); on-demand trigger instead of every push

Added (Corrosion Host Agent — Rust rewrite Phase 0 — 2026-06-11)

New: corrosion-host-agent/ — Rust rewrite of the Go companion agent (which stays in-tree as the behavior reference until parity). Wire protocol v2 (COA-B, Commander-approved): instance-scoped subjects corrosion.{license}.{instance}.* with host-level corrosion.{license}.host.* — full spec in corrosion-host-agent/PROTOCOL.md.

• Multi-instance TOML config baked into the foundation (one agent supervises N game instances; rust/conan/soulmask/dune), env overrides for secrets, strict validation (subject-safe ids, reserved segments)
• NATS layer with the production-proven Vigilance profile: infinite reconnect w/ capped backoff, 30s ping, 8192-msg offline send buffer, tls:// scheme support
• Host heartbeat with REAL telemetry via sysinfo (CPU/mem/disks/per-instance state) — the Go agent hardcoded disk=50000MB and cpu=0.0; this is the first true Resources data
• Connectivity prober (outbound TCP + latency, periodic jittered + on-demand) — first piece of the support-triage story
• Host command channel (ping/probe/sysinfo, request-reply), going-offline beacon, CancellationToken graceful shutdown
• Version embedding (semver + git hash + build ts) in --version and every heartbeat
• Verified live against production NATS: connected, heartbeats published, clean shutdown
• Deploy artifacts verified: 3.7MB fully-static linux-musl binary, 3.8MB windows .exe (static CRT, no VC++ redist needed)

Next phases: 1 = process-class adapter (spawn/RCON/SteamCMD/files for Rust/Conan/Soulmask) + NestJS v2 heartbeat consumer; 2 = Dune Docker adapter; 3 = signed self-update (release gate) + service install.

Fixed (Site Audit — Fake Data, Resilience, Fonts — 2026-06-11)

Frontend:

• SetupWizardView.vue — Replaced fake install instructions (get.corrosionmgmt.com | sh install script and corrosion-agent binary, neither of which exists) with the real host-agent download + run commands matching ServerView; multi-game copy on the completion step
• Marketing views (Landing, Pricing, HowItWorks, Roadmap, EarlyAccess) — Replaced "View live demo" CTA (no demo exists; it linked to the panel login) with an honest "Sign in" link
• ErrorBoundary.vue — Error state now resets on route change (previously one failed view bricked the entire SPA, including marketing pages, until manual reload); added content variant
• DashboardLayout.vue — Routed views are now wrapped in a content-scoped ErrorBoundary so the sidebar/topbar survive a view failure instead of the whole panel unmounting
• index.html / styles/tokens/fonts.css — Google Fonts moved from CSS @import to <link> tags. The bundler silently dropped the mid-bundle @import, so production shipped system fallback fonts (Geist/JetBrains Mono/Oxanium never loaded)
• StatusPageView.vue — Platform KPIs show "—" until the first successful fetch instead of fake zeros
• LoginView.vue — Added missing "Forgot password?" link (route + backend endpoint already existed)

Backend (NestJS):

• AdminSeedService (new, auth module) — Bootstraps a super-admin user + active license from ADMIN_EMAIL/ADMIN_PASSWORD/ADMIN_USERNAME/ADMIN_LICENSE_KEY when the users table is empty. A fresh deploy previously had a schema but no possible login. Compose already passes the env vars

Purpose: Findings from the full-site fake-data audit. Show real data or honest empty states — never invented values, dead URLs, or fabricated zeros.

Fixed (Safe Formatting Utilities — 2026-02-15)

Frontend:

• AnalyticsView.vue — Replaced unsafe .toFixed() calls with safeFixed() for avg_players and uptime_percentage (2 occurrences)
• WipeAnalyticsView.vue — Replaced unsafe .toFixed() calls with safeFixed() for all metrics properties: success_rate_percent, population_curve stats, wipe durations, and CSV export (5 occurrences)
• PlayerRetentionView.vue — Replaced unsafe .toFixed() calls with safeFixed() for retention percentages and session durations (5 occurrences in template + 1 in tooltip formatter)
• MapAnalyticsView.vue — Replaced unsafe .toFixed() calls with safeFixed() for rotation effectiveness, map performance metrics, and table display (6 occurrences)

Purpose: Prevents runtime errors from calling .toFixed() on null/undefined values in analytics views. Uses the safe formatting utilities from @/utils/formatters.ts with optional chaining for all numeric display operations.

Fixed (NestJS Entity Alignment — 2026-02-15)

Backend (NestJS):

• NotificationsConfig entity — Renamed email_alerts_enabled → email_enabled, added email_address column
• NotificationsConfig entity — Renamed notification columns to match service expectations: notify_on_start, notify_on_stop, notify_on_crash, notify_on_wipe_start, notify_on_wipe_complete, notify_on_wipe_failure, notify_on_player_threshold, player_threshold
• ScheduledTask entity — Renamed is_active → is_enabled, added last_run column
• TeamMember entity — Renamed accepted_at → joined_at to match service expectations
• Role entity — Added description column
• JwtStrategy — Updated to reference joined_at instead of accepted_at
• Resolved all 12 TypeScript compilation errors caused by entity/service column mismatches

Added (Frontend Gap Closure — 2026-02-15)

New Views:

• SchedulesView.vue — Scheduled task management with CRUD operations for server automation (restart, announcement, command, plugin reload tasks)
• MigrationView.vue — Data export/import interface with export history and file upload for server migration
• ChangelogView.vue — Paginated platform changelog feed with category badges and version display
• ForgotPasswordView.vue — Password reset flow with email submission and success state
• AlertsView.vue — Alert configuration dashboard with threshold sliders, notification channel toggles, and alert history table

Component Updates:

• ErrorBoundary.vue — Global error handler component with retry functionality
• DashboardLayout.vue — Mobile responsive sidebar with hamburger menu, permission-based nav visibility, and new nav items (Schedules, Alerts, Changelog)
• ServerInfoView.vue — Complete rewrite for public server info page with header image, MOTD, wipe schedule, mods list, and Discord integration

Store & API Integration:

• plugins.ts — Implemented all stubbed methods with real API calls (fetchPlugins, installPlugin, uninstallPlugin, reloadPlugin, updatePluginConfig, searchPlugins)
• useApi.ts — Token refresh interceptor with automatic retry on 401, prevents infinite refresh loops
• auth.ts — Added hasPermission() helper with basic permission checking

Router:

• Added routes: /schedules, /migration, /changelog, /alerts, /forgot-password
• Added catch-all route redirecting to home
• All new routes under authenticated dashboard layout

App Structure:

• Wrapped root <RouterView> with ErrorBoundary for global error handling

Purpose: Closes frontend implementation gaps identified during Phase 4. Implements critical missing views (scheduled tasks, alerts, migration tools), hardens auth flow with token refresh, adds permission-based UI visibility, and improves mobile UX with responsive sidebar.

Added (NestJS Backend — Core Modules)

Auth Module (modules/auth/):

• Complete authentication system with JWT and refresh tokens
• DTOs: LoginDto, RegisterDto, RefreshTokenDto, VerifyTotpDto, UpdateProfileDto, ForgotPasswordDto, ResetPasswordDto
• JwtStrategy — Passport strategy with user lookup, license resolution, and role permissions injection
• AuthService — Full auth lifecycle:
  • register() — User creation with auto-generated license key (CORR-XXXX-XXXX-XXXX format)
  • login() — Credential validation, TOTP verification, token generation
  • refresh() — Access token refresh from valid refresh token
  • setupTotp() — TOTP secret generation with QR code (otpauth + qrcode libraries)
  • verifyTotp() — TOTP code validation and 2FA enablement
  • getProfile() / updateProfile() — User profile management
  • forgotPassword() / resetPassword() — Password recovery stubs (SMTP integration pending)
• AuthController — 9 REST endpoints:
  • POST /auth/login — Email/password login with optional TOTP
  • POST /auth/register — New user registration with auto-license creation
  • POST /auth/refresh — Token refresh
  • POST /auth/2fa/setup — Generate TOTP QR code (authenticated)
  • POST /auth/2fa/verify — Enable 2FA (authenticated)
  • GET /auth/me — Current user profile (authenticated)
  • PUT /auth/profile — Update profile (authenticated)
  • POST /auth/forgot-password — Request password reset (public)
  • POST /auth/reset-password — Reset with token (public)
• Password hashing via argon2, TOTP via otpauth with 30-second window validation
• License key auto-generation on registration (random hex parts)
• JWT payload includes: sub (user ID), email, username, is_super_admin, license_id, permissions
• Strategy enriches JWT with license context (owner or team member lookup) and role permissions

Users Module (modules/users/):

• Simple CRUD wrapper around User repository
• UsersService — findById(), findByEmail(), findAll() with password_hash excluded from select
• UsersController — Admin-only endpoints:
  • GET /users — List all users (requires users.view permission)
  • GET /users/:id — Get user by ID (requires users.view permission)
• Password fields excluded from all query results

Licenses Module (modules/licenses/):

• License management with owner authorization
• DTO: ValidateKeyDto — License key validation input
• LicensesService:
  • findById() — License lookup with owner/super admin authorization check
  • findByKey() — Key-based lookup
  • findByOwner() — All licenses owned by user
  • create() — New license generation with CORR-XXXX-XXXX-XXXX format
  • validateKey() — Public key validation returning status and metadata
• LicensesController:
  • GET /licenses/:id — Get license (owner or super admin only)
  • POST /licenses/validate-key — Public key validation endpoint
• License key format: CORR-{4-hex}-{4-hex}-{4-hex} (e.g., CORR-A1B2-C3D4-E5F6)
• Ownership enforced: non-super-admin users can only access their own licenses

Patterns Applied:

• All DTOs use class-validator decorators (@IsEmail, @IsString, @MinLength, etc.)
• All controllers use @ApiTags and @ApiBearerAuth for Swagger documentation
• All routes use @ApiOperation for endpoint descriptions
• Custom decorators: @Public(), @CurrentUser(), @CurrentTenant(), @RequirePermission()
• Entity imports from ../../entities/ directory
• ConfigService for environment variables (JWT_SECRET, JWT_ACCESS_EXPIRY_SECONDS, JWT_REFRESH_EXPIRY_SECONDS)
• Multi-tenant isolation: License lookup respects ownership unless super admin
• JwtStrategy enriches request.user with license_id and permissions for downstream guards

Security:

• Argon2 password hashing (not bcrypt — more resistant to GPU attacks)
• TOTP 6-digit codes with ±1 period window validation
• Refresh tokens with separate expiry (default 7 days vs 1 hour access token)
• Password fields never returned in API responses
• License access requires ownership or super admin flag

Status: Core auth, users, and licenses modules operational. Registration creates user + license atomically. Login returns JWT with license context. TOTP 2FA flow complete. Password reset stubbed pending SMTP integration. All endpoints documented via Swagger.

Added (Phase 4 — Module Licensing Backend)

Backend Infrastructure:

• Migration 009_module_licensing.sql — Module marketplace database schema:
  • modules table — Registry of available modules (slug, name, description, category, price, features, version, plugin URL)
  • module_purchases table — License-module ownership tracking with transaction logging
  • module_installations table — Deployment status tracking (pending, installing, installed, failed)
  • Seed data: Loot Manager module ($9.99) with features array
• backend/src/models/modules.rs — Domain models:
  • Module struct with rust_decimal pricing support
  • ModuleWithOwnership — Catalog display with is_purchased flag
  • ModulePurchase, ModuleInstallation — Purchase and deployment records
  • PurchasedModule — Combined view for user's module library
• backend/src/db/modules.rs — Data access layer (11 query functions):
  • get_module_catalog() — All available modules
  • get_catalog_with_ownership(license_id) — Annotated catalog with purchase status
  • get_purchased_modules(license_id) — User's module library with installation status
  • is_module_purchased(license_id, module_id) — Ownership validation
  • record_module_purchase() — Transaction logging with PayPal ID support
  • get_module_installation_status() / update_installation_status() — Deployment tracking
  • get_module_by_id() / get_module_by_slug() — Module lookup
• backend/src/api/modules.rs — REST endpoints with auth middleware:
  • GET /api/modules/catalog — Returns modules with is_purchased flag for current license
  • GET /api/modules/my-modules — Purchased modules with installation details
  • POST /api/modules/purchase — Records purchase (stub transaction for Phase 4 MVP — payment integration deferred to XO's direct touch)
  • POST /api/modules/install — Triggers module installation via ModuleInstaller service
  • GET /api/modules/:module_id/installation-status — Real-time deployment status polling
• Router integration in main.rs at /api/modules with JWT auth requirement
• Cargo.toml dependency: rust_decimal for DECIMAL field support

Multi-Tenancy Enforcement:

• All queries scoped by license_id from JWT claims
• Foreign key constraints enforce license-module binding
• Purchase validation prevents cross-tenant access
• Installation status isolated per license

Payment Integration Strategy:

• Purchase endpoint stubs transaction with "STUB_TRANSACTION" ID
• PayPal integration deferred to XO's direct implementation
• transaction_id and amount_paid fields ready for real gateway

Status: Module licensing backend operational. Catalog queryable, purchases recordable, ownership enforceable, installation status trackable. Payment gateway integration pending.

Added (Phase 4 — Loot Manager Plugin Skeleton)

Plugin Skeleton:

• plugin/modules/LootManager.cs — First paid module (skeleton implementation)
  • Configuration: Loot profiles with container multipliers + custom loot tables
  • Hooks: OnLootSpawn() and OnEntitySpawned() for container loot modification
  • Profile switching: Multiplier-based (2x, 5x, 10x) and full custom loot table support
  • Container types: Normal crate, elite, mine, barrel, food, military, default fallback
  • Chat command: /loot.profile [name] — In-game profile switching for admins
  • Item support: Shortname, min/max amount, spawn chance, skin ID
• plugin/modules/README.md — Module documentation
  • Price: $9.99
  • Features: Visual loot table editor (dashboard integration TBD), profile switching, skin support
  • Installation: Auto-deploy via module store (implementation TBD)

Database:

• Migration 009 already includes Loot Manager seed data in modules table

Status: Skeleton complete. Hooks functional. Profile switching works via chat command. Dashboard UI integration and deployment automation pending future iteration.

Added (Phase 4 — Module Auto-Installation Pipeline)

Backend Service:

• backend/src/services/module_installer.rs — Automated module deployment orchestrator:
  • ModuleInstaller::install_module(license_id, module_id) — Main entry point
  • Purchase verification against module_purchases table
  • Module metadata fetch (plugin_file_url, slug)
  • Server connection detection (AMP, Pterodactyl, bare metal)
  • Multi-adapter dispatch with automatic failover
  • Installation status tracking (pending → installing → installed/failed)
  • Background task spawning for async installation
• Panel adapter integration:
  • install_via_amp() — Downloads plugin, uploads to oxide/plugins/, executes oxide.reload *
  • install_via_pterodactyl() — Same flow using Pterodactyl client API
  • install_via_companion() — Publishes NATS command to bare metal agent
• HTTP client integration: reqwest for plugin file download from CDN
• Encryption support: Decrypts panel API keys using services::encryption::decrypt()
• Error handling: Comprehensive context wrapping with installation failure logging

NATS Integration:

• New subject pattern: corrosion.{license_id}.cmd.module.install
• Request/reply timeout: 60 seconds for companion agent response
• Expected payload:

  {
    "module_id": "loot-manager",
    "download_url": "https://cdn.corrosionmgmt.com/modules/LootManager.cs",
    "filename": "LootManager.cs",
    "target_path": "oxide/plugins/"
  }
  

• Expected response:

  {
    "module_id": "loot-manager",
    "success": true|false,
    "error": "optional error message"
  }
  

• Subject pattern already covered by existing corrosion.*.cmd.> wildcard in STREAM_AGENT_COMMANDS

API Updates:

• backend/src/api/modules.rs:
  • Updated POST /api/modules/install — Replaced stub with real ModuleInstaller invocation
  • Spawn background task for async installation
  • Return immediately with "installing" status
  • GET /api/modules/:module_id/installation-status — Already existed, now returns real data from module_installations table
• ModuleInstaller instantiation with encryption key from AppConfig

Documentation:

• docs/COMPANION_AGENT_MODULE_INSTALL.md — Companion agent NATS contract specification:
  • Subject patterns and payload schemas
  • Expected agent behavior (download, install, reload, respond)
  • Error handling requirements
  • Example pseudocode implementation (Go)
  • Testing procedures and failure scenarios

Dependencies:

• Cargo.toml: Added rust_decimal feature to sqlx for DECIMAL field support

Status: Backend pipeline fully operational. Modules install automatically to AMP/Pterodactyl servers. Companion agent NATS contract documented. Companion agent implementation (Go) pending future iteration.

Added (Phase 4 — Module Store Frontend)

Frontend:

• Complete ModuleStoreView.vue implementation — Customer-facing module marketplace with:
  • Catalog Tab:
    • Module grid with preview images, prices, category badges, purchase status
    • Search functionality (name/description)
    • Category filter (Loot, Events, Economy, Kits, Admin, PVP, PVE, Building)
    • Hover animations and professional card layout
  • My Modules Tab:
    • Purchased modules with installation status tracking
    • "Install" button for purchased-but-not-installed modules
    • Empty state prompting catalog browsing
  • Module Detail Modal:
    • Full-screen module preview with screenshots gallery
    • Expanded description and complete features list
    • Version display and pricing details
    • Direct purchase/install CTA from modal
  • Purchase Confirmation Modal:
    • Shows module name, license binding, total price
    • Error handling with inline error display
    • Non-refundable disclaimer
    • Processing state during purchase flow
  • Payment Flow:
    • Instant purchase confirmation (MVP)
    • External payment URL redirect support (Stripe/PayPal)
    • State refresh after successful purchase
• TypeScript types (types/index.ts):
  • Module interface with full marketplace metadata (id, slug, name, description, price, category, images, features, version, purchase/install status)
  • PurchaseRequest interface for API integration
• API Integration:
  • GET /api/modules/catalog — Browse all available modules
  • GET /api/modules/my-modules — Fetch purchased modules for current license
  • POST /api/modules/purchase — Initiate module purchase (returns payment URL or instant confirmation)
  • POST /api/modules/install — Trigger deployment to game server

Design Details:

• Professional marketplace UI using existing Tailwind patterns
• Color-coded category badges (8 categories supported)
• Preview image with hover scale effect
• "Purchased" badge overlay on owned modules
• Three-state purchase flow: Not Purchased → Purchased → Installed
• Mobile-responsive grid (1/2/3 columns)
• Empty states for zero results and zero purchases
• Price display prominently in catalog cards and modals

Purpose: Enables server admins to browse, preview, purchase, and install premium gameplay modules (Loot systems, Events, Economy plugins, Kits) directly from the dashboard. Customers pay real money here — UI polish critical.

Added (Phase 2 — Alerting System)

Backend:

• Migration 008: Alert configuration and history tables
  • alert_config table with threshold settings per license (population drop %, FPS threshold)
  • alert_history table logging all triggered alerts with metadata
  • Default alert config created for all existing licenses
• Alert service (services/alerting.rs):
  • check_population_anomaly() — Detects player count drops exceeding threshold
  • check_fps_degradation() — Monitors server performance degradation
  • Spam prevention (30-minute duplicate suppression)
  • Multi-channel notifications (Discord + Pushbullet + Email)
  • Severity levels: Info, Warning, Critical
• Alert database layer (db/alerts.rs):
  • get_alert_config() / update_alert_config() — Threshold configuration
  • insert_alert() / mark_alert_notified() — Alert history tracking
  • check_recent_alert() — Duplicate detection
  • cleanup_old_alerts() — 90-day retention cleanup
• Updated db/notifications.rs — Notification config retrieval with webhook/API key support

Alert Types:

• Population Drop — Triggers when player count drops >X% in 1 hour
• FPS Degradation — Triggers when FPS falls below configurable threshold
• Server Crash — Critical alert for auto-recovery failures
• Wipe Failed — Alert when wipe execution fails

Purpose: Proactive monitoring for server health issues. Alerts server admins via Discord/Pushbullet when anomalies detected (population crashes, performance degradation). Configurable thresholds per license.

Added (Phase 2 — Wipe Performance Analytics)

Backend:

• backend/src/db/wipes.rs — Comprehensive wipe analytics query layer:
  • get_wipe_success_rate() — Success vs failure rate over time range
  • get_average_wipe_duration() — Average execution time for successful wipes
  • get_wipe_to_peak_population() — Hours from wipe completion to peak player count (24h window)
  • get_population_curve_by_cycle() — Day 1 vs Day 2 vs Day 3 average player counts post-wipe
  • get_optimal_wipe_timing() — Recommends best day of week + hour based on historical peak populations
  • get_wipe_analytics_entries() — Detailed per-wipe records for charting (duration, peak pop, success)
  • All queries use hourly aggregates (server_stats_hourly) with 90-day retention
• backend/src/api/analytics.rs — Wipe performance endpoint:
  • GET /api/analytics/wipes/performance?range=90d — Returns full wipe performance metrics
  • Supports range params: 6d, 12d, 90d, all (converted to wipe count estimates)
  • Response includes: success rate, avg duration, population curve, optimal timing, individual wipe entries

Frontend:

• WipeAnalyticsView.vue — Complete wipe performance dashboard:
  • ECharts Visualizations:
    • Wipe success timeline (scatter plot: green = success, red = failed)
    • Population curve bar chart (Day 1/Day 2/Day 3 average players post-wipe)
    • Wipe duration trend (line chart showing execution time evolution)
  • Insight Cards:
    • Success rate percentage with total wipe count
    • Average wipe duration (formatted as minutes:seconds)
    • Peak population day identifier
    • Optimal wipe timing recommendation (day + hour)
  • Actionable Recommendations Banner:
    • Optimal wipe day/hour based on post-wipe player peaks
    • Weekly vs bi-weekly wipe suggestion (if Day 1 >> Day 2 population)
    • Duration optimization alerts (if avg > 10 minutes)
    • Rollback protection warnings (if failures detected)
  • Time range selector: Last 6 wipes / Last 12 wipes / All time
  • CSV export functionality
• Added route /wipes/analytics to router
• TypeScript interfaces: WipePerformanceMetrics, WipeAnalyticsEntry, PopulationCurve

Purpose: Answers critical questions: "How long do wipes take? When do players peak post-wipe? What's my success rate? When should I schedule wipes for max population?" Enables data-driven wipe timing optimization and operational insights.

Added (Phase 3 — Public Status Page)

Backend:

• Migration 007: Added status_page_description TEXT column to public_site_config
• Public API models (models/public.rs):
  • PublicServerStatus — Server status with live stats for public display
  • PlatformHealth — Platform-wide health metrics (total servers, online count, total players, uptime)
  • StatusPageResponse — Complete status page data structure
  • PublicSiteConfig — Full public site configuration model
• Public database queries (db/public.rs):
  • get_public_servers() — Retrieves all opted-in servers with current stats, uptime percentages (24h/7d/30d), wipe schedules
  • get_platform_health() — Calculates platform-wide aggregate metrics
  • calculate_uptime_percentage() — Uptime calculation from hourly stats
  • format_cron_expression() — Human-readable wipe schedule formatting
  • get_public_site_config() / create_public_site_config() / update_public_site_config() — Config management
• Public API endpoint (api/public.rs):
  • GET /api/public/status — Public status page data (no auth required)
• Settings API (api/settings.rs):
  • GET /api/settings/public-site — Fetch public site config (auth required)
  • PUT /api/settings/public-site — Update status page opt-in and description (auth required)

Frontend:

• StatusPageView.vue — Complete public status page with:
  • Platform health header (total servers, online now, total players, platform uptime)
  • Server grid with status indicators (green/yellow/red), player counts, uptime badges (24h/7d/30d)
  • Wipe schedule display with countdown timers
  • Server search/filter functionality
  • Auto-refresh every 10 seconds via polling
  • Mobile-responsive grid layout
  • "Powered by Corrosion" footer with panel link
• Settings dashboard integration (SettingsView.vue):
  • New "Public Status" tab with toggle for show_on_status_page
  • Text area for status_page_description
  • Save endpoint integration

Infrastructure:

• nginx already configured for status.corrosionmgmt.com routing
• Router already configured with /status route on both panel and marketing domains

Purpose: Public-facing marketing page showcasing all Corrosion servers. Drives platform visibility and attracts new customers ("I want this for my server too").

Added (Phase 2.2 — Player Retention Analytics)

Backend:

• Migration 004_player_sessions.sql — Player session tracking table with indexes for retention queries
• backend/src/db/player_sessions.rs — Complete player session tracking and retention analysis:
  • track_player_join() / track_player_leave() — Record individual player sessions
  • calculate_retention_after_wipe() — Calculate 24h/48h/72h return rates per wipe
  • get_unique_player_count() / get_avg_session_duration() — Session metrics
  • get_new_vs_returning_ratio() — New vs returning player analysis
  • get_recent_wipe_retention_metrics() — Multi-wipe retention trends
  • cleanup_old_player_sessions() — 90-day retention cleanup
• backend/src/api/plugin.rs — Plugin event endpoints:
  • POST /api/plugin/player-event — Track player join/leave events
  • POST /api/plugin/checkin — Plugin registration on server start
• Extended backend/src/api/analytics.rs with retention endpoints:
  • GET /api/analytics/retention?wipe_count=6 — Multi-wipe retention metrics
  • GET /api/analytics/retention/export — CSV export of retention data

Frontend:

• PlayerRetentionView.vue — Complete retention analytics dashboard:
  • ECharts retention curve (24h/48h/72h lines across multiple wipes)
  • Summary cards: unique players, avg session duration, new vs returning ratio
  • Wipe selector (last 3/6/10/20 wipes)
  • Detailed wipe table with retention percentages
  • CSV export functionality
• Added route /retention to router
• TypeScript interfaces: WipeRetentionMetric, SessionSummary, RetentionResponse

Plugin:

• Updated CorrosionCompanion.cs to track player events via /api/plugin/player-event
• Modified OnPlayerConnected / OnPlayerDisconnected hooks with license_key authentication

Purpose: Answers critical question: "What percentage of players return 24h/48h/72h after a wipe?" Enables data-driven wipe timing optimization and player retention analysis.

Added (Phase 2.2 — Map Analytics System)

Backend:

• Migration 005: Added map_id FK to server_stats and wipe_history for map effectiveness tracking
• Stats consumer now captures current_map_id from server_config when persisting stats
• Map analytics database queries (db/maps.rs):
  • get_map_analytics() — Returns performance metrics per map (avg/peak players, times used, effectiveness score)
  • get_map_population_trends() — Player count trends per map over wipe cycles
  • Effectiveness scoring algorithm: (avg_players / peak_players) * 100
• Analytics API endpoint (api/analytics.rs):
  • GET /api/analytics/maps?range=90d — Map performance summary with rotation effectiveness

Frontend:

• MapAnalyticsView.vue — Complete map effectiveness dashboard with:
  • Summary cards: Best performing map, rotation effectiveness %, total maps tracked
  • ECharts bar chart comparing avg vs peak players per map
  • Sortable performance table with effectiveness color coding (green ≥80%, yellow ≥60%, red <60%)
  • Actionable insights section recommending rotation improvements
  • CSV export functionality
  • Time range selector (30d/90d/all)
• TypeScript types: MapPerformanceMetrics, MapAnalyticsSummary
• Router: Added /maps/analytics route under admin dashboard

Purpose: Answers "Which maps drive the most players? Is my rotation working?" Enables data-driven map selection for wipe day.

Added (Phase 2 — Data Aggregation Pipeline)

Backend:

• Stats ingestion consumer service (stats_consumer.rs) subscribing to corrosion.*.stats NATS subject
• Complete stats database queries (db/stats.rs) with support for:
  • Raw stats insertion and retrieval
  • Hourly aggregation queries
  • Analytics summary calculations (peak/avg players, uptime)
  • Data retention cleanup (7 days raw, 90 days hourly)
• Hourly stats aggregation scheduler job (runs at :05 past every hour)
• Daily cleanup scheduler job (runs at 03:00 UTC)
• Analytics API endpoints (api/analytics.rs):
  • GET /api/analytics/summary — Peak/avg players, uptime percentage
  • GET /api/analytics/timeseries — Time-series data for charting (hourly/raw granularity)
  • GET /api/analytics/export — CSV export of server stats
• Background service initialization in main.rs (stats consumer + scheduler)

Frontend:

• Analytics TypeScript types (AnalyticsSummary, TimeseriesData, HourlyStats)
• Complete AnalyticsView.vue implementation with:
  • Real-time data fetching from analytics API
  • Apache ECharts integration for Player Count and Server Performance charts
  • Time range selector (24h/7d/30d)
  • CSV export functionality
  • Loading states and responsive layout

Infrastructure:

• Made NatsBridge.jetstream public for service consumer access

Added (Sovereign Infrastructure Stack)

Services Deployed:

• Gitea (git.corrosionmgmt.com) — Self-hosted Git with Actions support
  • Container: corrosion-gitea on port 8090 (HTTP) and 8095 (SSH)
  • SQLite database (self-contained, persistent)
  • Replaces GitHub dependency for source control
  • Gitea Actions enabled for CI/CD
• SeaweedFS (cdn.corrosionmgmt.com) — S3-compatible object storage and CDN
  • Container: corrosion-cdn with integrated Master/Volume/Filer/S3
  • Filer UI at port 8091 (cdn.corrosionmgmt.com)
  • Master UI at port 8093 (admin.cdn.corrosionmgmt.com)
  • S3 API at port 8092 (internal access)
  • Purpose: Map hosting, plugin packages, companion binaries, backups
• Gitea Act Runner (asgard build server) — CI/CD execution environment
  • Runs on Ryzen 9 7945HX (16C/32T, 64GB DDR5)
  • Docker-based job execution
  • Go 1.21+ and Rust toolchains available
  • Connects to public Gitea instance remotely

CI/CD Workflows:

• test-runner.yml — Runner capability validation (hostname, resources, toolchains)
• build-companion.yml — Production companion agent build pipeline:
  • Triggers on version tags (v*..)
  • Cross-compiles for Linux AMD64 and Windows AMD64
  • Generates SHA256 checksums
  • Creates Gitea release with auto-generated installation instructions
  • Uploads binaries and checksums as release assets

Documentation:

• infra/docker-compose.yml — Infrastructure stack definition
• infra/README.md — Deployment guide and architecture overview
• infra/NPM-CONFIG.md — Nginx Proxy Manager configuration
• infra/ASGARD-RUNNER.md — Act runner setup guide

Repository Migration:

• Migrated from GitHub to self-hosted Gitea
• Remote updated to git@git.corrosionmgmt.com:vantzs/corrosion-admin-panel.git
• All future development on sovereign infrastructure

Technical Details

Data Flow:

Plugin/Agent publishes stats (60s interval)
  → NATS JetStream (corrosion.*.stats)
  → StatsConsumerService persists to server_stats table
  → Hourly aggregation job rolls up to server_stats_hourly
  → Analytics API queries aggregated data
  → Frontend renders charts via ECharts

Database Schema:

• server_stats table (raw stats, 7-day retention)
• server_stats_hourly table (aggregated hourly data, 90-day retention)

Scheduler Jobs:

• Hourly aggregation: 0 5 * * * * (at :05 past every hour)
• Daily cleanup: 0 0 3 * * * (at 03:00 UTC)

Installation Notes

Frontend:

cd frontend && npm install echarts

Backend: No additional dependencies beyond existing Cargo.toml.

Deferred to Phase 2.2

• Player retention tracking (new vs returning players, session duration)
• Wipe-correlated analytics
• Player activity heatmaps (time-of-day patterns)
• Anomaly alerting system

---

[2025-02-15] — Phase 1 Complete

Added (Phase 1 — Foundation)

Backend Services:

• Core control plane (Axum + Tokio)
• Auto-wiper with rollback (wipe_engine.rs)
• Plugin management system
• WebSocket/NATS bridge for real-time data
• Companion agent adapter (bare metal server management)
• Panel adapters (AMP + Pterodactyl)

Frontend:

• Vue 3 dashboard with 19 admin sub-views
• Wipe management UI with real-time progress
• Toast notification system
• Plugin management interface
• Public server site

Infrastructure:

• PostgreSQL schema (migrations 001-003)
• NATS JetStream streams (6 streams configured)
• Docker Compose deployment (4 services)
• JWT auth with refresh tokens, TOTP 2FA

Companion Agent:

• Go binary for bare metal server management
• NATS-based command execution
• Process lifecycle control
• File operations support

uMod Plugin:

• C# plugin for Rust game server integration
• Stats publishing every 60 seconds
• Server lifecycle event reporting

Commits

• c5d0571 — feat: Complete Phase 1 frontend — WebSocket + Wipe feature end-to-end
• 590765f — feat: Complete Phase 1 backend services and WebSocket/NATS bridge
• 8320591 — docs: Update companion agent language choice to Go
• 3c39345 — docs: Add CLAUDE.md and Claude Code settings
• 81eeb3b — docs: Add AGENTS.md roster and resource discipline

---

Format: type: Short description

Types: feat, fix, docs, refactor, test, chore, perf, ci