From 2935a526c7d1e7dc559034b30cad04d848c94336 Mon Sep 17 00:00:00 2001 From: dahyeon Date: Fri, 3 Jul 2026 01:19:45 -0700 Subject: [PATCH] Wire baseline computation jobs --- .../analysis-pipeline.service.spec.ts | 69 +++++++++++++++- .../analysis/analysis-pipeline.service.ts | 73 ++++++++++++++++- .../analysis/analysis-queue.service.spec.ts | 61 ++++++++++++++ .../analysis/analysis-queue.service.ts | 74 ++++++++++++++++- .../modules/analysis/analysis.constants.ts | 1 + .../analysis/analysis.processor.spec.ts | 80 +++++++++++++++++++ .../modules/analysis/analysis.processor.ts | 56 +++++++++++++ .../src/modules/analysis/analysis.types.ts | 8 ++ 8 files changed, 418 insertions(+), 4 deletions(-) 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 9d83e82..baf1838 100644 --- a/apps/api/src/modules/analysis/analysis-pipeline.service.spec.ts +++ b/apps/api/src/modules/analysis/analysis-pipeline.service.spec.ts @@ -7,11 +7,16 @@ import type { RiotMatch, } from '../global/database/schemas'; import { RiotNotFoundError, type RiotApiClient } from '../riot/riot-api.client'; +import type { MetricBaselineService } from './metric-baseline.service'; import type { + BaselineComputationJobData, FeatureRecomputeJobData, UserAnalysisJobData, } from './analysis.types'; -import { FEATURE_RECOMPUTE_JOB_NAME } from './analysis.constants'; +import { + BASELINE_COMPUTATION_JOB_NAME, + 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'; @@ -235,6 +240,18 @@ function createFeatureRecomputeJobData( }; } +function createBaselineComputationJobData( + overrides: Partial = {}, +): BaselineComputationJobData { + return { + platformRoute: 'kr', + queueId: 420, + cohort: 'MASTER_PLUS', + patch: 'ALL', + ...overrides, + }; +} + function suppressLoggerError() { return jest .spyOn(Logger.prototype, 'error') @@ -243,6 +260,7 @@ function suppressLoggerError() { interface PipelineHarnessOptions { accountError?: Error; + computeMetricBaselines?: jest.Mock; existingMatchRaw?: Record | null; existingTimeline?: Record; findOneAccountResult?: Account | null; @@ -341,6 +359,15 @@ function createPipelineHarness(options: PipelineHarnessOptions = {}) { const getMatchIds = jest .fn, [string, Record]>() .mockResolvedValue(options.matchIds ?? ['KR_1']); + const computeMetricBaselines = + options.computeMetricBaselines ?? + jest.fn().mockResolvedValue({ + baselinesWritten: 3, + cohort: 'MASTER_PLUS', + computedAt: new Date('2026-07-03T12:00:00.000Z'), + patch: 'ALL', + samplesRead: 30, + }); const riotApiClient = { getAccountByRiotId, getSummonerByPuuid: jest.fn().mockResolvedValue({ @@ -357,6 +384,7 @@ function createPipelineHarness(options: PipelineHarnessOptions = {}) { return { findOneAccount, findOneRiotMatch, + computeMetricBaselines, getMatchIds, getMatch, getMatchTimeline, @@ -367,6 +395,9 @@ function createPipelineHarness(options: PipelineHarnessOptions = {}) { new ProfileBuilderService(), new TimelineDerivedService(), new TimelineMetricService(), + { + computeMetricBaselines, + } as unknown as MetricBaselineService, ), updateAnalysisJob, updatePlayerMatchFeature, @@ -630,6 +661,42 @@ describe('AnalysisPipelineService', () => { expect(updatePlayerProfile).not.toHaveBeenCalled(); }); + it('computes metric baselines and completes the baseline job', async () => { + const { computeMetricBaselines, service, updateAnalysisJob } = + createPipelineHarness(); + + await service.processBaselineComputationJob( + createBaselineComputationJobData(), + 'baseline-job-1', + ); + + expect(computeMetricBaselines).toHaveBeenCalledWith({ + cohort: 'MASTER_PLUS', + patch: 'ALL', + }); + const processingUpdate = updateAnalysisJob.mock.calls.find( + ([, update]) => + asRecord(asRecord(update).$set).jobType === + BASELINE_COMPUTATION_JOB_NAME && + asRecord(asRecord(update).$set).status === 'processing', + ); + expect(processingUpdate).toBeDefined(); + const completedUpdate = updateAnalysisJob.mock.calls.find( + ([, update]) => + asRecord(asRecord(update).$set).jobType === + BASELINE_COMPUTATION_JOB_NAME && + asRecord(asRecord(update).$set).status === 'completed', + ); + expect(completedUpdate).toBeDefined(); + expect(asRecord(asRecord(completedUpdate?.[1]).$set)).toMatchObject({ + progress: { + fetchedMatches: 30, + totalMatches: 3, + }, + stage: 'completed', + }); + }); + it('completes without building a profile when no ranked matches are returned', async () => { const { service, updateAnalysisJob, updatePlayerProfile } = createPipelineHarness({ diff --git a/apps/api/src/modules/analysis/analysis-pipeline.service.ts b/apps/api/src/modules/analysis/analysis-pipeline.service.ts index c43d444..f3893b4 100644 --- a/apps/api/src/modules/analysis/analysis-pipeline.service.ts +++ b/apps/api/src/modules/analysis/analysis-pipeline.service.ts @@ -1,4 +1,4 @@ -import { Injectable, Logger } from '@nestjs/common'; +import { Injectable, Logger, Optional } from '@nestjs/common'; import { FEATURE_SCHEMA_VERSION } from '@persona-lenz/shared'; import { ConnectionService } from '../global/database/connection.service'; import type { @@ -15,6 +15,7 @@ import { } from '../riot/riot-api.client'; import { FEATURE_RECOMPUTE_JOB_NAME, + BASELINE_COMPUTATION_JOB_NAME, MAX_ANALYSIS_MATCH_COUNT, normalizeFeatureRecomputeBatchSize, normalizeRequestedMatchCount, @@ -22,6 +23,7 @@ import { USER_ANALYSIS_JOB_NAME, } from './analysis.constants'; import type { + BaselineComputationJobData, ExtractedPlayerMatchFeature, FeatureRecomputeJobData, SeedAccountPipelineData, @@ -29,6 +31,7 @@ import type { UserAnalysisJobData, } from './analysis.types'; import { FeatureExtractorService } from './feature-extractor.service'; +import { MetricBaselineService } from './metric-baseline.service'; import { ProfileBuilderService } from './profile-builder.service'; import { TimelineDerivedService } from './timeline-derived.service'; import { TimelineMetricService } from './timeline-metric.service'; @@ -98,6 +101,8 @@ export class AnalysisPipelineService { private readonly profileBuilderService: ProfileBuilderService, private readonly timelineDerivedService: TimelineDerivedService, private readonly timelineMetricService: TimelineMetricService, + @Optional() + private readonly metricBaselineService?: MetricBaselineService, ) {} public async processUserAnalysisJob( @@ -277,6 +282,68 @@ export class AnalysisPipelineService { } } + public async processBaselineComputationJob( + data: BaselineComputationJobData, + jobId: string, + options: { isFinalAttempt?: boolean } = {}, + ): Promise { + const normalizedData = { + ...data, + cohort: data.cohort ?? 'MASTER_PLUS', + patch: data.patch?.trim() || 'ALL', + }; + + try { + await this.updateJob( + jobId, + { + status: 'processing', + stage: 'compute-baselines', + progress: { + fetchedMatches: 0, + totalMatches: 0, + }, + }, + BASELINE_COMPUTATION_JOB_NAME, + ); + + if (!this.metricBaselineService) { + throw new Error('Metric baseline service is not available.'); + } + const result = await this.metricBaselineService.computeMetricBaselines({ + cohort: normalizedData.cohort, + patch: normalizedData.patch, + }); + + await this.updateJob( + jobId, + { + status: 'completed', + stage: 'completed', + progress: { + fetchedMatches: result.samplesRead, + totalMatches: result.baselinesWritten, + }, + completedAt: new Date(), + error: undefined, + }, + BASELINE_COMPUTATION_JOB_NAME, + ); + } catch (error) { + if (options.isFinalAttempt === true) { + await this.updateJob( + jobId, + { + status: 'failed', + error: this.publicBaselineComputationErrorMessage(), + }, + BASELINE_COMPUTATION_JOB_NAME, + ); + } + throw error; + } + } + public async processSeedAccountPipeline( data: SeedAccountPipelineData, jobId: string, @@ -972,6 +1039,10 @@ export class AnalysisPipelineService { return 'Analysis failed during processing.'; } + private publicBaselineComputationErrorMessage(): string { + return 'Baseline computation failed during processing.'; + } + private logFinalFailure( data: UserAnalysisJobData, jobId: string, 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 1fdc2fa..a8e8a6e 100644 --- a/apps/api/src/modules/analysis/analysis-queue.service.spec.ts +++ b/apps/api/src/modules/analysis/analysis-queue.service.spec.ts @@ -1,10 +1,12 @@ import type { AnalysisJob } from '../global/database/schemas'; import type { ConnectionService } from '../global/database/connection.service'; import type { + BaselineComputationJobData, SeedCollectionJobData, UserAnalysisJobData, } from './analysis.types'; import { + BASELINE_COMPUTATION_JOB_NAME, DEFAULT_SEED_COLLECTION_MATCH_COUNT, FEATURE_RECOMPUTE_JOB_NAME, SEED_COLLECTION_JOB_NAME, @@ -57,6 +59,18 @@ function createSeedCollectionJobData( }; } +function createBaselineComputationJobData( + overrides: Partial = {}, +): BaselineComputationJobData { + return { + platformRoute: 'kr', + queueId: 420, + cohort: 'MASTER_PLUS', + patch: 'ALL', + ...overrides, + }; +} + describe('AnalysisQueueService', () => { it('creates an analysis job document and enqueues a BullMQ job', async () => { const add = jest.fn().mockResolvedValue({ id: 'job-from-bull' }); @@ -207,6 +221,53 @@ describe('AnalysisQueueService', () => { expect(analysisAdd).not.toHaveBeenCalled(); }); + it('creates a baseline computation job document and enqueues an analysis queue job', async () => { + const add = jest.fn().mockResolvedValue({ id: 'job-from-bull' }); + const seedAdd = jest.fn(); + 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, + { add: seedAdd } as never, + connectionService, + () => 'baseline-job-1', + ); + + const result = await service.enqueueBaselineComputation( + createBaselineComputationJobData(), + ); + + expect(result).toEqual({ jobId: 'baseline-job-1', status: 'queued' }); + expect(create).toHaveBeenCalledWith( + expect.objectContaining({ + jobId: 'baseline-job-1', + jobType: BASELINE_COMPUTATION_JOB_NAME, + platformRoute: 'kr', + queueId: 420, + requestedMatchCount: 0, + status: 'queued', + }), + ); + expect(add).toHaveBeenCalledWith( + BASELINE_COMPUTATION_JOB_NAME, + createBaselineComputationJobData(), + expect.objectContaining({ + attempts: 1, + jobId: 'baseline-job-1', + }), + ); + expect(seedAdd).not.toHaveBeenCalled(); + }); + it('returns an existing active job instead of enqueueing a duplicate', async () => { const add = jest.fn(); const findOneChain = createFindOneChain({ diff --git a/apps/api/src/modules/analysis/analysis-queue.service.ts b/apps/api/src/modules/analysis/analysis-queue.service.ts index 4bbe02c..faeee11 100644 --- a/apps/api/src/modules/analysis/analysis-queue.service.ts +++ b/apps/api/src/modules/analysis/analysis-queue.service.ts @@ -9,6 +9,7 @@ import { ANALYSIS_JOB_ID_FACTORY, ACTIVE_ANALYSIS_JOB_STATUSES, ANALYSIS_QUEUE_NAME, + BASELINE_COMPUTATION_JOB_NAME, DEFAULT_SEED_COLLECTION_MATCH_COUNT, FEATURE_RECOMPUTE_JOB_NAME, normalizeFeatureRecomputeBatchSize, @@ -18,15 +19,19 @@ import { USER_ANALYSIS_JOB_NAME, } from './analysis.constants'; import type { + BaselineComputationJobData, FeatureRecomputeJobData, SeedCollectionJobData, UserAnalysisJobData, } from './analysis.types'; type JobIdFactory = () => string; -type AnalysisQueueJobData = UserAnalysisJobData | FeatureRecomputeJobData; +type AnalysisQueueJobData = + UserAnalysisJobData | FeatureRecomputeJobData | BaselineComputationJobData; type AnalysisQueueJobName = - typeof USER_ANALYSIS_JOB_NAME | typeof FEATURE_RECOMPUTE_JOB_NAME; + | typeof USER_ANALYSIS_JOB_NAME + | typeof FEATURE_RECOMPUTE_JOB_NAME + | typeof BASELINE_COMPUTATION_JOB_NAME; type SeedCollectionQueueJobName = typeof SEED_COLLECTION_JOB_NAME; type ActiveAnalysisJob = Pick & { status: Extract; @@ -179,6 +184,59 @@ export class AnalysisQueueService { }; } + public async enqueueBaselineComputation( + data: BaselineComputationJobData, + ): Promise { + const normalizedData = this.normalizeBaselineComputationData(data); + const analysisJobModel = + await this.connectionService.getModel('analysisJob'); + const jobId = this.jobIdFactory(); + + await analysisJobModel.create({ + jobId, + jobType: BASELINE_COMPUTATION_JOB_NAME, + platformRoute: normalizedData.platformRoute, + queueId: normalizedData.queueId, + requestedMatchCount: 0, + status: 'queued', + stage: 'queued', + progress: { + fetchedMatches: 0, + totalMatches: 0, + }, + }); + + try { + await this.analysisQueue.add( + BASELINE_COMPUTATION_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( @@ -294,6 +352,18 @@ export class AnalysisQueueService { }; } + private normalizeBaselineComputationData( + data: BaselineComputationJobData, + ): BaselineComputationJobData { + const patch = data.patch?.trim(); + return { + platformRoute: data.platformRoute, + queueId: data.queueId, + cohort: data.cohort ?? 'MASTER_PLUS', + patch: patch && patch.length > 0 ? patch : 'ALL', + }; + } + private normalizeSeedSourceLimits( sourceLimits: NonNullable, ): NonNullable { diff --git a/apps/api/src/modules/analysis/analysis.constants.ts b/apps/api/src/modules/analysis/analysis.constants.ts index b8123bf..c90d3ea 100644 --- a/apps/api/src/modules/analysis/analysis.constants.ts +++ b/apps/api/src/modules/analysis/analysis.constants.ts @@ -3,6 +3,7 @@ export const SEED_COLLECTION_QUEUE_NAME = 'seed-collection'; export const USER_ANALYSIS_JOB_NAME = 'user-analysis'; export const FEATURE_RECOMPUTE_JOB_NAME = 'feature-recompute'; export const SEED_COLLECTION_JOB_NAME = 'seed-collection'; +export const BASELINE_COMPUTATION_JOB_NAME = 'baseline-computation'; export const ANALYSIS_JOB_ID_FACTORY = Symbol('ANALYSIS_JOB_ID_FACTORY'); export const DEFAULT_ANALYSIS_MATCH_COUNT = 20; diff --git a/apps/api/src/modules/analysis/analysis.processor.spec.ts b/apps/api/src/modules/analysis/analysis.processor.spec.ts index 12afa06..2ea7237 100644 --- a/apps/api/src/modules/analysis/analysis.processor.spec.ts +++ b/apps/api/src/modules/analysis/analysis.processor.spec.ts @@ -1,11 +1,13 @@ import type { Job } from 'bullmq'; import { + BASELINE_COMPUTATION_JOB_NAME, DEFAULT_FEATURE_RECOMPUTE_BATCH_SIZE, FEATURE_RECOMPUTE_JOB_NAME, MAX_FEATURE_RECOMPUTE_BATCH_SIZE, USER_ANALYSIS_JOB_NAME, } from './analysis.constants'; import type { + BaselineComputationJobData, FeatureRecomputeJobData, UserAnalysisJobData, } from './analysis.types'; @@ -38,6 +40,18 @@ function createFeatureRecomputeJobData( }; } +function createBaselineComputationJobData( + overrides: Partial = {}, +): BaselineComputationJobData { + return { + platformRoute: 'kr', + queueId: 420, + cohort: 'MASTER_PLUS', + patch: 'ALL', + ...overrides, + }; +} + describe('AnalysisProcessor', () => { it('delegates BullMQ jobs to the analysis pipeline', async () => { const processUserAnalysisJob = jest @@ -91,6 +105,32 @@ describe('AnalysisProcessor', () => { ); }); + it('delegates baseline computation jobs to the analysis pipeline', async () => { + const processBaselineComputationJob = jest + .fn< + Promise, + [BaselineComputationJobData, string, { isFinalAttempt?: boolean }] + >() + .mockResolvedValue(undefined); + const processor = new AnalysisProcessor({ + processBaselineComputationJob, + } as unknown as AnalysisPipelineService); + + await processor.process({ + attemptsMade: 0, + id: 'baseline-job-1', + name: BASELINE_COMPUTATION_JOB_NAME, + opts: { attempts: 1 }, + data: createBaselineComputationJobData(), + } as Job); + + expect(processBaselineComputationJob).toHaveBeenCalledWith( + createBaselineComputationJobData(), + 'baseline-job-1', + { isFinalAttempt: true }, + ); + }); + it('normalizes feature recompute batch size from valid queue payloads', async () => { const processFeatureRecomputeJob = jest.fn().mockResolvedValue(undefined); const processor = new AnalysisProcessor({ @@ -198,6 +238,46 @@ describe('AnalysisProcessor', () => { }, ); + it.each([ + { + data: null, + expectedError: 'Baseline computation job data must be an object.', + }, + { + data: { + ...createBaselineComputationJobData(), + cohort: 'INVALID', + }, + expectedError: 'Baseline computation job cohort is unsupported.', + }, + { + data: { + ...createBaselineComputationJobData(), + patch: ' ', + }, + expectedError: 'Analysis job patch is out of range.', + }, + ])( + 'rejects malformed baseline computation payloads', + async ({ data, expectedError }) => { + const processBaselineComputationJob = jest.fn(); + const processor = new AnalysisProcessor({ + processBaselineComputationJob, + } as unknown as AnalysisPipelineService); + + await expect( + processor.process({ + attemptsMade: 0, + id: 'baseline-job-1', + name: BASELINE_COMPUTATION_JOB_NAME, + opts: { attempts: 1 }, + data, + } as Job), + ).rejects.toThrow(expectedError); + expect(processBaselineComputationJob).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 8ff48b9..ccac34d 100644 --- a/apps/api/src/modules/analysis/analysis.processor.ts +++ b/apps/api/src/modules/analysis/analysis.processor.ts @@ -1,7 +1,9 @@ import { Processor, WorkerHost } from '@nestjs/bullmq'; import type { Job } from 'bullmq'; +import { BASELINE_COHORTS } from '../global/database/schemas'; import { ANALYSIS_QUEUE_NAME, + BASELINE_COMPUTATION_JOB_NAME, FEATURE_RECOMPUTE_JOB_NAME, normalizeFeatureRecomputeBatchSize, normalizeRequestedMatchCount, @@ -9,6 +11,7 @@ import { } from './analysis.constants'; import { AnalysisPipelineService } from './analysis-pipeline.service'; import type { + BaselineComputationJobData, FeatureRecomputeJobData, UserAnalysisJobData, } from './analysis.types'; @@ -52,6 +55,18 @@ export class AnalysisProcessor extends WorkerHost { return; } + if (job.name === BASELINE_COMPUTATION_JOB_NAME) { + const data = this.parseBaselineComputationJobData(job.data); + await this.analysisPipelineService.processBaselineComputationJob( + data, + job.id, + { + isFinalAttempt: this.isFinalAttempt(job), + }, + ); + return; + } + throw new Error(`Unsupported analysis job name "${job.name}".`); } @@ -110,6 +125,30 @@ export class AnalysisProcessor extends WorkerHost { }; } + private parseBaselineComputationJobData( + value: unknown, + ): BaselineComputationJobData { + if (typeof value !== 'object' || value === null || Array.isArray(value)) { + throw new Error('Baseline computation job data must be an object.'); + } + + const record = value as Record; + const platformRoute = this.parsePlatformRoute(record.platformRoute); + const queueId = this.parseQueueId(record.queueId); + const cohort = this.parseBaselineCohort(record.cohort); + const patch = + record.patch === undefined + ? 'ALL' + : this.parseBoundedString(record.patch, 'patch', 32); + + return { + platformRoute, + queueId, + cohort, + patch, + }; + } + private parseBoundedString( value: unknown, fieldName: string, @@ -159,6 +198,23 @@ export class AnalysisProcessor extends WorkerHost { return normalizeRequestedMatchCount(value); } + private parseBaselineCohort( + value: unknown, + ): BaselineComputationJobData['cohort'] { + if (value === undefined) { + return 'MASTER_PLUS'; + } + if ( + typeof value !== 'string' || + !BASELINE_COHORTS.includes( + value as NonNullable, + ) + ) { + throw new Error('Baseline computation job cohort is unsupported.'); + } + return value as NonNullable; + } + private parseFeatureRecomputeBatchSize(value: unknown): number { if (typeof value !== 'number' || !Number.isFinite(value)) { throw new Error('Feature recompute job batchSize must be finite.'); diff --git a/apps/api/src/modules/analysis/analysis.types.ts b/apps/api/src/modules/analysis/analysis.types.ts index 97cf5bd..d255edd 100644 --- a/apps/api/src/modules/analysis/analysis.types.ts +++ b/apps/api/src/modules/analysis/analysis.types.ts @@ -1,5 +1,6 @@ import type { Role } from '@persona-lenz/shared'; import type { + BaselineCohort, LaneOpponentRef, SeedSource, TeamPositionOrUnknown, @@ -28,6 +29,13 @@ export interface SeedCollectionJobData { sourceLimits?: Partial>; } +export interface BaselineComputationJobData { + platformRoute: RiotPlatformRoute; + queueId: number; + cohort?: BaselineCohort; + patch?: string; +} + export interface SeedAccountPipelineData { puuid: string; platformRoute: RiotPlatformRoute;