Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand All @@ -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`).
Expand Down
1 change: 1 addition & 0 deletions backend/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
1 change: 1 addition & 0 deletions backend/src/__tests__/db/modelIndexes.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down
78 changes: 78 additions & 0 deletions backend/src/__tests__/modules/leagues/cohorts.test.ts
Original file line number Diff line number Diff line change
@@ -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');
});
});
63 changes: 63 additions & 0 deletions backend/src/__tests__/modules/leagues/fakeScoreStore.ts
Original file line number Diff line number Diff line change
@@ -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<string, Map<string, number>>();
readonly applied = new Map<string, Set<string>>();
readonly ttls = new Map<string, number>();

async incrementOnce(key: string, member: string, delta: number, dedupe: { setKey: string; id: string }) {
const seen = this.applied.get(dedupe.setKey) ?? new Set<string>();
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<string, number>();
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<string, number>();
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<string, number>())]
.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();
}
}
39 changes: 39 additions & 0 deletions backend/src/__tests__/modules/leagues/leagues.migration.test.ts
Original file line number Diff line number Diff line change
@@ -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();
});
});
95 changes: 95 additions & 0 deletions backend/src/__tests__/modules/leagues/leagues.routes.test.ts
Original file line number Diff line number Diff line change
@@ -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<typeof import('../../../modules/leagues/scoreStore.js')>()),
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<void>(resolve => server.once('listening', resolve));
base = `http://127.0.0.1:${(server.address() as AddressInfo).port}/api/v1/leagues`;
});
afterAll(() => new Promise<void>(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);
});
});
Loading
Loading