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

@@ -36,6 +36,7 @@ describe('migrateCompetitionDomain', () => {
expect(startSession).not.toHaveBeenCalled();
expect(db.writeCount).toBe(0);
expect(db.docs('competition')).toHaveLength(0);
expect(db.createdIndexes).toHaveLength(0);
});
it('applies one Match atomically and converges on an already-applied replay', async () => {
@@ -181,6 +182,309 @@ describe('migrateCompetitionDomain', () => {
});
expect(db.writeCount).toBe(0);
});
it('ensures every Competition unique or partial index before the first apply write', async () => {
const match = readyMatch();
const db = new MemoryMigrationDb({
match: [match],
riotMatch: [riotArchive()],
tournamentCode: [usedTournamentCode(match)],
});
const result = await migrateCompetitionDomain(db, {
dryRun: false,
startSession: () => Promise.resolve(new FakeSession()),
});
expect(result.indexPreflight).toMatchObject({
status: 'ensured',
requiredIndexes: 10,
conflicts: [],
});
expect(result.indexPreflight.ensuredIndexes).toHaveLength(10);
expect(db.createdIndexes).toHaveLength(10);
expect(db.createdIndexes).toEqual(
expect.arrayContaining([
expect.objectContaining({
collection: 'match',
key: { competitionId: 1 },
options: expect.objectContaining({
unique: true,
partialFilterExpression: {
competitionId: { $type: 'objectId' },
},
}),
}),
expect.objectContaining({
collection: 'competition',
key: { matchId: 1 },
options: expect.objectContaining({ unique: true }),
}),
expect.objectContaining({
collection: 'competition_fact',
key: { 'evidence.riotMatchId': 1 },
options: expect.objectContaining({
unique: true,
partialFilterExpression: expect.any(Object),
}),
}),
expect.objectContaining({
collection: 'tournament_code_assignment',
key: { gameSlotId: 1 },
options: expect.objectContaining({
unique: true,
partialFilterExpression: expect.any(Object),
}),
}),
]),
);
expect(db.operations.indexOf('create-index')).toBeLessThan(
db.operations.indexOf('write'),
);
});
it('blocks apply with a machine-readable report when a required index cannot be created', async () => {
const match = readyMatch();
const db = new MemoryMigrationDb({ match: [match] });
db.indexCreationError = Object.assign(
new Error('E11000 duplicate key while building competitionId_1'),
{
code: 11000,
keyPattern: { competitionId: 1 },
keyValue: { competitionId: match._id },
},
);
const startSession = jest.fn(() => Promise.resolve(new FakeSession()));
const result = await migrateCompetitionDomain(db, {
dryRun: false,
startSession,
});
expect(result.indexPreflight).toMatchObject({
status: 'blocked',
conflicts: [
expect.objectContaining({
collection: 'match',
code: 11000,
keyValue: {
competitionId: (match._id as mongoose.Types.ObjectId).toHexString(),
},
}),
],
});
expect(result.matches).toEqual([]);
expect(result.summary.scanned).toBe(0);
expect(startSession).not.toHaveBeenCalled();
expect(db.writeCount).toBe(0);
});
it('quarantines a later Match that reuses an already accepted global Riot identity', async () => {
const firstMatch = readyMatch('KR_SHARED_MIGRATION');
const secondMatch = readyMatch('KR_SHARED_MIGRATION');
const db = new MemoryMigrationDb({
match: [firstMatch, secondMatch],
riotMatch: [riotArchive('KR_SHARED_MIGRATION')],
tournamentCode: [
usedTournamentCode(firstMatch, 'KR_SHARED_MIGRATION'),
usedTournamentCode(secondMatch, 'KR_SHARED_MIGRATION'),
],
});
const result = await migrateCompetitionDomain(db, {
dryRun: false,
startSession: () => Promise.resolve(new FakeSession()),
});
expect(result.summary).toMatchObject({ applied: 1, quarantined: 1 });
expect(result.matches).toContainEqual(
expect.objectContaining({
status: 'quarantined',
reasons: expect.arrayContaining([
expect.objectContaining({ code: 'GLOBAL_UNIQUE_INDEX_CONFLICT' }),
]),
}),
);
expect(db.docs('competition_fact')).toHaveLength(1);
expect(db.docs('competition_migration_quarantine')).toHaveLength(1);
});
it('resumes repeated limited apply runs after the durable Match checkpoint', async () => {
const firstMatch = readyMatch('KR_BATCH_1');
const secondMatch = readyMatch('KR_BATCH_2');
const db = new MemoryMigrationDb({
match: [firstMatch, secondMatch],
riotMatch: [riotArchive('KR_BATCH_1'), riotArchive('KR_BATCH_2')],
tournamentCode: [
usedTournamentCode(firstMatch, 'KR_BATCH_1'),
usedTournamentCode(secondMatch, 'KR_BATCH_2'),
],
});
const first = await migrateCompetitionDomain(db, {
dryRun: false,
limit: 1,
startSession: () => Promise.resolve(new FakeSession()),
});
const second = await migrateCompetitionDomain(db, {
dryRun: false,
limit: 1,
startSession: () => Promise.resolve(new FakeSession()),
});
expect(first.summary).toMatchObject({ scanned: 1, applied: 1 });
expect(first.resume).toMatchObject({
strategy: 'checkpoint',
hasMore: true,
completed: false,
});
expect(second.summary).toMatchObject({ scanned: 1, applied: 1 });
expect(second.matches[0].matchId).not.toBe(first.matches[0].matchId);
expect(second.resume).toMatchObject({
strategy: 'checkpoint',
startedAfterMatchId: first.matches[0].matchId,
hasMore: false,
completed: true,
});
expect(db.docs('competition')).toHaveLength(2);
expect(db.docs('competition_migration_checkpoint')).toHaveLength(1);
});
it('does not let an apply checkpoint silently narrow a later dry-run', async () => {
const firstMatch = readyMatch('KR_DRY_RUN_1');
const secondMatch = readyMatch('KR_DRY_RUN_2');
const db = new MemoryMigrationDb({
match: [firstMatch, secondMatch],
riotMatch: [riotArchive('KR_DRY_RUN_1'), riotArchive('KR_DRY_RUN_2')],
tournamentCode: [
usedTournamentCode(firstMatch, 'KR_DRY_RUN_1'),
usedTournamentCode(secondMatch, 'KR_DRY_RUN_2'),
],
});
const applied = await migrateCompetitionDomain(db, {
dryRun: false,
limit: 1,
startSession: () => Promise.resolve(new FakeSession()),
});
const dryRun = await migrateCompetitionDomain(db, {
dryRun: true,
limit: 1,
});
expect(dryRun.resume.strategy).toBe('none');
expect(dryRun.matches[0].matchId).toBe(applied.matches[0].matchId);
});
it('does not advance a limited-run checkpoint past a failed Match', async () => {
const match = readyMatch('KR_RETRY_AFTER_FAILURE');
const db = new MemoryMigrationDb({
match: [match],
riotMatch: [riotArchive('KR_RETRY_AFTER_FAILURE')],
tournamentCode: [usedTournamentCode(match, 'KR_RETRY_AFTER_FAILURE')],
});
const failed = await migrateCompetitionDomain(db, {
dryRun: false,
limit: 1,
startSession: () => Promise.resolve(undefined),
});
expect(failed.summary).toMatchObject({ scanned: 1, failed: 1 });
expect(failed.resume).toMatchObject({
strategy: 'checkpoint',
hasMore: true,
completed: false,
});
expect(db.docs('competition_migration_checkpoint')).toHaveLength(0);
const retried = await migrateCompetitionDomain(db, {
dryRun: false,
limit: 1,
startSession: () => Promise.resolve(new FakeSession()),
});
expect(db.docs('competition_migration_checkpoint')).toHaveLength(1);
expect(retried.matches[0].matchId).toBe(failed.matches[0].matchId);
expect(retried.summary).toMatchObject({ scanned: 1, applied: 1 });
});
it('durably overrides a later checkpoint before an explicit earlier retry can fail', async () => {
const retryMatch = readyMatch('KR_EXPLICIT_RETRY');
const laterMatch = readyMatch('KR_LATER_CHECKPOINT');
const explicitAfter = '000000000000000000000000';
const migrationRunId = '20260712-competition-domain';
const db = new MemoryMigrationDb({
match: [retryMatch, laterMatch],
riotMatch: [
riotArchive('KR_EXPLICIT_RETRY'),
riotArchive('KR_LATER_CHECKPOINT'),
],
tournamentCode: [
usedTournamentCode(retryMatch, 'KR_EXPLICIT_RETRY'),
usedTournamentCode(laterMatch, 'KR_LATER_CHECKPOINT'),
],
competition_migration_checkpoint: [
{
_id: migrationRunId,
migrationRunId,
lastMatchId: laterMatch._id,
status: 'running',
},
],
});
const failed = await migrateCompetitionDomain(db, {
dryRun: false,
limit: 1,
afterMatchId: explicitAfter,
startSession: () => Promise.resolve(undefined),
});
expect(failed.summary).toMatchObject({ scanned: 1, failed: 1 });
expect(
String(db.docs('competition_migration_checkpoint')[0].lastMatchId),
).toBe(explicitAfter);
const retried = await migrateCompetitionDomain(db, {
dryRun: false,
limit: 1,
startSession: () => Promise.resolve(new FakeSession()),
});
expect(retried.matches[0].matchId).toBe(failed.matches[0].matchId);
expect(retried.summary).toMatchObject({ scanned: 1, applied: 1 });
});
it('does not persist an explicit checkpoint override during dry-run', async () => {
const match = readyMatch('KR_DRY_EXPLICIT_CURSOR');
const migrationRunId = '20260712-competition-domain';
const persistedCheckpoint = objectId();
const db = new MemoryMigrationDb({
match: [match],
riotMatch: [riotArchive('KR_DRY_EXPLICIT_CURSOR')],
tournamentCode: [usedTournamentCode(match, 'KR_DRY_EXPLICIT_CURSOR')],
competition_migration_checkpoint: [
{
_id: migrationRunId,
migrationRunId,
lastMatchId: persistedCheckpoint,
status: 'running',
},
],
});
await migrateCompetitionDomain(db, {
dryRun: true,
limit: 1,
afterMatchId: '000000000000000000000000',
});
expect(
String(db.docs('competition_migration_checkpoint')[0].lastMatchId),
).toBe(persistedCheckpoint.toHexString());
expect(db.writeCount).toBe(0);
});
});
class FakeSession implements CompetitionDomainMigrationSession {
@@ -211,6 +515,13 @@ type AnyDoc = Record<string, any> & { _id: unknown };
class MemoryMigrationDb implements CompetitionDomainMigrationDb {
private readonly collections = new Map<string, AnyDoc[]>();
public writeCount = 0;
public readonly createdIndexes: Array<{
collection: string;
key: Record<string, unknown>;
options: Record<string, unknown>;
}> = [];
public readonly operations: string[] = [];
public indexCreationError?: Error;
constructor(seed: Record<string, AnyDoc[]> = {}) {
for (const [name, docs] of Object.entries(seed)) {
@@ -227,6 +538,23 @@ class MemoryMigrationDb implements CompetitionDomainMigrationDb {
collection(name: string) {
const owner = this;
return {
createIndex(
key: Record<string, unknown>,
options: Record<string, unknown>,
) {
owner.operations.push('create-index');
if (owner.indexCreationError) {
const error = owner.indexCreationError;
owner.indexCreationError = undefined;
return Promise.reject(error);
}
owner.createdIndexes.push({ collection: name, key, options });
return Promise.resolve(
typeof options.name === 'string'
? options.name
: Object.keys(key).join('_'),
);
},
find(filter: Record<string, unknown>) {
return new MemoryCursor(() =>
owner.docs(name).filter((doc) => matches(doc, filter)),
@@ -240,6 +568,7 @@ class MemoryMigrationDb implements CompetitionDomainMigrationDb {
update: Record<string, Record<string, unknown>>,
options: { upsert?: boolean } = {},
) {
owner.operations.push('write');
owner.writeCount += 1;
const docs = owner.docs(name);
let doc = docs.find((candidate) => matches(candidate, filter));
@@ -251,6 +580,7 @@ class MemoryMigrationDb implements CompetitionDomainMigrationDb {
if (!doc) return { matchedCount: 0, modifiedCount: 0 };
if (inserted) Object.assign(doc, update.$setOnInsert ?? {});
Object.assign(doc, update.$set ?? {});
for (const field of Object.keys(update.$unset ?? {})) delete doc[field];
return {
matchedCount: inserted ? 0 : 1,
modifiedCount: 1,
@@ -258,6 +588,7 @@ class MemoryMigrationDb implements CompetitionDomainMigrationDb {
};
},
async deleteOne(filter: Record<string, unknown>) {
owner.operations.push('write');
owner.writeCount += 1;
const docs = owner.docs(name);
const index = docs.findIndex((doc) => matches(doc, filter));
@@ -318,6 +649,9 @@ function matches(doc: AnyDoc, filter: Record<string, unknown>): boolean {
sameValue(actual, candidate),
);
}
if ('$gt' in expected) {
return String(actual) > String(expected.$gt);
}
}
return sameValue(actual, expected);
});
@@ -348,7 +682,7 @@ function isRecord(value: unknown): value is Record<string, any> {
return value !== null && typeof value === 'object' && !Array.isArray(value);
}
function readyMatch(): AnyDoc {
function readyMatch(riotMatchId = 'KR_MIGRATION_1'): AnyDoc {
const matchId = objectId();
const codeId = objectId();
return {
@@ -362,11 +696,11 @@ function readyMatch(): AnyDoc {
gameSchedule: [{ gameNumber: 1, teamAIndex: 1, teamBIndex: 2 }],
tournamentCodeIds: [codeId],
result: {
riotMatchIds: ['KR_MIGRATION_1'],
riotMatchIds: [riotMatchId],
games: [
{
gameNumber: 1,
riotMatchId: 'KR_MIGRATION_1',
riotMatchId,
blueTeamIndex: 1,
redTeamIndex: 2,
winnerTeamIndex: 1,
@@ -383,23 +717,26 @@ function readyMatch(): AnyDoc {
};
}
function usedTournamentCode(match = readyMatch()): AnyDoc {
function usedTournamentCode(
match = readyMatch(),
riotMatchId = 'KR_MIGRATION_1',
): AnyDoc {
return {
_id: match.tournamentCodeIds[0],
matchId: match._id,
state: 'used',
gameNumber: 1,
riotMatchId: 'KR_MIGRATION_1',
riotMatchId,
reservedAt: new Date('2026-07-01T00:30:00.000Z'),
usedAt: new Date('2026-07-01T01:00:00.000Z'),
};
}
function riotArchive(): AnyDoc {
function riotArchive(matchId = 'KR_MIGRATION_1'): AnyDoc {
return {
_id: objectId(),
matchId: 'KR_MIGRATION_1',
raw: { metadata: { matchId: 'KR_MIGRATION_1' } },
matchId,
raw: { metadata: { matchId } },
};
}
@@ -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(
@@ -31,4 +31,22 @@ describe('competition domain migration CLI', () => {
nodeEnv: 'dev',
});
});
it('accepts an explicit Match cursor for limited-run recovery', () => {
expect(
parseCliOptions([
'--apply',
'--limit=25',
'--after',
'66a000000000000000000123',
]),
).toMatchObject({
dryRun: false,
limit: 25,
afterMatchId: '66a000000000000000000123',
});
expect(() => parseCliOptions(['--after', 'not-an-object-id'])).toThrow(
'--after requires a 24-character hexadecimal Match ObjectId.',
);
});
});
@@ -15,6 +15,7 @@ export interface CompetitionDomainCliOptions {
dryRun: boolean;
help: boolean;
limit?: number;
afterMatchId?: string;
nodeEnv: string;
}
@@ -60,6 +61,7 @@ export function parseCliOptions(argv: string[]): CompetitionDomainCliOptions {
let dryRun = true;
let help = false;
let limit: number | undefined;
let afterMatchId: string | undefined;
let nodeEnv = process.env.NODE_ENV ?? 'dev';
for (let index = 0; index < argv.length; index += 1) {
@@ -95,6 +97,15 @@ export function parseCliOptions(argv: string[]): CompetitionDomainCliOptions {
limit = positiveInteger(argument.slice('--limit='.length), '--limit');
continue;
}
if (argument === '--after') {
afterMatchId = matchObjectId(argv[index + 1]);
index += 1;
continue;
}
if (argument.startsWith('--after=')) {
afterMatchId = matchObjectId(argument.slice('--after='.length));
continue;
}
if (argument === '--help' || argument === '-h') {
help = true;
continue;
@@ -105,7 +116,7 @@ export function parseCliOptions(argv: string[]): CompetitionDomainCliOptions {
if (!['dev', 'staging', 'prod'].includes(nodeEnv)) {
throw new Error('--env must be dev, staging, or prod.');
}
return { dryRun, help, limit, nodeEnv };
return { dryRun, help, limit, afterMatchId, nodeEnv };
}
function positiveInteger(value: string | undefined, label: string): number {
@@ -116,6 +127,15 @@ function positiveInteger(value: string | undefined, label: string): number {
return parsed;
}
function matchObjectId(value: string | undefined): string {
if (!value || !/^[a-f\d]{24}$/i.test(value)) {
throw new Error(
'--after requires a 24-character hexadecimal Match ObjectId.',
);
}
return value.toLowerCase();
}
function printHelp(): void {
process.stdout.write(`Usage:
pnpm --silent --filter api competition:migrate
@@ -125,7 +145,8 @@ Options:
--dry-run Plan and report without writes. Default.
--apply Apply one transaction per Match.
--env <env> dev | staging | prod. Default: NODE_ENV or dev.
--limit <n> Scan at most n Matches in deterministic _id order.
--limit <n> Scan at most n Matches. Apply resumes from a durable checkpoint.
--after <id> Override the checkpoint with a Match ObjectId cursor.
The JSON report is written to stdout; the concise human summary is written to stderr.
`);
@@ -153,6 +174,7 @@ async function main(): Promise<void> {
{
dryRun: options.dryRun,
limit: options.limit,
afterMatchId: options.afterMatchId,
startSession: options.dryRun
? undefined
: async () => connection.startSession(),
@@ -164,11 +186,15 @@ async function main(): Promise<void> {
`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`,
`failed=${summary.failed} unclassified=${summary.unclassified} ` +
`indexPreflight=${result.indexPreflight.status} ` +
`resume=${result.resume.checkpointAfterMatchId ?? 'none'} ` +
`completed=${result.resume.completed}\n`,
);
process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
if (summary.failed > 0) process.exitCode = 1;
if (result.indexPreflight.status === 'blocked') process.exitCode = 1;
else if (summary.failed > 0) process.exitCode = 1;
else if (summary.quarantined > 0) process.exitCode = 2;
} finally {
await app.close().catch((error: unknown) => {