feat: add leaderboard with time-windowed rankings and pagination

Flegma · Flegma · commit 67c4aa93a5ac · 2026-02-19T02:48:40.000+01:00
Add getLeaderboard Hasura action with 7 categories (highest ELO, most
ELO gained, most kills, best KDR, best win rate, most matches, highest
HS%), time period filters, match type filters, tournament exclusion,
and server-side pagination with Redis caching. Also generate ELO
ratings in fixture loader and add more fixture matches for testing.
diff --git a/hasura/fixtures/fixtures.sql b/hasura/fixtures/fixtures.sql
@@ -1,5 +1,5 @@
 -- Dev Fixture Data
--- Inserts ~40 players, 8 teams, ~100 matches with scores, map veto picks, utility/flash data, and 4 tournaments
+-- Inserts ~40 players, 8 teams, ~143 matches with scores, map veto picks, utility/flash data, and 4 tournaments
 -- This file is idempotent: running cleanup.sql first removes prior fixture data
 
 -- Disable triggers on affected tables (excluding hypertables which don't support this)
@@ -491,6 +491,182 @@ BEGIN
     END IF; -- finished/live
   END LOOP; -- matches
 
+  -- ==========================================
+  -- 5b. ADDITIONAL STANDALONE MATCHES (~43 more finished, spread across last 30 days)
+  -- ==========================================
+  FOR match_idx IN 1..43 LOOP
+    -- Pick two different teams with offset for variety
+    team_1_idx := ((match_idx + 3) % 8) + 1;
+    team_2_idx := ((match_idx + 6) % 8) + 1;
+    IF team_1_idx = team_2_idx THEN
+      team_2_idx := (team_2_idx % 8) + 1;
+    END IF;
+
+    -- Spread across last 30 days (denser toward recent)
+    match_date := now() - (interval '16 hours' * (43 - match_idx)) - interval '6 hours';
+
+    -- Create match options
+    match_options_id := gen_random_uuid();
+    INSERT INTO match_options (id, overtime, knife_round, mr, best_of, map_veto, type, map_pool_id, lobby_access, tv_delay)
+    VALUES (match_options_id, true, true, 12, 1, true, 'Competitive', comp_map_pool_id, 'Private', 115);
+
+    -- Create lineups
+    lineup_1_id := gen_random_uuid();
+    lineup_2_id := gen_random_uuid();
+    INSERT INTO match_lineups (id, team_id, team_name) VALUES (lineup_1_id, team_ids[team_1_idx], team_names[team_1_idx]);
+    INSERT INTO match_lineups (id, team_id, team_name) VALUES (lineup_2_id, team_ids[team_2_idx], team_names[team_2_idx]);
+
+    -- Create match
+    match_id := gen_random_uuid();
+    INSERT INTO matches (id, status, match_options_id, lineup_1_id, lineup_2_id, created_at, scheduled_at,
+                         started_at, ended_at, winning_lineup_id)
+    VALUES (match_id, 'Finished', match_options_id, lineup_1_id, lineup_2_id,
+            match_date - interval '1 hour', match_date, match_date,
+            match_date + interval '45 minutes',
+            CASE WHEN match_idx % 2 = 0 THEN lineup_1_id ELSE lineup_2_id END);
+
+    -- Add lineup players (5 per team)
+    FOR j IN 1..5 LOOP
+      INSERT INTO match_lineup_players (match_lineup_id, steam_id, captain, checked_in)
+      VALUES (lineup_1_id, p_steam_ids[(team_1_idx - 1) * 5 + j], j = 1, true);
+      INSERT INTO match_lineup_players (match_lineup_id, steam_id, captain, checked_in)
+      VALUES (lineup_2_id, p_steam_ids[(team_2_idx - 1) * 5 + j], j = 1, true);
+    END LOOP;
+
+    -- Create match map (BO1)
+    cur_map_id := map_ids[((match_idx + 3) % map_count) + 1];
+    match_map_id := gen_random_uuid();
+    INSERT INTO match_maps (id, match_id, map_id, "order", status, lineup_1_side, lineup_2_side, started_at, ended_at, winning_lineup_id)
+    VALUES (match_map_id, match_id, cur_map_id, 1, 'Finished', 'CT', 'TERRORIST',
+            match_date, match_date + interval '40 minutes',
+            CASE WHEN match_idx % 2 = 0 THEN lineup_1_id ELSE lineup_2_id END);
+
+    -- Map veto picks
+    DECLARE
+      ban_n int := 0;
+    BEGIN
+      FOR j IN 1..map_count LOOP
+        IF map_ids[j] != cur_map_id THEN
+          ban_n := ban_n + 1;
+          INSERT INTO match_map_veto_picks (match_id, type, match_lineup_id, map_id, created_at)
+          VALUES (match_id, 'Ban', CASE WHEN ban_n % 2 = 1 THEN lineup_1_id ELSE lineup_2_id END,
+                  map_ids[j], match_date - interval '10 minutes' + (interval '30 seconds' * ban_n));
+        END IF;
+      END LOOP;
+      ban_n := ban_n + 1;
+      INSERT INTO match_map_veto_picks (match_id, type, match_lineup_id, map_id, created_at)
+      VALUES (match_id, 'Decider', lineup_1_id, cur_map_id,
+              match_date - interval '10 minutes' + (interval '30 seconds' * ban_n));
+    END;
+
+    -- Determine score
+    IF match_idx % 2 = 0 THEN
+      l1_score := 13; l2_score := 5 + (match_idx % 8);
+    ELSE
+      l1_score := 5 + (match_idx % 8); l2_score := 13;
+    END IF;
+    total_rounds := l1_score + l2_score;
+
+    -- Generate rounds, kills, and utility
+    v_t1_wins := 0; v_t2_wins := 0;
+    FOR round_num IN 1..total_rounds LOOP
+      IF v_t1_wins * total_rounds < round_num * l1_score AND v_t1_wins < l1_score THEN
+        v_t1_wins := v_t1_wins + 1;
+        IF round_num <= 12 THEN winning_side := 'CT'; ELSE winning_side := 'TERRORIST'; END IF;
+      ELSE
+        v_t2_wins := v_t2_wins + 1;
+        IF round_num <= 12 THEN winning_side := 'TERRORIST'; ELSE winning_side := 'CT'; END IF;
+      END IF;
+
+      INSERT INTO match_map_rounds (
+        match_map_id, round, lineup_1_score, lineup_2_score,
+        lineup_1_money, lineup_2_money, time,
+        lineup_1_timeouts_available, lineup_2_timeouts_available,
+        winning_side, lineup_1_side, lineup_2_side)
+      VALUES (
+        match_map_id, round_num, v_t1_wins, v_t2_wins,
+        4100 + (round_num * 300), 4100 + (round_num * 300),
+        match_date + (interval '2 minutes' * round_num), 2, 2, winning_side,
+        CASE WHEN round_num <= 12 THEN 'CT' ELSE 'TERRORIST' END,
+        CASE WHEN round_num <= 12 THEN 'TERRORIST' ELSE 'CT' END);
+
+      -- Kills (5-7 per round)
+      FOR k IN 1..(5 + (round_num % 3)) LOOP
+        IF k % 2 = 1 THEN
+          attacker_idx := (team_1_idx - 1) * 5 + ((k - 1) % 5) + 1;
+          attacked_idx := (team_2_idx - 1) * 5 + ((k + round_num) % 5) + 1;
+        ELSE
+          attacker_idx := (team_2_idx - 1) * 5 + ((k - 1) % 5) + 1;
+          attacked_idx := (team_1_idx - 1) * 5 + ((k + round_num) % 5) + 1;
+        END IF;
+
+        weapon_idx := ((match_idx + round_num + k + 50) % array_length(weapons, 1)) + 1;
+        is_headshot := (match_idx + round_num + k + 1) % 3 = 0;
+        kill_time := match_date + (interval '2 minutes' * round_num) + (interval '5 seconds' * k);
+
+        INSERT INTO player_kills (
+          match_id, match_map_id, round,
+          attacker_steam_id, attacker_team,
+          attacked_steam_id, attacked_team, attacked_location,
+          "with", hitgroup, headshot, time)
+        VALUES (
+          match_id, match_map_id, round_num,
+          p_steam_ids[attacker_idx],
+          CASE WHEN k % 2 = 1 THEN 'CT' ELSE 'TERRORIST' END,
+          p_steam_ids[attacked_idx],
+          CASE WHEN k % 2 = 1 THEN 'TERRORIST' ELSE 'CT' END,
+          'BombsiteA', weapons[weapon_idx],
+          CASE WHEN is_headshot THEN 'head' ELSE hitgroups[((k + round_num) % 6) + 2] END,
+          is_headshot, kill_time)
+        ON CONFLICT DO NOTHING;
+
+        -- Track stats
+        kill_counts[attacker_idx] := kill_counts[attacker_idx] + 1;
+        death_counts[attacked_idx] := death_counts[attacked_idx] + 1;
+        IF is_headshot THEN
+          headshot_counts[attacker_idx] := headshot_counts[attacker_idx] + 1;
+        END IF;
+
+        DECLARE
+          wkey text := p_steam_ids[attacker_idx]::text || ':' || weapons[weapon_idx];
+        BEGIN
+          IF weapon_kill_map ? wkey THEN
+            weapon_kill_map := jsonb_set(weapon_kill_map, ARRAY[wkey], to_jsonb((weapon_kill_map->>wkey)::int + 1));
+          ELSE
+            weapon_kill_map := weapon_kill_map || jsonb_build_object(wkey, 1);
+          END IF;
+        END;
+      END LOOP; -- kills per round
+
+      -- Utility events (flash + smoke per round)
+      DECLARE
+        ut timestamptz;
+        fp1 int := (team_1_idx - 1) * 5 + ((round_num + 1) % 5) + 1;
+        fp2 int := (team_2_idx - 1) * 5 + ((round_num + 2) % 5) + 1;
+        fe1 int := (team_2_idx - 1) * 5 + ((round_num + 3) % 5) + 1;
+        fe2 int := (team_1_idx - 1) * 5 + ((round_num + 4) % 5) + 1;
+      BEGIN
+        ut := match_date + (interval '2 minutes' * round_num) + interval '40 seconds';
+        INSERT INTO player_utility (match_map_id, attacker_steam_id, time, match_id, round, type)
+        VALUES (match_map_id, p_steam_ids[fp1], ut, match_id, round_num, 'Flash') ON CONFLICT DO NOTHING;
+        INSERT INTO player_flashes (match_map_id, time, attacker_steam_id, attacked_steam_id, match_id, round, duration, team_flash)
+        VALUES (match_map_id, ut + interval '1 second', p_steam_ids[fp1], p_steam_ids[fe1], match_id, round_num,
+                1.5 + (round_num % 3)::numeric * 0.5, false) ON CONFLICT DO NOTHING;
+
+        ut := match_date + (interval '2 minutes' * round_num) + interval '50 seconds';
+        INSERT INTO player_utility (match_map_id, attacker_steam_id, time, match_id, round, type)
+        VALUES (match_map_id, p_steam_ids[fp2], ut, match_id, round_num, 'Flash') ON CONFLICT DO NOTHING;
+        INSERT INTO player_flashes (match_map_id, time, attacker_steam_id, attacked_steam_id, match_id, round, duration, team_flash)
+        VALUES (match_map_id, ut + interval '1 second', p_steam_ids[fp2], p_steam_ids[fe2], match_id, round_num,
+                1.5 + ((round_num + 1) % 3)::numeric * 0.5, false) ON CONFLICT DO NOTHING;
+
+        ut := match_date + (interval '2 minutes' * round_num) + interval '35 seconds';
+        INSERT INTO player_utility (match_map_id, attacker_steam_id, time, match_id, round, type)
+        VALUES (match_map_id, p_steam_ids[(team_1_idx - 1) * 5 + ((round_num + 3) % 5) + 1], ut, match_id, round_num, 'Smoke') ON CONFLICT DO NOTHING;
+      END;
+    END LOOP; -- rounds
+  END LOOP; -- additional matches
+
   -- ==========================================
   -- 6. POPULATE AGGREGATE TABLES
   -- ==========================================
diff --git a/hasura/metadata/actions.graphql b/hasura/metadata/actions.graphql
@@ -334,6 +334,33 @@ type Mutation {
   ): SuccessOutput
 }
 
+type Query {
+  getLeaderboard(
+    category: String!
+    window_days: Int!
+    match_type: String
+    limit: Int
+    offset: Int
+    exclude_tournaments: Boolean
+  ): LeaderboardResponse!
+}
+
+type LeaderboardResponse {
+  entries: [LeaderboardEntry!]!
+  total: Int!
+}
+
+type LeaderboardEntry {
+  rank: Int!
+  player_steam_id: String!
+  player_name: String!
+  player_avatar_url: String
+  player_country: String
+  value: Float!
+  secondary_value: Float
+  matches_played: Int
+}
+
 input SampleInput {
   username: String!
   password: String!
diff --git a/hasura/metadata/actions.yaml b/hasura/metadata/actions.yaml
@@ -443,6 +443,14 @@ actions:
     permissions:
       - role: administrator
     comment: Write content to file on game server
+  - name: getLeaderboard
+    definition:
+      kind: ""
+      handler: '{{HASURA_GRAPHQL_ACTIONS_HOOK}}'
+      forward_client_headers: true
+    permissions:
+      - role: guest
+    comment: Get leaderboard rankings by category and time window
 custom_types:
   enums: []
   input_objects:
@@ -496,4 +504,6 @@ custom_types:
     - name: StorageStats
     - name: StorageSummary
     - name: TableSizeInfo
+    - name: LeaderboardResponse
+    - name: LeaderboardEntry
   scalars: []
diff --git a/src/app.module.ts b/src/app.module.ts
@@ -43,6 +43,7 @@ import { K8sModule } from "./k8s/k8s.module";
 import { FileManagerModule } from "./file-manager/file-manager.module";
 import { BrandingModule } from "./branding/branding.module";
 import { FixturesModule } from "./fixtures/fixtures.module";
+import { LeaderboardModule } from "./leaderboard/leaderboard.module";
 
 @Module({
   imports: [
@@ -126,6 +127,7 @@ import { FixturesModule } from "./fixtures/fixtures.module";
     FileManagerModule,
     BrandingModule,
     FixturesModule,
+    LeaderboardModule,
   ],
   providers: [loggerFactory()],
   controllers: [AppController, QuickConnectController],
diff --git a/src/fixtures/fixtures.controller.ts b/src/fixtures/fixtures.controller.ts
@@ -43,6 +43,28 @@ export class FixturesController {
       this.logger.log("Fixtures: Loading fixture data...");
       await this.postgres.query(fixturesSql);
 
+      this.logger.log("Fixtures: Generating player ELO ratings...");
+      await this.postgres.query(`
+        DO $$
+        DECLARE
+          m RECORD;
+        BEGIN
+          DELETE FROM player_elo
+          WHERE match_id IN (
+            SELECT id FROM matches
+            WHERE ended_at IS NOT NULL AND winning_lineup_id IS NOT NULL
+          );
+          FOR m IN
+            SELECT id FROM matches
+            WHERE ended_at IS NOT NULL
+              AND winning_lineup_id IS NOT NULL
+            ORDER BY created_at ASC
+          LOOP
+            PERFORM generate_player_elo_for_match(m.id);
+          END LOOP;
+        END $$;
+      `);
+
       this.logger.log("Fixtures: Refreshing Typesense player index...");
       await this.typesenseQueue.add(RefreshAllPlayersJob.name, {});
 
diff --git a/src/leaderboard/leaderboard.controller.ts b/src/leaderboard/leaderboard.controller.ts
diff --git a/src/leaderboard/leaderboard.module.ts b/src/leaderboard/leaderboard.module.ts
