import type { CompetitionCommandResponse, CompetitionDetailResponse, CompetitionFactsResponse, SeriesReversalPreviewResponse, TeamCompetitionViewResponse, } from '@lolympus/contracts'; import { Body, Controller, Get, Headers, HttpException, Param, Post, Query, Res, UseGuards, } from '@nestjs/common'; import type { Response } from 'express'; import mongoose from 'mongoose'; import { plainToInstance } from 'class-transformer'; import { validateSync, type ValidationError } from 'class-validator'; import { AllowPublicAccess } from '../auth/allow-public-access.decorator'; import { CurrentUser } from '../auth/current-user.decorator'; import { Roles } from '../auth/roles.decorator'; import { RolesGuard } from '../auth/roles.guard'; import { ParseObjectIdPipe } from '../common/parse-object-id.pipe'; import type { UserDocument } from '../global/database/schema'; import { CompetitionCommandService } from './competition-command.service'; import { presentCompetitionDetail } from './competition.presenter'; import { CompetitionQueryService } from './competition-query.service'; import { AcceptCompetitionGameDto, AdjudicateCompetitionSeriesDto, CompetitionFactsQueryDto, PreviewCompetitionSeriesReversalDto, ReverseCompetitionSeriesDto, } from './dto/competition-command.dto'; @Controller('communities/:communityId/matches/:matchId/competition') export class CompetitionController { constructor( private readonly queryService: CompetitionQueryService, private readonly commandService: CompetitionCommandService, ) {} @Get() @AllowPublicAccess() public async getDetail( @Param('communityId', ParseObjectIdPipe) communityId: mongoose.Types.ObjectId, @Param('matchId', ParseObjectIdPipe) matchId: mongoose.Types.ObjectId, @Res({ passthrough: true }) response: Response, ): Promise { return this.translate(async () => { const competition = await this.queryService.getCompetition({ communityId, matchId, }); response.setHeader('ETag', revisionEtag(competition.revision)); return presentCompetitionDetail(competition as never); }); } // Temporarily public: community members are not all signed in yet, so the // team progress page addresses a team through an explicit `teamId` instead of // the caller's identity. A signed-in caller with no `teamId` keeps the // membership-scoped behaviour. @Get('team') @AllowPublicAccess() public async getTeamView( @CurrentUser() currentUser: UserDocument | undefined, @Param('communityId', ParseObjectIdPipe) communityId: mongoose.Types.ObjectId, @Param('matchId', ParseObjectIdPipe) matchId: mongoose.Types.ObjectId, @Query('teamId') requestedTeamId?: string, @Res({ passthrough: true }) response?: Response, ): Promise { return this.translate(async () => { const teamId = parseOptionalObjectId(requestedTeamId, 'teamId'); if (!teamId) { if (!currentUser) { throw apiHttpError( 401, 'COMPETITION_TEAM_UNIDENTIFIED', 'Sign in or provide a teamId query parameter to read a team view.', ); } assertSameCommunity(currentUser, communityId); } const result = await this.queryService.getTeamView({ communityId, matchId, ...(teamId ? { teamId } : { userId: currentUser!._id }), }); response?.setHeader('ETag', revisionEtag(result.revision)); return result; }); } @Get('facts') @Roles('owner', 'admin') @UseGuards(RolesGuard) public async listFacts( @CurrentUser() currentUser: UserDocument, @Param('communityId', ParseObjectIdPipe) communityId: mongoose.Types.ObjectId, @Param('matchId', ParseObjectIdPipe) matchId: mongoose.Types.ObjectId, @Query() rawQuery: unknown, ): Promise { return this.translate(async () => { assertSameCommunity(currentUser, communityId); const query = validateDto(CompetitionFactsQueryDto, rawQuery); return this.queryService.listFacts({ communityId, matchId, cursor: query.cursor, limit: query.limit, }); }); } @Post('games/accept') @Roles('owner', 'admin') @UseGuards(RolesGuard) public async acceptGame( @CurrentUser() currentUser: UserDocument, @Param('communityId', ParseObjectIdPipe) communityId: mongoose.Types.ObjectId, @Param('matchId', ParseObjectIdPipe) matchId: mongoose.Types.ObjectId, @Headers('if-match') ifMatch: string | undefined, @Headers('idempotency-key') idempotencyKey: string | undefined, @Body() rawBody: unknown, ): Promise { return this.translate(async () => { assertSameCommunity(currentUser, communityId); const body = validateDto(AcceptCompetitionGameDto, rawBody); const expectedRevision = requireCommandHeaders(ifMatch, idempotencyKey); const competition = await this.queryService.getCompetition({ communityId, matchId, }); const result = await this.commandService.acceptGame({ competitionId: competition._id, expectedRevision, idempotencyKey: idempotencyKey!, actor: { type: 'user', userId: currentUser._id }, gameId: new mongoose.Types.ObjectId(body.gameId), seriesId: new mongoose.Types.ObjectId(body.seriesId), gameSlotId: new mongoose.Types.ObjectId(body.gameSlotId), ordinal: body.ordinal, evidence: { ...body.evidence }, mapping: { ...body.mapping }, ...(body.startedAt ? { startedAt: body.startedAt } : {}), ...(body.durationSeconds === undefined ? {} : { durationSeconds: body.durationSeconds }), ...(body.participants ? { participants: body.participants } : {}), ...(body.tournamentCode ? { tournamentCode: { tournamentCodeId: new mongoose.Types.ObjectId( body.tournamentCode.tournamentCodeId, ), riotMatchId: body.tournamentCode.riotMatchId, }, } : {}), }); return { competition: presentCompetitionDetail(result.competition as never), }; }); } @Post('series/:seriesId/adjudications') @Roles('owner', 'admin') @UseGuards(RolesGuard) public async adjudicateSeries( @CurrentUser() currentUser: UserDocument, @Param('communityId', ParseObjectIdPipe) communityId: mongoose.Types.ObjectId, @Param('matchId', ParseObjectIdPipe) matchId: mongoose.Types.ObjectId, @Param('seriesId', ParseObjectIdPipe) seriesId: mongoose.Types.ObjectId, @Headers('if-match') ifMatch: string | undefined, @Headers('idempotency-key') idempotencyKey: string | undefined, @Body() rawBody: unknown, ): Promise { return this.translate(async () => { assertSameCommunity(currentUser, communityId); const body = validateDto(AdjudicateCompetitionSeriesDto, rawBody); const expectedRevision = requireCommandHeaders(ifMatch, idempotencyKey); const competition = await this.queryService.getCompetition({ communityId, matchId, }); const decision = body.decision.type === 'administrative-draw' ? ({ type: 'administrative-draw' } as const) : { type: body.decision.type, winnerTeamId: new mongoose.Types.ObjectId( body.decision.winnerTeamId!, ), }; const result = await this.commandService.adjudicateSeries({ competitionId: competition._id, expectedRevision, idempotencyKey: idempotencyKey!, actor: { type: 'user', userId: currentUser._id }, seriesId, decision, reason: body.reason, }); return { competition: presentCompetitionDetail(result.competition as never), }; }); } @Post('series/:seriesId/reversal-preview') @Roles('owner', 'admin') @UseGuards(RolesGuard) public async previewReversal( @CurrentUser() currentUser: UserDocument, @Param('communityId', ParseObjectIdPipe) communityId: mongoose.Types.ObjectId, @Param('matchId', ParseObjectIdPipe) matchId: mongoose.Types.ObjectId, @Param('seriesId', ParseObjectIdPipe) seriesId: mongoose.Types.ObjectId, @Headers('if-match') ifMatch: string | undefined, @Body() rawBody: unknown, ): Promise { return this.translate(async () => { assertSameCommunity(currentUser, communityId); const body = validateDto(PreviewCompetitionSeriesReversalDto, rawBody); const expectedRevision = requireRevisionHeader(ifMatch); const competition = await this.queryService.getCompetition({ communityId, matchId, }); return (await this.commandService.previewSeriesReversal({ competitionId: competition._id, expectedRevision, seriesId, mode: body.mode, })) as SeriesReversalPreviewResponse; }); } @Post('series/:seriesId/reverse') @Roles('owner', 'admin') @UseGuards(RolesGuard) public async reverseSeries( @CurrentUser() currentUser: UserDocument, @Param('communityId', ParseObjectIdPipe) communityId: mongoose.Types.ObjectId, @Param('matchId', ParseObjectIdPipe) matchId: mongoose.Types.ObjectId, @Param('seriesId', ParseObjectIdPipe) seriesId: mongoose.Types.ObjectId, @Headers('if-match') ifMatch: string | undefined, @Headers('idempotency-key') idempotencyKey: string | undefined, @Body() rawBody: unknown, ): Promise { return this.translate(async () => { assertSameCommunity(currentUser, communityId); const body = validateDto(ReverseCompetitionSeriesDto, rawBody); const expectedRevision = requireCommandHeaders(ifMatch, idempotencyKey); const competition = await this.queryService.getCompetition({ communityId, matchId, }); const result = await this.commandService.reverseSeries({ competitionId: competition._id, expectedRevision, idempotencyKey: idempotencyKey!, actor: { type: 'user', userId: currentUser._id }, seriesId, mode: body.mode, reason: body.reason, impactHash: body.impactHash, }); return { competition: presentCompetitionDetail(result.competition as never), }; }); } private async translate(operation: () => Promise): Promise { try { return await operation(); } catch (error) { throw explicitHttpError(error); } } } function requireCommandHeaders( ifMatch: string | undefined, idempotencyKey: string | undefined, ): number { const revision = parseRevision(ifMatch); if ( revision === undefined || typeof idempotencyKey !== 'string' || idempotencyKey.trim().length === 0 || idempotencyKey.length > 200 ) { throw apiHttpError( 422, 'INVALID_COMPETITION_COMMAND_HEADERS', 'A numeric If-Match revision and non-empty Idempotency-Key are required.', ); } return revision; } function parseOptionalObjectId( value: string | undefined, field: string, ): mongoose.Types.ObjectId | undefined { if (value === undefined || value.trim().length === 0) return undefined; if (!mongoose.isValidObjectId(value)) { throw apiHttpError( 422, 'INVALID_COMPETITION_REQUEST', `The ${field} query parameter must be a valid ObjectId.`, ); } return new mongoose.Types.ObjectId(value); } function requireRevisionHeader(ifMatch: string | undefined): number { const revision = parseRevision(ifMatch); if (revision === undefined) { throw apiHttpError( 422, 'INVALID_COMPETITION_COMMAND_HEADERS', 'A numeric If-Match revision is required.', ); } return revision; } function parseRevision(value: string | undefined): number | undefined { if (!value) return undefined; const match = /^(?:W\/)?"?(\d+)"?$/.exec(value.trim()); if (!match) return undefined; const revision = Number(match[1]); return Number.isSafeInteger(revision) ? revision : undefined; } function revisionEtag(revision: number): string { return `"${revision}"`; } function assertSameCommunity( user: UserDocument, communityId: mongoose.Types.ObjectId, ): void { if (!user?.communityId?.equals(communityId)) { throw apiHttpError( 403, 'COMPETITION_COMMUNITY_FORBIDDEN', 'The authenticated user does not belong to this community.', ); } } function explicitHttpError(error: unknown): HttpException { if (error instanceof HttpException) { const response = error.getResponse(); if ( typeof response === 'object' && response !== null && 'error' in response ) { return error; } return apiHttpError( error.getStatus(), statusCodeName(error.getStatus()), typeof response === 'string' ? response : error.message || 'Competition request failed.', ); } if (isCodedError(error)) { return apiHttpError( error.httpStatus ?? codedErrorStatus(error.code), error.code, error.message, error.details, ); } return apiHttpError( 500, 'COMPETITION_INTERNAL_ERROR', 'Competition request failed.', ); } function codedErrorStatus(code: string): number { switch (code) { case 'REVERSAL_SERIES_NOT_FOUND': case 'REVERSAL_REASON_REQUIRED': return 422; case 'REVERSAL_DESCENDANT_ACTIVITY': case 'REVERSAL_NO_ACTIVE_RESULT': case 'REVERSAL_PREVIEW_STALE': case 'DUPLICATE_FACT_ID': case 'DUPLICATE_GAME_ID': case 'DUPLICATE_RIOT_MATCH_ID': case 'DUPLICATE_GAME_SLOT': case 'DUPLICATE_GAME_ORDINAL': case 'DUPLICATE_ADJUDICATION': case 'FACT_ALREADY_REVERSED': case 'SERIES_ALREADY_COMPLETED': case 'WALKOVER_HAS_ACTIVE_GAMES': return 409; case 'FACT_REFERENCE_NOT_FOUND': case 'FACT_TYPE_INVALID': case 'GAME_SLOT_INVALID': case 'GAME_ORDINAL_INVALID': case 'GAME_SERIES_MISMATCH': case 'GAME_TEAM_MISMATCH': case 'GAME_WINNER_INVALID': case 'SERIES_DEFINITION_INVALID': case 'SERIES_PARTICIPANTS_INVALID': case 'ADJUDICATION_INVALID': case 'ADJUDICATION_DRAW_NOT_ALLOWED': return 422; default: return 500; } } function statusCodeName(status: number): string { switch (status) { case 403: return 'COMPETITION_FORBIDDEN'; case 404: return 'COMPETITION_NOT_FOUND'; case 409: return 'COMPETITION_CONFLICT'; case 412: return 'STALE_COMPETITION_REVISION'; case 422: return 'INVALID_COMPETITION_REQUEST'; default: return 'COMPETITION_REQUEST_FAILED'; } } function apiHttpError( status: number, code: string, message: string, details?: unknown, ): HttpException { return new HttpException( { error: { code, message, ...(details === undefined ? {} : { details }), }, }, status, ); } function isCodedError(error: unknown): error is { code: string; message: string; httpStatus?: number; details?: unknown; } { return ( typeof error === 'object' && error !== null && typeof (error as { code?: unknown }).code === 'string' && typeof (error as { message?: unknown }).message === 'string' ); } type DtoConstructor = new () => T; function validateDto( constructor: DtoConstructor, value: unknown, ): T { if (typeof value !== 'object' || value === null || Array.isArray(value)) { throw apiHttpError( 422, 'INVALID_COMPETITION_REQUEST', 'The Competition request body must be an object.', ); } const instance = plainToInstance(constructor, value); const errors = validateSync(instance, { whitelist: true, forbidNonWhitelisted: true, forbidUnknownValues: true, }); if (errors.length > 0) { throw apiHttpError( 422, 'INVALID_COMPETITION_REQUEST', 'The Competition request payload is invalid.', { fields: flattenValidationErrors(errors) }, ); } return instance; } function flattenValidationErrors( errors: readonly ValidationError[], prefix = '', ): Array<{ field: string; constraints: string[] }> { return errors.flatMap((error) => { const field = prefix ? `${prefix}.${error.property}` : error.property; const current = error.constraints ? [{ field, constraints: Object.values(error.constraints) }] : []; return [ ...current, ...flattenValidationErrors(error.children ?? [], field), ]; }); }