From ee4c3eeb27bed02aa018e5cebc64096df585ae62 Mon Sep 17 00:00:00 2001 From: Park Dahyeon Date: Sun, 12 Jul 2026 19:34:52 +0000 Subject: [PATCH] feat: add resumable competition migration runner --- apps/api/package.json | 1 + .../competition-domain-runner.spec.ts | 450 +++++++++ .../migrations/competition-domain-runner.ts | 927 ++++++++++++++++++ .../migrations/run-competition-domain.spec.ts | 34 + .../migrations/run-competition-domain.ts | 196 ++++ 5 files changed, 1608 insertions(+) create mode 100644 apps/api/src/modules/global/database/migrations/competition-domain-runner.spec.ts create mode 100644 apps/api/src/modules/global/database/migrations/competition-domain-runner.ts create mode 100644 apps/api/src/modules/global/database/migrations/run-competition-domain.spec.ts create mode 100644 apps/api/src/modules/global/database/migrations/run-competition-domain.ts diff --git a/apps/api/package.json b/apps/api/package.json index 04bb9dd7..05377cc8 100644 --- a/apps/api/package.json +++ b/apps/api/package.json @@ -8,6 +8,7 @@ "scripts": { "build": "nest build", "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"", + "competition:migrate": "ts-node src/modules/global/database/migrations/run-competition-domain.ts", "seed:dev": "ts-node src/seed.ts", "seed:dakao-participant": "ts-node src/seed-dakao-participant.ts", "start:dev": "NODE_ENV=dev NEW_RELIC_HOME=. node --import newrelic/esm-loader.mjs -r newrelic dist/main.js", diff --git a/apps/api/src/modules/global/database/migrations/competition-domain-runner.spec.ts b/apps/api/src/modules/global/database/migrations/competition-domain-runner.spec.ts new file mode 100644 index 00000000..580eddf8 --- /dev/null +++ b/apps/api/src/modules/global/database/migrations/competition-domain-runner.spec.ts @@ -0,0 +1,450 @@ +import mongoose from 'mongoose'; +import { + migrateCompetitionDomain, + type CompetitionDomainMigrationDb, + type CompetitionDomainMigrationSession, +} from './competition-domain-runner'; + +describe('migrateCompetitionDomain', () => { + it('defaults to a side-effect-free dry run and reports the deterministic plan', async () => { + const match = readyMatch(); + const db = new MemoryMigrationDb({ + match: [match], + riotMatch: [riotArchive()], + tournamentCode: [usedTournamentCode(match)], + }); + const startSession = jest.fn(async () => new FakeSession()); + + const result = await migrateCompetitionDomain(db, { startSession }); + + expect(result.mode).toBe('dry-run'); + expect(result.summary).toMatchObject({ + scanned: 1, + ready: 1, + applied: 0, + quarantined: 0, + failed: 0, + unclassified: 0, + factsPlanned: 1, + assignmentsPlanned: 1, + }); + expect(result.matches[0]).toMatchObject({ + status: 'ready', + factCount: 1, + assignmentCount: 1, + }); + expect(startSession).not.toHaveBeenCalled(); + expect(db.writeCount).toBe(0); + expect(db.docs('competition')).toHaveLength(0); + }); + + it('applies one Match atomically and converges on an already-applied replay', async () => { + const match = readyMatch(); + const originalResult = canonical(match.result); + const db = new MemoryMigrationDb({ + match: [match], + riotMatch: [riotArchive()], + tournamentCode: [usedTournamentCode(match)], + }); + const sessions: FakeSession[] = []; + const startSession = jest.fn(async () => { + const session = new FakeSession(); + sessions.push(session); + return session; + }); + + const first = await migrateCompetitionDomain(db, { + dryRun: false, + startSession, + }); + + expect(first.summary).toMatchObject({ + scanned: 1, + applied: 1, + alreadyApplied: 0, + failed: 0, + }); + expect(db.docs('competition')).toHaveLength(1); + expect(db.docs('competition_fact')).toHaveLength(1); + expect(db.docs('competition_fact')[0].evidence).toMatchObject({ + type: 'riot', + riotMatchId: 'KR_MIGRATION_1', + payloadHash: expect.stringMatching(/^sha256:[a-f0-9]{64}$/), + }); + expect(db.docs('tournament_code_assignment')).toHaveLength(1); + expect(db.docs('competition_migration_quarantine')).toHaveLength(0); + expect(String(db.docs('match')[0].competitionId)).toBe( + first.matches[0].competitionId, + ); + expect(canonical(db.docs('match')[0].result)).toBe(originalResult); + expect(sessions[0]).toMatchObject({ + started: 1, + committed: 1, + aborted: 0, + ended: 1, + }); + + const second = await migrateCompetitionDomain(db, { + dryRun: false, + startSession, + }); + + expect(second.summary).toMatchObject({ + scanned: 1, + applied: 0, + alreadyApplied: 1, + failed: 0, + }); + expect(db.docs('competition')).toHaveLength(1); + expect(db.docs('competition_fact')).toHaveLength(1); + expect(db.docs('tournament_code_assignment')).toHaveLength(1); + expect(sessions[1]).toMatchObject({ committed: 1, aborted: 0, ended: 1 }); + }); + + it('quarantines an ambiguous Match without changing any legacy Match field', async () => { + const match = ambiguousMatch(); + const before = canonical(match); + const db = new MemoryMigrationDb({ match: [match] }); + const session = new FakeSession(); + + const result = await migrateCompetitionDomain(db, { + dryRun: false, + startSession: async () => session, + }); + + expect(result.summary).toMatchObject({ + scanned: 1, + quarantined: 1, + applied: 0, + failed: 0, + }); + expect(result.matches[0]).toMatchObject({ + status: 'quarantined', + reasons: expect.arrayContaining([ + expect.objectContaining({ code: 'AMBIGUOUS_GAME_ASSIGNMENT' }), + ]), + }); + expect(canonical(db.docs('match')[0])).toBe(before); + expect(db.docs('competition')).toHaveLength(0); + expect(db.docs('competition_fact')).toHaveLength(0); + expect(db.docs('competition_migration_quarantine')).toHaveLength(1); + expect(session).toMatchObject({ committed: 1, aborted: 0, ended: 1 }); + }); + + it('aborts and reports a failed Match when persisted projection replay diverges', async () => { + const match = readyMatch(); + const db = new MemoryMigrationDb({ + match: [match], + riotMatch: [riotArchive()], + tournamentCode: [usedTournamentCode(match)], + }); + await migrateCompetitionDomain(db, { + dryRun: false, + startSession: async () => new FakeSession(), + }); + db.docs('competition')[0].projection = { + phase: 'completed', + corrupt: true, + }; + const session = new FakeSession(); + + const result = await migrateCompetitionDomain(db, { + dryRun: false, + startSession: async () => session, + }); + + expect(result.summary).toMatchObject({ + scanned: 1, + applied: 0, + alreadyApplied: 0, + failed: 1, + }); + expect(result.matches[0]).toMatchObject({ + status: 'failed', + error: expect.stringContaining('replay'), + }); + expect(session).toMatchObject({ committed: 0, aborted: 1, ended: 1 }); + }); + + it('reports apply failures without attempting writes when no session can be created', async () => { + const db = new MemoryMigrationDb({ match: [readyMatch()] }); + + const result = await migrateCompetitionDomain(db, { + dryRun: false, + startSession: async () => undefined, + }); + + expect(result.summary.failed).toBe(1); + expect(result.matches[0]).toMatchObject({ + status: 'failed', + error: expect.stringContaining('transaction session'), + }); + expect(db.writeCount).toBe(0); + }); +}); + +class FakeSession implements CompetitionDomainMigrationSession { + public started = 0; + public committed = 0; + public aborted = 0; + public ended = 0; + + startTransaction(): void { + this.started += 1; + } + + async commitTransaction(): Promise { + this.committed += 1; + } + + async abortTransaction(): Promise { + this.aborted += 1; + } + + async endSession(): Promise { + this.ended += 1; + } +} + +type AnyDoc = Record & { _id: unknown }; + +class MemoryMigrationDb implements CompetitionDomainMigrationDb { + private readonly collections = new Map(); + public writeCount = 0; + + constructor(seed: Record = {}) { + for (const [name, docs] of Object.entries(seed)) { + this.collections.set(name, docs); + } + } + + docs(name: string): AnyDoc[] { + const docs = this.collections.get(name) ?? []; + this.collections.set(name, docs); + return docs; + } + + collection(name: string) { + const owner = this; + return { + find(filter: Record) { + return new MemoryCursor(() => + owner.docs(name).filter((doc) => matches(doc, filter)), + ); + }, + async findOne(filter: Record) { + return owner.docs(name).find((doc) => matches(doc, filter)) ?? null; + }, + async updateOne( + filter: Record, + update: Record>, + options: { upsert?: boolean } = {}, + ) { + owner.writeCount += 1; + const docs = owner.docs(name); + let doc = docs.find((candidate) => matches(candidate, filter)); + const inserted = !doc && options.upsert === true; + if (inserted) { + doc = materializeEqualityFilter(filter); + docs.push(doc); + } + if (!doc) return { matchedCount: 0, modifiedCount: 0 }; + if (inserted) Object.assign(doc, update.$setOnInsert ?? {}); + Object.assign(doc, update.$set ?? {}); + return { + matchedCount: inserted ? 0 : 1, + modifiedCount: 1, + upsertedCount: inserted ? 1 : 0, + }; + }, + async deleteOne(filter: Record) { + owner.writeCount += 1; + const docs = owner.docs(name); + const index = docs.findIndex((doc) => matches(doc, filter)); + if (index === -1) return { deletedCount: 0 }; + docs.splice(index, 1); + return { deletedCount: 1 }; + }, + }; + } +} + +class MemoryCursor { + private sortSpec: Record = {}; + private max = 0; + + constructor(private readonly read: () => AnyDoc[]) {} + + sort(spec: Record): this { + this.sortSpec = spec; + return this; + } + + limit(limit: number): this { + this.max = limit; + return this; + } + + async *[Symbol.asyncIterator](): AsyncIterator { + const entries = [...this.read()].sort((left, right) => { + for (const [key, direction] of Object.entries(this.sortSpec)) { + const compared = String(readPath(left, key)).localeCompare( + String(readPath(right, key)), + ); + if (compared !== 0) return compared * direction; + } + return 0; + }); + for (const doc of this.max > 0 ? entries.slice(0, this.max) : entries) { + yield doc; + } + } +} + +function matches(doc: AnyDoc, filter: Record): boolean { + return Object.entries(filter).every(([key, expected]) => { + if (key === '$or') { + return (expected as Record[]).some((candidate) => + matches(doc, candidate), + ); + } + const actual = readPath(doc, key); + if (isRecord(expected)) { + if ('$exists' in expected) { + return (actual !== undefined) === Boolean(expected.$exists); + } + if ('$in' in expected) { + return (expected.$in as unknown[]).some((candidate) => + sameValue(actual, candidate), + ); + } + } + return sameValue(actual, expected); + }); +} + +function readPath(value: unknown, path: string): unknown { + return path.split('.').reduce((current, segment) => { + if (Array.isArray(current) && /^\d+$/.test(segment)) { + return current[Number(segment)]; + } + return isRecord(current) ? current[segment] : undefined; + }, value); +} + +function materializeEqualityFilter(filter: Record): AnyDoc { + return Object.fromEntries( + Object.entries(filter).filter( + ([key, value]) => !key.startsWith('$') && !isRecord(value), + ), + ) as AnyDoc; +} + +function sameValue(left: unknown, right: unknown): boolean { + return String(left) === String(right); +} + +function isRecord(value: unknown): value is Record { + return value !== null && typeof value === 'object' && !Array.isArray(value); +} + +function readyMatch(): AnyDoc { + const matchId = objectId(); + const codeId = objectId(); + return { + _id: matchId, + communityId: objectId(), + gameMode: 'pair', + gameCount: 1, + status: 'in-progress', + participants: [], + teams: [legacyTeam(1), legacyTeam(2)], + gameSchedule: [{ gameNumber: 1, teamAIndex: 1, teamBIndex: 2 }], + tournamentCodeIds: [codeId], + result: { + riotMatchIds: ['KR_MIGRATION_1'], + games: [ + { + gameNumber: 1, + riotMatchId: 'KR_MIGRATION_1', + blueTeamIndex: 1, + redTeamIndex: 2, + winnerTeamIndex: 1, + winnerSide: 'blue', + gameCreation: 1_782_864_000_000, + gameDuration: 1800, + participants: [], + }, + ], + seriesResults: [], + }, + createdAt: new Date('2026-07-01T00:00:00.000Z'), + updatedAt: new Date('2026-07-02T00:00:00.000Z'), + }; +} + +function usedTournamentCode(match = readyMatch()): AnyDoc { + return { + _id: match.tournamentCodeIds[0], + matchId: match._id, + state: 'used', + gameNumber: 1, + riotMatchId: 'KR_MIGRATION_1', + reservedAt: new Date('2026-07-01T00:30:00.000Z'), + usedAt: new Date('2026-07-01T01:00:00.000Z'), + }; +} + +function riotArchive(): AnyDoc { + return { + _id: objectId(), + matchId: 'KR_MIGRATION_1', + raw: { metadata: { matchId: 'KR_MIGRATION_1' } }, + }; +} + +function ambiguousMatch(): AnyDoc { + const match = readyMatch(); + match.teams = [legacyTeam(1), legacyTeam(2), legacyTeam(3), legacyTeam(4)]; + match.gameSchedule = [ + { gameNumber: 7, teamAIndex: 1, teamBIndex: 2 }, + { gameNumber: 7, teamAIndex: 3, teamBIndex: 4 }, + ]; + match.tournamentCodeIds = []; + match.result = { + games: [ + { + gameNumber: 7, + riotMatchId: 'KR_AMBIGUOUS', + blueTeamIndex: 1, + redTeamIndex: 2, + winnerTeamIndex: 1, + winnerSide: 'blue', + participants: [], + }, + ], + seriesResults: [], + }; + return match; +} + +function legacyTeam(teamIndex: number) { + return { + teamIndex, + name: `${teamIndex}팀`, + captainUserId: objectId(), + members: [], + }; +} + +function objectId(): mongoose.Types.ObjectId { + return new mongoose.Types.ObjectId(); +} + +function canonical(value: unknown): string { + return JSON.stringify(value, (_key, child) => { + if (child instanceof mongoose.Types.ObjectId) return child.toHexString(); + if (child instanceof Date) return child.toISOString(); + return child; + }); +} diff --git a/apps/api/src/modules/global/database/migrations/competition-domain-runner.ts b/apps/api/src/modules/global/database/migrations/competition-domain-runner.ts new file mode 100644 index 00000000..04c554bd --- /dev/null +++ b/apps/api/src/modules/global/database/migrations/competition-domain-runner.ts @@ -0,0 +1,927 @@ +import { createHash } from 'node:crypto'; +import mongoose from 'mongoose'; +import { projectCompetition } from '../../../competition/domain/competition-projector'; +import { + planCompetitionMigration, + type CompetitionMigrationAssignment, + type CompetitionMigrationFact, + type CompetitionMigrationIssue, + type LegacyMatchInput, + type ReadyCompetitionMigrationPlan, +} from './20260712-competition-domain'; + +const DEFAULT_MIGRATION_RUN_ID = '20260712-competition-domain'; +const MATCH_SCAN_FILTER = { 'teams.1': { $exists: true } }; + +type AnyDocument = Record & { _id: unknown }; + +export interface CompetitionDomainMigrationCursor extends AsyncIterable { + sort(specification: Record): CompetitionDomainMigrationCursor; + limit(limit: number): CompetitionDomainMigrationCursor; +} + +export interface CompetitionDomainMigrationCollection { + find( + filter: Record, + options?: { session?: CompetitionDomainMigrationSession }, + ): CompetitionDomainMigrationCursor; + findOne( + filter: Record, + options?: { session?: CompetitionDomainMigrationSession }, + ): Promise; + updateOne( + filter: Record, + update: { + $set?: Record; + $setOnInsert?: Record; + }, + options?: { + session?: CompetitionDomainMigrationSession; + upsert?: boolean; + }, + ): Promise<{ + matchedCount?: number; + modifiedCount?: number; + upsertedCount?: number; + }>; + deleteOne( + filter: Record, + options?: { session?: CompetitionDomainMigrationSession }, + ): Promise<{ deletedCount?: number }>; +} + +export interface CompetitionDomainMigrationDb { + collection(name: string): CompetitionDomainMigrationCollection; +} + +export interface CompetitionDomainMigrationSession { + startTransaction(): void; + commitTransaction(): Promise; + abortTransaction(): Promise; + endSession(): Promise; +} + +export interface CompetitionDomainMigrationOptions { + dryRun?: boolean; + limit?: number; + migrationRunId?: string; + now?: Date; + startSession?: () => Promise; + onProgress?: (progress: CompetitionDomainMigrationProgress) => void; +} + +export interface CompetitionDomainMigrationProgress { + index: number; + matchId: string; + status: CompetitionDomainMigrationMatchResult['status']; + total: number; +} + +interface CompetitionDomainMigrationMatchBase { + matchId: string; + competitionId?: string; + warnings: CompetitionMigrationIssue[]; +} + +export type CompetitionDomainMigrationMatchResult = + | (CompetitionDomainMigrationMatchBase & { + status: 'ready' | 'applied'; + factCount: number; + assignmentCount: number; + }) + | (CompetitionDomainMigrationMatchBase & { + status: 'already-applied'; + }) + | (CompetitionDomainMigrationMatchBase & { + status: 'quarantined'; + reasons: CompetitionMigrationIssue[]; + }) + | (CompetitionDomainMigrationMatchBase & { + status: 'failed'; + error: string; + }); + +export interface CompetitionDomainMigrationSummary { + scanned: number; + ready: number; + applied: number; + alreadyApplied: number; + quarantined: number; + failed: number; + /** Planner/runtime failures that were neither ready nor explicitly quarantined. */ + unclassified: number; + factsPlanned: number; + assignmentsPlanned: number; + warnings: number; +} + +export interface CompetitionDomainMigrationResult { + migrationRunId: string; + mode: 'dry-run' | 'apply'; + summary: CompetitionDomainMigrationSummary; + matches: CompetitionDomainMigrationMatchResult[]; +} + +/** + * Plans or applies the clean-break Competition migration. Apply mode owns one + * Mongo transaction per Match so a process can be stopped and safely resumed. + */ +export async function migrateCompetitionDomain( + db: CompetitionDomainMigrationDb, + options: CompetitionDomainMigrationOptions = {}, +): Promise { + const dryRun = options.dryRun ?? true; + const migrationRunId = + options.migrationRunId?.trim() || DEFAULT_MIGRATION_RUN_ID; + assertOptions(options); + + const matchSnapshots = await scanMatches(db, options.limit); + const matches: CompetitionDomainMigrationMatchResult[] = []; + for (const [index, scannedMatch] of matchSnapshots.entries()) { + const result = dryRun + ? await inspectMatch(db, scannedMatch, migrationRunId) + : await applyMatch(db, scannedMatch, migrationRunId, options); + matches.push(result); + options.onProgress?.({ + index: index + 1, + matchId: result.matchId, + status: result.status, + total: matchSnapshots.length, + }); + } + + return { + migrationRunId, + mode: dryRun ? 'dry-run' : 'apply', + summary: summarize(matches), + matches, + }; +} + +async function scanMatches( + db: CompetitionDomainMigrationDb, + limit: number | undefined, +): Promise { + return readCursor( + db + .collection('match') + .find(MATCH_SCAN_FILTER) + .sort({ _id: 1 }) + .limit(limit ?? 0), + ); +} + +async function inspectMatch( + db: CompetitionDomainMigrationDb, + scannedMatch: AnyDocument, + migrationRunId: string, +): Promise { + const matchId = idString(scannedMatch._id); + try { + const linkedCompetitionId = optionalIdString(scannedMatch.competitionId); + if (linkedCompetitionId) { + assertExpectedCompetitionId(matchId, linkedCompetitionId); + await verifyProjectionReplay(db, linkedCompetitionId); + return { + status: 'already-applied', + matchId, + competitionId: linkedCompetitionId, + warnings: [], + }; + } + + const legacy = await hydrateLegacyMatch(db, scannedMatch); + const plan = planCompetitionMigration(legacy, { migrationRunId }); + return planResult(matchId, plan); + } catch (error) { + return failedResult(matchId, error); + } +} + +async function applyMatch( + db: CompetitionDomainMigrationDb, + scannedMatch: AnyDocument, + migrationRunId: string, + options: CompetitionDomainMigrationOptions, +): Promise { + const matchId = idString(scannedMatch._id); + let session: CompetitionDomainMigrationSession | undefined; + try { + session = await options.startSession?.(); + if (!session) { + throw new Error( + 'Apply mode requires a MongoDB transaction session for every Match.', + ); + } + session.startTransaction(); + + const currentMatch = await db + .collection('match') + .findOne({ _id: scannedMatch._id }, { session }); + if (!currentMatch) throw new Error(`Match ${matchId} no longer exists.`); + + const linkedCompetitionId = optionalIdString(currentMatch.competitionId); + if (linkedCompetitionId) { + assertExpectedCompetitionId(matchId, linkedCompetitionId); + await verifyProjectionReplay(db, linkedCompetitionId, session); + await db + .collection('competition_migration_quarantine') + .deleteOne({ _id: currentMatch._id }, { session }); + await verifyProjectionReplay(db, linkedCompetitionId, session); + await session.commitTransaction(); + return { + status: 'already-applied', + matchId, + competitionId: linkedCompetitionId, + warnings: [], + }; + } + + // Re-read all evidence inside the transaction. The scan is only a work + // list; it is never treated as the source snapshot for an apply. + const legacy = await hydrateLegacyMatch(db, currentMatch, session); + const plan = planCompetitionMigration(legacy, { migrationRunId }); + if (plan.status === 'quarantined') { + await persistQuarantine( + db, + currentMatch, + plan.reasons, + plan.warnings, + migrationRunId, + options.now ?? new Date(), + session, + ); + await session.commitTransaction(); + return { + status: 'quarantined', + matchId, + warnings: plan.warnings, + reasons: plan.reasons, + }; + } + + await upsertReadyPlan(db, plan, session); + await verifyReadyPlan(db, plan, session); + + const competitionId = plan.competition.id; + const linkResult = await db.collection('match').updateOne( + { + _id: currentMatch._id, + $or: [ + { competitionId: { $exists: false } }, + { competitionId: null }, + { competitionId: persistenceId(competitionId) }, + ], + }, + { $set: { competitionId: persistenceId(competitionId) } }, + { session }, + ); + if (linkResult.matchedCount !== 1) { + throw new Error( + `Match ${matchId} was concurrently linked to another Competition.`, + ); + } + + await db + .collection('competition_migration_quarantine') + .deleteOne({ _id: currentMatch._id }, { session }); + // Verify again after the final Match/quarantine writes, immediately before + // committing, so every applied Match ends with a replay-equal aggregate. + await verifyProjectionReplay(db, competitionId, session); + await session.commitTransaction(); + return { + status: 'applied', + matchId, + competitionId, + factCount: plan.facts.length, + assignmentCount: plan.assignments.length, + warnings: plan.warnings, + }; + } catch (error) { + if (session) await session.abortTransaction().catch(() => undefined); + return failedResult(matchId, error); + } finally { + if (session) await session.endSession().catch(() => undefined); + } +} + +async function hydrateLegacyMatch( + db: CompetitionDomainMigrationDb, + match: AnyDocument, + session?: CompetitionDomainMigrationSession, +): Promise { + const tournamentCodeIds = arrayOf(match.tournamentCodeIds); + const tournamentCodes = await readCursor( + db + .collection('tournamentCode') + .find( + { + $or: [ + ...(tournamentCodeIds.length > 0 + ? [{ _id: { $in: tournamentCodeIds } }] + : []), + { matchId: match._id }, + ], + }, + { session }, + ) + .sort({ _id: 1 }) + .limit(0), + ); + const result = isRecord(match.result) ? match.result : undefined; + const games = Array.isArray(result?.games) ? result.games : []; + const riotMatchIds = uniqueStrings( + games.map((game) => (isRecord(game) ? game.riotMatchId : undefined)), + ); + const archives = + riotMatchIds.length === 0 + ? [] + : await readCursor( + db + .collection('riotMatch') + .find({ matchId: { $in: riotMatchIds } }, { session }) + .sort({ matchId: 1 }) + .limit(0), + ); + const archiveByMatchId = new Map( + archives.map((archive) => [String(archive.matchId), archive]), + ); + const archivedIds = new Set(archiveByMatchId.keys()); + const hydratedResult = result + ? { + ...result, + games: games.map((game) => + isRecord(game) + ? hydrateLegacyGameEvidence(game, archiveByMatchId) + : game, + ), + } + : undefined; + + return { + ...match, + ...(hydratedResult ? { result: hydratedResult } : {}), + tournamentCodes, + riotMatchArchiveIds: [...archivedIds].sort(), + } as unknown as LegacyMatchInput; +} + +function hydrateLegacyGameEvidence( + game: Record, + archiveByMatchId: ReadonlyMap, +): Record { + const riotMatchId = + typeof game.riotMatchId === 'string' ? game.riotMatchId : undefined; + const archive = riotMatchId ? archiveByMatchId.get(riotMatchId) : undefined; + if (!archive) return { ...game, riotArchivePresent: false }; + const existingPayloadHash = + typeof game.payloadHash === 'string' && game.payloadHash.trim().length > 0 + ? game.payloadHash + : undefined; + return { + ...game, + riotArchivePresent: true, + payloadHash: + existingPayloadHash ?? + `sha256:${createNodeHash(canonicalJson(archive.raw ?? archive))}`, + }; +} + +async function upsertReadyPlan( + db: CompetitionDomainMigrationDb, + plan: ReadyCompetitionMigrationPlan, + session: CompetitionDomainMigrationSession, +): Promise { + const competition = competitionForPersistence(plan); + await db + .collection('competition') + .updateOne( + { _id: competition._id }, + { $setOnInsert: competition }, + { upsert: true, session }, + ); + for (const fact of plan.facts) { + const persisted = factForPersistence(fact); + await db + .collection('competition_fact') + .updateOne( + { _id: persisted._id }, + { $setOnInsert: persisted }, + { upsert: true, session }, + ); + } + for (const assignment of plan.assignments) { + const persisted = assignmentForPersistence(assignment); + await db + .collection('tournament_code_assignment') + .updateOne( + { _id: persisted._id }, + { $setOnInsert: persisted }, + { upsert: true, session }, + ); + } +} + +async function verifyReadyPlan( + db: CompetitionDomainMigrationDb, + plan: ReadyCompetitionMigrationPlan, + session: CompetitionDomainMigrationSession, +): Promise { + const competition = await db + .collection('competition') + .findOne({ _id: persistenceId(plan.competition.id) }, { session }); + if (!competition) { + throw new Error( + `Competition ${plan.competition.id} is missing after deterministic upsert.`, + ); + } + assertFieldsEqual( + competition, + competitionForPersistence(plan), + [ + '_id', + 'matchId', + 'communityId', + 'schemaVersion', + 'projectorVersion', + 'teams', + 'format', + 'seriesGraph', + ], + `Competition ${plan.competition.id}`, + ); + + for (const fact of plan.facts) { + const expected = factForPersistence(fact); + const actual = await db + .collection('competition_fact') + .findOne({ _id: expected._id }, { session }); + if (!actual) throw new Error(`Migration fact ${fact.id} is missing.`); + assertFieldsEqual( + actual, + expected, + Object.keys(expected).filter( + (key) => key !== 'createdAt' && key !== 'updatedAt', + ), + `Migration fact ${fact.id}`, + ); + } + + for (const assignment of plan.assignments) { + const expected = assignmentForPersistence(assignment); + const actual = await db + .collection('tournament_code_assignment') + .findOne({ _id: expected._id }, { session }); + if (!actual) { + throw new Error(`TournamentCode assignment ${assignment.id} is missing.`); + } + assertFieldsEqual( + actual, + expected, + Object.keys(expected).filter( + (key) => key !== 'createdAt' && key !== 'updatedAt', + ), + `TournamentCode assignment ${assignment.id}`, + ); + } + + await verifyProjectionReplay(db, plan.competition.id, session); +} + +async function verifyProjectionReplay( + db: CompetitionDomainMigrationDb, + competitionId: string, + session?: CompetitionDomainMigrationSession, +): Promise { + const competition = await db + .collection('competition') + .findOne({ _id: persistenceId(competitionId) }, { session }); + if (!competition) { + throw new Error(`Linked Competition ${competitionId} does not exist.`); + } + const facts = await readCursor( + db + .collection('competition_fact') + .find({ competitionId: persistenceId(competitionId) }, { session }) + .sort({ revision: 1, ordinalWithinRevision: 1 }) + .limit(0), + ); + const revision = numberField(competition, 'revision'); + const projectorVersion = numberField(competition, 'projectorVersion'); + assertLedgerRevision(facts, revision, competitionId); + const replay = projectCompetition({ + competitionId, + revision, + projectorVersion, + teams: canonicalValue(competition.teams) as never, + format: canonicalValue(competition.format) as never, + seriesGraph: canonicalValue(competition.seriesGraph) as never, + facts: facts.map(factForProjection), + }); + if (canonicalJson(replay) !== canonicalJson(competition.projection)) { + throw new Error( + `Competition ${competitionId} projection replay does not equal the persisted projection.`, + ); + } + if (replay.phase !== competition.phase) { + throw new Error( + `Competition ${competitionId} replay phase does not equal the persisted phase.`, + ); + } +} + +function assertLedgerRevision( + facts: ReadonlyArray>, + competitionRevision: number, + competitionId: string, +): void { + const positions = new Set(); + const revisions = new Set(); + let maximumRevision = 0; + for (const fact of facts) { + const revision = numberField(fact, 'revision'); + const ordinal = numberField(fact, 'ordinalWithinRevision'); + if (revision < 1 || ordinal < 1) { + throw new Error( + `Competition ${competitionId} has an invalid fact ledger position.`, + ); + } + const position = `${revision}:${ordinal}`; + if (positions.has(position)) { + throw new Error( + `Competition ${competitionId} has duplicate fact ledger position ${position}.`, + ); + } + positions.add(position); + revisions.add(revision); + maximumRevision = Math.max(maximumRevision, revision); + } + if (maximumRevision !== competitionRevision) { + throw new Error( + `Competition ${competitionId} revision ${competitionRevision} does not match fact ledger revision ${maximumRevision}.`, + ); + } + if (revisions.size !== maximumRevision) { + throw new Error( + `Competition ${competitionId} fact ledger has a revision gap.`, + ); + } +} + +async function persistQuarantine( + db: CompetitionDomainMigrationDb, + match: AnyDocument, + reasons: CompetitionMigrationIssue[], + warnings: CompetitionMigrationIssue[], + migrationRunId: string, + observedAt: Date, + session: CompetitionDomainMigrationSession, +): Promise { + const sourceUpdatedAt = dateOrUndefined(match.updatedAt); + const payload = { + matchId: match._id, + migrationRunId, + status: 'quarantined', + reasons, + warnings, + sourceUpdatedAt, + planHash: canonicalHash({ + matchId: idString(match._id), + sourceUpdatedAt, + reasons, + warnings, + }), + observedAt, + updatedAt: observedAt, + }; + await db.collection('competition_migration_quarantine').updateOne( + { _id: match._id }, + { + $set: payload, + $setOnInsert: { _id: match._id, createdAt: observedAt }, + }, + { upsert: true, session }, + ); +} + +function competitionForPersistence( + plan: ReadyCompetitionMigrationPlan, +): AnyDocument { + const source = plan.competition; + return { + _id: persistenceId(source.id), + matchId: persistenceId(source.matchId), + communityId: persistenceId(source.communityId), + schemaVersion: source.schemaVersion, + projectorVersion: source.projectorVersion, + revision: source.revision, + phase: source.phase, + teams: source.teams.map((team) => ({ + ...team, + teamId: persistenceId(team.teamId), + ...(team.captainUserId + ? { captainUserId: persistenceId(team.captainUserId) } + : {}), + members: team.members.map((member) => ({ + ...member, + userId: persistenceId(member.userId), + })), + })), + format: source.format, + seriesGraph: source.seriesGraph, + projection: source.projection, + createdAt: new Date(source.createdAt), + updatedAt: new Date(source.updatedAt), + }; +} + +function factForPersistence(fact: CompetitionMigrationFact): AnyDocument { + const recordedAt = new Date(fact.recordedAt); + const common: AnyDocument = { + ...fact, + _id: persistenceId(fact.id), + competitionId: persistenceId(fact.competitionId), + occurredAt: new Date(fact.occurredAt), + recordedAt, + createdAt: recordedAt, + updatedAt: recordedAt, + }; + delete common.id; + if (fact.type === 'game-accepted') { + common.gameId = persistenceId(fact.gameId); + common.seriesId = persistenceId(fact.seriesId); + common.gameSlotId = persistenceId(fact.gameSlotId); + common.mapping = { + ...fact.mapping, + blueTeamId: persistenceId(fact.mapping.blueTeamId), + redTeamId: persistenceId(fact.mapping.redTeamId), + winnerTeamId: persistenceId(fact.mapping.winnerTeamId), + participantAssignments: fact.mapping.participantAssignments.map( + (assignment) => ({ + ...assignment, + userId: persistenceId(assignment.userId), + teamId: persistenceId(assignment.teamId), + }), + ), + }; + } else { + common.seriesId = persistenceId(fact.seriesId); + common.decision = + 'winnerTeamId' in fact.decision + ? { + ...fact.decision, + winnerTeamId: persistenceId(fact.decision.winnerTeamId), + } + : fact.decision; + } + return common; +} + +function assignmentForPersistence( + assignment: CompetitionMigrationAssignment, +): AnyDocument { + const reservedAt = new Date(assignment.reservedAt); + const updatedAt = new Date( + assignment.releasedAt ?? assignment.usedAt ?? assignment.reservedAt, + ); + const voidedAt = + assignment.state === 'voided' + ? new Date( + assignment.releasedAt ?? assignment.usedAt ?? assignment.reservedAt, + ) + : undefined; + return { + _id: persistenceId(assignment.id), + competitionId: persistenceId(assignment.competitionId), + seriesId: persistenceId(assignment.seriesId), + gameSlotId: persistenceId(assignment.gameSlotId), + tournamentCodeId: persistenceId(assignment.tournamentCodeId), + state: assignment.state, + reservedAt, + ...(assignment.usedAt ? { usedAt: new Date(assignment.usedAt) } : {}), + ...(assignment.releasedAt + ? { releasedAt: new Date(assignment.releasedAt) } + : {}), + ...(voidedAt ? { voidedAt } : {}), + ...(assignment.riotMatchId ? { riotMatchId: assignment.riotMatchId } : {}), + commandId: assignment.commandId, + createdAt: reservedAt, + updatedAt, + }; +} + +function factForProjection( + fact: Readonly>, +): Readonly> { + const canonical = canonicalValue(fact) as Readonly>; + return { ...canonical, id: idString(fact.id ?? fact._id) }; +} + +function planResult( + matchId: string, + plan: ReturnType, +): CompetitionDomainMigrationMatchResult { + if (plan.status === 'quarantined') { + return { + status: 'quarantined', + matchId, + warnings: plan.warnings, + reasons: plan.reasons, + }; + } + return { + status: 'ready', + matchId, + competitionId: plan.competition.id, + factCount: plan.facts.length, + assignmentCount: plan.assignments.length, + warnings: plan.warnings, + }; +} + +function failedResult( + matchId: string, + error: unknown, +): CompetitionDomainMigrationMatchResult { + return { + status: 'failed', + matchId, + warnings: [], + error: error instanceof Error ? error.message : String(error), + }; +} + +function summarize( + matches: CompetitionDomainMigrationMatchResult[], +): CompetitionDomainMigrationSummary { + const count = (status: CompetitionDomainMigrationMatchResult['status']) => + matches.filter((match) => match.status === status).length; + return { + scanned: matches.length, + ready: count('ready'), + applied: count('applied'), + alreadyApplied: count('already-applied'), + quarantined: count('quarantined'), + failed: count('failed'), + unclassified: count('failed'), + factsPlanned: matches.reduce( + (sum, match) => sum + ('factCount' in match ? match.factCount : 0), + 0, + ), + assignmentsPlanned: matches.reduce( + (sum, match) => + sum + ('assignmentCount' in match ? match.assignmentCount : 0), + 0, + ), + warnings: matches.reduce((sum, match) => sum + match.warnings.length, 0), + }; +} + +function assertExpectedCompetitionId( + matchId: string, + linkedCompetitionId: string, +): void { + const expected = deterministicCompetitionId(matchId); + if (linkedCompetitionId !== expected) { + throw new Error( + `Match ${matchId} links Competition ${linkedCompetitionId}; expected deterministic Competition ${expected}.`, + ); + } +} + +function deterministicCompetitionId(matchId: string): string { + return createHash('sha256') + .update(JSON.stringify([matchId, 'competition'])) + .digest('hex') + .slice(0, 24); +} + +function assertFieldsEqual( + actual: Record, + expected: Record, + fields: string[], + label: string, +): void { + for (const field of fields) { + if (canonicalJson(actual[field]) !== canonicalJson(expected[field])) { + throw new Error(`${label} has conflicting persisted field ${field}.`); + } + } +} + +function assertOptions(options: CompetitionDomainMigrationOptions): void { + if ( + options.limit !== undefined && + (!Number.isInteger(options.limit) || options.limit < 1) + ) { + throw new Error('Competition migration limit must be a positive integer.'); + } + if (options.dryRun === false && !options.startSession) { + throw new Error('Apply mode requires a transaction session factory.'); + } +} + +async function readCursor( + cursor: CompetitionDomainMigrationCursor, +): Promise { + const result: AnyDocument[] = []; + for await (const document of cursor) result.push(document); + return result; +} + +function numberField(document: Record, field: string): number { + const value = document[field]; + if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) { + throw new Error(`Competition has invalid ${field}.`); + } + return value; +} + +function persistenceId(value: unknown): unknown { + if (value instanceof mongoose.Types.ObjectId) return value; + const stringValue = idString(value); + return mongoose.Types.ObjectId.isValid(stringValue) && + /^[a-f\d]{24}$/i.test(stringValue) + ? new mongoose.Types.ObjectId(stringValue) + : value; +} + +function optionalIdString(value: unknown): string | undefined { + return value === undefined || value === null || value === '' + ? undefined + : idString(value); +} + +function idString(value: unknown): string { + if (value instanceof mongoose.Types.ObjectId) return value.toHexString(); + if ( + value && + typeof value === 'object' && + 'toHexString' in value && + typeof value.toHexString === 'function' + ) { + return String(value.toHexString()); + } + return String(value); +} + +function arrayOf(value: unknown): unknown[] { + return Array.isArray(value) ? value : []; +} + +function uniqueStrings(values: unknown[]): string[] { + return [ + ...new Set( + values.filter( + (value): value is string => + typeof value === 'string' && value.trim().length > 0, + ), + ), + ].sort(); +} + +function isRecord(value: unknown): value is Record { + return value !== null && typeof value === 'object' && !Array.isArray(value); +} + +function dateOrUndefined(value: unknown): Date | undefined { + if (value === undefined || value === null || value === '') return undefined; + const date = value instanceof Date ? value : new Date(value as string); + return Number.isNaN(date.getTime()) ? undefined : date; +} + +function canonicalHash(value: unknown): string { + return `sha256:${createNodeHash(canonicalJson(value))}`; +} + +function createNodeHash(value: string): string { + // Kept in one helper so canonical hashes use exactly one encoding. + return createHash('sha256').update(value).digest('hex'); +} + +function canonicalJson(value: unknown): string { + return JSON.stringify(canonicalValue(value)); +} + +function canonicalValue(value: unknown): unknown { + if (value instanceof mongoose.Types.ObjectId) return value.toHexString(); + if (value instanceof Date) return value.toISOString(); + if ( + value && + typeof value === 'object' && + 'toHexString' in value && + typeof value.toHexString === 'function' + ) { + return String(value.toHexString()); + } + if (Array.isArray(value)) return value.map(canonicalValue); + if (isRecord(value)) { + return Object.fromEntries( + Object.entries(value) + .filter(([, child]) => child !== undefined) + .sort(([left], [right]) => left.localeCompare(right)) + .map(([key, child]) => [key, canonicalValue(child)]), + ); + } + return value; +} diff --git a/apps/api/src/modules/global/database/migrations/run-competition-domain.spec.ts b/apps/api/src/modules/global/database/migrations/run-competition-domain.spec.ts new file mode 100644 index 00000000..f1c3b0b7 --- /dev/null +++ b/apps/api/src/modules/global/database/migrations/run-competition-domain.spec.ts @@ -0,0 +1,34 @@ +import { parseCliOptions } from './run-competition-domain'; + +describe('competition domain migration CLI', () => { + const originalNodeEnv = process.env.NODE_ENV; + + beforeEach(() => { + process.env.NODE_ENV = 'dev'; + }); + + afterAll(() => { + process.env.NODE_ENV = originalNodeEnv; + }); + + it('ignores pnpm standalone separators before dry-run and apply options', () => { + expect(parseCliOptions(['--', '--dry-run'])).toMatchObject({ + dryRun: true, + help: false, + nodeEnv: 'dev', + }); + expect(parseCliOptions(['--', '--apply'])).toMatchObject({ + dryRun: false, + help: false, + nodeEnv: 'dev', + }); + }); + + it('recognizes help after a pnpm standalone separator without exiting', () => { + expect(parseCliOptions(['--', '--help'])).toMatchObject({ + dryRun: true, + help: true, + nodeEnv: 'dev', + }); + }); +}); diff --git a/apps/api/src/modules/global/database/migrations/run-competition-domain.ts b/apps/api/src/modules/global/database/migrations/run-competition-domain.ts new file mode 100644 index 00000000..6c3133b6 --- /dev/null +++ b/apps/api/src/modules/global/database/migrations/run-competition-domain.ts @@ -0,0 +1,196 @@ +import 'reflect-metadata'; +import { Module } from '@nestjs/common'; +import { ConfigModule } from '@nestjs/config'; +import { NestFactory } from '@nestjs/core'; +import { readFile } from 'node:fs/promises'; +import { resolve } from 'node:path'; +import { ConnectionService, resolveMongoDbName } from '../connection.service'; +import { SecretModule } from '../../secret/secret.module'; +import { + migrateCompetitionDomain, + type CompetitionDomainMigrationDb, +} from './competition-domain-runner'; + +export interface CompetitionDomainCliOptions { + dryRun: boolean; + help: boolean; + limit?: number; + nodeEnv: string; +} + +@Module({ + imports: [ + ConfigModule.forRoot({ + isGlobal: true, + envFilePath: [ + resolve(__dirname, '../../../../../../project.env'), + resolve(process.cwd(), '../project.env'), + resolve(process.cwd(), 'apps/project.env'), + resolve(process.cwd(), 'project.env'), + ], + }), + SecretModule, + ], + providers: [ConnectionService], +}) +class MigrationModule {} + +async function loadMachineEnvFile(): Promise { + const homeDir = process.env.HOME ?? process.env.USERPROFILE; + if (!homeDir) return; + try { + const file = await readFile( + resolve(homeDir, 'source/global-env-vars.txt'), + 'utf8', + ); + for (const rawLine of file.split(/\r?\n/)) { + const line = rawLine.trim(); + if (!line || line.startsWith('#')) continue; + const matched = line.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/); + if (!matched) continue; + const [, key, rawValue] = matched; + process.env[key] = rawValue.replace(/^["']|["']$/g, ''); + } + } catch { + // A local machine env file is optional for one-off migrations. + } +} + +export function parseCliOptions(argv: string[]): CompetitionDomainCliOptions { + let dryRun = true; + let help = false; + let limit: number | undefined; + let nodeEnv = process.env.NODE_ENV ?? 'dev'; + + for (let index = 0; index < argv.length; index += 1) { + const argument = argv[index]; + // pnpm preserves the conventional option separator when it forwards + // script arguments (`pnpm ... -- --apply`). It is not a CLI option. + if (argument === '--') continue; + if (argument === '--apply') { + dryRun = false; + continue; + } + if (argument === '--dry-run') { + dryRun = true; + continue; + } + if (argument === '--env') { + const value = argv[index + 1]; + if (!value) throw new Error('--env requires dev, staging, or prod.'); + nodeEnv = value; + index += 1; + continue; + } + if (argument.startsWith('--env=')) { + nodeEnv = argument.slice('--env='.length); + continue; + } + if (argument === '--limit') { + limit = positiveInteger(argv[index + 1], '--limit'); + index += 1; + continue; + } + if (argument.startsWith('--limit=')) { + limit = positiveInteger(argument.slice('--limit='.length), '--limit'); + continue; + } + if (argument === '--help' || argument === '-h') { + help = true; + continue; + } + throw new Error(`Unknown argument: ${argument}`); + } + + if (!['dev', 'staging', 'prod'].includes(nodeEnv)) { + throw new Error('--env must be dev, staging, or prod.'); + } + return { dryRun, help, limit, nodeEnv }; +} + +function positiveInteger(value: string | undefined, label: string): number { + const parsed = Number(value); + if (!Number.isInteger(parsed) || parsed < 1) { + throw new Error(`${label} requires a positive integer.`); + } + return parsed; +} + +function printHelp(): void { + process.stdout.write(`Usage: + pnpm --silent --filter api competition:migrate + pnpm --silent --filter api competition:migrate -- --env staging --apply + +Options: + --dry-run Plan and report without writes. Default. + --apply Apply one transaction per Match. + --env dev | staging | prod. Default: NODE_ENV or dev. + --limit Scan at most n Matches in deterministic _id order. + +The JSON report is written to stdout; the concise human summary is written to stderr. +`); +} + +async function main(): Promise { + const options = parseCliOptions(process.argv.slice(2)); + if (options.help) { + printHelp(); + return; + } + await loadMachineEnvFile(); + process.env.NODE_ENV = options.nodeEnv; + + const app = await NestFactory.createApplicationContext(MigrationModule, { + logger: false, + }); + try { + const connectionService = app.get(ConnectionService); + const connection = await connectionService.getConnection(); + if (!connection.db) throw new Error('MongoDB connection has no db handle.'); + + const result = await migrateCompetitionDomain( + connection.db as unknown as CompetitionDomainMigrationDb, + { + dryRun: options.dryRun, + limit: options.limit, + startSession: options.dryRun + ? undefined + : async () => connection.startSession(), + }, + ); + const { summary } = result; + process.stderr.write( + `[competition-domain migration] mode=${result.mode} env=${options.nodeEnv} ` + + `db=${resolveMongoDbName(options.nodeEnv)} scanned=${summary.scanned} ` + + `ready=${summary.ready} applied=${summary.applied} ` + + `alreadyApplied=${summary.alreadyApplied} quarantined=${summary.quarantined} ` + + `failed=${summary.failed} unclassified=${summary.unclassified}\n`, + ); + process.stdout.write(`${JSON.stringify(result, null, 2)}\n`); + + if (summary.failed > 0) process.exitCode = 1; + else if (summary.quarantined > 0) process.exitCode = 2; + } finally { + await app.close().catch((error: unknown) => { + const message = error instanceof Error ? error.message : String(error); + process.stderr.write( + `[competition-domain migration] context close warning: ${message}\n`, + ); + }); + } +} + +if (require.main === module) { + void main().catch((error: unknown) => { + const message = error instanceof Error ? error.message : String(error); + process.stderr.write(`[competition-domain migration] failed: ${message}\n`); + process.stdout.write( + `${JSON.stringify({ + migrationRunId: '20260712-competition-domain', + mode: process.argv.includes('--apply') ? 'apply' : 'dry-run', + error: message, + })}\n`, + ); + process.exitCode = 1; + }); +}