feat: deliver competition projection outbox effects

This commit is contained in:
dahyeon committed 2026-07-12 19:57:47 +00:00
1 parent ab9c48b1e6
commit 5049220e03
5 files changed
+504 -8

No files matched your search

@@ -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<CompetitionAssignmentProvisioner>;
const buildAndUpsert = jest.fn().mockResolvedValue(undefined);
const stats = {
buildAndUpsert,
} as unknown as jest.Mocked<MatchStatsService>;
const invalidateCommunity = jest.fn().mockResolvedValue(undefined);
const communityStats = {
invalidateCommunity,
} as unknown as jest.Mocked<CommunityStatsService>;
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<T>(value: T) {
const query = {
lean: jest.fn(),
exec: jest.fn().mockResolvedValue(value),
};
query.lean.mockReturnValue(query);
return query;
}
function executable<T>(value: T) {
return { exec: jest.fn().mockResolvedValue(value) };
}
@@ -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<string, unknown>;
}
/**
* 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<number> {
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<void> {
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<ClaimedOutboxEvent | null> {
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<ClaimedOutboxEvent | null>;
}
private async deliver(event: ClaimedOutboxEvent): Promise<void> {
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<void> {
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<string, unknown> = { 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<string, unknown>,
): 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<string, unknown>): unknown[] {
return arrayValue(projection.games);
}
function recordValue(value: unknown): Record<string, unknown> {
return value !== null && typeof value === 'object' && !Array.isArray(value)
? (value as Record<string, unknown>)
: {};
}
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);
}
@@ -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']);
});
});
@@ -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'
@@ -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 {}