Harden match and tournament code concurrency

This commit is contained in:
dahyeon committed 2026-06-27 12:28:05 -07:00
1 parent 292e37aaac
commit df7dcd3a9c
9 files changed
+2339 -128

No files matched your search

@@ -0,0 +1,572 @@
import { migrateTournamentCodeUniqueIndexes } from './20260627-tournament-code-unique-indexes';
type Doc = Record<string, unknown> & { _id: string };
type FakeIndex = {
commitQuorum?: number | string;
key: Record<string, 1 | -1>;
maxTimeMS?: number;
name: string;
partialFilterExpression?: Record<string, unknown>;
unique?: boolean;
};
type Projection = Record<string, 0 | 1>;
function createDb(params: {
codes?: Doc[];
indexes?: FakeIndex[];
matches?: Doc[];
missingTournamentCodeNamespace?: boolean;
}) {
const collections = {
match: params.matches ?? [],
tournamentCode: params.codes ?? [],
};
const indexes = [...(params.indexes ?? [])];
const collectionNames: string[] = [];
let tournamentCodeNamespaceMissing =
params.missingTournamentCodeNamespace ?? false;
return {
collectionNames,
collections,
indexes,
db: {
collection(name: string) {
collectionNames.push(name);
const docs =
name === 'tournamentCode'
? collections.tournamentCode
: name === 'match'
? collections.match
: [];
return {
find(
filter: Record<string, unknown> = {},
options?: { projection?: Projection },
) {
return {
limit() {
return {
async *[Symbol.asyncIterator]() {
for (const doc of docs) {
if (!matchesFilter(doc, filter)) continue;
yield applyProjection(doc, options?.projection);
}
},
};
},
};
},
async updateMany(
filter: Record<string, unknown>,
update: {
$pull?: Record<string, unknown>;
$set?: Record<string, unknown>;
$unset?: Record<string, ''>;
},
) {
let matchedCount = 0;
let modifiedCount = 0;
for (const doc of docs) {
if (!matchesFilter(doc, filter)) continue;
matchedCount += 1;
const before = JSON.stringify(doc);
applyUpdate(doc, update);
if (JSON.stringify(doc) !== before) modifiedCount += 1;
}
return { matchedCount, modifiedCount };
},
async indexes() {
if (name === 'tournamentCode' && tournamentCodeNamespaceMissing) {
const error = new Error(
'ns does not exist: lolympus.tournamentCode',
) as Error & { code: number; codeName: string };
error.code = 26;
error.codeName = 'NamespaceNotFound';
throw error;
}
return indexes.map((index) => ({ ...index }));
},
async dropIndex(name: string) {
const index = indexes.findIndex((item) => item.name === name);
if (index >= 0) indexes.splice(index, 1);
},
async createIndex(
key: Record<string, 1 | -1>,
options: {
name: string;
partialFilterExpression?: Record<string, unknown>;
unique?: boolean;
},
) {
if (name === 'tournamentCode') {
tournamentCodeNamespaceMissing = false;
}
indexes.push({ key, ...options });
return options.name;
},
};
},
},
};
}
function matchesFilter(doc: Doc, filter: Record<string, unknown>): boolean {
const clauses = filter.$or;
if (Array.isArray(clauses)) {
return clauses.some((clause) => matchesFilter(doc, clause));
}
return Object.entries(filter).every(([key, value]) => {
if (key === '$or') return true;
return matchesValue(readPath(doc, key), value);
});
}
function matchesValue(actual: unknown, expectedValue: unknown): boolean {
if (isRecord(expectedValue)) {
if ('$exists' in expectedValue) {
const exists = actual !== undefined;
if (exists !== expectedValue.$exists) return false;
}
if ('$in' in expectedValue) {
const expected = (expectedValue.$in as unknown[]).map(String);
if (Array.isArray(actual)) {
if (!actual.some((item) => expected.includes(String(item)))) {
return false;
}
} else if (!expected.includes(String(actual))) {
return false;
}
}
if ('$ne' in expectedValue) {
if (JSON.stringify(actual) === JSON.stringify(expectedValue.$ne)) {
return false;
}
}
if ('$type' in expectedValue) {
if (expectedValue.$type === 'string' && typeof actual !== 'string') {
return false;
}
}
return true;
}
return actual === expectedValue;
}
function applyUpdate(
doc: Doc,
update: {
$pull?: Record<string, unknown>;
$set?: Record<string, unknown>;
$unset?: Record<string, ''>;
},
) {
Object.assign(doc, update.$set ?? {});
for (const key of Object.keys(update.$unset ?? {})) {
delete doc[key];
}
for (const [key, pull] of Object.entries(update.$pull ?? {})) {
const current = doc[key];
if (!Array.isArray(current)) continue;
if (!isRecord(pull) || !('$in' in pull)) continue;
const pulled = (pull.$in as unknown[]).map(String);
doc[key] = current.filter((item) => !pulled.includes(String(item)));
}
}
function applyProjection(doc: Doc, projection?: Projection): Doc {
if (!projection) return doc;
const projected: Doc = { _id: doc._id };
for (const [key, value] of Object.entries(projection)) {
if (value !== 1 || key === '_id') continue;
const actual = readPath(doc, key);
if (actual !== undefined) projected[key] = actual;
}
return projected;
}
function readPath(doc: Record<string, unknown>, path: string): unknown {
const parts = path.split('.');
let current: unknown = doc;
for (const part of parts) {
if (Array.isArray(current) && /^\d+$/.test(part)) {
current = current[Number(part)];
continue;
}
if (!isRecord(current)) return undefined;
current = current[part];
}
return current;
}
function isRecord(value: unknown): value is Record<string, unknown> {
return Boolean(value && typeof value === 'object' && !Array.isArray(value));
}
describe('migrateTournamentCodeUniqueIndexes', () => {
it('dry-runs duplicate cleanup without mutating documents or indexes', async () => {
const { db, collectionNames, collections, indexes } = createDb({
codes: [
{
_id: 'code-1',
code: 'A',
matchId: 'match-1',
gameNumber: 1,
reservedAt: new Date('2026-06-01T00:00:00.000Z'),
state: 'reserved',
},
{
_id: 'code-2',
code: 'B',
matchId: 'match-1',
gameNumber: 1,
reservedAt: new Date('2026-06-02T00:00:00.000Z'),
state: 'reserved',
},
{
_id: 'code-3',
code: 'C',
riotMatchId: 'KR_1',
state: 'released',
},
{
_id: 'code-4',
code: 'D',
riotMatchId: 'KR_1',
state: 'used',
},
{
_id: 'code-5',
code: 'E',
riotMatchId: ' ',
state: 'reserved',
},
],
indexes: [{ key: { riotMatchId: 1 }, name: 'riotMatchId_1' }],
matches: [{ _id: 'match-1', tournamentCodeIds: ['code-1', 'code-2'] }],
});
const beforeCodes = JSON.stringify(collections.tournamentCode);
const beforeIndexes = JSON.stringify(indexes);
const progressPhases: string[] = [];
const result = await migrateTournamentCodeUniqueIndexes(db, {
dryRun: true,
onProgress: (progress) => progressPhases.push(progress.phase),
});
expect(result.stats).toMatchObject({
blankRiotMatchIdsToUnset: 1,
blankRiotMatchIdsUnset: 0,
duplicateCodesReleased: 0,
duplicateCodesToRelease: 2,
duplicateGameNumberGroups: 1,
duplicateRiotMatchGroups: 1,
indexesCreated: 0,
indexesDropped: 0,
scannedCodes: 5,
scannedMatches: 1,
});
expect(result.sampleDuplicateGroups).toHaveLength(2);
expect(progressPhases).toEqual(
expect.arrayContaining(['scanMatches', 'scanTournamentCodes']),
);
expect(collectionNames).toContain('tournamentCode');
expect(collectionNames).not.toContain('tournament_code');
expect(JSON.stringify(collections.tournamentCode)).toBe(beforeCodes);
expect(JSON.stringify(indexes)).toBe(beforeIndexes);
});
it('releases duplicate losers, pulls them from matches, and replaces old indexes', async () => {
const now = new Date('2026-06-27T00:00:00.000Z');
const { db, collections, indexes } = createDb({
codes: [
{
_id: 'code-1',
code: 'A',
matchId: 'match-1',
gameNumber: 1,
reservedAt: new Date('2026-06-01T00:00:00.000Z'),
state: 'reserved',
},
{
_id: 'code-2',
code: 'B',
matchId: 'match-1',
gameNumber: 1,
reservedAt: new Date('2026-06-02T00:00:00.000Z'),
state: 'reserved',
},
{
_id: 'code-3',
code: 'C',
riotMatchId: 'KR_1',
state: 'used',
},
{
_id: 'code-4',
code: 'D',
riotMatchId: 'KR_1',
state: 'released',
},
{
_id: 'code-5',
code: 'E',
riotMatchId: '',
state: 'reserved',
},
],
indexes: [
{ key: { matchId: 1, gameNumber: 1 }, name: 'matchId_1_gameNumber_1' },
{
key: { matchId: 1, bracketMatchId: 1 },
name: 'matchId_1_bracketMatchId_1',
},
{ key: { riotMatchId: 1 }, name: 'riotMatchId_1' },
],
matches: [{ _id: 'match-1', tournamentCodeIds: ['code-1', 'code-4'] }],
});
const result = await migrateTournamentCodeUniqueIndexes(db, {
dryRun: false,
now,
});
expect(result.stats).toMatchObject({
blankRiotMatchIdsToUnset: 1,
blankRiotMatchIdsUnset: 1,
duplicateCodesReleased: 2,
duplicateCodesToRelease: 2,
indexesCreated: 3,
indexesDropped: 3,
matchesUpdated: 1,
});
expect(collections.tournamentCode.find((code) => code._id === 'code-2')).toMatchObject({
code: 'B',
releasedAt: now,
state: 'released',
});
expect(collections.tournamentCode.find((code) => code._id === 'code-2')).not.toHaveProperty(
'matchId',
);
expect(collections.tournamentCode.find((code) => code._id === 'code-4')).not.toHaveProperty(
'riotMatchId',
);
expect(collections.tournamentCode.find((code) => code._id === 'code-5')).not.toHaveProperty(
'riotMatchId',
);
expect(collections.match[0].tournamentCodeIds).toEqual(['code-1']);
expect(indexes).toEqual(
expect.arrayContaining([
expect.objectContaining({
key: { matchId: 1, gameNumber: 1 },
name: 'matchId_1_gameNumber_1',
partialFilterExpression: expect.objectContaining({
state: { $in: ['reserved', 'used'] },
}),
unique: true,
}),
expect.objectContaining({
key: { matchId: 1, bracketMatchId: 1 },
name: 'matchId_1_bracketMatchId_1',
unique: true,
}),
expect.objectContaining({
key: { riotMatchId: 1 },
name: 'riotMatchId_1',
partialFilterExpression: { riotMatchId: { $type: 'string' } },
unique: true,
}),
]),
);
});
it('creates indexes when the tournament code collection does not exist yet', async () => {
const { db, indexes } = createDb({
missingTournamentCodeNamespace: true,
});
const progress: string[] = [];
const result = await migrateTournamentCodeUniqueIndexes(db, {
dryRun: false,
indexCommitQuorum: 1,
indexMaxTimeMS: 60_000,
onProgress: (event) =>
progress.push(`${event.action ?? ''}:${event.indexName ?? ''}`),
});
expect(result.stats).toMatchObject({
duplicateCodesReleased: 0,
indexesAlreadyCorrect: 0,
indexesCreated: 3,
indexesDropped: 0,
scannedCodes: 0,
scannedMatches: 0,
});
expect(indexes).toEqual(
expect.arrayContaining([
expect.objectContaining({
commitQuorum: 1,
key: { matchId: 1, gameNumber: 1 },
maxTimeMS: 60_000,
name: 'matchId_1_gameNumber_1',
unique: true,
}),
expect.objectContaining({
key: { matchId: 1, bracketMatchId: 1 },
name: 'matchId_1_bracketMatchId_1',
unique: true,
}),
expect.objectContaining({
key: { riotMatchId: 1 },
name: 'riotMatchId_1',
unique: true,
}),
]),
);
expect(progress).toEqual(
expect.arrayContaining([
'create:matchId_1_gameNumber_1',
'created:matchId_1_gameNumber_1',
]),
);
});
it('refuses to release used duplicate losers by default', async () => {
const { db, collections } = createDb({
codes: [
{
_id: 'code-1',
matchId: 'match-1',
gameNumber: 1,
state: 'used',
usedAt: new Date('2026-06-01T00:00:00.000Z'),
},
{
_id: 'code-2',
matchId: 'match-1',
gameNumber: 1,
state: 'used',
usedAt: new Date('2026-06-02T00:00:00.000Z'),
},
],
matches: [{ _id: 'match-1', tournamentCodeIds: ['code-1', 'code-2'] }],
});
await expect(
migrateTournamentCodeUniqueIndexes(db, { dryRun: false }),
).rejects.toThrow('Refusing to release 1 used duplicate tournament codes');
expect(collections.tournamentCode[0]).toMatchObject({
matchId: 'match-1',
state: 'used',
});
});
it('keeps the match-referenced slot code before state priority', async () => {
const { db, collections } = createDb({
codes: [
{
_id: 'code-1',
code: 'USED-NOT-REFERENCED',
matchId: 'match-1',
gameNumber: 1,
state: 'used',
usedAt: new Date('2026-06-02T00:00:00.000Z'),
},
{
_id: 'code-2',
code: 'RESERVED-REFERENCED',
matchId: 'match-1',
gameNumber: 1,
state: 'reserved',
reservedAt: new Date('2026-06-01T00:00:00.000Z'),
},
],
matches: [{ _id: 'match-1', tournamentCodeIds: ['code-2'] }],
});
const beforeCodes = JSON.stringify(collections.tournamentCode);
const beforeMatches = JSON.stringify(collections.match);
await expect(
migrateTournamentCodeUniqueIndexes(db, { dryRun: false }),
).rejects.toThrow('Refusing to release 1 used duplicate tournament codes');
expect(JSON.stringify(collections.tournamentCode)).toBe(beforeCodes);
expect(JSON.stringify(collections.match)).toBe(beforeMatches);
});
it('unsets blank riot match ids without treating them as duplicate releases', async () => {
const { db, collections } = createDb({
codes: [
{ _id: 'code-1', riotMatchId: '', state: 'reserved' },
{ _id: 'code-2', riotMatchId: ' ', state: 'available' },
],
});
const result = await migrateTournamentCodeUniqueIndexes(db, {
dryRun: false,
createIndexes: false,
});
expect(result.stats).toMatchObject({
blankRiotMatchIdsToUnset: 2,
blankRiotMatchIdsUnset: 2,
duplicateCodesReleased: 0,
duplicateCodesToRelease: 0,
duplicateRiotMatchGroups: 0,
});
expect(collections.tournamentCode[0]).toMatchObject({
_id: 'code-1',
state: 'reserved',
});
expect(collections.tournamentCode[0]).not.toHaveProperty('riotMatchId');
expect(collections.tournamentCode[1]).not.toHaveProperty('riotMatchId');
});
it('allows used duplicate cleanup only when explicitly requested', async () => {
const now = new Date('2026-06-27T00:00:00.000Z');
const { db, collections } = createDb({
codes: [
{
_id: 'code-1',
matchId: 'match-1',
gameNumber: 1,
state: 'used',
usedAt: new Date('2026-06-01T00:00:00.000Z'),
},
{
_id: 'code-2',
matchId: 'match-1',
gameNumber: 1,
state: 'used',
usedAt: new Date('2026-06-02T00:00:00.000Z'),
},
],
matches: [{ _id: 'match-1', tournamentCodeIds: ['code-1', 'code-2'] }],
});
const result = await migrateTournamentCodeUniqueIndexes(db, {
allowUsedDuplicateRelease: true,
dryRun: false,
now,
});
expect(result.stats).toMatchObject({
duplicateCodesReleased: 1,
unsafeUsedDuplicateCodes: 1,
unsafeUsedDuplicateGroups: 1,
});
expect(collections.tournamentCode[0]).toMatchObject({
releasedAt: now,
state: 'released',
});
expect(collections.tournamentCode[0]).not.toHaveProperty('usedAt');
expect(collections.match[0].tournamentCodeIds).toEqual(['code-2']);
});
});
@@ -0,0 +1,757 @@
type TournamentCodeState =
| 'available'
| 'reserved'
| 'used'
| 'released'
| 'expired'
| 'voided'
| string;
type AnyDoc = Record<string, unknown> & { _id: unknown };
type IndexKey = Record<string, 1 | -1>;
type PartialFilterExpression = Record<string, unknown>;
type Projection = Record<string, 0 | 1>;
interface MigrationCursor {
limit(limit: number): AsyncIterable<AnyDoc>;
}
interface MigrationIndex {
key: IndexKey;
name: string;
partialFilterExpression?: PartialFilterExpression;
unique?: boolean;
}
interface MigrationCollection {
find(
filter: Record<string, unknown>,
options?: { projection?: Projection },
): MigrationCursor;
updateMany(
filter: Record<string, unknown>,
update: {
$pull?: Record<string, unknown>;
$set?: Record<string, unknown>;
$unset?: Record<string, ''>;
},
options?: { ordered?: boolean },
): Promise<{ matchedCount?: number; modifiedCount?: number } | unknown>;
indexes?(): Promise<MigrationIndex[]>;
dropIndex?(name: string): Promise<unknown>;
createIndex?(
key: IndexKey,
options: {
commitQuorum?: number | string;
maxTimeMS?: number;
name: string;
partialFilterExpression?: PartialFilterExpression;
unique?: boolean;
},
): Promise<string>;
}
interface MigrationDb {
collection(name: string): MigrationCollection;
}
interface TournamentCodeDoc extends AnyDoc {
bracketMatchId?: unknown;
code?: unknown;
createdAt?: unknown;
gameNumber?: unknown;
matchId?: unknown;
reservedAt?: unknown;
riotMatchId?: unknown;
state?: TournamentCodeState;
updatedAt?: unknown;
uploadedAt?: unknown;
usedAt?: unknown;
}
interface MatchDoc extends AnyDoc {
tournamentCodeIds?: unknown;
}
interface DesiredIndex {
key: IndexKey;
options: {
name: string;
partialFilterExpression?: PartialFilterExpression;
unique?: boolean;
};
}
interface DuplicateGroup {
codeDocs: TournamentCodeDoc[];
key: string;
kind: TournamentCodeDuplicateKind;
}
interface ReleasePlanEntry {
code: TournamentCodeDoc;
reasons: string[];
}
export type TournamentCodeDuplicateKind =
| 'gameNumber'
| 'bracketMatchId'
| 'riotMatchId';
export interface TournamentCodeDuplicateSummary {
bracketMatchId?: string;
code?: string;
gameNumber?: string;
id: string;
matchId?: string;
riotMatchId?: string;
state?: string;
}
export interface TournamentCodeDuplicateGroupSummary {
keeper: TournamentCodeDuplicateSummary;
key: string;
kind: TournamentCodeDuplicateKind;
losers: TournamentCodeDuplicateSummary[];
}
export interface TournamentCodeUniqueIndexMigrationOptions {
allowUsedDuplicateRelease?: boolean;
createIndexes?: boolean;
dryRun?: boolean;
duplicateSampleLimit?: number;
indexCommitQuorum?: number | string;
indexMaxTimeMS?: number;
now?: Date;
onProgress?: (progress: TournamentCodeUniqueIndexMigrationProgress) => void;
progressInterval?: number;
}
export interface TournamentCodeUniqueIndexMigrationStats {
blankRiotMatchIdsToUnset: number;
blankRiotMatchIdsUnset: number;
duplicateBracketMatchGroups: number;
duplicateCodesReleased: number;
duplicateCodesToRelease: number;
duplicateGameNumberGroups: number;
duplicateRiotMatchGroups: number;
indexesAlreadyCorrect: number;
indexesCreated: number;
indexesDropped: number;
matchesUpdated: number;
scannedCodes: number;
scannedMatches: number;
unsafeUsedDuplicateCodes: number;
unsafeUsedDuplicateGroups: number;
}
export interface TournamentCodeUniqueIndexMigrationResult {
sampleDuplicateGroups: TournamentCodeDuplicateGroupSummary[];
stats: TournamentCodeUniqueIndexMigrationStats;
}
export interface TournamentCodeUniqueIndexMigrationProgress {
action?: 'alreadyCorrect' | 'create' | 'created' | 'drop' | 'dropped' | 'list';
phase:
| 'scanMatches'
| 'scanTournamentCodes'
| 'cleanupBlankRiotMatchIds'
| 'cleanupDuplicateCodes'
| 'ensureIndexes';
scanned?: number;
indexName?: string;
total?: number;
}
const ACTIVE_CODE_STATES = new Set(['reserved', 'used']);
const MATCH_SCAN_FILTER = { 'tournamentCodeIds.0': { $exists: true } };
const MATCH_SCAN_PROJECTION: Projection = { _id: 1, tournamentCodeIds: 1 };
const TOURNAMENT_CODE_SCAN_FILTER = {
$or: [
{ state: { $in: ['reserved', 'used'] }, matchId: { $exists: true } },
{ riotMatchId: { $type: 'string' } },
],
};
const TOURNAMENT_CODE_SCAN_PROJECTION: Projection = {
_id: 1,
bracketMatchId: 1,
code: 1,
createdAt: 1,
gameNumber: 1,
matchId: 1,
reservedAt: 1,
riotMatchId: 1,
state: 1,
updatedAt: 1,
uploadedAt: 1,
usedAt: 1,
};
const DESIRED_TOURNAMENT_CODE_INDEXES: DesiredIndex[] = [
{
key: { matchId: 1, gameNumber: 1 },
options: {
name: 'matchId_1_gameNumber_1',
unique: true,
partialFilterExpression: {
matchId: { $exists: true },
gameNumber: { $exists: true },
state: { $in: ['reserved', 'used'] },
},
},
},
{
key: { matchId: 1, bracketMatchId: 1 },
options: {
name: 'matchId_1_bracketMatchId_1',
unique: true,
partialFilterExpression: {
matchId: { $exists: true },
bracketMatchId: { $exists: true },
state: { $in: ['reserved', 'used'] },
},
},
},
{
key: { riotMatchId: 1 },
options: {
name: 'riotMatchId_1',
unique: true,
partialFilterExpression: { riotMatchId: { $type: 'string' } },
},
},
];
export async function migrateTournamentCodeUniqueIndexes(
db: MigrationDb,
options: TournamentCodeUniqueIndexMigrationOptions = {},
): Promise<TournamentCodeUniqueIndexMigrationResult> {
const dryRun = options.dryRun ?? true;
const now = options.now ?? new Date();
const tournamentCodeCollection = db.collection('tournamentCode');
const matchCollection = db.collection('match');
const matchScan = await readReferencedTournamentCodeIds(
matchCollection,
options,
);
const codeDocs = await readTournamentCodes(tournamentCodeCollection, options);
const groups = findDuplicateGroups(codeDocs, matchScan.referencedCodeIds);
const releasePlan = buildReleasePlan(groups, matchScan.referencedCodeIds);
const blankRiotMatchCodeIds = codeDocs
.filter(hasBlankRiotMatchId)
.map((code) => code._id);
const unsafePlanEntries = releasePlan.filter(
(entry) => entry.code.state === 'used',
);
const unsafeGroupCount = groups.filter((group) => {
const keeper = chooseKeeper(group, matchScan.referencedCodeIds);
const keeperId = stringifyId(keeper._id);
return group.codeDocs.some(
(code) => stringifyId(code._id) !== keeperId && code.state === 'used',
);
}).length;
const stats: TournamentCodeUniqueIndexMigrationStats = {
blankRiotMatchIdsToUnset: blankRiotMatchCodeIds.length,
blankRiotMatchIdsUnset: 0,
duplicateBracketMatchGroups: groups.filter(
(group) => group.kind === 'bracketMatchId',
).length,
duplicateCodesReleased: 0,
duplicateCodesToRelease: releasePlan.length,
duplicateGameNumberGroups: groups.filter(
(group) => group.kind === 'gameNumber',
).length,
duplicateRiotMatchGroups: groups.filter(
(group) => group.kind === 'riotMatchId',
).length,
indexesAlreadyCorrect: 0,
indexesCreated: 0,
indexesDropped: 0,
matchesUpdated: 0,
scannedCodes: codeDocs.length,
scannedMatches: matchScan.scannedMatches,
unsafeUsedDuplicateCodes: unsafePlanEntries.length,
unsafeUsedDuplicateGroups: unsafeGroupCount,
};
if (
!dryRun &&
unsafePlanEntries.length > 0 &&
options.allowUsedDuplicateRelease !== true
) {
throw new Error(
`Refusing to release ${unsafePlanEntries.length} used duplicate tournament codes. ` +
'Review the duplicate groups manually or re-run with --allow-used-duplicate-release.',
);
}
if (!dryRun) {
if (blankRiotMatchCodeIds.length > 0) {
emitProgress(options, 'cleanupBlankRiotMatchIds', {
total: blankRiotMatchCodeIds.length,
});
const result = await tournamentCodeCollection.updateMany(
{ _id: { $in: blankRiotMatchCodeIds } },
{ $unset: { riotMatchId: '' } },
);
stats.blankRiotMatchIdsUnset = readModifiedCount(result);
}
if (releasePlan.length > 0) {
const releaseIds = releasePlan.map((entry) => entry.code._id);
emitProgress(options, 'cleanupDuplicateCodes', {
total: releaseIds.length,
});
const releaseResult = await tournamentCodeCollection.updateMany(
{ _id: { $in: releaseIds } },
{
$set: { releasedAt: now, state: 'released' },
$unset: {
bracketMatchId: '',
gameNumber: '',
matchId: '',
reservedAt: '',
riotMatchId: '',
usedAt: '',
},
},
);
stats.duplicateCodesReleased = readModifiedCount(releaseResult);
const matchResult = await matchCollection.updateMany(
{ tournamentCodeIds: { $in: releaseIds } },
{ $pull: { tournamentCodeIds: { $in: releaseIds } } },
);
stats.matchesUpdated = readModifiedCount(matchResult);
}
if (options.createIndexes ?? true) {
emitProgress(options, 'ensureIndexes');
const indexStats = await ensureTournamentCodeUniqueIndexes(
tournamentCodeCollection,
options,
);
stats.indexesAlreadyCorrect = indexStats.indexesAlreadyCorrect;
stats.indexesCreated = indexStats.indexesCreated;
stats.indexesDropped = indexStats.indexesDropped;
}
}
return {
sampleDuplicateGroups: summarizeGroups(
groups,
matchScan.referencedCodeIds,
options.duplicateSampleLimit ?? 20,
),
stats,
};
}
async function readTournamentCodes(
collection: MigrationCollection,
options: TournamentCodeUniqueIndexMigrationOptions,
): Promise<TournamentCodeDoc[]> {
const docs: TournamentCodeDoc[] = [];
for await (const doc of collection
.find(TOURNAMENT_CODE_SCAN_FILTER, {
projection: TOURNAMENT_CODE_SCAN_PROJECTION,
})
.limit(0)) {
docs.push(doc as TournamentCodeDoc);
emitScanProgress(options, 'scanTournamentCodes', docs.length);
}
emitProgress(options, 'scanTournamentCodes', { scanned: docs.length });
return docs;
}
async function readReferencedTournamentCodeIds(
collection: MigrationCollection,
options: TournamentCodeUniqueIndexMigrationOptions,
): Promise<{ referencedCodeIds: Set<string>; scannedMatches: number }> {
const referencedCodeIds = new Set<string>();
let scannedMatches = 0;
for await (const doc of collection
.find(MATCH_SCAN_FILTER, { projection: MATCH_SCAN_PROJECTION })
.limit(0)) {
scannedMatches += 1;
emitScanProgress(options, 'scanMatches', scannedMatches);
const ids = (doc as MatchDoc).tournamentCodeIds;
if (!Array.isArray(ids)) continue;
for (const id of ids) {
const stringId = stringifyId(id);
if (stringId) referencedCodeIds.add(stringId);
}
}
emitProgress(options, 'scanMatches', { scanned: scannedMatches });
return { referencedCodeIds, scannedMatches };
}
function emitScanProgress(
options: TournamentCodeUniqueIndexMigrationOptions,
phase: TournamentCodeUniqueIndexMigrationProgress['phase'],
scanned: number,
) {
const interval = options.progressInterval ?? 5_000;
if (interval < 1 || scanned % interval !== 0) return;
emitProgress(options, phase, { scanned });
}
function emitProgress(
options: TournamentCodeUniqueIndexMigrationOptions,
phase: TournamentCodeUniqueIndexMigrationProgress['phase'],
values: Omit<TournamentCodeUniqueIndexMigrationProgress, 'phase'> = {},
) {
options.onProgress?.({ phase, ...values });
}
function findDuplicateGroups(
docs: TournamentCodeDoc[],
referencedCodeIds: Set<string>,
): DuplicateGroup[] {
return [
...duplicateGroupsFor(docs, referencedCodeIds, 'gameNumber'),
...duplicateGroupsFor(docs, referencedCodeIds, 'bracketMatchId'),
...duplicateGroupsFor(docs, referencedCodeIds, 'riotMatchId'),
];
}
function duplicateGroupsFor(
docs: TournamentCodeDoc[],
referencedCodeIds: Set<string>,
kind: TournamentCodeDuplicateKind,
): DuplicateGroup[] {
const groups = new Map<string, TournamentCodeDoc[]>();
for (const doc of docs) {
const key = duplicateKey(doc, kind);
if (!key) continue;
const group = groups.get(key) ?? [];
group.push(doc);
groups.set(key, group);
}
return [...groups.entries()]
.filter(([, groupDocs]) => groupDocs.length > 1)
.map(([key, groupDocs]) => ({
codeDocs: sortCodesByKeeperPriority(groupDocs, referencedCodeIds, kind),
key,
kind,
}));
}
function duplicateKey(
doc: TournamentCodeDoc,
kind: TournamentCodeDuplicateKind,
): string | null {
if (kind === 'riotMatchId') {
if (typeof doc.riotMatchId !== 'string') return null;
if (doc.riotMatchId.trim() === '') return null;
return `riotMatchId:${doc.riotMatchId}`;
}
if (!ACTIVE_CODE_STATES.has(String(doc.state))) return null;
if (!hasField(doc, 'matchId')) return null;
if (kind === 'gameNumber') {
if (!hasField(doc, 'gameNumber')) return null;
return `matchId:${stringifyKeyPart(doc.matchId)}:gameNumber:${stringifyKeyPart(
doc.gameNumber,
)}`;
}
if (!hasField(doc, 'bracketMatchId')) return null;
return `matchId:${stringifyKeyPart(
doc.matchId,
)}:bracketMatchId:${stringifyKeyPart(doc.bracketMatchId)}`;
}
function buildReleasePlan(
groups: DuplicateGroup[],
referencedCodeIds: Set<string>,
): ReleasePlanEntry[] {
const byCodeId = new Map<string, ReleasePlanEntry>();
for (const group of groups) {
const keeper = chooseKeeper(group, referencedCodeIds);
const keeperId = stringifyId(keeper._id);
for (const code of group.codeDocs) {
const codeId = stringifyId(code._id);
if (!codeId || codeId === keeperId) continue;
const entry = byCodeId.get(codeId) ?? { code, reasons: [] };
entry.reasons.push(`${group.kind}:${group.key}`);
byCodeId.set(codeId, entry);
}
}
return [...byCodeId.values()];
}
function summarizeGroups(
groups: DuplicateGroup[],
referencedCodeIds: Set<string>,
limit: number,
): TournamentCodeDuplicateGroupSummary[] {
return groups.slice(0, limit).map((group) => {
const keeper = chooseKeeper(group, referencedCodeIds);
const keeperId = stringifyId(keeper._id);
return {
keeper: summarizeCode(keeper),
key: group.key,
kind: group.kind,
losers: group.codeDocs
.filter((code) => stringifyId(code._id) !== keeperId)
.map(summarizeCode),
};
});
}
function summarizeCode(doc: TournamentCodeDoc): TournamentCodeDuplicateSummary {
return {
bracketMatchId:
doc.bracketMatchId === undefined ? undefined : String(doc.bracketMatchId),
code: doc.code === undefined ? undefined : String(doc.code),
gameNumber: doc.gameNumber === undefined ? undefined : String(doc.gameNumber),
id: stringifyId(doc._id) ?? '',
matchId: doc.matchId === undefined ? undefined : stringifyId(doc.matchId),
riotMatchId:
doc.riotMatchId === undefined ? undefined : String(doc.riotMatchId),
state: doc.state === undefined ? undefined : String(doc.state),
};
}
function chooseKeeper(
group: DuplicateGroup,
referencedCodeIds: Set<string>,
): TournamentCodeDoc {
return sortCodesByKeeperPriority(
group.codeDocs,
referencedCodeIds,
group.kind,
)[0];
}
function sortCodesByKeeperPriority(
docs: TournamentCodeDoc[],
referencedCodeIds: Set<string>,
kind: TournamentCodeDuplicateKind,
): TournamentCodeDoc[] {
return [...docs].sort((left, right) =>
compareCodePriority(left, right, referencedCodeIds, kind),
);
}
function compareCodePriority(
left: TournamentCodeDoc,
right: TournamentCodeDoc,
referencedCodeIds: Set<string>,
kind: TournamentCodeDuplicateKind,
): number {
if (kind !== 'riotMatchId') {
const leftReferenced = referencedCodeIds.has(stringifyId(left._id) ?? '');
const rightReferenced = referencedCodeIds.has(stringifyId(right._id) ?? '');
if (leftReferenced !== rightReferenced) return leftReferenced ? -1 : 1;
}
const leftStateRank = stateRank(left.state);
const rightStateRank = stateRank(right.state);
if (leftStateRank !== rightStateRank) return leftStateRank - rightStateRank;
if (kind === 'riotMatchId') {
const leftReferenced = referencedCodeIds.has(stringifyId(left._id) ?? '');
const rightReferenced = referencedCodeIds.has(stringifyId(right._id) ?? '');
if (leftReferenced !== rightReferenced) return leftReferenced ? -1 : 1;
}
const leftHasRiotMatch = hasNonBlankRiotMatchId(left);
const rightHasRiotMatch = hasNonBlankRiotMatchId(right);
if (leftHasRiotMatch !== rightHasRiotMatch) {
return leftHasRiotMatch ? -1 : 1;
}
const leftDate = latestTimestamp(left);
const rightDate = latestTimestamp(right);
if (leftDate !== rightDate) return rightDate - leftDate;
return (stringifyId(left._id) ?? '').localeCompare(stringifyId(right._id) ?? '');
}
function stateRank(state: unknown): number {
if (state === 'used') return 0;
if (state === 'reserved') return 1;
if (state === 'available') return 2;
if (state === 'released') return 3;
if (state === 'expired') return 4;
if (state === 'voided') return 5;
return 10;
}
function latestTimestamp(doc: TournamentCodeDoc): number {
return Math.max(
toTimestamp(doc.usedAt),
toTimestamp(doc.reservedAt),
toTimestamp(doc.updatedAt),
toTimestamp(doc.createdAt),
toTimestamp(doc.uploadedAt),
0,
);
}
function toTimestamp(value: unknown): number {
if (value instanceof Date) return value.getTime();
if (typeof value === 'number') return value;
if (typeof value !== 'string') return 0;
const parsed = Date.parse(value);
return Number.isNaN(parsed) ? 0 : parsed;
}
function hasBlankRiotMatchId(doc: TournamentCodeDoc): boolean {
return typeof doc.riotMatchId === 'string' && doc.riotMatchId.trim() === '';
}
function hasNonBlankRiotMatchId(doc: TournamentCodeDoc): boolean {
return typeof doc.riotMatchId === 'string' && doc.riotMatchId.trim() !== '';
}
async function ensureTournamentCodeUniqueIndexes(
collection: MigrationCollection,
options: TournamentCodeUniqueIndexMigrationOptions,
): Promise<{
indexesAlreadyCorrect: number;
indexesCreated: number;
indexesDropped: number;
}> {
if (!collection.indexes || !collection.dropIndex || !collection.createIndex) {
throw new Error('Migration collection does not support index operations.');
}
emitProgress(options, 'ensureIndexes', { action: 'list' });
let indexes = await listCollectionIndexes(collection);
let indexesAlreadyCorrect = 0;
let indexesCreated = 0;
let indexesDropped = 0;
for (const desired of DESIRED_TOURNAMENT_CODE_INDEXES) {
const matchingIndexes = indexes.filter(
(index) =>
index.name === desired.options.name ||
sameObject(index.key, desired.key),
);
const correctIndex = matchingIndexes.find((index) =>
sameIndex(index, desired),
);
if (correctIndex) {
emitProgress(options, 'ensureIndexes', {
action: 'alreadyCorrect',
indexName: desired.options.name,
});
indexesAlreadyCorrect += 1;
continue;
}
for (const index of matchingIndexes) {
if (index.name === '_id_') continue;
emitProgress(options, 'ensureIndexes', {
action: 'drop',
indexName: index.name,
});
await collection.dropIndex(index.name);
emitProgress(options, 'ensureIndexes', {
action: 'dropped',
indexName: index.name,
});
indexesDropped += 1;
}
emitProgress(options, 'ensureIndexes', {
action: 'create',
indexName: desired.options.name,
});
await collection.createIndex(desired.key, {
...desired.options,
...(options.indexCommitQuorum !== undefined
? { commitQuorum: options.indexCommitQuorum }
: {}),
...(options.indexMaxTimeMS !== undefined
? { maxTimeMS: options.indexMaxTimeMS }
: {}),
});
emitProgress(options, 'ensureIndexes', {
action: 'created',
indexName: desired.options.name,
});
indexesCreated += 1;
emitProgress(options, 'ensureIndexes', { action: 'list' });
indexes = await listCollectionIndexes(collection);
}
return { indexesAlreadyCorrect, indexesCreated, indexesDropped };
}
async function listCollectionIndexes(
collection: MigrationCollection,
): Promise<MigrationIndex[]> {
if (!collection.indexes) {
throw new Error('Migration collection does not support index operations.');
}
try {
return await collection.indexes();
} catch (error) {
if (isNamespaceNotFoundError(error)) return [];
throw error;
}
}
function isNamespaceNotFoundError(error: unknown): boolean {
const candidate = error as {
code?: number;
codeName?: string;
message?: string;
};
return Boolean(
candidate?.code === 26 ||
candidate?.codeName === 'NamespaceNotFound' ||
candidate?.message?.includes('ns does not exist'),
);
}
function sameIndex(index: MigrationIndex, desired: DesiredIndex): boolean {
return (
sameObject(index.key, desired.key) &&
index.unique === desired.options.unique &&
sameObject(
index.partialFilterExpression ?? {},
desired.options.partialFilterExpression ?? {},
)
);
}
function sameObject(left: unknown, right: unknown): boolean {
return JSON.stringify(left) === JSON.stringify(right);
}
function readModifiedCount(result: unknown): number {
if (!result || typeof result !== 'object') return 0;
const modifiedCount = (result as { modifiedCount?: unknown }).modifiedCount;
return typeof modifiedCount === 'number' ? modifiedCount : 0;
}
function hasField(doc: Record<string, unknown>, key: string): boolean {
return Object.prototype.hasOwnProperty.call(doc, key);
}
function stringifyKeyPart(value: unknown): string {
if (value === null) return '<null>';
if (value === undefined) return '<undefined>';
return stringifyId(value) ?? String(value);
}
function stringifyId(value: unknown): string | undefined {
if (value === undefined || value === null) return undefined;
return typeof value === 'string' ? value : String(value);
}
@@ -0,0 +1,318 @@
import 'reflect-metadata';
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { NestFactory } from '@nestjs/core';
import mongoose from 'mongoose';
import { readFile } from 'node:fs/promises';
import { resolve } from 'node:path';
import { ConnectionService, resolveMongoDbName } from '../connection.service';
import { SecretModule } from '../../secret/secret.module';
import {
migrateTournamentCodeUniqueIndexes,
TournamentCodeDuplicateGroupSummary,
TournamentCodeUniqueIndexMigrationProgress,
} from './20260627-tournament-code-unique-indexes';
interface CliOptions {
allowUsedDuplicateRelease: boolean;
createIndexes: boolean;
dryRun: boolean;
duplicateSampleLimit: number;
indexCommitQuorum?: number | string;
indexMaxTimeMS?: number;
listDuplicates: boolean;
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() {
const homeDir = process.env.HOME ?? process.env.USERPROFILE;
if (!homeDir) return;
const machineEnvFile = resolve(homeDir, 'source/global-env-vars.txt');
try {
const file = await readFile(machineEnvFile, '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 {
// Local machine env is optional for one-off migrations.
}
}
function parseArgs(argv: string[]): CliOptions {
let allowUsedDuplicateRelease = false;
let createIndexes = true;
let dryRun = true;
let duplicateSampleLimit = 20;
let indexCommitQuorum: number | string | undefined;
let indexMaxTimeMS: number | undefined;
let listDuplicates = false;
let nodeEnv = process.env.NODE_ENV ?? 'dev';
for (let index = 0; index < argv.length; index += 1) {
const arg = argv[index];
if (arg === '--allow-used-duplicate-release') {
allowUsedDuplicateRelease = true;
continue;
}
if (arg === '--apply') {
dryRun = false;
continue;
}
if (arg === '--dry-run') {
dryRun = true;
continue;
}
if (arg === '--duplicate-sample-limit') {
duplicateSampleLimit = parsePositiveInteger(
argv[index + 1],
'--duplicate-sample-limit',
);
index += 1;
continue;
}
if (arg.startsWith('--duplicate-sample-limit=')) {
duplicateSampleLimit = parsePositiveInteger(
arg.slice('--duplicate-sample-limit='.length),
'--duplicate-sample-limit',
);
continue;
}
if (arg === '--env') {
const value = argv[index + 1];
if (!value) throw new Error('--env requires dev, staging, or prod.');
nodeEnv = value;
index += 1;
continue;
}
if (arg.startsWith('--env=')) {
nodeEnv = arg.slice('--env='.length);
continue;
}
if (arg === '--index-commit-quorum') {
indexCommitQuorum = parseCommitQuorum(
argv[index + 1],
'--index-commit-quorum',
);
index += 1;
continue;
}
if (arg.startsWith('--index-commit-quorum=')) {
indexCommitQuorum = parseCommitQuorum(
arg.slice('--index-commit-quorum='.length),
'--index-commit-quorum',
);
continue;
}
if (arg === '--index-max-time-ms') {
indexMaxTimeMS = parsePositiveInteger(
argv[index + 1],
'--index-max-time-ms',
);
index += 1;
continue;
}
if (arg.startsWith('--index-max-time-ms=')) {
indexMaxTimeMS = parsePositiveInteger(
arg.slice('--index-max-time-ms='.length),
'--index-max-time-ms',
);
continue;
}
if (arg === '--list-duplicates') {
listDuplicates = true;
continue;
}
if (arg === '--skip-indexes') {
createIndexes = false;
continue;
}
if (arg === '--help' || arg === '-h') {
printHelp();
process.exit(0);
}
throw new Error(`Unknown argument: ${arg}`);
}
if (!['dev', 'staging', 'prod'].includes(nodeEnv)) {
throw new Error('--env must be dev, staging, or prod.');
}
return {
allowUsedDuplicateRelease,
createIndexes,
dryRun,
duplicateSampleLimit,
indexCommitQuorum,
indexMaxTimeMS,
listDuplicates,
nodeEnv,
};
}
function parseCommitQuorum(value: string | undefined, label: string) {
if (!value) {
throw new Error(`${label} requires a positive integer, majority, or votingMembers.`);
}
if (value === 'majority' || value === 'votingMembers') return value;
return parsePositiveInteger(value, label);
}
function parsePositiveInteger(value: string | undefined, label: string) {
const parsed = Number(value);
if (!Number.isInteger(parsed) || parsed < 1) {
throw new Error(`${label} requires a positive integer.`);
}
return parsed;
}
function printHelp() {
console.log(`Usage:
pnpm --filter api exec ts-node src/modules/global/database/migrations/run-tournament-code-unique-indexes.ts [--dry-run]
pnpm --filter api exec ts-node src/modules/global/database/migrations/run-tournament-code-unique-indexes.ts --env staging --apply
Options:
--dry-run Print affected counts without writing. Default.
--apply Release duplicate losers, pull them from matches, and create unique indexes.
--env <env> dev | staging | prod. Default: NODE_ENV or dev.
--list-duplicates
Print duplicate tournamentCode group samples.
--duplicate-sample-limit <n>
Max duplicate groups to print. Default: 20.
--index-commit-quorum <n|majority|votingMembers>
Override MongoDB index build commitQuorum. Use 1 only after checking replica health.
--index-max-time-ms <n>
Abort an individual index command after n milliseconds.
--skip-indexes Apply document cleanup without creating indexes.
--allow-used-duplicate-release
Allow releasing duplicate codes whose state is used. Default refuses this.
`);
}
function printDuplicateGroups(groups: TournamentCodeDuplicateGroupSummary[]) {
if (groups.length === 0) {
console.log('No duplicate tournamentCode groups found.');
return;
}
console.log('Duplicate tournamentCode groups:');
console.table(
groups.map((group) => ({
keeperCode: group.keeper.code ?? '',
keeperId: group.keeper.id,
keeperState: group.keeper.state ?? '',
key: group.key,
kind: group.kind,
loserCodes: group.losers.map((loser) => loser.code ?? '').join(', '),
loserIds: group.losers.map((loser) => loser.id).join(', '),
loserStates: group.losers
.map((loser) => loser.state ?? '')
.join(', '),
})),
);
}
function printProgress(progress: TournamentCodeUniqueIndexMigrationProgress) {
const count =
progress.scanned !== undefined
? ` scanned=${progress.scanned}`
: progress.total !== undefined
? ` total=${progress.total}`
: '';
const index = progress.indexName ? ` index=${progress.indexName}` : '';
const action = progress.action ? ` action=${progress.action}` : '';
console.log(
`[tournament-code unique index migration] ${progress.phase}${action}${index}${count}`,
);
}
async function main() {
const options = parseArgs(process.argv.slice(2));
process.env.NODE_ENV = options.nodeEnv;
process.env.SECRET_SOURCE = process.env.SECRET_SOURCE || 'infisical';
await loadMachineEnvFile();
const app = await NestFactory.createApplicationContext(MigrationModule, {
logger: ['log', 'warn', 'error'],
});
try {
const connectionService = app.get(ConnectionService);
const connection = await connectionService.getConnection();
if (!connection.db) {
throw new Error('MongoDB connection has no db handle.');
}
const dbName = resolveMongoDbName(options.nodeEnv);
console.log(
`[tournament-code unique index migration] mode=${
options.dryRun ? 'dry-run' : 'apply'
} env=${options.nodeEnv} db=${dbName}`,
);
const result = await migrateTournamentCodeUniqueIndexes(
connection.db as Parameters<typeof migrateTournamentCodeUniqueIndexes>[0],
{
allowUsedDuplicateRelease: options.allowUsedDuplicateRelease,
createIndexes: options.createIndexes,
dryRun: options.dryRun,
duplicateSampleLimit: options.duplicateSampleLimit,
indexCommitQuorum: options.indexCommitQuorum,
indexMaxTimeMS: options.indexMaxTimeMS,
onProgress: printProgress,
},
);
console.table(result.stats);
if (options.listDuplicates) {
printDuplicateGroups(result.sampleDuplicateGroups);
}
if (result.stats.unsafeUsedDuplicateCodes > 0 && options.dryRun) {
console.log(
'Apply will refuse used duplicate cleanup unless --allow-used-duplicate-release is provided.',
);
}
if (options.dryRun) {
console.log(
'No writes were made. Re-run with --apply to clean documents and create indexes.',
);
} else if (options.createIndexes) {
console.log('Migration applied and indexes ensured.');
} else {
console.log('Migration applied without index creation.');
}
} finally {
await app.close();
await mongoose.disconnect();
}
}
void main().catch((error: unknown) => {
console.error(error instanceof Error ? error.message : error);
process.exitCode = 1;
});