diff --git a/README.md b/README.md index c9f62519..cbe4077b 100644 --- a/README.md +++ b/README.md @@ -343,6 +343,7 @@ All primary endpoints are versioned under `/api/v1` (legacy `/api/*` routes are | **Evidence ledger** | `/evidence/claims` | Required | Current user's evidence, optionally filtered by `subjectType` and `verificationStatus` | | **Focus** | `/focus` | Required | Stopwatch sessions, Pomodoro cycle tracking, and checklists | | **Gamification** | `/xp`, `/streak`, `/missions` | Required | XP allocation sagas, streak updates with freeze mechanics | +| **Weekly leagues** | `/leagues` | Required | Opt-in weekly cohorts: live Redis standings, Sunday 00:00 UTC rollover with promotion and demotion | | **Projects** | `/projects` | Required | Project and task CRUD operations, GitHub repository links | | **Platforms** | `/platforms` | Required | Third-party platform synchronizers (LeetCode, Codeforces, GitHub) | | **Ops (Admin)** | `/ops` | Auditor / Admin | Queue metrics, Dead Letter Queue (DLQ) inspection, and replays | @@ -355,6 +356,12 @@ With evidence writers stopped and `MONGODB_URI` explicitly set to the intended d To roll back, stop the ledger-enabled app and run the same command with `down`. This removes the index and the fields added to legacy rows. Claims written by the ledger remain in MongoDB. If you also revert the application to a pre-ledger release, its resume queries can include retained platform claims because they lack subject filtering. +### Weekly leagues migration + +Run `npm run migrate:leagues --prefix backend -- up` with `MONGODB_URI` explicitly set. It creates the `leaguestandings` indexes and writes `leagues.participate: false` onto existing user settings (leagues are opt-in). `down` drops those indexes and removes the `leagues` settings field; `LeagueStanding` rows are kept as history. + +Live standings are Redis sorted sets named `league:{weekKey}:{division}:{cohortId}`, scored by the `league-score` queue. The `league-rollover` repeatable job (Sunday 00:00 UTC) is scheduled by the `maintenance` worker role and the score worker runs in the `xp` role. If Redis is flushed, the next standings read rebuilds the affected cohort from the `XpTransaction` ledger. + ## Security & Performance Hardening * **Tiered Rate Limiting:** High-sensitivity authentication and sync routes enforce strict windows (5 requests per 15 min), while dashboard reads allow higher throughput (`backend/src/middleware/rateLimitAdvanced.ts`). diff --git a/backend/package.json b/backend/package.json index 809ca394..5f68358b 100644 --- a/backend/package.json +++ b/backend/package.json @@ -22,6 +22,7 @@ "start": "node dist/index.js", "test": "vitest run", "migrate:evidence-ledger": "tsx src/db/migrations/run-evidence-ledger.ts", + "migrate:leagues": "tsx src/db/migrations/run-leagues.ts", "migrate:daily-challenge-tiers": "tsx src/db/migrations/run-daily-challenge-tiers.ts", "test:safety": "vitest run -c vitest.safety.config.ts", "test:unit": "npm run test:safety && vitest run", diff --git a/backend/src/__tests__/db/modelIndexes.test.ts b/backend/src/__tests__/db/modelIndexes.test.ts index 5635b144..62e3f4ea 100644 --- a/backend/src/__tests__/db/modelIndexes.test.ts +++ b/backend/src/__tests__/db/modelIndexes.test.ts @@ -41,6 +41,7 @@ import '../../db/models/feedbackReport.model.js'; import '../../db/models/fineTuneRun.model.js'; import '../../db/models/focusSession.model.js'; import '../../db/models/intelligenceRecommendation.model.js'; +import '../../db/models/leagueStanding.model.js'; import '../../db/models/mlBaseline.model.js'; import '../../db/models/mlExperiment.model.js'; import '../../db/models/mission.model.js'; diff --git a/backend/src/__tests__/modules/leagues/cohorts.test.ts b/backend/src/__tests__/modules/leagues/cohorts.test.ts new file mode 100644 index 00000000..82a86776 --- /dev/null +++ b/backend/src/__tests__/modules/leagues/cohorts.test.ts @@ -0,0 +1,78 @@ +import { describe, expect, it } from 'vitest'; +import { assignCohorts, cohortIdFor, partitionIntoCohorts, pickCohortForLateJoiner } from '../../../modules/leagues/cohorts.js'; + +const users = (n: number) => Array.from({ length: n }, (_, i) => `user-${String(i).padStart(3, '0')}`); + +describe('partitionIntoCohorts', () => { + it('returns nothing for an empty division', () => { + expect(partitionIntoCohorts([], 'seed')).toEqual([]); + }); + + it('keeps a division smaller than the minimum in a single cohort', () => { + expect(partitionIntoCohorts(users(4), 'seed')).toHaveLength(1); + }); + + it('fills cohorts of 30', () => { + const cohorts = partitionIntoCohorts(users(60), 'seed'); + expect(cohorts.map(c => c.length)).toEqual([30, 30]); + }); + + it('keeps a leftover of exactly the minimum (10) as its own cohort', () => { + expect(partitionIntoCohorts(users(70), 'seed').map(c => c.length)).toEqual([30, 30, 10]); + }); + + it('merges a leftover smaller than 10 into the previous cohort', () => { + expect(partitionIntoCohorts(users(69), 'seed').map(c => c.length)).toEqual([30, 39]); + expect(partitionIntoCohorts(users(31), 'seed').map(c => c.length)).toEqual([31]); + expect(partitionIntoCohorts(users(129), 'seed').map(c => c.length)).toEqual([30, 30, 30, 39]); + }); + + it('places every user exactly once, even if the input repeats an id', () => { + const ids = [...users(45), 'user-000', 'user-001']; + const placed = partitionIntoCohorts(ids, 'seed').flat(); + expect(placed).toHaveLength(45); + expect(new Set(placed).size).toBe(45); + }); + + it('is deterministic for a seed and independent of input order', () => { + const forward = partitionIntoCohorts(users(75), 'week-a'); + const backward = partitionIntoCohorts([...users(75)].reverse(), 'week-a'); + expect(backward).toEqual(forward); + }); + + it('shuffles differently for another seed', () => { + expect(partitionIntoCohorts(users(75), 'week-a')).not.toEqual(partitionIntoCohorts(users(75), 'week-b')); + }); + + it('honours custom sizing', () => { + expect(partitionIntoCohorts(users(25), 'seed', { target: 10, min: 5 }).map(c => c.length)).toEqual([10, 10, 5]); + expect(partitionIntoCohorts(users(23), 'seed', { target: 10, min: 5 }).map(c => c.length)).toEqual([10, 13]); + }); +}); + +describe('assignCohorts', () => { + it('labels cohorts c1, c2, ... and covers all users', () => { + const assignments = assignCohorts(users(61), 'seed'); + expect(new Set(assignments.map(a => a.cohortId))).toEqual(new Set(['c1', 'c2'])); + expect(assignments).toHaveLength(61); + expect(cohortIdFor(0)).toBe('c1'); + }); +}); + +describe('pickCohortForLateJoiner', () => { + it('starts c1 when the division has no cohorts yet', () => { + expect(pickCohortForLateJoiner(new Map())).toBe('c1'); + }); + + it('joins the emptiest cohort that has room', () => { + expect(pickCohortForLateJoiner(new Map([['c1', 30], ['c2', 12], ['c3', 20]]))).toBe('c2'); + }); + + it('breaks size ties by cohort number, not by string order', () => { + expect(pickCohortForLateJoiner(new Map([['c10', 5], ['c2', 5]]))).toBe('c2'); + }); + + it('opens a new cohort when every cohort is full', () => { + expect(pickCohortForLateJoiner(new Map([['c1', 30], ['c2', 30]]))).toBe('c3'); + }); +}); diff --git a/backend/src/__tests__/modules/leagues/fakeScoreStore.ts b/backend/src/__tests__/modules/leagues/fakeScoreStore.ts new file mode 100644 index 00000000..501d48e3 --- /dev/null +++ b/backend/src/__tests__/modules/leagues/fakeScoreStore.ts @@ -0,0 +1,63 @@ +// In-memory stand-in for the Redis sorted sets, so league tests never need a Redis server. +// Ordering matches ZREVRANGE: higher score first, equal scores in reverse lexicographic order. +import type { LeagueScoreStore, ScoreEntry } from '../../../modules/leagues/scoreStore.js'; + +export class FakeScoreStore implements LeagueScoreStore { + readonly sets = new Map>(); + readonly applied = new Map>(); + readonly ttls = new Map(); + + async incrementOnce(key: string, member: string, delta: number, dedupe: { setKey: string; id: string }) { + const seen = this.applied.get(dedupe.setKey) ?? new Set(); + this.applied.set(dedupe.setKey, seen); + if (seen.has(dedupe.id)) return null; + seen.add(dedupe.id); + const set = this.sets.get(key) ?? new Map(); + this.sets.set(key, set); + const score = (set.get(member) ?? 0) + delta; + set.set(member, score); + return score; + } + + async seed(key: string, members: string[]) { + if (members.length === 0) return; + const set = this.sets.get(key) ?? new Map(); + this.sets.set(key, set); + for (const member of members) if (!set.has(member)) set.set(member, 0); + } + + async replace(key: string, entries: ScoreEntry[]) { + if (entries.length === 0) this.sets.delete(key); + else this.sets.set(key, new Map(entries.map(e => [e.member, e.score]))); + } + + async remove(key: string, member: string) { + this.sets.get(key)?.delete(member); + } + + async ranked(key: string, start: number, stop: number) { + const all = [...(this.sets.get(key) ?? new Map())] + .map(([member, score]) => ({ member, score })) + .sort((a, b) => b.score - a.score || (a.member < b.member ? 1 : a.member > b.member ? -1 : 0)); + return all.slice(start, stop === -1 ? undefined : stop + 1); + } + + async exists(key: string) { + return this.sets.has(key); + } + + async expire(key: string, seconds: number) { + if (this.sets.has(key)) this.ttls.set(key, seconds); + } + + score(key: string, member: string): number | undefined { + return this.sets.get(key)?.get(member); + } + + /** Simulates FLUSHALL on the Redis the leagues use. */ + flush() { + this.sets.clear(); + this.applied.clear(); + this.ttls.clear(); + } +} diff --git a/backend/src/__tests__/modules/leagues/leagues.migration.test.ts b/backend/src/__tests__/modules/leagues/leagues.migration.test.ts new file mode 100644 index 00000000..58aea570 --- /dev/null +++ b/backend/src/__tests__/modules/leagues/leagues.migration.test.ts @@ -0,0 +1,39 @@ +import mongoose from 'mongoose'; +import { describe, expect, it } from 'vitest'; +import { migrateLeagues, rollbackLeagues } from '../../../db/migrations/0012-leagues.js'; +import { LEAGUE_STANDING_INDEXES } from '../../../db/models/leagueStandingIndexes.js'; +import { LeagueStanding } from '../../../db/models/index.js'; + +describe('0012-leagues migration', () => { + it('creates the standing indexes, backfills the opt-in flag and rolls back cleanly', async () => { + const db = mongoose.connection.db!; + const settings = db.collection('usersettings'); + const standings = db.collection('leaguestandings'); + await LeagueStanding.createCollection(); + await rollbackLeagues(db); + + const legacy = await settings.insertOne({ userId: new mongoose.Types.ObjectId(), appearance: { theme: 'dark' } }); + const optedIn = await settings.insertOne({ userId: new mongoose.Types.ObjectId(), leagues: { participate: true } }); + + await migrateLeagues(db); + await migrateLeagues(db); // safe to run twice + + const indexNames = (await standings.indexes()).map(index => index.name); + for (const { options } of LEAGUE_STANDING_INDEXES) expect(indexNames).toContain(options.name); + const unique = (await standings.indexes()).find(index => index.name === 'uq_leaguestandings_week_user'); + expect(unique).toMatchObject({ key: { weekKey: 1, userId: 1 }, unique: true }); + + expect(await settings.findOne({ _id: legacy.insertedId })).toMatchObject({ leagues: { participate: false }, appearance: { theme: 'dark' } }); + expect(await settings.findOne({ _id: optedIn.insertedId })).toMatchObject({ leagues: { participate: true } }); // never overwritten + + await rollbackLeagues(db); + await rollbackLeagues(db); // and twice + const after = (await standings.indexes()).map(index => index.name); + for (const { options } of LEAGUE_STANDING_INDEXES) expect(after).not.toContain(options.name); + expect(await settings.findOne({ _id: legacy.insertedId })).not.toHaveProperty('leagues'); + }); + + it('rolls back on a database that never ran the migration', async () => { + await expect(rollbackLeagues(mongoose.connection.db!)).resolves.toBeUndefined(); + }); +}); diff --git a/backend/src/__tests__/modules/leagues/leagues.routes.test.ts b/backend/src/__tests__/modules/leagues/leagues.routes.test.ts new file mode 100644 index 00000000..7aef5a5e --- /dev/null +++ b/backend/src/__tests__/modules/leagues/leagues.routes.test.ts @@ -0,0 +1,95 @@ +import type { AddressInfo } from 'node:net'; +import type { Server } from 'node:http'; +import express from 'express'; +import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'; +import { Types } from 'mongoose'; +import { LeagueStanding, UserSettings, User } from '../../../db/models/index.js'; +import { errorHandler } from '../../../middleware/error.js'; +import { FakeScoreStore } from './fakeScoreStore.js'; + +const shared = vi.hoisted(() => ({ userId: '000000000000000000000001', store: null as unknown })); + +vi.mock('../../../middleware/index.js', async () => { + const { asyncHandler } = await import('../../../middleware/error.js'); + const { commonErrors } = await import('../../../shared/response.js'); + return { + asyncHandler, + authMiddleware: (req: express.Request, res: express.Response, next: express.NextFunction) => { + if (req.get('authorization') !== 'Bearer league-token') return commonErrors.unauthorized(res); + Object.assign(req, { user: { id: shared.userId } }); + next(); + }, + }; +}); +vi.mock('../../../modules/leagues/scoreStore.js', async importOriginal => ({ + ...(await importOriginal()), + getLeagueScoreStore: () => shared.store, +})); + +import { leaguesRoutes } from '../../../modules/leagues/leagues.routes.js'; + +let server: Server; +let base: string; +const headers = { authorization: 'Bearer league-token', 'content-type': 'application/json' }; + +beforeAll(async () => { + const app = express(); + app.use(express.json()); + app.use('/api/v1/leagues', leaguesRoutes); + app.use(errorHandler); + server = app.listen(0, '127.0.0.1'); + await new Promise(resolve => server.once('listening', resolve)); + base = `http://127.0.0.1:${(server.address() as AddressInfo).port}/api/v1/leagues`; +}); +afterAll(() => new Promise(resolve => server.close(() => resolve()))); +beforeEach(() => { shared.store = new FakeScoreStore(); }); + +describe('weekly leagues routes', () => { + it('requires authentication', async () => { + expect((await fetch(`${base}/current`)).status).toBe(401); + expect((await fetch(`${base}/participation`, { method: 'PUT', body: '{}' })).status).toBe(401); + }); + + it('GET /current says "not participating" until the user opts in (default off)', async () => { + const res = await fetch(`${base}/current`, { headers }); + const body = await res.json(); + expect(res.status).toBe(200); + expect(body.data).toMatchObject({ participating: false, standings: [], me: null }); + expect(body.data.secondsUntilReset).toBeGreaterThan(0); + expect(await LeagueStanding.countDocuments()).toBe(0); + }); + + it('PUT /participation opts in, then GET /current returns the cohort with the caller in it', async () => { + await User.create({ _id: new Types.ObjectId(shared.userId), clerkId: 'c-1', email: 'one@example.com', username: 'one', displayName: 'One' }); + + const put = await fetch(`${base}/participation`, { method: 'PUT', headers, body: JSON.stringify({ participate: true }) }); + expect(put.status).toBe(200); + expect((await put.json()).data).toEqual({ participating: true }); + expect(await UserSettings.countDocuments({ userId: new Types.ObjectId(shared.userId), 'leagues.participate': true })).toBe(1); + + const current = (await (await fetch(`${base}/current`, { headers })).json()).data; + expect(current).toMatchObject({ participating: true, division: 'bronze', cohortId: 'c1', cohortSize: 1, me: { rank: 1, points: 0 } }); + expect(current.standings).toEqual([ + { rank: 1, userId: shared.userId, username: 'one', displayName: 'One', avatarUrl: null, points: 0, isMe: true }, + ]); + }); + + it('PUT /participation with false leaves the league', async () => { + await fetch(`${base}/participation`, { method: 'PUT', headers, body: JSON.stringify({ participate: true }) }); + const off = await fetch(`${base}/participation`, { method: 'PUT', headers, body: JSON.stringify({ participate: false }) }); + expect((await off.json()).data).toEqual({ participating: false }); + expect(await LeagueStanding.countDocuments({ status: 'active' })).toBe(0); + expect((await (await fetch(`${base}/current`, { headers })).json()).data.participating).toBe(false); + }); + + it.each([ + ['missing field', {}], + ['string instead of boolean', { participate: 'yes' }], + ['unknown key', { participate: true, division: 'master' }], + ])('PUT /participation rejects %s', async (_name, payload) => { + const res = await fetch(`${base}/participation`, { method: 'PUT', headers, body: JSON.stringify(payload) }); + expect(res.status).toBe(400); + expect((await res.json()).code).toBe('VALIDATION_ERROR'); + expect(await UserSettings.countDocuments()).toBe(0); + }); +}); diff --git a/backend/src/__tests__/modules/leagues/rollover.test.ts b/backend/src/__tests__/modules/leagues/rollover.test.ts new file mode 100644 index 00000000..a006aa77 --- /dev/null +++ b/backend/src/__tests__/modules/leagues/rollover.test.ts @@ -0,0 +1,506 @@ +// Weekly leagues: cohort assignment, score increments, rollover transitions, idempotency and +// Redis rebuild. MongoDB is the in-memory server from the shared test setup; the Redis sorted +// sets are replaced by FakeScoreStore, so no Redis server is involved. +import { beforeEach, describe, expect, it, vi } from 'vitest'; +import { Types } from 'mongoose'; +import { LeagueStanding, UserSettings, User, XpTransaction } from '../../../db/models/index.js'; +import type { LeagueDivision } from '../../../db/models/index.js'; +import { cohortKey } from '../../../modules/leagues/leagues.constants.js'; +import { + getCurrentStandings, + isParticipating, + joinCurrentWeek, + rebuildWeekFromLedger, + recordXpAward, + setParticipation, +} from '../../../modules/leagues/leagues.service.js'; +import { computeCohortOutcomes, runWeeklyRollover, type WeekFinalizedPayload } from '../../../modules/leagues/rollover.js'; +import { processLeagueScoreJob } from '../../../modules/leagues/workers/leagueScore.worker.js'; +import { weekToFinalize } from '../../../modules/leagues/workers/weeklyRollover.worker.js'; +import { FakeScoreStore } from './fakeScoreStore.js'; + +const PREVIOUS = '2026-11-08'; +const WEEK = '2026-11-15'; +const NEXT = '2026-11-22'; +const MID_WEEK = new Date('2026-11-18T12:00:00.000Z'); +const ROLLOVER_AT = new Date('2026-11-22T00:00:05.000Z'); + +let store: FakeScoreStore; +let counter = 0; + +beforeEach(() => { + store = new FakeScoreStore(); + counter = 0; +}); + +async function makeUsers(n: number, participate = true): Promise { + const ids = Array.from({ length: n }, () => new Types.ObjectId()); + await UserSettings.insertMany(ids.map(userId => ({ userId, leagues: { participate } }))); + return ids.map(id => id.toString()); +} + +/** Gives users a finalized earlier week that sends them to `division` this week. */ +async function startIn(ids: string[], division: LeagueDivision) { + await LeagueStanding.insertMany(ids.map(id => ({ + weekKey: PREVIOUS, userId: new Types.ObjectId(id), division, cohortId: 'c1', status: 'finalized', + joinedAt: new Date('2026-11-08T00:00:00Z'), points: 1, rank: 1, cohortSize: 1, outcome: 'stayed', + nextDivision: division, finalizedAt: new Date('2026-11-15T00:00:00Z'), + }))); +} + +async function joinAll(ids: string[], at = MID_WEEK) { + for (const id of ids) await joinCurrentWeek(id, at, store); +} + +async function award(userId: string, xp: number, at = MID_WEEK, sourceId = `src-${++counter}`) { + return recordXpAward({ userId, sourceType: 'dsa_accepted', sourceId, xpAwarded: xp, occurredAt: at }, store, at); +} + +const row = (userId: string, weekKey: string) => LeagueStanding.findOne({ weekKey, userId: new Types.ObjectId(userId) }).lean(); + +async function snapshot(weekKey: string) { + return (await LeagueStanding.find({ weekKey }).sort({ userId: 1 }).lean()).map(r => ({ + userId: r.userId.toString(), division: r.division, cohortId: r.cohortId, status: r.status, + points: r.points, rank: r.rank, outcome: r.outcome, nextDivision: r.nextDivision, + })); +} + +describe('opt-in setting', () => { + it('defaults leagues.participate to false', async () => { + const userId = new Types.ObjectId(); + const settings = await UserSettings.create({ userId }); + expect(settings.leagues.participate).toBe(false); + expect(await isParticipating(userId.toString())).toBe(false); + }); + + it('setParticipation creates the settings document and places the user in a cohort', async () => { + const userId = new Types.ObjectId().toString(); + await setParticipation(userId, true, MID_WEEK, store); + expect(await isParticipating(userId)).toBe(true); + expect(await row(userId, WEEK)).toMatchObject({ division: 'bronze', cohortId: 'c1', status: 'active' }); + expect(store.score(cohortKey(WEEK, 'bronze', 'c1'), userId)).toBe(0); + }); + + it('opting out removes the live row and the Redis member but keeps history', async () => { + const [userId] = await makeUsers(1); + await startIn([userId], 'silver'); + await joinAll([userId]); + await award(userId, 40); + await setParticipation(userId, false, MID_WEEK, store); + + expect(await isParticipating(userId)).toBe(false); + expect(await row(userId, WEEK)).toBeNull(); + expect(store.score(cohortKey(WEEK, 'silver', 'c1'), userId)).toBeUndefined(); + expect(await row(userId, PREVIOUS)).not.toBeNull(); + }); +}); + +describe('cohort assignment', () => { + it('starts new users in bronze and uses the division of their last finalized week otherwise', async () => { + const [fresh, veteran] = await makeUsers(2); + await startIn([veteran], 'diamond'); + await joinAll([fresh, veteran]); + expect(await row(fresh, WEEK)).toMatchObject({ division: 'bronze' }); + expect(await row(veteran, WEEK)).toMatchObject({ division: 'diamond' }); + }); + + it('is idempotent for the same user and week', async () => { + const [userId] = await makeUsers(1); + await joinAll([userId]); + await joinAll([userId]); + expect(await LeagueStanding.countDocuments({ weekKey: WEEK })).toBe(1); + }); + + it('fills a cohort to 30 and opens the next one for late joiners', async () => { + const ids = await makeUsers(31); + await joinAll(ids); + const cohorts = await LeagueStanding.aggregate([{ $match: { weekKey: WEEK } }, { $group: { _id: '$cohortId', n: { $sum: 1 } } }, { $sort: { _id: 1 } }]); + expect(cohorts).toEqual([{ _id: 'c1', n: 30 }, { _id: 'c2', n: 1 }]); + }); + + it('settles concurrent joins of one user into a single row', async () => { + const [userId] = await makeUsers(1); + await Promise.all([joinCurrentWeek(userId, MID_WEEK, store), joinCurrentWeek(userId, MID_WEEK, store), joinCurrentWeek(userId, MID_WEEK, store)]); + expect(await LeagueStanding.countDocuments({ weekKey: WEEK })).toBe(1); + }); +}); + +describe('score increments from XP awards', () => { + it('adds the awarded XP to the user in the active cohort sorted set', async () => { + const [a, b] = await makeUsers(2); + await joinAll([a, b]); + expect(await award(a, 10)).toMatchObject({ applied: true, weekKey: WEEK, score: 10 }); + expect(await award(a, 25)).toMatchObject({ applied: true, score: 35 }); + await award(b, 5); + const key = cohortKey(WEEK, 'bronze', 'c1'); + expect(store.score(key, a)).toBe(35); + expect(store.score(key, b)).toBe(5); + }); + + it('places an opted-in user without a row on their first award of the week', async () => { + const [userId] = await makeUsers(1); + expect(await award(userId, 20)).toMatchObject({ applied: true, score: 20 }); + expect(await row(userId, WEEK)).toMatchObject({ status: 'active' }); + }); + + it('ignores users who did not opt in', async () => { + const [userId] = await makeUsers(1, false); + expect(await award(userId, 20)).toEqual({ applied: false, reason: 'not_participating' }); + expect(await LeagueStanding.countDocuments()).toBe(0); + }); + + it('adds 0 for awards without XP, e.g. a focus session that did not qualify', async () => { + const [userId] = await makeUsers(1); + await joinAll([userId]); + expect(await award(userId, 0)).toEqual({ applied: false, reason: 'no_xp' }); + expect(await award(userId, -5)).toEqual({ applied: false, reason: 'no_xp' }); + expect(await award(userId, 2.5)).toEqual({ applied: false, reason: 'no_xp' }); + expect(store.score(cohortKey(WEEK, 'bronze', 'c1'), userId)).toBe(0); + }); + + it('counts a replayed award once', async () => { + const [userId] = await makeUsers(1); + await joinAll([userId]); + expect(await award(userId, 15, MID_WEEK, 'same-source')).toMatchObject({ applied: true }); + expect(await award(userId, 15, MID_WEEK, 'same-source')).toEqual({ applied: false, reason: 'duplicate' }); + expect(store.score(cohortKey(WEEK, 'bronze', 'c1'), userId)).toBe(15); + }); + + it('drops XP earned before the user joined, and XP that arrives after the week was finalized', async () => { + const [userId] = await makeUsers(1); + await joinAll([userId]); + expect(await award(userId, 10, new Date('2026-11-18T11:00:00Z'))).toEqual({ applied: false, reason: 'before_join' }); + + await runWeeklyRollover(WEEK, { store, now: ROLLOVER_AT, notify: vi.fn() }); + expect(await award(userId, 10, new Date('2026-11-21T23:59:00Z'))).toEqual({ applied: false, reason: 'week_closed' }); + }); + + it('puts an award in the week of its ledger timestamp, not of the time the job ran', async () => { + const [userId] = await makeUsers(1); + await joinAll([userId], new Date('2026-11-15T00:00:00Z')); + const result = await recordXpAward( + { userId, sourceType: 'dsa_accepted', sourceId: 'late-job', xpAwarded: 30, occurredAt: new Date('2026-11-21T23:59:59Z') }, + store, + new Date('2026-11-22T00:00:02Z'), + ); + expect(result).toMatchObject({ applied: true, weekKey: WEEK, score: 30 }); + }); + + it('the score worker handler validates its job and applies it', async () => { + const [userId] = await makeUsers(1); + await joinAll([userId]); + const data = { userId, sourceType: 'dsa_accepted', sourceId: 'p-1', xpAwarded: 12, occurredAt: MID_WEEK.toISOString() }; + expect(await processLeagueScoreJob(data, store, MID_WEEK)).toMatchObject({ applied: true, score: 12 }); + await expect(processLeagueScoreJob({ ...data, occurredAt: 'not a date' }, store, MID_WEEK)).rejects.toThrow(/invalid occurredAt/); + }); +}); + +describe('computeCohortOutcomes', () => { + const board = (n: number) => Array.from({ length: n }, (_, i) => ({ userId: `u${i + 1}`, points: (n - i) * 10 })); + const outcomes = (division: LeagueDivision, n: number) => computeCohortOutcomes(division, board(n)).map(s => s.outcome); + + it('promotes the top 20% and demotes the bottom 20% of a cohort of 30', () => { + const result = outcomes('gold', 30); + expect(result.slice(0, 6)).toEqual(Array(6).fill('promoted')); + expect(result.slice(6, 24)).toEqual(Array(18).fill('stayed')); + expect(result.slice(24)).toEqual(Array(6).fill('demoted')); + }); + + it('rounds the 20% down, so small cohorts move fewer people', () => { + expect(outcomes('gold', 4)).toEqual(['stayed', 'stayed', 'stayed', 'stayed']); + expect(outcomes('gold', 9).filter(o => o === 'promoted')).toHaveLength(1); + expect(outcomes('gold', 10).filter(o => o === 'demoted')).toHaveLength(2); + }); + + it('cannot demote out of bronze or promote out of grandmaster', () => { + expect(outcomes('bronze', 10)).toEqual(['promoted', 'promoted', ...Array(8).fill('stayed')]); + expect(outcomes('grandmaster', 10)).toEqual([...Array(8).fill('stayed'), 'demoted', 'demoted']); + }); + + it('moves exactly one division and reports rank, points and cohort size', () => { + const [first, , , , , , , , , last] = computeCohortOutcomes('silver', board(10)); + expect(first).toEqual({ userId: 'u1', rank: 1, points: 100, cohortSize: 10, outcome: 'promoted', nextDivision: 'gold' }); + expect(last).toEqual({ userId: 'u10', rank: 10, points: 10, cohortSize: 10, outcome: 'demoted', nextDivision: 'bronze' }); + }); +}); + +describe('weekly rollover', () => { + /** 10 gold users; user i earns (i + 1) * 10 XP, so index 9 is rank 1. */ + async function goldCohort() { + const ids = await makeUsers(10); + await startIn(ids, 'gold'); + await joinAll(ids); + for (const [i, id] of ids.entries()) await award(id, (i + 1) * 10); + return ids; + } + + it('finalizes ranks, promotes the top 20%, demotes the bottom 20% and persists the records', async () => { + const ids = await goldCohort(); + const notify = vi.fn(); + const result = await runWeeklyRollover(WEEK, { store, now: ROLLOVER_AT, notify }); + + expect(result).toMatchObject({ weekKey: WEEK, nextWeekKey: NEXT, finalized: 10, promoted: 2, demoted: 2, assigned: 10 }); + const rows = await Promise.all(ids.map(id => row(id, WEEK))); + expect(rows.map(r => r!.rank)).toEqual([10, 9, 8, 7, 6, 5, 4, 3, 2, 1]); + expect(rows.map(r => r!.points)).toEqual([10, 20, 30, 40, 50, 60, 70, 80, 90, 100]); + expect(rows.map(r => r!.outcome)).toEqual([ + 'demoted', 'demoted', 'stayed', 'stayed', 'stayed', 'stayed', 'stayed', 'stayed', 'promoted', 'promoted', + ]); + expect(rows.map(r => r!.nextDivision)).toEqual([ + 'silver', 'silver', 'gold', 'gold', 'gold', 'gold', 'gold', 'gold', 'platinum', 'platinum', + ]); + for (const r of rows) expect(r).toMatchObject({ status: 'finalized', cohortSize: 10, finalizedAt: ROLLOVER_AT }); + }); + + it('puts everyone in a fresh cohort of the new week in the division they moved to', async () => { + const ids = await goldCohort(); + await runWeeklyRollover(WEEK, { store, now: ROLLOVER_AT, notify: vi.fn() }); + + const next = await Promise.all(ids.map(id => row(id, NEXT))); + expect(next.map(r => r!.division)).toEqual([ + 'silver', 'silver', 'gold', 'gold', 'gold', 'gold', 'gold', 'gold', 'platinum', 'platinum', + ]); + for (const r of next) expect(r).toMatchObject({ status: 'active', points: 0, rank: null, outcome: null }); + expect(new Set(next.map(r => r!.joinedAt.toISOString()))).toEqual(new Set(['2026-11-22T00:00:00.000Z'])); + // The Redis boards for the new week exist with everybody at 0, and the old week is set to expire. + expect(store.score(cohortKey(NEXT, 'gold', 'c1'), ids[2])).toBe(0); + expect(store.score(cohortKey(NEXT, 'platinum', 'c1'), ids[9])).toBe(0); + expect(store.score(cohortKey(NEXT, 'silver', 'c1'), ids[0])).toBe(0); + expect(store.ttls.get(cohortKey(WEEK, 'gold', 'c1'))).toBeGreaterThan(0); + }); + + it('notifies each finalized user once with league.week.finalized data', async () => { + const ids = await goldCohort(); + const notify = vi.fn<(userId: string, payload: WeekFinalizedPayload) => Promise>().mockResolvedValue(undefined); + await runWeeklyRollover(WEEK, { store, now: ROLLOVER_AT, notify }); + + expect(notify).toHaveBeenCalledTimes(10); + expect(notify).toHaveBeenCalledWith(ids[9], { + weekKey: WEEK, division: 'gold', rank: 1, points: 100, cohortSize: 10, outcome: 'promoted', nextDivision: 'platinum', + }); + }); + + it('a failing notification does not fail the rollover', async () => { + await goldCohort(); + const notify = vi.fn().mockRejectedValue(new Error('sse down')); + await expect(runWeeklyRollover(WEEK, { store, now: ROLLOVER_AT, notify })).resolves.toMatchObject({ finalized: 10 }); + }); + + it('running it again for the same week is a no-op: same rows, no double promotion, no new notifications', async () => { + await goldCohort(); + const notify = vi.fn().mockResolvedValue(undefined); + await runWeeklyRollover(WEEK, { store, now: ROLLOVER_AT, notify }); + const weekRows = await snapshot(WEEK); + const nextRows = await snapshot(NEXT); + const redisBefore = JSON.stringify([...store.sets].map(([k, v]) => [k, [...v]])); + + const again = await runWeeklyRollover(WEEK, { store, now: new Date('2026-11-22T00:07:00Z'), notify }); + const thrice = await runWeeklyRollover(WEEK, { store, now: new Date('2026-11-22T01:00:00Z'), notify }); + + expect(again).toMatchObject({ finalized: 0, promoted: 0, demoted: 0, assigned: 0 }); + expect(thrice).toMatchObject({ finalized: 0, assigned: 0 }); + expect(await snapshot(WEEK)).toEqual(weekRows); + expect(await snapshot(NEXT)).toEqual(nextRows); + expect(JSON.stringify([...store.sets].map(([k, v]) => [k, [...v]]))).toBe(redisBefore); + expect(notify).toHaveBeenCalledTimes(10); + // A promoted user is exactly one division up, not two. + expect((await LeagueStanding.find({ weekKey: NEXT, division: 'platinum' })).length).toBe(2); + expect((await LeagueStanding.find({ weekKey: NEXT, division: 'diamond' })).length).toBe(0); + }); + + it('does nothing when the week has no participants', async () => { + const result = await runWeeklyRollover(WEEK, { store, now: ROLLOVER_AT, notify: vi.fn() }); + expect(result).toMatchObject({ finalized: 0, promoted: 0, demoted: 0, assigned: 0 }); + expect(await LeagueStanding.countDocuments()).toBe(0); + }); + + it('repairs a run that stopped after finalizing: finishes the new week without re-ranking or re-notifying', async () => { + await goldCohort(); + const notify = vi.fn().mockResolvedValue(undefined); + await runWeeklyRollover(WEEK, { store, now: ROLLOVER_AT, notify }); + const weekRows = await snapshot(WEEK); + const nextRows = await snapshot(NEXT); + + // Simulate a crash after phase 1: the new week and its Redis boards never got written. + await LeagueStanding.deleteMany({ weekKey: NEXT }); + store.flush(); + const repaired = await runWeeklyRollover(WEEK, { store, now: ROLLOVER_AT, notify }); + + expect(repaired).toMatchObject({ finalized: 0, promoted: 0, demoted: 0, assigned: 10 }); + expect(await snapshot(WEEK)).toEqual(weekRows); + expect(await snapshot(NEXT)).toEqual(nextRows); + expect(notify).toHaveBeenCalledTimes(10); + }); + + it('ranks a half-finalized cohort the same way, finalizing only the remaining rows', async () => { + const ids = await goldCohort(); + // An earlier run finalized the current leader before dying. + await LeagueStanding.updateOne( + { weekKey: WEEK, userId: new Types.ObjectId(ids[9]) }, + { $set: { status: 'finalized', points: 100, rank: 1, cohortSize: 10, outcome: 'promoted', nextDivision: 'platinum', finalizedAt: ROLLOVER_AT } }, + ); + const result = await runWeeklyRollover(WEEK, { store, now: ROLLOVER_AT, notify: vi.fn() }); + + expect(result).toMatchObject({ finalized: 9, promoted: 1, demoted: 2 }); + expect(await row(ids[8], WEEK)).toMatchObject({ rank: 2, outcome: 'promoted' }); + expect(await row(ids[0], WEEK)).toMatchObject({ rank: 10, outcome: 'demoted' }); + }); + + it('does not carry users who opted out into the next week, but keeps their final record', async () => { + const ids = await goldCohort(); + await UserSettings.updateOne({ userId: new Types.ObjectId(ids[9]) }, { $set: { 'leagues.participate': false } }); + await runWeeklyRollover(WEEK, { store, now: ROLLOVER_AT, notify: vi.fn() }); + + expect(await row(ids[9], WEEK)).toMatchObject({ status: 'finalized', rank: 1, outcome: 'promoted' }); + expect(await row(ids[9], NEXT)).toBeNull(); + expect(await LeagueStanding.countDocuments({ weekKey: NEXT })).toBe(9); + }); + + it('builds the new week in cohorts of ~30 and merges a leftover under 10 into the previous cohort', async () => { + // Gold cohorts of 30, 20 and 10 this week: 18 + 12 + 6 = 36 users stay in gold, which is one + // cohort of 30 plus a leftover of 6, so the leftover is merged instead of standing alone. + const sizes = { c1: 30, c2: 20, c3: 10 }; + const ids = await makeUsers(60); + let next = 0; + for (const [cohortId, size] of Object.entries(sizes)) { + await LeagueStanding.insertMany(ids.slice(next, next + size).map(id => ({ + weekKey: WEEK, userId: new Types.ObjectId(id), division: 'gold', cohortId, status: 'active', + joinedAt: new Date('2026-11-15T00:00:00Z'), + }))); + next += size; + } + await runWeeklyRollover(WEEK, { store, now: ROLLOVER_AT, notify: vi.fn() }); + + const grouped = await LeagueStanding.aggregate([ + { $match: { weekKey: NEXT } }, + { $group: { _id: { d: '$division', c: '$cohortId' }, n: { $sum: 1 } } }, + ]); + const bySize = Object.fromEntries(grouped.map(g => [`${g._id.d}/${g._id.c}`, g.n])); + expect(bySize).toEqual({ 'gold/c1': 36, 'platinum/c1': 12, 'silver/c1': 12 }); + }); + + it('finalizes cohorts in several divisions in one run', async () => { + const silver = await makeUsers(10); + const master = await makeUsers(10); + await startIn(silver, 'silver'); + await startIn(master, 'master'); + await joinAll([...silver, ...master]); + for (const [i, id] of [...silver, ...master].entries()) await award(id, i + 1); + await runWeeklyRollover(WEEK, { store, now: ROLLOVER_AT, notify: vi.fn() }); + + expect(await row(silver[9], NEXT)).toMatchObject({ division: 'gold' }); + expect(await row(silver[0], NEXT)).toMatchObject({ division: 'bronze' }); + expect(await row(master[9], NEXT)).toMatchObject({ division: 'grandmaster' }); + expect(await row(master[0], NEXT)).toMatchObject({ division: 'diamond' }); + }); + + it('the repeatable job finalizes the week before the one it runs in, even when it runs late', () => { + expect(weekToFinalize(new Date('2026-11-22T00:00:01Z'))).toBe(WEEK); + expect(weekToFinalize(new Date('2026-11-23T09:30:00Z'))).toBe(WEEK); // worker was down at midnight + expect(weekToFinalize(new Date('2026-11-22T00:00:01Z'), '2026-11-08')).toBe('2026-11-08'); + expect(() => weekToFinalize(new Date(), '2026-11-09')).toThrow(/Invalid league week key/); + }); +}); + +describe('rebuilding from the XpTransaction ledger after Redis is flushed', () => { + async function ledger(userId: string, xp: number, createdAt: Date) { + await XpTransaction.create({ + userId: new Types.ObjectId(userId), sourceType: 'dsa_accepted', sourceId: `ledger-${++counter}`, + xpAwarded: xp, previousTotalXp: 0, newTotalXp: xp, levelBefore: 1, levelAfter: 1, createdAt, + }); + } + + it('restores every cohort score from the ledger, counting only this week and only after the user joined', async () => { + const [a, b, c] = await makeUsers(3); + await joinAll([a, b], new Date('2026-11-15T08:00:00Z')); + await joinAll([c], new Date('2026-11-19T00:00:00Z')); + + await ledger(a, 10, new Date('2026-11-16T10:00:00Z')); + await ledger(a, 5, new Date('2026-11-20T10:00:00Z')); + await ledger(b, 50, new Date('2026-11-14T23:00:00Z')); // previous week + await ledger(b, 7, new Date('2026-11-22T00:00:00Z')); // next week + await ledger(c, 30, new Date('2026-11-17T10:00:00Z')); // before c joined + await ledger(c, 9, new Date('2026-11-20T10:00:00Z')); + + store.flush(); + expect(await rebuildWeekFromLedger(WEEK, store)).toBe(1); + + const key = cohortKey(WEEK, 'bronze', 'c1'); + expect(store.score(key, a)).toBe(15); + expect(store.score(key, b)).toBe(0); + expect(store.score(key, c)).toBe(9); + }); + + it('standings reads rebuild a missing cohort on demand', async () => { + const [a, b] = await makeUsers(2); + await joinAll([a, b], new Date('2026-11-15T00:00:00Z')); + await ledger(a, 40, new Date('2026-11-16T10:00:00Z')); + await ledger(b, 15, new Date('2026-11-17T10:00:00Z')); + store.flush(); + + const view = await getCurrentStandings(a, store, MID_WEEK); + expect(view.standings.map(s => [s.userId, s.points])).toEqual([[a, 40], [b, 15]]); + expect(view.me).toEqual({ rank: 1, points: 40 }); + }); + + it('a rollover run after a flush ranks from the ledger instead of treating everybody as 0', async () => { + const ids = await makeUsers(10); + await startIn(ids, 'gold'); + await joinAll(ids, new Date('2026-11-15T00:00:00Z')); + for (const [i, id] of ids.entries()) await ledger(id, (i + 1) * 10, new Date('2026-11-17T10:00:00Z')); + store.flush(); + + await runWeeklyRollover(WEEK, { store, now: ROLLOVER_AT, notify: vi.fn() }); + expect(await row(ids[9], WEEK)).toMatchObject({ rank: 1, points: 100, outcome: 'promoted' }); + expect(await row(ids[0], WEEK)).toMatchObject({ rank: 10, points: 10, outcome: 'demoted' }); + }); +}); + +describe('current standings view', () => { + it('tells a non-participant to opt in and still reports the countdown', async () => { + const [userId] = await makeUsers(1, false); + const view = await getCurrentStandings(userId, store, MID_WEEK); + expect(view).toMatchObject({ + participating: false, weekKey: WEEK, standings: [], me: null, + weekStartsAt: '2026-11-15T00:00:00.000Z', resetsAt: '2026-11-22T00:00:00.000Z', + }); + expect(view.secondsUntilReset).toBe(Math.ceil((Date.parse('2026-11-22T00:00:00Z') - MID_WEEK.getTime()) / 1000)); + }); + + it('lists the cohort best first with rank, username, avatar and points', async () => { + const [a, b, c] = await makeUsers(3); + await User.insertMany([ + { _id: new Types.ObjectId(a), clerkId: 'c-a', email: 'a@example.com', username: 'alice', displayName: 'Alice', avatarUrl: 'https://img.example/a.png' }, + { _id: new Types.ObjectId(b), clerkId: 'c-b', email: 'b@example.com', username: 'bob', displayName: 'Bob', avatarUrl: null }, + { _id: new Types.ObjectId(c), clerkId: 'c-c', email: 'c@example.com', username: 'carol', displayName: 'Carol', avatarUrl: null }, + ]); + await joinAll([a, b, c]); + await award(a, 20); + await award(b, 70); + await award(c, 45); + + const view = await getCurrentStandings(a, store, MID_WEEK); + expect(view).toMatchObject({ participating: true, division: 'bronze', cohortId: 'c1', cohortSize: 3, promotionSlots: 0, demotionSlots: 0 }); + expect(view.me).toEqual({ rank: 3, points: 20 }); + expect(view.standings).toEqual([ + { rank: 1, userId: b, username: 'bob', displayName: 'Bob', avatarUrl: null, points: 70, isMe: false }, + { rank: 2, userId: c, username: 'carol', displayName: 'Carol', avatarUrl: null, points: 45, isMe: false }, + { rank: 3, userId: a, username: 'alice', displayName: 'Alice', avatarUrl: 'https://img.example/a.png', points: 20, isMe: true }, + ]); + }); + + it('only shows members of the caller\'s own cohort', async () => { + const ids = await makeUsers(31); + await joinAll(ids); + const view = await getCurrentStandings(ids[30], store, MID_WEEK); + expect(view.cohortId).toBe('c2'); + expect(view.standings.map(s => s.userId)).toEqual([ids[30]]); + }); + + it('places a participant who has no row yet and reports the 20% zones of a full cohort', async () => { + const ids = await makeUsers(30); + await joinAll(ids.slice(0, 29)); + const view = await getCurrentStandings(ids[29], store, MID_WEEK); + expect(view).toMatchObject({ cohortSize: 30, promotionSlots: 6, demotionSlots: 6 }); + }); +}); diff --git a/backend/src/__tests__/modules/leagues/scoreStore.test.ts b/backend/src/__tests__/modules/leagues/scoreStore.test.ts new file mode 100644 index 00000000..a4f302c1 --- /dev/null +++ b/backend/src/__tests__/modules/leagues/scoreStore.test.ts @@ -0,0 +1,101 @@ +import { describe, expect, it, vi } from 'vitest'; +import { createRedisScoreStore } from '../../../modules/leagues/scoreStore.js'; +import { FakeScoreStore } from './fakeScoreStore.js'; + +// The Redis adapter is exercised against a stub client that records commands. No Redis server is involved. +function stubClient() { + const pipeline = { del: vi.fn().mockReturnThis(), zadd: vi.fn().mockReturnThis(), exec: vi.fn().mockResolvedValue([]) }; + return { + pipeline, + client: { + eval: vi.fn(), + zadd: vi.fn().mockResolvedValue(1), + zrem: vi.fn().mockResolvedValue(1), + zrevrange: vi.fn(), + exists: vi.fn(), + expire: vi.fn().mockResolvedValue(1), + multi: vi.fn().mockReturnValue(pipeline), + }, + }; +} + +describe('createRedisScoreStore', () => { + it('increments through one atomic script and returns the new score', async () => { + const { client } = stubClient(); + client.eval.mockResolvedValue('75'); + const store = createRedisScoreStore(client as never); + + const score = await store.incrementOnce('league:2026-11-15:gold:c1', 'u1', 25, { setKey: 'league:2026-11-15:applied', id: 'u1|dsa|p1' }); + + expect(score).toBe(75); + const args = client.eval.mock.calls[0]; + expect(args[0]).toContain('ZINCRBY'); + expect(args[0]).toContain('SADD'); + expect(args.slice(1, 7)).toEqual([2, 'league:2026-11-15:gold:c1', 'league:2026-11-15:applied', '25', 'u1|dsa|p1', expect.any(String)]); + expect(args[7]).toBe('u1'); + }); + + it('reports an already applied award as null', async () => { + const { client } = stubClient(); + client.eval.mockResolvedValue(null); + const store = createRedisScoreStore(client as never); + expect(await store.incrementOnce('k', 'u1', 5, { setKey: 's', id: 'i' })).toBeNull(); + }); + + it('reads ZREVRANGE WITHSCORES into entries', async () => { + const { client } = stubClient(); + client.zrevrange.mockResolvedValue(['u2', '90', 'u1', '40']); + const store = createRedisScoreStore(client as never); + expect(await store.ranked('k', 0, -1)).toEqual([{ member: 'u2', score: 90 }, { member: 'u1', score: 40 }]); + expect(client.zrevrange).toHaveBeenCalledWith('k', 0, -1, 'WITHSCORES'); + }); + + it('seeds with ZADD NX so existing scores are untouched', async () => { + const { client } = stubClient(); + const store = createRedisScoreStore(client as never); + await store.seed('k', ['a', 'b']); + expect(client.zadd).toHaveBeenCalledWith('k', 'NX', 0, 'a', 0, 'b'); + await store.seed('k', []); + expect(client.zadd).toHaveBeenCalledTimes(1); + }); + + it('replaces a set in one transaction', async () => { + const { client, pipeline } = stubClient(); + const store = createRedisScoreStore(client as never); + await store.replace('k', [{ member: 'a', score: 3 }, { member: 'b', score: 0 }]); + expect(pipeline.del).toHaveBeenCalledWith('k'); + expect(pipeline.zadd).toHaveBeenCalledWith('k', 3, 'a', 0, 'b'); + expect(pipeline.exec).toHaveBeenCalledOnce(); + }); + + it('maps exists, remove and expire to their Redis commands', async () => { + const { client } = stubClient(); + client.exists.mockResolvedValueOnce(1).mockResolvedValueOnce(0); + const store = createRedisScoreStore(client as never); + expect(await store.exists('k')).toBe(true); + expect(await store.exists('k')).toBe(false); + await store.remove('k', 'a'); + await store.expire('k', 60); + expect(client.zrem).toHaveBeenCalledWith('k', 'a'); + expect(client.expire).toHaveBeenCalledWith('k', 60); + }); +}); + +describe('FakeScoreStore (test double used by the league tests)', () => { + it('orders like ZREVRANGE: score descending, ties by member descending', async () => { + const store = new FakeScoreStore(); + await store.seed('k', ['a', 'b', 'c']); + await store.incrementOnce('k', 'a', 10, { setKey: 's', id: '1' }); + expect(await store.ranked('k', 0, -1)).toEqual([ + { member: 'a', score: 10 }, { member: 'c', score: 0 }, { member: 'b', score: 0 }, + ]); + expect(await store.ranked('k', 0, 0)).toEqual([{ member: 'a', score: 10 }]); + }); + + it('applies a dedupe id only once', async () => { + const store = new FakeScoreStore(); + expect(await store.incrementOnce('k', 'a', 5, { setKey: 's', id: 'x' })).toBe(5); + expect(await store.incrementOnce('k', 'a', 5, { setKey: 's', id: 'x' })).toBeNull(); + expect(store.score('k', 'a')).toBe(5); + }); +}); diff --git a/backend/src/__tests__/modules/leagues/weeks.test.ts b/backend/src/__tests__/modules/leagues/weeks.test.ts new file mode 100644 index 00000000..d9fc77fd --- /dev/null +++ b/backend/src/__tests__/modules/leagues/weeks.test.ts @@ -0,0 +1,39 @@ +import { describe, expect, it } from 'vitest'; +import { isValidWeekKey, nextWeekKey, previousWeekKey, secondsUntilReset, weekKeyFor, weekRange } from '../../../modules/leagues/weeks.js'; + +describe('league weeks (Sunday 00:00 UTC)', () => { + it('starts a new week exactly at Sunday 00:00 UTC', () => { + expect(weekKeyFor(new Date('2026-11-14T23:59:59.999Z'))).toBe('2026-11-08'); // Saturday + expect(weekKeyFor(new Date('2026-11-15T00:00:00.000Z'))).toBe('2026-11-15'); // Sunday + expect(weekKeyFor(new Date('2026-11-18T10:00:00Z'))).toBe('2026-11-15'); + }); + + it('does not depend on the server time zone: a late Saturday offset time is still the old week', () => { + expect(weekKeyFor(new Date('2026-11-14T20:00:00-05:00'))).toBe('2026-11-15'); + expect(weekKeyFor(new Date('2026-11-15T03:00:00+05:30'))).toBe('2026-11-08'); + }); + + it('gives a half-open range of 7 days', () => { + const { start, end } = weekRange('2026-11-15'); + expect(start.toISOString()).toBe('2026-11-15T00:00:00.000Z'); + expect(end.toISOString()).toBe('2026-11-22T00:00:00.000Z'); + }); + + it('walks across month and year boundaries', () => { + expect(nextWeekKey('2026-12-27')).toBe('2027-01-03'); + expect(previousWeekKey('2027-01-03')).toBe('2026-12-27'); + }); + + it('validates week keys', () => { + expect(isValidWeekKey('2026-11-15')).toBe(true); + expect(isValidWeekKey('2026-11-16')).toBe(false); // a Monday + expect(isValidWeekKey('2026-02-30')).toBe(false); + expect(isValidWeekKey('2026-W46')).toBe(false); + expect(() => weekRange('2026-11-16')).toThrow(/Invalid league week key/); + }); + + it('counts down to the next reset', () => { + expect(secondsUntilReset(new Date('2026-11-21T23:59:00Z'))).toBe(60); + expect(secondsUntilReset(new Date('2026-11-15T00:00:00Z'))).toBe(7 * 86400); + }); +}); diff --git a/backend/src/__tests__/modules/leagues/xp-league-hook.test.ts b/backend/src/__tests__/modules/leagues/xp-league-hook.test.ts new file mode 100644 index 00000000..a124401b --- /dev/null +++ b/backend/src/__tests__/modules/leagues/xp-league-hook.test.ts @@ -0,0 +1,45 @@ +// The XP processor must hand every committed, positive award to the league score queue and nothing else. +import { beforeEach, describe, expect, it, vi } from 'vitest'; +import { Types } from 'mongoose'; + +const enqueue = vi.hoisted(() => vi.fn()); +vi.mock('../../../modules/leagues/workers/leagueScore.worker.js', () => ({ enqueueLeagueScore: enqueue })); + +import { processXpEvent } from '../../../modules/xp/processor.js'; + +const userId = () => new Types.ObjectId().toString(); + +beforeEach(() => { enqueue.mockReset().mockResolvedValue(undefined); }); + +describe('XP processor -> league score queue', () => { + it('enqueues the ledger-backed amount once, and not again for a duplicate event', async () => { + const id = userId(); + const first = await processXpEvent({ userId: id, sourceType: 'dsa_accepted', sourceId: 'sub-1', difficulty: 'hard' }); + await processXpEvent({ userId: id, sourceType: 'dsa_accepted', sourceId: 'sub-1', difficulty: 'hard' }); + + expect(first.awarded).toBe(true); + expect(enqueue).toHaveBeenCalledTimes(1); + expect(enqueue).toHaveBeenCalledWith({ + userId: id, sourceType: 'dsa_accepted', sourceId: 'sub-1', xpAwarded: first.xpAwarded, + occurredAt: expect.stringMatching(/^\d{4}-\d{2}-\d{2}T/), requestId: undefined, + }); + }); + + it('does not enqueue an award worth 0 XP', async () => { + const result = await processXpEvent({ userId: userId(), sourceType: 'sync_completed', sourceId: 'sync-0', metadata: { deltaSolved: 0 } }); + expect(result.xpAwarded).toBe(0); + expect(enqueue).not.toHaveBeenCalled(); + }); + + it('does not enqueue a focus session that does not qualify (no completed session means 0 XP)', async () => { + const result = await processXpEvent({ userId: userId(), sourceType: 'focus_session', sourceId: `focus_${new Types.ObjectId()}` }); + expect(result.awarded).toBe(false); + expect(enqueue).not.toHaveBeenCalled(); + }); + + it('a failing enqueue never fails the XP award', async () => { + enqueue.mockRejectedValue(new Error('redis down')); + const result = await processXpEvent({ userId: userId(), sourceType: 'dsa_accepted', sourceId: 'sub-2', difficulty: 'easy' }); + expect(result.awarded).toBe(true); + }); +}); diff --git a/backend/src/db/migrations/0012-leagues.ts b/backend/src/db/migrations/0012-leagues.ts new file mode 100644 index 00000000..e26412a5 --- /dev/null +++ b/backend/src/db/migrations/0012-leagues.ts @@ -0,0 +1,32 @@ +import type { mongo } from 'mongoose'; +import { LEAGUE_STANDING_INDEXES } from '../models/leagueStandingIndexes.js'; + +const standingsCollection = 'leaguestandings'; +const settingsCollection = 'usersettings'; + +// Weekly leagues are opt-in. Mongoose applies the default to new documents only, so write the +// explicit `false` onto existing settings documents. +export async function migrateLeagues(db: mongo.Db): Promise { + const standings = db.collection(standingsCollection); + for (const { key, options } of LEAGUE_STANDING_INDEXES) { + await standings.createIndex(key, options); + } + await db + .collection(settingsCollection) + .updateMany({ 'leagues.participate': { $exists: false } }, { $set: { 'leagues.participate': false } }); +} + +export async function rollbackLeagues(db: mongo.Db): Promise { + const standings = db.collection(standingsCollection); + for (const { options } of LEAGUE_STANDING_INDEXES) { + try { + await standings.dropIndex(options.name); + } catch (error) { + // 26 = namespace not found, 27 = index not found: already rolled back. + const code = (error as { code?: number }).code; + if (code !== 26 && code !== 27) throw error; + } + } + // Only the opt-in flag is removed. LeagueStanding rows are history and are kept. + await db.collection(settingsCollection).updateMany({ leagues: { $exists: true } }, { $unset: { leagues: '' } }); +} diff --git a/backend/src/db/migrations/run-leagues.ts b/backend/src/db/migrations/run-leagues.ts new file mode 100644 index 00000000..8471a861 --- /dev/null +++ b/backend/src/db/migrations/run-leagues.ts @@ -0,0 +1,17 @@ +import mongoose from 'mongoose'; +import { migrateLeagues, rollbackLeagues } from './0012-leagues.js'; + +const uri = process.env.MONGODB_URI; +if (!uri) throw new Error('Set MONGODB_URI explicitly before running this migration'); + +const [direction = 'up', ...extra] = process.argv.slice(2); +if (extra.length || (direction !== 'up' && direction !== 'down')) throw new Error('Expected up or down'); + +try { + await mongoose.connect(uri, { autoIndex: false }); + const db = mongoose.connection.db!; + await (direction === 'up' ? migrateLeagues(db) : rollbackLeagues(db)); + console.log(`Leagues migration ${direction} complete`); +} finally { + await mongoose.disconnect(); +} diff --git a/backend/src/db/models/index.ts b/backend/src/db/models/index.ts index 8a853057..8e085337 100644 --- a/backend/src/db/models/index.ts +++ b/backend/src/db/models/index.ts @@ -30,6 +30,7 @@ export { Mission, type IMission } from './mission.model.js'; export { SyncJob, type ISyncJob } from './syncJob.model.js'; export { UserXp, type IUserXp } from './userXp.model.js'; export { XpTransaction, type IXpTransaction, type XpSourceType } from './xpTransaction.model.js'; +export { LeagueStanding, LEAGUE_DIVISIONS, type ILeagueStanding, type LeagueDivision, type LeagueOutcome, type LeagueStandingStatus } from './leagueStanding.model.js'; export { UserStreakLog, type IUserStreakLog, type StreakType } from './userStreakLog.model.js'; export { UserAnalytics, type IUserAnalytics } from './userAnalytics.model.js'; export { ProcessedEvent, type IProcessedEvent } from './processedEvent.model.js'; diff --git a/backend/src/db/models/leagueStanding.model.ts b/backend/src/db/models/leagueStanding.model.ts new file mode 100644 index 00000000..94d6ee7d --- /dev/null +++ b/backend/src/db/models/leagueStanding.model.ts @@ -0,0 +1,66 @@ +// src/db/models/leagueStanding.model.ts — Weekly league membership and final standings. +// A row is created as 'active' when a user is placed in a cohort for a week and is +// flipped to 'finalized' (rank, points, outcome) by the Sunday rollover. The live +// score for an active week lives in a Redis sorted set; this collection is the +// durable record and the source of truth for who is in which cohort. + +import mongoose, { Schema, type Document, type Types } from 'mongoose'; +import { LEAGUE_STANDING_INDEXES } from './leagueStandingIndexes.js'; + +export const LEAGUE_DIVISIONS = [ + 'bronze', + 'silver', + 'gold', + 'platinum', + 'diamond', + 'master', + 'grandmaster', +] as const; +export type LeagueDivision = (typeof LEAGUE_DIVISIONS)[number]; + +export type LeagueStandingStatus = 'active' | 'finalized'; +export type LeagueOutcome = 'promoted' | 'demoted' | 'stayed'; + +export interface ILeagueStanding extends Document { + /** UTC date (YYYY-MM-DD) of the Sunday that starts the week. */ + weekKey: string; + userId: Types.ObjectId; + division: LeagueDivision; + cohortId: string; + status: LeagueStandingStatus; + /** Only XP awarded at or after this instant counts toward the week. */ + joinedAt: Date; + /** Final points; 0 until the week is finalized. */ + points: number; + rank: number | null; + cohortSize: number | null; + outcome: LeagueOutcome | null; + nextDivision: LeagueDivision | null; + finalizedAt: Date | null; + createdAt: Date; + updatedAt: Date; +} + +const leagueStandingSchema = new Schema( + { + weekKey: { type: String, required: true, match: /^\d{4}-\d{2}-\d{2}$/ }, + userId: { type: Schema.Types.ObjectId, ref: 'User', required: true }, + division: { type: String, required: true, enum: LEAGUE_DIVISIONS }, + cohortId: { type: String, required: true }, + status: { type: String, required: true, enum: ['active', 'finalized'], default: 'active' }, + joinedAt: { type: Date, required: true }, + points: { type: Number, default: 0, min: 0 }, + rank: { type: Number, default: null, min: 1 }, + cohortSize: { type: Number, default: null, min: 1 }, + outcome: { type: String, enum: ['promoted', 'demoted', 'stayed', null], default: null }, + nextDivision: { type: String, enum: [...LEAGUE_DIVISIONS, null], default: null }, + finalizedAt: { type: Date, default: null }, + }, + { timestamps: true }, +); + +for (const { key, options } of LEAGUE_STANDING_INDEXES) { + leagueStandingSchema.index(key, options); +} + +export const LeagueStanding = mongoose.model('LeagueStanding', leagueStandingSchema); diff --git a/backend/src/db/models/leagueStandingIndexes.ts b/backend/src/db/models/leagueStandingIndexes.ts new file mode 100644 index 00000000..fce31069 --- /dev/null +++ b/backend/src/db/models/leagueStandingIndexes.ts @@ -0,0 +1,24 @@ +// Index definitions shared by the LeagueStanding model and the leagues migration, +// so the schema and the migrated collection cannot drift apart. +export interface LeagueIndexSpec { + key: Record; + options: { name: string; unique?: boolean }; +} + +export const LEAGUE_STANDING_INDEXES: LeagueIndexSpec[] = [ + { + // One row per user per week: makes cohort assignment and rollover idempotent. + key: { weekKey: 1, userId: 1 }, + options: { name: 'uq_leaguestandings_week_user', unique: true }, + }, + { + // Cohort lookups: size counts for late joiners, rollover, Redis rebuild. + key: { weekKey: 1, division: 1, cohortId: 1, status: 1 }, + options: { name: 'idx_leaguestandings_cohort' }, + }, + { + // A user's league history, newest week first. + key: { userId: 1, weekKey: -1 }, + options: { name: 'idx_leaguestandings_user_history' }, + }, +]; diff --git a/backend/src/db/models/userSettings.model.ts b/backend/src/db/models/userSettings.model.ts index bb68690b..9105c048 100644 --- a/backend/src/db/models/userSettings.model.ts +++ b/backend/src/db/models/userSettings.model.ts @@ -42,6 +42,9 @@ export interface IUserSettings extends Document { showGithub: boolean; showTimeline: boolean; }; + leagues: { + participate: boolean; + }; createdAt: Date; updatedAt: Date; } @@ -93,6 +96,10 @@ const userSettingsSchema = new Schema( showGithub: { type: Boolean, default: true }, showTimeline: { type: Boolean, default: true }, }, + // Weekly leagues are opt-in: standings show username and avatar to other participants. + leagues: { + participate: { type: Boolean, default: false }, + }, }, { timestamps: true, diff --git a/backend/src/modules/leagues/cohorts.ts b/backend/src/modules/leagues/cohorts.ts new file mode 100644 index 00000000..0ab87b86 --- /dev/null +++ b/backend/src/modules/leagues/cohorts.ts @@ -0,0 +1,65 @@ +// src/modules/leagues/cohorts.ts — Cohort partitioning for a league division (pure, no I/O). +import { createHash } from 'node:crypto'; +import { MIN_COHORT_SIZE, TARGET_COHORT_SIZE } from './leagues.constants.js'; + +export interface CohortSizing { + target?: number; + min?: number; +} + +export function cohortIdFor(index: number): string { + return `c${index + 1}`; +} + +/** + * Splits the users of one division into cohorts of `target` (default 30). The order is a + * shuffle seeded by `seed` (the week + division), so the same inputs always give the same + * cohorts and a rerun after a crash assigns everybody the same way. A leftover group smaller + * than `min` (default 10) is merged into the previous cohort instead of standing alone. + */ +export function partitionIntoCohorts(userIds: string[], seed: string, sizing: CohortSizing = {}): string[][] { + const target = sizing.target ?? TARGET_COHORT_SIZE; + const min = sizing.min ?? MIN_COHORT_SIZE; + const shuffled = [...new Set(userIds)] + .map(id => ({ id, order: createHash('sha1').update(`${seed}:${id}`).digest('hex') })) + .sort((a, b) => (a.order < b.order ? -1 : a.order > b.order ? 1 : 0)) + .map(entry => entry.id); + + const cohorts: string[][] = []; + for (let i = 0; i < shuffled.length; i += target) cohorts.push(shuffled.slice(i, i + target)); + + if (cohorts.length > 1 && cohorts[cohorts.length - 1].length < min) { + const tail = cohorts.pop()!; + cohorts[cohorts.length - 1].push(...tail); + } + return cohorts; +} + +export interface CohortAssignment { + userId: string; + cohortId: string; +} + +export function assignCohorts(userIds: string[], seed: string, sizing: CohortSizing = {}): CohortAssignment[] { + return partitionIntoCohorts(userIds, seed, sizing).flatMap((members, index) => + members.map(userId => ({ userId, cohortId: cohortIdFor(index) })), + ); +} + +/** + * Picks the cohort for a user who joins after the week started: the emptiest cohort that is + * still below the target size, otherwise a brand new one. Existing cohorts are never reshuffled + * mid-week because their scores already exist. + */ +export function pickCohortForLateJoiner(sizes: Map, sizing: CohortSizing = {}): string { + const target = sizing.target ?? TARGET_COHORT_SIZE; + let best: { id: string; size: number; index: number } | null = null; + let highestIndex = 0; + for (const [id, size] of sizes) { + const index = Number(id.slice(1)); + highestIndex = Math.max(highestIndex, index); + if (size >= target) continue; + if (!best || size < best.size || (size === best.size && index < best.index)) best = { id, size, index }; + } + return best ? best.id : cohortIdFor(highestIndex); +} diff --git a/backend/src/modules/leagues/index.ts b/backend/src/modules/leagues/index.ts new file mode 100644 index 00000000..e7026b83 --- /dev/null +++ b/backend/src/modules/leagues/index.ts @@ -0,0 +1,8 @@ +// src/modules/leagues/index.ts — Weekly Leagues module barrel +export * from './leagues.constants.js'; +export * from './weeks.js'; +export * from './cohorts.js'; +export * from './scoreStore.js'; +export * from './leagues.service.js'; +export * from './rollover.js'; +export * from './leagues.routes.js'; diff --git a/backend/src/modules/leagues/leagues.constants.ts b/backend/src/modules/leagues/leagues.constants.ts new file mode 100644 index 00000000..6d72871b --- /dev/null +++ b/backend/src/modules/leagues/leagues.constants.ts @@ -0,0 +1,37 @@ +// src/modules/leagues/leagues.constants.ts — Tunables and Redis key builders for weekly leagues. +import { LEAGUE_DIVISIONS, type LeagueDivision } from '../../db/models/leagueStanding.model.js'; + +/** Cohorts are filled up to this many participants. */ +export const TARGET_COHORT_SIZE = 30; +/** A leftover cohort smaller than this is merged into the previous one. */ +export const MIN_COHORT_SIZE = 10; +/** Percent of each cohort promoted (top) and demoted (bottom) at rollover. */ +export const PROMOTION_PERCENT = 20; +export const DEMOTION_PERCENT = 20; + +export const DEFAULT_DIVISION: LeagueDivision = 'bronze'; + +/** Finished weeks stay readable in Redis for this long, then expire on their own. */ +export const FINISHED_WEEK_TTL_SECONDS = 14 * 24 * 60 * 60; +/** Idempotency markers for score increments only need to outlive the week. */ +export const SCORE_DEDUPE_TTL_SECONDS = 21 * 24 * 60 * 60; + +export function nextDivision(division: LeagueDivision): LeagueDivision { + const index = LEAGUE_DIVISIONS.indexOf(division); + return LEAGUE_DIVISIONS[Math.min(index + 1, LEAGUE_DIVISIONS.length - 1)]; +} + +export function previousDivision(division: LeagueDivision): LeagueDivision { + const index = LEAGUE_DIVISIONS.indexOf(division); + return LEAGUE_DIVISIONS[Math.max(index - 1, 0)]; +} + +/** league:{weekKey}:{division}:{cohortId} */ +export function cohortKey(weekKey: string, division: LeagueDivision, cohortId: string): string { + return `league:${weekKey}:${division}:${cohortId}`; +} + +/** Set of already-applied XP awards for a week, so a replayed job never double counts. */ +export function dedupeSetKey(weekKey: string): string { + return `league:${weekKey}:applied`; +} diff --git a/backend/src/modules/leagues/leagues.routes.ts b/backend/src/modules/leagues/leagues.routes.ts new file mode 100644 index 00000000..401594b5 --- /dev/null +++ b/backend/src/modules/leagues/leagues.routes.ts @@ -0,0 +1,43 @@ +// src/modules/leagues/leagues.routes.ts — Weekly leagues API (mounted at /api/v1/leagues) +import { Router, type Response } from 'express'; +import { z } from 'zod'; +import { asyncHandler, authMiddleware } from '../../middleware/index.js'; +import type { AuthenticatedRequest } from '../../middleware/index.js'; +import { commonErrors, successResponse } from '../../shared/response.js'; +import { getCurrentStandings, setParticipation } from './leagues.service.js'; +import { getLeagueScoreStore } from './scoreStore.js'; + +const router = Router(); + +const participationSchema = z.object({ participate: z.boolean() }).strict(); + +// GET /api/v1/leagues/current — the caller's cohort standings for the running week (L-01) +router.get('/current', authMiddleware, asyncHandler(async (req: AuthenticatedRequest, res: Response) => { + const userId = req.user?.id; + if (!userId) return commonErrors.unauthorized(res); + + const view = await getCurrentStandings(userId, getLeagueScoreStore()); + successResponse(res, view, 'League standings retrieved successfully'); +})); + +// PUT /api/v1/leagues/participation — opt in or out of weekly leagues (default: out) +router.put('/participation', authMiddleware, asyncHandler(async (req: AuthenticatedRequest, res: Response) => { + const userId = req.user?.id; + if (!userId) return commonErrors.unauthorized(res); + + const parsed = participationSchema.safeParse(req.body); + if (!parsed.success) { + const details: Record = {}; + for (const issue of parsed.error.issues) { + const key = issue.path.join('.') || '_root'; + (details[key] ??= []).push(issue.message); + } + return commonErrors.validationError(res, details); + } + + const result = await setParticipation(userId, parsed.data.participate, new Date(), getLeagueScoreStore()); + successResponse(res, result, parsed.data.participate ? 'Joined weekly leagues' : 'Left weekly leagues'); +})); + +export const leaguesRoutes = router; +export default router; diff --git a/backend/src/modules/leagues/leagues.service.ts b/backend/src/modules/leagues/leagues.service.ts new file mode 100644 index 00000000..ba4615f4 --- /dev/null +++ b/backend/src/modules/leagues/leagues.service.ts @@ -0,0 +1,313 @@ +// src/modules/leagues/leagues.service.ts — Weekly league membership, live scoring and standings reads. +// +// Live scores are Redis sorted sets (see scoreStore.ts). MongoDB `LeagueStanding` rows say who +// is in which cohort, so a flushed Redis can always be rebuilt from those rows plus the +// `XpTransaction` ledger. + +import { Types } from 'mongoose'; +import { LeagueStanding, UserSettings, User, XpTransaction } from '../../db/models/index.js'; +import type { ILeagueStanding, LeagueDivision } from '../../db/models/index.js'; +import { logger } from '../../shared/logger.js'; +import { pickCohortForLateJoiner } from './cohorts.js'; +import { + DEFAULT_DIVISION, + DEMOTION_PERCENT, + PROMOTION_PERCENT, + cohortKey, + dedupeSetKey, +} from './leagues.constants.js'; +import type { LeagueScoreStore } from './scoreStore.js'; +import { secondsUntilReset, weekKeyFor, weekRange } from './weeks.js'; + +type StandingRow = Pick & { + userId: Types.ObjectId; +}; + +export interface XpAwardInput { + userId: string; + sourceType: string; + sourceId: string; + xpAwarded: number; + /** When the XP ledger row was written. Decides which week the points belong to. */ + occurredAt: Date; +} + +export type ScoreResult = + | { applied: true; weekKey: string; score: number } + | { applied: false; reason: 'no_xp' | 'not_participating' | 'week_closed' | 'before_join' | 'duplicate' }; + +export interface RankedMember { + userId: string; + points: number; +} + +export interface LeagueStandingsView { + participating: boolean; + weekKey: string; + weekStartsAt: string; + resetsAt: string; + secondsUntilReset: number; + division: LeagueDivision | null; + cohortId: string | null; + cohortSize: number; + promotionSlots: number; + demotionSlots: number; + me: { rank: number; points: number } | null; + standings: Array<{ + rank: number; + userId: string; + username: string | null; + displayName: string | null; + avatarUrl: string | null; + points: number; + isMe: boolean; + }>; +} + +/** Top and bottom slots for a cohort of `size` members (20% each, rounded down). */ +export function zoneSlots(size: number): { promotion: number; demotion: number } { + return { + promotion: Math.floor((size * PROMOTION_PERCENT) / 100), + demotion: Math.floor((size * DEMOTION_PERCENT) / 100), + }; +} + +function isDuplicateKey(error: unknown): boolean { + return (error as { code?: number })?.code === 11000; +} + +// ─── Membership ───────────────────────────────────────────────────────────── + +export async function isParticipating(userId: string): Promise { + return Boolean(await UserSettings.exists({ userId: new Types.ObjectId(userId), 'leagues.participate': true })); +} + +/** Division a user starts the week in: where their last finalized week sent them, else bronze. */ +async function divisionForNextWeek(userObjId: Types.ObjectId): Promise { + const last = await LeagueStanding.findOne({ userId: userObjId, status: 'finalized' }) + .sort({ weekKey: -1 }) + .select('nextDivision') + .lean(); + return last?.nextDivision ?? DEFAULT_DIVISION; +} + +/** + * Places the user in a cohort for the week containing `now`. Safe to call repeatedly: + * an existing row for the week is returned untouched (the unique week+user index + * settles concurrent calls). + */ +export async function joinCurrentWeek(userId: string, now: Date, store: LeagueScoreStore): Promise { + const userObjId = new Types.ObjectId(userId); + const weekKey = weekKeyFor(now); + + const existing = await LeagueStanding.findOne({ weekKey, userId: userObjId }).lean(); + if (existing) return existing; + + const division = await divisionForNextWeek(userObjId); + const counts = await LeagueStanding.aggregate<{ _id: string; n: number }>([ + { $match: { weekKey, division, status: 'active' } }, + { $group: { _id: '$cohortId', n: { $sum: 1 } } }, + ]); + const cohortId = pickCohortForLateJoiner(new Map(counts.map(c => [c._id, c.n]))); + + let row: StandingRow; + try { + const created = await LeagueStanding.create({ + weekKey, userId: userObjId, division, cohortId, status: 'active', joinedAt: now, + }); + row = created.toObject() as StandingRow; + } catch (error) { + if (!isDuplicateKey(error)) throw error; + return (await LeagueStanding.findOne({ weekKey, userId: userObjId }).lean())!; + } + await store.seed(cohortKey(weekKey, row.division, row.cohortId), [userId]); + return row; +} + +/** Opt in or out. Opting out removes the user from the live week; finished weeks stay as history. */ +export async function setParticipation( + userId: string, + participate: boolean, + now: Date, + store: LeagueScoreStore, +): Promise<{ participating: boolean }> { + const userObjId = new Types.ObjectId(userId); + await UserSettings.updateOne({ userId: userObjId }, { $set: { 'leagues.participate': participate } }, { upsert: true }); + + if (participate) { + await joinCurrentWeek(userId, now, store); + } else { + const weekKey = weekKeyFor(now); + const row = await LeagueStanding.findOneAndDelete({ weekKey, userId: userObjId, status: 'active' }).lean(); + if (row) await store.remove(cohortKey(weekKey, row.division, row.cohortId), userId); + } + return { participating: participate }; +} + +// ─── Scoring ──────────────────────────────────────────────────────────────── + +/** + * Adds a server-awarded XP amount to the user's cohort score. Only ledger-backed awards reach + * this point (the XP processor writes the ledger row and emits the job; focus sessions that + * do not qualify end up with 0 XP and never produce one), so there is nothing client + * controlled here. + */ +export async function recordXpAward(input: XpAwardInput, store: LeagueScoreStore, now = new Date()): Promise { + if (!Number.isSafeInteger(input.xpAwarded) || input.xpAwarded <= 0) return { applied: false, reason: 'no_xp' }; + + const userObjId = new Types.ObjectId(input.userId); + const weekKey = weekKeyFor(input.occurredAt); + + let row = await LeagueStanding.findOne({ weekKey, userId: userObjId }).lean(); + if (!row) { + // Opted in but not placed yet: only possible for the running week. + if (weekKey !== weekKeyFor(now) || !(await isParticipating(input.userId))) { + return { applied: false, reason: 'not_participating' }; + } + row = await joinCurrentWeek(input.userId, now, store); + } + if (row.status !== 'active') return { applied: false, reason: 'week_closed' }; + if (input.occurredAt < row.joinedAt) return { applied: false, reason: 'before_join' }; + + const score = await store.incrementOnce( + cohortKey(weekKey, row.division, row.cohortId), + input.userId, + input.xpAwarded, + { setKey: dedupeSetKey(weekKey), id: `${input.userId}|${input.sourceType}|${input.sourceId}` }, + ); + if (score === null) return { applied: false, reason: 'duplicate' }; + return { applied: true, weekKey, score }; +} + +// ─── Rebuild from the XP ledger ───────────────────────────────────────────── + +/** + * Recomputes one cohort's sorted set from `XpTransaction`. Each member only counts XP + * from their own join time onward, exactly like live scoring does. + */ +export async function rebuildCohortFromLedger( + weekKey: string, + division: LeagueDivision, + cohortId: string, + store: LeagueScoreStore, +): Promise { + const rows = await LeagueStanding.find({ weekKey, division, cohortId }) + .select('userId joinedAt') + .lean>(); + const key = cohortKey(weekKey, division, cohortId); + if (rows.length === 0) return; + + const { start, end } = weekRange(weekKey); + const totals = await XpTransaction.aggregate<{ _id: Types.ObjectId; points: number }>([ + { + $match: { + xpAwarded: { $gt: 0 }, + $or: rows.map(row => ({ + userId: row.userId, + createdAt: { $gte: row.joinedAt > start ? row.joinedAt : start, $lt: end }, + })), + }, + }, + { $group: { _id: '$userId', points: { $sum: '$xpAwarded' } } }, + ]); + const pointsByUser = new Map(totals.map(t => [t._id.toString(), t.points])); + await store.replace( + key, + rows.map(row => ({ member: row.userId.toString(), score: pointsByUser.get(row.userId.toString()) ?? 0 })), + ); + logger.info('[leagues] Rebuilt cohort standings from XP ledger', { + event: 'league_cohort_rebuilt', weekKey, division, cohortId, members: rows.length, + }); +} + +/** Rebuilds every active cohort of a week, e.g. after Redis was flushed. */ +export async function rebuildWeekFromLedger(weekKey: string, store: LeagueScoreStore): Promise { + const cohorts = await LeagueStanding.aggregate<{ _id: { division: LeagueDivision; cohortId: string } }>([ + { $match: { weekKey, status: 'active' } }, + { $group: { _id: { division: '$division', cohortId: '$cohortId' } } }, + ]); + for (const { _id } of cohorts) await rebuildCohortFromLedger(weekKey, _id.division, _id.cohortId, store); + return cohorts.length; +} + +// ─── Reads ────────────────────────────────────────────────────────────────── + +/** + * Current ranking of one cohort, highest score first, covering every member of the cohort. If the Redis set is gone it is rebuilt from the ledger first. Equal scores keep the + * order Redis gives them (reverse lexicographic by member id), which is stable between calls. + */ +export async function readCohortBoard( + weekKey: string, + division: LeagueDivision, + cohortId: string, + store: LeagueScoreStore, +): Promise { + const key = cohortKey(weekKey, division, cohortId); + if (!(await store.exists(key))) await rebuildCohortFromLedger(weekKey, division, cohortId, store); + + const members = await LeagueStanding.find({ weekKey, division, cohortId }) + .select('userId') + .lean>(); + const memberIds = new Set(members.map(m => m.userId.toString())); + + const board: RankedMember[] = (await store.ranked(key, 0, -1)) + .filter(entry => memberIds.has(entry.member)) + .map(entry => ({ userId: entry.member, points: entry.score })); + const seen = new Set(board.map(b => b.userId)); + const missing = [...memberIds].filter(id => !seen.has(id)).sort().reverse(); + for (const userId of missing) board.push({ userId, points: 0 }); + return board; +} + +export async function getCurrentStandings(userId: string, store: LeagueScoreStore, now = new Date()): Promise { + const weekKey = weekKeyFor(now); + const { start, end } = weekRange(weekKey); + const base = { + weekKey, + weekStartsAt: start.toISOString(), + resetsAt: end.toISOString(), + secondsUntilReset: secondsUntilReset(now), + }; + + if (!(await isParticipating(userId))) { + return { + ...base, participating: false, division: null, cohortId: null, cohortSize: 0, + promotionSlots: 0, demotionSlots: 0, me: null, standings: [], + }; + } + + const row = await joinCurrentWeek(userId, now, store); + const board = await readCohortBoard(weekKey, row.division, row.cohortId, store); + + const profiles = await User.find({ _id: { $in: board.map(b => new Types.ObjectId(b.userId)) } }) + .select('username displayName avatarUrl') + .lean>(); + const profileById = new Map(profiles.map(p => [p._id.toString(), p])); + + const standings = board.map((member, index) => { + const profile = profileById.get(member.userId); + return { + rank: index + 1, + userId: member.userId, + username: profile?.username ?? null, + displayName: profile?.displayName ?? null, + avatarUrl: profile?.avatarUrl ?? null, + points: member.points, + isMe: member.userId === userId, + }; + }); + const mine = standings.find(s => s.isMe); + const slots = zoneSlots(board.length); + + return { + ...base, + participating: true, + division: row.division, + cohortId: row.cohortId, + cohortSize: board.length, + promotionSlots: slots.promotion, + demotionSlots: slots.demotion, + me: mine ? { rank: mine.rank, points: mine.points } : null, + standings, + }; +} diff --git a/backend/src/modules/leagues/rollover.ts b/backend/src/modules/leagues/rollover.ts new file mode 100644 index 00000000..aa43541d --- /dev/null +++ b/backend/src/modules/leagues/rollover.ts @@ -0,0 +1,220 @@ +// src/modules/leagues/rollover.ts — Weekly league rollover (Sunday 00:00 UTC). +// +// For the week that just ended: read the final ranking of every cohort from Redis, write +// rank/points/outcome into the LeagueStanding rows, promote the top 20% and demote the bottom +// 20%, place everyone in fresh cohorts for the new week and notify them over SSE. +// +// Idempotency: every step is keyed on (weekKey, userId). Phase 1 only touches rows that are +// still 'active', phase 2 only inserts rows that do not exist yet ($setOnInsert) and phase 3 uses +// ZADD NX. Running the rollover again, or after a crash halfway, converges on the same result +// and never promotes or demotes anybody twice. + +import { Types } from 'mongoose'; +import { LeagueStanding, UserSettings } from '../../db/models/index.js'; +import type { LeagueDivision, LeagueOutcome } from '../../db/models/index.js'; +import { LEAGUE_DIVISIONS } from '../../db/models/index.js'; +import { eventBus } from '../../shared/sse/index.js'; +import { logger } from '../../shared/logger.js'; +import { assignCohorts } from './cohorts.js'; +import { FINISHED_WEEK_TTL_SECONDS, cohortKey, nextDivision, previousDivision } from './leagues.constants.js'; +import { readCohortBoard, zoneSlots, type RankedMember } from './leagues.service.js'; +import type { LeagueScoreStore } from './scoreStore.js'; +import { nextWeekKey, weekRange } from './weeks.js'; + +export interface FinalStanding { + userId: string; + rank: number; + points: number; + cohortSize: number; + outcome: LeagueOutcome; + nextDivision: LeagueDivision; +} + +export interface WeekFinalizedPayload { + weekKey: string; + division: LeagueDivision; + rank: number; + points: number; + cohortSize: number; + outcome: LeagueOutcome; + nextDivision: LeagueDivision; +} + +export interface RolloverResult { + weekKey: string; + nextWeekKey: string; + /** Rows moved from active to finalized by this run (0 when the week was already done). */ + finalized: number; + promoted: number; + demoted: number; + /** New-week rows inserted by this run. */ + assigned: number; +} + +export interface RolloverOptions { + store: LeagueScoreStore; + now?: Date; + /** Defaults to an SSE `league_week_finalized` event to the user. */ + notify?: (userId: string, payload: WeekFinalizedPayload) => Promise; +} + +const WRITE_BATCH = 500; + +/** + * Ranks a finished cohort and decides who moves. `board` must already be ordered best first. + * The top 20% (rounded down) move up one division, the bottom 20% move down one. Bronze + * cannot be demoted and Grandmaster cannot be promoted: those users stay. + */ +export function computeCohortOutcomes(division: LeagueDivision, board: RankedMember[]): FinalStanding[] { + const size = board.length; + const slots = zoneSlots(size); + const canPromote = division !== LEAGUE_DIVISIONS[LEAGUE_DIVISIONS.length - 1]; + const canDemote = division !== LEAGUE_DIVISIONS[0]; + + return board.map((member, index) => { + const rank = index + 1; + let outcome: LeagueOutcome = 'stayed'; + if (canPromote && rank <= slots.promotion) outcome = 'promoted'; + else if (canDemote && rank > size - slots.demotion) outcome = 'demoted'; + return { + userId: member.userId, + rank, + points: member.points, + cohortSize: size, + outcome, + nextDivision: + outcome === 'promoted' ? nextDivision(division) : outcome === 'demoted' ? previousDivision(division) : division, + }; + }); +} + +async function defaultNotify(userId: string, payload: WeekFinalizedPayload): Promise { + await eventBus.publishEnvelope(userId, 'league_week_finalized', { ...payload }); +} + +export async function runWeeklyRollover(weekKey: string, options: RolloverOptions): Promise { + const { store, now = new Date(), notify = defaultNotify } = options; + const upcomingWeekKey = nextWeekKey(weekKey); + const result: RolloverResult = { weekKey, nextWeekKey: upcomingWeekKey, finalized: 0, promoted: 0, demoted: 0, assigned: 0 }; + + // ── Phase 1: finalize each cohort that still has active rows ────────────── + const cohorts = await LeagueStanding.aggregate<{ _id: { division: LeagueDivision; cohortId: string } }>([ + { $match: { weekKey, status: 'active' } }, + { $group: { _id: { division: '$division', cohortId: '$cohortId' } } }, + { $sort: { '_id.division': 1, '_id.cohortId': 1 } }, + ]); + + const finalizedNow: Array = []; + for (const { _id: { division, cohortId } } of cohorts) { + // Rank the whole cohort, including rows a crashed earlier run already finalized, so ranks + // never depend on how far that run got. Only rows still active are written below. + const board = await readCohortBoard(weekKey, division, cohortId, store); + const stillActive = new Set( + (await LeagueStanding.find({ weekKey, division, cohortId, status: 'active' }) + .select('userId') + .lean>()).map(row => row.userId.toString()), + ); + const standings = computeCohortOutcomes(division, board).filter(s => stillActive.has(s.userId)); + const finalizedAt = now; + const writes = await LeagueStanding.bulkWrite( + standings.map(s => ({ + updateOne: { + // The status filter is what makes a second run a no-op for this row. + filter: { weekKey, userId: new Types.ObjectId(s.userId), status: 'active' as const }, + update: { + $set: { + status: 'finalized' as const, points: s.points, rank: s.rank, cohortSize: s.cohortSize, + outcome: s.outcome, nextDivision: s.nextDivision, finalizedAt, + }, + }, + }, + })), + ); + if (writes.modifiedCount > 0) { + result.finalized += writes.modifiedCount; + for (const s of standings) { + if (s.outcome === 'promoted') result.promoted++; + if (s.outcome === 'demoted') result.demoted++; + finalizedNow.push({ ...s, division }); + } + } + // Keep the finished week readable for a while, then let Redis drop it. + await store.expire(cohortKey(weekKey, division, cohortId), FINISHED_WEEK_TTL_SECONDS); + } + + // ── Phase 2: place the opted-in users in new cohorts for the next week ──── + const finished = await LeagueStanding.find({ weekKey, status: 'finalized' }) + .select('userId nextDivision') + .lean>(); + const optedIn = new Set( + (await UserSettings.find({ userId: { $in: finished.map(f => f.userId) }, 'leagues.participate': true }) + .select('userId') + .lean>()).map(s => s.userId.toString()), + ); + + const byDivision = new Map(); + for (const row of finished) { + const id = row.userId.toString(); + if (!optedIn.has(id)) continue; + byDivision.set(row.nextDivision, [...(byDivision.get(row.nextDivision) ?? []), id]); + } + + const { end: upcomingStart } = weekRange(weekKey); + const placements: Array<{ userId: string; division: LeagueDivision; cohortId: string }> = []; + for (const division of LEAGUE_DIVISIONS) { + const ids = byDivision.get(division); + if (!ids) continue; + for (const { userId, cohortId } of assignCohorts(ids, `${upcomingWeekKey}:${division}`)) { + placements.push({ userId, division, cohortId }); + } + } + for (let i = 0; i < placements.length; i += WRITE_BATCH) { + const writes = await LeagueStanding.bulkWrite( + placements.slice(i, i + WRITE_BATCH).map(p => ({ + updateOne: { + filter: { weekKey: upcomingWeekKey, userId: new Types.ObjectId(p.userId) }, + update: { + $setOnInsert: { + weekKey: upcomingWeekKey, userId: new Types.ObjectId(p.userId), division: p.division, cohortId: p.cohortId, + status: 'active' as const, joinedAt: upcomingStart, points: 0, + rank: null, cohortSize: null, outcome: null, nextDivision: null, finalizedAt: null, + }, + }, + upsert: true, + }, + })), + ); + result.assigned += writes.upsertedCount; + } + + // ── Phase 3: make every member of the new week visible on its Redis board ─ + const upcoming = await LeagueStanding.find({ weekKey: upcomingWeekKey, status: 'active' }) + .select('userId division cohortId') + .lean>(); + const members = new Map(); + for (const row of upcoming) { + const key = cohortKey(upcomingWeekKey, row.division, row.cohortId); + const entry = members.get(key) ?? { division: row.division, cohortId: row.cohortId, ids: [] }; + entry.ids.push(row.userId.toString()); + members.set(key, entry); + } + for (const [key, entry] of members) await store.seed(key, entry.ids); + + // ── Notify only the users finalized by this run ─────────────────────────── + for (const s of finalizedNow) { + try { + await notify(s.userId, { + weekKey, division: s.division, rank: s.rank, points: s.points, + cohortSize: s.cohortSize, outcome: s.outcome, nextDivision: s.nextDivision, + }); + } catch (error) { + logger.warn('[leagues] league.week.finalized notification failed', { + event: 'league_week_finalized_notify_failed', weekKey, userId: s.userId, + error: error instanceof Error ? error.message : String(error), + }); + } + } + + logger.info('[leagues] Weekly rollover complete', { event: 'league_rollover_complete', ...result }); + return result; +} diff --git a/backend/src/modules/leagues/scoreStore.ts b/backend/src/modules/leagues/scoreStore.ts new file mode 100644 index 00000000..12833c78 --- /dev/null +++ b/backend/src/modules/leagues/scoreStore.ts @@ -0,0 +1,99 @@ +// src/modules/leagues/scoreStore.ts — Narrow interface over the Redis sorted sets that hold live standings. +// The leagues code only talks to LeagueScoreStore, so unit tests can use an in-memory fake +// and never need a Redis server. + +import type { Redis } from 'ioredis'; +import { getRedisClient } from '../../shared/redis/index.js'; +import { SCORE_DEDUPE_TTL_SECONDS } from './leagues.constants.js'; + +export interface ScoreEntry { + member: string; + score: number; +} + +export interface LeagueScoreStore { + /** + * ZINCRBY, applied at most once per dedupe id. Resolves with the new score, + * or null when this award was already applied. + */ + incrementOnce( + key: string, + member: string, + delta: number, + dedupe: { setKey: string; id: string }, + ): Promise; + /** ZADD NX with score 0: makes members appear on the board without touching existing scores. */ + seed(key: string, members: string[]): Promise; + /** Replaces the whole sorted set (used when rebuilding from the XP ledger). */ + replace(key: string, entries: ScoreEntry[]): Promise; + /** ZREM */ + remove(key: string, member: string): Promise; + /** ZREVRANGE key start stop WITHSCORES, highest score first. */ + ranked(key: string, start: number, stop: number): Promise; + exists(key: string): Promise; + expire(key: string, seconds: number): Promise; +} + +// Add to the applied-set first; only a first-time award touches the score. Atomic in Redis. +const INCREMENT_ONCE_LUA = ` +if redis.call('SADD', KEYS[2], ARGV[2]) == 0 then return false end +redis.call('EXPIRE', KEYS[2], ARGV[3]) +return redis.call('ZINCRBY', KEYS[1], ARGV[1], ARGV[4]) +`; + +type RedisLike = Pick; + +export function createRedisScoreStore(client: RedisLike): LeagueScoreStore { + return { + async incrementOnce(key, member, delta, dedupe) { + const result = await client.eval( + INCREMENT_ONCE_LUA, 2, key, dedupe.setKey, String(delta), dedupe.id, String(SCORE_DEDUPE_TTL_SECONDS), member, + ); + return result === null || result === false || result === undefined ? null : Number(result); + }, + + async seed(key, members) { + if (members.length === 0) return; + const args: (string | number)[] = []; + for (const member of members) args.push(0, member); + await client.zadd(key, 'NX', ...(args as [number, string])); + }, + + async replace(key, entries) { + const pipeline = client.multi().del(key); + if (entries.length > 0) { + const args: (string | number)[] = []; + for (const { member, score } of entries) args.push(score, member); + pipeline.zadd(key, ...(args as [number, string])); + } + await pipeline.exec(); + }, + + async remove(key, member) { + await client.zrem(key, member); + }, + + async ranked(key, start, stop) { + const flat = await client.zrevrange(key, start, stop, 'WITHSCORES'); + const entries: ScoreEntry[] = []; + for (let i = 0; i < flat.length; i += 2) entries.push({ member: flat[i], score: Number(flat[i + 1]) }); + return entries; + }, + + async exists(key) { + return (await client.exists(key)) === 1; + }, + + async expire(key, seconds) { + await client.expire(key, seconds); + }, + }; +} + +let defaultStore: LeagueScoreStore | null = null; + +/** Lazily bound so importing this module never opens a Redis connection. */ +export function getLeagueScoreStore(): LeagueScoreStore { + defaultStore ??= createRedisScoreStore(getRedisClient()); + return defaultStore; +} diff --git a/backend/src/modules/leagues/weeks.ts b/backend/src/modules/leagues/weeks.ts new file mode 100644 index 00000000..7d198615 --- /dev/null +++ b/backend/src/modules/leagues/weeks.ts @@ -0,0 +1,47 @@ +// src/modules/leagues/weeks.ts — League weeks run Sunday 00:00 UTC to the next Sunday 00:00 UTC. +// A week is identified by the UTC date of the Sunday that starts it (e.g. "2026-11-15"). + +const DAY_MS = 86_400_000; +const WEEK_MS = 7 * DAY_MS; +const WEEK_KEY_RE = /^(\d{4})-(\d{2})-(\d{2})$/; + +export function weekStart(date: Date): Date { + const midnight = Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()); + return new Date(midnight - date.getUTCDay() * DAY_MS); +} + +export function weekKeyFor(date: Date): string { + return weekStart(date).toISOString().slice(0, 10); +} + +export function isValidWeekKey(weekKey: string): boolean { + const match = WEEK_KEY_RE.exec(weekKey); + if (!match) return false; + const start = new Date(`${weekKey}T00:00:00.000Z`); + return !Number.isNaN(start.getTime()) && start.toISOString().slice(0, 10) === weekKey && start.getUTCDay() === 0; +} + +function assertWeekKey(weekKey: string): Date { + if (!isValidWeekKey(weekKey)) throw new Error(`Invalid league week key: ${weekKey}`); + return new Date(`${weekKey}T00:00:00.000Z`); +} + +/** Half-open range [start, end). */ +export function weekRange(weekKey: string): { start: Date; end: Date } { + const start = assertWeekKey(weekKey); + return { start, end: new Date(start.getTime() + WEEK_MS) }; +} + +export function nextWeekKey(weekKey: string): string { + return weekRange(weekKey).end.toISOString().slice(0, 10); +} + +export function previousWeekKey(weekKey: string): string { + const start = assertWeekKey(weekKey); + return new Date(start.getTime() - WEEK_MS).toISOString().slice(0, 10); +} + +export function secondsUntilReset(now: Date): number { + const { end } = weekRange(weekKeyFor(now)); + return Math.max(0, Math.ceil((end.getTime() - now.getTime()) / 1000)); +} diff --git a/backend/src/modules/leagues/workers/leagueScore.worker.ts b/backend/src/modules/leagues/workers/leagueScore.worker.ts new file mode 100644 index 00000000..6cae7b92 --- /dev/null +++ b/backend/src/modules/leagues/workers/leagueScore.worker.ts @@ -0,0 +1,70 @@ +// src/modules/leagues/workers/leagueScore.worker.ts — Applies awarded XP to weekly league standings. +// The XP processor enqueues one job per ledger-backed award (after the transaction commits); +// this worker turns it into a ZINCRBY on the user's cohort sorted set. + +import { Worker, Job } from 'bullmq'; +import { createDlqWorker } from '../../../shared/jobs/dlq.service.js'; +import { getOrCreateQueue } from '../../../shared/jobs/queueFactory.js'; +import { QueueNames, JobRetryConfig, type LeagueScoreJobData } from '../../../shared/jobs/types.js'; +import { getRedisClient } from '../../../shared/redis/index.js'; +import { logger } from '../../../shared/logger.js'; +import { recordXpAward } from '../leagues.service.js'; +import { getLeagueScoreStore, type LeagueScoreStore } from '../scoreStore.js'; + +let _worker: Worker | null = null; + +export async function enqueueLeagueScore(data: LeagueScoreJobData): Promise { + await getOrCreateQueue(QueueNames.LEAGUE_SCORE).add('league-score', data, { + ...JobRetryConfig.xpProcessing, + }); +} + +/** Job handler, exported separately so tests can drive it with a fake store. */ +export async function processLeagueScoreJob( + data: LeagueScoreJobData, + store: LeagueScoreStore = getLeagueScoreStore(), + now = new Date(), +) { + const occurredAt = new Date(data.occurredAt); + if (Number.isNaN(occurredAt.getTime())) throw new Error('league-score job has an invalid occurredAt'); + return recordXpAward( + { userId: data.userId, sourceType: data.sourceType, sourceId: data.sourceId, xpAwarded: data.xpAwarded, occurredAt }, + store, + now, + ); +} + +export function startLeagueScoreWorker(): Worker { + if (_worker) return _worker; + + _worker = createDlqWorker( + QueueNames.LEAGUE_SCORE, + async (job: Job) => { + const result = await processLeagueScoreJob(job.data); + logger.debug('[league-score] Processed XP award', { + event: 'league_score_processed', + jobId: job.id, + userId: job.data.userId, + applied: result.applied, + reason: result.applied ? undefined : result.reason, + }); + return result; + }, + { connection: getRedisClient(), concurrency: 10, ...JobRetryConfig.xpProcessing }, + ); + + _worker.on('failed', (job, err) => { + logger.error('[league-score] Job failed', err, { event: 'league_score_failed', jobId: job?.id, userId: job?.data.userId }); + }); + _worker.on('error', err => { + logger.error('[league-score] Worker error', err, { event: 'league_score_worker_error' }); + }); + logger.info('[league-score] Worker started', { event: 'league_score_worker_started', queue: QueueNames.LEAGUE_SCORE }); + return _worker; +} + +export async function stopLeagueScoreWorker(): Promise { + if (!_worker) return; + await _worker.close(); + _worker = null; +} diff --git a/backend/src/modules/leagues/workers/weeklyRollover.worker.ts b/backend/src/modules/leagues/workers/weeklyRollover.worker.ts new file mode 100644 index 00000000..9c904355 --- /dev/null +++ b/backend/src/modules/leagues/workers/weeklyRollover.worker.ts @@ -0,0 +1,77 @@ +// src/modules/leagues/workers/weeklyRollover.worker.ts — Sunday 00:00 UTC league rollover. +// A BullMQ repeatable job fires the rollover; the work itself is runWeeklyRollover, which is +// idempotent per week key, so a retry or a duplicate trigger is harmless. + +import { Worker, Job } from 'bullmq'; +import { createDlqWorker } from '../../../shared/jobs/dlq.service.js'; +import { getOrCreateQueue } from '../../../shared/jobs/queueFactory.js'; +import { QueueNames, JobRetryConfig, type LeagueRolloverJobData } from '../../../shared/jobs/types.js'; +import { getRedisClient } from '../../../shared/redis/index.js'; +import { logger } from '../../../shared/logger.js'; +import { runWeeklyRollover, type RolloverResult } from '../rollover.js'; +import { getLeagueScoreStore } from '../scoreStore.js'; +import { isValidWeekKey, previousWeekKey, weekKeyFor } from '../weeks.js'; + +/** Every Sunday at 00:00 UTC. */ +export const WEEKLY_ROLLOVER_CRON = '0 0 * * 0'; + +let _worker: Worker | null = null; + +/** + * Week to finalize for a trigger that ran at `ranAt`: the one before the week `ranAt` is in. + * A late run (worker was down at midnight) still finalizes the right week. + */ +export function weekToFinalize(ranAt: Date, requested?: string): string { + if (requested !== undefined) { + if (!isValidWeekKey(requested)) throw new Error(`Invalid league week key: ${requested}`); + return requested; + } + return previousWeekKey(weekKeyFor(ranAt)); +} + +export async function processRolloverJob(data: LeagueRolloverJobData, ranAt: Date): Promise { + return runWeeklyRollover(weekToFinalize(ranAt, data.weekKey), { store: getLeagueScoreStore(), now: ranAt }); +} + +export async function scheduleWeeklyRollover(): Promise { + await getOrCreateQueue(QueueNames.LEAGUE_ROLLOVER).add( + 'weekly-rollover', + {}, + { + repeat: { pattern: WEEKLY_ROLLOVER_CRON, tz: 'UTC' }, + jobId: 'league-weekly-rollover', + ...JobRetryConfig.standard, + removeOnComplete: { count: 5 }, + removeOnFail: { count: 10 }, + }, + ); +} + +export function startWeeklyRolloverWorker(): Worker { + if (_worker) return _worker; + + _worker = createDlqWorker( + QueueNames.LEAGUE_ROLLOVER, + async (job: Job) => { + const result = await processRolloverJob(job.data, new Date(job.processedOn ?? Date.now())); + logger.info('[league-rollover] Rollover finished', { event: 'league_rollover_job_done', jobId: job.id, ...result }); + return result; + }, + { connection: getRedisClient(), concurrency: 1 }, + ); + + _worker.on('failed', (job, err) => { + logger.error('[league-rollover] Job failed', err, { event: 'league_rollover_failed', jobId: job?.id }); + }); + _worker.on('error', err => { + logger.error('[league-rollover] Worker error', err, { event: 'league_rollover_worker_error' }); + }); + logger.info('[league-rollover] Worker started', { event: 'league_rollover_worker_started', queue: QueueNames.LEAGUE_ROLLOVER }); + return _worker; +} + +export async function stopWeeklyRolloverWorker(): Promise { + if (!_worker) return; + await _worker.close(); + _worker = null; +} diff --git a/backend/src/modules/xp/processor.ts b/backend/src/modules/xp/processor.ts index 13a507f3..a405bd8b 100644 --- a/backend/src/modules/xp/processor.ts +++ b/backend/src/modules/xp/processor.ts @@ -18,6 +18,7 @@ import { updateMissionProgress } from '../missions/missionProgress.service.js'; import { cacheManager } from '../../shared/cache/cacheManager.js'; import { unifiedRuntimeStateService } from '../runtime-state/unifiedRuntimeState.service.js'; import { computeActiveSec, decideFocusXp } from '../activity/focusXpDecision.js'; +import { enqueueLeagueScore } from '../leagues/workers/leagueScore.worker.js'; export interface XpEventPayload { userId: string; @@ -214,6 +215,15 @@ async function applyXpEvent(payload: XpEventPayload, missionReward?: number): Pr for (let level = levelBefore + 1; level <= levelAfter; level++) { eventBus.emitLevelUp(userId, level, newTotalXp); } + // ── Weekly leagues: hand the committed award to the league score worker ── + if (xpAwarded > 0) { + try { + await enqueueLeagueScore({ userId, sourceType, sourceId, xpAwarded, occurredAt: new Date().toISOString(), requestId }); + } catch (err) { + logger.warn('[xp] League score enqueue failed (non-fatal)', { error: err }); + } + } + // ── Step 9: Runtime state sync ────────────────────────────────────────── try { await unifiedRuntimeStateService.updateFromEvent({ diff --git a/backend/src/routes/index.ts b/backend/src/routes/index.ts index bd674954..0a09be10 100644 --- a/backend/src/routes/index.ts +++ b/backend/src/routes/index.ts @@ -31,6 +31,7 @@ import { evidenceRoutes } from '../modules/resume/routes/evidence.routes.js'; import { resumeIntelligenceRoutes } from '../modules/resume/index.js'; import analyticsRoutes from '../modules/analytics/analytics.routes.js'; import { revisionRoutes } from '../modules/revision/index.js'; +import { leaguesRoutes } from '../modules/leagues/index.js'; import { aiQuotaRoutes } from '../modules/ai/quota.routes.js'; import { rateLimiters } from '../middleware/rateLimitAdvanced.js'; @@ -91,6 +92,7 @@ router.use('/evidence', evidenceRoutes); router.use('/recommendations', rateLimiters.ai, recommendationRoutes); router.use('/analytics', analyticsRoutes); router.use('/revision', revisionRoutes); +router.use('/leagues', leaguesRoutes); router.use('/ai', rateLimiters.ai, aiQuotaRoutes); export default router; diff --git a/backend/src/shared/events/eventContract.ts b/backend/src/shared/events/eventContract.ts index 1d749456..4bc9e2b5 100644 --- a/backend/src/shared/events/eventContract.ts +++ b/backend/src/shared/events/eventContract.ts @@ -67,6 +67,7 @@ export type DomainEventType = | 'dsa.problem.solved' | 'revision.reviewed' | 'contest.starting-soon' + | 'league.week.finalized' // Public profile integrity | 'profile.flagged'; diff --git a/backend/src/shared/events/sseBridge.ts b/backend/src/shared/events/sseBridge.ts index 44d20035..5794408f 100644 --- a/backend/src/shared/events/sseBridge.ts +++ b/backend/src/shared/events/sseBridge.ts @@ -27,6 +27,7 @@ export const SSE_BRIDGE_ALLOWLIST: readonly string[] = [ 'contest.starting-soon', 'dsa.problem.solved', 'revision.reviewed', + 'league.week.finalized', ]; /** @@ -73,6 +74,8 @@ export function mapDomainEventToSseType(type: string): SseEventType { return 'dsa_problem_solved'; case 'revision.reviewed': return 'revision_reviewed'; + case 'league.week.finalized': + return 'league_week_finalized'; default: return type.replace(/[\.\-]/g, '_') as SseEventType; } diff --git a/backend/src/shared/jobs/types.ts b/backend/src/shared/jobs/types.ts index 2a14c321..c0a65940 100644 --- a/backend/src/shared/jobs/types.ts +++ b/backend/src/shared/jobs/types.ts @@ -107,7 +107,23 @@ export interface DatasetValidationJobData { requestId?: string; } -export type JobData = PlatformSyncJobData | RealtimeEventJobData | SystemMaintenanceJobData | XpProcessingJobData | StreakRecalcJobData | NotificationJobData | ResumeUploadJobData | ResumeCheckpointJobData | ResumeATSJobData | ResumeEmbeddingJobData | ResumeSemanticJobData | ResumeRecommendationJobData | ResumeReplayJobData | DatasetIngestionJobData | DatasetValidationJobData; +export interface LeagueScoreJobData { + userId: string; + sourceType: string; + sourceId: string; + xpAwarded: number; + /** ISO timestamp of the XP ledger write; picks the league week the points belong to. */ + occurredAt: string; + requestId?: string; +} + +export interface LeagueRolloverJobData { + /** Week to finalize. Omit on the repeatable schedule: the worker finalizes the week before the current one. */ + weekKey?: string; + requestId?: string; +} + +export type JobData = PlatformSyncJobData | RealtimeEventJobData | SystemMaintenanceJobData | XpProcessingJobData | StreakRecalcJobData | NotificationJobData | ResumeUploadJobData | ResumeCheckpointJobData | ResumeATSJobData | ResumeEmbeddingJobData | ResumeSemanticJobData | ResumeRecommendationJobData | ResumeReplayJobData | DatasetIngestionJobData | DatasetValidationJobData | LeagueScoreJobData | LeagueRolloverJobData; export const QueueNames = { PLATFORM_SYNC: 'platform-sync', @@ -117,6 +133,10 @@ export const QueueNames = { STREAK_RECALC: 'streak-recalc', NOTIFICATIONS: 'notifications', PROFILE_REBUILD: 'profile-rebuild', + + // Weekly Leagues + LEAGUE_SCORE: 'league-score', + LEAGUE_ROLLOVER: 'league-rollover', // Readiness Decoupled Pipelines READINESS_DSA: 'readiness-dsa', diff --git a/backend/src/shared/sse/eventBus.ts b/backend/src/shared/sse/eventBus.ts index bb7ee513..d27ef264 100644 --- a/backend/src/shared/sse/eventBus.ts +++ b/backend/src/shared/sse/eventBus.ts @@ -223,6 +223,7 @@ export type SseEventType = | 'contest_starting_soon' | 'revision_reviewed' | 'streak_updated' + | 'league_week_finalized' // System | 'heartbeat'; diff --git a/backend/src/workers/worker-runtime.test.ts b/backend/src/workers/worker-runtime.test.ts index 3e0d54ae..a48130e6 100644 --- a/backend/src/workers/worker-runtime.test.ts +++ b/backend/src/workers/worker-runtime.test.ts @@ -4,10 +4,11 @@ import { spawnSync } from 'node:child_process'; import { createWorkerRuntime, parseWorkerType, WORKER_TYPES, workerDefinitions } from './worker-runtime.js'; const mocks = vi.hoisted(() => { - const names = ['sync', 'xp', 'maintenance', 'generation', 'ats', 'export', 'credibility', 'variant', 'evidence', 'embedding', 'github', 'upload', 'profile', 'dataset', 'streak', 'notifications', 'sessionAts', 'sessionEmbedding', 'sessionSemantic', 'recommendation', 'dsa', 'projects', 'skills', 'benchmarks', 'roadmap', 'aggregation']; + const names = ['sync', 'xp', 'maintenance', 'generation', 'ats', 'export', 'credibility', 'variant', 'evidence', 'embedding', 'github', 'upload', 'profile', 'dataset', 'streak', 'notifications', 'sessionAts', 'sessionEmbedding', 'sessionSemantic', 'recommendation', 'dsa', 'projects', 'skills', 'benchmarks', 'roadmap', 'aggregation', 'leagueScore', 'leagueRollover']; return { workers: Object.fromEntries(names.map(name => [name, { start: vi.fn(), stop: vi.fn().mockResolvedValue(undefined) }])), schedule: vi.fn().mockResolvedValue(undefined), + scheduleRollover: vi.fn().mockResolvedValue(undefined), closeQueue: vi.fn().mockResolvedValue(undefined), }; }); @@ -29,6 +30,8 @@ vi.mock('../shared/jobs/profileRebuildWorker.js', () => ({ startProfileRebuildWo vi.mock('./worker-dataset-ingestion.js', () => ({ startDatasetIngestionWorker: mocks.workers.dataset.start, stopDatasetIngestionWorker: mocks.workers.dataset.stop })); vi.mock('../shared/jobs/streakRecalcWorker.js', () => ({ startStreakRecalcWorker: mocks.workers.streak.start, stopStreakRecalcWorker: mocks.workers.streak.stop })); +vi.mock('../modules/leagues/workers/leagueScore.worker.js', () => ({ startLeagueScoreWorker: mocks.workers.leagueScore.start, stopLeagueScoreWorker: mocks.workers.leagueScore.stop })); +vi.mock('../modules/leagues/workers/weeklyRollover.worker.js', () => ({ startWeeklyRolloverWorker: mocks.workers.leagueRollover.start, stopWeeklyRolloverWorker: mocks.workers.leagueRollover.stop, scheduleWeeklyRollover: mocks.scheduleRollover })); vi.mock('../shared/jobs/notificationWorker.js', () => ({ startNotificationWorker: mocks.workers.notifications.start, stopNotificationWorker: mocks.workers.notifications.stop })); vi.mock('./worker-resume-ats.js', () => ({ startResumeATSWorker: mocks.workers.sessionAts.start, stopResumeATSWorker: mocks.workers.sessionAts.stop })); vi.mock('./worker-resume-embedding.js', () => ({ startResumeEmbeddingWorker: mocks.workers.sessionEmbedding.start, stopResumeEmbeddingWorker: mocks.workers.sessionEmbedding.stop })); @@ -54,7 +57,7 @@ beforeEach(() => { vi.clearAllMocks(); }); describe('standalone worker selection and lifecycle', () => { const resume = ['generation', 'ats', 'export', 'credibility', 'variant', 'evidence', 'embedding', 'github', 'upload', 'profile', 'sessionAts', 'sessionEmbedding', 'sessionSemantic', 'recommendation']; const cases: [string | undefined, string[]][] = [ - ['sync', ['sync']], ['xp', ['xp', 'streak', 'notifications']], ['maintenance', ['maintenance']], + ['sync', ['sync']], ['xp', ['xp', 'streak', 'notifications', 'leagueScore']], ['maintenance', ['maintenance', 'leagueRollover']], ['readiness', ['dsa', 'projects', 'skills', 'benchmarks', 'roadmap', 'aggregation']], ['resume-intelligence', resume], ['dataset', ['dataset']], ['all', Object.keys(mocks.workers)], [undefined, Object.keys(mocks.workers)], ['', Object.keys(mocks.workers)], @@ -70,6 +73,7 @@ describe('standalone worker selection and lifecycle', () => { expect(worker.stop).not.toHaveBeenCalled(); } expect(mocks.schedule).toHaveBeenCalledTimes(expected.includes('maintenance') ? 1 : 0); + expect(mocks.scheduleRollover).toHaveBeenCalledTimes(expected.includes('leagueRollover') ? 1 : 0); await Promise.all([runtime.stop(), runtime.stop()]); for (const [name, worker] of Object.entries(mocks.workers)) { expect(worker.stop).toHaveBeenCalledTimes(expected.includes(name) ? 1 : 0); @@ -134,6 +138,14 @@ describe('standalone worker selection and lifecycle', () => { expect(mocks.workers.maintenance.stop).toHaveBeenCalledOnce(); }); + it('treats a failed rollover schedule as startup failure and closes the rollover worker', async () => { + mocks.scheduleRollover.mockRejectedValueOnce(new Error('rollover schedule failed')); + const runtime = createWorkerRuntime('maintenance', services()); + await expect(runtime.start()).rejects.toThrow('rollover schedule failed'); + await runtime.stop(); + expect(mocks.workers.leagueRollover.stop).toHaveBeenCalledOnce(); + }); + it('propagates loader failures and drains earlier consumers', async () => { const load = vi.fn().mockRejectedValueOnce(new Error('module missing')); const runtime = createWorkerRuntime('all', services(), [workerDefinitions[0], { role: 'xp', load }]); diff --git a/backend/src/workers/worker-runtime.ts b/backend/src/workers/worker-runtime.ts index cfb31cfa..7a74eb8e 100644 --- a/backend/src/workers/worker-runtime.ts +++ b/backend/src/workers/worker-runtime.ts @@ -83,6 +83,14 @@ export const workerDefinitions: { role: Role; queueName?: string; load(): Promis const m = await import('../shared/jobs/notificationWorker.js'); return { start: m.startNotificationWorker, stop: m.stopNotificationWorker }; } }, + { role: 'xp', queueName: 'league-score', load: async () => { + const m = await import('../modules/leagues/workers/leagueScore.worker.js'); + return { start: m.startLeagueScoreWorker, stop: m.stopLeagueScoreWorker }; + } }, + { role: 'maintenance', queueName: 'league-rollover', load: async () => { + const m = await import('../modules/leagues/workers/weeklyRollover.worker.js'); + return { start: async () => { m.startWeeklyRolloverWorker(); await m.scheduleWeeklyRollover(); }, stop: m.stopWeeklyRolloverWorker }; + } }, { role: 'resume-intelligence', queueName: 'resume-ats', load: async () => { const m = await import('./worker-resume-ats.js'); return { start: m.startResumeATSWorker, stop: m.stopResumeATSWorker };