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 { DistributedLockService } from '../global/redis/distributed-lock.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; const MAX_DELIVERY_ATTEMPTS = 10; 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, private readonly distributedLockService: DistributedLockService, ) {} 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 }, }, { returnDocument: 'after', 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}.`); } // Different revision events can be leased by different API instances. // Serialize their effects so the next builder can reuse committed stats. const applied = await this.distributedLockService.runWithRenewedLock( { lockKey: `competition:projection-effects:${event.competitionId.toString()}`, lockExpirationDurationMilliseconds: PROCESSING_LEASE_MS, lockRenewalIntervalMilliseconds: PROCESSING_LEASE_MS / 3, }, async () => { await this.applyProjectionEffects(event); return true; }, ); if (!applied) { // Contention is not a failed delivery and must not exhaust retries. await OutboxModel.updateOne(leaseFilter(event), { $set: { state: 'pending', availableAt: new Date(Date.now() + DRAIN_INTERVAL_MS), }, $inc: { attemptCount: -1 }, }).exec(); return; } await OutboxModel.updateOne(leaseFilter(event), { $set: { state: 'published', publishedAt: new Date() }, $unset: { lastError: 1 }, }).exec(); } catch (error) { const lastError = errorMessage(error).slice(0, 2_000); if (event.attemptCount >= MAX_DELIVERY_ATTEMPTS) { const terminal = await OutboxModel.updateOne(leaseFilter(event), { $set: { state: 'dead-letter', lastError, }, }).exec(); if (terminal.matchedCount > 0) { this.logger.error( `Competition outbox event ${event._id.toString()} moved to dead-letter after ${event.attemptCount} attempts: ${lastError}`, ); } return; } const availableAt = new Date( Date.now() + retryDelayMilliseconds(event.attemptCount), ); await OutboxModel.updateOne(leaseFilter(event), { $set: { state: 'failed', lastError, availableAt, }, }).exec(); this.logger.warn( `Competition outbox event ${event._id.toString()} failed: ${lastError}`, ); } } 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); }