fix: close competition cutover integrity gaps

This commit is contained in:
dahyeon committed 2026-07-12 21:22:22 +00:00
1 parent 7ea2002975
commit 683d602d63
57 files changed
+4805 -1582

No files matched your search

@@ -1,6 +1,10 @@
import { createHash } from 'node:crypto';
import mongoose from 'mongoose';
import { projectCompetition } from '../../../competition/domain/competition-projector';
import {
COMPETITION_DOMAIN_INVARIANT_INDEXES,
type CompetitionDomainInvariantIndex,
} from '../../../competition/competition.schema';
import {
planCompetitionMigration,
type CompetitionMigrationAssignment,
@@ -21,6 +25,10 @@ export interface CompetitionDomainMigrationCursor extends AsyncIterable<AnyDocum
}
export interface CompetitionDomainMigrationCollection {
createIndex(
key: mongoose.IndexDefinition,
options: mongoose.IndexOptions,
): Promise<string>;
find(
filter: Record<string, unknown>,
options?: { session?: CompetitionDomainMigrationSession },
@@ -34,6 +42,7 @@ export interface CompetitionDomainMigrationCollection {
update: {
$set?: Record<string, unknown>;
$setOnInsert?: Record<string, unknown>;
$unset?: Record<string, unknown>;
},
options?: {
session?: CompetitionDomainMigrationSession;
@@ -64,6 +73,7 @@ export interface CompetitionDomainMigrationSession {
export interface CompetitionDomainMigrationOptions {
dryRun?: boolean;
limit?: number;
afterMatchId?: string;
migrationRunId?: string;
now?: Date;
startSession?: () => Promise<CompetitionDomainMigrationSession | undefined>;
@@ -118,10 +128,37 @@ export interface CompetitionDomainMigrationSummary {
export interface CompetitionDomainMigrationResult {
migrationRunId: string;
mode: 'dry-run' | 'apply';
indexPreflight: CompetitionDomainIndexPreflight;
resume: CompetitionDomainMigrationResume;
summary: CompetitionDomainMigrationSummary;
matches: CompetitionDomainMigrationMatchResult[];
}
export interface CompetitionDomainMigrationResume {
strategy: 'none' | 'cursor' | 'checkpoint';
startedAfterMatchId?: string;
checkpointAfterMatchId?: string;
hasMore: boolean;
completed: boolean;
}
export interface CompetitionDomainIndexConflict {
collection: CompetitionDomainInvariantIndex['collection'];
indexName: string;
key: Record<string, unknown>;
code?: number;
keyPattern?: Record<string, unknown>;
keyValue?: unknown;
message: string;
}
export interface CompetitionDomainIndexPreflight {
status: 'dry-run' | 'ensured' | 'blocked';
requiredIndexes: number;
ensuredIndexes: string[];
conflicts: CompetitionDomainIndexConflict[];
}
/**
* 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.
@@ -135,9 +172,43 @@ export async function migrateCompetitionDomain(
options.migrationRunId?.trim() || DEFAULT_MIGRATION_RUN_ID;
assertOptions(options);
const matchSnapshots = await scanMatches(db, options.limit);
const resumeStart = await resolveResumeStart(
db,
migrationRunId,
options,
dryRun,
);
const indexPreflight = await ensureCompetitionDomainIndexes(db, dryRun);
if (indexPreflight.status === 'blocked') {
return {
migrationRunId,
mode: 'apply',
indexPreflight,
resume: resumeReport(resumeStart, undefined, true, false),
summary: summarize([]),
matches: [],
};
}
if (!dryRun && options.limit !== undefined && options.afterMatchId) {
await persistMigrationCheckpoint(db, {
migrationRunId,
matchId: options.afterMatchId,
completed: false,
resetMatchStatus: true,
observedAt: options.now ?? new Date(),
});
}
const scan = await scanMatches(
db,
options.limit,
resumeStart.startedAfterMatchId,
);
const matches: CompetitionDomainMigrationMatchResult[] = [];
for (const [index, scannedMatch] of matchSnapshots.entries()) {
let checkpointAfterMatchId = resumeStart.startedAfterMatchId;
let haltedOnFailure = false;
for (const [index, scannedMatch] of scan.matches.entries()) {
const result = dryRun
? await inspectMatch(db, scannedMatch, migrationRunId)
: await applyMatch(db, scannedMatch, migrationRunId, options);
@@ -146,29 +217,216 @@ export async function migrateCompetitionDomain(
index: index + 1,
matchId: result.matchId,
status: result.status,
total: matchSnapshots.length,
total: scan.matches.length,
});
if (!dryRun && options.limit !== undefined) {
if (result.status === 'failed') {
haltedOnFailure = true;
break;
}
await persistMigrationCheckpoint(db, {
migrationRunId,
matchId: result.matchId,
matchStatus: result.status,
completed: false,
observedAt: options.now ?? new Date(),
});
checkpointAfterMatchId = result.matchId;
}
}
const hasMore =
scan.hasMore || haltedOnFailure || matches.length < scan.matches.length;
const completed =
!hasMore && !matches.some(({ status }) => status === 'failed');
if (!dryRun && options.limit !== undefined && completed) {
await persistMigrationCheckpoint(db, {
migrationRunId,
matchId: checkpointAfterMatchId,
completed: true,
observedAt: options.now ?? new Date(),
});
}
return {
migrationRunId,
mode: dryRun ? 'dry-run' : 'apply',
indexPreflight,
resume: resumeReport(
resumeStart,
checkpointAfterMatchId,
hasMore,
completed,
),
summary: summarize(matches),
matches,
};
}
interface ResumeStart {
strategy: CompetitionDomainMigrationResume['strategy'];
startedAfterMatchId?: string;
}
async function resolveResumeStart(
db: CompetitionDomainMigrationDb,
migrationRunId: string,
options: CompetitionDomainMigrationOptions,
dryRun: boolean,
): Promise<ResumeStart> {
if (dryRun || options.limit === undefined) {
return {
strategy: options.afterMatchId ? 'cursor' : 'none',
...(options.afterMatchId
? { startedAfterMatchId: options.afterMatchId }
: {}),
};
}
if (options.afterMatchId) {
return {
strategy: 'cursor',
startedAfterMatchId: options.afterMatchId,
};
}
const checkpoint = await db
.collection('competition_migration_checkpoint')
.findOne({ _id: migrationRunId });
const checkpointMatchId = optionalIdString(checkpoint?.lastMatchId);
if (checkpointMatchId) assertMatchCursor(checkpointMatchId);
return {
strategy: 'checkpoint',
...(checkpointMatchId ? { startedAfterMatchId: checkpointMatchId } : {}),
};
}
function resumeReport(
start: ResumeStart,
checkpointAfterMatchId: string | undefined,
hasMore: boolean,
completed: boolean,
): CompetitionDomainMigrationResume {
return {
strategy: start.strategy,
...(start.startedAfterMatchId
? { startedAfterMatchId: start.startedAfterMatchId }
: {}),
...(checkpointAfterMatchId ? { checkpointAfterMatchId } : {}),
hasMore,
completed,
};
}
async function persistMigrationCheckpoint(
db: CompetitionDomainMigrationDb,
params: {
migrationRunId: string;
matchId?: string;
matchStatus?: CompetitionDomainMigrationMatchResult['status'];
completed: boolean;
resetMatchStatus?: boolean;
observedAt: Date;
},
): Promise<void> {
await db.collection('competition_migration_checkpoint').updateOne(
{ _id: params.migrationRunId },
{
$set: {
migrationRunId: params.migrationRunId,
status: params.completed ? 'completed' : 'running',
...(params.matchId
? { lastMatchId: persistenceId(params.matchId) }
: {}),
...(params.matchStatus ? { lastMatchStatus: params.matchStatus } : {}),
updatedAt: params.observedAt,
},
$setOnInsert: {
_id: params.migrationRunId,
createdAt: params.observedAt,
},
...(params.resetMatchStatus ? { $unset: { lastMatchStatus: 1 } } : {}),
},
{ upsert: true },
);
}
async function ensureCompetitionDomainIndexes(
db: CompetitionDomainMigrationDb,
dryRun: boolean,
): Promise<CompetitionDomainIndexPreflight> {
if (dryRun) {
return {
status: 'dry-run',
requiredIndexes: COMPETITION_DOMAIN_INVARIANT_INDEXES.length,
ensuredIndexes: [],
conflicts: [],
};
}
const ensuredIndexes: string[] = [];
const conflicts: CompetitionDomainIndexConflict[] = [];
for (const index of COMPETITION_DOMAIN_INVARIANT_INDEXES) {
try {
const createdName = await db
.collection(index.collection)
.createIndex(index.key, index.options);
ensuredIndexes.push(createdName);
} catch (error) {
conflicts.push(indexConflict(index, error));
}
}
return {
status: conflicts.length > 0 ? 'blocked' : 'ensured',
requiredIndexes: COMPETITION_DOMAIN_INVARIANT_INDEXES.length,
ensuredIndexes,
conflicts,
};
}
function indexConflict(
index: CompetitionDomainInvariantIndex,
error: unknown,
): CompetitionDomainIndexConflict {
const record = isRecord(error) ? error : {};
const code =
typeof record.code === 'number' && Number.isInteger(record.code)
? record.code
: undefined;
const keyPattern = isRecord(record.keyPattern)
? (canonicalValue(record.keyPattern) as Record<string, unknown>)
: undefined;
const keyValue =
record.keyValue === undefined ? undefined : canonicalValue(record.keyValue);
return {
collection: index.collection,
indexName: index.options.name,
key: canonicalValue(index.key) as Record<string, unknown>,
...(code === undefined ? {} : { code }),
...(keyPattern ? { keyPattern } : {}),
...(keyValue === undefined ? {} : { keyValue }),
message: error instanceof Error ? error.message : String(error),
};
}
async function scanMatches(
db: CompetitionDomainMigrationDb,
limit: number | undefined,
): Promise<AnyDocument[]> {
return readCursor(
afterMatchId: string | undefined,
): Promise<{ matches: AnyDocument[]; hasMore: boolean }> {
const scanned = await readCursor(
db
.collection('match')
.find(MATCH_SCAN_FILTER)
.find({
...MATCH_SCAN_FILTER,
...(afterMatchId ? { _id: { $gt: persistenceId(afterMatchId) } } : {}),
})
.sort({ _id: 1 })
.limit(limit ?? 0),
.limit(limit === undefined ? 0 : limit + 1),
);
if (limit === undefined) return { matches: scanned, hasMore: false };
return {
matches: scanned.slice(0, limit),
hasMore: scanned.length > limit,
};
}
async function inspectMatch(
@@ -260,6 +518,30 @@ async function applyMatch(
};
}
const uniquenessConflicts = await findReadyPlanUniquenessConflicts(
db,
plan,
session,
);
if (uniquenessConflicts.length > 0) {
await persistQuarantine(
db,
currentMatch,
uniquenessConflicts,
plan.warnings,
migrationRunId,
options.now ?? new Date(),
session,
);
await session.commitTransaction();
return {
status: 'quarantined',
matchId,
warnings: plan.warnings,
reasons: uniquenessConflicts,
};
}
await upsertReadyPlan(db, plan, session);
await verifyReadyPlan(db, plan, session);
@@ -305,6 +587,123 @@ async function applyMatch(
}
}
interface UniqueIdentityCheck {
collection: 'competition' | 'competition_fact' | 'tournament_code_assignment';
indexName: string;
filter: Record<string, unknown>;
expectedDocumentId: string;
}
async function findReadyPlanUniquenessConflicts(
db: CompetitionDomainMigrationDb,
plan: ReadyCompetitionMigrationPlan,
session: CompetitionDomainMigrationSession,
): Promise<CompetitionMigrationIssue[]> {
const checks: UniqueIdentityCheck[] = [
{
collection: 'competition',
indexName: 'matchId_1',
filter: { matchId: persistenceId(plan.competition.matchId) },
expectedDocumentId: plan.competition.id,
},
];
for (const fact of plan.facts) {
checks.push(
{
collection: 'competition_fact',
indexName: 'competitionId_1_revision_1_ordinalWithinRevision_1',
filter: {
competitionId: persistenceId(fact.competitionId),
revision: fact.revision,
ordinalWithinRevision: fact.ordinalWithinRevision,
},
expectedDocumentId: fact.id,
},
{
collection: 'competition_fact',
indexName: 'competitionId_1_commandId_1_ordinalWithinRevision_1',
filter: {
competitionId: persistenceId(fact.competitionId),
commandId: fact.commandId,
ordinalWithinRevision: fact.ordinalWithinRevision,
},
expectedDocumentId: fact.id,
},
);
if (fact.type === 'game-accepted' && fact.evidence.type === 'riot') {
checks.push({
collection: 'competition_fact',
indexName: 'evidence.riotMatchId_1',
filter: {
type: 'game-accepted',
'evidence.riotMatchId': fact.evidence.riotMatchId,
},
expectedDocumentId: fact.id,
});
}
}
for (const assignment of plan.assignments) {
if (assignment.state === 'reserved' || assignment.state === 'used') {
checks.push(
{
collection: 'tournament_code_assignment',
indexName: 'gameSlotId_1',
filter: {
gameSlotId: persistenceId(assignment.gameSlotId),
state: { $in: ['reserved', 'used'] },
},
expectedDocumentId: assignment.id,
},
{
collection: 'tournament_code_assignment',
indexName: 'tournamentCodeId_1',
filter: {
tournamentCodeId: persistenceId(assignment.tournamentCodeId),
state: { $in: ['reserved', 'used'] },
},
expectedDocumentId: assignment.id,
},
);
}
if (assignment.riotMatchId) {
checks.push({
collection: 'tournament_code_assignment',
indexName: 'riotMatchId_1',
filter: { riotMatchId: assignment.riotMatchId },
expectedDocumentId: assignment.id,
});
}
}
const conflicts: CompetitionMigrationIssue[] = [];
// Mongo sessions do not support parallel operations inside one transaction.
for (const check of checks) {
const existing = await db
.collection(check.collection)
.findOne(check.filter, { session });
if (!existing || idString(existing._id) === check.expectedDocumentId) {
continue;
}
conflicts.push({
code: 'GLOBAL_UNIQUE_INDEX_CONFLICT',
message: `Migration input conflicts with ${check.collection}.${check.indexName}.`,
details: {
collection: check.collection,
indexName: check.indexName,
key: canonicalValue(check.filter) as Record<string, unknown>,
expectedDocumentId: check.expectedDocumentId,
conflictingDocumentId: idString(existing._id),
...(existing.competitionId
? { conflictingCompetitionId: idString(existing.competitionId) }
: {}),
},
});
}
return conflicts;
}
async function hydrateLegacyMatch(
db: CompetitionDomainMigrationDb,
match: AnyDocument,
@@ -819,6 +1218,17 @@ function assertOptions(options: CompetitionDomainMigrationOptions): void {
if (options.dryRun === false && !options.startSession) {
throw new Error('Apply mode requires a transaction session factory.');
}
if (options.afterMatchId !== undefined) {
assertMatchCursor(options.afterMatchId);
}
}
function assertMatchCursor(value: string): void {
if (!/^[a-f\d]{24}$/i.test(value)) {
throw new Error(
'Competition migration afterMatchId must be a 24-character hexadecimal Match ObjectId.',
);
}
}
async function readCursor(