From 5049220e03f5d0e2c7c7286e9346462cc08f0c5a Mon Sep 17 00:00:00 2001 From: Park Dahyeon Date: Sun, 12 Jul 2026 19:57:47 +0000 Subject: [PATCH] feat: deliver competition projection outbox effects --- .../competition-outbox.processor.spec.ts | 174 ++++++++++ .../competition-outbox.processor.ts | 317 ++++++++++++++++++ .../competition-result.adapter.spec.ts | 11 +- .../competition-result.adapter.ts | 3 +- .../tournament-result.module.ts | 7 +- 5 files changed, 504 insertions(+), 8 deletions(-) create mode 100644 apps/api/src/modules/tournament-result/competition-outbox.processor.spec.ts create mode 100644 apps/api/src/modules/tournament-result/competition-outbox.processor.ts diff --git a/apps/api/src/modules/tournament-result/competition-outbox.processor.spec.ts b/apps/api/src/modules/tournament-result/competition-outbox.processor.spec.ts new file mode 100644 index 00000000..b0e1b8b8 --- /dev/null +++ b/apps/api/src/modules/tournament-result/competition-outbox.processor.spec.ts @@ -0,0 +1,174 @@ +/* eslint-disable @typescript-eslint/no-unsafe-assignment */ +import mongoose from 'mongoose'; +import { CommunityStatsService } from '../community-stats/community-stats.service'; +import { MatchStatsService } from '../community-stats/match-stats.service'; +import { ConnectionService } from '../global/database/connection.service'; +import { CompetitionAssignmentProvisioner } from './competition-assignment.provisioner'; +import { CompetitionOutboxProcessor } from './competition-outbox.processor'; + +describe('CompetitionOutboxProcessor', () => { + it('leases a projection event and applies idempotent downstream effects', async () => { + const competitionId = new mongoose.Types.ObjectId(); + const matchId = new mongoose.Types.ObjectId(); + const communityId = new mongoose.Types.ObjectId(); + const eventId = new mongoose.Types.ObjectId(); + const event = { + _id: eventId, + competitionId, + revision: 7, + type: 'competition.projection-updated', + state: 'pending', + attemptCount: 1, + }; + const publish = jest.fn(() => executable({ matchedCount: 1 })); + const claim = jest + .fn() + .mockReturnValueOnce(leanExecutable(event)) + .mockReturnValueOnce(leanExecutable(null)); + const matchUpdate = jest.fn(() => executable({ matchedCount: 1 })); + const models = { + competitionOutbox: { + findOneAndUpdate: claim, + updateOne: publish, + }, + competition: { + findById: jest.fn(() => + leanExecutable({ + _id: competitionId, + matchId, + communityId, + revision: 8, + phase: 'completed', + teams: [], + projection: { + phase: 'completed', + series: [], + gameSlots: [], + games: [{ evidence: { type: 'riot', riotMatchId: 'KR_1' } }], + }, + }), + ), + }, + match: { + findById: jest.fn(() => + leanExecutable({ status: 'in-progress', resultPollState: {} }), + ), + updateOne: matchUpdate, + }, + }; + const connection = { + getModel: jest.fn((name: keyof typeof models) => + Promise.resolve(models[name]), + ), + } as unknown as ConnectionService; + const provisionReadyAssignments = jest.fn().mockResolvedValue({}); + const provisioner = { + provisionReadyAssignments, + } as unknown as jest.Mocked; + const buildAndUpsert = jest.fn().mockResolvedValue(undefined); + const stats = { + buildAndUpsert, + } as unknown as jest.Mocked; + const invalidateCommunity = jest.fn().mockResolvedValue(undefined); + const communityStats = { + invalidateCommunity, + } as unknown as jest.Mocked; + const processor = new CompetitionOutboxProcessor( + connection, + provisioner, + stats, + communityStats, + ); + + await expect(processor.drainOnce()).resolves.toBe(1); + + expect(provisionReadyAssignments).toHaveBeenCalledWith({ + matchId, + competition: expect.objectContaining({ + competitionId: competitionId.toString(), + revision: 8, + }), + }); + expect(matchUpdate).toHaveBeenCalledWith( + { _id: matchId }, + { + $set: expect.objectContaining({ + status: 'finished', + 'resultPollState.matchedCount': 1, + 'resultPollState.state': 'complete', + }), + }, + ); + expect(buildAndUpsert).toHaveBeenCalledWith(matchId, { + sourceRevision: 8, + }); + expect(invalidateCommunity).toHaveBeenCalledWith(communityId); + expect(publish).toHaveBeenCalledWith( + { _id: eventId, state: 'pending', attemptCount: 1 }, + expect.objectContaining({ + $set: expect.objectContaining({ state: 'published' }), + }), + ); + }); + + it('marks a leased event failed and retryable when effects cannot run', async () => { + const event = { + _id: new mongoose.Types.ObjectId(), + competitionId: new mongoose.Types.ObjectId(), + revision: 2, + type: 'competition.projection-updated', + state: 'pending', + attemptCount: 3, + }; + const updateOne = jest.fn(() => executable({ matchedCount: 1 })); + const models = { + competitionOutbox: { + findOneAndUpdate: jest + .fn() + .mockReturnValueOnce(leanExecutable(event)) + .mockReturnValueOnce(leanExecutable(null)), + updateOne, + }, + competition: { + findById: jest.fn(() => leanExecutable(null)), + }, + match: {}, + }; + const processor = new CompetitionOutboxProcessor( + { + getModel: jest.fn((name: keyof typeof models) => + Promise.resolve(models[name]), + ), + } as unknown as ConnectionService, + { provisionReadyAssignments: jest.fn() } as never, + { buildAndUpsert: jest.fn() } as never, + { invalidateCommunity: jest.fn() } as never, + ); + + await expect(processor.drainOnce()).resolves.toBe(1); + + expect(updateOne).toHaveBeenCalledWith( + { _id: event._id, state: 'pending', attemptCount: 3 }, + { + $set: expect.objectContaining({ + state: 'failed', + lastError: 'Competition no longer exists.', + availableAt: expect.any(Date), + }), + }, + ); + }); +}); + +function leanExecutable(value: T) { + const query = { + lean: jest.fn(), + exec: jest.fn().mockResolvedValue(value), + }; + query.lean.mockReturnValue(query); + return query; +} + +function executable(value: T) { + return { exec: jest.fn().mockResolvedValue(value) }; +} diff --git a/apps/api/src/modules/tournament-result/competition-outbox.processor.ts b/apps/api/src/modules/tournament-result/competition-outbox.processor.ts new file mode 100644 index 00000000..dbd71012 --- /dev/null +++ b/apps/api/src/modules/tournament-result/competition-outbox.processor.ts @@ -0,0 +1,317 @@ +import { + Injectable, + Logger, + OnModuleDestroy, + OnModuleInit, +} from '@nestjs/common'; +import mongoose from 'mongoose'; +import { CommunityStatsService } from '../community-stats/community-stats.service'; +import { MatchStatsService } from '../community-stats/match-stats.service'; +import { ConnectionService } from '../global/database/connection.service'; +import { CompetitionAssignmentProvisioner } from './competition-assignment.provisioner'; +import type { CompetitionResultSnapshot } from './competition-result.adapter'; + +const DRAIN_INTERVAL_MS = 5_000; +const PROCESSING_LEASE_MS = 60_000; +const MAX_EVENTS_PER_DRAIN = 20; +const MAX_RETRY_DELAY_MS = 5 * 60_000; + +interface ClaimedOutboxEvent { + _id: mongoose.Types.ObjectId; + competitionId: mongoose.Types.ObjectId; + revision: number; + type: string; + state: 'pending' | 'failed'; + attemptCount: number; +} + +interface CompetitionEffectDocument { + _id: mongoose.Types.ObjectId; + matchId: mongoose.Types.ObjectId; + communityId: mongoose.Types.ObjectId; + revision: number; + phase: string; + teams: unknown[]; + projection: Record; +} + +/** + * Delivers durable Competition projection effects. The Mongo outbox lease is + * the retry boundary; every downstream effect is intentionally idempotent so + * an expired lease can be processed safely by another API instance. + */ +@Injectable() +export class CompetitionOutboxProcessor + implements OnModuleInit, OnModuleDestroy +{ + private readonly logger = new Logger(CompetitionOutboxProcessor.name); + private timer?: NodeJS.Timeout; + private draining = false; + + constructor( + private readonly connectionService: ConnectionService, + private readonly assignmentProvisioner: CompetitionAssignmentProvisioner, + private readonly matchStatsService: MatchStatsService, + private readonly communityStatsService: CommunityStatsService, + ) {} + + public onModuleInit(): void { + this.timer = setInterval(() => void this.drainSafely(), DRAIN_INTERVAL_MS); + this.timer.unref?.(); + void this.drainSafely(); + } + + public onModuleDestroy(): void { + if (this.timer) clearInterval(this.timer); + } + + public async drainOnce(limit = MAX_EVENTS_PER_DRAIN): Promise { + if (!Number.isInteger(limit) || limit < 1) return 0; + let processed = 0; + while (processed < limit) { + const event = await this.claimNextEvent(); + if (!event) break; + await this.deliver(event); + processed += 1; + } + return processed; + } + + private async drainSafely(): Promise { + if (this.draining) return; + this.draining = true; + try { + await this.drainOnce(); + } catch (error) { + this.logger.warn( + `Competition outbox drain failed: ${errorMessage(error)}`, + ); + } finally { + this.draining = false; + } + } + + private async claimNextEvent(): Promise { + const OutboxModel = + await this.connectionService.getModel('competitionOutbox'); + const now = new Date(); + return OutboxModel.findOneAndUpdate( + { + state: { $in: ['pending', 'failed'] }, + availableAt: { $lte: now }, + }, + { + $set: { + state: 'pending', + availableAt: new Date(now.getTime() + PROCESSING_LEASE_MS), + }, + $inc: { attemptCount: 1 }, + $unset: { lastError: 1 }, + }, + { + new: true, + sort: { availableAt: 1, revision: 1, _id: 1 }, + }, + ) + .lean() + .exec() as Promise; + } + + private async deliver(event: ClaimedOutboxEvent): Promise { + const OutboxModel = + await this.connectionService.getModel('competitionOutbox'); + try { + if (event.type !== 'competition.projection-updated') { + throw new Error(`Unsupported Competition outbox type ${event.type}.`); + } + await this.applyProjectionEffects(event); + await OutboxModel.updateOne(leaseFilter(event), { + $set: { state: 'published', publishedAt: new Date() }, + $unset: { lastError: 1 }, + }).exec(); + } catch (error) { + const availableAt = new Date( + Date.now() + retryDelayMilliseconds(event.attemptCount), + ); + await OutboxModel.updateOne(leaseFilter(event), { + $set: { + state: 'failed', + lastError: errorMessage(error).slice(0, 2_000), + availableAt, + }, + }).exec(); + this.logger.warn( + `Competition outbox event ${event._id.toString()} failed: ${errorMessage(error)}`, + ); + } + } + + private async applyProjectionEffects( + event: ClaimedOutboxEvent, + ): Promise { + const [CompetitionModel, MatchModel] = await Promise.all([ + this.connectionService.getModel('competition'), + this.connectionService.getModel('match'), + ]); + const competition = (await CompetitionModel.findById(event.competitionId) + .lean() + .exec()) as CompetitionEffectDocument | null; + if (!competition) throw new Error('Competition no longer exists.'); + if (competition.revision < event.revision) { + throw new Error( + `Competition revision ${competition.revision} is behind outbox revision ${event.revision}.`, + ); + } + + const snapshot = toResultSnapshot(competition); + await this.assignmentProvisioner.provisionReadyAssignments({ + matchId: competition.matchId, + competition: snapshot, + }); + + const match = await MatchModel.findById(competition.matchId).lean().exec(); + if (!match) throw new Error('Competition Match no longer exists.'); + const phase = projectionPhase(competition.projection); + const gameCount = projectionGames(competition.projection).length; + const status = + phase === 'completed' + ? 'finished' + : gameCount > 0 || match.status === 'finished' + ? 'in-progress' + : match.status; + const set: Record = { status }; + if (match.resultPollState) { + set['resultPollState.matchedCount'] = gameCount; + set['resultPollState.state'] = + phase === 'completed' ? 'complete' : 'polling'; + } + await MatchModel.updateOne( + { _id: competition.matchId }, + { $set: set }, + ).exec(); + + await this.matchStatsService.buildAndUpsert(competition.matchId, { + sourceRevision: competition.revision, + }); + await this.communityStatsService.invalidateCommunity( + competition.communityId, + ); + } +} + +function leaseFilter(event: ClaimedOutboxEvent) { + return { + _id: event._id, + state: 'pending', + attemptCount: event.attemptCount, + }; +} + +function retryDelayMilliseconds(attemptCount: number): number { + return Math.min( + Math.max(1, 2 ** Math.min(attemptCount, 8)) * 1_000, + MAX_RETRY_DELAY_MS, + ); +} + +function toResultSnapshot( + competition: CompetitionEffectDocument, +): CompetitionResultSnapshot { + const projection = competition.projection; + return { + competitionId: competition._id.toString(), + revision: competition.revision, + phase: String(competition.phase) as CompetitionResultSnapshot['phase'], + teams: arrayValue(competition.teams).map((team) => ({ + teamId: idValue(recordValue(team).teamId), + members: arrayValue(recordValue(team).members).map((member) => ({ + userId: idValue(recordValue(member).userId), + })), + })), + projection: { + phase: projectionPhase(projection), + series: arrayValue(projection.series).map((series) => { + const source = recordValue(series); + return { + seriesId: idValue(source.seriesId), + status: String( + source.status, + ) as CompetitionResultSnapshot['projection']['series'][number]['status'], + entries: arrayValue(source.entries).map((entry) => { + const row = recordValue(entry); + return { + slot: String(row.slot) as 'A' | 'B', + teamId: row.teamId == null ? null : idValue(row.teamId), + gameWins: numberValue(row.gameWins), + }; + }), + }; + }), + gameSlots: arrayValue(projection.gameSlots).map((slot) => { + const source = recordValue(slot); + return { + id: idValue(source.id), + seriesId: idValue(source.seriesId), + ordinal: numberValue(source.ordinal), + displayNumber: numberValue(source.displayNumber), + status: String( + source.status, + ) as CompetitionResultSnapshot['projection']['gameSlots'][number]['status'], + }; + }), + games: projectionGames(projection).map((game) => { + const evidence = recordValue(recordValue(game).evidence); + return { + evidence: { + type: typeof evidence.type === 'string' ? evidence.type : undefined, + riotMatchId: + typeof evidence.riotMatchId === 'string' + ? evidence.riotMatchId + : undefined, + }, + }; + }), + }, + }; +} + +function projectionPhase( + projection: Record, +): CompetitionResultSnapshot['projection']['phase'] { + const phase = projection.phase; + if (phase !== 'ready' && phase !== 'running' && phase !== 'completed') { + throw new Error('Competition projection phase is invalid.'); + } + return phase; +} + +function projectionGames(projection: Record): unknown[] { + return arrayValue(projection.games); +} + +function recordValue(value: unknown): Record { + return value !== null && typeof value === 'object' && !Array.isArray(value) + ? (value as Record) + : {}; +} + +function arrayValue(value: unknown): unknown[] { + return Array.isArray(value) ? value : []; +} + +function idValue(value: unknown): string { + if (value instanceof mongoose.Types.ObjectId) return value.toString(); + if (typeof value === 'string') return value; + if (typeof value === 'number' || typeof value === 'bigint') { + return String(value); + } + return ''; +} + +function numberValue(value: unknown): number { + return typeof value === 'number' ? value : Number(value); +} + +function errorMessage(error: unknown): string { + return error instanceof Error ? error.message : String(error); +} diff --git a/apps/api/src/modules/tournament-result/competition-result.adapter.spec.ts b/apps/api/src/modules/tournament-result/competition-result.adapter.spec.ts index 05026de3..0fdae862 100644 --- a/apps/api/src/modules/tournament-result/competition-result.adapter.spec.ts +++ b/apps/api/src/modules/tournament-result/competition-result.adapter.spec.ts @@ -153,8 +153,8 @@ describe('Competition result Riot mapping', () => { }); expect(accepted?.evidence.payloadHash).toMatch(/^[a-f0-9]{64}$/); expect(accepted?.normalizedParticipants).toHaveLength(10); + expect(typeof accepted?.normalizedParticipants[0]?.userId).toBe('string'); expect(accepted?.normalizedParticipants[0]).toMatchObject({ - userId: expect.any(String), teamId: teamBId, side: 'blue', summonerName: '', @@ -219,9 +219,10 @@ describe('Competition result Riot mapping', () => { info: { ...detail.info, gameCreation: detail.info.gameCreation + 60_000 }, }; - expect([later, detail].sort(compareRiotGameChronology).map((game) => game.metadata.matchId)).toEqual([ - 'KR_123456789', - 'KR_LATER', - ]); + expect( + [later, detail] + .sort(compareRiotGameChronology) + .map((game) => game.metadata.matchId), + ).toEqual(['KR_123456789', 'KR_LATER']); }); }); diff --git a/apps/api/src/modules/tournament-result/competition-result.adapter.ts b/apps/api/src/modules/tournament-result/competition-result.adapter.ts index 05dd7cd9..d54ce4d4 100644 --- a/apps/api/src/modules/tournament-result/competition-result.adapter.ts +++ b/apps/api/src/modules/tournament-result/competition-result.adapter.ts @@ -233,8 +233,7 @@ export function mapRiotGameToCompetitionSlot(params: { winnerTeamId, algorithmVersion: MAPPING_ALGORITHM_VERSION, confidence: - trustedOverlap / - Math.max(slotAPuuids.length + slotBPuuids.length, 1), + trustedOverlap / Math.max(slotAPuuids.length + slotBPuuids.length, 1), diagnostics: { trustedOverlap, normalOverlap, reversedOverlap }, participantAssignments: normalizedParticipants.flatMap((participant) => typeof participant.userId === 'string' diff --git a/apps/api/src/modules/tournament-result/tournament-result.module.ts b/apps/api/src/modules/tournament-result/tournament-result.module.ts index 52c2e19a..89db0a0d 100644 --- a/apps/api/src/modules/tournament-result/tournament-result.module.ts +++ b/apps/api/src/modules/tournament-result/tournament-result.module.ts @@ -4,6 +4,7 @@ import { CompetitionModule } from '../competition/competition.module'; import { RiotJobQueueModule } from '../riot-job-queue/riot-job-queue.module'; import { RiotModule } from '../riot/riot.module'; import { CompetitionAssignmentProvisioner } from './competition-assignment.provisioner'; +import { CompetitionOutboxProcessor } from './competition-outbox.processor'; import { TournamentResultController } from './tournament-result.controller'; import { TournamentResultService } from './tournament-result.service'; @@ -15,7 +16,11 @@ import { TournamentResultService } from './tournament-result.service'; forwardRef(() => RiotJobQueueModule), ], controllers: [TournamentResultController], - providers: [CompetitionAssignmentProvisioner, TournamentResultService], + providers: [ + CompetitionAssignmentProvisioner, + CompetitionOutboxProcessor, + TournamentResultService, + ], exports: [TournamentResultService], }) export class TournamentResultModule {}