diff --git a/apps/api/src/modules/analysis/analysis-pipeline.service.spec.ts b/apps/api/src/modules/analysis/analysis-pipeline.service.spec.ts index e5e4a65..ff2835c 100644 --- a/apps/api/src/modules/analysis/analysis-pipeline.service.spec.ts +++ b/apps/api/src/modules/analysis/analysis-pipeline.service.spec.ts @@ -1,9 +1,17 @@ import { Logger } from '@nestjs/common'; import { FEATURE_SCHEMA_VERSION, VECTOR_METRICS } from '@persona-lenz/shared'; import type { ConnectionService } from '../global/database/connection.service'; -import type { Account } from '../global/database/schemas'; +import type { + Account, + PlayerMatchFeature, + RiotMatch, +} from '../global/database/schemas'; import { RiotNotFoundError, type RiotApiClient } from '../riot/riot-api.client'; -import type { UserAnalysisJobData } from './analysis.types'; +import type { + FeatureRecomputeJobData, + UserAnalysisJobData, +} from './analysis.types'; +import { FEATURE_RECOMPUTE_JOB_NAME } from './analysis.constants'; import { FeatureExtractorService } from './feature-extractor.service'; import { AnalysisPipelineService } from './analysis-pipeline.service'; import { ProfileBuilderService } from './profile-builder.service'; @@ -159,6 +167,20 @@ function leanExecResolved(value: T) { }; } +function findManyChain(value: T) { + const exec = jest.fn, []>().mockResolvedValue(value); + const lean = jest.fn(() => ({ exec })); + const limit = jest.fn(() => ({ lean })); + const sort = jest.fn(() => ({ limit })); + return { + chain: { sort }, + exec, + lean, + limit, + sort, + }; +} + function createStoredAccount(overrides: Partial = {}): Account { return { createdAt: new Date('2026-07-01T00:00:00.000Z'), @@ -176,6 +198,43 @@ function createStoredAccount(overrides: Partial = {}): Account { }; } +function createStoredFeature( + overrides: Partial = {}, +): PlayerMatchFeature { + return { + createdAt: new Date('2026-07-01T00:00:00.000Z'), + updatedAt: new Date('2026-07-01T00:00:00.000Z'), + matchId: 'KR_1', + puuid: 'target-puuid', + queueId: 420, + role: 'MIDDLE', + championId: 103, + gameCreation: 1_700_000_000_000, + gameDurationSec: 1_800, + win: true, + patch: '26.13', + features: { kda: 7 }, + normalized: { kda: 1 }, + vector: [], + featureSchemaVersion: 1, + normalizationMethod: 'registry-baseline', + confidence: 1, + timelineProcessed: false, + ...overrides, + }; +} + +function createFeatureRecomputeJobData( + overrides: Partial = {}, +): FeatureRecomputeJobData { + return { + platformRoute: 'kr', + queueId: 420, + batchSize: 100, + ...overrides, + }; +} + function suppressLoggerError() { return jest .spyOn(Logger.prototype, 'error') @@ -300,6 +359,113 @@ function createPipelineHarness(options: PipelineHarnessOptions = {}) { }; } +interface FeatureRecomputeHarnessOptions { + account?: Account | null; + profileFeatures?: PlayerMatchFeature[]; + remainingTargets?: PlayerMatchFeature[]; + scanError?: Error; + storedMatch?: Pick | null; + targetFeatures?: PlayerMatchFeature[]; +} + +function createFeatureRecomputeHarness( + options: FeatureRecomputeHarnessOptions = {}, +) { + const scanChain = findManyChain( + options.targetFeatures ?? [createStoredFeature()], + ); + if (options.scanError) { + scanChain.exec.mockRejectedValueOnce(options.scanError); + } + const remainingTargetsChain = findManyChain(options.remainingTargets ?? []); + const profileFeaturesChain = findManyChain( + options.profileFeatures ?? [ + createStoredFeature({ + featureSchemaVersion: FEATURE_SCHEMA_VERSION, + timelineProcessed: true, + }), + ], + ); + const findPlayerMatchFeatures = jest + .fn() + .mockReturnValueOnce(scanChain.chain) + .mockReturnValueOnce(remainingTargetsChain.chain) + .mockReturnValueOnce(profileFeaturesChain.chain); + const updatePlayerMatchFeature: UpdateOneMock = jest + .fn, Parameters>() + .mockReturnValue(execResolved({ acknowledged: true })); + const updatePlayerProfile: UpdateOneMock = jest + .fn, Parameters>() + .mockReturnValue(execResolved({ acknowledged: true })); + const updateAnalysisJob: UpdateOneMock = jest + .fn, Parameters>() + .mockReturnValue(execResolved({ acknowledged: true })); + const updateAccount: UpdateOneMock = jest + .fn, Parameters>() + .mockReturnValue(execResolved({ acknowledged: true })); + const findOneAccount = jest + .fn() + .mockReturnValue( + leanExecResolved( + options.account === undefined ? createStoredAccount() : options.account, + ), + ); + const storedMatch = + options.storedMatch === undefined + ? { + raw: createMatchPayload(), + timeline: createTimelinePayload(), + } + : options.storedMatch; + const findOneRiotMatch = jest + .fn() + .mockReturnValue(leanExecResolved(storedMatch)); + const models = { + account: { + findOne: findOneAccount, + updateOne: updateAccount, + }, + analysisJob: { + updateOne: updateAnalysisJob, + }, + playerMatchFeature: { + find: findPlayerMatchFeatures, + updateOne: updatePlayerMatchFeature, + }, + playerProfile: { + updateOne: updatePlayerProfile, + }, + riotMatch: { + findOne: findOneRiotMatch, + }, + }; + const connectionService = { + getModel: jest.fn((modelKey: keyof typeof models) => + Promise.resolve(models[modelKey]), + ), + } as unknown as ConnectionService; + + return { + findOneAccount, + findOneRiotMatch, + findPlayerMatchFeatures, + profileFeaturesChain, + remainingTargetsChain, + scanChain, + service: new AnalysisPipelineService( + connectionService, + {} as RiotApiClient, + new FeatureExtractorService(), + new ProfileBuilderService(), + new TimelineDerivedService(), + new TimelineMetricService(), + ), + updateAnalysisJob, + updatePlayerMatchFeature, + updatePlayerProfile, + }; +} + describe('AnalysisPipelineService', () => { it('fetches missing match details, stores features, builds a profile, and completes the job', async () => { const { @@ -645,6 +811,276 @@ describe('AnalysisPipelineService', () => { expect(completedJobUpdate).toBeDefined(); }); + it('recomputes stale stored features and rebuilds affected profiles', async () => { + const staleFeature = createStoredFeature({ + featureSchemaVersion: 1, + timelineProcessed: false, + }); + const currentProfileFeature = createStoredFeature({ + featureSchemaVersion: FEATURE_SCHEMA_VERSION, + normalized: { kda: 1 }, + vector: VECTOR_METRICS.map((metric) => (metric.id === 'kda' ? 1 : 0)), + timelineProcessed: true, + }); + const scanChain = findManyChain([staleFeature]); + const remainingTargetsChain = findManyChain([]); + const profileFeaturesChain = findManyChain([currentProfileFeature]); + const findPlayerMatchFeatures = jest + .fn() + .mockReturnValueOnce(scanChain.chain) + .mockReturnValueOnce(remainingTargetsChain.chain) + .mockReturnValueOnce(profileFeaturesChain.chain); + const updatePlayerMatchFeature: UpdateOneMock = jest + .fn, Parameters>() + .mockReturnValue(execResolved({ acknowledged: true })); + const updatePlayerProfile: UpdateOneMock = jest + .fn, Parameters>() + .mockReturnValue(execResolved({ acknowledged: true })); + const updateAnalysisJob: UpdateOneMock = jest + .fn, Parameters>() + .mockReturnValue(execResolved({ acknowledged: true })); + const updateAccount: UpdateOneMock = jest + .fn, Parameters>() + .mockReturnValue(execResolved({ acknowledged: true })); + const findOneAccount = jest + .fn() + .mockReturnValue(leanExecResolved(createStoredAccount())); + const findOneRiotMatch = jest.fn().mockReturnValue( + leanExecResolved({ + matchId: 'KR_1', + raw: createMatchPayload(), + timeline: createTimelinePayload(), + }), + ); + const models = { + account: { + findOne: findOneAccount, + updateOne: updateAccount, + }, + analysisJob: { + updateOne: updateAnalysisJob, + }, + playerMatchFeature: { + find: findPlayerMatchFeatures, + updateOne: updatePlayerMatchFeature, + }, + playerProfile: { + updateOne: updatePlayerProfile, + }, + riotMatch: { + findOne: findOneRiotMatch, + }, + }; + const connectionService = { + getModel: jest.fn((modelKey: keyof typeof models) => + Promise.resolve(models[modelKey]), + ), + } as unknown as ConnectionService; + const service = new AnalysisPipelineService( + connectionService, + {} as RiotApiClient, + new FeatureExtractorService(), + new ProfileBuilderService(), + new TimelineDerivedService(), + new TimelineMetricService(), + ); + + await service.processFeatureRecomputeJob( + createFeatureRecomputeJobData(), + 'recompute-job-1', + ); + + expect(findPlayerMatchFeatures).toHaveBeenNthCalledWith( + 1, + expect.objectContaining({ + queueId: 420, + $or: [ + { featureSchemaVersion: { $lt: FEATURE_SCHEMA_VERSION } }, + { + timelineProcessed: false, + 'derived.timelineUnavailableForFeatureSchemaVersion': { + $ne: FEATURE_SCHEMA_VERSION, + }, + }, + ], + }), + ); + expect(scanChain.sort).toHaveBeenCalledWith({ gameCreation: -1 }); + expect(scanChain.limit).toHaveBeenCalledWith(100); + expect(findOneRiotMatch).toHaveBeenCalledWith({ matchId: 'KR_1' }); + const recomputedFeatureSet = asRecord( + asRecord(updatePlayerMatchFeature.mock.calls[0][1]).$set, + ); + expect(recomputedFeatureSet).toMatchObject({ + matchId: 'KR_1', + puuid: 'target-puuid', + featureSchemaVersion: FEATURE_SCHEMA_VERSION, + timelineProcessed: true, + }); + expect(findPlayerMatchFeatures).toHaveBeenNthCalledWith( + 2, + expect.objectContaining({ + puuid: 'target-puuid', + queueId: 420, + $or: [ + { featureSchemaVersion: { $lt: FEATURE_SCHEMA_VERSION } }, + { + timelineProcessed: false, + 'derived.timelineUnavailableForFeatureSchemaVersion': { + $ne: FEATURE_SCHEMA_VERSION, + }, + }, + ], + }), + ); + expect(remainingTargetsChain.limit).toHaveBeenCalledWith(1); + expect(findPlayerMatchFeatures).toHaveBeenNthCalledWith(3, { + puuid: 'target-puuid', + queueId: 420, + featureSchemaVersion: FEATURE_SCHEMA_VERSION, + }); + expect(profileFeaturesChain.limit).toHaveBeenCalledWith(50); + const playerProfileSet = asRecord( + asRecord(updatePlayerProfile.mock.calls[0][1]).$set, + ); + expect(playerProfileSet).toMatchObject({ + puuid: 'target-puuid', + queueId: 420, + featureSchemaVersion: FEATURE_SCHEMA_VERSION, + sampleGameCount: 1, + }); + const completedJobUpdate = updateAnalysisJob.mock.calls.find( + ([, update]) => asRecord(asRecord(update).$set).status === 'completed', + ); + expect(asRecord(asRecord(completedJobUpdate?.[1]).$set)).toMatchObject({ + jobType: FEATURE_RECOMPUTE_JOB_NAME, + status: 'completed', + stage: 'completed', + }); + }); + + it('marks timeline-less recomputed features as current but missing timeline coverage', async () => { + const targetFeature = createStoredFeature({ + featureSchemaVersion: 1, + timelineProcessed: false, + }); + const currentProfileFeature = createStoredFeature({ + featureSchemaVersion: FEATURE_SCHEMA_VERSION, + normalized: { kda: 1 }, + vector: VECTOR_METRICS.map((metric) => (metric.id === 'kda' ? 1 : 0)), + timelineProcessed: false, + }); + const { service, updatePlayerMatchFeature, updatePlayerProfile } = + createFeatureRecomputeHarness({ + profileFeatures: [currentProfileFeature], + storedMatch: { + raw: createMatchPayload(), + }, + targetFeatures: [targetFeature], + }); + + await service.processFeatureRecomputeJob( + createFeatureRecomputeJobData(), + 'recompute-job-1', + ); + + const recomputedFeatureSet = asRecord( + asRecord(updatePlayerMatchFeature.mock.calls[0][1]).$set, + ); + expect(recomputedFeatureSet).toMatchObject({ + featureSchemaVersion: FEATURE_SCHEMA_VERSION, + timelineProcessed: false, + derived: { + timelineUnavailableForFeatureSchemaVersion: FEATURE_SCHEMA_VERSION, + }, + }); + expect(asRecord(recomputedFeatureSet.normalized).objectivePreWardRate).toBe( + undefined, + ); + const playerProfileSet = asRecord( + asRecord(updatePlayerProfile.mock.calls[0][1]).$set, + ); + expect(playerProfileSet.sampleGameCount).toBe(1); + expect(playerProfileSet.confidence).toBeCloseTo(0.14); + }); + + it('does not publish a partial profile while stale features remain for that player', async () => { + const { findOneAccount, service, updatePlayerProfile } = + createFeatureRecomputeHarness({ + remainingTargets: [ + createStoredFeature({ + matchId: 'KR_2', + featureSchemaVersion: 1, + timelineProcessed: false, + }), + ], + targetFeatures: [ + createStoredFeature({ + matchId: 'KR_1', + featureSchemaVersion: 1, + timelineProcessed: false, + }), + ], + }); + + await service.processFeatureRecomputeJob( + createFeatureRecomputeJobData(), + 'recompute-job-1', + ); + + expect(updatePlayerProfile).not.toHaveBeenCalled(); + expect(findOneAccount).not.toHaveBeenCalled(); + }); + + it('does not mark feature recompute jobs failed before BullMQ exhausts retries', async () => { + const { service, updateAnalysisJob } = createFeatureRecomputeHarness({ + scanError: new Error('database unavailable'), + }); + + await expect( + service.processFeatureRecomputeJob( + createFeatureRecomputeJobData(), + 'recompute-job-1', + { isFinalAttempt: false }, + ), + ).rejects.toThrow('database unavailable'); + + const failedJobUpdate = updateAnalysisJob.mock.calls.find( + ([, update]) => asRecord(asRecord(update).$set).status === 'failed', + ); + expect(failedJobUpdate).toBeUndefined(); + }); + + it('marks feature recompute jobs failed with a public error on the final attempt', async () => { + const loggerErrorSpy = suppressLoggerError(); + const { service, updateAnalysisJob } = createFeatureRecomputeHarness({ + scanError: new Error('database unavailable'), + }); + + await expect( + service.processFeatureRecomputeJob( + createFeatureRecomputeJobData({ puuid: 'target-puuid' }), + 'recompute-job-1', + { isFinalAttempt: true }, + ), + ).rejects.toThrow('database unavailable'); + + const failedJobUpdate = updateAnalysisJob.mock.calls.find( + ([, update]) => asRecord(asRecord(update).$set).status === 'failed', + ); + expect(asRecord(asRecord(failedJobUpdate?.[1]).$set)).toMatchObject({ + jobType: FEATURE_RECOMPUTE_JOB_NAME, + status: 'failed', + error: 'Analysis failed during processing.', + }); + expect(loggerErrorSpy).toHaveBeenCalledWith( + expect.stringContaining('Feature recompute job failed'), + expect.any(String), + ); + expect(loggerErrorSpy.mock.calls[0][0]).toContain('puuid="target-puuid"'); + loggerErrorSpy.mockRestore(); + }); + it('does not mark the job failed before BullMQ exhausts retries', async () => { const { service, updateAnalysisJob } = createPipelineHarness({ accountError: new Error('upstream unavailable'), diff --git a/apps/api/src/modules/analysis/analysis-pipeline.service.ts b/apps/api/src/modules/analysis/analysis-pipeline.service.ts index 7b3ffd0..317d5db 100644 --- a/apps/api/src/modules/analysis/analysis-pipeline.service.ts +++ b/apps/api/src/modules/analysis/analysis-pipeline.service.ts @@ -1,8 +1,10 @@ import { Injectable, Logger } from '@nestjs/common'; +import { FEATURE_SCHEMA_VERSION } from '@persona-lenz/shared'; import { ConnectionService } from '../global/database/connection.service'; import type { Account, AnalysisJobStatus, + PlayerMatchFeature, RiotMatch, TierInfo, } from '../global/database/schemas'; @@ -12,11 +14,15 @@ import { type RiotLeagueEntryDto, } from '../riot/riot-api.client'; import { + FEATURE_RECOMPUTE_JOB_NAME, + MAX_ANALYSIS_MATCH_COUNT, + normalizeFeatureRecomputeBatchSize, normalizeRequestedMatchCount, USER_ANALYSIS_JOB_NAME, } from './analysis.constants'; import type { ExtractedPlayerMatchFeature, + FeatureRecomputeJobData, UserAnalysisJobData, } from './analysis.types'; import { FeatureExtractorService } from './feature-extractor.service'; @@ -38,6 +44,10 @@ interface ParsedMatchSummary { participantPuuids: string[]; } +const TIMELINE_UNAVAILABLE_FEATURE_SCHEMA_VERSION_FIELD = + 'timelineUnavailableForFeatureSchemaVersion'; +const TIMELINE_UNAVAILABLE_FEATURE_SCHEMA_VERSION_PATH = `derived.${TIMELINE_UNAVAILABLE_FEATURE_SCHEMA_VERSION_FIELD}`; + function asRecord(value: unknown): Record { if (typeof value === 'object' && value !== null && !Array.isArray(value)) { return value as Record; @@ -173,6 +183,97 @@ export class AnalysisPipelineService { } } + public async processFeatureRecomputeJob( + data: FeatureRecomputeJobData, + jobId: string, + options: { isFinalAttempt?: boolean } = {}, + ): Promise { + const normalizedData = { + ...data, + batchSize: normalizeFeatureRecomputeBatchSize(data.batchSize), + }; + + try { + await this.updateJob( + jobId, + { + status: 'processing', + stage: 'scan-features', + progress: { + fetchedMatches: 0, + totalMatches: 0, + }, + }, + FEATURE_RECOMPUTE_JOB_NAME, + ); + + const targetFeatures = + await this.findFeatureRecomputeTargets(normalizedData); + await this.updateJob( + jobId, + { + stage: 'recompute-features', + progress: { + fetchedMatches: 0, + totalMatches: targetFeatures.length, + }, + }, + FEATURE_RECOMPUTE_JOB_NAME, + ); + + const affectedPuuids = new Set(); + for (const [index, targetFeature] of targetFeatures.entries()) { + const recomputedFeature = + await this.recomputeStoredFeature(targetFeature); + if (recomputedFeature) { + affectedPuuids.add(recomputedFeature.puuid); + } + await this.updateJob( + jobId, + { + progress: { + fetchedMatches: index + 1, + totalMatches: targetFeatures.length, + }, + }, + FEATURE_RECOMPUTE_JOB_NAME, + ); + } + + await this.updateJob( + jobId, + { + stage: 'build-profile', + }, + FEATURE_RECOMPUTE_JOB_NAME, + ); + for (const puuid of affectedPuuids) { + await this.rebuildStoredProfile(puuid, normalizedData.queueId); + } + + await this.completeJob(jobId, FEATURE_RECOMPUTE_JOB_NAME); + } catch (error) { + if (options.isFinalAttempt === true) { + const publicError = this.publicErrorMessage(error); + this.logFeatureRecomputeFinalFailure( + normalizedData, + jobId, + publicError, + error, + ); + await this.updateJob( + jobId, + { + status: 'failed', + error: publicError, + }, + FEATURE_RECOMPUTE_JOB_NAME, + ); + } + throw error; + } + } + private async resolveAndStoreAccount( data: UserAnalysisJobData, ): Promise { @@ -426,32 +527,154 @@ export class AnalysisPipelineService { return extractedFeatures; } + private async findFeatureRecomputeTargets( + data: FeatureRecomputeJobData, + ): Promise { + const playerMatchFeatureModel = + await this.connectionService.getModel('playerMatchFeature'); + + return playerMatchFeatureModel + .find( + this.featureRecomputeTargetQuery({ + queueId: data.queueId, + puuid: data.puuid, + }), + ) + .sort({ gameCreation: -1 }) + .limit(data.batchSize) + .lean() + .exec(); + } + + private async recomputeStoredFeature( + targetFeature: PlayerMatchFeature, + ): Promise { + const riotMatchModel = await this.connectionService.getModel('riotMatch'); + const playerMatchFeatureModel = + await this.connectionService.getModel('playerMatchFeature'); + + const storedMatch = await riotMatchModel + .findOne({ matchId: targetFeature.matchId }) + .lean() + .exec(); + if (!storedMatch) { + this.logger.warn( + `Skipping feature recompute for matchId="${this.safeLogText(targetFeature.matchId)}": stored match was not found`, + ); + return undefined; + } + + try { + const feature = this.featureExtractorService.extractPlayerMatchFeature( + storedMatch.raw, + targetFeature.puuid, + ); + if (feature.queueId !== targetFeature.queueId) { + return undefined; + } + + if (isTimelinePayload(storedMatch.timeline)) { + const derived = this.timelineDerivedService.buildDerivedData( + storedMatch.timeline, + storedMatch.raw, + ); + const timelineMetrics = + this.timelineMetricService.extractTimelineMetrics( + feature, + storedMatch.raw, + storedMatch.timeline, + derived, + ); + feature.derived = { + ...derived, + }; + feature.features = { + ...feature.features, + ...timelineMetrics.features, + }; + feature.normalized = { + ...feature.normalized, + ...timelineMetrics.normalized, + }; + feature.vector = timelineMetrics.vector; + feature.timelineProcessed = true; + } else { + feature.derived = { + [TIMELINE_UNAVAILABLE_FEATURE_SCHEMA_VERSION_FIELD]: + FEATURE_SCHEMA_VERSION, + }; + } + + await playerMatchFeatureModel + .updateOne( + { matchId: feature.matchId, puuid: feature.puuid }, + { $set: feature }, + { upsert: true }, + ) + .exec(); + return feature; + } catch (error) { + this.logger.warn( + `Skipping feature recompute for matchId="${this.safeLogText(targetFeature.matchId)}": ${this.safeLogText(errorMessage(error))}`, + ); + return undefined; + } + } + + private async rebuildStoredProfile( + puuid: string, + queueId: number, + ): Promise { + const playerMatchFeatureModel = + await this.connectionService.getModel('playerMatchFeature'); + const hasRemainingTargets = + await this.hasRemainingFeatureRecomputeTargetsForPlayer(puuid, queueId); + if (hasRemainingTargets) { + return; + } + + const accountModel = await this.connectionService.getModel('account'); + const account = await accountModel + .findOne({ puuid }) + .lean | null>() + .exec(); + const features = await playerMatchFeatureModel + .find({ + puuid, + queueId, + featureSchemaVersion: FEATURE_SCHEMA_VERSION, + }) + .sort({ gameCreation: -1 }) + .limit(MAX_ANALYSIS_MATCH_COUNT) + .lean() + .exec(); + + if (features.length === 0) { + return; + } + + await this.storeBuiltProfile({ + features, + isSeed: account?.isSeed ?? false, + puuid, + queueId, + }); + } + private async buildAndStoreProfile( account: Account, data: UserAnalysisJobData, extractedFeatures: ExtractedPlayerMatchFeature[], ): Promise { - const profile = this.profileBuilderService.buildProfile({ + await this.storeBuiltProfile({ features: extractedFeatures, isSeed: account.isSeed, puuid: account.puuid, queueId: data.queueId, }); - const playerProfileModel = - await this.connectionService.getModel('playerProfile'); const accountModel = await this.connectionService.getModel('account'); const analyzedAt = new Date(); - await playerProfileModel - .updateOne( - { - puuid: account.puuid, - queueId: data.queueId, - }, - { $set: profile }, - { upsert: true }, - ) - .exec(); await accountModel .updateOne( { puuid: account.puuid }, @@ -464,13 +687,82 @@ export class AnalysisPipelineService { .exec(); } - private async completeJob(jobId: string): Promise { - await this.updateJob(jobId, { - status: 'completed', - stage: 'completed', - completedAt: new Date(), - error: undefined, + private async hasRemainingFeatureRecomputeTargetsForPlayer( + puuid: string, + queueId: number, + ): Promise { + const playerMatchFeatureModel = + await this.connectionService.getModel('playerMatchFeature'); + const remainingTargets = await playerMatchFeatureModel + .find(this.featureRecomputeTargetQuery({ puuid, queueId })) + .sort({ gameCreation: -1 }) + .limit(1) + .lean() + .exec(); + + return remainingTargets.length > 0; + } + + private featureRecomputeTargetQuery(params: { + puuid?: string; + queueId: number; + }): Record { + return { + ...(params.puuid ? { puuid: params.puuid } : {}), + queueId: params.queueId, + $or: [ + { featureSchemaVersion: { $lt: FEATURE_SCHEMA_VERSION } }, + { + timelineProcessed: false, + [TIMELINE_UNAVAILABLE_FEATURE_SCHEMA_VERSION_PATH]: { + $ne: FEATURE_SCHEMA_VERSION, + }, + }, + ], + }; + } + + private async storeBuiltProfile(params: { + features: PlayerMatchFeature[] | ExtractedPlayerMatchFeature[]; + isSeed: boolean; + puuid: string; + queueId: number; + }): Promise { + const profile = this.profileBuilderService.buildProfile({ + features: params.features, + isSeed: params.isSeed, + puuid: params.puuid, + queueId: params.queueId, }); + const playerProfileModel = + await this.connectionService.getModel('playerProfile'); + + await playerProfileModel + .updateOne( + { + puuid: params.puuid, + queueId: params.queueId, + }, + { $set: profile }, + { upsert: true }, + ) + .exec(); + } + + private async completeJob( + jobId: string, + jobType = USER_ANALYSIS_JOB_NAME, + ): Promise { + await this.updateJob( + jobId, + { + status: 'completed', + stage: 'completed', + completedAt: new Date(), + error: undefined, + }, + jobType, + ); } private async updateJob( @@ -483,12 +775,13 @@ export class AnalysisPipelineService { stage?: string; status?: AnalysisJobStatus; }, + jobType = USER_ANALYSIS_JOB_NAME, ): Promise { const analysisJobModel = await this.connectionService.getModel('analysisJob'); const set: Record = { jobId, - jobType: USER_ANALYSIS_JOB_NAME, + jobType, ...patch, }; const unset: Record = {}; @@ -585,6 +878,25 @@ export class AnalysisPipelineService { ); } + private logFeatureRecomputeFinalFailure( + data: FeatureRecomputeJobData, + jobId: string, + publicError: string, + error: unknown, + ): void { + this.logger.error( + [ + `Feature recompute job failed jobId="${this.safeLogText(jobId)}"`, + `puuid="${this.safeLogText(data.puuid ?? '')}"`, + `platformRoute="${data.platformRoute}"`, + `queueId="${data.queueId}"`, + `publicError="${this.safeLogText(publicError)}"`, + `cause="${this.safeLogText(errorMessage(error))}"`, + ].join(' '), + error instanceof Error ? error.stack : undefined, + ); + } + private safeLogText(value: string): string { return value.replace(/[\r\n\t]/gu, ' ').slice(0, 300); } diff --git a/apps/api/src/modules/analysis/analysis-queue.service.spec.ts b/apps/api/src/modules/analysis/analysis-queue.service.spec.ts index ba718fb..122edfb 100644 --- a/apps/api/src/modules/analysis/analysis-queue.service.spec.ts +++ b/apps/api/src/modules/analysis/analysis-queue.service.spec.ts @@ -1,7 +1,10 @@ import type { AnalysisJob } from '../global/database/schemas'; import type { ConnectionService } from '../global/database/connection.service'; import type { UserAnalysisJobData } from './analysis.types'; -import { USER_ANALYSIS_JOB_NAME } from './analysis.constants'; +import { + FEATURE_RECOMPUTE_JOB_NAME, + USER_ANALYSIS_JOB_NAME, +} from './analysis.constants'; import { AnalysisQueueService } from './analysis-queue.service'; function createJobData( @@ -78,6 +81,59 @@ describe('AnalysisQueueService', () => { ); }); + it('creates a feature recompute job document and enqueues a BullMQ job', async () => { + const add = jest.fn().mockResolvedValue({ id: 'job-from-bull' }); + const create = jest.fn().mockResolvedValue({}); + const updateOne = jest.fn(() => ({ + exec: jest.fn().mockResolvedValue({}), + })); + const analysisJobModel = { + create, + updateOne, + }; + const connectionService = { + getModel: jest.fn().mockResolvedValue(analysisJobModel), + } as unknown as ConnectionService; + const service = new AnalysisQueueService( + { add } as never, + connectionService, + () => 'recompute-job-1', + ); + + const result = await service.enqueueFeatureRecompute({ + platformRoute: 'kr', + queueId: 420, + batchSize: 25, + puuid: 'target-puuid', + }); + + expect(result).toEqual({ jobId: 'recompute-job-1', status: 'queued' }); + expect(create).toHaveBeenCalledWith( + expect.objectContaining({ + jobId: 'recompute-job-1', + jobType: FEATURE_RECOMPUTE_JOB_NAME, + platformRoute: 'kr', + queueId: 420, + requestedMatchCount: 0, + puuid: 'target-puuid', + status: 'queued', + }), + ); + expect(add).toHaveBeenCalledWith( + FEATURE_RECOMPUTE_JOB_NAME, + { + platformRoute: 'kr', + queueId: 420, + batchSize: 25, + puuid: 'target-puuid', + }, + expect.objectContaining({ + attempts: 1, + jobId: 'recompute-job-1', + }), + ); + }); + it('returns an existing active job instead of enqueueing a duplicate', async () => { const add = jest.fn(); const findOneChain = createFindOneChain({ @@ -143,6 +199,44 @@ describe('AnalysisQueueService', () => { ); }); + it('marks a pre-created feature recompute job failed when BullMQ enqueue fails', async () => { + const add = jest.fn().mockRejectedValue(new Error('redis unavailable')); + const create = jest.fn().mockResolvedValue({}); + const updateOne = jest.fn(() => ({ + exec: jest.fn().mockResolvedValue({}), + })); + const analysisJobModel = { + create, + updateOne, + }; + const connectionService = { + getModel: jest.fn().mockResolvedValue(analysisJobModel), + } as unknown as ConnectionService; + const service = new AnalysisQueueService( + { add } as never, + connectionService, + () => 'recompute-job-1', + ); + + await expect( + service.enqueueFeatureRecompute({ + platformRoute: 'kr', + queueId: 420, + batchSize: 25, + }), + ).rejects.toThrow('redis unavailable'); + expect(updateOne).toHaveBeenCalledWith( + { jobId: 'recompute-job-1' }, + { + $set: { + status: 'failed', + stage: 'enqueue', + error: 'Analysis could not be queued.', + }, + }, + ); + }); + it('serializes identical in-process requests before creating a duplicate job', async () => { const add = jest.fn().mockResolvedValue({ id: 'analysis-job-1' }); let activeJob: Pick | null = null; diff --git a/apps/api/src/modules/analysis/analysis-queue.service.ts b/apps/api/src/modules/analysis/analysis-queue.service.ts index db3aa50..659ac73 100644 --- a/apps/api/src/modules/analysis/analysis-queue.service.ts +++ b/apps/api/src/modules/analysis/analysis-queue.service.ts @@ -9,12 +9,20 @@ import { ANALYSIS_JOB_ID_FACTORY, ACTIVE_ANALYSIS_JOB_STATUSES, ANALYSIS_QUEUE_NAME, + FEATURE_RECOMPUTE_JOB_NAME, + normalizeFeatureRecomputeBatchSize, normalizeRequestedMatchCount, USER_ANALYSIS_JOB_NAME, } from './analysis.constants'; -import type { UserAnalysisJobData } from './analysis.types'; +import type { + FeatureRecomputeJobData, + UserAnalysisJobData, +} from './analysis.types'; type JobIdFactory = () => string; +type AnalysisQueueJobData = UserAnalysisJobData | FeatureRecomputeJobData; +type AnalysisQueueJobName = + typeof USER_ANALYSIS_JOB_NAME | typeof FEATURE_RECOMPUTE_JOB_NAME; type ActiveAnalysisJob = Pick & { status: Extract; }; @@ -24,9 +32,9 @@ export class AnalysisQueueService { constructor( @InjectQueue(ANALYSIS_QUEUE_NAME) private readonly analysisQueue: Queue< - UserAnalysisJobData, + AnalysisQueueJobData, void, - typeof USER_ANALYSIS_JOB_NAME + AnalysisQueueJobName >, private readonly connectionService: ConnectionService, @Inject(ANALYSIS_JOB_ID_FACTORY) @@ -57,6 +65,56 @@ export class AnalysisQueueService { } } + public async enqueueFeatureRecompute( + data: FeatureRecomputeJobData, + ): Promise { + const normalizedData = this.normalizeFeatureRecomputeData(data); + const analysisJobModel = + await this.connectionService.getModel('analysisJob'); + const jobId = this.jobIdFactory(); + + await analysisJobModel.create({ + jobId, + jobType: FEATURE_RECOMPUTE_JOB_NAME, + puuid: normalizedData.puuid, + platformRoute: normalizedData.platformRoute, + queueId: normalizedData.queueId, + requestedMatchCount: 0, + status: 'queued', + stage: 'queued', + progress: { + fetchedMatches: 0, + totalMatches: 0, + }, + }); + + try { + await this.analysisQueue.add(FEATURE_RECOMPUTE_JOB_NAME, normalizedData, { + attempts: 1, + jobId, + }); + } catch (error) { + await analysisJobModel + .updateOne( + { jobId }, + { + $set: { + status: 'failed', + stage: 'enqueue', + error: this.publicErrorMessage(), + }, + }, + ) + .exec(); + throw error; + } + + return { + jobId, + status: 'queued', + }; + } + private readonly pendingDuplicateRequestKeys = new Set(); private async enqueueUserAnalysisWithoutDuplicateRequestRace( @@ -148,6 +206,18 @@ export class AnalysisQueueService { return 'Analysis could not be queued.'; } + private normalizeFeatureRecomputeData( + data: FeatureRecomputeJobData, + ): FeatureRecomputeJobData { + const puuid = data.puuid?.trim(); + return { + platformRoute: data.platformRoute, + queueId: data.queueId, + batchSize: normalizeFeatureRecomputeBatchSize(data.batchSize), + ...(puuid ? { puuid } : {}), + }; + } + private duplicateRequestKey(data: UserAnalysisJobData): string { return [ data.platformRoute, diff --git a/apps/api/src/modules/analysis/analysis.constants.ts b/apps/api/src/modules/analysis/analysis.constants.ts index 5533e94..1a4e740 100644 --- a/apps/api/src/modules/analysis/analysis.constants.ts +++ b/apps/api/src/modules/analysis/analysis.constants.ts @@ -1,9 +1,12 @@ export const ANALYSIS_QUEUE_NAME = 'analysis'; export const USER_ANALYSIS_JOB_NAME = 'user-analysis'; +export const FEATURE_RECOMPUTE_JOB_NAME = 'feature-recompute'; export const ANALYSIS_JOB_ID_FACTORY = Symbol('ANALYSIS_JOB_ID_FACTORY'); export const DEFAULT_ANALYSIS_MATCH_COUNT = 20; export const MAX_ANALYSIS_MATCH_COUNT = 50; +export const DEFAULT_FEATURE_RECOMPUTE_BATCH_SIZE = 100; +export const MAX_FEATURE_RECOMPUTE_BATCH_SIZE = 500; export const ACTIVE_ANALYSIS_JOB_STATUSES = ['queued', 'processing'] as const; @@ -16,3 +19,16 @@ export function normalizeRequestedMatchCount( return Math.min(Math.trunc(requestedMatchCount), MAX_ANALYSIS_MATCH_COUNT); } + +export function normalizeFeatureRecomputeBatchSize(batchSize: number): number { + if (!Number.isFinite(batchSize) || batchSize <= 0) { + return DEFAULT_FEATURE_RECOMPUTE_BATCH_SIZE; + } + + const normalizedBatchSize = Math.trunc(batchSize); + if (normalizedBatchSize <= 0) { + return DEFAULT_FEATURE_RECOMPUTE_BATCH_SIZE; + } + + return Math.min(normalizedBatchSize, MAX_FEATURE_RECOMPUTE_BATCH_SIZE); +} diff --git a/apps/api/src/modules/analysis/analysis.processor.spec.ts b/apps/api/src/modules/analysis/analysis.processor.spec.ts index a5247c3..12afa06 100644 --- a/apps/api/src/modules/analysis/analysis.processor.spec.ts +++ b/apps/api/src/modules/analysis/analysis.processor.spec.ts @@ -1,10 +1,20 @@ import type { Job } from 'bullmq'; -import { USER_ANALYSIS_JOB_NAME } from './analysis.constants'; -import type { UserAnalysisJobData } from './analysis.types'; +import { + DEFAULT_FEATURE_RECOMPUTE_BATCH_SIZE, + FEATURE_RECOMPUTE_JOB_NAME, + MAX_FEATURE_RECOMPUTE_BATCH_SIZE, + USER_ANALYSIS_JOB_NAME, +} from './analysis.constants'; +import type { + FeatureRecomputeJobData, + UserAnalysisJobData, +} from './analysis.types'; import { AnalysisPipelineService } from './analysis-pipeline.service'; import { AnalysisProcessor } from './analysis.processor'; -function createJobData(): UserAnalysisJobData { +function createJobData( + overrides: Partial = {}, +): UserAnalysisJobData { return { gameName: 'Hide on bush', tagLine: 'KR1', @@ -12,6 +22,19 @@ function createJobData(): UserAnalysisJobData { regionalRoute: 'asia', queueId: 420, requestedMatchCount: 20, + ...overrides, + }; +} + +function createFeatureRecomputeJobData( + overrides: Partial = {}, +): FeatureRecomputeJobData { + return { + platformRoute: 'kr', + queueId: 420, + batchSize: 25, + puuid: 'target-puuid', + ...overrides, }; } @@ -42,6 +65,139 @@ describe('AnalysisProcessor', () => { ); }); + it('delegates feature recompute jobs to the analysis pipeline', async () => { + const processFeatureRecomputeJob = jest + .fn< + Promise, + [FeatureRecomputeJobData, string, { isFinalAttempt?: boolean }] + >() + .mockResolvedValue(undefined); + const processor = new AnalysisProcessor({ + processFeatureRecomputeJob, + } as unknown as AnalysisPipelineService); + + await processor.process({ + attemptsMade: 0, + id: 'recompute-job-1', + name: FEATURE_RECOMPUTE_JOB_NAME, + opts: { attempts: 2 }, + data: createFeatureRecomputeJobData(), + } as Job); + + expect(processFeatureRecomputeJob).toHaveBeenCalledWith( + createFeatureRecomputeJobData(), + 'recompute-job-1', + { isFinalAttempt: false }, + ); + }); + + it('normalizes feature recompute batch size from valid queue payloads', async () => { + const processFeatureRecomputeJob = jest.fn().mockResolvedValue(undefined); + const processor = new AnalysisProcessor({ + processFeatureRecomputeJob, + } as unknown as AnalysisPipelineService); + + await processor.process({ + attemptsMade: 0, + id: 'recompute-job-1', + name: FEATURE_RECOMPUTE_JOB_NAME, + opts: { attempts: 2 }, + data: createFeatureRecomputeJobData({ batchSize: 999 }), + } as Job); + + expect(processFeatureRecomputeJob).toHaveBeenCalledWith( + createFeatureRecomputeJobData({ + batchSize: MAX_FEATURE_RECOMPUTE_BATCH_SIZE, + }), + 'recompute-job-1', + { isFinalAttempt: false }, + ); + }); + + it('defaults fractional feature recompute batch sizes below one', async () => { + const processFeatureRecomputeJob = jest.fn().mockResolvedValue(undefined); + const processor = new AnalysisProcessor({ + processFeatureRecomputeJob, + } as unknown as AnalysisPipelineService); + + await processor.process({ + attemptsMade: 0, + id: 'recompute-job-1', + name: FEATURE_RECOMPUTE_JOB_NAME, + opts: { attempts: 2 }, + data: createFeatureRecomputeJobData({ batchSize: 0.5 }), + } as Job); + + expect(processFeatureRecomputeJob).toHaveBeenCalledWith( + createFeatureRecomputeJobData({ + batchSize: DEFAULT_FEATURE_RECOMPUTE_BATCH_SIZE, + }), + 'recompute-job-1', + { isFinalAttempt: false }, + ); + }); + + it.each([ + { + data: null, + expectedError: 'Feature recompute job data must be an object.', + }, + { + data: { + ...createFeatureRecomputeJobData(), + platformRoute: 'invalid', + }, + expectedError: 'Analysis job platformRoute is unsupported.', + }, + { + data: { + ...createFeatureRecomputeJobData(), + queueId: 430, + }, + expectedError: 'Analysis job queueId is unsupported.', + }, + { + data: { + ...createFeatureRecomputeJobData(), + batchSize: Number.NaN, + }, + expectedError: 'Feature recompute job batchSize must be finite.', + }, + { + data: { + ...createFeatureRecomputeJobData(), + puuid: ' ', + }, + expectedError: 'Analysis job puuid is out of range.', + }, + { + data: { + ...createFeatureRecomputeJobData(), + puuid: 'x'.repeat(129), + }, + expectedError: 'Analysis job puuid is out of range.', + }, + ])( + 'rejects malformed feature recompute payloads', + async ({ data, expectedError }) => { + const processFeatureRecomputeJob = jest.fn(); + const processor = new AnalysisProcessor({ + processFeatureRecomputeJob, + } as unknown as AnalysisPipelineService); + + await expect( + processor.process({ + attemptsMade: 0, + id: 'recompute-job-1', + name: FEATURE_RECOMPUTE_JOB_NAME, + opts: { attempts: 2 }, + data, + } as Job), + ).rejects.toThrow(expectedError); + expect(processFeatureRecomputeJob).not.toHaveBeenCalled(); + }, + ); + it('rejects jobs without a BullMQ id', async () => { const processor = new AnalysisProcessor({ processUserAnalysisJob: jest.fn(), diff --git a/apps/api/src/modules/analysis/analysis.processor.ts b/apps/api/src/modules/analysis/analysis.processor.ts index d0bb102..8ff48b9 100644 --- a/apps/api/src/modules/analysis/analysis.processor.ts +++ b/apps/api/src/modules/analysis/analysis.processor.ts @@ -2,11 +2,16 @@ import { Processor, WorkerHost } from '@nestjs/bullmq'; import type { Job } from 'bullmq'; import { ANALYSIS_QUEUE_NAME, + FEATURE_RECOMPUTE_JOB_NAME, + normalizeFeatureRecomputeBatchSize, normalizeRequestedMatchCount, USER_ANALYSIS_JOB_NAME, } from './analysis.constants'; import { AnalysisPipelineService } from './analysis-pipeline.service'; -import type { UserAnalysisJobData } from './analysis.types'; +import type { + FeatureRecomputeJobData, + UserAnalysisJobData, +} from './analysis.types'; import { RIOT_PLATFORM_ROUTES, RIOT_REGIONAL_ROUTES, @@ -27,14 +32,27 @@ export class AnalysisProcessor extends WorkerHost { if (!job.id) { throw new Error('Analysis job is missing a BullMQ job id.'); } - if (job.name !== USER_ANALYSIS_JOB_NAME) { - throw new Error(`Unsupported analysis job name "${job.name}".`); + if (job.name === USER_ANALYSIS_JOB_NAME) { + const data = this.parseUserAnalysisJobData(job.data); + await this.analysisPipelineService.processUserAnalysisJob(data, job.id, { + isFinalAttempt: this.isFinalAttempt(job), + }); + return; } - const data = this.parseUserAnalysisJobData(job.data); - await this.analysisPipelineService.processUserAnalysisJob(data, job.id, { - isFinalAttempt: this.isFinalAttempt(job), - }); + if (job.name === FEATURE_RECOMPUTE_JOB_NAME) { + const data = this.parseFeatureRecomputeJobData(job.data); + await this.analysisPipelineService.processFeatureRecomputeJob( + data, + job.id, + { + isFinalAttempt: this.isFinalAttempt(job), + }, + ); + return; + } + + throw new Error(`Unsupported analysis job name "${job.name}".`); } private parseUserAnalysisJobData(value: unknown): UserAnalysisJobData { @@ -68,6 +86,30 @@ export class AnalysisProcessor extends WorkerHost { }; } + private parseFeatureRecomputeJobData( + value: unknown, + ): FeatureRecomputeJobData { + if (typeof value !== 'object' || value === null || Array.isArray(value)) { + throw new Error('Feature recompute job data must be an object.'); + } + + const record = value as Record; + const platformRoute = this.parsePlatformRoute(record.platformRoute); + const queueId = this.parseQueueId(record.queueId); + const batchSize = this.parseFeatureRecomputeBatchSize(record.batchSize); + const puuid = + record.puuid === undefined + ? undefined + : this.parseBoundedString(record.puuid, 'puuid', 128); + + return { + platformRoute, + queueId, + batchSize, + ...(puuid ? { puuid } : {}), + }; + } + private parseBoundedString( value: unknown, fieldName: string, @@ -117,6 +159,13 @@ export class AnalysisProcessor extends WorkerHost { return normalizeRequestedMatchCount(value); } + private parseFeatureRecomputeBatchSize(value: unknown): number { + if (typeof value !== 'number' || !Number.isFinite(value)) { + throw new Error('Feature recompute job batchSize must be finite.'); + } + return normalizeFeatureRecomputeBatchSize(value); + } + private isFinalAttempt(job: Job): boolean { const attempts = typeof job.opts?.attempts === 'number' && job.opts.attempts > 0 diff --git a/apps/api/src/modules/analysis/analysis.types.ts b/apps/api/src/modules/analysis/analysis.types.ts index 7ae8c40..db0d0fe 100644 --- a/apps/api/src/modules/analysis/analysis.types.ts +++ b/apps/api/src/modules/analysis/analysis.types.ts @@ -14,6 +14,13 @@ export interface UserAnalysisJobData { requestedMatchCount: number; } +export interface FeatureRecomputeJobData { + platformRoute: RiotPlatformRoute; + queueId: number; + batchSize: number; + puuid?: string; +} + export interface ExtractedPlayerMatchFeature { matchId: string; puuid: string;